goldeneye-pc-port/README.md

GoldenEye 007 PC Port

GoldenEye 007 (Nintendo 64, 1997) as a native PC game for Windows, Linux and Steam Deck. Native widescreen, a steady 60 fps, 2–4 player split-screen, mouse and keyboard or a modern controller, rebindable controls and an in-game options menu. No emulator: the original game's own code, rebuilt from the GoldenEye 007 decompilation, running from your own ROM.

Download the latest release, then follow the Quick start.

Quick start · Controls · Features · Settings and files · Troubleshooting · Roadmap · Building · Legal

Important

You must supply your own GoldenEye 007 ROM. This repository and its downloads contain no Nintendo code or assets, and no ROM. See What's a ROM? and Legal.

v0.4.1 is the current release. It is a pre-1.0 release, not a finished product: the campaign and split-screen multiplayer play end to end, but expect missing pieces (PAL/JP ROMs, macOS) and the occasional breaking change between versions. v1.0 is the target for a feature-complete build.

AI disclosure: this port was developed agentically, with Claude Code and a local open-weight model, directed by one person in their spare time. The project is as much a study of that process as it is a port. See How it was made.

All in-engine, running in the port: a ~24 s gameplay montage from live v0.4.0 play sessions, opening on the Runway tank · 12 level stills in the project index

---

News

• v0.4.1: 2–4 player split-screen multiplayer, controller presets and rebinding, PlayStation/Nintendo button names, master volume and audio device selection, a steady 60 fps on low-end GPUs, and fidelity fixes checked against the N64 game (AI visibility at long draw distances, sniper zoom, turret pacing, Dam/Caverns water, weapons). Release notes.
• 2026-09-28 — v0.4.0: native widescreen, a complete aim system for mouse and controller, in-game key rebinding, crosshair customization, rumble-pak haptics, a rebuilt options overlay, and a broad fidelity-fix pass (water, particles, billboard trees, front-end logo, gunshot SFX, a true stable 60 fps). Release notes.
• 2026-09-20 — v0.3.0: the first release with the complete campaign playable end to end at 60 fps on Windows, Linux, and Steam Deck. Release notes.
• 2026-09-04 → 2026-09-16 — v0.1.0 – v0.2.2: the alpha and beta cycle: build chain, software RSP, first rendered frames, front end, and per-level stabilization across the campaign.

---

System requirements

Windows: Windows 10 or 11, 64-bit. Nothing else to install: the download carries its own runtime libraries and the one-time asset tool (no Python, no emulator).

Linux / Steam Deck: 64-bit x86 Linux. SDL2 is bundled, so the tarball runs as-is; it sideloads onto a Steam Deck with nothing installed.

Both: a GPU with OpenGL 3.0 drivers (practically any PC GPU from the last fifteen years; keep the driver up to date). A 2011 laptop with Intel HD 3000 graphics holds 60 fps; on very weak integrated GPUs (Atom/Celeron class) the first launch lowers draw distance and anti-aliasing to keep up. A keyboard and mouse, or a controller (Xbox, PlayStation, Switch and most SDL-supported pads); split-screen needs one controller per extra player.

Not yet: macOS, ARM Linux and Windows 7 are on the roadmap.

Quick start

1. From Releases, download the win64.zip (Windows) or the linux tarball (Linux and Steam Deck), and extract it. On Windows, never run the exe from inside the zip.
2. Make a data/ folder next to the executable and put your ROM in it as ge007.ntsc-final.z64. Only the US (NTSC-U) ROM works today; see What's a ROM? to check yours.
3. Launch the executable from that folder. Windows may show "Windows protected your PC" (SmartScreen, because the exe is not code-signed): click More info, then Run anyway.
4. The first start takes a few extra seconds: the port reads your ROM and generates its asset files once. After that it starts normally.
5. Play. F10 (pad: Select) opens the options overlay; the Controls table lists the default keys.

Steam Deck: the Linux tarball is the Deck build. Download it on the Deck (or copy it over from your PC), extract it, add your ROM to data/, launch it once, and add the executable as a non-Steam game. On first start it applies Deck-friendly display defaults (native 1280×800 fullscreen); if the resolution is wrong, set it under F10 → Resolution.

---

Controls

Action	Keyboard / mouse	Controller
Move / strafe	W A S D	Left stick (or D-pad)
Move / turn	Arrow keys	—
Aim / look	Mouse	Right stick
Fire	Left mouse	Right trigger
Aim mode	Right mouse / LShift	Left trigger / LB
Use / interact	E	A
Reload	R	X
Crouch	LCtrl	Left or right stick click
Cycle owned gadgets	Watch inventory	B
Next weapon	Mouse wheel down / Q	Y
Previous weapon	Mouse wheel up	—
Start	Enter / Tab	Start
Options overlay	F10	Select

The keyboard defaults are a GEPD-style layout. The controller layout matches Rare's Xbox 1.1 (Jinx) button roles; the other Xbox styles (1.2 Christmas, 1.3 Frost, 1.4 Elektra, which swap the stick roles) are selectable under Input → Controller → Layout preset. PlayStation and Nintendo controllers show their own button names in the menus.

Rebinding: Input → Bindings… in the options overlay rebinds the keyboard and mouse (Movement… and Actions…). Controller buttons are rebindable per controller under Input → Controller: set Layout preset to Custom, select an action and press a pad button (tap B or Esc to cancel, hold B to bind B itself, hold Back to clear; Y clears the selected slot). Each action takes up to two buttons. Menus always keep A/X accept and B/Y cancel, so you can't lock yourself out.

Split-screen: pick Multiplayer from the main menu. With one controller, keyboard/mouse is player 1 and the controller is player 2; with two or more controllers, the controllers take players 1–4 (Input.MPMode in ge007.ini changes this). A controller unplugged mid-match keeps its player when plugged back in.

Options overlay with a controller (also how it works on the Deck): Select opens it, the D-pad or left stick moves between options, A steps the selected option forward, B steps it back, and Start (or Select again) closes. With a keyboard, use F10 and the arrow keys/Enter.

Features

• 2–4 player split-screen multiplayer on every MP map, with the N64's own setup flow and per-player HUD.
• Native widescreen at any aspect ratio: the world is undistorted, the HUD sits at the screen edges, and 4:3 menus are pillarboxed. FOV and draw/LOD distance are adjustable, and AI behaviour stays as on the N64 whatever you set them to.
• The original look in one click: the Original N64 preset restores the N64's settings, Aspect → Original shows the exact 4:3 frame, and the Port defaults preset goes back.
• A steady 60 fps, with VSync and a frame cap (30 or 60), including on low-end GPUs.
• Graphics options: resolution, borderless fullscreen, MSAA (up to 16×), anisotropic filtering, and nearest, bilinear, trilinear or the N64's own 3-point texture filter.
• Mouse aim in your choice of style (the N64's, or centred FPS-style) with per-device sensitivity, smoothing and Y-inversion.
• Modern controller support: dual-stick layout, deadzones, sensitivity, southpaw, trigger thresholds, rumble-pak vibration, and PlayStation/Nintendo button names.
• Rebindable controls for keyboard, mouse and each controller.
• HUD and crosshair options: HUD scale, an optional customizable crosshair, and a no-hit-flash option.
• Full audio: in-level music and sound effects, with music, FX and master volume and a choice of output device.
• An in-game options overlay (F10 / pad Select) for all of the above, saved automatically.
• Faithful N64 progression by default. Opt-in extras: Skip intro and All unlocked (every level, 007 mode and the full cheat menu, without touching your save; both experimental).
• Saves in a plain file next to the game, so backing up is a file copy.

Status

Fully playable, with a small set of known caveats. All 20 solo missions and the end-of-campaign credits load, render and run crash-free; the full campaign was playtested end to end at Agent difficulty on Windows, Linux and real Steam Deck hardware for v0.4.0. Split-screen multiplayer was played live in 2P on every MP map and in 4P on Temple.

Known issues: see the known-issues table (what you'll notice, impact, workarounds). The short version: NTSC-U ROMs only in the release packages, and no macOS/ARM builds yet.

All unlocked never changes your save since v0.4.1: it unlocks every level and cheat in memory only, and switching it off shows your real progress. Builds before v0.4.1 could write fake unlocks into the save, and those are not repaired; if you used it on an older build, keep a backup of data/ge007.eep.

What a release installs (no networking, no telemetry, no ROM or game assets) and how faithfully the port tracks the original game's logic: Security & fidelity status.

---

Settings and files

Options overlay: press F10 (pad: Select) in game or in the menus. Changes are saved automatically. Most settings live in ge007.ini; the ones that come from the game's own watch menu (auto-aim, look ahead, sight and ammo on screen, music and FX volume) are part of your save, as on the N64.

Where files live: everything stays inside the game's own folder. The port never writes to %APPDATA%, the registry or any system location.

File	What it is
data/ge007.ntsc-final.z64	Your ROM (you put it there).
data/ge007.eep	Your game progress (the N64 save).
data/ge007.ini	Settings, written on first start.
data/pcmodels-<region>/, data/pccg-<region>/	Asset files generated from your ROM on first start. Safe to delete: they are made again on the next start.
data/ge007.shaders	A list of the graphics shaders the game used, compiled at startup to avoid stutter. Safe to delete.
ge007.crash.log	Written in the folder you launched from if the game crashes.

ge007.ini uses [Section] headers and Key = value lines. A few common keys and their defaults:

[Video]
Fullscreen = 0
VSync = 1
FpsCap = 60
MSAA = 2
TextureFilter = 1
NativeWidescreen = 1
FovScale = 100
DrawDistance = 250

[Audio]
MasterVolume = 100

Fullscreen 1 is borderless fullscreen; TextureFilter is 0 nearest, 1 bilinear, 2 the N64 3-point filter, 3 trilinear; FovScale and DrawDistance are percentages of the original (the options overlay shows the field of view in degrees). On Atom/Celeron-class GPUs the first launch writes lighter values for draw distance, LOD distance and MSAA. Edit the file with the game closed: it is rewritten on a clean exit, and comments are dropped.

Launch options: -fresh wipes the save and settings before starting (a clean-slate run). --version prints the build id.

What's a ROM?

A ROM is a copy of the game cartridge's data, made with a cartridge dumper from a cartridge you own. This project can't provide or link one. The port needs the big-endian .z64 format, and supports the US version today:

Region	ROM filename (in data/)	SHA-1	Supported
NTSC-U (US)	ge007.ntsc-final.z64	abe01e4aeb033b6c0836819f549c791b26cfde83	yes
PAL (EU)	ge007.pal-final.z64	167c3c433dec1f1eb921736f7d53fac8cb45ee31	not yet (#85)
NTSC-J (JP)	ge007.jpn-final.z64	2a5dade32f7fad6c73c659d2026994632c1b3174	not yet (#85)

To check which file you have, compute its SHA-1: on Windows, certutil -hashfile ge007.ntsc-final.z64 SHA1; on Linux, sha1sum ge007.ntsc-final.z64.

Updating

Extract the new release into a new folder, then copy your ROM, ge007.eep and ge007.ini from the old data/ folder into the new one. Don't copy the generated pcmodels-* and pccg-* folders: the new version makes its own on first start, and stale ones from an older version can cause glitches.

Uninstalling

Delete the folder. The port writes nothing anywhere else, so that removes the game, your save and your settings; back up data/ge007.eep first if you want to keep your progress.

Troubleshooting

• The game says the ROM is missing or wrong: check it is in data/, named ge007.ntsc-final.z64, in .z64 byte order, and that its SHA-1 matches the US row in What's a ROM?. PAL and JP ROMs are not supported yet.
• Windows shows a SmartScreen warning: the exe is not code-signed. Click More info, then Run anyway.
• Black screen or no window: update your graphics driver; the port needs OpenGL 3.0.
• Wrong resolution on the Steam Deck: F10 → Resolution.
• Where are my saves? data/ge007.eep. Copy it somewhere safe while the game is not running to back it up.
• The game crashes: open an issue and attach ge007.crash.log (in the folder you launched from), the output of --version, your OS, your GPU and your ROM's SHA-1. Never attach the ROM itself.

---

Roadmap

The goal is a feature-complete, faithful port: every mode and region the N64 cartridge ships, behaving 1:1 with the original, with modern options on top that can always be switched back to the original look and feel. The full list of open items, and which ones are waiting on a decision, lives in one place: docs/ROADMAP.md. In brief:

• PAL and JP ROM support in the release packages (#85). Both regions already convert, build and boot from source.
• macOS and ARM builds.
• The remaining small accuracy differences, each checked against the N64 game in an emulator.
• Emulator saves: a converter so saves from 1964, Project64 and other N64 emulators can be moved to and from the port (they need converting today; a straight copy is wiped).
• 1.0 sign-off: a full campaign playthrough at more than one difficulty plus a split-screen session, on every platform that ships.

This is spare-time work, so there's no timeline. Opt-in extras beyond the N64 game (LAN play, bots, co-op, HD textures, enhanced visuals, frame rates above 60) come after 1.0, and always off by default. Not planned: online multiplayer over the internet, achievements or cloud saves, remake-scope assets (new models, music or voice), and new movement mechanics. If any of these matter to you, open an issue — it helps prioritize.

How it was made

The port was built by two coding agents, directed by one person part-time. A local open-weight model (unsloth/Qwen3.8-27B-GGUF on one RTX 5090, via the pi agent) did the groundwork: build, boot chain, software-RSP integration, asset pipeline, first frames. Claude Code (Sonnet 5, Opus 5 for the hardest bugs) joined for the collaborative phase: the 21-level sweep, the ABI finding catalog, SDL input, front end. The two handed work back and forth through shared written notes. Up to v0.4.0: 43 days (16 Aug – 28 Sep), 1005 commits, 286 findings root-caused and logged (D1–D408).

The full write-up (timeline, handoff mechanism, effort breakdown, an honest "what worked / what didn't"): docs/dev/agentic-development.md. The workflow itself: docs/dev-process.md. To cite the project or its findings: 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	The other well-known "GoldenEye on PC" recompilation projects (and their Steam Deck builds)
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	Pre-1.0 releases; full campaign and split-screen playable at 60 fps (see Status)	Playable full game
Why it exists	To run the original N64 game from source, and as a case study in AI-agent collaboration on a hard low-level codebase	To get a playable PC release of the remaster

---

Building from source

Prerequisites: CMake >= 3.16, a C/C++ toolchain, SDL2, zlib, OpenGL and Python 3, plus MIPS binutils, make and git for the one-time asset extraction (no IDO/IRIX toolchain is involved; on Windows the extraction is easiest under WSL). 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         # NTSC-U; PAL/JP: see docs/building.md

Linux

The Linux build is compiled on every push by CI (ubuntu-24.04); the release bundle additionally bundles SDL2 so no system packages are needed at runtime.

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). To run a source build, create data/ in the repo root, put your ROM in it as in What's a ROM?, and run ./build-pc/ge007.x86_64 from the repo root.

How it works

The game code in src/ is the decompilation's, and its control flow is ground truth. Everything that would touch N64 hardware is redirected into port/: a software RSP (port/fast3d/, adapted from the Perfect Dark port) that interprets the GBI display list the game builds each frame and emits OpenGL, bypassing the RDP; libultra OS shims (port/src/libultra.c, game threads as real host threads) that let the game's own scheduler run, with the software RSP on its own render thread as the RSP was its own chip; and SDL2/OpenGL/filesystem backends for video, audio, input and storage. Edits inside src/ are rare, marked #ifdef PORT, and each one is documented: mostly mechanical 64-bit fixes (a struct or pointer field that the 32→64-bit move misaligned or truncated), plus a few maintainer-approved timing fixes where per-frame N64 code ran too fast at the PC's 60 fps (for example sniper zoom and turret fire), and the opt-in All unlocked hook. Where it diverges from the Perfect Dark port: GoldenEye's N64 serialized asset formats are converted offline by Python "sidecar" converters in tools_pc/ rather than fixed up at load time. Full detail: docs/internals.md and docs/porting-notes.md.

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); port edits are #ifdef PORT
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/ROADMAP.md	The single tracker of open work and known issues.
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, 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.

Contributing and forking

Issues and pull requests are welcome, and so are forks: the port layer, build system and tools_pc/ are MIT-licensed and exist to be extended. Read CONTRIBUTING.md first: it has the ground rules that keep the port faithful (game logic stays unmodified), what to verify before a pull request, and what a fork is asked to keep.

---

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 fast3d software RSP.
• The Perfect Dark decompilation, the sibling decomp the PD port is built on.
• Carnivorous: author of the Mouse Injector input plugin for 1964 (the "GEPD Edition" bundle). Its mouse-aim behaviour for GoldenEye/Perfect Dark is what the in-game GEPD-style aim mode is modelled on; the implementation here is an independent reimplementation of that behaviour, not derived code. Thanks also to Rice and schibo of the 1964 team for the emulator it shipped with.

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, see port/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-irix and rabbitizer (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.md are adapted from it.

Contributors

• dolent (#120, #121, #122), italoarruda (#107, #109), JosephAHK (#133), and MST246 (the #125 investigation), plus everyone who filed issues.

Consultation

• f1zz1ec0ke (GitHub): LLM consultation on model tuning, agent harnesses, and agentic strategy throughout the port's development.

Tools and models used to develop the port

• Qwen 3.8 (Alibaba Qwen team), run locally from the unsloth/Qwen3.8-27B-GGUF repo — UD-Q4_K_XL as the primary quant, with other quants used along the way; Unsloth (the GGUF quantisation and Unsloth Desktop) 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 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. "GoldenEye 007", "007", "James Bond" and related marks belong to their respective owners; they are used here only to say which game this port runs. No official logos, box art, or marketing assets are used.

What the download contains

• The engine: the port/ layer plus the compiled decompilation.
• Runtime libraries under permissive licenses (SDL2, zlib, the MinGW runtime); their licenses travel in the download.
• The one-time asset tool, which reads your ROM on your machine.

It contains no ROM and no game assets of any kind. Any build, yours or a release, is useless without a ROM you supply.

What happens on your computer

Textures, audio, models, level data and in-game text are extracted from a ROM you already own, on your machine, the first time you start the game. The port has no network access and never uploads anything.

This repository

The repository is a fork of the public GoldenEye 007 decompilation and inherits its contents (see NOTICE for what that includes). The few port-specific edits inside the decompiled code are marked #ifdef PORT.

Your part

• Only use a ROM that you dumped from a cartridge you own.
• Never ask for, link to or share ROMs or extracted game files in issues, discussions or pull requests.

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.

---

Last updated 2026-10-03 — v0.4.1 · GitHub · Releases