From c3729170dcbde05292f02ba2dd5ce7cd31eb1dbb Mon Sep 17 00:00:00 2001 From: gamer147 Date: Thu, 9 Jul 2026 10:01:54 -0400 Subject: [PATCH] re: EngineCtx field registry (engine-ctx.toml) + builder Canonical source vm-map/engine-ctx.toml (35 documented ctx fields) + engine_ctx_build.py (--build/--lint, unit-tested) -> build/engine-ctx.json + docs/engine-ctx-reference.md. Applied to Ghidra in the next task. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/engine-ctx-reference.md | 43 ++++++++ tools/engine_ctx_build.py | 85 ++++++++++++++++ tools/test_engine_ctx.py | 61 ++++++++++++ vm-map/engine-ctx.toml | 184 +++++++++++++++++++++++++++++++++++ 4 files changed, 373 insertions(+) create mode 100644 docs/engine-ctx-reference.md create mode 100644 tools/engine_ctx_build.py create mode 100644 tools/test_engine_ctx.py create mode 100644 vm-map/engine-ctx.toml diff --git a/docs/engine-ctx-reference.md b/docs/engine-ctx-reference.md new file mode 100644 index 0000000..cfa5f78 --- /dev/null +++ b/docs/engine-ctx-reference.md @@ -0,0 +1,43 @@ +# EngineCtx field reference + +> Generated from `vm-map/engine-ctx.toml` by `tools/engine_ctx_build.py --build`. Do not edit. + +Struct `EngineCtx`, size `0xa1000`. Applied to the Ghidra `/v2` image (dispatch-handler `this` = `EngineCtx *`). + +| offset | name | type | note | +|---|---|---|---| +| `0x408` | `gfx_obj_registry` | `int` | gfx object registry (std::map handle->object); op 0x1a2 insert / 0x215 find | +| `0x40c` | `sys4ini_count` | `int` | SYS4INI record count | +| `0x410` | `archive_name_table` | `void*` | archive-name table base (arc_id*0x100 indexes it) | +| `0x414` | `sys4ini_records` | `void*` | SYS4INI 80-byte record base {name[64],arc_id,file_number,offset,size}; record = base + id*0x50 | +| `0x3028` | `alt_pack_table` | `int` | call-script high-byte alternate pack table (unused by corpus) | +| `0xb558` | `gfx_dirty_a` | `int` | gfx dirty flag (anim set raises) | +| `0xb560` | `gfx_dirty_b` | `int` | gfx dirty flag | +| `0x14d54` | `gfx_obj_ptr_table` | `void*` | per-object pointer table (ops 0x212/0x213 write obj+0x64/0x68/0x6c) | +| `0x14f45` | `script_frame_index` | `int` | call-script frame index (0x1e-dword frames) | +| `0x46d14` | `query_table_46d14` | `void*` | stride-0x14 table read by op 0x216 | +| `0x51b64` | `frame_timer` | `int` | frame timer (present updates 0x51b64/0x51b68) | +| `0x51b78` | `anim_clock_elapsed` | `int` | global anim clock elapsed (op 0x238 zeroes) | +| `0x51b7c` | `anim_clock_duration` | `int` | global anim clock total duration (op 0x238 sets) | +| `0x52bd4` | `surfaces` | `void*` | surface array base [~1000 slots]; create/set-texture (0x1f8/0x1f9) allocate | +| `0x53d14` | `cur_ctx_index` | `uint` | current gfx-object / script-context index (curCtx); indexes 0x78-byte records | +| `0x53d28` | `frame_codebase` | `void*` | current frame codebase (PC = codebase + off*4) | +| `0x53d2c` | `frame_pc` | `int` | current frame PC column (op = *(0x53d2c + curCtx*0x78)) | +| `0x53d60` | `ctx_record_base` | `void*` | 0x78-byte context-record array base (coroutine/script contexts) | +| `0x53d64` | `gfx_obj_record_array` | `void*` | gfx object-record array (field[0]=0xffffffff free; cmd-type at rec+0x24) | +| `0x53d88` | `cmd_type_table` | `int` | per-object cmd-type column base (write *(0x53d88 + curCtx*0x78)) | +| `0x55120` | `anti_tamper_a` | `int` | anti-tamper checksum operand | +| `0x55124` | `anti_tamper_b` | `int` | anti-tamper checksum operand | +| `0x5512c` | `anti_tamper_fp` | `int` | anti-tamper (import fn ptr / result) | +| `0x55248` | `ret_stack_a` | `void*` | per-frame return stack (op 0x8f call pushes) | +| `0x552e8` | `ret_stack_b` | `void*` | per-frame return stack (companion) | +| `0x5f304` | `sleep_timer` | `int` | sleep timer object (op 0xc8; +8 active, +0x14 start-ms, +0x18 duration) | +| `0x6da88` | `coroutine_yield_a` | `void*` | op 0x7b yield-state save (op1 -> +ctxidx*4) | +| `0x6db28` | `coroutine_yield_b` | `void*` | op 0x7b yield-state save (op2 -> +ctxidx*4) | +| `0x6dbc8` | `coroutine_runstate` | `int` | op 0x7c resume gate (run-state bit 0x2000000) | +| `0x6dbcc` | `coroutine_resume_off` | `int` | op 0x7c resume PC offset | +| `0x9b24c` | `dispatch_table` | `void*` | opcode->handler table base [0x400]; handler(op) = *(0x9b24c + op*4) | +| `0xa0cc0` | `screen_w` | `int` | screen width (640) | +| `0xa0cc4` | `screen_h` | `int` | screen height (480) | +| `0xa0cc8` | `screen_bpp` | `int` | screen bpp (8) | +| `0xa0ce4` | `run_state_flags` | `uint` | interpreter run-state flags (bit1 sleeping; 0x8000000 skip/fast-forward) | diff --git a/tools/engine_ctx_build.py b/tools/engine_ctx_build.py new file mode 100644 index 0000000..4005881 --- /dev/null +++ b/tools/engine_ctx_build.py @@ -0,0 +1,85 @@ +"""Build the EngineCtx struct artifacts from vm-map/engine-ctx.toml (single source of truth). + + py -3.11 -X utf8 tools/engine_ctx_build.py --build # -> build/engine-ctx.json + docs/engine-ctx-reference.md + py -3.11 -X utf8 tools/engine_ctx_build.py --lint # checks only (overlap / out-of-bounds / dup name / type) + +The struct is APPLIED to the Ghidra /v2 image via run_script_inline reading build/engine-ctx.json +(see docs/superpowers/plans/2026-07-09-engine-ctx-struct.md). ctx = engine context (esi / thiscall this); +the VM global bank G[...] is a separate space (vm-map/globals.toml), never added here. +""" +import json +import sys +import tomllib +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent +TYPE_SIZES = {"int": 4, "uint": 4, "void*": 4} + + +def load(toml_text): + d = tomllib.loads(toml_text) + fields = [{"offset": int(f["offset"]), "name": f["name"], "type": f["type"], "note": f.get("note", "")} + for f in d.get("field", [])] + fields.sort(key=lambda f: f["offset"]) + return {"meta": d["meta"], "fields": fields} + + +def lint(model): + errs, size = [], int(model["meta"]["size"]) + seen_names, prev = {}, None + for f in model["fields"]: + sz = TYPE_SIZES.get(f["type"]) + if sz is None: + errs.append(f"unknown type {f['type']!r} for {f['name']}") + sz = 4 + if f["offset"] + sz > size: + errs.append(f"field {f['name']} @0x{f['offset']:x} out of bounds (size 0x{size:x})") + if f["name"] in seen_names: + errs.append(f"duplicate name {f['name']!r}") + seen_names[f["name"]] = True + if prev is not None and f["offset"] < prev["end"]: + errs.append(f"overlap: {f['name']} @0x{f['offset']:x} into {prev['name']} (ends 0x{prev['end']:x})") + prev = {"name": f["name"], "end": f["offset"] + sz} + return errs + + +def emit_json(model): + return {"meta": model["meta"], + "fields": {hex(f["offset"]): {"name": f["name"], "type": f["type"]} for f in model["fields"]}} + + +def emit_reference_md(model): + lines = ["# EngineCtx field reference", "", + "> Generated from `vm-map/engine-ctx.toml` by `tools/engine_ctx_build.py --build`. Do not edit.", + "", f"Struct `{model['meta']['struct_name']}`, size `0x{int(model['meta']['size']):x}`. " + "Applied to the Ghidra `/v2` image (dispatch-handler `this` = `EngineCtx *`).", "", + "| offset | name | type | note |", "|---|---|---|---|"] + for f in model["fields"]: + lines.append(f"| `0x{f['offset']:x}` | `{f['name']}` | `{f['type']}` | {f['note']} |") + return "\n".join(lines) + "\n" + + +def main(): + text = (REPO / "vm-map" / "engine-ctx.toml").read_text(encoding="utf-8") + model = load(text) + errs = lint(model) + if errs: + print("LINT ERRORS:") + for e in errs: + print(" " + e) + return 1 + if "--lint" in sys.argv[1:]: + print(f"lint clean: {len(model['fields'])} fields") + return 0 + if "--build" in sys.argv[1:]: + (REPO / "build" / "engine-ctx.json").write_text( + json.dumps(emit_json(model), indent=2) + "\n", encoding="utf-8") + (REPO / "docs" / "engine-ctx-reference.md").write_text(emit_reference_md(model), encoding="utf-8") + print(f"built {len(model['fields'])} fields -> build/engine-ctx.json + docs/engine-ctx-reference.md") + return 0 + print(__doc__) + return 2 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/test_engine_ctx.py b/tools/test_engine_ctx.py new file mode 100644 index 0000000..3c22706 --- /dev/null +++ b/tools/test_engine_ctx.py @@ -0,0 +1,61 @@ +"""Unit tests for the EngineCtx builder (tools/engine_ctx_build.py). + +Run: py -3.11 -X utf8 tools/test_engine_ctx.py (plain runner, no pytest). +""" +import sys + +from engine_ctx_build import load, lint, emit_json + +FAILS = [] + + +def check(cond, msg): + if not cond: + FAILS.append(msg) + print("FAIL:", msg) + else: + print("ok:", msg) + + +GOOD = ('[meta]\nstruct_name="EngineCtx"\nsize=0x1000\n' + '[[field]]\noffset=0x10\nname="a"\ntype="int"\nnote="x"\n' + '[[field]]\noffset=0x20\nname="b"\ntype="void*"\nnote="y"\n') + + +def test_load_and_emit(): + j = emit_json(load(GOOD)) + check(j["fields"]["0x10"]["name"] == "a" and j["meta"]["struct_name"] == "EngineCtx", + "emit_json keys fields by hex offset + carries meta") + + +def test_lint_clean(): + check(lint(load(GOOD)) == [], "clean model lints with no errors") + + +def test_lint_catches_overlap(): + bad = ('[meta]\nstruct_name="E"\nsize=0x1000\n' + '[[field]]\noffset=0x10\nname="a"\ntype="int"\nnote=""\n' + '[[field]]\noffset=0x12\nname="b"\ntype="int"\nnote=""\n') # 0x10+4 > 0x12 -> overlap + check(any("overlap" in e.lower() for e in lint(load(bad))), "lint flags overlapping fields") + + +def test_lint_catches_oob_and_dupname(): + bad = ('[meta]\nstruct_name="E"\nsize=0x14\n' + '[[field]]\noffset=0x10\nname="a"\ntype="int"\nnote=""\n' + '[[field]]\noffset=0x40\nname="a"\ntype="int"\nnote=""\n') # 0x40 > size AND dup name + errs = lint(load(bad)) + check(any("out of bounds" in e.lower() for e in errs) and any("duplicate" in e.lower() for e in errs), + "lint flags out-of-bounds offset and duplicate name") + + +def main(): + test_load_and_emit() + test_lint_clean() + test_lint_catches_overlap() + test_lint_catches_oob_and_dupname() + print("FAILURES:", len(FAILS)) + return 1 if FAILS else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/vm-map/engine-ctx.toml b/vm-map/engine-ctx.toml new file mode 100644 index 0000000..648fa75 --- /dev/null +++ b/vm-map/engine-ctx.toml @@ -0,0 +1,184 @@ +# 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 = 0x408 +name = "gfx_obj_registry" +type = "int" +note = "gfx object registry (std::map handle->object); op 0x1a2 insert / 0x215 find" +[[field]] +offset = 0x40c +name = "sys4ini_count" +type = "int" +note = "SYS4INI record count" +[[field]] +offset = 0x410 +name = "archive_name_table" +type = "void*" +note = "archive-name table base (arc_id*0x100 indexes it)" +[[field]] +offset = 0x414 +name = "sys4ini_records" +type = "void*" +note = "SYS4INI 80-byte record base {name[64],arc_id,file_number,offset,size}; record = base + id*0x50" +[[field]] +offset = 0x3028 +name = "alt_pack_table" +type = "int" +note = "call-script high-byte alternate pack table (unused by corpus)" +[[field]] +offset = 0xb558 +name = "gfx_dirty_a" +type = "int" +note = "gfx dirty flag (anim set raises)" +[[field]] +offset = 0xb560 +name = "gfx_dirty_b" +type = "int" +note = "gfx dirty flag" +[[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 = 0x14f45 +name = "script_frame_index" +type = "int" +note = "call-script frame index (0x1e-dword frames)" +[[field]] +offset = 0x46d14 +name = "query_table_46d14" +type = "void*" +note = "stride-0x14 table read by op 0x216" +[[field]] +offset = 0x51b64 +name = "frame_timer" +type = "int" +note = "frame timer (present updates 0x51b64/0x51b68)" +[[field]] +offset = 0x51b78 +name = "anim_clock_elapsed" +type = "int" +note = "global anim clock elapsed (op 0x238 zeroes)" +[[field]] +offset = 0x51b7c +name = "anim_clock_duration" +type = "int" +note = "global anim clock total duration (op 0x238 sets)" +[[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 gfx-object / script-context index (curCtx); indexes 0x78-byte records" +[[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 = "gfx_obj_record_array" +type = "void*" +note = "gfx object-record array (field[0]=0xffffffff free; cmd-type at rec+0x24)" +[[field]] +offset = 0x53d88 +name = "cmd_type_table" +type = "int" +note = "per-object cmd-type column base (write *(0x53d88 + curCtx*0x78))" +[[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 = 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 = 0x9b24c +name = "dispatch_table" +type = "void*" +note = "opcode->handler table base [0x400]; handler(op) = *(0x9b24c + op*4)" +[[field]] +offset = 0xa0cc0 +name = "screen_w" +type = "int" +note = "screen width (640)" +[[field]] +offset = 0xa0cc4 +name = "screen_h" +type = "int" +note = "screen height (480)" +[[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)"