# EarthBoundRecomp

A native port of **EarthBound (USA)** built by static recompilation, using the
[snesrecomp](https://github.com/mstan/snesrecomp) framework. Sibling project to
[SuperMetroidRecomp](https://github.com/mstan/SuperMetroidRecomp) — and the
framework's first HiROM game.

The port is **LLE-first**: initially the entire game executes through the
embedded 65816 interpreter tier against the real ROM, and proven-hot functions
are promoted to statically recompiled C over time. Only the CPU is recompiled;
PPU/APU/DMA run in the framework's hardware model.

**You must supply your own legally-dumped ROM.** This repository contains no
ROM data. Expected dump: EarthBound (USA), 3,145,728 bytes (headerless),
SHA-256 `a8fe2226728002786d68c27ddddf0b90a894db52e4dfe268fdf72a68cae5f02e`.

## Status

Early bring-up. Boots through the LLE interpreter tier to the title screen
and file-select menu. AOT coverage and disassembly symbol ingestion are the
next milestones.

| | |
|:---:|:---:|
| ![Intro: The War Against Giygas](docs/screenshots/03-intro.png) | ![Title screen](docs/screenshots/04-title.png) |
| ![File select](docs/screenshots/05-file-select.png) | ![HALKEN logo](docs/screenshots/02-halken.png) |

## Building

Prerequisites: cmake, ninja, a C compiler, Python 3, SDL3
(`brew install cmake ninja sdl3` on macOS).

```sh
git clone --recurse-submodules <this repo>
cd EarthBoundRecomp
cp /path/to/your/"EarthBound (USA).sfc" .

./tools/regen.sh                                  # generate src/gen/ from ROM + recomp/*.cfg
cmake -G Ninja -B build -S . -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=/opt/homebrew
cmake --build build -j 8

./build/EarthBoundRecomp "EarthBound (USA).sfc"
```

`-DSNESRECOMP_SDL_BACKEND=SDL2` selects the SDL2 fallback backend.

## Layout

| Path | Contents |
|---|---|
| `snesrecomp/` | framework submodule (recompiler, runner, SNES hardware model) |
| `recomp/` | per-bank recompiler directives (`bankXX.cfg`) + generated `funcs.h` |
| `src/` | hand-written host: `main.c`, frame model (`eb_rtl.c`), game registration |
| `src/gen/` | generated recompiled C (gitignored; produced by `tools/regen.sh`) |
| `refs/eb-disasm.pin` | pinned commit of the EarthBound disassembly used as symbol reference |
| `tools/` | regen pipeline |

## Credits

- **[Yoshifanatic](https://github.com/Yoshifanatic1)** — the
  [EarthBound-Disassembly](https://github.com/Yoshifanatic1/EarthBound-Disassembly),
  which this project uses as its symbol and reverse-engineering reference
  (interrupt vectors, label names, RAM map). The exact commit is pinned in
  `refs/eb-disasm.pin`.
- **[snesrecomp](https://github.com/mstan/snesrecomp)** — the SNES static
  recompilation framework this port is built on (recompiler, 65816
  interpreter tier, and the LakeSnes-derived hardware model).
- **EarthBound** is © 1994, 1995 Nintendo / Shigesato Itoi / Ape Inc. /
  HAL Laboratory. This project is an unofficial fan effort, contains no
  game assets, and requires your own legally-dumped ROM.