LLE-first recompilation of Super Metroid (SNES) into native C, using the
snesrecomp framework. This repo
is the per-game side: the single-fiber runtime, the per-game .cfg, the
build glue, and optional HLE optimizations. The recompiled C output
(src/gen/, ~93 MB) is generated locally and is not committed.
This is game #4 on snesrecomp, after Mega Man X, Super Mario World, and The Legend of Zelda: A Link to the Past.
The ROM and interpreter are the architectural ground truth. Proven hot 65816
functions may be statically translated to C, while every absent or rejected
exact M/X variant executes the original ROM through LLE. HLE is an optional
optimization over that model. 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 all run through
the embedded SNES emulation in snesrecomp/runner/src/snes/. Recompile
the CPU, emulate the silicon.
The default LLE scheduler executes the real WaitForNMI loop and resumes at
its architectural continuation. Optional HLE mode replaces that wait with a
host-fiber yield for performance.
The ROM is never redistributed — you supply your own legally-dumped copy.
The default LLE-first build boots, renders, plays audio, completes the attract demo, starts a new game, traverses doors, pauses, and saves at Samus's ship. It remains a work in progress and needs broader end-to-end regression testing.
Custom widescreen at the landing site, with energy and the minimap anchored to the outer edges:
Tourian gameplay with energy and reserves on the left, weapons centered, and the minimap on the right:
Screenshots supplied by the project owner from the custom-renderer build.
Download the Windows x64 ZIP or Linux x86_64 AppImage from this repository's
Releases page. Extract the entire Windows ZIP before launching the executable;
its DLLs and assets/ directory are required. On Linux, make the AppImage
executable and launch it. Supply your own unmodified Super Metroid (Japan, USA)
ROM; no ROM or saved progress is included in either package.
Open Mods in the launcher to enable Widescreen (Fit, 16:9, 21:9 or 32:9) and choose edge-anchored or centered HUD placement. Presentation FPS is a separate mod with Auto and fixed frame-rate targets. Both are off by default; turning both off uses stock rendering. Game logic retains its native timing. These features are experimental: full-game visual fidelity is not certified, and achievable FPS depends on hardware and the scene.
Settings and saves live beside the executable/AppImage. Keep that directory
writable, and preserve your settings and saves/ when updating. The detailed
implementation and validation record is in docs/custom-renderer.md.
Prerequisites: a snesrecomp checkout at ./snesrecomp (junction/symlink
to the sibling repo, pinned in snesrecomp.pin), a verified Super Metroid
ROM at the repo root, SDL3 + OpenGL, and the mingw64 toolchain (cmake,
gcc, ninja) on PATH. Regeneration also requires rustup; it builds and
requires the fast native analyzer by default. Set
SNESRECOMP_ANALYSIS_BACKEND=python only to use the slower reference path.
# 1. (once) clone the snesrev/sm decomp as the symbol/oracle reference
# (commit pinned in refs/snesrev-sm.pin), then ingest its symbols:
git clone --depth 1 https://github.com/snesrev/sm.git refs/snesrev-sm
python tools/ingest_sm_decomp.py # funcs -> recomp/*.cfg; tables -> recomp/sm_decomp_symbols.json
# 2. deterministic profile-scoped regeneration (no guest widescreen hooks). Strict mode
# independently regenerates and requires byte-identical output.
./tools/regen.sh --strict-idempotent
# 3. configure + build
cmake -G Ninja -B build -S . -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=gcc
cmake --build build -j 8
# 4. run (supply your own ROM)
./build/SuperMetroidSNESRecomp.exe "Super Metroid (Japan, USA) (En,Ja).sfc"| Path | What |
|---|---|
src/ |
hand-written runtime: sm_rtl.c (single-fiber frame driver), sm_cpu_infra.c, sm_spc_player.c, gen_stubs.c (HLE bodies), main.c, post_mortem.c |
src/gen/ |
generated recompiled C (not committed) |
recomp/ |
per-bank .cfg (function boundaries, HLE/dispatch directives) + generated funcs.h |
snesrecomp/ |
junction to the shared framework repo (tracked there; see snesrecomp.pin) |
tools/ |
per-game helpers |
R.A.I.D. — Retro AI Development · a Discord for AI-assisted retro reverse-engineering, decomp & recomp
PolyForm Noncommercial 1.0.0. See LICENSE. Code in this repo is original;
vendored dependencies under third_party/ retain their own licenses.
The game ROM and any data extracted from it are not in this repo and are not licensed for redistribution.