dream

Live progress dashboard: 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 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
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); 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/toolchain_evidence.md, docs/data_formats.md, docs/handler_tables.md, docs/dkc_crossref.md. Recomp design decisions: docs/RECOMP.md.

Quickstart

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

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.