diff --git a/.github/social-preview.html b/.github/social-preview.html new file mode 100644 index 00000000..98910229 --- /dev/null +++ b/.github/social-preview.html @@ -0,0 +1,147 @@ + + + + + + + + + + + +
+ +
+
+
+
+
+ +
GOLDENEYE 007
PC PORT
+ +
+ Mission: Native PC port of GoldenEye, compiled from the N64 decomp project +
+ +
REPORT:
+ +
+
Status: PHASE 2 OF 4 — RENDERING
+
+ Statistics:21 / 21 solo missions load & render + ~230 game-code units, compiled unmodified + ~17k lines C/C++  ·  ~6k Python (port layer + tools) + 162 bugs root-caused  ·  built in ~2 weeks, part-time +
+
+ +
github.com/jkdansereau/goldeneye-pc-port
+ +
CLASSIFIED
+
+ +
+
NEXT
+
PREVIOUS
+
+
+ + diff --git a/.github/social-preview.md b/.github/social-preview.md new file mode 100644 index 00000000..a895a16a --- /dev/null +++ b/.github/social-preview.md @@ -0,0 +1,62 @@ +# Social preview card + +`social-preview.png` is the image GitHub shows when the repo is linked on +Slack, Discord, Reddit, X, etc. (Repo **Settings → General → Social preview**.) +It is generated from `social-preview.html` — the two live side by side so the +card stays editable. + +- **Size:** 1280×640 (GitHub's recommended ratio). +- **Fonts:** Tinos (a Times metric-compatible serif) for the title, Arimo + (Arial metric-compatible) for the body — both from Google Fonts. +- **Everything else is pure CSS** — no raster assets, no external images. + +## Design brief + +Recreate GoldenEye 007's in-game **mission-briefing / objectives screen** and +repurpose it as a project status card: + +- a mottled grey-green **concrete/stone** surround (three layered SVG + `feTurbulence` fractal-noise fills — broad staining, mid mottle, fine tooth — + plus a soft edge vignette); +- a cream **parchment card** with a faint wavy watermark and a drop shadow; +- the game's right-edge **filing tabs** (`NEXT` / `PREVIOUS`) and the small red + **crosshair/reticle**; +- a faint circular **emblem** watermark, upper right; +- a translucent diagonal **`CLASSIFIED`** stamp, kept low-opacity so the status + text stays readable; +- serif title, `007` and `PC PORT` in the GoldenEye menu **red** (`#a01818`); +- body laid out as the briefing's `Mission:` / `REPORT:` / `Status:` / + `Statistics:` fields. + +Keep the copy short. Update the stat lines from the README's "By the numbers" +table when the numbers move; update `Status:` when the phase changes. + +## Regenerate the PNG + +Any Chromium (Chrome, Edge, Brave, `chromium`) can render it headless: + +```sh +cd .github +chrome --headless --disable-gpu --hide-scrollbars \ + --force-device-scale-factor=1 --virtual-time-budget=6000 \ + --window-size=1280,640 \ + --screenshot="$(pwd)/social-preview.png" \ + "$(pwd)/social-preview.html" +``` + +`--virtual-time-budget=6000` gives the web fonts time to load. +`--force-device-scale-factor=1` keeps the output exactly 1280×640. + +If your browser blocks web-font loads over `file://`, serve the folder first: + +```sh +cd .github && python -m http.server 8000 & +chrome --headless --disable-gpu --hide-scrollbars \ + --force-device-scale-factor=1 --virtual-time-budget=6000 \ + --window-size=1280,640 \ + --screenshot="$(pwd)/social-preview.png" \ + "http://127.0.0.1:8000/social-preview.html" +``` + +Then re-upload `social-preview.png` under Settings → General → Social preview +(GitHub does not pick it up from the repo automatically). diff --git a/.github/social-preview.png b/.github/social-preview.png new file mode 100644 index 00000000..7941d3d8 Binary files /dev/null and b/.github/social-preview.png differ diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 00000000..d52c2a6f --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,35 @@ +cff-version: 1.2.0 +title: "GoldenEye 007 PC Port — a two-agent AI development case study" +message: >- + If you reference this project or its write-up on AI-agent collaboration, + please cite it using the metadata below. +type: software +authors: + - family-names: Dansereau + given-names: James +repository-code: "https://github.com/jkdansereau/goldeneye-pc-port" +abstract: >- + A work-in-progress native PC port of GoldenEye 007 (Rare, 1997, Nintendo 64), + built on the GoldenEye 007 decompilation, and a research project on AI-agent + collaboration in a large, unfamiliar, low-level codebase: how two coding + agents (a local open-weight model and a hosted frontier model), directed by + one person part-time, were driven through ~230 translation units of unmodified + big-endian MIPS game code and made to run on a 64-bit desktop. Covers software + RSP emulation, N64-to-x86-64 ABI reconciliation, and a shared-artifact handoff + workflow between agents. +keywords: + - goldeneye-007 + - nintendo-64 + - n64 + - decompilation + - pc-port + - game-porting + - reverse-engineering + - agentic-development + - ai-agents + - llm + - coding-agents + - software-renderer + - mips + - opengl +license: MIT diff --git a/README.md b/README.md index e10d0975..95bd0068 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,26 @@ -# GoldenEye 007 — PC port +# GoldenEye 007 PC Port +[![CI](https://github.com/jkdansereau/goldeneye-pc-port/actions/workflows/ci.yml/badge.svg)](https://github.com/jkdansereau/goldeneye-pc-port/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-Phase_2_of_4_(rendering)-orange) ![tested on](https://img.shields.io/badge/tested_on-Windows_x86--64-blue) ![license](https://img.shields.io/badge/license-MIT-green) ![built with](https://img.shields.io/badge/built_with-coding_agents-8A2BE2) -A work-in-progress native port of **GoldenEye 007** (Rare, 1997) to modern -desktop platforms, built on top of the -[GoldenEye decompilation](https://github.com/n64decomp/007). +**A work-in-progress native PC port of _GoldenEye 007_ (Rare, 1997, Nintendo 64), +built on the [GoldenEye 007 decompilation](https://github.com/n64decomp/007).** +It is first and foremost a **research project on AI-agent collaboration in a +large, unfamiliar, low-level codebase** — how far two coding agents (a local +open-weight model and Claude), driven by one person part-time, can be pushed +through ~230 translation units of unmodified big-endian MIPS game code and made +to run on a 64-bit desktop. **Current status: Phase 2 of 4 (rendering).** The +port boots, renders the full intro and front end, and loads all 21 solo +missions; there is no audio yet and it is not a playable game. See +[Status](#status) and [Background](#background). -It follows the architecture of the +Technically, it follows the architecture of the [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark) — the same Rare "Indy" engine family, one hardware generation apart. The unmodified game C -sources are compiled for the host; the N64's Reality Signal Processor is +sources are compiled for the host; the N64's Reality Signal Processor (RSP) is emulated in software; every other hardware surface (video, audio, input, timers, save storage) is shimmed in a dedicated `port/` layer. @@ -33,6 +41,7 @@ timers, save storage) is shimmed in a dedicated `port/` layer. ## Contents - [Background](#background) +- [How this differs from the other GoldenEye PC projects](#how-this-differs-from-the-other-goldeneye-pc-projects) - [Status](#status) - [Requirements](#requirements) - [Building](#building) · [Windows (MSYS2)](#windows-msys2) · [Linux](#linux) @@ -46,10 +55,11 @@ timers, save storage) is shimmed in a dedicated `port/` layer. ## Background -This port is primarily a **research project on agentic software development** — -how far coding agents can be driven, by one person, through a large and -unfamiliar low-level codebase (~230 translation units of unmodified -big-endian MIPS game code, made to run on a 64-bit desktop). +Beyond the port itself, this is primarily a **research project on agentic +software development** — specifically, on AI-agent collaboration in a large, +unfamiliar, low-level codebase: how far coding agents can be driven, by one +person working part-time, through ~230 translation units of unmodified +big-endian MIPS game code, made to run on a 64-bit desktop. It used two agents: @@ -106,7 +116,31 @@ asset converters — then both agents ran the debugging phase together: Full write-up, timeline chart, and an honest "what worked / what didn't": [`docs/dev/agentic-development.md`](docs/dev/agentic-development.md). The -workflow itself: [`docs/dev-process.md`](docs/dev-process.md). +workflow itself: [`docs/dev-process.md`](docs/dev-process.md). To cite this +project or its findings, use [`CITATION.cff`](CITATION.cff) (GitHub's "Cite +this repository" menu). + +## How this differs from the other GoldenEye PC projects + +This is a **native port of the original 1997 Nintendo 64 game, built from its +actual reconstructed source code** — the same lineage as the Perfect Dark PC +port. The other well-known "GoldenEye on PC" projects are something different: +they machine-translate the shipped binary of the *unreleased Xbox 360 XBLA +remaster* — a different game, a different codebase, no shared code with this. + +| | This project | [GoldenEye-Recomp](https://github.com/SunJaycy/GoldenEye-Recomp) / [Steam Deck build](https://github.com/couchk1ng/GoldenEye-Recomp-SteamDeck) | +|---|---|---| +| **What it ports** | The original **Nintendo 64** game (1997) | The **Xbox 360 XBLA** HD remaster (built ~2007, never released) | +| **How** | **Decompilation-based source port** — human-reconstructed C, compiled for the host; game logic runs as written | **Static binary recompilation** — the shipped machine code is auto-translated to C; no source-level understanding | +| **Lineage** | [GoldenEye 007 decompilation](https://github.com/n64decomp/007) + [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark) engine family | Xbox 360 "…Recompiled" static-recompilation family | +| **Renderer** | Software RSP → OpenGL | Hardware (Vulkan) | +| **Status** | WIP, Phase 2 — renders and loads all 21 levels; no audio; not playable end to end | Playable full game, higher frame rates, online multiplayer | +| **Why it exists** | A [case study in AI-agent collaboration](#background) on a hard low-level codebase; the port is the target, not a product | A polished, playable PC release of the remaster | + +**If you just want to play GoldenEye on PC today, use one of the recompilation +projects — they are finished and this is not.** What is interesting here is the +other half: getting the *original* game running from source, and how much of +that work was driven by AI agents. ## Status @@ -275,11 +309,15 @@ docs/ see below ## Documentation +Key docs are also published as a site: +****. + | Doc | What's in it | |---|---| | [`docs/building.md`](docs/building.md) | Full build + asset-extraction guide. | | [`docs/internals.md`](docs/internals.md) | Architecture, the RSP-emulation approach, GE-vs-PD engine differences, the phased plan. | | [`docs/porting-notes.md`](docs/porting-notes.md) | The recurring N64→PC bug classes hit during the port, with fixes. | +| [`docs/dev/game-behavior-reference.md`](docs/dev/game-behavior-reference.md) | How the retail N64 game is meant to behave — combat/AI model, difficulty scaling, per-level objectives, timers, weapon data, original-game quirks. Playtest reference. | | [`docs/dev/agentic-development.md`](docs/dev/agentic-development.md) | The research angle: the two-agent setup, timeline, handoff workflow, and an assessment of what did and didn't work. | | [`docs/dev-process.md`](docs/dev-process.md) | The investigation workflow in detail — budgets, file partitioning, the finding-log discipline. | | [`docs/dev/`](docs/dev/) | The raw engineering record: the full finding log, per-level status, graphics backlog, playtest matrices. | diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..bf3cd7f7 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,16 @@ +# GitHub Pages config. Site is served from the /docs folder on the default +# branch (Settings -> Pages -> Deploy from a branch -> main / docs). +title: GoldenEye 007 PC Port +description: >- + A native PC port of the original Nintendo 64 GoldenEye 007, built from its + decompiled source, and a case study in AI-agent collaboration on a large + low-level codebase. +theme: jekyll-theme-cayman +show_downloads: false + +# jekyll-relative-links (on by default for Pages) rewrites the .md links in +# these docs to .html so cross-links work on the published site. + +# Rolling local working files - not useful as published pages. +exclude: + - HANDOFF.md diff --git a/docs/dev/agentic-development.md b/docs/dev/agentic-development.md index 5c61e2a4..34ecbe19 100644 --- a/docs/dev/agentic-development.md +++ b/docs/dev/agentic-development.md @@ -1,10 +1,12 @@ -# Agentic development: a two-agent experiment +# Agentic development: two AI coding agents porting GoldenEye 007 -*A GoldenEye 007 N64→desktop port, taken from "builds a ROM" to "playable front -end" in about two weeks — driven mostly by two coding agents, a local -open-weight model and a hosted frontier model, handing work back and forth -through shared written notes under one person's direction. This is the goal, -the method, the timeline, and an honest read on what did and didn't work.* +*A case study in AI-agent collaboration on a large, low-level codebase. A +GoldenEye 007 Nintendo 64 → desktop port, taken from "builds a ROM" to +"playable front end" in about two weeks — driven mostly by two coding agents (a +local open-weight model, Qwen 3, on a single RTX 5090, and a hosted frontier +model, Claude / Claude Code), handing work back and forth through shared +written notes under one person's part-time direction. This is the goal, the +method, the timeline, and an honest read on what did and didn't work.* ## Contents diff --git a/docs/dev/game-behavior-reference.md b/docs/dev/game-behavior-reference.md new file mode 100644 index 00000000..a552177b --- /dev/null +++ b/docs/dev/game-behavior-reference.md @@ -0,0 +1,358 @@ +# GoldenEye 007 — game-behaviour reference + +Community-documented account of how the retail N64 game is *supposed* to +behave: the combat/AI/stealth model, difficulty scaling, per-level objective +sets, timers, weapon data, and the original game's known quirks and glitches. + +**Status of this document.** This is secondary source material, not ground +truth. The decompiled game code in `src/` is authoritative for behaviour (see +`AGENTS.md`). Use this doc to know *what correct looks like* when playtesting +the port — which objectives a level must expose, what a timer value should be, +whether a weird behaviour you just saw is an original-game quirk or a port +regression. + +**Sources** (subjective commentary stripped; mechanical/factual data only): + +- GameFAQs walkthrough by **Brett "Nemesis" Franklin**, v1.01, July 2001 — + overview, mechanics, objective lists, weapon/gadget data, glitches. +- **marshmallow**, *Extensive 00 Agent Walkthrough* v3.0 (GameFAQs) — the + 00 Agent difficulty-delta list and the AI-exploit notes in §3. + +Distilled from `goldeneye_007_reference.md` (the full raw walkthrough dump); +the walkthrough's per-stage tactical routes were dropped as not +behaviour-defining. + +--- + +## 1. Difficulty modes + +Three tiers. **00 Agent is a strict superset** of Agent and Secret Agent — +every objective required at a lower tier is also required at 00 Agent, so one +00 Agent run satisfies all three. + +| Mode | Rank | Layout | Objectives | +|---|---|---|---| +| Agent | starting rank | small/simple | fewest | +| Secret Agent | +1 | average | more | +| 00 Agent | highest | big/complex | maximum (superset) | + +### What 00 Agent changes mechanically + +Relative to the lower tiers: + +1. Guards are tougher — body-armoured guards can **survive a headshot** (a DD44 + headshot may not kill). +2. Better AI — enemies fire sooner, roll/dodge more often, and "hear" the + player from further. +3. Picked-up guns start with only **10 rounds**. +4. Body armour is nearly absent (a few fixed locations only). +5. More objectives per level. +6. Low player health — roughly **8× KF7 Soviet hits** or **~5× AR33 hits** is + lethal. +7. Higher enemy accuracy. +8. Explosions (crates, grenades, chairs) are near-instant-kill unless the + player clears the radius fast. +9. Security cameras acquire the player in **~3 s** (vs ~10 s on Agent). + +--- + +## 2. Combat, stealth & AI model + +### Damage + +- **Body-part damage system** — different hit locations do different damage; + head shots are the fastest kill and are the intended way to conserve ammo. +- **Auto-Aim** (option) — snaps to the nearest enemy under the crosshair when + firing; ~90% reliable at target selection. +- **Manual aim** (R / L-R) — zooms for precise body-part targeting. +- **Full-auto accuracy falls off** with sustained fire and with distance: + "pecking" 1–2 rounds is more accurate than spraying; spray only wins against + groups. + +### Alerting + +- A **loud** weapon fired within earshot of **2+ guards** triggers an area + alert (they converge on the player's position and can call reinforcements). + A lone guard may not call for help. +- **Silenced** weapons (PP7 Silenced, D5K Silenced, silenced pistols, knives) + never alert. +- **Security cameras**: if a camera acquires the player it raises an alert + that **spawns black-clad guards** armed with DD44s and KF7s. Shoot the + camera centre for a one-shot kill. +- **Retreating** breaks pursuit — most guards stop following after a set + distance, letting the player reload / heal / reposition. + +### AI line-of-sight & animation quirks (exploitable, i.e. defining behaviour) + +- A guard behind a **wall, low barrier or railing cannot shoot** the player, + even point-blank — it must path around the obstacle. **Exception:** a guard + behind a **crate** *can* shoot through/over it. +- Turrets / sentry guns **drop target beyond a set range**. +- Most guards play a **kneel animation before firing** (takes ~1–2 s). Circling + a kneeling guard makes it fire at the player's previous position. +- **Point-blank**: a guard the player is pressed against **cannot fire** until + it steps back. + +--- + +## 3. Player state + +| System | Behaviour | +|---|---| +| Health | restored by health packs; no regen. 00 Agent pool ≈ 8 KF7 hits (§1). | +| Body armour | separate absorbing layer; fixed pickup locations (e.g. by the Jungle drone guns, start of Antenna Cradle). Nearly absent on 00 Agent. | +| Explosive barrels/crates | shootable for area damage; can kill the player. In Water Caverns, detonating the barrels **before** using the radio destroys the radio and fails that objective. | + +--- + +## 4. Timers (exact values — verify against decomp) + +| Level | Trigger | Value | On expiry | +|---|---|---|---| +| Silo (M3) | level start | **8:30** | facility self-destructs; must reach the escape elevator | +| Bunker 2 (M5) | Natalya activates the main control panel | **~60 s** | alarm; must escort Natalya to the exit | +| Train (M6) | hostage scene, if Xenia is **not** killed | **4 s** | escape window before failure | + +--- + +## 5. Companion AI — Natalya + +- Present in Bunker 2, Jungle, Control Center, Water Caverns, Train + (Missions 5–7). +- Carries a **Cougar Magnum**; engages enemies autonomously. +- Must survive — her death fails objectives. +- Scripted roles: hacks the mainframe in Control Center (player defends both + staircases); freed from a cell and escorted out under the timer in Bunker 2; + hacks a terminal in Train while the player laser-cuts the grate bearings. + +--- + +## 6. Objective system + +Each sub-level exposes a fixed set of **primary objectives** shown at level +start; completing the final one ends the sub-level. Objective *count* scales +with difficulty (§1). Some are **conditional / fail-state** objectives — +"Minimize scientist casualties", "Minimize civilian casualties" — tracked by a +running kill count against that class. + +21 sub-levels across 9 missions: + +| M | Location | Sub-levels | +|---|---|---| +| 1 | Aarkangelsk | Dam → Facility → Runaway | +| 2 | Severnaya | Surface → Bunker | +| 3 | Kirghizstan | Silo | +| 4 | Monte Carlo | Frigate | +| 5 | Severnaya (return) | Surface 2 → Bunker 2 | +| 6 | St. Petersburg | Statue Park → Military Archives → Streets → Depot → Train | +| 7 | Cuba | Jungle → Control Center → Water Caverns → Antenna Cradle | +| 8 | Teotihuacán | Aztec Complex | +| 9 | el-Saghira | Egyptian Temple | + +### Per-level objective sets (00 Agent — the superset) + +**Dam** — neutralize all alarms · install covert modem · intercept data backup · +bungee jump from platform. +**Facility** — gain entry to lab · contact double agent (Dr. Doak) · rendezvous +with 006 · destroy all tanks in bottling room · minimize scientist casualties. +**Runaway** — find plane ignition key · destroy heavy gun emplacements · +destroy missile battery · escape in plane. +**Surface** — power down comms dish · obtain safe key · steal building plans · +enter base via ventilation tower. +**Bunker** — disrupt all surveillance equipment · copy Goldeneye Key and leave +original · get personnel to activate computer · download data · photograph main +video screen. +**Silo** — plant bombs in fuel rooms · photograph satellite · obtain telemetric +data · retrieve satellite circuitry · minimize scientist casualties. +**Frigate** — rescue hostages · disarm bridge bomb · disarm engine-room bomb · +plant tracking bug on helicopter. +**Surface 2** — disrupt all surveillance equipment · break comms link to bunker · +disable Spetznaz support aircraft · gain entry to bunker. +**Bunker 2** — compare staff/casualties lists · recover CCTV tape · disable all +security cameras · recover Goldeneye operations manual · escape with Natalya. +**Statue Park** — contact Valentin · confront and unmask Janus · locate +helicopter · rescue Natalya · find flight recorder. +**Military Archives** — escape interrogation room · find Natalya · recover +helicopter black box · escape with Natalya. +**Streets** — contact Valentin · pursue Ourumov and Natalya · minimize civilian +casualties. +**Depot** — destroy illegal arms cache · destroy computer network · obtain safe +key · recover helicopter blueprints · locate Trevelyan's train. +**Train** — destroy brake units · rescue Natalya · locate Janus secret base · +crack Boris' password · escape to safety. +**Jungle** — destroy drone guns · eliminate Xenia · blow up ammo dump · escort +Natalya to Janus base. +**Control Center** — protect Natalya · disable Goldeneye satellite · destroy +armored mainframes. +**Water Caverns** — destroy inlet pump controls · destroy outlet pump controls · +destroy master control console · use radio to contact Jack Wade · minimize +scientist casualties. +**Antenna Cradle** — destroy control console · settle score with Trevelyan. +**Aztec Complex** — reprogram shuttle guidance · launch shuttle. +**Egyptian Temple** — recover the Golden Gun · defeat Baron Samedi. + +### Key scripted mechanics per level + +- **Bunker / Surface 2** — cameras must be killed to avoid the black-clad + alert spawn. +- **Silo** — Ourumov is killable here (he normally flees; Invisibility stops + him); drops DD44 + briefcase. He still reappears later regardless. +- **Frigate** — hostages held at gunpoint; shoot the guard not the hostage. + Bomb Diffuser used on two terminal-mounted bombs. +- **Streets** — tank vehicle; running over a **civilian** fails the mission; + street land-mines apply damage-over-time to the tank. +- **Train** — kill Xenia + Ourumov simultaneously in the hostage scene; if + Xenia survives, the 4 s timer starts and extra guards spawn. +- **Jungle** — Xenia boss on the bridge: uses RCP-90 + Grenade Launcher, rolls + when hit, drops both weapons. +- **Control Center** — Boris pulls a gun ("I am Invincible!") and fades out + rather than being killed. +- **Water Caverns** — contact Jack Wade by radio **before** detonating the + barrel room; Code Cards A/B/C drop from guards in sequence. +- **Antenna Cradle** — Trevelyan final boss reappears alternately at the two + sheds/catwalks; player kills him at each appearance, final fight point-blank + in the shed under the cradle. +- **Aztec Complex** — first terminal starts the launch sequence + opens a + door; a second terminal must be destroyed to reveal a hidden hallway before + the launch finishes. +- **Egyptian Temple** — Golden Gun glass case lowers only after a fixed + tile-path is walked; Baron Samedi appears twice, uses Lasers, dies only to + the Golden Gun. + +--- + +## 7. Weapons — data table + +Clip / max-capacity / behaviour. (Balance and capacity numbers to cross-check +against the decomp's weapon tables.) + +| Weapon | Type | Clip | Max | Behaviour notes | +|---|---|---|---|---| +| PP7 | pistol | 7 | 800 | default sidearm | +| PP7 (Silenced) | pistol | 7 | 800 | no alert on fire | +| DD44 Dostovei | pistol | 8 | 812 | high power, Magnum-like recoil | +| Cougar Magnum | pistol | 6 | 200 | high per-shot damage; Natalya's sidearm | +| Gold PP7 / Golden Gun | pistol | 7 / 1 | 800 / 100 | one-shot kill anywhere; Golden Gun = 1 round/clip | +| Silver PP7 | pistol | 7 | 800 | cosmetic | +| Klobb | SMG | 20 | 812 | weakest automatic | +| KF7 Soviet | auto rifle | 30 | 400 | ubiquitous early-game weapon | +| AR-33 | auto rifle | 30 | 400 | stronger than KF7; zoom | +| D5K Deutsche | auto rifle | 32 | 800 | zoom | +| D5K (Silenced) | auto rifle | 32 | 800 | no alert; one level | +| Phantom | auto rifle | 50 | 800 | very loud; one level | +| RCP-90 | auto rifle | 80 | 800 | fastest fire rate in the game | +| ZMG (9mm) | heavy auto | 32 | 800 | dual-wieldable | +| Automatic Shotgun | auto shotgun | 5 | 200 | Statue Park only (SP) | +| Shotgun | pump shotgun | 5 | 200 | slower reload; via All Guns cheat | +| Sniper Rifle | bolt rifle | 8 | 400 | longest zoom; best stealth weapon | +| Grenade Launcher | launcher | 6 | 12 | arcing grenades | +| Rocket Launcher | launcher | 1 | 3 | large blast, can kill player | +| Grenades | thrown | 12 | 12 | — | +| Throwing Knives | ranged melee | 12 | 12 | low damage | +| Hunting Knives | melee | — | — | fast silent takedowns | +| Proximity Mines | placed | 10 | 10 | triggers on proximity | +| Remote Mines | placed | 10 | 10 | detonated by Remote Watch; no timeout | +| Timed Mines | placed | 10 | 10 | detonate ~8 s after placement | +| Taser | gadget | — | — | non-lethal stun | +| Moonraker (Military) Laser | energy | — | — | fires through walls/doors; kills Jaws | +| Tank Shells | vehicle | — | — | Runaway, Streets | + +Availability: weapons are level-scoped and do not carry between missions unless +noted. **All Guns** cheat unlocks everything. + +--- + +## 8. Gadgets + +| Gadget | Level(s) | Activation / effect | +|---|---|---| +| Covert Modem | Dam | toss onto a computer screen to install | +| Bomb Diffuser | Frigate | use on a terminal-mounted bomb | +| Camera | Bunker, Silo | photograph a target (video screen / satellite) | +| Key Analyzer | Bunker | copies a key and **destroys the original** | +| Data Thief | Bunker | download data from a terminal | +| Tracking Bug | Frigate | place on the Pirate helicopter | +| Watch Magnet | Bunker 2, Train | pull a key / metal object at range | +| Watch Laser | Train | cut metal (grate bearings) | +| Remote Mines + Remote Watch | Facility, Control Center, Water Caverns | place, then detonate at range | +| Door Decoder | Facility | from Dr. Doak; opens the locked bottling-room door | + +--- + +## 9. World-interaction objects + +| Object | Rule | +|---|---| +| Red alarm boxes | shoot to complete "neutralize all alarms"; a guard reaching one spawns reinforcements | +| Security cameras | destroy (centre = one-shot); acquisition raises the black-clad alert | +| Sentry guns | fixed turrets (Bunker 2 striped corridor, Depot); destroy to pass | +| Drone guns | remote turrets (Jungle, Control Center, Water Caverns, Aztec); some pairs must be destroyed together | +| Locks / grates | shootable (e.g. the 4-lock vent grate at the end of Surface) | +| Doors | B to open; some need keycard / key / code | +| Gate switches | red/green buttons control gates (Dam) | + +--- + +## 10. Vehicles + +| Vehicle | Level | Rules | +|---|---|---| +| Tank | Runaway, Streets | cannons + missiles (Runaway); may crush enemies, **must not crush civilians** (Streets); street mines = DoT | +| Plane | Runaway | final escape after the missile battery is destroyed | +| Train | Train | car-to-car traversal; a brake unit (red/yellow wires) in every car must be destroyed | + +--- + +## 11. Controls / input options (relevant to `port/src/input.c`) + +Default mapping (control style 1.1): **A** switch weapon/device · **B** +action / reload · **Z** fire / use gadget · **L/R** aim · **C-Up/Down** look · +**C-Left/Right** strafe · **Stick** move · **D-Pad** mirrors C. + +Four SP control styles (1.1–1.4) permute which of {aim, fire} is on Z vs A/L-R +and whether the stick moves or looks. Derived actions: **crouch** = Aim + +C-Down, **stand** = Aim + C-Up. + +Options that change feel: **Reverse Pitch** (invert vertical aim), +**Look Ahead** (camera leads movement), **Head Roll** (full 360° look), +**Auto-Aim** (snap to nearest on fire), **Aim Control** = Hold or Toggle. + +--- + +## 12. Original-game quirks & glitches + +These are **retail N64 behaviours**. If the port reproduces them it is +faithful; if you see one while testing, it is probably *not* a port bug. + +- **Guard AI freeze under Invisibility** — kill one guard in a group and the + rest aim at the player's last known position but can never re-acquire (player + is invisible); they hold the aim pose until the player moves or dies. +- **Ourumov / Jaws killable via Invisibility** — both normally can't be + engaged (Ourumov flees, Jaws is near-indestructible); with Invisibility the + AI can't see the player, so both become killable with any weapon. +- **Trevelyan respawn loop (Antenna Cradle, 00 Agent + Invisibility)** — + killing Trevelyan on the catwalk can respawn him alive at the far shed, + repeatable indefinitely. A pathing/AI bug, not intended. +- **Invulnerable 006 in Water Caverns** — with Invisibility, one of the + "guards" leaving the elevator is actually a static, invulnerable Trevelyan + model (his AI never detects the invisible player). An easter egg, not a + spawn error. +- **Post-dialogue allies become killable** — after an ally's scripted + conversation ends (e.g. Valentin in Statue Park) the player can kill them; + no mechanical penalty. +- **Ourumov's key opens the Silo launch doors** — the briefcase/key dropped by + Ourumov has no objective use, but "firing" the key (action button) near the + rocket opens the giant launch doors. Otherwise both items are inert. +- **Cut content left in levels**: the Dam has the unused geometry of a + cancelled boat mission out on the water; the Train's rear region past + Alec/Trevelyan leads nowhere; the Facility's starting vent has a second path + blocked purely cosmetically and shootable ceiling glass. + +--- + +## 13. Multiplayer (brief) + +Up to 4 local players. Deathmatch + variant modes. Level list = all SP levels +plus dedicated MP maps. Character/costume/face are swappable (the raw dump has +the full GameShark costume/character ID tables if ever needed for the MP +character system). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..5019d7ec --- /dev/null +++ b/docs/index.md @@ -0,0 +1,32 @@ +--- +title: GoldenEye 007 PC Port +description: A native PC port of the original Nintendo 64 GoldenEye 007, built from decompiled source — and a case study in AI-agent collaboration on a large low-level codebase. +--- + +# GoldenEye 007 PC Port + +A work-in-progress **native PC port of the original 1997 Nintendo 64 +_GoldenEye 007_**, compiled from the game's +[decompiled source](https://github.com/n64decomp/007) and running the N64's +graphics coprocessor in software. It follows the architecture of the +[Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark). + +It is also a **research project on AI-agent collaboration in a large, +unfamiliar, low-level codebase**: two coding agents — a local open-weight model +(Qwen 3) on a single RTX 5090, and Claude / Claude Code — driven by one person +part-time through ~230 translation units of unmodified big-endian MIPS game +code, handing work back and forth through shared written notes. + +**Status:** Phase 2 of 4 (rendering). Boots, renders the full intro and front +end, loads all 21 solo missions. No audio yet; not playable end to end. + +- **[Project repository and README](https://github.com/jkdansereau/goldeneye-pc-port)** — build instructions, requirements, status, how it compares to the Xbox 360 recompilation projects. + +## Documentation + +- **[The two-agent development case study](dev/agentic-development.md)** — goal, setup, timeline, the handoff workflow, and an honest assessment of what did and didn't work. +- **[Development process](dev-process.md)** — how work was scoped, partitioned, and budgeted across agents; the finding-log discipline. +- **[Internals](internals.md)** — architecture, the software RSP-emulation approach, GoldenEye-vs-Perfect-Dark engine differences, the phased plan. +- **[Porting notes](porting-notes.md)** — the recurring Nintendo 64 → PC bug classes hit during the port, with fixes. +- **[Game-behaviour reference](dev/game-behavior-reference.md)** — how the retail N64 game is meant to behave: combat/AI model, difficulty scaling, per-level objectives, timers, weapon data, and the original game's known quirks. +- **[Building](building.md)** — full build and asset-extraction guide.