OpenMaidEngine/vm-map/engine-ctx.toml

# vm-map/engine-ctx.toml -- CANONICAL source for the EngineCtx struct (hand-edited).
# Generated: build/engine-ctx.json + docs/engine-ctx-reference.md via `tools/engine_ctx_build.py --build`.
# Applied to the Ghidra /v2 image via run_script_inline (docs/superpowers/plans/2026-07-09-engine-ctx-struct.md).
# ctx = the engine context (esi; thiscall `this`). The VM global bank G[...] is a SEPARATE address space
# (vm-map/globals.toml), NOT ctx offsets -- do not add globals here. Grows one [[field]] at a time as we RE more.
[meta]
struct_name = "EngineCtx"
size = 0xa1000

[[field]]
offset = 0x814
name = "input_action_count"
type = "int"
note = "logical action count (0..31); op 0xfe sets it, op 0x100 scans actions below it and uses callback slot count itself when the polled mask is empty"
[[field]]
offset = 0x898
name = "joystick_physical_button_count"
type = "int"
note = "WinMM JOYCAPS physical button count returned by op 0x106"
[[field]]
offset = 0x89c
name = "joystick_button_map"
type = "int"
note = "base of 32-entry logical button-slot to physical joystick-button table; op 0x107 writes it, slot N emits action N+4"
[[field]]
offset = 0x135c
name = "mouse_button_action_map"
type = "int"
note = "base of physical mouse-button to logical button-slot table; op 0x10b writes it and polling adds 4 to obtain the action index"
[[field]]
offset = 0x13dc
name = "message_skip_enabled"
type = "int"
note = "persistent all-message Skip flag; op 0x88 writes it and adv_interpreter_tick injects input bit 0x40 while nonzero"
[[field]]
offset = 0x1428
name = "keyboard_vk_action_map"
type = "int"
note = "base of 256-entry Win32 virtual-key to logical action table consumed by keyboard polling"
[[field]]
offset = 0x1828
name = "dik_to_vk_table"
type = "int"
note = "base of 256-entry DirectInput DIK scan-code to Win32 virtual-key translation used by op 0x10c"
[[field]]
offset = 0x1c34
name = "mouse_wheel_delta"
type = "int"
note = "signed WM_MOUSEWHEEL delta accumulated by age_main_window_proc; op 0x10d returns and clears it"
[[field]]
offset = 0x144e0
name = "sfx_channel_resource_ids"
type = "int"
note = "base of ten packed resource ids retained by the sound-effect facade; op 0xb4 loads a channel, op 0xb6 clears it, and numbered-save layouts restore then reopen every positive id"
[[field]]
offset = 0x14d54
name = "gfx_obj_ptr_table"
type = "void*"
note = "per-object pointer table (ops 0x212/0x213 write obj+0x64/0x68/0x6c)"
[[field]]
offset = 0x14e08
name = "gfx_default_object_slot"
type = "int"
note = "op 0x80 selected slot; op 0x1d9 substitutes it when its explicit object-slot operand is zero"
[[field]]
offset = 0x14ea0
name = "text_line_spacing"
type = "int"
note = "extra pixel leading between text lines; defaults to 6, op 0x8b writes it"
[[field]]
offset = 0x14f45
name = "script_frame_index"
type = "int"
note = "call-script frame index (0x1e-dword frames)"
[[field]]
offset = 0x46188
name = "renderer_device_state"
type = "int"
note = "embedded D3D9 device/render state; op 0x20e passes this base to the target/depth clear worker"
[[field]]
offset = 0x46598
name = "d3d9_device"
type = "void*"
note = "IDirect3DDevice9 pointer at renderer_device_state+0x410; op 0x20e invokes vtable Clear +0xac"
[[field]]
offset = 0x46614
name = "retained_gfx_manager"
type = "int"
note = "embedded retained graphics manager passed by gfx opcode handlers; worker offsets are relative to this base"
[[field]]
offset = 0x46a1c
name = "gfx_obj_registry"
type = "int"
note = "retained_gfx_manager+0x408 std::map handle->object; 0x1f6 clears, geometry/draw get-or-create, 0x215 queries, 0x1f7 erases"
[[field]]
offset = 0x46d14
name = "query_table_46d14"
type = "void*"
note = "stride-0x14 table read by op 0x216"
[[field]]
offset = 0x4d7c
name = "shared_profile_state"
type = "void*"
note = "embedded shared SAVE.DAT state object; owns profile integer/settings tables and container timing metadata"
[[field]]
offset = 0x5190
name = "shared_profile_int_table"
type = "int"
note = "open-addressing 12-byte string-key to 32-bit value table; op 0x1a2 stores, 0x1a3 loads, shared SAVE.DAT serializes it"
[[field]]
offset = 0x50ba4
name = "gfx_render_target_table"
type = "void*"
note = "retained_gfx_manager+0xa590 array of per-slot D3D texture wrappers selected by op 0x20d"
[[field]]
offset = 0x51b64
name = "frame_timer_current"
type = "int"
note = "current shared millisecond presentation timestamp at retained_gfx_manager+0xb550; active outer-engine ticks and op 0x23c sample timeGetTime, and every retained animation channel samples it"
[[field]]
offset = 0x51b68
name = "frame_timer_previous"
type = "int"
note = "previous shared presentation timestamp at retained_gfx_manager+0xb554; shifted from current before each new sample, and op 0x231 compares current/previous source cells to raise redraw dirty only at cell changes"
[[field]]
offset = 0x51b78
name = "anim_clock_start"
type = "int"
note = "start timestamp for the separate finite-animation service window at retained_gfx_manager+0xb564; seeded from frame_timer_current by gfx_animation_service_poll, while op 0x238, op 0x243, and object reset 0x1f6 zero it"
[[field]]
offset = 0x51b7c
name = "anim_clock_duration"
type = "int"
note = "global anim clock duration at retained_gfx_manager+0xb568; op 0x238 sets and object reset 0x1f6 zeroes it"
[[field]]
offset = 0x51b44
name = "gfx_current_render_target"
type = "int"
note = "retained_gfx_manager+0xb530 selected surface slot; -1 denotes device backbuffer"
[[field]]
offset = 0x51b6c
name = "gfx_dirty_a"
type = "int"
note = "retained_gfx_manager+0xb558 redraw-dirty flag; retained mutations and continuous channels set it, while op 0x231 sets it only when the sampled source cell differs across the shared current/previous frame timestamps; op 0x1f6 clears it"
[[field]]
offset = 0x51b70
name = "gfx_force_complete"
type = "int"
note = "retained_gfx_manager+0xb55c requests forced completion of one-shot channels; op 0x1f6 clears it"
[[field]]
offset = 0x51b74
name = "gfx_dirty_b"
type = "int"
note = "retained_gfx_manager+0xb560 blocking-presentation dirty flag; active finite object channels set it unless obj+0x2d0 bit 0 detaches them"
[[field]]
offset = 0x51b80
name = "gfx_animation_service_flags"
type = "uint"
note = "retained_gfx_manager+0xb56c service flags; bit 1 suppresses op 0x243 force-complete/clock-reset request"
[[field]]
offset = 0x52bd4
name = "surfaces"
type = "void*"
note = "surface array base [~1000 slots]; create/set-texture (0x1f8/0x1f9) allocate"
[[field]]
offset = 0x53d14
name = "cur_ctx_index"
type = "uint"
note = "current script-context index (curCtx); indexes 0x78-byte coroutine/frame records"
[[field]]
offset = 0x53d24
name = "save_load_stack_restore_active"
type = "int"
note = "set while a deserialized numbered-save script stack is being reconstructed; op 0xae restores saved frame PCs/contexts and clears it at the terminal saved context"
[[field]]
offset = 0x53d28
name = "frame_codebase"
type = "void*"
note = "current frame codebase (PC = codebase + off*4)"
[[field]]
offset = 0x53d2c
name = "frame_pc"
type = "int"
note = "current frame PC column (op = *(0x53d2c + curCtx*0x78))"
[[field]]
offset = 0x53d60
name = "ctx_record_base"
type = "void*"
note = "0x78-byte context-record array base (coroutine/script contexts)"
[[field]]
offset = 0x53d64
name = "frame_script_resource_id"
type = "uint"
note = "raw packed SYS4/AAI resource id for this 0x78-byte script frame; persisted ReadTextDB script key"
[[field]]
offset = 0x53d88
name = "frame_instruction_word_count"
type = "int"
note = "current decoded instruction length in dwords for each 0x78-byte script frame; interpreter advances PC by this value * 4"
[[field]]
offset = 0x54ff0
name = "initial_root_run"
type = "int"
note = "initialized to 1 at AGE context construction; queried by op 0x130 and cleared by op 0x9 before root script id 0 is reloaded"
[[field]]
offset = 0x550fc
name = "message_skip_display_enabled"
type = "int"
note = "persistent all-message Skip state returned by op 0x19a for the ADV control-strip active overlay"
[[field]]
offset = 0x55100
name = "adv_skip_service_enabled"
type = "int"
note = "ADV presentation lifecycle gate: op 0x19b clears it while preserving the persistent Skip toggle; op 0x19c sets it before recomputing active message/read skip"
[[field]]
offset = 0x55104
name = "auto_message_enabled"
type = "int"
note = "ADV Auto mode flag; op 0x1b6 reads, op 0x1b7 writes, adv_input_service_poll consumes"
[[field]]
offset = 0x55110
name = "text_history_recording_suppressed"
type = "uint"
note = "high bit suppresses ADV retained-history index/text/metadata/voice recording; op 0x1bb writes 0x80000000 or zero, and HISTORY.BIN brackets itself with disable/enable"
[[field]]
offset = 0x55120
name = "anti_tamper_a"
type = "int"
note = "anti-tamper checksum operand"
[[field]]
offset = 0x55124
name = "anti_tamper_b"
type = "int"
note = "anti-tamper checksum operand"
[[field]]
offset = 0x5512c
name = "anti_tamper_fp"
type = "int"
note = "anti-tamper (import fn ptr / result)"
[[field]]
offset = 0x55248
name = "ret_stack_a"
type = "void*"
note = "per-frame return stack (op 0x8f call pushes)"
[[field]]
offset = 0x552e8
name = "ret_stack_b"
type = "void*"
note = "per-frame return stack (companion)"
[[field]]
offset = 0x5f304
name = "sleep_timer"
type = "int"
note = "sleep timer object (op 0xc8; +8 active, +0x14 start-ms, +0x18 duration)"
[[field]]
offset = 0x5f3ac
name = "timed_callback_timer"
type = "int"
note = "elapsed timer object armed by op 0xd5 and sampled by the timed callback scheduler"
[[field]]
offset = 0x5f64c
name = "adv_wait_indicator_timer"
type = "int"
note = "elapsed timer started by op 0x1ce and ADV wait setup to select the animated input-wait indicator frame"
[[field]]
offset = 0x5f690
name = "timed_callback_abort_pc"
type = "int"
note = "optional local fallback PC supplied to op 0xd5; -1 disables abort redirection"
[[field]]
offset = 0x5f694
name = "timed_callback_entries_vector"
type = "int"
note = "MSVC vector object base for 16-byte schedule entries; begin/end/capacity pointers follow"
[[field]]
offset = 0x5f698
name = "timed_callback_entries_begin"
type = "void*"
note = "begin pointer for 16-byte entries {deadline_ms, field_100, primary_pc, catchup_pc}"
[[field]]
offset = 0x5f69c
name = "timed_callback_entries_end"
type = "void*"
note = "end pointer for the timed callback entry vector"
[[field]]
offset = 0x5f6a0
name = "timed_callback_entries_capacity"
type = "void*"
note = "capacity-end pointer for the timed callback entry vector"
[[field]]
offset = 0x5f6a4
name = "timed_callback_last_index"
type = "int"
note = "last appended schedule index; op 0xd3 resets to -1 and op 0xd4 increments per entry"
[[field]]
offset = 0x5f6a8
name = "timed_callback_cursor"
type = "int"
note = "next schedule entry consumed by timed_callback_sequence_tick; op 0xd3 resets to zero"
[[field]]
offset = 0x5f6b4
name = "timed_callback_script_resource_id"
type = "uint"
note = "active frame script resource retained by op 0xd5 for local callback dispatch safety"
[[field]]
offset = 0x5f6b8
name = "timed_callback_script_resource_guard"
type = "uint"
note = "companion current-script identity checked before redirecting to a scheduled callback"
[[field]]
offset = 0x5f6c0
name = "value_switch_table"
type = "int"
note = "temporary formatted-value branch table reset by 0xa1, populated by 0xa2, queried by 0xa3; distinct from shared_profile_int_table"
[[field]]
offset = 0x5f72c
name = "adv_wait_indicator_frame"
type = "int"
note = "current animated input-wait indicator frame, reset to zero when the service is armed"
[[field]]
offset = 0x5f730
name = "adv_wait_indicator_terminal_frame"
type = "int"
note = "terminal frame returned by the indicator layout during ADV wait setup"
[[field]]
offset = 0x5f734
name = "adv_wait_indicator_enabled_value"
type = "int"
note = "raw enable operand last written by op 0x1ce; nonzero arms the ADV wait-indicator service"
[[field]]
offset = 0x6da6c
name = "input_callback_scan_index"
type = "int"
note = "op 0xff resets this to zero; op 0x100 advances it while scanning set action bits below input_action_count"
[[field]]
offset = 0x6da70
name = "input_action_count_snapshot"
type = "int"
note = "op 0xff copies input_action_count here when beginning a callback poll/dispatch pass"
[[field]]
offset = 0x6da78
name = "message_skip_activation_guard"
type = "int"
note = "set when op 0x88 enables Skip; suppresses the enabling click from immediately becoming a hotspot activation"
[[field]]
offset = 0x6da80
name = "message_skip_cancel_click_phase"
type = "int"
note = "press/release phase used only when set:CancelMesSkipOnClick is nonzero"
[[field]]
offset = 0x6da84
name = "adv_wait_indicator_layout_slot"
type = "int"
note = "ADV text layout whose wait indicator is armed or erased by input-wait setup and op 0x1ce"
[[field]]
offset = 0x6da88
name = "coroutine_yield_a"
type = "void*"
note = "op 0x7b yield-state save (op1 -> +ctxidx*4)"
[[field]]
offset = 0x6db28
name = "coroutine_yield_b"
type = "void*"
note = "op 0x7b yield-state save (op2 -> +ctxidx*4)"
[[field]]
offset = 0x6dbc8
name = "coroutine_runstate"
type = "int"
note = "op 0x7c resume gate (run-state bit 0x2000000)"
[[field]]
offset = 0x6dbcc
name = "coroutine_resume_off"
type = "int"
note = "op 0x7c resume PC offset"
[[field]]
offset = 0x6dbd4
name = "adv_read_skip_state"
type = "int"
note = "current ADV read/click-skip service state; queried by op 0x1cc, maintained from ReadTextSkip + per-PC read history"
[[field]]
offset = 0x6dbe4
name = "adv_auto_voice_pending"
type = "int"
note = "set by play-voice ops when voice service exists; Auto waits for voice completion then arms AutoMessageTime0; op 0x1bc resets"
[[field]]
offset = 0x6dbe8
name = "voice_bgm_duck_saved_volume"
type = "int"
note = "BGM volume saved by the voice-start duck helper before applying MusicFadeOnVoicePlayingVol"
[[field]]
offset = 0x6dbf0
name = "voice_bgm_duck_control_flags"
type = "uint"
note = "transient mask replaced by op 0x1cf; bit 0 suppresses automatic voice-triggered BGM attenuation"
[[field]]
offset = 0x6dbf4
name = "message_skip_queued_voice_id"
type = "int"
note = "latest voice resource deferred by op 0xc4 while run_state_flags message-skip bit is active"
[[field]]
offset = 0x6dbf8
name = "message_skip_queued_voice_arg"
type = "int"
note = "second argument retained with message_skip_queued_voice_id; Himegari op 0xc4 stores zero"
[[field]]
offset = 0x6f89c
name = "script_launch_queue"
type = "int"
note = "embedded integer FIFO used for engine-level auxiliary/root script launches; data pointer and queue indices follow"
[[field]]
offset = 0x6f8a0
name = "script_launch_queue_data"
type = "void*"
note = "dword storage for packed script ids or negative frame-resume ids"
[[field]]
offset = 0x6f8a4
name = "script_launch_queue_read_cursor"
type = "int"
note = "next queued launch consumed by script_launch_queue_dispatch_next"
[[field]]
offset = 0x6f8a8
name = "script_launch_queue_write_cursor"
type = "int"
note = "one-past-last queued launch; op 0x143 appends mounted selector record-zero ids here"
[[field]]
offset = 0x6f8ac
name = "script_launch_queue_capacity"
type = "int"
note = "allocated dword capacity; initialized to 0x100"
[[field]]
offset = 0x6f8b0
name = "script_launch_queue_growth"
type = "int"
note = "capacity growth quantum; initialized to 0x100"
[[field]]
offset = 0x6f8b4
name = "script_launch_queue_high_water"
type = "int"
note = "highest consumed cursor retained across FIFO compaction"
[[field]]
offset = 0x6f8b8
name = "script_launch_dispatch_active"
type = "int"
note = "suppresses immediate dispatch while op 0x143 batches mounted append record-zero ids and while a queued script is active"
[[field]]
offset = 0x9928c
name = "save_frame_boundary_index"
type = "int"
note = "highest script-frame index included by numbered-save layouts 2/3; -1 falls back to cur_ctx_index; op 0x1ad marks current frame and op 0x2 clears after unwinding below it"
[[field]]
offset = 0x9b24c
name = "dispatch_table"
type = "void*"
note = "opcode->handler table base [0x400]; handler(op) = *(0x9b24c + op*4)"
[[field]]
offset = 0x9c658
name = "sys4ini_count"
type = "int"
note = "SYS4INI record count at embedded FileDB+0x40c"
[[field]]
offset = 0x9c65c
name = "archive_name_table"
type = "void*"
note = "archive-name table base at embedded FileDB+0x410; arc_id*0x100 indexes it"
[[field]]
offset = 0x9c660
name = "sys4ini_records"
type = "void*"
note = "SYS4INI 80-byte record base at embedded FileDB+0x414; record = base + id*0x50"
[[field]]
offset = 0x9f274
name = "mounted_aai_catalogs"
type = "void*"
note = "base of 256-entry selector-keyed AAI catalog-pointer table inside the embedded FileDB; op 0x143 scans slots 1..255 from +0x9f278"
[[field]]
offset = 0x9f278
name = "mounted_aai_catalog_selector_1"
type = "void*"
note = "selector-one cell and op 0x143 scan start; subsequent dwords are selector 2..255"
[[field]]
offset = 0xa0b84
name = "current_bgm_track_id"
type = "int"
note = "direct-name BGM track id retained by the music facade; op 0xbf starts/replaces it, ops 0xc0/0xc3 get/set it, and numbered-save layouts restore it"
[[field]]
offset = 0xa0cc0
name = "screen_w"
type = "int"
note = "logical screen width; constructor/default registry uses 640, then the SYS4INI SCREENX setting overrides it (Himegari 800)"
[[field]]
offset = 0xa0cc4
name = "screen_h"
type = "int"
note = "logical screen height; constructor/default registry uses 480, then the SYS4INI SCREENY setting overrides it (Himegari 600)"
[[field]]
offset = 0xa0cc8
name = "screen_bpp"
type = "int"
note = "screen bpp (8)"
[[field]]
offset = 0xa0ce4
name = "run_state_flags"
type = "uint"
note = "interpreter run-state flags (bit1 sleeping; 0x8000000 skip/fast-forward)"
[[field]]
offset = 0xa0ce8
name = "timed_callback_abort_signal"
type = "int"
note = "scheduler-polled abort/input signal cleared when op 0xd5 starts; redirects to abort PC when configured"