# dream

**[Live progress dashboard](https://nathanialf.github.io/dream/)**: per-section, per-routine and per-region status, updated on every push.

A matching disassembly of the **Dream: Land of Giants** prototype (codename Project Dream), the SNES game Rare built around 1995
that later became *Banjo-Kazooie*. `make` rebuilds the 2 MiB ROM byte-for-byte from
the sources here plus data extracted from your own copy of the ROM.

> [!IMPORTANT]
> This project is unaffiliated with Rare, Microsoft, or Nintendo. No ROM data or
> extracted assets ship with this repository; you must supply your own ROM to build.
> This is a disassembly, not a clean-room reimplementation. Read
> [`docs/LEGAL.md`](docs/LEGAL.md) before contributing.

## Target

The end goal is a **recomp**: a C reimplementation of the game that runs natively and
is verified by executing it in lockstep with the original ROM in an emulator, comparing
WRAM, VRAM, CGRAM, OAM, ARAM, the DSP and the SPC700 registers every frame under scripted
input (the approach that produced native ports of other SNES titles). That target is
reached for everything the game executes; see the table below for what is left. There was no compiler in 1995, so byte-matching C is not a
meaningful goal on this platform; a byte-identical *disassembly* is the foundation, and
behaviour-matching C is the target.

| phase | state |
|---|---|
| 1. Disassembly with byte-identical rebuild | done: 65816 program and SPC700 driver both rebuild exactly (`make check`) |
| 2. Understanding: named routines, RAM map, data formats | in progress: the `code`, `sound_iface` and `spc700` rows of [`docs/PROGRESS.md`](docs/PROGRESS.md) |
| 3. Asset extraction with round-trip gates (sprites, tiles, maps, palettes, BRR, music) | in progress: `config/assets.txt` (1926 named assets, generated by `tools/gen_assets.py`) covers the whole ROM; `tools/extract.py` writes them under `data/`, `tools/emit_asar.py` incbins by name |
| 4. C reimplementation with per-frame lockstep verification | in progress: 139 converted 65816 routines and 95 SPC700 routines, 234 of them credited by the gates (`config/recomp.txt`, the `recomp` row of [`docs/PROGRESS.md`](docs/PROGRESS.md)); the native app ships in the releases |

The ROM is HiROM with an intact vector table but a header overwritten by tilemap data,
no checksum, and a stale older build of the same program sitting in the first 32 KB.
The sound driver is the DKC2/DKC3 driver (96% identical) and ten library routines are
verbatim from the DKC games. Details and evidence: [`docs/NOTES.md`](docs/NOTES.md),
[`docs/toolchain_evidence.md`](docs/toolchain_evidence.md),
[`docs/data_formats.md`](docs/data_formats.md), [`docs/handler_tables.md`](docs/handler_tables.md),
[`docs/dkc_crossref.md`](docs/dkc_crossref.md). Recomp design decisions: [`docs/RECOMP.md`](docs/RECOMP.md).

## Quickstart

```sh
git clone https://github.com/RPGHacker/asar && cd asar && mkdir build && cd build && \
  cmake ../src/asar -DCMAKE_BUILD_TYPE=Release -DASAR_GEN_EXE=ON -DASAR_GEN_DLL=OFF -DASAR_GEN_LIB=OFF && \
  make && mkdir -p ../../tools/bin && cp bin/asar ../../tools/bin/ && cd ../..
cp /path/to/DREAM.sfc baserom/        # sha1 2675d7afe886f20462337aa1ee3aa5c3135fff3a
make                                  # extract -> assemble -> verify (ROM and SPC700 driver)
```

`tools/extract.py` refuses a ROM whose SHA-1 does not match. Everything under
`baserom/`, `data/`, `build/`, and `out/` is gitignored. Run `tools/install_hooks.sh`
once: the pre-commit hook runs `tools/check_no_rom.sh`, refuses a commit whose index and
working tree differ under any path a gate reads, runs the byte-identical gate, the three
recomp gates and `make app-check` when the commit touches the port, and refreshes
`docs/PROGRESS.md` and `docs/progress.json`. The pre-push hook re-runs all of it on the
pushed tip, including for a branch the remote does not have yet, and refuses a dirty tree.

### Playing it

The port is separate from the disassembly: `dream` is a native build of the game
that reads your own ROM. Builds for Linux and Windows are attached to each tagged (macOS builds are produced but untested and may be missing)
[release](https://github.com/nathanialf/dream/releases): a zip holding the
executable, this README and the LICENSE, and no game data of any kind. Unpack it,
put your own `DREAM.sfc` where the app looks for it, and run it. On Windows that is
next to `dream.exe`, then `%APPDATA%\dream\`, then `.\baserom\`. On Linux and macOS
it is `./baserom/DREAM.sfc` relative to the directory you run it from, then
`~/.local/share/dream/DREAM.sfc`; beside the executable is a Windows-only lookup, so
`mkdir baserom && cp DREAM.sfc baserom/` is the one that always works. A path on the
command line beats all of them. Windows needs nothing installed alongside:
`dream.exe` imports only Windows' own DLLs.
[`recomp/app/README.md`](recomp/app/README.md) has the controls, the gallery, and
the Windows section in full; building it yourself is `make app`, or `make app-win`
to cross-build the Windows executables from Linux with mingw-w64.

## Workflow

`src/` and `spc/driver.asm` are generated:

1. `tools/trace65816.py` traces the 65816 code from the vectors, tracking M/X flags,
   jump tables, RAM-dispatch tables, and subroutine return states.
2. `tools/names.txt` supplies curated labels (ROM code, data, RAM).
3. `tools/emit_asar.py` writes asar source with symbolic references and `incbin`
   ranges for data.

To improve the disassembly, edit `tools/names.txt` (or the tracer), then
`make regen && make`. Hand edits to `src/` are discarded by `regen`; the plan is to keep
enriching the generators until the output is worth freezing. Symbol files for
emulator debuggers (`out/dream.mlb` for Mesen2, `out/dream.sym` for bsnes-plus) are
produced by the tracer.

## Releasing

The git hooks keep only the fast checks: the no-ROM scan, a clean tree, the byte-identical
rebuild and the SPC driver compare. The lockstep gates are the release checklist; run them
by hand on the commit you intend to tag, then tag:

```sh
make recomp-check          # C bodies against the ROM, seven input scripts, both processors
make recomp-check-units    # the routines no script reaches, from seeded states
make recomp-check-nocpu    # the mode the app ships in: no emulated CPU
make app-check             # gallery gates and app/harness frame-line parity
git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z
```

`release.yml` then builds and attaches the Linux and Windows zips (macOS is built but
untested and non-blocking).

## Layout

```
baserom/   your ROM (gitignored)          docs/     notes, legal, analysis reports
data/      extracted half-banks (ignored) spc/      SPC700 driver disassembly
src/       generated asar source          tools/    tracer, emitter, extract, checks
```

## License

MIT for everything authored here. The game and its data remain the property of their
respective owners.