LegendOfZeldaNESRecomp

This recompilation is a byproduct of developing nesrecomp — the games are the proving ground, the framework is the goal. These are in-development previews, not finished ports — expect rough edges, and depth will keep landing over months, not days. My time for any one title is limited, so I ask for your patience. Contributions are welcome — testing, issues, and PRs to the game or framework all help and will accelerate this game's polish. More on the why at: Recomp + AI: 5 Months Later »

Static recompilation of The Legend of Zelda (NES) for native PC. Built with the NESRecomp framework.

Cycle migration preview: the cycle CPU is now the default source build, with the legacy backend still available. The earlier legacy build was tested through dungeon 7. Current cycle checks cover startup, an overworld route, save/replay and presentation modes; a new full-game audit is pending. See cycle migration notes.

Acknowledgments

The complete dispatch function coverage was made possible by the zelda1-disassembly by Aldo Nunez. The disassembly's debug symbols were used to extract callable function addresses for the SRAM-mapped code region, closing the final dispatch gaps.

What Works

• Overworld exploration, with optional seamless camera and neighboring rooms
• Dungeons, bosses, and items
• Enemies and combat
• Caves (old man, merchants, dungeon entrances)
• Inventory / pause subscreen
• Battery-backed save persistence (saves/<ROM stem>.sav beside the executable); older raw 8 KiB .srm progress imports through the launcher

Quick Start

1. Download LegendOfZeldaNESRecomp-windows-x64.zip from Releases
2. Extract and run LegendOfZeldaNESRecomp.exe
3. Select your Legend of Zelda (USA) ROM when prompted — the path is saved for future launches

Seamless Overworld · Experimental

New in v1.10.0. Open Mods and enable Seamless Overworld, the first entry under Camera. Its amber EXP / EXPERIMENTAL badge marks it as an experimental feature. Fresh profiles enable it for adaptive widescreen; existing explicit mod choices are retained. Its Gameplay options include Stopwatch scope: Entire map, Current viewport at pickup, or Current room at pickup.

<p align="center"> <img src="docs/assets/seamless-overworld.png" alt="Expanded Zelda overworld showing Link and live enemies in neighboring areas" width="960"> </p>

The camera follows Link across ordinary room boundaries, with neighboring terrain and actors visible before he enters. Connected dungeon rooms also share the continuous view. Fit to screen expands the visible world to match the window in landscape or portrait; resize freely, use the mouse wheel to change pixel zoom, or press F4 to see the whole map.

<p align="center"> <img src="docs/assets/seamless-dungeon.png" alt="Level 1 dungeon with multiple connected rooms and their enemies visible together" width="960"> </p>

Inventory retains the expanded scene, bomb flashes span the view, and death, Game Over and Continue keep the window's framing. Caves, stairs, dungeon entrances and maze puzzles preserve their original portal routing. This mode is mutually exclusive with voxel and Remastered views.

<p align="center"> <a href="docs/assets/seamless-atlas.png"><img src="docs/assets/seamless-atlas.png" alt="The entire Zelda overworld displayed at once using the whole-map view" width="960"></a> </p>

Experimental limits: local play only. Enemy migration and projectile interactions across room boundaries are incomplete, the whole-map simulation runs slower, and later dungeons, bosses and both quests still need broader coverage. These are representative gameplay checks, not a full-game completion claim. See implementation and validation notes.

Controls

For silent startup failures, enable Startup and Crash Diagnostics in Mods before PLAY, then share the newest log and any matching Windows minidump from diagnostics beside the program. This mod is disabled by default. See diagnostic instructions.

NES Button	Keyboard
D-Pad	Arrow keys
A	Z
B	X
Start	Enter
Select	Backslash

Hotkey	Action
Escape	Menu/settings
Tab	Hold fast-forward
F7	Save-state slots
F8	Rewind
F11	Fullscreen
F12	Screenshot
Numpad 0	Toggle Voxel 3D
Numpad 8 / 2	Increase / decrease camera pitch
Numpad 4 / 6	Adjust camera yaw left / right
Numpad 7 / 9	Roll camera left / right
Numpad + / -	Zoom in / out
Numpad 1 / 3	Shrink / enlarge assembled sprites
Numpad 5	Reset the live camera rig to package defaults
Right stick (first person)	Look horizontally and vertically
Left stick / D-pad / arrow keys (first person)	Move relative to the camera

Zelda Remastered HD Mod

The cycle build uses the original USA PRG0 ROM for every presentation mode. Remastered is installed and selected through Mods in the same executable. Create a local package from your existing Mesen pack:

python tools/import_hdpack.py --pack "/path/to/pack" --rom "/path/to/Legend of Zelda.NES" --out "Zelda-Remastered.nesmod"

Install that archive in the launcher's Mods page, then enable Zelda Remastered HD before starting. It is disabled by default and shares an exclusion group with voxel views. The framework verifies the pack's IPS and applies it to an in-memory cartridge copy; your ROM stays unchanged. The included pack creator notice is preserved. Texture/background presentation uses the original PPU; replacement music and sound files remain unsupported. To return to stock, disable the feature in the launcher and restart. Pack/patch selection is read-only during gameplay, and save states require matching assets and options.

With Remastered enabled, choose Graphics → HD resolution in the in-game settings. Pack resolution keeps the pack's original size; you can also choose 1× through 16×. The 32× and 64× choices are experimental.

Voxel 3D (experimental)

<p align="center"> <img src="docs/assets/voxel-3d.webp" alt="The Legend of Zelda rendered as a Voxel 3D diorama" width="960"> </p>

Open Mods in the launcher and enable either Voxel 3D Overworld (Experimental) or Voxel 3D First Person (Experimental). The two presentation modes are mutually exclusive: enabling one automatically disables the other. Both bundled features are disabled by default and target the verified stock PRG0 ROM. Camera pitch, yaw, roll, zoom, and sprite scale can be saved as package options. The numpad controls above provide temporary live experimentation; they do not rewrite mods/state.toml. Title, registration, and inventory screens remain flat and pillarboxed.

The overworld camera presents each room as a raised tabletop. Pitch changes how far the camera looks down into the room; yaw orbits around the vertical axis; roll tilts the horizon; zoom changes framing without changing the room; and sprite scale adjusts assembled Link, enemy, item, and effect cards. Extreme angles are intentionally available for experimentation, while Numpad 5 returns the live camera to the package defaults.

The first-person camera follows Link's live position and uses a two-stick control model: the right stick owns continuous yaw and pitch, while the left stick moves relative to the direction being viewed. D-pad and arrow-key input use the same camera-relative mapping. Zelda's original movement remains four-directional, so diagonal or off-axis intent is quantized to the nearest native cardinal direction with a small hysteresis band to prevent jitter. Temporary numpad yaw participates in that same mapping, so pressing forward continues through the adjusted view instead of snapping the camera elsewhere. Link's own card is hidden because the camera occupies it, while enemies, weapons, pickups, effects, terrain, shadows, and the original HUD remain visible. In this mode pitch looks up or down, yaw offsets the view from the current heading, and zoom adjusts the field of view.

Geometry comes from Zelda's live 32x22 PlayAreaTiles grid and its collision classification. The original frame supplies tile textures, while current OAM pieces are assembled into coherent camera-facing metasprite cards before projection. Zelda's verified 2x2 tree metatiles become transparent, camera-facing foliage cards; boundary rocks remain solid prisms. Every tree, actor, pickup, weapon, projectile, and effect card receives a proportional contact shadow. Native-room clipping and a Link-specific height cap prevent transition-only OAM pieces from stretching over northern doors. Room scrolling holds the last complete diorama while Zelda streams its next nametable, then replaces it atomically with the completed destination room. The black HUD field is extended across the widescreen frame while the original HUD remains centered and pixel-perfect. This is a presentation-only trusted plugin: normal execution, the stock ROM, saves, and launches with the feature disabled are unchanged.

Building from Source

Requires Visual Studio 2022 and CMake 3.20+.

git clone https://github.com/mstan/LegendOfZeldaNESRecomp
cd LegendOfZeldaNESRecomp

# Windows
setup.bat

# Linux / macOS
chmod +x setup.sh && ./setup.sh

This initializes the pinned nesrecomp and recomp-ui submodules. Cycle configuration generates native code directly from your supplied ROM.

Then build:

cmake -S . -B build-cycle -G "Visual Studio 17 2022" -A x64 -DNESRECOMP_ROM="F:/ROMs/Legend of Zelda.NES"
cmake --build build-cycle --config Release

Choose the same USA PRG0 ROM at runtime. Remastered uses the Mods importer above. For an explicit legacy build, see cycle migration notes.

Architecture

The original 6502 code is translated to cycle-aware C and compiled to native code. Unprofiled code and cartridge work-RAM code safely use the cycle interpreter. The PPU, APU and mapper advance with the guest CPU.

• config/cycle/ — default cycle configuration, seeds and capture inputs
• config/legacy/ — retained legacy compiler configuration and disassembly symbols
• src/ — game integration, presentation, diagnostics and mod plugins
• assets/ — launcher box art
• docs/ — controls, release notes, diagnostics and implementation notes; historical discovery evidence is in docs/reference/
• tools/make_release.ps1 (or tools/release.bat) — Windows release packaging
• tools/import_hdpack.py — shared framework HD-pack package importer with Zelda attribution
• src/cyc_extras.c / src/cycle_bridge.h — cycle presentation, input and diagnostics adapter
• src/zelda_voxel.c — Zelda tile-height profile and 3D view controls
• build-cycle/cycle-* — generated cycle code (do not edit manually)
• generated/ — retained legacy generated inputs
• nesrecomp/ — framework submodule (recompiler + runner)

Known Limitations

• Remastered preserves the existing sampler limitations for unsupported conditions or missing images. HD-pack replacement music and sound files remain unsupported.
• Legacy binary save states do not transfer to the cycle backend. Raw battery progress remains portable.
• Voxel views retain their existing experimental camera and geometry limitations.
• Seamless Overworld remains experimental; its current limitations are listed above.

License

PolyForm Noncommercial 1.0.0 — see LICENSE. Third-party components retain their own licenses.

---

<p align="center"> _{<b>R.A.I.D. — Retro AI Development</b> · a Discord for AI-assisted retro reverse-engineering, decomp &amp; recomp} </p> <p align="center"> <a href="https://discord.gg/Ad9BwSzctP"><img src=".github/raid-discord.png" alt="Join the Retro AI Development (R.A.I.D.) Discord" width="200"></a> </p>