Runtime model

This page lifts the byte-level notes into implementation-facing data types and operation families. It is still a clean-room model: every name here is derived from local disassembly, local SQ2 resources, and the evidence recorded in the other pages.

The names are intentionally descriptive rather than final API names. A new implementation can use different public names, but should preserve the observed storage widths, lifetimes, and side effects unless later evidence proves a better model.

Global scalar state

The interpreter uses a byte-variable array rooted at DS:0x0009. Variable opcodes operate on unsigned bytes:

The flag store is a packed bitfield rooted at DS:0x0109. The flag helper maps a flag number to:

byte_address = 0x0109 + flag_number / 8
mask = 0x80 >> (flag_number & 7)

This means flag 0 is the high bit of byte 0x0109, flag 1 is the next bit, and so on. Initialization helper 0x752a clears 0x20 bytes, so the observed flag storage spans 256 bits.

Strings and parsed input

Fixed string slots begin at DS:0x020d. Each slot is 0x28 bytes, and the parser-facing action 0x75 (parse_string_slot) accepts only slot indexes 0..11, giving twelve script-visible slots in the observed interpreter.

Observed string operations:

Parser normalization for action 0x75 uses two SQ2 tables. Bytes in data.words.parser_separators_0c67 ( ,.?!();:[]{}) become word separators and separator runs collapse to one space. Bytes in data.words.parser_ignored_0c75 (apostrophe, backtick, hyphen, and double quote) are dropped without creating a separator. The normalized buffer is trimmed of a trailing space and then scanned one token at a time.

Dictionary lookup is case-insensitive for ASCII letters. Recognized dictionary entries whose word ID is zero are ignored and do not consume one of the ten parsed output slots; local examples include the, a, i, to, and with. Recognized nonzero IDs are appended to the parsed-ID table. If lookup finds an unknown token, the parser stores the pointer for the next output slot, records len(parsed_ids) + 1 in byte variable [0x0012] and data.words.parsed_count_or_error_position, sets parser flag 2, and stops. So an unknown word after ignored zero-ID words still reports output slot 1. If parsing reaches the end with at least one nonzero word ID, the same count word stores the number of parsed IDs and flag 2 is set. If only zero-ID words were present, flag 2 remains clear.

Condition 0x0e (input_word_sequence) consumes the parsed-word buffer rather than the raw string slot. Its bytecode operand is a count followed by that many little-endian word IDs. Word ID 0x270f terminates a successful match, and word ID 0x0001 behaves as a wildcard for one parsed word. QEMU batch parser_edges_001 validates exact two-word matching for look get, wildcard matching for look *, and 0x270f accepting a look prefix while an additional parsed word remains. Source helper 0x095c also allows a terminator-only pattern to match an unknown-token parse state when flag 2 is set and data.words.parsed_count_or_error_position is nonzero; QEMU batch parser_unknown_terminator_001 confirms this behavior.

Condition 0x0f (string_slots_equal_normalized) is the direct string-slot comparison path. It treats space, tab, ., ,, ;, :, ', !, and - as ignored bytes in the local SQ2 AGIDATA.OVL, lowercases ASCII uppercase letters, and then requires exact byte equality through both strings’ zero terminators.

For a new implementation, the clean boundary is:

StringSlots: fixed-size editable strings
WordParser: converts one slot into word IDs and parser flags
SaidLikeCondition: matches bytecode word sequences against WordParser output
StringCompareCondition: normalized direct slot equality, independent of WordParser

This separation matches the observed data flow and now has dynamic coverage for the basic message-to-string parse path, exact parsed-word matching, wildcard matching, terminator-prefix matching including the unknown-token edge, and direct normalized string comparison.

Logic resources and execution state

Loaded logic resources are represented by 10-byte cache records linked from [0x0977]:

+0x00: next record
+0x02: logic number
+0x03: message count
+0x04: bytecode base pointer
+0x06: current instruction pointer
+0x08: message offset table base

The interpreter loop reads from record+0x06. Action 0x91 (save_logic_resume_ip) stores the current bytecode pointer there, and action 0x92 (restore_logic_entry_ip) restores it from the bytecode base at record+0x04.

Implementation-facing lifetimes:

The important higher-level type is not just “logic bytecode”; it is a logic activation record containing bytecode, messages, and resumable instruction state.

Resource handles

All four resource types are addressed through directory entries and VOL.* records, then cached as small linked records. After the generic volume reader, payload pointers refer to the type-specific payload, not the five-byte VOL.* header.

A replacement implementation should separate “resource id”, “loaded payload”, and “typed decoded view” concepts. The original interpreter often decodes lazily by storing raw payload pointers in object records, but the object contracts depend on decoded fields such as group counts, frame pointers, width, and height.

Sound resources have a small typed structure on top of the raw payload. The loader reads the first four little-endian words and stores four payload-relative channel stream pointers in the sound cache record. The playback start helper copies those pointers into the runtime channel pointer table and initializes per-channel countdown, active, and attenuation words. The tick routine then consumes each channel as a sequence of records:

The local SQ2 corpus scan found 49 present sound resources. All present resources have four sorted, in-bounds channel offsets, and the first offset is 8, immediately after the four-word header. The current clean-room model covers the resource container and event stream shape, not full audio synthesis.

Source inspection also gives an implementation-facing playback schedule. The timer interrupt hook calls the sound tick only while data.sound.active_state is nonzero. At the start of each tick, flag 9 is tested; if flag 9 is clear, the driver stops immediately and sets the configured completion flag. Driver start initializes every channel countdown to 1, so the first event or channel terminator is read on the first active tick. After a non-terminating event is read, its duration word becomes the next 16-bit countdown. A duration of zero would wrap and delay the next channel record read for 65,536 ticks; the local SQ2 corpus has no zero-duration sound events.

The active channel set depends on the hardware selector. When selector [0x112e] is 0 or 8, the tick loop advances only channel 0. Other observed selector values advance all four channels. Natural completion occurs when the last active channel reaches its 0xffff terminator; the stop path clears active state and sets the flag stored by start_sound_with_flag.

Hardware output is source-backed only to the driver interface level. For selector 0/8, the driver uses the PC-speaker-style PIT path: an event with attenuation nibble 0x0f clears port 0x61 bits 0 and 1; otherwise the tone word is converted to a PIT divisor as 12 * (((tone_word & 0x3f) << 4) + ((tone_word >> 8) & 0x0f)), written low byte then high byte to port 0x42 after mode byte 0xb6 is written to port 0x43, and port 0x61 bits 0 and 1 are set. Stop on this path emits the same silence behavior.

Other observed selectors write driver bytes to port 0xc0. Tone output sends the high tone byte and, unless that high byte has top bits 0xe0, also sends the low tone byte. Stop on this path writes the four silence bytes 0x9f, 0xbf, 0xdf, and 0xff. Selector 2 calls a small source helper that adjusts an internal control byte whose high bits match 0x90 and whose low nibble is below 8; the observed port-facing tone bytes remain the high/low tone bytes described above.

Attenuation output is also source-modeled. Each channel has a base attenuation byte, an envelope index, and a previous envelope value. If the base attenuation is 0x0f, the helper writes the channel mask plus 0x0f and skips envelope processing. Otherwise, when the envelope index is not 0xffff, the helper reads a byte from the default table at 0x17b8. Byte 0x80 disables the envelope and copies the previous envelope value into the base attenuation. Other table bytes are deltas from the base attenuation, not cumulative deltas: negative underflow clamps to 0, positive overflow clamps to 0x0f, and the result becomes the previous envelope value. A runtime adjustment byte at [0x0020] is then added and clamped to 0x0f; selector 2 also raises non-silent values below 8 by 2. The final port byte is the adjusted low nibble ORed with the channel mask 0x90, 0xb0, 0xd0, or 0xf0.

These port writes are an implementation detail for hardware-facing compatibility. The portable game-state contract remains the event schedule, active-channel set, attenuation state, tone/attenuation port-output boundary, and completion-flag behavior above. This is not a claim about faithfully synthesizing the analog waveform from the original hardware.

Object records

Persistent objects live in a table of 43-byte records from [0x096b] to [0x096d]. The record is the central runtime type for visible, movable entities:

ObjectRecord {
    current_position: x at +0x03, y/baseline at +0x05
    selected_view: resource byte +0x07, payload pointer +0x08
    selected_group: byte +0x0a, group pointer +0x0c
    selected_frame: byte +0x0e, frame pointer +0x10
    saved_frame_and_position: +0x12, +0x16, +0x18
    dimensions: width +0x1a, height +0x1c
    motion: step +0x1e, direction +0x21, mode +0x22, mode2 +0x23
    priority_control: byte +0x24
    flags: word +0x25
    motion_parameters: mode-specific bytes +0x27..+0x2a
}

The implementation-facing object operations are:

The separate 3-byte table rooted at [0x0971] stores object/item metadata used by inventory-like logic. The third byte is a location/state marker. Actions 0x5c..0x61 set, clear, and read that marker, and action 0x7c (show_inventory_selection) treats marker value 0xff as “carried”: it builds a two-column list from those entries, displays their table-relative name pointers, and stores the selected item index in byte variable [0x22] or 0xff on cancel.

Two temporary object forms reuse the same structure:

• Actions 0x7a (setup_transient_object) and 0x7b (setup_transient_object_var) use a fixed object-like record at 0x0eb4.
• Actions 0x81 (display_view_resource_text_like) and 0xa2 (display_view_resource_text_like_var) use a stack-local 43-byte record.

That reuse is a strong signal that object rendering should be implemented against a common object/frame interface rather than only against persistent table entries.

Graphics and update operations

The picture decoder, object renderer, and display overlay operate on a logical graphics/control buffer segment stored at [0x136f]. The observed coordinate space is 0xa0 columns by 0xa8 rows.

Implementation-facing phases:

1. Picture preparation decodes picture command bytes into the logical buffer.
2. View binding selects frame data and dimensions for object records.
3. Placement validates object coordinates against screen bounds, the horizon-like line [0x012d], object-object crossing, and control-buffer classes.
4. Update-list builders partition active objects between roots 0x1703 and 0x16ff. Each root draws objects in ascending key order, where the key is baseline Y unless fixed-priority bit 0x0004 routes object byte +0x24 through the reverse-priority helper. Equal keys remain in object-table order, so later object-table entries draw later. Root 0x1703 is drawn completely before root 0x16ff.
5. Render nodes save backing rectangles, draw frame data, and later restore old rectangles during list flushes.
6. Display-overlay entries copy full-screen or rectangular regions from the logical buffer to display memory.

This implies a useful replacement architecture:

ResourceStore -> LogicVM -> ObjectTable -> PictureBuffer
                          -> RenderLists -> DisplayBackend

The original interpreter interleaves these concerns through global helpers, but the observed side effects line up with those separable components.

Implementation state machines

The source names and addresses are useful evidence, but a clean-room implementation should model the main runtime objects as small state machines. These states are implementation-facing summaries of the observed transitions; they are not claims about the exact original memory layout.

Top-level cycle:

The timer interrupt path is not inserted into this table as a synchronous phase. It advances the elapsed-time and pacing counters independently; the sound hook advances active sound before periodically chaining to the ordinary timer path. A host scheduler may represent these as queued tick events while preserving their state transitions relative to cycle boundaries.

Resource lifecycle:

Heap and allocation lifecycle:

Action 0x8e configures the replay log capacity. It writes data.event.pair_capacity, flushes update-list state, resets/allocates the pair buffer through code.event.reset_pair_buffer, clears the active pair count, and rebuilds update-list state.

Save/restore data model:

Save/restore selector state machine:

Gold Rush / AGI v3 keeps the five-block save-envelope shape but changes the object/inventory block written from [0x07d6] with length [0x07da]: action 0x7d applies a repeating Avis Durgan XOR key from data address DS:0x072c before the save path and applies the same transform again before return, so the on-disk block is transformed while runtime memory is restored. QEMU extractions validate this for both blank-prefix and signed saves: build/gr-v3-behavior/save_xor_extract_qemu_001.json writes SG.1, while build/gr-v3-behavior/save_xor_extract_signed_qemu_001.json executes 0x8f("GR"), writes GRSG.1, and confirms that the first saved-state block starts with GR\0. Both saves have block lengths 1028, 989, 1811, 100, and 12, and both third blocks change and round-trip under gr_v3_object_inventory_save_xor(). Source inspection shows the first block is the contiguous range DS:0x0002..0x0405, giving a byte-complete 1028-byte global-state partition with the same signature/variables/flags/timer/string roles as profile 2.936, an expanded 49-slot key map, no second 480-byte opaque string bank, and GR tail fields for the menu interaction and key-release gates. The observed GR OBJECT metadata decodes to item-table size 0x0189, maximum object index 22, and runtime payload length 0x0713; therefore the GR save uses 23 object records in block 2, 131 three-byte inventory entries plus a 1418-byte name pool in decoded block 3, 50 replay-pair slots in block 4, and the same four-byte logic-resume record grammar in block 5. The signed restore probe in build/gr-v3-behavior/signed_restore_roundtrip_suite.json uses a generated GRSG.1 from the original engine, restores it in a second fixture, and matches the restored capture to a direct saved-state control while differing from an unrestored control. Source inspection shows GR action 0x7e reads the same five length-prefixed blocks as SQ2, then applies the same repeating-key helper over [0x07d6]..[0x07d6]+[0x07da] after the third block has been loaded.

Restart, save/restore, and termination lifecycle:

Gold Rush / AGI v3 changes the prompt-marker redraw branch in action 0x80. It records data.input.prompt_marker_visible_state before erasing the marker; after confirmation it redraws the marker when restart was accepted or, for a canceled restart, only when the marker had been visible before entry. The local truth-table helper gr_v3_restart_redraws_prompt_marker() models this branch. QEMU report build/gr-v3-behavior/restart_prompt_marker_qemu_001.json confirms the canceled branch by comparing hidden and visible prompt-marker controls: hidden cancel left 0 prompt-row foreground pixels, while visible cancel restored the 8-pixel prompt glyph.

Picture decoder lifecycle:

View and cel drawing contract:

Persistent placement and movement accept a proposed object position only when the object-object crossing test accepts it and the control-buffer scan accepts the selected frame-width scanline. In the control scan, class 0x00 rejects immediately, class 0x10 requires object bit 0x0002, class 0x20 leaves final state (flag3=true, flag0=false), class 0x30 leaves final state (flag3=false, flag0=true), and other nonzero classes leave (flag3=false, flag0=false). The final scanned class, not an accumulated history of earlier cells, drives the post-scan 0x0100 and 0x0800 rejection bits and the global flag updates for objects whose byte +0x02 is zero. Priority/control byte 0x0f bypasses this scan.

Object drawing lifecycle:

Motion and animation lifecycle:

Gold Rush / AGI 3.002.149 source comparison adds two version-specific motion notes. First, object motion mode 4 dispatches to the same target-direction helper as mode 3; SQ2 treats modes above 3 as no autonomous-mode dispatch. The mode-4 dispatcher branch is now validated with an instrumented GR fixture: a copied interpreter under build/ changes action 0x51’s mode seed from 3 to 4, and QEMU shows the resulting capture matches the unmodified mode-3 target-movement capture while a stationary control does not. That confirms the internal dispatcher behavior, but the natural engine path that seeds mode 4 remains source-only rather than script-visible.

Second, GR’s automatic direction-to-loop selection changes the high group-count branch. Exactly-four-loop views use the four-plus direction table without an extra flag check, while views with more than four loops use that table only when flag 0x14 is set. QEMU report build/gr-v3-behavior/frame_selection_gate_qemu_001.json validates exact-four view 177 selecting group 1 for direction 6 whether flag 0x14 is clear or set, and more-than-four view 39 remaining on group 0 until flag 0x14 is set.

Text/input UI lifecycle:

Menu/list data model:

Gold Rush / AGI v3 adds one extra gate in front of the shared menu interaction path. Action 0xb1 stores its immediate byte in word [0x0403]; the GR code.menu.interact routine returns immediately while that word is zero, even if action 0xa1 has requested interaction. QEMU report build/gr-v3-behavior/menu_gate_suite.json validates this observable split: 0xb1(0) plus a menu request matches a blocked control, while 0xb1(1) plus the same request produces a distinct modal-menu capture.

Menu interaction lifecycle:

Text rectangle clears (0x69 and 0x9a) are display-surface operations. They do not decode or mutate a picture resource; they overwrite the visible text-cell rectangle with the requested attribute/background. In the EGA target validated so far, text columns are four logical pixels wide and text rows are eight logical pixels tall.

Status-line hide (0x71) and input-line disable (0x77) use the same visible text surface rather than the decoded picture buffer. In the normal EGA path, 0x71 clears the single row configured as the status row by 0x6f operand 2, and 0x77 clears the single row configured as the input row by 0x6f operand

1. The validated row geometry is eight logical pixels tall.

Input-line enable (0x78) also redraws the configured input row through the text surface before it writes any configured prompt/input strings. With an empty prompt marker and empty input buffers, the validated visible result is the same single eight-pixel-tall black row. Input-line erase (0x8a) uses repeated backspace handling to reduce visible input length [0x0ff8] to zero; QEMU validates that typed live-edit glyphs disappear from the configured input row. Input-line refresh (0x89) does not replay unaccepted live-edit characters in the observed path. After Enter copies accepted text into the source input buffer at 0x0fce, 0x89 repaints visible glyphs by copying that source into visible buffer 0x0fa4. Entering alternate text-attribute mode through 0x6a is broader: the observed EGA result clears the full logical surface using the current attribute pair and ordinary transient-object composition is not visible while that mode remains active in the probe. With the default pair this is a black clear. After 0x6d(0, 1), the disassembly shows the stored pair is reinterpreted by 0x6a with [0x1757] = 1 as packed text attribute 0xf0; QEMU validates a full-screen visual color 15 clear for that case.

The prompt marker configured by 0x6c is a single byte copied from the start of the resolved message. When that byte is zero, input-line redraw skips marker drawing. The current QEMU evidence covers the empty-message suppression path; nonempty prompt glyph shape is still a font/text-rendering detail rather than a fully modeled compatibility contract.

Menu interaction is another consumer of the shared event queue. Menu setup builds circular heading and item lists; each node’s word at offset +0x00 is the next pointer and +0x02 is the previous pointer. A heading’s item root is at +0x0c, its remembered/current item is at +0x0e, and its active/enabled word is at +0x0a. Item nodes store their enabled word at +0x0a and their script-visible selection id at +0x0c. Enter enqueues a type-3 event carrying that id only when the current item is enabled. Movement events use values 1..8: up/previous item, page-up/first item, right/next enabled heading, page-down/last item, down/next item, end/last heading, left/previous enabled heading, and home/root heading. After each movement, the engine persists the current heading and item in [0x1d2e] and [0x1d30].

Diagnostic and Trace Services

Several action opcodes are developer-facing or VM-facing services rather than ordinary game-world operations:

• 0x87 (show_heap_status) formats heap/script memory counters into a message box.
• 0x1d (show_priority_screen) temporarily swaps the high and low nibbles of every logical graphics-buffer byte during a full-screen refresh. The observed command phrase is show pri, and the displayed buffer is best modeled as a priority/control inspection view.
• 0x95 (enable_action_trace_window) and 0x96 (configure_action_trace_window) manage an action-trace window. When enabled, the dispatcher calls the trace formatter before each action handler. QEMU validates the enabled path as a red-bordered, white-filled trace window with black opcode/operand text. A new implementation can expose this as optional VM tracing rather than coupling it to normal game semantics.
• 0x8f (verify_game_signature) resolves a short message string and compares it against the interpreter’s embedded SQ2 signature. A mismatch calls the same restart/exit helper used by confirmation-gated exit paths.

UI, diagnostics, and device state

Several actions are better modeled as services around the VM rather than as game-world operations:

• The input line has an enabled flag at [0x05d3], a visible/input buffer at 0x0fa4, an entered source buffer at 0x0fce, and a length word at [0x0ff8]. Actions 0x77, 0x78, 0x89, and 0x8a disable, enable, refresh, and erase that line.
• Action 0x88 is a pause dialog. It stops sound, displays a fixed pause message, and returns to the script after the display helper completes.
• Action 0x87 is a heap/status diagnostic. It formats heap and script-budget globals into a message, so a replacement implementation can expose it as a diagnostic overlay without tying it to game state.
• Action 0x6e is a transient display shake. In the normal path it does not mutate the logical picture/object buffers; it writes CRT/display-register offsets from a small table and waits on timer ticks. A portable implementation can model the observable contract as a short camera/display offset animation with no persistent surface change.
• Action 0x8b is joystick calibration. It presents a centered-joystick prompt, samples joystick state through helpers around 0x63be and 0x6425, and stores calibrated bounds in globals near 0x15c9..0x15cf.
• Action 0x8c toggles bit 0 of display mode word [0x1130] when the current hardware/display configuration allows it, then rebuilds display state.