Scene Bytecode

Overview

The 62 expanded BIN members are the game’s scene programs. Most are pure bytecode streams with no header. They select art and palettes, start music, change scenes, update variables, branch, call subroutines, and coordinate animation. The executable’s interpreter dispatches opcodes 0x01 through 0x91 through a 145-entry near-pointer table at load offset 0x59AB.

The operand layout and an evidence-based handler name have now been recovered for every dispatched opcode. Linear decoding identifies 25,829 commands in 64 code regions and uses 122 of the 145 possible opcodes. Names for commands that do not occur in the shipped scripts describe their direct engine effects rather than claiming an unobserved gameplay role.

An independent second pass reads the 145 dispatch pointers directly from the unpacked executable and finds 134 distinct implementation addresses. It walks every handler’s control-flow graph, records all operand-reader calls, and joins the results to the complete shipped corpus. The checked result is analysis/opcode-audit.tsv; tools/audit_bin_opcodes.py regenerates and verifies it.

Runtime model

initialize_scene at 0x6631 appends .BIN to a scene base name, loads that archive member into far memory, installs its base and initial cursor, resets scene-thread state, and calls execute_bin_commands at 0x451B with file offset zero. Later, update_scene_threads at 0x7997 resumes active command streams by passing their saved file offsets back to the same interpreter.

Four words in the data segment hold the current input state:

The interpreter sets its cursor to base + requested_offset, fetches one byte, converts opcode 1 to dispatch index 0, range-checks through 0x91, and calls the corresponding handler. Branch and call targets are absolute offsets within the expanded BIN member, rather than relative displacements.

Three shared operand readers make the encoding unambiguous:

Four other handlers implement their own byte-at-a-time inline string loops: opcodes 0x01, 0x0D, 0x4D, and 0x6D. Those loops do not recognize the 0xFF offset escape. Keeping the two encodings separate prevents an art, palette, or scene name beginning with CP437 byte 0xFF from being misinterpreted as a pointer.

Operand schema

The decoder records each opcode with a compact schema:

The conditional BHs form is used by opcodes 0x11, 0x12, and 0x17 through 0x1A. For example, bytes 11 01 F8 FF E6 01 contain byte 1, signed word -8, and therefore the extra word 0x01E6.

The complete machine-readable table is OPCODE_SCHEMAS in tools/inspect_bin.py. It contains one entry for every value from 0x01 through 0x91; tests extract the resources directly from CB/DD1.DAT and exercise every known code region against that table.

Top-level selector input

The main input dispatcher at 0x875D separates confirmation input from exploration actions with global action-selection word DS:004C. When it is zero, Enter (0x0D) or the primary-button event (0x7E) sets the opcode-64 latch at DS:7CC0. When it is nonzero, those events instead query render slot 0x124, require the current selector index at DS:00EE to be nonnegative, and call the selector activator at 0x851E. A press with no current selector does nothing; it does not leak into the confirmation latch.

ASCII Space reaches the cycling routine at 0x6939 only while action selection is enabled. That routine refreshes the current selector with update_action_selector_overlay, then advances through two tables. Kind zero visits the 16-byte scene-thread records at DS:7DC0; kind one visits the 10-byte opcode-3A records at DS:4810. Exhausting either table wraps into the other. An actor needs its byte at +7 set, while an action needs its byte at +8 set. Both require signed X less than 320 and signed Y less than 200. The successful record writes X and Y+4 to the logical pointer words and calls the overlay updater again.

The four extended arrow events have the same action-selection split. 0xC8, 0xD0, 0xCB, and 0xCD search for selector keys u, d, l, and r while DS:004C is nonzero. While it is zero, the branches at 0x889C, 0x88BD, 0x88F7, and 0x88D7 instead subtract or add eight to the corresponding logical pointer word.

Opcode 02 initializes the scene-thread selector X/Y fields to 30000 and its string pointer to -1; its navigation X/Y live elsewhere in the same record. Opcode 10 installs the on-screen selector anchor and string. Consequently an unlabeled navigation record such as GANTRY’s opening remains clickable through the navigation hit-test, but its untouched off-screen selector fields keep it out of proximity hover and Space cycling.

The standalone Bible routine at 0x1C88 is a blocking top-level interface. It saves action-selection state at 0x1D5F, clears DS:004C at 0x1D66, and services its own input loop before returning. The map, options, save, and status-notice dispatchers follow the same nested-interface model rather than returning to the scene controller on every host frame.

Independent audit

The second pass does not use successful linear decoding as proof of operand width. tools/audit_bin_opcodes.py instead combines five independent views:

1. the exact 145-word dispatch table at load offset 0x59AB;
2. every reachable path through the interpreter’s 1,817 Rizin instructions;
3. calls to the byte, word, and pointer-string readers, plus the four inline string loops and opcode 0x07’s direct nine-byte cursor advance;
4. the handler aliases and per-symbol evidence in analysis/cb.rz and analysis/symbol-map.tsv; and
5. all 25,829 decoded commands in all 64 known code regions.

The audit expands conditional schema BHs into both legal paths, BH and BHH. It also records the dialogue handler’s intentional no-read retry path: while a modal message is active, the command suspends without consuming its p operand; after the modal state clears, it consumes that same pointer and continues. No other handler is allowed an undeclared operand path.

Run the complete comparison with:

tools/audit_bin_opcodes.py

The report records, for every opcode value, the dispatch address, handler symbol and confidence, declared schema, independently observed read paths, script-variable operand positions, use count, resource set, and first shipped site. Twenty-three opcode values are absent from shipped code: 03, 0E, 13, 18, 1B, 2E, 30, 37, 39, 47, 4A, 4B, 4F, 50, 56, 5E, 65, 66, 6E, 6F, 8B, 8F, and 90.

Identified commands

These handler meanings have direct static support from their callees or clear control-flow behavior:

Formerly structural commands

The final unnamed-handler pass connected the remaining 51 opcode values to their consumers. Thirteen of these values never occur in the shipped command regions; their rows are marked unused and rely on static handler behavior. Ten already-named values are also absent, producing the audit’s overall total of 23 unused opcodes.

The movement opcodes share the controller recovered at 0x6F46, 0x7469, and 0x779D. Opcode 0x53 uses the same edge initializer with identical start and end nodes; opcode 0x0A therefore continues waiting until that minimum traversal completes. Opcode 0x54 first compares its operand with the retained desired node. During active interpolation a different operand only replaces that byte. The current edge, timer, pose, phase, and callbacks remain intact, and route search runs again from the reached node after its arrival callbacks. The retained byte starts at 0xFF, persists across scene changes, and is not reset by opcode 0x53.

Navigation callbacks are fresh synchronous command-stream invocations: each one runs through its first yield or return before the dispatcher examines the next matching record. A same-slot callback’s delay does not pause the outer command interpreter that synchronously invoked it; if that outer invocation later yields, its cursor replaces the nested cursor while both delay changes remain accumulated. Initial movement searches, runs the source-node and directional-edge departure callbacks in that order, and then initializes the edge. State-five continuation searches, initializes the edge, and runs the directional-edge then source-node departure callbacks. Completion makes the controller inactive for request purposes before running the directional-edge then destination-node arrival callbacks.

Opcode 0x69 was previously recorded as a one-word instruction. Its handler actually reads an immediate BIN offset and a destination-variable offset. In CP2.BIN, the second word’s low byte happened to be opcode 0x40, so all streams still decoded while eleven destination operands appeared as phantom commands. Correcting the schema reduces the corpus total from 25,840 to 25,829 without changing the set of 122 opcodes genuinely used by shipped scripts.

DOS coordinate-indexed object overrun

The operand source used by opcodes 0x8E and 0x91 is not a MAP field and is not a separately loaded 16×16 resource. Both handlers calculate 16 * map_y + map_x and read from DS:008A. The initialized object at that address contains only 80 bytes, covering rows zero through four:

92 DF 1A 72 01 83 9C E5 00 B8 A8 01 2C F7 E2 AA
64 F3 43 CA 7D 7C 6A 51 37 A3 33 7A 70 1F 8B 4F
98 EF 83 6F 65 41 A3 0F C8 93 80 3F 1F 18 90 6E
AC 5D 3E 31 46 2C 3A 40 4E B1 13 C1 E5 DB 07 CA
5C 05 1A 21 EC D6 65 46 A8 65 B1 B3 AF A1 44 62

The handlers perform no bounds check. Rows five through fifteen therefore alias the initialized data and live globals which immediately follow the 80-byte object. Those aliases explain why a literal 256-byte zero replacement removed combat variation and made every Communications room choose the same initial face during reverse engineering. They are DOS implementation details, not clean-room compatibility requirements.

The live aliases identified while explaining the DOS captures are:

The two segment words are allocator-derived. They were 42C5 in the focused fresh-load probes and 4C13 in a longer prior session, even though the resource-relative cursor behavior was identical. This is the only part of the lookup whose exact value can vary with the DOS heap history.

The clean-room engine treats this entire lookup as a DOS implementation detail. Every opcode-8E or opcode-91 execution advances the one portable runtime generator and uses the returned value’s low byte, regardless of map coordinate. Opcode 0x82, the text shuffle, unused opcode 0x8B, and the transient-status refresh started by 0x8B share that stream. The algorithm and call order are now explicit so, from the same initial state and inputs, a patched DOS run, Rust, and future implementations can replay the same branches without depending on resource addresses, selector state, or unrelated scene globals.

Instruction-boundary QEMU probes validate both consumers. COMBAT1.BIN reached 0627:5913 at map coordinate (0,4) with BX=0040, ART/display counts 6/35, and cursor 07F3, exactly one byte after its opcode-8E at 07F2. A patched ROOM3 save reached 0627:597F at coordinate (13,6) with BX=006D, ART/display counts 3/16, and cursor 169C, exactly one byte after opcode 91 at 169B.

The latter probe proves the problematic alias directly. DS:008A + 006D is DS:00F7, the high byte of the current BIN instruction pointer stored at DS:00F6; opcode 91 read 16h from the pointer value 169Ch. The deterministic DOS patch removes the whole coordinate calculation at 0x5905 and 0x5971 and routes each handler through the portable generator exactly once.

The pointer-capable p encoding is used by seven opcodes: 0x0C, 0x10, 0x14, 0x3A, 0x44, 0x48, and 0x4E. Only two shipped commands use its explicit-offset form: ROOM3.BIN at 0x181C (0x48) and 0x18CE (0x4E) both point back to string offset 0x0336. All other shipped p operands are inline strings.

Opcode 0x8D copies the same active player prefix and mutable suffix used by the save routines, then requests fopen(..., "rb"). At its only site, TITLE.BIN:0x012C, the initialized suffix is .SV0, so the constructed name is DDGAMES.SV0 with the default prefix. A failed open selects target 0x012F, which is also the next command; either result therefore reaches the same change_scene 'INTRO', 'seg'. The handler passes the returned stream to fclose after either path, including the null result on failure.

Opcode 0x7A deliberately modifies the loaded BIN buffer. Combat exits use it to replace the C in inline CHAL from the current level-letter variable; POWER.BIN replaces the digit in combat1 from the selected combat number. It is therefore a resource-name templating mechanism rather than a persistent-state write.

Opcode 0x6C calls rotate_palette_range at 0xB5A8. Its operands are inclusive minimum, inclusive maximum, signed step, and phase variable. The helper wraps the updated phase, fills the palette-index mapping across the range, and schedules a palette update. Opcode 0x7E calls start_palette_blackout at 0x1B6C; the next palette update writes an all black palette and counts down the effect state.

The suffix strings are present in the executable data segment and were also checked in the QEMU process image: .PAL at DS:0434, .ART at DS:0490, and .BIN at DS:0721. This corrects an early interpretation of bytes such as 4D 54 49 54 4C 45 00 as the string MTITLE: byte 0x4D is actually the palette opcode followed by the string TITLE.

Startup programs

The QEMU DOS trace and archive directory give this resource-load sequence:

LOGO.BIN -> LOGO.PAL -> LOGO.ART -> D003.ABT
TITLE.BIN -> TITLE.PAL -> TITLE.ART -> TITLE2.ART -> MUS001.XMI
INTRO.BIN -> INTRO.ART

The scripts involved decode completely:

INTRO.BIN begins by setting two small state values, loading TITLE.PAL, loading INTRO.ART, and drawing the opening sequence. Opcode 0x52 selects music index 1, which produces MUS001.XMI. At file offset 0x009A, opcode 0x0D carries strings dome and seg to enter the first gameplay scene.

The runtime dump contains all 184 INTRO.BIN bytes at physical address 0x4C130. The base pointer 4C13:0000 appears at physical address 0x14F0A, stored as offset word 0000 at DS:00FA and segment word 4C13 at DS:00FC. The live cursor is 4C13:004B; resource offset 0x004B begins opcode 0x42 and is exactly the boundary after the preceding return_minus_one command. This ties the static decoder’s command boundaries to live interpreter state.

Mixed code and data

Sixty members decode linearly from byte zero through end of file. Two members contain non-code regions:

• CP2.BIN has commands at 0x0000..0x1D54, followed by a 256-byte structured data trailer at 0x1D55..0x1E54. It contains a 16-node four-heading adjacency table, node types, transition values, and lower-right map coordinates. The Unibot chapter decodes every entry.
• ROOM3.BIN has command regions 0x0000..0x0336, 0x0C96..0x1754, and 0x1768..0x19DB. A 2,400-byte zero-filled block and a 20-byte zero-filled block separate them.

Opcode zero is invalid. The decoder deliberately reports it instead of guessing that arbitrary padding or embedded tables are executable commands. The later ROOM3.BIN entry points are therefore decoded explicitly rather than reached by a single linear sweep.

Inspection tool

After extracting the archive, inspect a complete stream with:

tools/inspect_bin.py build/dd1/all/005_INTRO.BIN

Use explicit bounds for embedded regions:

tools/inspect_bin.py \
  build/dd1/all/334_ROOM3.BIN --start 0x0c96 --limit 0x1754
tools/inspect_bin.py \
  build/dd1/all/334_ROOM3.BIN --start 0x1768
tools/inspect_unibot.py build/dd1/all/315_CP2.BIN

Output includes the file-offset range, opcode, current semantic name, and typed operands. Variable operands show both their word index and encoded byte offset, with recovered names such as var[21:faith]@0x002a. Other words with their high bit set are displayed in both unsigned hexadecimal and signed decimal forms. Every dispatched opcode now has a name; low-level names for unused commands deliberately describe state changes rather than inferred UI.

Add --objects to append a linear summary of commands which define display records, --choices to inventory dialogue target/text pairs, or --animations --actions to inventory animation sequences and selectable screen targets. Action summaries name the four combat selectors and the hall selectors for movement, Confront Cyber, Unlock, and Get Verse. The scene-display-object chapter documents the ten-byte runtime record, while the conversation-flow chapter documents the six-byte choice table. The combat-runtime chapter documents animation slots, action targets, and the BIN scheduler; the world-map chapter correlates the hall actions with map-cell features. These summaries warn that branches can change which definitions execute.

Executable routines

Offsets use the unpacked load-module convention documented elsewhere in this book.