116 lines
4.7 KiB
Markdown
116 lines
4.7 KiB
Markdown
# Legend of Zelda: A Link to the Past Recomp
|
|
|
|
A native recompilation of **Legend of Zelda: A Link to the Past** (USA), built on
|
|
[snesrecomp](https://github.com/RetroPortingToolKit/snesrecomp).
|
|
|
|
_Add a short description here._
|
|
|
|
|
|
|
|
> **You must legally own a copy of the game.** No ROM data is distributed with
|
|
> this project, in the repository or in any release. The recompiled C is
|
|
> generated locally from your own copy and is never committed.
|
|
|
|
## Status
|
|
|
|
Scaffolded on 2026-10-30 — **not yet a working port.** The layout, build,
|
|
regeneration pipeline, CI, and packaging are wired up; the game does not run
|
|
until the host work in `src/game_rtl.c` is done. See
|
|
[Porting from here](#porting-from-here).
|
|
|
|
## ROM identity
|
|
|
|
| | |
|
|
|---|---|
|
|
| File | `Legend of Zelda, The - A Link to the Past (USA).sfc` |
|
|
| Publisher | — |
|
|
| Developer | — |
|
|
| Year | — |
|
|
| Mapping | lorom |
|
|
| Region | USA (North America) |
|
|
| Coprocessor | none |
|
|
| CRC32 | `777aac2f` |
|
|
| SHA-256 | `66871d66be19ad2c34c927d6b14cd8eb6fc3181965b6e517cb361f7316009cfb` |
|
|
|
|
`tools/regen.sh` refuses to run against anything else, so a mismatched
|
|
revision fails immediately instead of producing subtly wrong output.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
git submodule update --init --recursive
|
|
bash tools/regen.sh --rom /path/to/Legend of Zelda, The - A Link to the Past (USA).sfc
|
|
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
|
|
cmake --build build -j
|
|
```
|
|
|
|
The ROM does not have to live in the repository — keeping it on your own
|
|
drive is the better habit, and `SNESRECOMP_ROM` sets the path once for a
|
|
shell. Without either, `tools/regen.sh` finds `Legend of Zelda, The - A Link to the Past (USA).sfc` at the repo root,
|
|
then the path the setup wizard recorded in `rom.cfg`; `.gitignore` blocks
|
|
both from ever being committed.
|
|
|
|
`tools/regen.sh` verifies the ROM, generates `src/gen/*.c`, and re-syncs
|
|
`recomp/funcs.h`. Re-run it whenever you change anything under `recomp/`.
|
|
|
|
## Run
|
|
|
|
```sh
|
|
./build/LegendOfZeldaALinkToThePastSNESRecomp # launcher picks the ROM
|
|
./build/LegendOfZeldaALinkToThePastSNESRecomp /path/to/Legend of Zelda, The - A Link to the Past (USA).sfc # or name it and skip the launcher
|
|
```
|
|
|
|
With no ROM on the command line the build opens the recomp-ui launcher: a ROM
|
|
picker with a verification badge, plus display / audio / input settings. Your
|
|
choice is cached in `rom.cfg` beside the executable, so the next launch opens
|
|
on it and "Skip launcher on boot" makes it immediate. If the launcher is not
|
|
built in (`--no-recomp-ui`), the host falls back to a native file picker.
|
|
|
|
Either way the ROM is checked against the digests above before anything boots
|
|
— a dump that could not have produced this build is refused at the door rather
|
|
than mis-executing ten frames in.
|
|
|
|
## Layout
|
|
|
|
| Path | What lives there |
|
|
|---|---|
|
|
| `recomp/` | Analysis input: `bank*.cfg`, `symbols.toml`, generated `funcs.h` |
|
|
| `rom_identity.txt` | ROM digests — read by the build, `tools/regen.sh` and CI |
|
|
| `src/` | Host code you own: `main.c`, `game_rtl.c` |
|
|
| `src/gen/` | Generated C. Never committed — regenerate locally |
|
|
| `snesrecomp/` | Framework submodule (owns `lib/recomp-net`, `lib/retcomm-rbengine`) |
|
|
| `tools/` | `regen.sh` — the ROM → C pipeline |
|
|
| `scripts/` | `package_release.sh` — player-facing zip |
|
|
| `framework_pins.txt` | Exact framework commits this project was scaffolded against |
|
|
|
|
## Porting from here
|
|
|
|
The scaffold stops where the game-specific work starts. In rough order:
|
|
|
|
1. **Make it boot.** `src/game_rtl.c` holds the frame driver. It starts on
|
|
the framework's beam-aligned driver (`snesrecomp/runner/src/beam_frame_driver.h`):
|
|
one frame per PPU field, interrupts taken where the beam latches them,
|
|
the field rasterized from the raster journal. A title whose main loop it
|
|
does not fit replaces those calls with its own driver.
|
|
2. **Name things.** Add entries to `recomp/symbols.toml` as you identify
|
|
routines, then re-run `tools/regen.sh`. Set `emit = true` to promote one
|
|
into ahead-of-time analysis; leave it false to keep it interpreted.
|
|
Regen synchronizes the marked blocks in each bank cfg, creating missing
|
|
configs. Only proven variants become AOT code. See `recomp/README.md`.
|
|
3. **Resolve dispatch misses.** After every run, deal with unresolved
|
|
indirect targets before anything else — they are the reason a port
|
|
diverges, and they are cheap to fix early.
|
|
4. **Never synthesise a result** to get past uncovered code, and never edit
|
|
`src/gen/` by hand. Fix the config or the framework and regenerate.
|
|
|
|
## Multiplayer
|
|
|
|
Single player.
|
|
|
|
## License
|
|
|
|
This project's own source is under the license in `LICENSE`. The framework
|
|
carries its own terms — see `snesrecomp/LICENSE` and
|
|
`snesrecomp/THIRD_PARTY_ATTRIBUTION.md`. Neither covers the game data, which
|
|
is not distributed here.
|