What is nesrecomp - NES Recompiler Project?

nesrecomp - NES Recompiler Project is an open-source tool. Tooling used for decompilation and recompilation work. The original game ran on NES.

Do I need the original game files to run nesrecomp - NES Recompiler Project?

Yes. The project does not include the original game's assets, so you need your own copy.

nesrecomp - NES Recompiler Project

ToolActive

Tooling used for decompilation and recompilation work.

nesrecomp - NES Recompiler Project screenshot

Links, repository & details

About

NESRecomp is a static 6502 recompiler framework for NES games that translates NES ROM machine code to C, which is then compiled to native code for modern PCs. The README lists per-game projects built on it, including Super Mario Bros., Duck Hunt, Dr. Mario, The Legend of Zelda, Metroid and Mega Man 3, with their own status notes. Windows is the primary platform, with macOS marked experimental.

Getting started

The README says no BIOS is needed and no ROMs are included. The generated output builds a static library only, so each game still needs game-specific configuration and runner integration; the listed game projects serve as starting points.

Known issues & limitations

macOS support is experimental; individual games may have minor behavior differences, including timing/demo differences in Super Mario Bros.

What you need to run it

Original game files required. The project ships code only; you provide your own copy of the game (NES version).

Windows x64 is the primary, mature platform; macOS support is experimental, and Linux is less tested.
A playable game requires game-specific configuration and runner integration; generating the source alone does not create a playable game.

Features

Games can use an optional Voxel 3D presentation that reconstructs tile geometry and sprites, with adjustable camera angles, zoom, and sprite scale.
A runtime text replacement system can change in-game text without editing the ROM.
Text overrides can hot-reload while the game runs; changes apply within about one second.
Game controllers are supported through SDL, including Xbox, PlayStation/DualSense, Switch Pro, and generic pads.
Keyboard and gamepad input work at the same time, with no configuration required to start playing.
The display preserves the NES aspect ratio, uses integer scaling and nearest-neighbor filtering, and letterboxes instead of stretching.

How to install

On Windows, download the CLI zip from Releases, extract it, open PowerShell in that folder, and run `nesrecomp.exe build` with the ROM and output paths.
If you have a `game.toml`, pass its path with the `--game` option when running the build command.

Controls

Tab toggles turbo (fast-forward).
Alt+Enter toggles borderless fullscreen.
The default Player 1 Select key is backslash; Tab and F1–F12 are reserved runtime hotkeys.

Summarised from the project's README.

Additional notes

Mapper support: Supported mappers are 0, 1, 4 and 66; UxROM, CNROM, AxROM and MMC2 are listed as not yet supported.
Voxel renderer: An opt-in, presentation-only Voxel 3D renderer is available to game projects that can describe their tile map and sprites.
Text override: A runtime text replacement system lets game plugins patch in-game text without editing the ROM.
Undocumented opcodes: Some undocumented 6502 opcodes are treated as sized no-ops, so a game relying on them would misbehave.

FAQ

What is nesrecomp - NES Recompiler Project?: nesrecomp - NES Recompiler Project is an open-source tool. Tooling used for decompilation and recompilation work. The original game ran on NES.
Do I need the original game files to run nesrecomp - NES Recompiler Project?: Yes. The project does not include the original game's assets, so you need your own copy.