> **Development reference status and credit:** The authoritative Star Fox
> (SNES) PC port project is kandowontu's
> [starfox-enhanced](https://github.com/kandowontu/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](https://github.com/kandowontu/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](https://github.com/mstan/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](../../issues).

![StarFoxSNESRecomp Enhanced widescreen training mode](docs/images/starfox-enhanced-widescreen-training.png)

## 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](docs/ARWING64.md). 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.

![Star Fox 64 Arwing flying over Corneria with the restored ground dots](docs/images/starfox-arwing64-flight.png)

See the [Arwing64 gameplay gallery](docs/ARWING64.md#gameplay-gallery) for
hangar launch, flight and combat captures from the current build.

![Star Fox 64 Arwing with expanded wings in the SNES controls preview](docs/images/starfox-arwing64-controls.png)

Actual gameplay and owner-provided controls-preview captures; the ROMs and extracted models, textures and audio are
not included. See [adaptive widescreen behavior](docs/TRUE_WIDESCREEN.md) for
the presentation rules and current validation limits.

1. Download `StarFoxSNESRecomp-windows-x64-v0.3.0.zip` from
   [Releases](../../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](https://github.com/kandowontu/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`

![Enhanced 21:9 Corneria gameplay with the original SNES Arwing](docs/images/starfox-enhanced-21-9-corneria.png)

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](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`.

```bash
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:

```bash
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
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:

```bash
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:

```bash
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](https://github.com/SpyderTL/StarFoxDisassembly) reference.
See [docs/REFERENCE_SOURCES.md](docs/REFERENCE_SOURCES.md) for its pinned commit
and usage constraints.

[Star Fox Enhanced](https://github.com/kandowontu/starfox-enhanced) is pinned as
a reference-only decomp submodule for symbol inventory, architecture comparison, and
portable mod research. See
[docs/STARFOX_ENHANCED_COMPARISON.md](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">
  <sub><b>R.A.I.D. — Retro AI Development</b> · a Discord for AI-assisted retro reverse-engineering, decomp &amp; recomp</sub><br>
  <a href="https://discord.gg/Ad9BwSzctP">Join the R.A.I.D. community</a>
</p>