goldeneye-pc-port

KO | EN

gitlite — search

#macos #animation #containers #github #self-hosted #android #javascript #large-language-models #nextjs #agent

goldeneye-pc-port

(★ 9)

Work-in-progress native PC port of GoldenEye 007 (N64), built on the decompilation — and a research project on multi-agent AI-assisted porting of a large low-level codebase.

File Explorer

ZIP Download

Showing a partial file list — download the zip above to see everything.

- - bug_report.yml
  - config.yml
- - ci.yml
  - selfhosted.yml
- dependabot.yml
- labels.yml
- pull_request_template.md
- release-notes.md
- SECURITY.md
- social-preview.html
- social-preview.md
- social-preview.png
- - fontBankGothic.c
  - fontZurichBold.c
  - readme.md
- - readme.md
- - instruments.ctl.s
  - instruments.tbl.s
  - music.s
  - readme.md
  - sfx.ctl.s
  - sfx.tbl.s
- - file_resource_id_enums.h
  - file_resource_table.inc.c
  - Makefile.bg
  - Makefile.brief
  - Makefile.chr
  - Makefile.filelist
  - Makefile.gun
  - Makefile.prop
  - Makefile.setup
  - Makefile.stan
  - Makefile.text
  - ob_seg.s
  - obseg.h
  - readme.md
- - ramrom.s
  - readme.md
- animationtable_data.c
- animationtable_data.h
- animationtable_entries.c
- animationtable_entries.h
- font_chardatae.c
- font_chardataj.c
- font_dl.c
- font_dl.h
- image_externs.h
- images.def
- Makefile.music
- Makefile.obseg
- oddtextures.c
- oddtextures.h
- rarewarelogo.c
- readme.md
- romfiles2.s
- FindSDL2.cmake
- TargetArch.cmake
- - head-custom.html
- - agentic-development.md
  - AUDIO-PLAN.md
  - AUDIT-M6-player-offsets.md
  - CUT-CONTENT-BACKLOG.md
  - D172-PARTICLE-COLOR-RESEARCH.md
  - D176a-SKY-NOTES.md
  - findings-index.csv
  - findings.md
  - game-behavior-reference.md
  - GE-ENV-PROBES.md
  - GRAPHICS-BACKLOG.md
  - HANDOFF-ARCHIVE.md
  - LEVEL-OBJECTIVES.md
  - LEVEL-PLAYTEST.md
  - LEVEL-STATUS.md
  - LINUX-PORT.md
  - M-35-PLAYTEST-CHECKLIST.md
  - M-35-QOL-REVIEW.md
  - M-36-TRIAGE.md
  - OPTIONS-MENU-PLAN.md
  - preview-video.md
  - QOL-INVENTORY.md
  - release-dropin-rom-plan.md
  - TEXTURE-GLITCH-ANALYSIS.md
  - UNLOCKED-FPS-PLAN.md
  - VIEWMODEL-RESEARCH.md
  - WIDESCREEN-FOV-PLAN.md
- - goldeneye-gh-preview.gif
- _config.yml
- building.md
- dev-process.md
- index.md
- internals.md
- porting-notes.md
- SetupGuide.md
- StyleGuide.md
- - cmd.make
  - Gui.make
  - VT100Codes.make
- - abi.h
  - gbi.h
  - gs2dex.h
  - gu.h
  - libaudio.h
  - libultra.h
  - mbi.h
  - os.h
  - os_internal.h
  - primage.h
  - R4300.h
  - ram_ORIGINAL_rom.h
  - rcp.h
  - rdb.h
  - region.h
  - rm_ORIGINAL_on.h
  - sptask.h
  - ucode.h
  - ultraerror.h
  - ultratypes.h
- assert.h
- bstring.h
- CPPLib.h
- gbi_extension.h
- LibFixedPoint.h
- limits.h
- macros.inc
- Makefile.targets
- math.h
- os_extension.h
- platform_info.h
- readme.md
- sgidefs.h
- stdarg.h
- stddef.h
- stdlib.h
- string.h
- svr4_math.h
- ultra64.h
- unused.h
- game.bss.ld.inc
- game.data.ld.inc
- game.rodata.ld.inc
- game.text.ld.inc
- images.ld.inc
- lib.bss.ld.inc
- lib.data.ld.inc
- lib.rodata.ld.inc
- lib.text.ld.inc
- prop_model.ld
- - gbiex.h
  - gfx_api.h
  - gfx_cc.cpp
  - gfx_cc.h
  - gfx_opengl.cpp
  - gfx_opengl.h
  - gfx_pc.cpp
  - gfx_pc.h
  - gfx_rendering_api.h
  - gfx_screen_config.h
  - gfx_sdl.h
  - gfx_sdl2.cpp
  - gfx_window_manager_api.h
  - LICENSE.txt
  - README.md
- - audio.h
  - audiotrace.h
  - config.h
  - crash.h
  - dram.h
  - fs.h
  - gimgfixup.h
  - hostsched.h.in
  - hoststddef.h.in
  - hoststdlib.h.in
  - hoststring.h.in
  - input.h
  - mixer.h
  - optionsoverlay.h
  - pc_protos.h
  - pccg.h
  - pcmodels.h
  - platform.h
  - port_math.h
  - realzlib.h.in
  - romconvert.h
  - romdata.h
  - system.h
  - utils.h
  - versioninfo.h.in
  - video.h
- - bondaicommands.h
  - bondconstants.h
  - bondtypes.h
  - CPPLib.h
  - R4300.h
  - sched.h
  - stdarg.h
  - stddef.h
  - stdlib.h
  - string.h
- - audio.c
  - config.c
  - crash.c
  - dram.c
  - dram_syms.s
  - fs.c
  - gimgfixup.c
  - input.c
  - libultra.c
  - main.c
  - mixer.c
  - n64stubs.c
  - optionsoverlay.c
  - pc_netorder.c
  - pccg.c
  - pcmodels.c
  - random.c
  - romassets_u.s
  - romconvert.c
  - romdata.c
  - rzdecomp.c
  - system.c
  - ucode.c
  - utils.c
  - video.c
- README.md
- - gmain.s
- rspboot.s
- d219_census.txt
- d219_headers.py
- - build_hashtable.sh
  - build_tools.sh
  - checksum.sh
  - clean_nuke.sh
  - combine_images.sh
  - combine_images_named.sh
  - create_directories.sh
  - generate_imagelist.py
  - rebuild_allver_hashtables.sh
  - sync_imagelist_with_def.py
- asmdiff.sh
- clean_baserom.sh
- extract_asp_gsp_rsp.sh
- extract_baserom.u.sh
- extract_cdata.sh
- extract_diff.e.sh
- extract_diff.j.sh
- filediff.e.csv
- filediff.j.csv
- filelist.e.csv
- filelist.j.csv
- filelist.u.csv
- ge007.e-test_basis.csv
- ge007.j-test_basis.csv
- ge007.u-test_basis.csv
- gen_pcprotos.py
- gen_romassets.py
- generate_chr_c.py
- generate_gun_c.py
- generate_prop_model_c.py
- IMAGE_BUILD_SYSTEM.md
- rename_sym.sh
- show_build_offsets.sh
- test_files.sh
- test_files_readme.md
- wsl_32bit_enable.sh
- - alloc_window_pieces.c
  - alloc_window_pieces.h
  - bg.c
  - bg.h
  - bg_portal_table.c
  - bgapply.c
  - bgfog.c
  - bgfog.h
  - bgroomtrans.c
  - bgroomtrans.h
  - blood_animation.c
  - blood_animation.h
  - blood_decrypt.c
  - blood_decrypt.h
  - bondhead.c
  - bondhead.h
  - bondinv.c
  - bondinv.h
  - bondview.c
  - bondview.h
  - bondview2.c
  - bondview_internal.h
  - bondview_r.c
  - bondview_r.h
  - bondwalk2.c
  - bondwalk2.h
  - cheat.c
  - cheat.h
  - chr.c
  - chr.h
  - chr_b.c
  - chr_b.h
  - chraction.c
  - chraction.h
  - chrai.c
  - chrai.h
  - chraidata.c
  - chraidata.h
  - chrobjdata.h
  - chrObjRandom.h
  - chrObjRandom.s
  - chrprop.c
  - cleanexplosions.c
  - cleanplayersound.c
  - cleanup_alarms.c
  - cleanup_alarms.h
  - cleanup_guard_data.c
  - cleanup_object_sounds.c
  - cleanup_objectives.c
  - cleanup_objects.c
  - cleanup_objects.h
  - cleanupSFXRelated.c
  - cleanwindowpieces.c
  - cobjdata.c
  - compiletime.c
  - compiletime.h
  - crc.c
  - deb_loadallmodels.c
  - deb_loadallmodels.h
  - debug_camera.c
  - debug_camera.h
  - debugmenu_08FE00.c
  - debugmenu_handler.c
  - debugmenu_handler.h
  - decompress.c
  - decompress.h
  - dyn.c
  - dyn.h
  - ejectedcartridges.c
  - ejectedcartridges.h
  - explosion.c
  - explosion.h
  - file.c
  - file.h
  - file2.c
  - file2.h
  - frametiming.c
  - frametiming.h
  - front.c
  - front.h
  - game_debug.c
  - game_debug.h
  - glass.c
  - glass.h
  - glass2.c
  - gobjdata.c
  - gobjdata2.c
  - gun.c
  - gun.h
  - gun_rodata.c
  - gunfire.c
  - image.c
  - image.h
  - image_bank.c
  - image_bank.h
  - indy_commands.c
  - indy_commands.h
  - indy_comms.c
  - indy_comms.h
  - initactorpropstuff.c
  - initactorpropstuff.h
  - initanitable.c
  - initanitable.h
  - initBondDATA.c
  - initBondDATA.h
  - initBondDATAdefaults.c
  - initBondDATAdefaults.h
  - initcheattext.c
  - initcheattext.h
  - initexplosioncasing.c
  - initexplosioncasing.h
  - initgamedata.c
  - initgamedata.h
  - initguards.c
  - initguards.h
  - initimages.c
  - initintromatrices.c
  - initintromatrices.h
  - inititemslots.c
  - inititemslots.h
  - initmenus.c
  - initmenus.h
  - initmttex.c
  - initmttex.h
  - initnull_0009D0.c
  - initnull_000BC0.c
  - initobjects.c
  - initobjects.h
  - initpathtablelinks.c
  - initpathtablelinks.h
  - initpathtablesomething.c
  - initpathtablesomething.h
  - initplayergaitobject.c
  - initunk_0009E0.c
  - initunk_005450.c
  - initunk_005450.h
  - initunk_005520.c
  - initunk_005520.h
  - initunk_007290.c
  - initunk_007290.h
  - initweaponanigroups.c
  - language.c
  - language.h
  - lightfixture.c
  - lightfixture.h
  - line_tri_intersect.c
  - loadobjectmodel.c
  - loadobjectmodel.h
  - lv.c
  - lv.h
  - math_asinacos.c
  - math_asinacos.h
  - math_asinfacosf.c
  - math_asinfacosf.h
  - math_atan2f.c
  - math_atan2f.h
  - math_ceil.c
  - math_ceil.h
  - math_floor.c
  - math_floor.h
  - math_sincos.h
  - math_sincos.s
  - math_unk_05A9E0.c
  - math_unk_05A9E0.h
  - matrixmath.c
  - matrixmath.h
  - matrixmath_misc.c
  - model.c
  - model.h
  - mp_music.c
  - mp_music.h
  - mp_weapon.c
  - mp_weapon.h
  - mpmenu.c
  - mpmenu.h
  - music_0D2720.c
  - music_0D2720.h
  - null_007970.c
  - ob.c
  - ob.h
  - objecthandler.c
  - objecthandler.h
  - objecthandler_2.c
  - objective.c
  - objective.h
  - objective_status.c
  - objective_status.h
  - objective_status2.c
  - options.c
  - options.h
  - othermodemicrocode.c
  - othermodemicrocode.h
  - padhalllv.c
  - padhalllv.h
  - player.c
  - player.h
  - playerstats_007770.c
  - pobjdata.c
  - prop.c
  - prop.h
  - propobj.c
  - propobj.h
  - quaternion.c
  - quaternion.h
  - radar.c
  - ramromreplay.c
  - ramromreplay.h
  - rle.c
  - rle.h
  - rsp.c
  - rsp.h
  - setguscale.c
  - sky.c
  - sky.h
  - spectrum.c
  - spectrum.h
  - spectrum_hw.h
  - speedgraphrenderer.c
  - speedgraphrenderer.h
  - stan.c
  - stan.h
  - stanintersection.c
  - stanintersection.h
  - sub_GAME_7F01D1C0.s
  - tex.c
  - tex.h
  - textrelated.c
  - textrelated.h
  - title.c
  - title.h
  - title2.c
  - title2.h
  - title3.c
  - title3.h
  - unk_092E50.c
  - unk_092E50.h
  - viewport.c
  - viewport.h
  - vtxstore.c
  - vtxstore.h
  - zlib.c
  - zlib.h
- - inflate.c
  - inflate.h
- - readme.md
- - libultrare.h
  - Makefile.libultrare
  - readme.md
- _start.s
- aicommands.def
- aicommands2.h
- aspboot.s
- audi.c
- audi.h
- bondaicommands.h
- bondconstants.h
- bondgame.h
- bondtypes.h
- boot.h
- boot.s
- bootcode.s
- boss.c
- boss.h
- c_data_filler.c
- c_data_filler.h
- cfb.c
- crash.c
- crash.h
- deb.c
- deb.h
- debugmenu.c
- debugmenu.h
- fr.c
- fr.h
- getra.s
- gspboot.s
- init.c
- init.h
- joy.c
- joy.h
- macro.h
- mema.c
- mema.h
- memp.c
- memp.h
- motor.c
- music.c
- music.h
- osMapTLB.s
- pi.c
- pi.h
- ramrom.c
- ramrom.h
- random.h
- random.s
- rmon.c
- rmon.h
- rom_header.s
- rspboot.s
- sched.c
- sched.h
- snd.c
- snd.h
- speed_graph.c
- speed_graph.h
- sprintf.c
- stacks.c
- str.c
- str.h
- thread_config.h
- tlb_hardwire.h
- tlb_hardwire.s
- tlb_manage.c
- tlb_manage.h
- tlb_random.h
- tlb_random.s
- tlb_resolve.h
- tlb_resolve.s
- token.c
- token.h
- usb.c
- usb.h
- vi.c
- vi.h
- - main.c
  - makefile
- - fread_csv_line.c
  - fread_csv_line.h
  - main.c
  - makefile
  - puff.c
  - puff.h
- - bits.c
  - crypt.c
  - crypt.h
  - deflate.c
  - getopt.c
  - gzip.c
  - gzip.h
  - inflate.c
  - lzw.c
  - lzw.h
  - Makefile
  - revision.h
  - tailor.h
  - trees.c
  - unlzh.c
  - unlzw.c
  - unpack.c
  - unzip.c
  - util.c
  - zip.c
- - .gitignore
  - elf.h
  - header.h
  - helpers.h
  - libc_impl.c
  - libc_impl.h
  - Makefile
  - README.md
  - recomp.cpp
  - version_info.c
- - .gitignore
  - Makefile
  - README.md
- - background.jpg
  - cursor.cur
  - main.c
  - makefile
  - objectives.h
- 1172compress.sh
- 1172inflate.sh
- aiParse.c
- armips.cpp
- bg_binary_to_c.py
- cmdbuilder.c
- data_compress.sh
- diff.py
- diff_settings.py
- ge-stats-deprecated.py
- ge-stats.py
- include-stdin.c
- Makefile
- n64cksum.c
- n64cksum.h
- RareZip.sh
- rasm2armips.py
- SGIImgView.png
.clang-format
.editorconfig
.gitattributes
.gitignore
.mailmap
AGENTS.md
allbuild.sh
build-pc.sh
CITATION.cff
CLAUDE.md
CMakeLists.txt
CONTRIBUTING.md
docker-compose.yml
Dockerfile
ge007.e.sha1
ge007.j.sha1
ge007.ld
ge007.u.sha1
imagelist.u.csv
LICENSE
Makefile
NOTICE
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Showing a partial file list.

Link

Example

# Project Badges

CI Visit
license

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A native PC port of _GoldenEye 007_ (Rare, 1997, Nintendo 64), compiled from
the [GoldenEye 007 decompilation](https://github.com/n64decomp/007): the
original N64 game running from reconstructed source, not the Xbox 360
remaster. The N64's graphics coprocessor (RSP) is emulated in software; every
other hardware surface (video, audio, input, timers, save storage) is shimmed
in a dedicated `port/` layer, following the architecture of the
[Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark), the same
Rare "Indy" engine family, one hardware generation apart.

**v0.2.0** is out for Windows and Linux (including Steam Deck, where the
Linux bundle sideloads as-is) and runs the full campaign at a steady 60 fps
with known rough edges ([Status](#status)). Free to download, build on and
modify (you bring the ROM).

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](#background).

> [!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](#requirements) and [Legal](#legal).

<img src="docs/media/goldeneye-gh-preview.gif" width="64%"
 alt="~32 s gameplay montage from live play sessions">
 All in-engine, running in the port, a ~32&nbsp;s gameplay montage loop
 from the v0.2.0 playtest.

## Download

| Platform | Bundle | Notes |
|---|---|---|
| **Windows** (x86_64) | [win64.zip](https://github.com/jkdansereau/goldeneye-pc-port/releases) | Engine + runtime DLLs + the one-time asset tool. |
| **Linux** (x86_64) / **Steam Deck** | [linux tarball](https://github.com/jkdansereau/goldeneye-pc-port/releases) | SDL2 is bundled, so it runs as-is on any distro, and sideloads onto a Deck with nothing installed. |

Both bundles contain **no ROM and no game assets**: you supply your own
(see [Requirements](#requirements)), which keeps the release legal to
distribute. Earlier builds: v0.1.0 alpha, same page. You can also build it
yourself; see [Building](#building).

### Quick start

You need a GoldenEye 007 N64 ROM (`.z64`, big-endian). This release supports
the **NTSC-U (US)** version; PAL and JP are on the roadmap ([issue
#85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)). No ROM or game asset is
included or distributed. Then:

1. Download the Windows or Linux bundle from [Releases](https://github.com/jkdansereau/goldeneye-pc-port/releases) and unpack it.
2. Make a `data/` folder next to the executable and drop the ROM in as `ge007.ntsc-final.z64`.
3. Launch the executable from that folder. The first run takes a few extra seconds: it detects the ROM and generates the derived asset folders once (no Python or other tooling needed).

Read the [Status](#status) caveats first: v0.2.0 has known rough edges,
listed plainly there.

## Status

**v0.2.0 - playable, with known rough edges.** The full single-player
campaign is completable end to end (all 21 missions, Agent difficulty,
playtested), at a steady 60 fps; all 21 solo missions load, render and run
crash-free, verified on Windows, Linux and real Steam Deck hardware. Feedback
is very welcome.

**Working:** boot sequence and front end (menu → mission select → briefing →
start); all 21 solo missions load, render and are crash-free (full campaign
playtested end to end at Agent difficulty); steady 60 fps
(software RSP off the presentation critical path); full audio: in-level music and SFX; keyboard + mouse (click-to-lock, proportional aim mode) and a modern
dual-stick controller layout; file-backed saves; faithful N64 progression by default
(F10 → *All unlocked* opens every level, 007 mode and the full cheat menu); F10 in-game
options overlay (resolution, frame cap, MSAA, filtering, FOV, sensitivity);
Windows and Linux.

**Known issues:**

- **Cutscenes still glitch, mostly with James Bond**: in scripted sequences
  Bond is the one who gets misplaced, hovers, or spins; the other actors are
  fine for the most part now. The Dam level-end cutscene is racy (D243).
  Still the most visible gap in this release.
- Particle colours drift through a rainbow palette instead of holding their
  grey/orange intent (bullet sparks, lingering smoke/explosion residue) (D252).
- Water levels show a moving seam between two water patterns (D245); thin
  pixel strips at the left/right screen edges at non-integer window scales
  (D246).
- Some front-end 3D models are off: the spinning Nintendo logo renders as two
  white blobs and the Rareware logo's texture filtering looks wrong (D75).
- The F10 overlay's bottom row duplicates whatever item is currently selected
  (D251).
- **Steam Deck:** one intermittent SIGSEGV remains in heavy firefights (D255);
  current builds capture full faulting registers in `ge007.crash.log`.
- Assorted further cosmetic defects are tracked in
  [`docs/dev/GRAPHICS-BACKLOG.md`](docs/dev/GRAPHICS-BACKLOG.md).
- No macOS or ARM support; no controller rebinding UI.

Root causes and fix status for every item: the [release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases)
and the finding log in [`docs/dev/findings.md`](docs/dev/findings.md).

### Steam Deck

The Linux bundle is the Deck build. SFTP it over from your PC, or download
it straight from the [releases page](https://github.com/jkdansereau/goldeneye-pc-port/releases) on the Deck itself:
unzip, drop your ROM in `data/`, launch it once (the first run generates the
derived assets), and add the executable as a non-Steam game. SDL2 is bundled, so no dependencies need
installing. On SteamOS the first launch seeds `ge007.ini` with Deck-friendly
defaults: native 1280×800 fullscreen, VSync, MSAA 4, and 150% draw/LOD
distance (the authored N64 fade distances read short on the close-up panel);
everything is changeable in the options overlay and persists afterwards. The renderer is CPU-bound (software RSP); expect original N64-era
performance at 60 fps rather than more. This release was playtested on real
Deck hardware; the v0.1.0-era Facility crash (D203) did not recur: its root
cause was identified and fixed (D253), verified on the Deck; one intermittent
SIGSEGV in heavy firefights remains open (D255).

**In-game settings on the Deck.** The options overlay is fully gamepad-driven:
it opens with **Select**, the D-pad or left stick (up/down) moves between
options, **A** steps the selected option forward, **B** steps it back, and
**Start** (or Select again) closes. Toggles flip, resolution / MSAA /
filtering cycle, sliders step in increments. With a keyboard attached the same
overlay is `F10` + arrows/Enter.

## Beyond playing

- **Tweak it**: `ge007.ini` and the F10 in-game overlay expose resolution,
  frame cap, MSAA, texture filtering, FOV/draw distance and mouse feel;
  launch with `-fresh` for a clean-slate run.
- **Read it**: [`docs/internals.md`](docs/internals.md) maps the
  architecture and the software RSP; [`docs/porting-notes.md`](docs/porting-notes.md)
  is the catalogue of N64→PC bug classes hit along the way. Game logic in
  `src/` is unmodified decompilation; every hardware surface lives in the
  MIT-licensed `port/` layer.
- **Mod it**: the port layer, build system and `tools_pc/` are yours to
  extend (see [License](#license)); [`CONTRIBUTING.md`](CONTRIBUTING.md) has
  the ground rules for getting changes in, and [`docs/dev/`](docs/dev/) is
  the raw engineering record behind every fix.

## Background

The port was built by two coding agents, a local open-weight model
(`unsloth/Qwen3.8-27B-GGUF` on one RTX 5090, via the [pi](https://pi.dev/)
agent) doing the groundwork (build, boot chain, software-RSP integration,
asset pipeline, first frames), and **Claude Code** (Sonnet 5, Opus 5 for the
hardest bugs) joining for the collaborative phase (the 21-level sweep, the
ABI finding catalog, SDL input, front end), handing work back and forth
through shared written notes, directed by one person part-time. In short:
~3.5 weeks, ~430 commits, 200+ bugs logged and tracked to resolution.

The full write-up (timeline, handoff mechanism, effort breakdown, 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). To cite the
project or its findings: [`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 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](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** | v0.2.0 public release; full campaign playable at 60 fps (see [Status](#status)) | Playable full game with online multiplayer |
| **Why it exists** | To run the *original* N64 game from source, and as a [case study in AI-agent collaboration](#background) on a hard low-level codebase | To get a playable PC release of the remaster |

They answer a different question: how to get the *remaster* onto PC by
machine translation. This project answers how to get the *original 1997
game* onto PC, running from its reconstructed source.

## 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` |

This release supports the US (NTSC-U) version; PAL and JP ROMs are
recognised by region but not yet supported (on the roadmap, [issue
#85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)).

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).

## 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`](docs/building.md) for the full walkthrough and the
asset-extraction details.

### Windows (MSYS2)

```sh
# 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 engine builds compile, but their asset sidecars are not yet producible (issue #85)
```

### 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.

```sh
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

1. Create a `data/` directory in the repo root.
2. Put your ROM in it, named as in the table above
   (e.g. `data/ge007.ntsc-final.z64`).
3. Run the executable from the repo root:
   `./build-pc/ge007.x86_64`.

Configuration is written to `ge007.ini` on first run; game progress
lives in `ge007.eep`. Launch with `-fresh` to wipe both before starting
(a clean-slate run for playtesting).

### Default controls

| Action              | Keyboard / mouse         | Controller    |
|---------------------|--------------------------|---------------|
| Move / strafe       | `W` `A` `S` `D` / arrows  | Left stick (or D-pad) |
| 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         |
| Next weapon         | Mouse wheel up           | RB            |
| Previous weapon     | Mouse wheel down         | LB            |
| Start               | `Enter` / `Tab`          | Start         |
| Options overlay     | `F10`                    | Select (D-pad/stick + A/B navigate, Start closes) |

The controller layout follows the modern dual-stick scheme used by the
console re-releases (left stick move, right stick look, triggers fire/aim,
shoulders cycle weapons).

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 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; a scheduler
replacement (`port/src/gesched.c`) that drives it directly; single-threaded
libultra OS shims (`port/src/libultra.c`); and SDL2/OpenGL/filesystem backends
for video, audio, input and storage. 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 are converted offline by Python "sidecar" converters
in `tools_pc/` rather than fixed up at load time. Full detail:
[`docs/internals.md`](docs/internals.md) and
[`docs/porting-notes.md`](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) - 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`](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/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, and [`docs/dev/game-behavior-reference.md`](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/SetupGuide.md), [`docs/StyleGuide.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](https://github.com/n64decomp/007), 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](https://github.com/fgsfdsfgs/perfect_dark)
  (Ryan Dwyer and contributors), the reference architecture for this port and
  the source of the `fast3d` software RSP.
- The [Perfect Dark decompilation](https://github.com/n64decomp/perfect_dark),
  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](https://github.com/HarbourMasters) /
  libultraship fast3d (© Emill, MaikelChan; MIT, see `port/fast3d/LICENSE.txt`),
  which itself descends from
  [sm64-port](https://github.com/sm64-port/sm64-port)'s fast3d and audio mixer.
- `port/fast3d/glad/`: OpenGL loader generated by
  [glad](https://github.com/Dav1dde/glad) (David Herberth, MIT).
- The decompilation toolchain: [`ido-static-recomp`](https://github.com/decompals/ido-static-recomp)
  (Emill / decompals), [`qemu-irix`](https://github.com/n64decomp/qemu-irix) and
  `rabbitizer` (n64decomp).
- [SDL2](https://libsdl.org) and [zlib](https://zlib.net).

**Methodology**

- Chris Lewis, [*"Decompiling a Nintendo 64 Game in 84 Days"*](https://blog.chrislewis.au/decompiling-a-nintendo-64-game-in-84-days/) (the Snowboard
  Kids decompilation write-up), the agent-workflow practices in
  [`docs/dev-process.md`](docs/dev-process.md) are 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-GGUF`](https://huggingface.co/unsloth/Qwen3.8-27B-GGUF)
  `UD-Q4_K_XL` quant;
  [Unsloth](https://unsloth.ai) (the GGUF quantisation and Unsloth Desktop,
  used as the local model server).
- [pi](https://pi.dev/): the local coding-agent harness.
- [Claude / Claude Code](https://claude.com/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](https://github.com/n64decomp/007) and inherits
  its contents unmodified (see [`NOTICE`](NOTICE) for 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](https://github.com/jkdansereau/goldeneye-pc-port/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`](LICENSE). Everything inherited from the upstream decompilation
is covered by [`NOTICE`](NOTICE), not by that license.

goldeneye-pc-port

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README