From e899d06fd840aa5f3a6b954aab1e25fc26c478ee Mon Sep 17 00:00:00 2001 From: gamer147 Date: Fri, 10 Jul 2026 09:45:52 -0400 Subject: [PATCH] docs: archive EngineCtx design and implementation plan --- .../plans/2026-07-09-engine-ctx-struct.md | 451 ++++++++++++++++++ .../2026-07-09-engine-ctx-struct-design.md | 112 +++++ 2 files changed, 563 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-09-engine-ctx-struct.md create mode 100644 docs/superpowers/specs/2026-07-09-engine-ctx-struct-design.md diff --git a/docs/superpowers/plans/2026-07-09-engine-ctx-struct.md b/docs/superpowers/plans/2026-07-09-engine-ctx-struct.md new file mode 100644 index 0000000..db2400b --- /dev/null +++ b/docs/superpowers/plans/2026-07-09-engine-ctx-struct.md @@ -0,0 +1,451 @@ +# EngineCtx Struct — Implementation Plan + +**Status:** completed 2026-07-09 in `3826064` and `0ecd776`. This is the archived execution plan; +checkboxes below are preserved as originally authored. + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Type the engine context as a Ghidra `EngineCtx` struct sourced from a canonical `vm-map/engine-ctx.toml`, and retype the dispatch handlers' `this` so they decompile `ctx->field` instead of magic offsets. + +**Architecture:** Single source of truth (`engine-ctx.toml`) → generator (`engine_ctx_build.py`) emits `build/engine-ctx.json` + `docs/engine-ctx-reference.md` → a `run_script_inline` pass builds the `EngineCtx` struct and retypes handler `this` params on `/v2`. Pure model/lint/emit logic is unit-tested; the applied result is validated by decompiling two handlers. + +**Tech Stack:** Python 3.11 (`py -3.11 -X utf8`, `tomllib`), ghidra-mcp `run_script_inline` (Java; `GHIDRA_MCP_ALLOW_SCRIPTS=1`). + +**Spec:** `docs/superpowers/specs/2026-07-09-engine-ctx-struct-design.md`. + +## Global Constraints + +- Run Python as `py -3.11 -X utf8 tools/.py …`. Tools compute paths via `paths.py`; `build/` is disposable. +- **Never hand-edit generated files** (`build/engine-ctx.json`, `docs/engine-ctx-reference.md`): edit `engine-ctx.toml`, re-run `--build`. +- Scope = engine `ctx` (esi) fields ONLY; the VM global bank `G[…]` is a separate space (`globals.toml`), out of scope. +- **Ghidra:** confirm the active program is `/v2/range_00400000.bin` (base `0x400000`, 4400+ fns — the two-program gotcha) before any script; end mutation with `save_program`. +- Seed fields are 4-byte scalars (`int`/`uint`/`void*`) — names the offset without span-management; arrays/sub-structs are a later refinement. + +--- + +## Task 1: Canonical source + generator (`engine-ctx.toml` → JSON + doc) + +**Files:** +- Create: `vm-map/engine-ctx.toml` (canonical source) +- Create: `tools/engine_ctx_build.py` (model + lint + emit + CLI) +- Create: `tools/test_engine_ctx.py` (unit tests for lint + emit) +- Create: `build/engine-ctx.json` (generated), `docs/engine-ctx-reference.md` (generated) + +**Interfaces:** +- Produces: `load(toml_text) -> dict` (`{"meta": {...}, "fields": [{"offset":int,"name","type","note"}...]}`); `lint(model) -> list[str]` (errors); `emit_json(model) -> dict`; `emit_reference_md(model) -> str`. +- `TYPE_SIZES = {"int":4, "uint":4, "void*":4}` (all seed fields 4 bytes). + +- [ ] **Step 1: Create the canonical source `vm-map/engine-ctx.toml`** + +```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 (see the plan). ctx = engine context (esi/thiscall this). +# The VM global bank G[...] is a SEPARATE space (vm-map/globals.toml), NOT ctx offsets. +[meta] +struct_name = "EngineCtx" +size = 0xa1000 + +[[field]] +offset = 0x3028 +name = "alt_pack_table" +type = "int" +note = "call-script high-byte alternate pack table (unused by corpus)" +[[field]] +offset = 0x408 +name = "gfx_obj_registry" +type = "int" +note = "retained gfx-object map (std::map handle->object); geometry/draw get-or-create, 0x215 returns obj+4 source slot, 0x1f7 erases" +[[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 = 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)" +``` + +- [ ] **Step 2: Write the failing tests** + +```python +# tools/test_engine_ctx.py (plain runner, no pytest) +import sys +from engine_ctx_build import load, lint, emit_json + +FAILS = [] +def check(c, m): + (FAILS.append(m) or print("FAIL:", m)) if not c else print("ok:", m) + +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(): + m = load(GOOD) + j = emit_json(m) + 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()) +``` + +- [ ] **Step 3: Run tests to verify they fail** + +Run: `py -3.11 -X utf8 tools/test_engine_ctx.py` +Expected: FAIL — `ModuleNotFoundError: No module named 'engine_ctx_build'`. + +- [ ] **Step 4: Implement `tools/engine_ctx_build.py`** + +```python +"""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 + +Apply to the Ghidra /v2 image via run_script_inline (see docs/superpowers/plans/2026-07-09-engine-ctx-struct.md). +""" +import json, sys, 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}`.", "", + "| 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()) +``` + +- [ ] **Step 5: Run tests to verify they pass** + +Run: `py -3.11 -X utf8 tools/test_engine_ctx.py` +Expected: PASS (4 tests, `FAILURES: 0`). + +- [ ] **Step 6: Build the real artifacts and lint-check the seed** + +Run: `py -3.11 -X utf8 tools/engine_ctx_build.py --build` +Expected: `built 35 fields -> build/engine-ctx.json + docs/engine-ctx-reference.md`, no lint errors. Eyeball `docs/engine-ctx-reference.md` for the field table. + +- [ ] **Step 7: Commit** + +```bash +git add vm-map/engine-ctx.toml tools/engine_ctx_build.py tools/test_engine_ctx.py docs/engine-ctx-reference.md +git commit -m "re: EngineCtx field registry (engine-ctx.toml) + builder" +``` + +--- + +## Task 2: Apply the struct + retype handlers in Ghidra, validate + +**Precondition:** `build/engine-ctx.json` + `build/op-handler-map.json` exist; active program `/v2`. + +**Files:** none in-repo — driven via `run_script_inline` (Java). + +- [ ] **Step 1: Confirm the correct program + capture BEFORE snippet** + +Via MCP `get_current_program_info` — assert base `0x400000`, 4400+ fns (else `open_program`/`switch_program /v2/range_00400000.bin`). Then `decompile_function 0x44cff0` (`sleep_timer_arm`) and note the current `(*DAT_...)` / `param_1 + 0x5f304` rendering for the before/after. +Expected: confirmed program + a BEFORE snippet showing raw offsets. + +- [ ] **Step 2: Create the `EngineCtx` struct from `build/engine-ctx.json`** + +`run_script_inline` (Java): read the JSON; get/create a `StructureDataType("EngineCtx", size)` in the program's data type manager; for each `offset → {name,type}` map `type` to a Ghidra `DataType` (`int`/`uint` → `IntegerDataType`/`UnsignedIntegerDataType`; `void*` → `PointerDataType`) and `struct.replaceAtOffset(offset, dt, dt.getLength(), name, note)`; add via `dataTypeManager.addDataType(struct, REPLACE_HANDLER)`. One transaction. Print field count placed. + +```java +import java.nio.file.*; import ghidra.program.model.data.*; +String txt = new String(Files.readAllBytes(Paths.get("S:/Game Hacking/Eushully/Himegari/age-reimpl/build/engine-ctx.json"))); +// parse meta.size + each "0xoff":{"name":..,"type":..} with a regex; build the struct. +// map type: "void*" -> new PointerDataType(); "uint" -> UnsignedIntegerDataType.dataType; else IntegerDataType.dataType +// struct.replaceAtOffset(off, dt, 4, name, note); +``` +Expected: `EngineCtx` struct created with 35 fields. + +- [ ] **Step 3: Retype dispatch-handler `this` to `EngineCtx *`** + +`run_script_inline` (Java): read `build/op-handler-map.json`; resolve `EngineCtx *` (`new PointerDataType(struct)`); for each handler VA, get the `Function`; if it has a `this`/first param whose usage is `ctx` (thiscall or first param), set that param's type to `EngineCtx *` (`func.getParameter(0).setDataType(ptr, SourceType.USER_DEFINED)`, or `func.setCallingConvention("__thiscall")` + this-type where needed). Count retyped; collect + print the VAs skipped (no first param / not ctx-shaped) for review. One transaction; `save_program`. +Expected: most handlers retyped; a small skip list. + +- [ ] **Step 4: Validate — AFTER snippet** + +`decompile_function 0x44cff0` (`sleep_timer_arm`) and `0x42a0b0` (`gfx_op_0x215_query_source_slot`). +Expected: `sleep_timer_arm` renders `ctx->sleep_timer` (was `param_1 + 0x5f304`); the 0x215 handler renders `ctx->cur_ctx_index` / `ctx->cmd_type_table` at `0x53d14`/`0x53d88`. Record before/after. If fields don't render, diagnose the this-type application (Step 3) before proceeding. + +--- + +## Task 3: Docs + memory + close + +**Files:** +- Modify: `CLAUDE.md` (canonical-documents map + single-source-of-truth table: add the `engine-ctx.toml` row) +- Modify: `docs/tools-reference.md` (add `engine_ctx_build.py`) +- Modify: `docs/engine-re.md` (link `docs/engine-ctx-reference.md` from the ctx-offsets discussion) +- Modify: `~/.claude/…/memory/himegari-port-status.md` (milestone) + +- [ ] **Step 1: Update CLAUDE.md** + +Add to the canonical-documents map: `| Engine ctx struct fields | age-reimpl/vm-map/engine-ctx.toml (generated → build/engine-ctx.json, docs/engine-ctx-reference.md) |`. Add to the single-source table: `| vm-map/engine-ctx.toml | py -3.11 -X utf8 tools/engine_ctx_build.py --build | build/engine-ctx.json, docs/engine-ctx-reference.md |`. + +- [ ] **Step 2: Update tools-reference.md + engine-re.md** + +`tools-reference.md`: add an `engine_ctx_build.py` row (source → JSON+doc; `--build`/`--lint`; applied to Ghidra via run_script_inline). `engine-re.md`: in the dispatch/ctx-offsets area, add a line pointing to `docs/engine-ctx-reference.md` as the field map, noting the struct is applied to the `/v2` image. + +- [ ] **Step 3: Update the status memory** + +Record: EngineCtx struct DONE — N fields, applied to /v2 (M handlers retyped), before/after validated; source `engine-ctx.toml`; grows incrementally. + +- [ ] **Step 4: Commit** + +```bash +git add CLAUDE.md docs/tools-reference.md docs/engine-re.md +git commit -m "re: apply EngineCtx struct to /v2 handlers; doc + canonical-map wiring" +``` + +--- + +## Self-Review + +**Spec coverage:** source `engine-ctx.toml` → Task 1 Step 1; builder + lint + JSON + doc → Task 1 Steps 4/6; struct creation → Task 2 Step 2; handler `this` retype → Task 2 Step 3; validation decompiles → Task 2 Step 4; CLAUDE.md/tools-reference/memory → Task 3. Covered. + +**Placeholder scan:** Task 2 Java bodies are described with the key API calls (`replaceAtOffset`, `setDataType`, `PointerDataType`) rather than full source — intentional: the exact DataTypeManager calls are pinned at implementation against the live API (same as Task A's iterative script bring-up), and the logic is fully specified. No TBDs in the Python (Task 1 is complete code). + +**Type consistency:** `load` returns `{"meta","fields":[{offset,name,type,note}]}`; `lint`/`emit_json`/`emit_reference_md` all consume that shape; `emit_json` outputs `{meta, fields:{hex:{name,type}}}` which the Task 2 Step 2 Ghidra parser reads. `TYPE_SIZES` keys (`int`/`uint`/`void*`) match the toml `type` values and the Task 2 Ghidra type mapping. Consistent. diff --git a/docs/superpowers/specs/2026-07-09-engine-ctx-struct-design.md b/docs/superpowers/specs/2026-07-09-engine-ctx-struct-design.md new file mode 100644 index 0000000..5ce9266 --- /dev/null +++ b/docs/superpowers/specs/2026-07-09-engine-ctx-struct-design.md @@ -0,0 +1,112 @@ +# EngineCtx struct — typing the engine context — design + +**Date:** 2026-07-09 +**Status:** implemented 2026-07-09 (`3826064`, `0ecd776`) +**Home in the canonical map:** a NEW canonical source (`vm-map/engine-ctx.toml`) + a generated +reference (`docs/engine-ctx-reference.md`); add a row to the CLAUDE.md canonical-documents map and the +single-source-of-truth table. RE narrative stays in `docs/engine-re.md` (which already documents the +offsets); this struct is the machine-readable + applied form of that knowledge. + +## Motivation + +The recurring RE friction that survives the handler-labeling and import-map work is **re-decoding the +same `ctx` (esi) offsets by hand** — every handler RE means reading `*(int*)(param_1 + 0x53d14)`, +`+0x53d88`, `+0x9b24c`, `+0x408`, `+0x52bd4`, `+0x5f304`, `+0xa0ce4`… and recalling what each means. We +have already documented ~30 of these in `docs/engine-re.md`. Defining them **once** as a Ghidra struct +and applying it makes every handler decompile with named fields (`ctx->cur_gfx_idx`), front-loading the +"what's this offset" lookup so it never recurs. This is the same shape of win as Task A (handler +labeling): a one-time pass that pays out on every future look at the decomp. + +Scope note: this is strictly the **engine context** struct (`esi`/thiscall `this`). The VM **global bank** +`G[…]` is a *separate* address space (not `ctx` offsets) and is out of scope here (it has its own map, +`vm-map/globals.toml`). + +## Architecture + +Single source of truth → generated machine view + doc → applied to the Ghidra image. Mirrors the +`opcodes.toml`/`globals.toml` pattern exactly. + +### 1. `vm-map/engine-ctx.toml` (canonical source — hand-edited) + +```toml +[meta] +struct_name = "EngineCtx" +size = 0xa1000 # >= max field end; sparse (gaps = undefined). Grows as needed. + +[[field]] +offset = 0x53d14 +name = "cur_ctx_index" +type = "uint" +note = "current gfx-object / script-context index (curCtx); indexes the 0x78-byte context records" +source = "native-RE" +confidence = "high" +# … one [[field]] per documented offset … +``` + +Seeded with the ~30 fields already documented in `engine-re.md`, e.g.: `0x408` retained gfx-object map +(`std::map`; geometry/draw get-or-create, `0x215` queries obj+4 source slot, `0x1f7` erases), `0x40c` +SYS4INI record count, `0x410` archive-name table, `0x414` SYS4INI 80-byte record +base, `0x14d54` obj-pointer table, `0x14f45` script-frame index, `0x46d14` stride-0x14 query table, +`0x51b78/0x51b7c` anim clock elapsed/duration, `0x52bd4` surfaces[1000], `0x53d14` cur-ctx-index, +`0x53d28/0x53d2c` frame codebase/PC, `0x53d60` context-record base (stride 0x78), `0x53d64` gfx +object-record array, `0x53d88` per-object cmd-type table (stride 0x78), `0x55120/0x55124/0x5512c` +anti-tamper checksum, `0x55248/0x552e8` per-frame return stack, `0x5f304` sleep-timer object, `0x6da88/ +0x6db28` coroutine yield-state, `0x6dbc8/0x6dbcc` coroutine resume-state, `0x9b24c` dispatch handler +table[0x400], `0xa0cc0/0xa0cc4/0xa0cc8` screen w/h/bpp, `0xa0ce4` run-state flags, `0xb558/0xb560` gfx +dirty flags. + +**Types kept simple:** `int`/`uint`/`void*`; arrays where clearly arrays (`dispatch[0x400]` as +`void*[0x400]`, `surfaces[1000]`); a field may be a plain scalar even if it's the head of a table (the +struct only needs the offset named — the array modelling is optional polish). + +### 2. `tools/engine_ctx_build.py` (generator + linter) + +- `--build` → `build/engine-ctx.json` (`{ "0x53d14": {"name": "...", "type": "uint"}, ... }` + meta) and + regenerates `docs/engine-ctx-reference.md` (offset / name / type / note table, grouped). +- `--lint` → fail on: overlapping fields (offset+size collisions), a field whose end exceeds `meta.size`, + an unknown type, or a duplicate name. Run in `--build`. +- Model + lint in the tool (or a small `engine_ctx_model.py` if it grows); unit-tested (`test_engine_ctx.py`). + +### 3. Ghidra apply (`run_script_inline`, Java — the Task A pattern) + +Confirm the active program is `/v2/range_00400000.bin` (base `0x400000`, 4400+ fns — the two-program +gotcha). Then: +1. Read `build/engine-ctx.json`; create (or replace) a struct `EngineCtx` of `meta.size` bytes with each + field placed at its offset (`struct.replaceAtOffset` / `insertAtOffset` per the Ghidra API), gaps left + undefined. +2. Read `build/op-handler-map.json`; for each dispatch handler, set its `this`/first-parameter type to + `EngineCtx *` (via the thiscall `this` type, or parameter 0 where the convention lacks a `this`). + Skip functions that don't take `ctx` as first arg (report them). +3. One transaction; `save_program`. + +## Data flow + +`vm-map/engine-ctx.toml` ──`--build`──▶ `build/engine-ctx.json` + `docs/engine-ctx-reference.md` +`build/engine-ctx.json` + `build/op-handler-map.json` ──`run_script_inline`──▶ `EngineCtx` struct + +retyped handler `this` on `/v2` ──▶ handlers decompile `ctx->field`. + +## Validation + +- `--lint` passes (no overlaps/OOB/dup). +- Decompile **`sleep_timer_arm`** — expect `ctx->sleep_timer` (offset `0x5f304`) instead of + `param_1 + 0x5f304`; decompile **`gfx_op_0x215_query_source_slot`** — expect `ctx->cur_ctx_index` / + `ctx->cmd_type_table[...]` style rendering at `0x53d14`/`0x53d88`. Record a before/after snippet. +- Handler count retyped reported; functions skipped (no `ctx` first-arg) listed for review. +- `save_program` succeeds. + +## Scope & boundaries + +- **In:** the ~30 documented `ctx` fields; struct creation; retyping dispatch-handler `this` params. +- **Out:** the VM global bank (`globals.toml`); worker functions (`FUN_0047xxxx`) — retype later as we + touch them; exhaustive field discovery (grows incrementally via the toml, not a big-bang sweep); + nested sub-structs (e.g. modelling the 0x78-byte context record as its own type — a later refinement). +- **Regenerable:** `build/engine-ctx.json` + `docs/engine-ctx-reference.md` are generated — never + hand-edit; edit `engine-ctx.toml` and re-run `--build`. + +## Acceptance criteria + +- `vm-map/engine-ctx.toml` holds the ~30 seed fields; `--build` regenerates the JSON + doc; `--lint` clean. +- `EngineCtx` struct exists in the `/v2` image; dispatch-handler `this` params retyped (count reported). +- The two validation decompiles render named `ctx->…` fields; `save_program` OK. +- CLAUDE.md canonical-map + single-source table gain the `engine-ctx.toml` row; `tools-reference.md` + gains `engine_ctx_build.py`; status memory records the milestone.