SuperMarioBrosRecomp

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 Super Mario Bros. (NES) for native PC. Built with the NESRecomp framework.

Windows builds record startup diagnostics automatically. After a failed launch, send the diagnostics folder beside the executable. See collecting startup diagnostics, including the helper for Windows loader failures before the launcher appears.

Status: The game is fully playable. All worlds and levels are believed to be completable, though not every path has been exhaustively tested. If you find a game-breaking bug, please open an issue.

CPU backend

Cycle-accurate execution is the default. Stock gameplay and the existing enhancements have cycle adapters; see the historical migration validation. The previous runner remains available with -DNESRECOMP_BACKEND=legacy in a separate build directory. Legacy save states require the legacy runner; cycle states use their own format.

PPU rendering

Windows x64 cycle builds default to the qualified HLE renderer. Matched full-runtime measurements improved FPS in both run orders; focused PPU checks and an owner playcheck, including adaptive widescreen scrolling, passed. The scroll fix is PR #8.

The maintained LLE renderer remains the correctness reference and uses the same caller interface. Select it explicitly with -DNESRECOMP_PPU_IMPL=LLE in a separate build directory; this opt-out may lose performance. Other platforms retain the framework default. This qualification covers Super Mario Bros. on Windows x64, not other games or FDS software. Use --widescreen fit for adaptive window sizing.

Quick Start

1. Download SuperMarioBrosRecomp-windows-x64.zip from Releases
2. Extract and run SuperMarioBrosRecomp.exe
3. Select your Super Mario Bros. (World) ROM when prompted — the path is saved for future launches

Both the older iNES header and the modern NES 2.0 World header are supported:

File format	File CRC32	File SHA-1
NES 2.0 World	393A432F	33d23c2f2cfa4c9efec87f7bc1321ce3ce6c89bd
Legacy iNES	3337EC46	ea343f4e445a9050d4b4fbac2c77d0693b1d0922

These files contain identical USA-compatible World game data: PRG+CHR CRC32 D445F698, SHA-1 facee9c577a5262dbe33ac4930bb0b58c8c037f7. Keep the .nes header; no conversion is required. The launcher checks the game data, and the runtime accepts equivalent header encodings while retaining checks for different cartridge hardware and PAL-only timing.

For contributors: build from source, browse the repository layout, or start with the developer guides and test instructions.

Character replacements (experimental)

SuperMarioBrosRecomp includes default-off, mutually exclusive character replacement mods. They are experimental showcases: expect occasional bugs, and use the launcher Mods screen to enable only one player-controller package at a time. Each replacement is backed by a legally owned source ROM that the launcher verifies before play; no owner ROM data or generated owner-ROM assets are shipped in the release.

Captain Falcon	Pikachu
Samus	Link
Sonic

Smash 64 characters (bundled mod)

Open Mods, select Smash 64 Player Replacement, choose Captain Falcon or Pikachu from the Character dropdown, and select your legally owned Super Smash Bros. (USA), NTSC-U v1.0 ROM. The launcher accepts z64, v64, or n64 byte order and verifies normalized SHA-1 e2929e10fccc0aa84e5776227e798abc07cedabf. The mod cannot be enabled without that exact revision.

On first play, the bundled helper derives the selected fighter's model, animations, effects, and audio into an integrity-checked user cache. Neither the Smash 64 ROM nor generated fighter assets are included in the download or copied into the game directory. A is the fighter's normal attack, B is the fighter's special, and Up is the four-frame Smash jump. Captain Falcon has Falcon Punch, Falcon Dive, and Falcon Kick; Pikachu has Thunder Jolt, Quick Attack, and Thunder.

Samus (bundled mod)

Open Mods, enable Metroid Samus Player Replacement, and select a legally owned canonical Metroid USA PRG0 or Europe/PAL ROM. Headered and headerless images are accepted; the launcher strips a valid iNES header and verifies normalized SHA-1 fdbfc7871962f72a1ef57e5a7e456164fb93430b (USA) or 68a55eafcefa3014a4771cb7983d7db42f80456a (Europe). Samus's sprite tiles are extracted into memory from that verified ROM. No Metroid ROM data or derived graphics are shipped or written beside the game.

Samus begins with 99 energy and every original upgrade equipped. A jumps, B fires, Down morphs, and Select switches between the combined Long/Wave/Ice beam and infinite missiles. B lays bombs in Morph Ball. Screw Attack, missiles, and bombs break only SMB's ordinary breakable bricks; contact hurts Samus instead of stomping enemies. Mushroom restores 30 energy, Fire Flower restores all energy. Bomb blasts boost a nearby Morph Ball upward, and Starman contact defeats enemies while its native temporary invincibility is active. Metroid's ability sound effects are rebuilt in memory from the verified owner ROM.

The Samus and Smash 64 packages share the player-controller exclusive group, so the launcher permits only one at a time. See docs/METROID_SAMUS_MOD.md for implementation and validation details.

Zelda II Link (bundled mod)

Open Mods, enable Zelda II Link Player Replacement, and select a legally owned canonical Zelda II: The Adventure of Link (USA) ROM. Headered and headerless images are accepted; the launcher strips a valid iNES header and verifies normalized SHA-1 11333adb723a5975e0ecca3aee8f4747aa8d2d26. Link's side-view sprite tiles are extracted into memory from that verified ROM. No Zelda II ROM data or derived graphics are shipped or written beside the game.

Link uses Zelda II-style controls: A jumps, B slashes, Down crouches, and Up/Down with B in the air performs vertical stabs. Sword strikes hurt enemies and, as an SMB-specific liberty, can break ordinary breakable bricks. The Link, Samus and Smash 64 packages share the player-controller exclusive group, so the launcher permits only one at a time. See docs/ZELDA2_LINK_MOD.md for implementation and validation details.

Sonic 3 & Knuckles Sonic (bundled mod)

Open Mods, enable Sonic 3 & Knuckles Sonic Player Replacement, choose Sonic from the Character dropdown, and select a legally owned canonical Sonic 3 & Knuckles Genesis ROM. The launcher verifies normalized SHA-1 cfbf98c36c776677290a872547ac47c53d2761d6. Sonic's Genesis sprites are decoded into memory from that verified ROM, and his sounds come from Sonic 3 & Knuckles' own Z80 sound driver, decompressed from the same ROM and run on an emulated Genesis sound board. No Sonic 3 & Knuckles ROM data, derived graphics or rendered audio are shipped or written beside the game.

Optionally, also select a Sonic the Hedgehog 2 (World) (Rev A) ROM (normalized SHA-1 8bca5dcef1af3e00098666fd892dc1c2a76333f9). Sonic 3 & Knuckles has no art for the standard shield, so with it the Mushroom shield uses Sonic 2's shield instead of a Bubble Shield stand-in.

Sonic's player object is ported routine by routine from the Sonic 3 & Knuckles disassembly with its fixed-point math, so movement, rolling and air control match the original. A and B both act as the Genesis jump button: Down plus jump charges a spindash, and jump again in the air uses the Insta-Shield, or the Fire Shield dash while holding a Fire Flower. Coins work as rings (a hit spills them), a Mushroom is the standard shield and a Fire Flower the Fire Shield. SMB keeps deciding what happens to its own objects: stomps shed Koopa wings and shells, spinies and a rising jump into a ground enemy still hurt, shield moves and rolls hit blocks, and lifts are top-solid platforms. Bouncing blocks, jumping coins and power-ups are no longer limited by SMB's object slots while Sonic plays. The Sonic, Link, Samus and Smash 64 packages share the player-controller exclusive group, so the launcher permits only one at a time.

Simultaneous Co-op

Enable Simultaneous Co-op in the launcher's Mods tab and choose two, three, or four players. Mario, Luigi, Wario, and Waluigi share the original 4:3 levels, scarce items, score, and team attempts. Players pass through each other; kicked shells can hurt allies. Dead teammates return after a level ends or the whole team retries. Assign each device in Controls, then select CO-OP PLAY at the title screen.

Co-op supports local and online play, and is mutually exclusive with widescreen, voxel/first-person, and player replacement mods. See the co-op guide for the complete rules, save compatibility, and test coverage.

October 2026 coverage pass

The North American/World payload (D445F698) is checked before generation. The Windows x64 HLE default passed all 32 original area loaders and assisted exits in 32:9, including the original 8-4 ending. Native and interpreter runs matched every recorded machine hash, final picture and complete state. The fixtures assist player form, lives and exit positioning; they do not prove obstacle traversal or Bowser combat victories. Widescreen includes the current PPU scroll-phase correction for the margins.

HLE and LLE cycle states have different layouts. Older LLE states require an LLE build (NESRECOMP_PPU_IMPL=LLE); a renderer mismatch is refused on load.

Widescreen mod (experimental)

An experimental custom renderer extends the terrain beyond the NES's 256-pixel viewport, with Fit window, 16:9, 21:9, and 32:9 options. Ordinary authored enemies load across the wide view. Enemy movement selects movement on load or preserved original 4:3 activation. Independent moving platforms also use the expanded view. Special spawners, linked balance platforms and some other objects still retain native limits. See widescreen guide for the current limits and validation.

The camera anchors at the start and end of an area to avoid empty space. Small fixed rooms stay centered. Select Keep native view centered in the Camera option to restore the previous presentation.

Open Mods in the launcher and enable Widescreen (Experimental). It is a default-off package alongside Voxel 3D. The two display modes are mutually exclusive: enabling either one automatically disables the other. Neither package patches the stock ROM. With both disabled the game is the authentic 4:3 recomp, verified byte-identical to the emulator reference.

Voxel 3D (experimental)

Open Mods in the launcher and enable Voxel 3D. This first-person experiment rotates the sampled side-scroller plane upright and moves the camera with Mario while looking along his live facing direction. Right faces forward along the course; turning Left smoothly reverses the camera 180 degrees, as it does for Samus in Metroid's first-person mode. Mario's own sprite is hidden from the first-person view; enemies and items remain camera-facing cards among the reconstructed blocks, pipes, flagpoles, and terrain.

First-person movement uses compact tank controls: Up advances in the direction the camera faces and Left/Right select the corresponding facing. Down makes small Mario backpedal without reversing the view; grounded tall Mario retains his native crouch. The right stick looks vertically; pushing it fully upward looks almost straight up and centers Mario's overhead column for lining up jumps into blocks. Releasing the stick returns the camera to level. Crouching lowers the camera to tall Mario's crouched eye level and standing raises it again. Small Mario and pipe-entry input retain their ordinary eye height. A, B, Start, and Select retain their original NES behavior.

The package saves camera pitch, yaw, roll, zoom, and sprite scale. During play, Numpad 8/2 adjusts pitch, 4/6 rotates yaw, 7/9 rolls the view, +/- changes zoom, and 1/3 changes sprite scale. Numpad 0 toggles Voxel 3D and Numpad 5 restores the package defaults. These live controls are intended for experimentation; the values selected in Mods remain the persistent defaults.

Voxel 3D is disabled by default, is mutually exclusive with Widescreen, and does not patch the stock ROM or alter save data.

Controls

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

Hotkeys

Key	Action
Hold Tab	Turbo (fast-forward)
Escape	Open the menu
F8	Save state
F9	Load state
Alt+Enter	Toggle fullscreen

Configure bindings in Controls; they are saved in config.ini. An online match continues while the menu is open and disables fast-forward and states.

ROM

Field	Value
Title	Super Mario Bros. (World)
CRC32	3337EC46
MD5	811b027eaf99c2def7b933c5208636de
SHA-1	ea343f4e445a9050d4b4fbac2c77d0693b1d0922

Building from Source

Windows prerequisites: Visual Studio 2022 with C++ tools and CMake 3.20+ (SDL2 is bundled). The Linux and macOS build scripts list their platform prerequisites. Python 3 with PyInstaller and Pillow is needed for the Smash 64 owner-ROM cache helper and is required when packaging Windows/Linux releases.

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

# Windows
setup.bat

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

This initializes the pinned engine and launcher submodules and links the Nestopia oracle core. The optional smb-disassembly reference submodule is only needed for reverse engineering; initialize it with git submodule update --init smb-disassembly.

Then build on Windows:

cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DNESRECOMP_ROM="C:/Games/Super Mario Bros. (USA).nes"
cmake --build build --config Release

On Linux, run bash tools/build-linux.sh --no-package; on macOS, run bash tools/build-macos.sh --no-dmg.

The cycle build generates C in its build directory from your ROM and game-cycle.toml. It also recognizes baserom.nes and the canonical USA/World filenames in the repository root. The ROM is still required at runtime. build_all.bat invokes tools/build.ps1, which builds the compiler, game and owner-ROM helpers. Legacy-generated C remains committed for explicit legacy builds. Windows release packaging uses tools/make_release.ps1.

Repository layout

This is a static recompiler, not an emulator. The 6502 machine code in the ROM has been translated to C by NESRecomp and compiled to native x64.

Path	Purpose
src/	Handwritten game integration; start with extras.c
mods/	Character controllers, plugin entry points, and bundled package manifests
generated/	Committed recompiled 6502 code and dispatch table
game.toml, symbols.sym	Recompiler configuration and named ROM/RAM symbols
tests/	Controller harnesses, runtime probes, and regression baselines
tools/	Build, packaging, debugging, and owner-ROM asset tools
docs/	Technical guides, screenshots, and archived development notes
nesrecomp/, recomp-ui/	Pinned engine and launcher dependencies
smb-disassembly/	Optional upstream disassembly reference
ghidra/	Local analysis policy; database files are ignored

Report bugs through GitHub Issues. The notes under docs/archive/ preserve earlier investigations and are not a current issue tracker.

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>