James Dansereau
3c11e40c13
* fix(D223): directional mouse-wheel weapon cycling
Wheel-up keeps the existing 2-poll A pulse (weaponForwardOffset: fresh
A edge, Z released). Wheel-down now runs a 2-poll backward sequence:
A-only poll, then A+Z_TRIG -- the fresh-Z-edge-while-A-held combo that
weaponBackOffset requires (bondview2.c:5337-5340); ordering matters
because the edge is computed against the game's own previous poll.
moveData.triggerOn (bondview2.c:5419) requires A to be released, so
the synthesized Z edge can never fire a shot.
Roles are stable: the port forces CONTROLLER_CONFIG_HONEY
(bondview.c:1484), whose scheme gives invButtons=A_BUTTON /
shootButtons=Z_TRIG -- the same roles the pre-fix forward pulse
already relied on. While RMB aim is held the game flips controldef to
KISSY, under which neither direction cycles -- identical to the old
forward-only behavior in that state (pre-existing, not a regression).
Port-only; no src/ changes.
* docs(D223/D196): mark D223 FIXED (M-105); correct stale D196 status
D223 row now records the implemented fix and its known aim-mode
limitation. D196 was already fixed and merged (a17d5466, the
prescribed 1-line applyCursorVisibility() after reconcileGrab()) but
its status cell still led OPEN -- same stale-claim class the roadmap
flags; corrected. findings-index.csv regenerated.
* D223 follow-up: fix wheel-down backstep racing the real game tick
User playtest (M-105 cont.) found the backward-cycle combo unreliable:
PP7->AK47->PP7->wheel-down sometimes correctly landed on melee, but
sometimes landed back on AK47, and separately AK47->wheel-down sometimes
skipped past PP7 straight to melee.
Root cause: the wheel-down pulse staggered the synthetic 'hold A, tap Z'
combo across two polls (A alone, then A+Z one poll later). Whenever those
landed in two SEPARATE game ticks -- which happens unpredictably depending
on real-time poll/tick alignment (same D117-class nondeterminism as
everywhere else in the port) -- the 'A alone' tick was itself a fresh A
edge with no Z held, which bondview2.c's weaponForwardOffset formula (both
control-scheme sites) reads as a genuine cycle-FORWARD request, firing a
real, visible weapon change *before* the correcting backward tick ran.
Confirmed with an instrumented trace build: every wheel-down after the
very first one in a session mis-fired as a forward step.
Fix (port/src/input.c only, no game-logic touched): present A and Z
together from the first poll instead of staggering them, so whichever
single tick samples the 0->(A|Z) transition sees them rising
simultaneously. weaponForwardOffset requires Z NOT held, so that's
unambiguous -- only the backward path can fire, regardless of tick
timing. moveData.triggerOn (actual fire) is separately gated off while
A/invButtons is held, so this doesn't introduce an accidental shot.
User-verified: repeated up/down cycling through PP7/AK47/melee/Skorpion
in both directions with no more mismatches.
GoldenEye 007 PC Port
A native PC port of GoldenEye 007 (Rare, 1997, Nintendo 64), compiled from the GoldenEye 007 decompilation: the original N64 game running from reconstructed source, not the Xbox 360 remaster. The first alpha, v0.1.0, is out for Windows and Linux and runs the full campaign with rough edges (see Status).
It's also a case study in AI-agent collaboration on a large, low-level codebase: two coding agents, driven by one person part-time, porting ~230 translation units of unmodified big-endian MIPS game code to a 64-bit desktop. See Background.
Technically, it follows the architecture of the
Perfect Dark PC port, 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 (RSP)
is emulated in software; every other hardware surface (video, audio, input,
timers, save storage) is shimmed in a dedicated port/ layer.
Important
You must supply your own GoldenEye 007 ROM. This repository contains no Nintendo code or assets, and no ROM. Nothing here is distributable as a playable game — see Requirements and Legal.
In-engine, running in the port — Bunker 1 and Dam attract views, and a
~15 s clip (the clip itself has no audio track): mission dossier →
Facility → Silo → Jungle → Archives.
Quick start
You supply your own NTSC-U GoldenEye 007 N64 ROM (.z64, big-endian) — no
ROM or game asset is included or distributed. Then:
- Download the Windows or Linux bundle from Releases and unpack it.
- Make a
data/folder next to the executable and drop the ROM in asge007.ntsc-final.z64. - Run the one-time asset step:
python3 prepare-assets/prepare-assets.py(Python 3.8+, stdlib only). - Launch the executable from that folder.
Building from source instead: see Building. Read the Status caveats first — this is an early alpha.
Contents
- Quick start
- Background
- How this differs from the other GoldenEye PC projects
- Status
- Download
- Requirements
- Building · Windows (MSYS2) · Linux
- Running · Default controls
- How it works
- Project layout
- Documentation
- Credits
- Legal
- License
Background
The port used two agents handing work back and forth through shared written notes (a running handoff doc), directed by one person part-time:
- a local open-weight model —
unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XLon a single RTX 5090, driven mainly through the pi coding agent — which did the groundwork: the CMake build, the boot chain, the software-RSP integration, the offline asset-conversion pipeline, and the first rendered frames; - Claude (via Claude Code — mostly Sonnet 5, with Opus 5 as an escalation tier for the hardest bugs), which joined for a collaborative phase covering the 21-level load/render/no-crash sweep, the ABI/layout finding catalog, the SDL input layer, and the front-end flow.
In short: ~3.5 weeks, one person part-time, two agents, ~430 commits, 200+
root-caused bugs logged. The full write-up (timeline, the handoff mechanism,
commit/effort breakdown, and an honest "what worked / what didn't") lives in
docs/dev/agentic-development.md. The
workflow itself: docs/dev-process.md. To cite this
project or its findings, use 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 on a different codebase with no shared code with this one.
| This project | GoldenEye-Recomp / Steam Deck build | |
|---|---|---|
| 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 + Perfect Dark PC port engine family | Xbox 360 "…Recompiled" static-recompilation family |
| Renderer | Software RSP → OpenGL | Hardware (Vulkan) |
| Status | WIP alpha; see Status | Playable full game, higher frame rates, online multiplayer |
| Why it exists | A case study in AI-agent collaboration on a hard low-level codebase | 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's here is the other half, getting the original game running from source.
Status
Alpha — playable, not polished. It runs the full single-player campaign with no known crashes, but some front-end 3D models and cutscenes are broken, in-level music doesn't play yet, and input has known rough edges. A full end-to-end re-confirmation that all 21 missions are completable start to finish is still owed (see below). Treat it as an early alpha of the porting work, not a finished way to play GoldenEye.
Phase 3 of 4 (audio + input) is in progress; Phase 2 (rendering) is essentially done. First alpha: v0.1.0. The port boots, renders, and plays through the front end and the campaign, but is not finished or fully stable.
Working
- Boot → Rare/Nintendo logos → gun-barrel → cast intro, fully rendered.
- Front end: main menu → mission select → difficulty → briefing → mission start.
- All 21 solo missions load, render, and are crash-free. A v0.1.0-era
full-campaign playtest found two crashing levels (Bunker ii, Statue, one
root cause) and an AI-pacing bug that blocked the final level (Cradle) from
finishing; both were subsequently root-caused, fixed, and playtest-verified
(D191, D193) — a full re-playthrough confirming all 21 missions completable
start to finish on the current build is still owed. See
docs/dev/LEVEL-STATUS.md. - Software RSP (fast3d): textured world geometry, skeletal characters, HUD,
the GE-specific color-combiner / render modes and
G_TRI4. - Input: keyboard + mouse (with mode-aware mouse-look) and SDL game
controllers, mapped onto the N64 pad. Tunable via
ge007.ini. - File-backed EEPROM saves.
- Audio — software mixer (libultra audio layer → SDL, adapted from the PD port). In-level sound effects play; in-level music does not play yet (tracked as D77). Front-end/menu audio is unaffected.
- Windows and Linux (
x86_64). Windows is the primary development and playtest path. The Linux build was built and smoke-tested (boots, renders, passes the level sweep) at v0.1.0; it has not been actively maintained or retested since.
Not yet working
- In-level music — silent; see above (D77).
- Cutscenes — frequently glitch: skipped, wrong camera, misplaced or hovering actors, wrong timing (D148/D160).
- Some front-end 3D models — the spinning Nintendo logo, and the MISSION COMPLETE / mode-select models — are mispositioned or absent. (The gun-barrel Bond intro renders correctly.)
- Outdoor levels' sky rendering is still being fixed (was solid black; now
partially fixed with residual defects); assorted other cosmetic defects are
tracked in
docs/dev/GRAPHICS-BACKLOG.md. - No macOS or ARM support; no controller rebinding UI; no widescreen.
Download
Pre-built Windows and Linux x86_64 bundles are published under
Releases, starting with v0.1.0. Each contains the engine
executable, its runtime libraries, and the one-time prepare-assets tool —
no ROM and no game assets. See Quick start for the four
steps to get it running, Requirements for accepted ROMs, and
Status for the alpha caveats.
You can also build it yourself; see Building.
Requirements
You need a GoldenEye 007 (Nintendo 64) ROM that you legally own, in
big-endian (.z64) format, matching one of:
| Region | ROMID | ROM filename (in data/) |
SHA-1 |
|---|---|---|---|
| NTSC-U (US) | ntsc-final |
ge007.ntsc-final.z64 |
abe01e4aeb033b6c0836819f549c791b26cfde83 |
| PAL (EU) | pal-final |
ge007.pal-final.z64 |
167c3c433dec1f1eb921736f7d53fac8cb45ee31 |
| NTSC-J (JP) | jpn-final |
ge007.jpn-final.z64 |
2a5dade32f7fad6c73c659d2026994632c1b3174 |
US is the recommended and best-tested version.
The port also relies on the decompilation's asset-extraction step, which pulls the level, model, texture and music data out of your ROM at build time. That step, too, requires your ROM and is part of Building.
Building
Prerequisites: CMake >= 3.16, a C/C++ toolchain, SDL2, zlib, OpenGL, Python 3,
plus the decompilation's own build dependencies (an IRIX MIPS toolchain via
qemu-irix, used only for the one-time asset extraction). See
docs/building.md for the full walkthrough and the
asset-extraction details.
Windows (MSYS2)
# in the MINGW64 shell
pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-SDL2 \
mingw-w64-x86_64-zlib mingw-w64-x86_64-cmake \
mingw-w64-x86_64-python make git
git clone https://github.com/jkdansereau/goldeneye-pc-port.git
cd goldeneye-pc-port
# 1. extract assets from your ROM (see docs/building.md)
# 2. build the port
./build-pc.sh ntsc-final # or pal-final / jpn-final
Linux
Built and smoke-tested at v0.1.0; not actively maintained or retested since — the steps below are the intended path, not a continuously verified one.
sudo apt install build-essential cmake python3 libsdl2-dev zlib1g-dev libgl1-mesa-dev
git clone https://github.com/jkdansereau/goldeneye-pc-port.git
cd goldeneye-pc-port
# extract assets (docs/building.md), then:
./build-pc.sh ntsc-final
The executable is written to build-pc/ge007.x86_64 (on Windows,
build-pc/ge007.x86_64.exe).
Running
- Create a
data/directory in the repo root. - Put your ROM in it, named as in the table above
(e.g.
data/ge007.ntsc-final.z64). - Run the executable from the repo root:
./build-pc/ge007.x86_64.
Configuration is written to ge007.ini on first run.
Default controls
| Action | Keyboard / mouse | Controller |
|---|---|---|
| Move / strafe | W A S D / arrows |
Left stick |
| Aim / look | Mouse | Right stick |
| Fire (Z) | Left mouse / LCtrl |
Right trigger |
| Aim mode (R) | Right mouse / LShift |
Left trigger |
| Use / accept (A) | Space / E / X |
A / X |
| Reload / cancel (B) | R / F |
B / Y / RB |
| L trigger | Q |
LB |
| Start | Enter / Tab |
Start |
Mouse sensitivity, Y-inversion and the aim/turn split are tunable in the
[Input] section of ge007.ini.
How it works
The R4300 game code in src/ is compiled completely unmodified; the
decompilation's control flow is treated as ground truth. Everything that
would touch N64 hardware is redirected into port/:
port/fast3d/— a software RSP. It interprets the GBI display list the game builds each frame and emits OpenGL, bypassing the RDP. Adapted from the Perfect Dark port and extended for GoldenEye's custom GBI.port/src/gesched.c— replaces the RCP scheduler; instead of poking RSP registers it drives the software RSP directly.port/src/libultra.c— single-threaded shims for the libultra OS API (threads, messages, timers, PI/SI/AI/VI) over the host.port/src/{video,audio,input,fs,romdata,config}.c— the SDL2 / OpenGL / filesystem backends.
The 32→64-bit transition forces a small, cataloged class of mechanical ABI-only edits to ROM-serialized structs (pointer-width reconciliation); these change no behavior and are documented individually.
Where it diverges from the Perfect Dark port: GoldenEye's N64 serialized asset
formats (level setup, models, backgrounds) are converted offline by a set
of Python "sidecar" converters in tools_pc/, rather than fixed up at load
time. See docs/internals.md and
docs/porting-notes.md.
Project layout
CMakeLists.txt PC build (parallel to the decomp's Makefile, which is untouched)
build-pc.sh configure + build helper
src/ include/ the decompilation (game + libultra) - compiled unmodified
port/
fast3d/ software RSP -> OpenGL
src/ port layer (main, OS shims, video, audio, input, fs, ...)
include/ port-facing headers
tools/ Makefile the N64 build + asset extraction (from the decomp; do not modify)
tools_pc/ PC-port helper + analysis scripts
docs/ see below
Documentation
Key docs are also published as a site: https://jkdansereau.github.io/goldeneye-pc-port/.
| Doc | What's in it |
|---|---|
docs/building.md |
Full build + asset-extraction guide. |
docs/internals.md |
Architecture, the RSP-emulation approach, GE-vs-PD engine differences, the phased plan. |
docs/porting-notes.md |
The recurring N64→PC bug classes hit during the port, with fixes. |
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 |
The investigation workflow in detail — budgets, file partitioning, the finding-log discipline. |
docs/dev/ |
The raw engineering record: the full finding log, per-level status, graphics backlog, playtest matrices, and docs/dev/game-behavior-reference.md (a secondary-sourced playtest reference for how the retail game is meant to behave — repo-only, code is ground truth). |
docs/SetupGuide.md, docs/StyleGuide.md |
Inherited from the decompilation this repo forks. |
Credits
This port is a thin layer on a large amount of other people's work.
Prior work it is built on
- The GoldenEye 007 decompilation — years of effort by Larry Ficken ("kholdfuzion") and the project's contributors; plus zoinkity's GoldenEye documentation, which the decomp started from. This port is a fork of that repository.
- The Perfect Dark PC port
(Ryan Dwyer and contributors) — the reference architecture for this port and
the source of the
fast3dsoftware RSP. - The Perfect Dark decompilation — the sibling decomp the PD port is built on.
Vendored / adapted code
port/fast3d/— the software RSP, adapted from the PD port. It originates with the Ship of Harkinian / libultraship fast3d (© Emill, MaikelChan; MIT — seeport/fast3d/LICENSE.txt), which itself descends from sm64-port's fast3d and audio mixer.port/fast3d/glad/— OpenGL loader generated by glad (David Herberth, MIT).- The decompilation toolchain:
ido-static-recomp(Emill / decompals),qemu-irixandrabbitizer(n64decomp). - SDL2 and zlib.
Methodology
- Chris Lewis, "Decompiling a Nintendo 64 Game in 84 Days" (the Snowboard
Kids decompilation write-up) — the agent-workflow practices in
docs/dev-process.mdare adapted from it.
Tools and models used to develop the port
- Qwen 3.8 (Alibaba Qwen team), run locally as the
unsloth/Qwen3.8-27B-GGUFUD-Q4_K_XLquant; Unsloth (the GGUF quantisation and Unsloth Desktop, used as the local model server). - pi — the local coding-agent harness.
- Claude / Claude Code (Anthropic).
Legal
This is a non-commercial fan preservation/research project, in the same category as the many other N64 decompilation and native-port repositories on GitHub. It follows the same conventions they do:
- No ROM and no game assets are distributed — not in this repository and not in any release. Textures, audio, models, level data and in-game text are extracted from a ROM you already own, on your machine, at build time.
- The repository is a fork of the public
GoldenEye 007 decompilation and inherits
its contents unmodified (see
NOTICEfor what that includes). - No official logos, box art, or marketing assets are used. "GoldenEye 007", "007", "James Bond" and related marks belong to their respective owners (Nintendo, Microsoft/Rare, MGM, Danjaq, EON Productions).
- Pre-built binaries published under Releases contain
only the engine (the
port/layer plus the compiled decompilation, with no game data of any kind), bundled with permissively-licensed runtime libraries (SDL2, zlib, the MinGW runtime; their licenses travel in the download). Any build, yours or ours, is useless without a ROM you supply.
This project is not affiliated with, endorsed by, or sponsored by Nintendo, Rare, Microsoft, MGM, Danjaq, EON Productions, or any rights holder in GoldenEye or James Bond. If you are a rights holder with a concern, open an issue and it will be addressed.
License
The original work in this repository, the port layer (port/), the PC build
system, tools_pc/, and the documentation, is released under the MIT License;
see LICENSE. Everything inherited from the upstream decompilation
is covered by NOTICE, not by that license.