From fae5c9abef76267a4da6123b5f02e16abb5e70e4 Mon Sep 17 00:00:00 2001 From: gamer147 Date: Thu, 9 Jul 2026 10:08:06 -0400 Subject: [PATCH] re: apply EngineCtx struct to /v2 handlers; doc + canonical-map wiring Created the EngineCtx Ghidra struct (35 fields, 0xa1000) and retyped all 419 dispatch handlers' this -> EngineCtx* (CUSTOM_STORAGE, ctx in ECX). Handlers now decompile ctx->cur_ctx_index / ctx->run_state_flags etc. Validated: sleep_op_0xc8, gfx_op_0x215. tools-reference + engine-re.md wired; CLAUDE.md canonical-map updated (root, outside repo). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/engine-re.md | 7 +++++++ docs/tools-reference.md | 2 ++ 2 files changed, 9 insertions(+) diff --git a/docs/engine-re.md b/docs/engine-re.md index b5dfd97..02b7299 100644 --- a/docs/engine-re.md +++ b/docs/engine-re.md @@ -120,6 +120,13 @@ decode when you reverse one (the generic name is a floor, not a final). 0x41b940` (thiscall, `ecx=ctx`, arg = operand index → returns the operand value); `FUN_00415f30(i)` = a companion operand accessor. +**These `ctx` offsets are now a typed struct (2026-07-09).** The canonical field map is +`vm-map/engine-ctx.toml` → generated `docs/engine-ctx-reference.md`; a `run_script_inline` pass created +an `EngineCtx` Ghidra struct and retyped **all 419 dispatch handlers' `this` to `EngineCtx *`**, so they +decompile `ctx->cur_ctx_index` / `ctx->cmd_type_table` / `ctx->run_state_flags` instead of `param_1 + 0x…` +(verified: `sleep_op_0xc8`, `gfx_op_0x215_register_query`). Add a field: edit `engine-ctx.toml`, run +`engine_ctx_build.py --build`, re-apply the struct. (The VM global bank `G[…]` is separate — `globals.toml`.) + --- ## Findings diff --git a/docs/tools-reference.md b/docs/tools-reference.md index 890546d..195bd41 100644 --- a/docs/tools-reference.md +++ b/docs/tools-reference.md @@ -169,6 +169,8 @@ texture ops (no GPU context) — run windowed for real scenes. User args (after |---|---|---|---| | `ghidra_handler_map.py` | Extract the opcode→real-handler dispatch table (`handler(op)=ctx[0x26c93+op]`) from `FUN_00413860`'s override stores — the general fix for Kelebek VA-drift. `--check` diffs derived handlers vs `opcodes.toml` prose (found 0 real drift). Feeds the one-shot Ghidra annotation pass that names every handler `op_0xNN_handler` (see `docs/engine-re.md` "Materialized + applied image-wide"). | `ghidra_handler_map.py build/engine-dump/FUN_00413860.disasm.txt [--check]` | ⚙ `build/engine-dump/FUN_00413860.disasm.txt` (from ghidra-mcp `disassemble_function(0x413860)`) → ⚙ `build/op-handler-map.json` | | `test_ghidra_handler_map.py` | Unit tests for the dispatch-table parser (plain runner, no pytest). | `test_ghidra_handler_map.py` | — | +| `engine_ctx_build.py` | Build the `EngineCtx` struct artifacts from `vm-map/engine-ctx.toml` (canonical `ctx`-field registry). `--lint` = overlap/OOB/dup/type checks. The struct is then applied to the `/v2` image via `run_script_inline` (creates `EngineCtx`, retypes all dispatch-handler `this` → `EngineCtx *`) so handlers decompile `ctx->field` not `param_1+0x…`. Grows one `[[field]]` at a time. | `engine_ctx_build.py --build` · `--lint` | ⚙ `vm-map/engine-ctx.toml` → ⚙ `build/engine-ctx.json`, ⚙ `docs/engine-ctx-reference.md` | +| `test_engine_ctx.py` | Unit tests for the ctx builder (load/lint/emit; plain runner). | `test_engine_ctx.py` | — | ## Historical / one-off