daedalian/README.md

Daedalian Opus, ported to Rust

A rewrite of the Game Boy game as ordinary Rust, translated by hand from the disassembly in ../disassembly/. Unlike ../rust/ (a static recompilation that still runs the original instructions against emulated registers and memory), this is the game itself: the screens, the puzzle rules, the map, the story and the music sequencer are Rust functions over named state, so they can be read and changed.

cargo run --release                 # looks for "Daedalian Opus (USA).gb" here or in ..
cargo run --release -- --rom PATH

Controls: arrows = D-pad, Z = A, X = B, Enter = Start, Right Shift / Backspace = Select, Esc = quit.

What comes from where

The program contains no game content. At startup rom.rs parses the ROM into typed data: levels (Level: starting pieces, board layout, cursor start, music, pieces needed, which piece drops on the map), piece shapes, screen layouts (tilemap draw scripts), story text, passwords, tile graphics and the music byte code. Small numbers that are really code (coordinates, tile numbers for digits, timings) live in the Rust source as named constants.

Layout

file	what
src/game/mod.rs	Game state, the top-level flow (title → story → map → puzzle → ...), the per-frame tasks, the clear-time clock
src/game/puzzle.rs	the puzzle: picking up, moving, rotating, flipping and placing pieces; the win check; reset; the level-clear screen
src/game/map.rs	the map between levels: walking, castle doors, the bridge, the password bird, the piece that drops from the sky
src/game/menus.rs	title, how to play, password entry, puzzle list
src/game/story.rs	story screens and the ending
src/sound.rs	the game's sound driver: an 8-channel byte-code sequencer (format documented at the top)
src/apu.rs	the Game Boy sound chip, as the instrument the driver plays
src/video.rs	tile graphics, two background maps, 40 sprites, palettes, and the renderer
src/rom.rs	ROM loading and parsing
src/input.rs	buttons, with the game's d-pad auto-repeat
src/main.rs	window (winit + pixels), audio (cpal), frame pacing
src/headless.rs	scripted runs for testing

The game code is written the way the original is structured: straight-line code that calls wait_frame() whenever it needs the next frame (to animate, or to wait for a button). It runs on its own thread; wait_frame sends the finished picture and sound to the host and blocks until the host sends the next frame's buttons.

The display model (tiles, maps, sprites) is kept because it's what the art is made of, so the game still draws by placing tiles and sprites. Map addresses like 0x9800 remain the way cells are named, since the screen layout scripts in the ROM use them.

Faithfulness

It's checked against the recompiled build in ../rust/ with the headless runner. Same inputs give the same screens (title, every menu, story pages, map walks, levels 1-3 and 36 solved, the ending), and the sound driver's chip register writes match frame for frame. Known differences:

• Loading a screen takes no time here, where the original spent a few frames copying graphics with the display off, so the port runs a few frames ahead.
• The original queued tile updates to the next vblank; here they happen immediately, so some changes appear one frame sooner.
• The original's unused "resume music" sound (id $96) points at garbage; it just resumes.

Original quirks are kept on purpose and marked (sic) in the source. For example, undoing a Select flip that doesn't fit uses Start's rule.

Headless testing

cargo run --release -- --headless OUT_DIR 120 start:2 90 shot:title probe goto:44:54

Tokens: N run N frames; BUTTON:N hold a button for N frames (up down left right a b start select); shot:NAME save a PNG; probe print the level and cursor; goto:YY:XX steer the puzzle cursor (hex sprite coordinates). Audio goes to OUT_DIR/audio.wav.