Megaman3NESRecomp

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 Mega Man 3 (NES) for native PC. Built with the NESRecomp framework.

Status: Work in progress. Title screen, robot master select, and basic stage gameplay are functional. Boss fights, passwords, and special weapons are untested and may softlock. Visual gaps are expected. If you find a bug, please open an issue.

Cycle backend migration branch

Default cycle controls: arrows move, Z is A, X is B, Enter is Start and Backslash is Select. Escape opens the menu, Tab fast-forwards, and F8/F9 save/load the cycle state. Use Controls to remap inputs in config.ini. Older keybinds.ini and F5/F6/F7 instructions below apply to the legacy host.

The cycle build enables Reduce slowdown in the in-game menu. It gives the ROM additional CPU time between the visible picture and its frame interrupt; the display and audio retain their normal rate. Turn it off for original NES timing. The choice persists as [Game] ReduceSlowdown and in cycle save states. Headless checks can select --extra-scanlines 0 (stock) or 128 (enhanced).

The owner's enemy-heavy stage repro completed 503 updates in 600 display frames at stock timing, versus 600 with this enhancement. Native/interpreted enhanced runs and save-state continuation matched; the stock setting matched the previous cycle build exactly. This is a short repro result, not a full-game guarantee.

The normal build now uses the cycle CPU backend. Code is generated from the original ROM during configure and stays in the build directory. Run setup.bat or setup.sh to initialize the pinned engine/UI submodules, then configure:

cmake -S . -B build-cycle -DNESRECOMP_ROM="/path/to/Game.nes"
cmake --build build-cycle --config Release --parallel 4

Run the executable with that same ROM path. The launcher verifies the image; the runtime also verifies cartridge metadata and PRG identity. NESRECOMP_ROOT and NESRECOMP_RECOMP_UI can name other checkouts, and cross builds accept NESRECOMP_HOST_COMPILER pointing to a runnable host compiler.

Keep the old generated sources and select them explicitly with -DNESRECOMP_BACKEND=legacy in a separate build directory. Legacy save states cannot be loaded by the cycle backend; its cartridge shortcut slot uses saves/<ROM stem>.cycstate. Preserve existing saves and settings during rollout. Cycle-native comparisons use nesrecomp/tools/cyc/cyc_verify.py; --interp-only runs the cycle interpreter for diagnosis. Earlier --verify / --emulated Nestopia entry points remain in the legacy build.

The owner accepted the short Windows playtest on 2026-10-04. These remain branch previews; no merge or release has been performed. Desktop Windows checks cover a short gameplay route and runtime menu/input/save-state behavior; other platforms and full-game completion have not been validated by this migration.

What Works

• Title screen
• Main menu (GAME START / PASS WORD selection)
• Robot master stage select screen and navigation
• Loading into stages with background scrolling and basic enemies
• Player movement, jumping, and the Mega Buster

Known Limitations

• Boss fights are untested and likely to stall or softlock
• Special weapons are untested
• Passwords are untested
• Visual elements may have minor glitches or missing sprites in some areas
• Audio is basic (APU register writes are captured but full audio mixing is work-in-progress)

Quick Start

1. Download the latest release from Releases
2. Extract and run MegaMan3Recomp.exe
3. Select your Mega Man 3 (USA) ROM when prompted — the path is saved for future launches

Controls

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

Hotkey	Action
F5	Toggle turbo (fast-forward)
F6	Save state
F7	Load state

Building from Source

Requires Visual Studio 2022 and CMake 3.20+.

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

# Windows
setup.bat

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

This initializes the pinned nesrecomp submodule and links the Nestopia oracle core.

Then build:

cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

Place your Mega Man 3 (USA) ROM in the build directory or select it at runtime.

Architecture

This is a static recompiler, not an emulator. The original 6502 machine code is translated to C at build time, then compiled to native x64. The NES PPU, APU, and mapper are simulated by the runner library.

• Mapper: MMC3 (Mapper 4) with PRG/CHR bank switching and scanline IRQ
• Framework: nesrecomp — shared across multiple NES recomp projects
• game.toml — recompiler configuration (dispatch tables, extra functions, data regions)
• extras.c — game-specific hooks (coroutine scheduler, TCP debug interface)
• generated/ — auto-generated C code (do not edit manually)
• nesrecomp/ — framework submodule (recompiler + runner)

License

For this project's code covered by the PolyForm Noncommercial License, PERMISSIONS.md grants standing permission for voluntary donations, sponsorships, and advertising revenue, including support for broader development initiatives. Payment must not buy access to the software, games built with it, or their updates, features, or game content, including early access.

Matthew Stanley has authority from the relevant copyright holders to grant these permissions for the project's PolyForm-covered code. Third-party components and code explicitly licensed under other terms retain those terms.

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

---

Cycle Windows builds use tools/build.ps1 -Rom <original-ROM>. Create a ROM-free ZIP with tools/make_release.ps1 -Rom <original-ROM>; -SkipBuild -BuildDir build-cycle packages an existing production cycle build. Legacy C remains available through explicit CMake selection.