Development reference status and credit: The authoritative Star Fox (SNES) PC port project is kandowontu's starfox-enhanced, a decomp project and the reference implementation for the custom renderer behavior adapted here. This StarFoxSNESRecomp repository is for development reference purposes and is not intended to be a production release. Users seeking the full Star Fox experience should use starfox-enhanced. I am grateful for kandowontu's work and credit that project for the reference implementation behind this repo's opt-in native widescreen renderer and presentation frame-rate modes.

StarFoxSNESRecomp

Static recompilation of Star Fox (SNES) into native C, using the snesrecomp framework. This repository contains the per-game runtime, recompilation configuration, hardware glue, and build files. The ROM and ROM-derived generated code are never distributed.

What "static recompilation" means here

The SNES 65C816 program can run as ahead-of-time compiled native code while the shared snesrecomp runtime models the console hardware. Star Fox also uses the Super FX/GSU coprocessor extensively. Its low-level execution and architectural state remain authoritative; compiled paths may optimize that behavior but must not replace or diverge from it.

Current status: development reference preview

The game boots and its attract sequence, menus, route selection, training, and gameplay have passed basic interactive testing. The project includes an opt-in separate native renderer adapted from kandowontu's Star Fox Enhanced decomp for widened presentation, with fixed 16:10, 16:9, 21:9, and 32:9 presets. Authentic 4:3 output remains available when the Enhanced Widescreen mod is disabled and does not use the Enhanced renderer.

The adaptive presenter keeps gameplay and the hangar wide while centering menus, controls and briefings. Current-frame fades and retail HUD state address the observed boot-to-Corneria transition artifacts and bottom-edge stripes. Longer play sessions, additional routes, complete particle/effect parity, save-state behavior, and non-Windows builds still need more coverage. Please report reproducible visual, audio, timing, or stability problems through GitHub Issues.

Quick start (Windows release)

The source build also offers an opt-in Star Fox 64 Arwing with wing damage, glow, roll shield, green/blue lasers and ship audio, extracted locally from your own SF64 US v1.1 ROM. The wings start fully expanded, and the controls-screen ship preview also uses the SF64 model. Automated gameplay-state comparisons pass, and the owner approved the visual playtest on September 5, 2026. See Arwing64 setup and validation. Asset/audio semantics are informed by sonicdcer/sf64 (CC0), with Torch (MIT) as a development oracle, on the Star Fox Enhanced presentation foundation credited above.

See the Arwing64 gameplay gallery for hangar launch, flight and combat captures from the current build.

Actual gameplay and owner-provided controls-preview captures; the ROMs and extracted models, textures and audio are not included. See adaptive widescreen behavior for the presentation rules and current validation limits.

1. Download StarFoxSNESRecomp-windows-x64-v0.3.0.zip from Releases and extract it into a fresh folder.
2. Run StarFoxSNESRecomp.exe.
3. In the launcher, choose your legally obtained Star Fox (USA), version 1.2 ROM. The launcher verifies the ROM before enabling play.
4. Review graphics and controller settings, then select Play.

The launcher remembers the ROM path. Enable Skip Launcher on Boot for direct startup; pass --launcher to show it again.

Required ROM

Supply your own legally obtained, unheadered 1 MiB dump of Star Fox (USA), version 1.2. The required hashes are:

• CRC32: 8FC4E6D0
• MD5: DEF66DB12F5E644C0CF00C42CFA7AE7B
• SHA-256: 82E39DFBB3E4FE5C28044E80878392070C618B298DD5A267E5EA53C8F72CC548

The runtime verifies the SHA-256 before starting and caches the selected path in rom.cfg. ROM files, extracted data, and generated recompilation output are excluded from Git.

Controls

Default keyboard controls are written to keybinds.ini beside the executable on first launch.

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

SDL game controllers are detected automatically. System shortcuts are defined in config.ini:

Action	Default
Save-state browser	F7 / Select+R
Rewind filmstrip	F8 / Select+L
Save state 1-10 directly	Shift+F1..F10
Load states 1-6, 7-8, 9-10 directly	F1..F6, F11..F12, F9..F10
Toggle pause	P
Pause (dimmed)	Shift+P
Reset	Ctrl+R
Toggle fullscreen	Alt+Enter
Turbo / fast-forward	Tab
FPS / performance readout	F
Toggle PPU renderer	R
Presentation debugger	Ctrl+F5
Presentation step forward	Ctrl+F6
Presentation step back	Ctrl+F7
Window size	Ctrl+Up / Ctrl+Down
Volume	Shift+= / Shift+-

In recomp-ui, open Settings > Controls > Hotkeys to rebind or clear Save States and Rewind, using the same editor and F7/F8 defaults as PSXRecomp. The corresponding config.ini [KeyMap] keys are SaveStateMenu and Rewind; modifiers and comma-separated alternatives are supported. An empty value, None, or (unbound) disables an action. Existing configs with the old slot 7/8 load defaults automatically use F11/F12 instead.

The save browser has 12 slots with thumbnails. Use Up/Down to choose a slot, SNES X (keyboard S) to save, A (keyboard X) to load, and B (keyboard Z) or Escape to close. In rewind, use Left/Right to select a frame, A to resume there, or B/Escape to cancel. These menus pause guest execution and audio; closing buttons are held back from the game until released. A file load or reset starts a new rewind timeline.

Save states now include the CPU, title scheduler and Super FX execution state. Older Star Fox states lack that data and are rejected; create fresh saves with this build. The runtime uses snesrecomp's shared snapshot and rewind modules. Star Fox remains single-player and does not expose a netplay menu.

Widescreen

Widescreen output is an opt-in separate native renderer adapted from DisplayMode and renderer work in kandowontu's starfox-enhanced decomp. Credit for the widescreen renderer design and reference implementation belongs to the Star Fox Enhanced author and project; this repo integrates that model with the retail Star Fox recomp runtime.

In the launcher, open Mods, enable Enhanced Widescreen, and choose one of the fixed aspect presets:

• 16:10
• 16:9
• 21:9
• 32:9

This separate 21:9 capture uses the original SNES ship with Arwing64 disabled. The native renderer expands the world and positions the HUD at the outer edges; the ground dots are visible across the wider view.

Disabling Enhanced Widescreen returns to Authentic 4:3. DisplayMode, Widescreen, and EnhancedRenderer remain accepted as configuration keys for developer validation, including integer extra pixels per side, but Star Fox stock rendering remains 4:3. Wider output is only used by the Enhanced native renderer path.

See docs/TRUE_WIDESCREEN.md for the rendering model, validation notes, and the remaining spawn/culling audit.

Presentation adapts within the selected width: gameplay uses the wider scene, while menus and other original screens stay centered.

Enhanced-Derived Mods

Set CrosshairColor in config.ini to Original, White, Green, Blue, Red, Yellow, Cyan, Magenta, or Orange. Original preserves the retail palette; the other options apply a presentation-only tint to the OBJ crosshair palette during frame rendering and restore emulated CGRAM before the next simulation step. The same setting also redirects the Super FX cockpit HUD triangle color through the bright crosshair palette entry for the current simulation frame, then restores M_HUDCOLOUR.

The [Features] section also exposes GodMode and GodNuke. GodMode = 1 reasserts the Enhanced-derived no-collision flag and keeps Nova Bombs at a floor of three during active gameplay. With GodNuke = 1, hold R while firing a Nova Bomb with A to arm the newly created nuke for the Enhanced-style screen clear, including the protected boss-shape exceptions from the reference decomp.

Set ShowFPS = 1 in [General] to start with the live on-screen FPS readout enabled. Like Enhanced, it reports completed presentations in short samples. The F hotkey still toggles it at runtime.

Set PresentationFPS to 20, 30, 60, 90, 120, 240, 360, or 480 to choose the host presentation cadence. These modes keep SNES simulation cadence unchanged. Rates below 60 skip presentation draws; rates above 60 duplicate the newest completed presentation with vsync disabled. At 120 FPS, simulation and rendering run between evenly spaced display slots, with the retained picture displayed halfway between new pictures. Absolute deadlines prevent rendering time from bunching both presentations together. Software rendering and rewind capture use CPU memory before uploading the finished picture to the display texture. Enhanced-mode native shape poses use presentation interpolation to reduce object jitter, adapted from the Star Fox Enhanced reference behavior.

Building from source

Prerequisites are CMake 3.20+, Ninja or another CMake-supported build system, a C11/C++20 compiler, Python 3.9+, rustup, SDL3, and OpenGL development files. SDL2 is supported with -DSNESRECOMP_SDL_BACKEND=SDL2.

git clone --recurse-submodules https://github.com/mstan/StarFoxSNESRecomp
cd StarFoxSNESRecomp

If you cloned without --recurse-submodules, initialize the pinned framework, launcher, and reference sources before building:

git submodule update --init --recursive

For bounded validation runs, pass --frames N after any --script or --framedump arguments. This exits cleanly after N simulated frames and keeps launcher UI disabled for automated captures.

Place the verified ROM at starfox.sfc, generate the local recompilation output, and build:

bash tools/regen.sh
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/StarFoxSNESRecomp

Regeneration builds and requires the fast native analyzer by default. Set SNESRECOMP_ANALYSIS_BACKEND=python only to use the slower reference path.

src/gen/ is generated locally from the user's ROM and must never be committed. The exact framework revision expected by this project is recorded by the snesrecomp gitlink.

For framework development, use -DSNESRECOMP_ROOT=/path/to/snesrecomp and optionally -DRECOMP_UI_ROOT=/path/to/recomp-ui. Pass the same framework path to regeneration with SNESRECOMP_ROOT=/path/to/snesrecomp bash tools/regen.sh. The default build uses the pinned submodules without local links or junctions.

The build follows snesrecomp's tools/new_project/templates/CMakeLists.txt.in, using Gundam Wing: Endless Duel as the reference consumer. Shared CMake helpers own the runtime source list, SDL selection, launcher assets, GLSL shaders, fiber compatibility, and crash reports. Star Fox retains its custom host, configuration, Super FX integration, Enhanced renderer, and Arwing64 tool. Release configurations use VERSION; other configurations use dev. -DSNESRECOMP_BUILD_VERSION=<version> overrides either default.

The manual Build workflow in .github/workflows/release.yml follows the new-project CI template. It records the checked-out pins, compiles the Linux SDL2 host and dependencies, and runs the framework and Star Fox ROM-free tests. It does not publish a release or validate ROM-derived code or gameplay. Run its compilation check locally with:

cmake -S . -B build-ci -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DSTARFOX_HOST_CHECK_ONLY=ON -DSNESRECOMP_SDL_BACKEND=SDL2
cmake --build build-ci --parallel 2

This explicit CI mode excludes generated code even when it is present locally and produces a host-check static archive, not a playable executable. Normal builds still require verified ROM-derived output in src/gen/.

The menu integration was compared with a separately generated Star Fox reference project. The current scaffold includes the shared modules but its minimal host does not connect their menu input and presentation; this title's host supplies that bridge. The framework pin includes the beam-progress fix needed for Star Fox to boot and the complete Super FX save-state format.

To check actual ROM execution, add -DSTARFOX_STATE_TESTS=ON to a normal build, then run:

python tests/run_state_tests.py build/starfox_state_tests starfox.sfc
# Windows: use build/starfox_state_tests.exe

The harness uses temporary save files, checks recomp-ui binding persistence, compares complete snapshots after deterministic replay, and tests menu save, load, rewind cancellation/commit and restoration in a fresh process.

Repository layout

Path	Purpose
src/	Game runtime, Super FX integration, configuration, and CPU/PPU glue.
src/gen/	ROM-derived recompiler output; generated locally and ignored.
recomp/	Per-bank recompilation declarations and function metadata.
docs/	Reference-source provenance and development documentation.
snesrecomp/	Pinned shared framework submodule.
recomp-ui/	Pinned shared launcher submodule.
third_party/	Vendored dependencies retaining their own licenses.
third_party/starfox-enhanced/	Pinned reference-only decomp used for comparison and symbol provenance.
config.ini	Runtime graphics, audio, controller, and hotkey settings.
recomp/launcher/	Star Fox launcher theme and North American cover thumbnail.
tools/make_release.ps1	Packages a completed MinGW release build and its runtime DLLs.

Reference material

Addresses and annotations are checked against the exact-version StarFoxDisassembly reference. See docs/REFERENCE_SOURCES.md for its pinned commit and usage constraints.

Star Fox Enhanced is pinned as a reference-only decomp submodule for symbol inventory, architecture comparison, and portable mod research. See docs/STARFOX_ENHANCED_COMPARISON.md for the current comparison notes and transfer candidates.

License

PolyForm Noncommercial 1.0.0. See LICENSE. Vendored dependencies retain their own licenses. The Star Fox ROM and all data extracted from it are not part of this repository and are not licensed for redistribution.

---

<p align="center"> _{<b>R.A.I.D. — Retro AI Development</b> · a Discord for AI-assisted retro reverse-engineering, decomp &amp; recomp}<br> <a href="https://discord.gg/Ad9BwSzctP">Join the R.A.I.D. community</a> </p>

Coverage survey and regeneration

Game-owned generation policy is in recomp/generate.toml; the shared framework runs the same hooks for tools/regen.sh and launcher rebuilds. See the 2026-10-18 coverage survey for verified ROM identity, observed scenes, corrections, and remaining validation limits.