# FaxanaduRecomp
> _This recompilation is a **byproduct of developing
> [nesrecomp](https://github.com/mstan/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 »](https://1379.tech/recomp-ai-5-months-later/)_
Static recompilation of Faxanadu (NES) for native PC.
Built with the [NESRecomp](https://github.com/mstan/nesrecomp) framework.
> **Status: Playable.** The game runs from title screen through credits. No outstanding known bugs. Not 100% playtested — minor edge cases may exist, but normal gameplay is fully functional.
[](https://www.youtube.com/watch?v=lLXSnK3HVW4)
## Default cycle controls
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.
## Quick Start
1. Download `FaxanaduRecomp-windows-x64.zip` from [Releases](../../releases)
2. Extract and run `FaxanaduRecomp.exe`
3. Select your Faxanadu (USA) ROM when prompted — the path is saved for future launches
Optional **Play as Link** is available in Mods. Select your Zelda II USA ROM,
enable the mod, and launch Faxanadu with Link's movement, sword beams, vertical
stabs and all eight spells. See [controls and details](docs/LINK_MOD.md).
Optional **Seamless** appears first in Mods, marked **Experimental** and
disabled by default. It joins connected rooms, advances neighboring actors,
and adapts the world view to your window with Fit to screen. Mouse wheel
changes pixel zoom; F4 shows the connected map. Dialogue and pause preserve
the expanded view. It passed a preliminary owner playtest; broader gameplay
coverage and cross-room combat/projectiles remain incomplete. Seamless and
Play as Link are separate local-play modes. See [details](docs/SEAMLESS-WORLD.md).
## Controls
| NES Button | Keyboard |
|------------|----------|
| D-Pad | Arrow keys |
| A | Z |
| B | X |
| Start | Enter |
| Select | Right Shift |
## Mantra (Password) Features
Faxanadu uses a mantra system instead of battery-backed saves. FaxanaduRecomp adds convenience features around this:
**Auto-load** — On startup, the game reads `saves.txt` (next to the exe) and auto-fills the most recent mantra on the password entry screen. No need to write down or retype passwords.
**CLI override** — `--password STRING` overrides the `saves.txt` mantra for a single session.
```
FaxanaduRecomp.exe [ROM] --password "k8fPcv?,TwSYzGZQhMIQhCEA"
```
**saves.txt format** — One mantra per line, most recent first. Human-readable and copy-pasteable. You can edit this file manually to add or change your saved mantra.
> **Note:** Auto-saving mantras from the priest dialog is not yet implemented. For now, write the mantra shown by the priest into `saves.txt` manually, or pass it via `--password`.
## Save States
| Key | Action |
|-----|--------|
| F5 | Toggle turbo (fast-forward) |
| F6 | Save state → `C:\temp\quicksave.sav` |
| F7 | Load state ← `C:\temp\quicksave.sav` |
## ROM
| Field | Value |
|-------|-------|
| Title | Faxanadu (USA) |
| CRC32 | `57DD23D1` (ROM data only, iNES header excluded) |
| MD5 | `b3bb9296b5e1e0c83e90b6da9e8a41aa` (ROM data only) |
| SHA-1 | `5b05c8859f356013d37f0545f5de5fa1693da5da` (ROM data only) |
## Building from Source
Prerequisites: Windows 10+, Visual Studio 2022, CMake 3.20+ (SDL2 is bundled)
```bash
git clone https://github.com/mstan/FaxanaduRecomp
cd FaxanaduRecomp
# Windows
setup.bat
# Linux / macOS
chmod +x setup.sh && ./setup.sh
```
This initializes the pinned [nesrecomp](https://github.com/mstan/nesrecomp)
submodule and links the Nestopia oracle core.
Then build:
```bash
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
```
## Architecture
This is a **static recompiler**, not an emulator. The 6502 machine code in the ROM
has been translated to C by [NESRecomp](nesrecomp/) and compiled to native x64.
| File | Purpose |
|------|---------|
| `extras.c` | Faxanadu-specific hooks (mantra injection, auto-load) |
| `game.cfg` | Recompiler config (dispatch tables, trampolines) |
| `baserom_annotations.csv` | Address annotations for generated code |
| `generated/faxanadu_full.c` | Recompiled 6502 code (committed) |
| `generated/faxanadu_dispatch.c` | Dispatch table (committed) |
| `reference/` | Reference screenshots for visual regression |
## License
For this project's code covered by the [PolyForm Noncommercial License](LICENSE),
[PERMISSIONS.md](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`](LICENSE). Third-party
components retain their own licenses.
---
R.A.I.D. — Retro AI Development · a Discord for AI-assisted retro reverse-engineering, decomp & recomp
Cycle Windows builds use `tools/build.ps1 -Rom `. Create a ROM-free
ZIP with `tools/make_release.ps1 -Rom `; `-SkipBuild -BuildDir
build-cycle` packages an existing production cycle build. Legacy C remains
available through explicit CMake selection.
The October 2026 USA coverage pass exercises original entries for all six
outside regions and encounters all eight real boss species, including King
Grieve and Shadow Eura. Authored screen and sprite metadata were bound by
reproducing both complete 16 KiB data banks against the supplied USA ROM.
The probes assist screen selection, player health and entrance position;
original screen initialization, actors and combat routines still run.
These are encounter checks, with some routes ending in player death.
All eight boss routes match native/interpreter machine hashes, pictures and
complete states. After adding 958 observed ROM instruction starts, all eight
routes and the earlier six region routes replay exactly against their
pre-rebuild native and interpreter results on engine `0498965`. Earlier
intro/region coverage added 1,103 valid starts. Item collection, mantra
interactions and the ending require separate qualification. Areas 3 and 4
are the towns/buildings profiles; dungeon screens belong to the surrounding
regions. This build uses stock rendering.