MegaManXSNESRecomp

Version 1.6.6 fixes Ctrl+R (Reset) leaving a black screen and lets you reopen the launcher mid-game with Ctrl+L (or Select+L3 on a controller), change settings, and resume from the same moment.

Version 1.6.5 saves launcher settings on close and uses shared SNES shader presets and pixel-aspect geometry. Bundled shader choices also survive AppImage relaunches and moving the installation.

Version 1.6.3 fixes widescreen sprite layering on Boomer Kuwanger's tower and the corrupted electric effect around X after Zero's explosion in Sigma 1.

Version 1.6.2 makes adaptive and fixed widescreen respect Display Aspect. Choose 8:7 (Square pixels) with Fit to screen to fill a wide window while keeping sprites at square-pixel proportions.

Version 1.6.0 adds optional Password Saves (SRAM): remember the last password shown by the game and prefill it when selecting Password on a later launch. Enable the mod and optionally choose a save file from the launcher's Mods page.

Version 1.5.0 replaces the original 16:9 renderer with adaptive widescreen, including fixed 16:9, 21:9 and 32:9 options and HUD anchoring. The renderer has passed a complete Windows playthrough; its implementation and playtest notes record the fixes and validation.

Static recompilation of Mega Man X (SNES) into native C, using the snesrecomp framework. This repo is the per-game side: the runtime, the recompiled C output, the per-game .cfg, and the build glue.

What "static recompilation" means here

The 65816 CPU code from the ROM is statically translated to C — every function the analysis can prove is a real generated C function in src/gen/. Execution is LLE-first: an authoritative 65816 interpreter (LakeSnes-derived, MIT) is the correctness floor, and the statically compiled bodies are exact, proven materializations on top of it — anything the static pass cannot prove keeps running through the interpreter, loudly. The rest of the SNES is not recompiled — it's hardware. PPU rendering, the APU/SPC700 audio coprocessor, DMA and HDMA channels, hardware register I/O, and bank-mapping run through snesrecomp's own runner implementations (snesrecomp/runner/). Same model as N64Recomp and similar projects: recompile the CPU, emulate the silicon.

The ROM is never redistributed — you supply your own legally-dumped copy.

Current status: fully playable

The game has been tested and is playable end to end on Windows, with macOS and Linux builds supported from source. See Releases for the latest packaged version and ISSUES.md for the current known-issue ledger.

The USA Rev 1 build now also includes an adaptive widescreen Mod, rendering additional gameplay at the sides instead of stretching the original image. It is disabled by default and enabled from the launcher's Mods page. See Adaptive widescreen support for availability and controls.

Linux / Steam Deck validation

Tester littlerobotfairy completed the game on Linux running on Steam Deck (on the contributed widescreen fork build). The complete playthrough is documented in the Twitch VOD.

If you hit a reproducible lockup or visual regression, please open an issue with a savestate (Shift+F1) and the frame at which it manifested.

Quick start (pre-built release)

1. Download the latest release zip from Releases and extract it.
2. Run MegaManXSNESRecomp.exe. On first launch a file picker asks for your legally-obtained Mega Man X (USA) (Rev 1) ROM (.sfc / .smc). The expected SHA-256 is b8f70a6e7fb93819f79693578887e2c11e196bdf1ac6ddc7cb924b1ad0be2d32 (1.5 MiB, LoROM). 512-byte SMC copier headers are auto-stripped before hashing, so headered or unheadered both work.
3. Edit keybinds.ini (auto-generated next to the exe on first run) to remap keys, then restart.

The path you pick is cached to rom.cfg next to the exe so subsequent launches skip the picker.

Password saves

Version 1.6.0 includes an optional Password Saves (SRAM) mod. It saves the last generated password to a PC file and prefills the title screen's Password option. See Password saves for the optional file picker and default save location.

Controls (default keybinds.ini)

SNES button	Default key
D-Pad	Arrow keys
A	X
B	Z
X	S
Y	A
L	C
R	V
Start	Enter
Select	Right Shift

Player 2 is unbound by default — fill in keys in keybinds.ini to enable a second keyboard player.

Xbox / PlayStation / Switch Pro controllers are auto-detected via SDL_GameController (XInput on Windows). Plug it in before launching, or hot-plug after.

System shortcuts (all rebindable in config.ini's [KeyMap] section; set a key to an empty value there to unbind it, e.g. DisplayPerf =):

Action	Default
Save state 1-10	Shift+F1..F10
Load state 1-10	F1..F6, F11, F12, F9, F10
Save-state browser	F7
Rewind filmstrip	F8
Toggle pause	P
Pause (dimmed)	Shift+P
Reset	Ctrl+R
Toggle fullscreen	Alt+Enter
Turbo (fast-forward)	Tab
FPS / perf readout	F
Toggle PPU renderer	R
Volume up / down	Keypad + / Keypad -

F7 opens the shared save browser; F8 opens the rewind history. Both pause the game and audio while you choose. Rebind or clear these keys in the launcher's Hotkeys settings or in [KeyMap]. Existing default F7/F8 slot loads migrate to F11/F12. The launcher also exposes controller bindings.

States include the CPU/interpreter timeline and X1's widescreen spawn/CHR bookkeeping. Use new states with the same game variant and runtime build; older states remain readable with their original format's limitations.

Reporting crashes

The game continuously records its own boot/run diagnostics. If it crashes (or exits with an error), it writes these files next to MegaManXSNESRecomp.exe — attaching them to a GitHub issue usually lets the crash be diagnosed without a repro:

• crash_report_<timestamp>.json and crash_minidump_<timestamp>.dmp — written at the moment of a crash; never overwritten by later runs.
• last_run_report.json — written at the end of every run (crash or clean exit), so grab it right after the bad run if there is no crash_report_* file.

None of these contain personal data beyond your Windows version, hardware model, and the folder path the game runs from.

Building from source

Clone with all framework dependencies, then run the idempotent bootstrap check:

git clone --recurse-submodules https://github.com/mstan/MegaManXSNESRecomp.git
cd MegaManXSNESRecomp
bash tools/bootstrap.sh

The snesrecomp/ directory is a pinned submodule from mstan/snesrecomp, and recomp-ui/ is the shared launcher UI submodule. If you cloned without --recurse-submodules, tools/bootstrap.sh initializes them and their nested dependencies. The gitlink in this repository is the dependency pin; there is no separate SHA to keep synchronized.

Generated game C is not redistributed. Before the first build, stage a legally obtained USA Rev 1 ROM as mmx.sfc, then run:

cp "/path/to/Mega Man X (USA Rev 1).sfc" mmx.sfc
bash tools/regen.sh usa --no-tests

On Windows 10 or newer, install MSYS2 with the mingw64 toolchain (cmake, ninja), the SDL3 development package, Git, Python 3.9 or newer, and rustup. Run the bootstrap and regeneration steps from Git Bash, then:

cmake -S . -B build-recompui -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH=/path/to/SDL3/x86_64-w64-mingw32
cmake --build build-recompui
# or, packaged: SDL3_MINGW_ROOT=/path/to/SDL3 bash tools/build-windows-mingw.sh VERSION

SDL3 is the default. SDL2 remains an explicitly supported fallback: configure a separate tree with -DSNESRECOMP_SDL_BACKEND=SDL2.

Windows releases use CMake/MinGW with the shared recomp-ui launcher (tools/make_release.ps1). CMake is the maintained build definition on every platform. Visual Studio users can open the repository as a CMake project or configure with the Visual Studio generator and an MSVC-compatible SDL package. The former manually maintained solution and source list have been retired.

macOS / Linux (CMake)

Builds natively on macOS (Apple Silicon + Intel) and Linux with clang/gcc. On macOS, install dependencies with brew install cmake sdl3 ninja python3. On Ubuntu/Debian, install build-essential cmake ninja-build libsdl3-dev libgl1-mesa-dev python3.

cmake -S . -B build-dev -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build-dev --target MegaManXSNESRecomp
ctest --test-dir build-dev --output-on-failure

On macOS, add -DCMAKE_PREFIX_PATH="$(brew --prefix)" if CMake does not find Homebrew's SDL3. Apple Silicon contributors running an x86_64-translated shell must also configure with -DCMAKE_OSX_ARCHITECTURES=arm64. Packaging helpers detect the native hardware architecture and are documented by bash tools/build-macos.sh --help and bash tools/build-linux.sh --help. The cross-platform Windows release can be built with MinGW using SDL3_MINGW_ROOT=/path/to/SDL3 bash tools/build-windows-mingw.sh VERSION. All release packages are ROM-free; place your legally obtained ROM beside the executable or AppImage after extraction. CI compiles both launcher/setup hosts without ROM-derived sources using -DSNESRECOMP_SETUP_HOST=ON, plus the display geometry and widescreen policy checks. A setup host cannot run the game until its generated sources are built. For the focused real-ROM state check, add -DMMX_STATE_TESTS=ON, build mmx_state_tests, then run:

python snesrecomp/runner/tests/run_mmx_state_tests.py \
  --exe build-dev/mmx_state_tests --rom mmx.sfc

See CONTRIBUTING.md for dependency development, validation, and pull-request guidance.

macOS builds use the same SDL3 + CMake path as Linux. A native macOS backend (Metal presentation, GameController.framework, Core Audio output) and an optional in-game display menu were contributed in PR #10 and are staged on per-feature branches; they land after the shared launcher-UI restructure settles.

Adaptive widescreen support

Version 1.4.4 replaces the old fixed 16:9 renderer with the adaptive renderer, playtested through the ending on Windows. Enable Widescreen (Extended view) on the launcher's Mods page. It is disabled by default; existing enabled widescreen installations automatically use the replacement.

Choose Adaptive to fit the window, or 16:9, 21:9, or 32:9 for a fixed view aspect. Settings → Display Aspect controls pixel and sprite proportions in every mode: 4:3 (CRT), 8:7 (Square pixels), or 1:1 (Square frame). For example, a 16:9 view with 8:7 selected shows more scenery with square pixels. Adaptive follows the window's shape while preserving the selected pixel proportions. The view is bounded by the native 256 pixels and the renderer's 1024-pixel capacity; outside those bounds it is boxed to preserve pixel shape. Health bars can anchor to the screen edges or retain their native positions. Menus and other native screens remain pillarboxed. Expanded sprite capacity is a separate experimental option and remains off by default.

The original stage camera, collision and encounter timing are preserved, with scoped fixes for objects exposed by the wider view. The former legacy renderer selector has been removed. Rockman X (Japan) continues to use its authentic view.

With the widescreen mod disabled, Display Aspect also determines the overall shape of the native frame. With it enabled, Mods → View aspect ratio chooses the view shape and Display Aspect continues to determine pixel shape. Released saves and adaptive-playtest saves remain loadable. F7/F8 open the shared save browser and rewind; the corresponding old slot loads are now F11/F12.

The S-DSP retains the SNES BRR predictor filters and canonical four-tap Gaussian interpolation. Host-rate conversion uses continuous interpolation instead of nearest-sample hold. The current SPC700 core is instruction-cycle stepped with canonical opcode timing; a sub-cycle bsnes-style SPC700 core is a separate emulator-core replacement and is not represented as complete here.

The supported packaged workflow is:

bash tools/build-macos.sh --rom "/path/to/your/rom.sfc" --regen --no-dmg

The script builds an arm64 .app by default; use --arch universal for an Intel/Apple Silicon package. The ROM is used only for local regeneration and is never copied into release output.

The recompiled C in src/gen/ is not committed — contributors must regenerate it from a local ROM before the first build. See the next section.

Regenerating the recompiled C (contributors)

1. Stage a legally-obtained USA Rev 1 ROM as mmx.sfc at the repo root (.gitignore excludes it), or pass it to tools/build-macos.sh --rom.
2. Run bash tools/regen.sh usa --no-tests (drives the recompiler over every recomp/bank*.cfg and writes src/gen/bankXX_v2.c + dispatch_v2.c). The script builds and requires the fast native analyzer by default; set SNESRECOMP_ANALYSIS_BACKEND=python only to use the slower reference path. On Windows without bash, invoke the underlying tool directly:

   python snesrecomp/tools/build_native_analyzer.py
   python snesrecomp/tools/v2_emit.py --rom mmx.sfc --cfg-dir recomp --out-dir src/gen --cfg-roots --analysis-backend native

3. Rebuild as above.

For Rockman X (Japan v1.1), stage rockmanx.sfc under variants/jp/roms/ and run bash tools/regen.sh jp --no-tests. The JP path uses its checked-in LLE coverage profile as optional AOT input; variants the compiler cannot prove remain on the authoritative interpreter fallback. bash tools/regen.sh all regenerates both regions.

Repo layout

Path	Purpose
src/	Runtime C (CPU state glue, NMI orchestration, hand-written bodies for things the framework doesn't recompile).
src/gen/	Recompiler output (gitignored; regenerated from ROM).
recomp/bank*.cfg	Per-bank function declarations + hardware hints the framework cannot derive from the ROM alone.
recomp/funcs.h	Auto-regenerated by tools/regen.sh; never hand-edit.
snesrecomp/	Pinned submodule containing the snesrecomp framework.
recomp-ui/	Pinned submodule containing the shared, console-agnostic launcher UI.
third_party/	Remaining game dependencies and their licenses.
CMakeLists.txt	Shared framework build helpers and USA/JP targets.
config.ini	The config. Generated next to the exe on first run if missing.

License

PolyForm Noncommercial 1.0.0. See LICENSE. Code in this repo is original; vendored dependencies under third_party/ retain their own licenses.

The Mega Man X ROM and any data extracted from it are not in this repo and are not licensed for redistribution.

---

_{R.A.I.D. — Retro AI Development · a Discord for AI-assisted retro reverse-engineering, decomp & recomp}