McDonald's Treasure Land Adventure — Static Recompilation

A static recompilation of McDonald's Treasure Land Adventure (Treasure / SEGA, 1993) for the Sega Genesis / Mega Drive, built with the segagenesisrecomp framework.

The original 68000 machine code is translated to native C at build time and runs against the framework's clean-room Genesis runtime (VDP, bus, scheduler, YM2612 FM, SN76489 PSG, Z80). No emulator core is compiled or linked; code the static scan cannot prove is a function entry falls back to the framework's Tier-3 interpreter capsule at runtime.

This repository contains no ROM. You must supply your own legally obtained copy of the USA release (and, for the experimental Japan and Europe variants, the Japan and Europe releases). See ROM you need.

ROM you need

USA — the verified target

Title	McDonald's Treasure Land Adventure (USA)
Region	USA / NTSC
Size	1 MiB (1,048,576 bytes)
CRC32	04EF4899
Internal header	MCDONALD'S, serial GM MK-1067 -00

Place it at game/mcdonald.bin. The recompiler bakes in address-level discovery derived from this exact image, so other revisions/dumps are not supported.

Japan — experimental, optional

Title	McDonald's Treasure Land Adventure (Japan)
Region	Japan / NTSC
Size	1 MiB (1,048,576 bytes)
CRC32	FEBCFD06
Internal header	MCDONALD'S, serial GM G-004102-00

An opt-in second target (-DMCD_ROM_VARIANT=jp) built from a separately linked image: 63.9% of its bytes differ from the USA ROM and its 68000 code is relocated, so it is regenerated from scratch and no USA address carries over. Place it at game/jp/mcdonald.bin. It is unplaytested — treat it as an experiment, not a port.

Europe — experimental, optional

Title	McDonald's Treasure Land Adventure (Europe)
Region	Europe / PAL
Size	1 MiB (1,048,576 bytes)
CRC32	6AB6A8DA
Internal header	MCDONALD'S, serial GM MK-01067-00

An opt-in third target (-DMCD_ROM_VARIANT=eu) built from a separately linked Europe image. Like the Japan ROM it is relocated relative to the USA one and region-checks the version register $A10001 at boot (it wants 0xC0, PAL). Unlike the Japan ROM it also runs on PAL frame timing — 313 scanlines per frame at ~50.16 Hz instead of 262 at 59.94 — so the specification selects the PAL frame geometry and the engine scales the master-clock frame span (and the audio-chip drain that goes with it) to the region (engine fixes 5 and 6). Place it at game/eu/mcdonald.bin. It is unplaytested — treat it as an experiment, not a port.

Status

Area	State	Notes
Boot → SEGA / Treasure title	✅	mode dispatch, palettes, scrolling
Menus / attract mode	✅
In-game (level 1)	✅	scrolling, object updates, animation
Sprite / tile-list decoder	✅	$011A90 / $011B00 state machine
Password / symbol screen	✅	mode 16 sub-state dispatch ($01620E); reached from the title menu, not the attract loop
Audio	✅	YM2612 FM + SN76489 PSG
Full playthrough	⚠️	not verified end to end

Known gaps: a computed dispatch inside func_05AA24 ($05AA76 / $05AA7A) still resolves on the Tier-3 floor, and a handful of floor-coverage addresses remain unvalidated. See docs/ENGINE-FIXES.md.

Japan variant (experimental)

Built with -DMCD_ROM_VARIANT=jp. Same engine and RAM layout. The cartridge region-checks the version register $A10001 at boot, so its spec reports a Japanese domestic console (engine fix 4); the computed-dispatch seeds are mirrored from the USA set at their relocated JP addresses (game/jp/game.toml).

Area	State	Notes
Region screen → boot	✅	clears the "wrong region" warning
Title / attract	⚠️	renders; not fully audited
Password / symbol screen	✅	mode 16; symbols render, 0 dispatch misses
Gameplay / audio	⚠️	not verified

Nothing here is playtested end to end.

Europe variant (experimental)

Built with -DMCD_ROM_VARIANT=eu. Same engine and RAM layout, but the runtime runs PAL geometry — 313-line frames at ~50.16 Hz — because the specification reports a European console (engine fixes 4–6). No USA or JP address carries over: the Europe image is relocated, so its discovery seeds are mirrored from the USA set at their EU addresses (game/eu/game.toml).

Area	State	Notes
Region screen → boot	✅	clears the wrong-region warning at $A10001 = 0xC0
Frame rate / audio	✅	~50.16 Hz, no audio underruns (49.5 fps measured over 3000 frames)
Title / attract	⚠️	renders; not fully audited
Gameplay / audio	⚠️	not verified

Nothing here is playtested end to end.

Requirements

• CMake ≥ 3.16
• Ninja (or another generator)
• A C11 / C++17 toolchain (the FM core, ymfm, is C++)
• SDL2 development libraries
• git (the engine is a submodule)

Debian / Ubuntu:

sudo apt install build-essential cmake ninja-build libsdl2-dev

Build & run

git clone --recurse-submodules https://github.com/yourname/McDonaldsTreasureLandRecomp.git
cd McDonaldsTreasureLandRecomp

install -m644 "/path/to/McDonald's Treasure Land Adventure (USA).md" game/mcdonald.bin

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

./build/McDonaldsTreasureLandRecomp game/mcdonald.bin --no-launcher

The first build regenerates the translated C from the ROM (a few minutes); later builds are incremental.

GENESIS_RECOMP_ROOT defaults to the in-repo segagenesisrecomp/ submodule. Point it elsewhere with -DGENESIS_RECOMP_ROOT=/path/to/checkout to build against a different engine tree (e.g. one carrying local experiments).

Japan build (experimental)

install -m644 "/path/to/McDonald's Treasure Land Adventure (Japan).md" game/jp/mcdonald.bin

cmake -S . -B build-jp -G Ninja -DCMAKE_BUILD_TYPE=Release -DMCD_ROM_VARIANT=jp
cmake --build build-jp

./build-jp/McDonaldsTreasureLandRecompJP game/jp/mcdonald.bin --no-launcher

Europe build (experimental)

install -m644 "/path/to/McDonald's Treasure Land Adventure (Europe).md" game/eu/mcdonald.bin

cmake -S . -B build-eu -G Ninja -DCMAKE_BUILD_TYPE=Release -DMCD_ROM_VARIANT=eu
cmake --build build-eu

./build-eu/McDonaldsTreasureLandRecompEU game/eu/mcdonald.bin --no-launcher

MCD_ROM_VARIANT defaults to us. The variants use separate build directories and separate generated sources, so the USA build is never affected by the JP or Europe ones.

Layout

game/game.toml                discovery seeds + per-game RAM layout (USA)
game/mcdonald_spec.c          GameSpec: vectors, ROM identity, bring-up (USA)
game/jp/game.toml             discovery seeds + RAM layout (Japan, experimental)
game/jp/mcdonald_jp_spec.c    GameSpec for the Japan variant
game/eu/game.toml             discovery seeds + RAM layout (Europe, experimental)
game/eu/mcdonald_eu_spec.c    GameSpec for the Europe variant (PAL geometry)
CMakeLists.txt                native target; MCD_ROM_VARIANT selects the variant
segagenesisrecomp/            framework submodule (patched fork — see below)
patches/                      engine changes as plain patches
docs/ENGINE-FIXES.md          root-cause writeups for the engine changes
tests/scripts/                input scripts for automated / headless runs
tools/                        debug-server helper

How discovery works

There is no community disassembly for this game, so 68000 function boundaries come from the recompiler's heuristic scan (68K vector table + BSR/JSR/RTS walk) refined by a small set of hand-audited seeds in game/game.toml → [functions].extra. Every seed is decoded from the raw ROM before it is added — never blind-seeded from a runtime miss list.

When the scan cannot prove a computed-dispatch target, the runner executes it on the Tier-3 interpreter capsule and records it in build/dispatch_misses.toml and build/floor_coverage.toml. Those files are the work queue: each address is disassembled, confirmed against the ROM, and promoted into [functions].extra in the next revision.

Engine changes

This game needs six small engine changes on top of upstream segagenesisrecomp. They are carried in the segagenesisrecomp submodule fork and, for reference and upstreaming, as plain patches in patches/:

Patch	File	What
0001-runner-local-computed-return.patch	runner/m68k_interp.c	Tier-3 capsule honours a locally pushed return address
0002-codegen-net-pushed-return.patch	external/m68k-recomp-core/profiles/genesis/code_generator.c	code generator mirrors that behaviour for the same idiom, and byte-accurate stack-delta tracking
0003-runner-console-region.patch	runner/game_spec.h, runner/main.c	per-game $A10001 console region (Japan 0x00), so the JP cartridge clears its wrong-region screen
0004-runner-pal-frame-geometry.patch	runner/game_spec.h, runner/glue.c, runner/main.c, runner/video/*	region-derived frame geometry (PAL 313 lines / ~50.16 Hz), so the Europe build runs at PAL speed
0005-runner-pal-audio-drain.patch	runner/sim_step.c	scale the audio-chip drain to the frame geometry, so PAL frames no longer starve the bridge ring (that starvation was the PAL stutter)

See docs/ENGINE-FIXES.md for the full root-cause writeup.

Automated runs & debugging

The runner accepts an input script:

./build/McDonaldsTreasureLandRecomp game/mcdonald.bin --no-launcher \
    --input-script tests/scripts/smoke.input

Scripts can WAIT, PRESS / HOLD / RELEASE, WAIT_RAM16, DUMP_RAM, DUMP_VRAM, SCREENSHOT, SAVE_STATE and EXIT. WAIT_RAM* blocks until the value appears and keeps advancing frames meanwhile, so a script can gate on a screen that has to be reached first (e.g. tests/scripts/password-screen.input, which waits for the title-menu password screen).

For live inspection the runner exposes a TCP debug server (line-based JSON). It is disabled unless a debug.ini file exists next to the executable — its presence is what enables the server; an optional port= line sets the port (compiled default 4378, and --port N overrides both):

cp tools/debug.ini.example build/debug.ini     # enables the server on port 4378
./build/McDonaldsTreasureLandRecomp game/mcdonald.bin --no-launcher &

tools/genesis_debug.py --port 4378 ping
tools/genesis_debug.py --port 4378 read 0xFFE004 4
tools/genesis_debug.py --port 4378 shot shots/now.png

tools/genesis_debug.py is a tiny client; see the engine's DEBUG.md for the full command list. The runner also reads debug.ini for pacing= and interlace_display= overrides.

License

PolyForm Noncommercial License 1.0.0 — see LICENSE.md. The segagenesisrecomp submodule is licensed separately by its upstream authors; third-party components are listed in THIRD-PARTY-LICENSES.md.

No ROM, no copyrighted game assets and no SEGA / Treasure trademarks are distributed here. McDonald's Treasure Land Adventure is © SEGA / Treasure; "McDonald's" is a trademark of McDonald's Corporation. This is a noncommercial fan reverse-engineering effort.

Credits

• segagenesisrecomp — the recompilation framework, runtime and recompiler driver
• m68k-recomp-core — the shared 68K decoder / emitter