From 1b8c8c6ac775be6def9b4f5bccbe6803bc287fec Mon Sep 17 00:00:00 2001 From: gamer147 Date: Tue, 7 Jul 2026 22:09:11 -0400 Subject: [PATCH] fix(gfx): op 0x215 query registry is separate from the geometry store The retained-mode "2nd CG renders off-screen" bug: GfxState conflated two distinct native structures. It assigned a fabricated AcquireSlot() slot on every GetOrCreate (called by all geometry/draw ops) and returned it from QuerySlot (op 0x215). But Ghidra (gfx_op_0x215_register_query @0x42a0b0 / gfx_op_0x1a2_registry_insert @0x42d360) shows 0x215 does map.find(handle) over a registry populated ONLY by op 0x1a2 -- it never allocates a slot. So a CG handle (never 0x1a2-registered) read back as "existing", took the existing branch of label_12649, ran get-texture-size on the wrong slot (0), got size 0, and computed dst = pos(0,0) - (w/2,h) = (-400,-600) -> off-screen. The real engine returns -1 -> the fresh branch -> anchor from the INIT2 arrays -> dst=(0,0). Fix: GfxState keeps a separate _registry (HashSet) populated only by Register() (op 0x1a2); QuerySlot returns the handle if registered else -1, and no longer consults the geometry store or invents slots. Drop AcquireSlot / GfxObject.Slot / the free-list. Verified: Age.Cli gfx --boot SC0000.BIN -> all event CGs dst=(0,0), zero (-400,-600) draws; Godot --boot pages 1/2/4 render opening CGs full-screen; engine 44/44; sweep parity 284 exit / 13 STEP-LIMIT unchanged. Docs: engine-re.md (query-registry-vs-geometry-store section), opcodes.toml 0x1a2/0x215 rebuilt; Ghidra helpers gfx_registry_map_find/hash_insert annotated + saved. Tests rewritten to the native contract. Co-Authored-By: Claude Opus 4.8 --- docs/engine-re.md | 40 +++++++++++++++++ docs/opcode-reference.md | 4 +- .../Age.Engine.Tests/GfxCommandBufferTests.cs | 18 +++++--- engine/Age.Engine.Tests/GfxStateTests.cs | 31 +++++++------ engine/Age.Engine/Model/GfxState.cs | 43 +++++++++++-------- engine/Age.Engine/Vm/VirtualMachine.cs | 5 ++- vm-map/opcodes.toml | 4 +- 7 files changed, 102 insertions(+), 43 deletions(-) diff --git a/docs/engine-re.md b/docs/engine-re.md index 596cfde..32137fe 100644 --- a/docs/engine-re.md +++ b/docs/engine-re.md @@ -177,6 +177,46 @@ are **bytecode-driven** — so a faithful host-side model, with the gfx ops (`0x `0x212–0x21a` family) *executed* instead of stubbed, rebuilds the state from the same scripts. The opcode- level summary lives in `vm-map/opcodes.toml` op `0x215`. +#### The query registry is SEPARATE from the geometry object store (2026-07-07) — the retained-mode "2nd CG off-screen" fix + +Modelling the gfx ops (above) exposed a subtle but decisive point that the first retained-mode +implementation got wrong. There are **two distinct native structures**, and they must stay distinct: + +1. **The op-`0x215` query registry** — a `std::map` **populated ONLY by op `0x1a2`** + (`FUN_0042cf70` hash insert; native stores `map[handle] = handle`). `0x215` does `map.find(handle)` + → the found value (which equals the handle, and for small system/UI handles doubles as their surface + slot) or `0xffffffff` = **-1**. +2. **The geometry object store** — per-handle V18/V24/V16c/color/draw-bind, touched lazily by the + geometry SET ops and `draw-texture` (`gfx_object_get_or_create`). This feeds the compositor. + +The first `GfxState` conflated them: `GetOrCreate` (called by *every* geometry/draw op) also assigned a +fabricated per-object slot via an `AcquireSlot()` allocator, and `QuerySlot` (op `0x215`) returned it. +That is a fiction with **no basis in the engine** — the native `0x215` never allocates a slot. + +Consequence, traced end-to-end in `SC0000` `label_12649` (the CG-load subroutine): a CG handle +(`0xcb2a` = `INIT2`'s `G[0x62456]`, idx 1) is **never `0x1a2`-registered**. Real engine → `0x215` returns +`-1` → the **fresh branch** runs → anchor comes from the `INIT2` arrays (`G[0x62469+idx]=400`, +`G[0x6247d+idx]=600`) → `dst = anchor − (w/2, h) = (0,0)`. Correct. But with the fabricated allocator the +*second* pass over the same handle found it "existing" (slot `4`) → the **existing branch** ran +`get-texture-size(4)` on a slot whose surface was never loaded (the bytecode's own slot table +`rec[s3]`/`G[0x3239]` gave slot `0`) → size `0` → `anchor = pos(0,0) + 0` → `dst = (0−400, 0−600) = +(−400,−600)` — the CG rendered off-screen. This is the bug that had been mis-attributed to "geometry +accumulation / drift" several times. + +**Fix (branch `feat/gfx-command-buffer`):** `GfxState` keeps a separate `_registry` (a `HashSet`) +populated only by `Register(handle)` (op `0x1a2`); `QuerySlot` returns `handle` if registered else `-1`, +and no longer consults the geometry store or invents slots. Verified: `Age.Cli gfx --boot SC0000.BIN` +→ all event CGs `dst=(0,0)`, zero `(−400,−600)` draws; Godot `--boot --shot` pages 1/2/4 render the +opening event CGs full-screen; engine 44/44; sweep parity 284 exit / 13 STEP-LIMIT unchanged. + +Note a **second, still-latent** gap this uncovered: `label_125bd` (which fills `rec[s3]`/`G[0x3239]` with +the per-object slots 4..13, called at `SC0000` `0x50f`) does **not** execute in a cold single-scene run — +the scene coroutine framework (ops `0x7b`/`0x140` + the `G[0xaba5c]==1` re-entry gate) routes cold flow +past it, so every fresh CG is assigned slot `0`. It doesn't break the *opening* (one full-screen CG shown +at a time, so sharing slot 0 is harmless and the fresh-branch geometry is correct regardless), but a scene +with several simultaneous distinct-slot objects would need the setup to run. Tracked as the scene-coroutine +work, separate from this fix. + #### gfx command-buffer — op contract table (2026-07-07, full family reversed) Every gfx op shares one shape: **write a `cmd-type` into the current object record** (`*(ctx + 0x53d88 + diff --git a/docs/opcode-reference.md b/docs/opcode-reference.md index 23423fd..3128162 100644 --- a/docs/opcode-reference.md +++ b/docs/opcode-reference.md @@ -60,7 +60,7 @@ This also names the whole call graph statically (build/callscript-names.json). ## draw ### 0x1a2 `gfx-cmd-register` (gfx-cmd-register, argc 1) -- **summary:** 0x1a2 (val) — gfx cmd-type 3. Handler gfx_op_0x1a2_registry_insert @0x42d360: builds key '%c%8.8x'(3, operand-desc) and INSERTS operand 1 into the gfx command-buffer registry (FUN_0042cf70, open-addressing hash). This is what POPULATES the registry that op 0x215 queries. NOT save/scene (raw Kelebek VA 0x428010 drifted to op 0x1ac save handler). See docs/engine-re.md gfx op-contract table. +- **summary:** 0x1a2 (handle) — gfx cmd-type 3. Handler gfx_op_0x1a2_registry_insert @0x42d360: builds key '%c%8.8x'(3, operand-desc) and INSERTS operand 1 into the op-0x215 query registry (FUN_0042cf70, open-addressing hash; native stores map[handle]=handle). This is the SOLE populator of the registry op 0x215 queries — the geometry SET/draw ops (0x217/0x219/0x1ff/0x1fb/0x202/...) do NOT register. VM impl: GfxState.Register(handle) (a separate set from the geometry object store). Conflating the two (registering on every GetOrCreate) was the retained-mode geometry bug: CG handles wrongly read back as 'existing' and collapsed to (-400,-600). NOT save/scene (raw Kelebek VA 0x428010 drifted to op 0x1ac save handler). See docs/engine-re.md gfx op-contract table. - **grounding:** source=investigation, confidence=high - **evidence:** Ghidra: real handler FUN_0042d360 (via dispatch table ctx[0x26c93+op]); sets *(ctx+0x53d88+ctx[0x53d14]*0x78)=3, sprintf("%c%8.8x",3,op1), FUN_0042cf70 (hash insert; counterpart of op 0x215 find). NOT save/scene (raw Kelebek VA 0x428010 drifted to op 0x1ac save handler). See docs/engine-re.md @@ -120,7 +120,7 @@ This also names the whole call graph statically (build/callscript-names.json). - **evidence:** Ghidra handler 0x423110; writes obj+0x68/+0x6c from operands 2/3, obj from ctx+0x14d54[operand1*4]. ### 0x215 `query-gfx-object?` (query-gfx-object?, argc 2) -- **summary:** 0x215 (out)(handle_id) — native graphics command-buffer op. Real handler FUN_0042a0b0 (Ghidra-resolved via the dispatch table ctx[0x26c93+op]; Kelebek's 0x421160 is VA-drift, lands in an unrelated fn). Does TWO things: (1) writes cmd-type 5 into the CURRENT gfx-object record `[ctx+0x53d88 + ctx[0x53d14]*0x78]` (a command-buffer registration, parallel to op 0x1a2→type 3); (2) returns `out = map.find(handle_id)` over an engine-internal associative registry (found value, else 0xffffffff=not-found), sign-tested (gre/lt 0) to drive label_12649's slot-select branch + set working slot G[0x62452]. So `out` is NATIVE COMMAND-BUFFER STATE (the registry is populated by sibling gfx ops — op 0x1a2→FUN_0042cf70 is the hash insert), NOT the VM global bank → seeding story-state CANNOT reproduce it. Stubbed → constant return → every draw collapses to slot 0 → anchor-preserve reads foreign-sized textures → the cumulative bg/sprite drift. SETTLES the drift as (b) a genuine native op, NOT (a) state-divergence. Faithful fix = model the gfx command-buffer (record array + handle→object registry) and run the gfx ops instead of stubbing — static/Frida-free (handlers now readable; inserts are bytecode-driven). Full decode + verdict: docs/engine-re.md (op 0x215 section). +- **summary:** 0x215 (out)(handle_id) — native graphics command-buffer op. Real handler FUN_0042a0b0 (Ghidra-resolved via the dispatch table ctx[0x26c93+op]; Kelebek's 0x421160 is VA-drift, lands in an unrelated fn). Does TWO things: (1) writes cmd-type 5 into the CURRENT gfx-object record `[ctx+0x53d88 + ctx[0x53d14]*0x78]` (a command-buffer registration, parallel to op 0x1a2→type 3); (2) returns `out = map.find(handle_id)` over an engine-internal associative registry (found value, else 0xffffffff=not-found), sign-tested (gre/lt 0) to drive label_12649's slot-select branch + set working slot G[0x62452]. So `out` is NATIVE COMMAND-BUFFER STATE (the registry is populated by sibling gfx ops — op 0x1a2→FUN_0042cf70 is the hash insert), NOT the VM global bank → seeding story-state CANNOT reproduce it. Stubbed → constant return → every draw collapses to slot 0 → anchor-preserve reads foreign-sized textures → the cumulative bg/sprite drift. SETTLES the drift as (b) a genuine native op, NOT (a) state-divergence. Faithful fix = model the gfx command-buffer (record array + handle→object registry) and run the gfx ops instead of stubbing — static/Frida-free (handlers now readable; inserts are bytecode-driven). Full decode + verdict: docs/engine-re.md (op 0x215 section). RETAINED-MODE FIX (2026-07-07): the registry MUST be separate from the geometry object store — it is populated ONLY by op 0x1a2, never by the geometry SET/draw ops. VM: QuerySlot returns the registered value (=handle) or -1, NOT a fabricated per-object slot. CG handles are never 0x1a2-registered → query returns -1 → label_12649 takes its FRESH branch (anchor from the INIT2 arrays) → dst=(0,0). The prior GfxState.GetOrCreate-assigns-AcquireSlot model made CG handles read as 'existing' → existing branch called get-texture-size on the wrong slot (0) → dst=(-400,-600) off-screen (the '2nd CG off-screen' bug). - **grounding:** source=investigation, confidence=high - **evidence:** Ghidra: real handler FUN_0042a0b0 = {*(ctx+0x53d88+ctx[0x53d14]*0x78)=5; out=FUN_0047f280(FUN_0041b940(2))}. FUN_0047f280 = std::map::find (returns mapped value or 0xffffffff); FUN_0041b940(2) = operand-fetch of operand 2 (the handle key); FUN_00425fb0(1,val) = operand-write to `out`. Registry populated by op 0x1a2 handler FUN_0042d360 → FUN_0042cf70 (open-addressing hash insert). Bytecode sites: SC0000 label_12649 (0x12670) + label_123ef (0x12419/0x12450), handle-ids from 0x62455[idx] (±offset); result gre/lt 0 branches slot-select. Record table 0x3239 (label_125bd @0x0050f) assigns per-object slots 4..13. diff --git a/engine/Age.Engine.Tests/GfxCommandBufferTests.cs b/engine/Age.Engine.Tests/GfxCommandBufferTests.cs index aa4b191..52e3219 100644 --- a/engine/Age.Engine.Tests/GfxCommandBufferTests.cs +++ b/engine/Age.Engine.Tests/GfxCommandBufferTests.cs @@ -36,21 +36,27 @@ public class GfxCommandBufferTests Assert.Equal(30, vm.Globals[7]); } + private static (int, Operand[]) Register(int handle) => (0x1a2, new[] { G(handle) }); + [Fact] - public void QueryReturnsDistinctSlotsPerHandle_NotZero() + public void QueryReturnsMinusOneUntilRegistered_ThenTheHandle() { + // Native contract (docs/engine-re.md op 0x215/0x1a2): the query registry is populated ONLY by op 0x1a2 + // (gfx-cmd-register). Giving a handle geometry via set-geom (0x217) must NOT register it — query stays -1 + // so a CG handle takes label_12649's fresh branch. After 0x1a2, query returns the handle (native + // map[handle]=handle; small system handles double as their surface slot). var t = T(); - // create two objects via set-geom, then query each into g[10], g[11]. var scene = ScriptAssembler.Assemble(t, "GFX", new List<(int, Operand[])> { - MovGI(1, 0x1000), MovGI(2, 0x2000), MovGI(3, 0), - SetGeom3(1, 3, 3, 3), SetGeom3(2, 3, 3, 3), + MovGI(1, 0xcb2a), MovGI(2, 0xd), MovGI(3, 0), + SetGeom3(1, 3, 3, 3), // 0xcb2a: geometry only, NOT registered + Register(2), // 0xd: op 0x1a2 registers it Query(10, 1), Query(11, 2), Exit(), }, System.Array.Empty()); var vm = new VirtualMachine(scene, t, new RecordingHost()); vm.Run(); - Assert.NotEqual(0, vm.Globals[10]); // not collapsed to slot 0 - Assert.NotEqual(vm.Globals[10], vm.Globals[11]); // distinct slots => no collapse + Assert.Equal(-1, vm.Globals[10]); // geometry-only CG handle -> -1 -> fresh branch (the bug fix) + Assert.Equal(0xd, vm.Globals[11]); // 0x1a2-registered handle -> its value (== handle) } private static (int, Operand[]) BlitColor(int h, int x, int y, int alpha, int color) diff --git a/engine/Age.Engine.Tests/GfxStateTests.cs b/engine/Age.Engine.Tests/GfxStateTests.cs index 30627c0..09160af 100644 --- a/engine/Age.Engine.Tests/GfxStateTests.cs +++ b/engine/Age.Engine.Tests/GfxStateTests.cs @@ -4,14 +4,19 @@ using Xunit; public class GfxStateTests { [Fact] - public void DistinctHandlesGetDistinctSlots() + public void QueryRegistryIsPopulatedOnlyByRegister_NotByGeometryOps() { + // Native contract (docs/engine-re.md op 0x215/0x1a2): the op-0x215 query registry is populated ONLY by + // op 0x1a2 (gfx-cmd-register). Merely giving a handle geometry (GetOrCreate, as the set-geom ops do) + // must NOT make query-gfx-object return a slot for it — otherwise a CG handle (never 0x1a2-registered) + // wrongly takes label_12649's existing branch and collapses off-screen. var g = new GfxState(); - int s1 = g.GetOrCreate(0x1000).Slot; - int s2 = g.GetOrCreate(0x2000).Slot; - Assert.NotEqual(s1, s2); - Assert.Equal(s1, g.QuerySlot(0x1000)); // stable - Assert.Equal(-1, g.QuerySlot(0x9999)); // unknown -> -1 (matches native 0xffffffff) + g.GetOrCreate(0xcb2a).V18 = (400, 600, 0); // geometry only, like the fresh CG-load branch + Assert.Equal(-1, g.QuerySlot(0xcb2a)); // NOT registered => -1 => fresh branch (correct) + + g.Register(0xd); // op 0x1a2 registers a small system/UI handle + Assert.Equal(0xd, g.QuerySlot(0xd)); // native map[handle]=handle; the value doubles as its slot + Assert.Equal(-1, g.QuerySlot(0x9999)); // unknown -> -1 (matches native 0xffffffff) } [Fact] @@ -26,13 +31,13 @@ public class GfxStateTests } [Fact] - public void ReleaseFreesTheSlotForReuse() + public void ReleaseRemovesTheHandleFromTheQueryRegistry() { var g = new GfxState(); - int s1 = g.GetOrCreate(0x1000).Slot; - g.Release(0x1000); - Assert.Equal(-1, g.QuerySlot(0x1000)); - Assert.Equal(s1, g.GetOrCreate(0x2000).Slot); // freed slot reused + g.Register(0x10); + Assert.Equal(0x10, g.QuerySlot(0x10)); + g.Release(0x10); // op 0x1fa / 0x1f7 tear down the registration too + Assert.Equal(-1, g.QuerySlot(0x10)); } [Fact] @@ -43,7 +48,7 @@ public class GfxStateTests public void EraseRangeRemovesHandlesInRange() { var g = new GfxState(); - g.GetOrCreate(0x10); g.GetOrCreate(0x11); g.GetOrCreate(0x12); g.GetOrCreate(0x20); + g.Register(0x10); g.Register(0x11); g.Register(0x12); g.Register(0x20); g.EraseRange(0x10, 3); // count>1 → erase [0x10, 0x13) Assert.Equal(-1, g.QuerySlot(0x10)); Assert.Equal(-1, g.QuerySlot(0x12)); @@ -54,7 +59,7 @@ public class GfxStateTests public void EraseRangeCountLeOneErasesSingleHandle() { var g = new GfxState(); - g.GetOrCreate(0x10); g.GetOrCreate(0x11); + g.Register(0x10); g.Register(0x11); g.EraseRange(0x10, 1); // count<=1 → single handle Assert.Equal(-1, g.QuerySlot(0x10)); Assert.NotEqual(-1, g.QuerySlot(0x11)); diff --git a/engine/Age.Engine/Model/GfxState.cs b/engine/Age.Engine/Model/GfxState.cs index 4346602..3a904c8 100644 --- a/engine/Age.Engine/Model/GfxState.cs +++ b/engine/Age.Engine/Model/GfxState.cs @@ -19,7 +19,6 @@ public sealed class GfxState { public sealed class GfxObject { - public int Slot = -1; public (long X, long Y, long Z) V18, V24, V16c; public long Field64, Field68, Field6c; public long Color; @@ -29,42 +28,50 @@ public sealed class GfxState public bool Visible; } + // ---- geometry/draw object store (V18/V24/draw bind, the compositor's input) ---- + // Populated lazily by the geometry SET ops and draw-texture. Membership here does NOT mean the object is + // in the op-0x215 query registry (that is a SEPARATE native structure; see _registry below). private readonly Dictionary _objects = new(); - private readonly SortedSet _free = new(); - private int _nextSlot = 4; // observed native slot range is 4..13 + + // ---- op-0x215 query registry (native std::map queried by gfx_op_0x215, populated ONLY by op 0x1a2 + // gfx-cmd-register -> FUN_0042cf70 hash insert). map[handle] = handle (native stores operand1 as the value; + // small system/UI handles double as their surface slot). CG handles are NEVER 0x1a2-registered, so + // query-gfx-object returns -1 for them and label_12649 takes its fresh branch (correct anchor from the + // INIT2 arrays) instead of collapsing onto a fabricated slot. See docs/engine-re.md op 0x215/0x1a2. ---- + private readonly HashSet _registry = new(); + private readonly Dictionary _fieldTable = new(); // ctx+0x46d14 (0x216); no family writer -> default 0 public long CurrentObject { get; private set; } - /// Live objects and their slots — for the CLI gfx oracle (Task 3.7). + /// Live geometry objects and the surface slot they draw from — for the CLI gfx oracle. public IEnumerable<(long Handle, int Slot)> Objects { - get { foreach (var kv in _objects) yield return (kv.Key, kv.Value.Slot); } - } - - private int AcquireSlot() - { - if (_free.Count > 0) { int s = _free.Min; _free.Remove(s); return s; } - return _nextSlot++; + get { foreach (var kv in _objects) yield return (kv.Key, kv.Value.SourceSlot); } } public GfxObject GetOrCreate(long handle) { - if (!_objects.TryGetValue(handle, out var o)) - { - o = new GfxObject { Slot = AcquireSlot() }; - _objects[handle] = o; - } + if (!_objects.TryGetValue(handle, out var o)) { o = new GfxObject(); _objects[handle] = o; } CurrentObject = handle; return o; } + /// Op 0x1a2 (gfx-cmd-register, native FUN_0042d360 -> FUN_0042cf70 hash insert): add the handle to + /// the op-0x215 query registry. Native inserts map[handle]=handle; QuerySlot returns that value (handle) or + /// -1. Only this op populates the query registry — geometry/draw ops do not. + public void Register(long handle) => _registry.Add(handle); + public GfxObject? TryGet(long handle) => _objects.TryGetValue(handle, out var o) ? o : null; - public int QuerySlot(long handle) => _objects.TryGetValue(handle, out var o) ? o.Slot : -1; + + /// Op 0x215 (query-gfx-object): native returns std::map::find(handle) — the registered value (=handle), + /// or 0xffffffff (=-1) when the handle was never 0x1a2-registered. NOT a fabricated slot allocator. + public int QuerySlot(long handle) => _registry.Contains(handle) ? (int)handle : -1; public long QueryField(long idx) => _fieldTable.TryGetValue(idx, out var v) ? v : 0; public void Release(long handle) { - if (_objects.TryGetValue(handle, out var o)) { if (o.Slot >= 0) _free.Add(o.Slot); _objects.Remove(handle); } + _objects.Remove(handle); + _registry.Remove(handle); // op 0x1fa/0x1f7 also tear down the query registration } /// Op 0x1f7 semantics (native gfx_registry_erase_range @0x47d8b0): erase handles in diff --git a/engine/Age.Engine/Vm/VirtualMachine.cs b/engine/Age.Engine/Vm/VirtualMachine.cs index 0fb0644..2b25323 100644 --- a/engine/Age.Engine/Vm/VirtualMachine.cs +++ b/engine/Age.Engine/Vm/VirtualMachine.cs @@ -257,8 +257,9 @@ public sealed class VirtualMachine { var o = Gfx.GetOrCreate(Read(a[0])); o.Field68 = Read(a[1]); o.Field6c = Read(a[2]); return pc + 1; } - case "gfx-cmd-register": // 0x1a2 (val) — register/insert - Gfx.GetOrCreate(Read(a[0])); return pc + 1; + case "gfx-cmd-register": // 0x1a2 (handle) — insert into the op-0x215 query registry (native + // FUN_0042d360 -> FUN_0042cf70 hash insert; the ONLY populator of that map) + Gfx.Register(Read(a[0])); return pc + 1; case "gfx-elem-erase": // 0x1f7 (handle)(count) — erase registry range (teardown, NOT create) Gfx.EraseRange(Read(a[0]), Read(a[1])); return pc + 1; case "gfx-elem-release": // 0x1fa (handle) diff --git a/vm-map/opcodes.toml b/vm-map/opcodes.toml index 0069787..5410c75 100644 --- a/vm-map/opcodes.toml +++ b/vm-map/opcodes.toml @@ -3457,7 +3457,7 @@ abi_source = "kelebek+decode-validated" [opcode.semantics] name = "gfx-cmd-register" category = "draw" -summary = "0x1a2 (val) — gfx cmd-type 3. Handler gfx_op_0x1a2_registry_insert @0x42d360: builds key '%c%8.8x'(3, operand-desc) and INSERTS operand 1 into the gfx command-buffer registry (FUN_0042cf70, open-addressing hash). This is what POPULATES the registry that op 0x215 queries. NOT save/scene (raw Kelebek VA 0x428010 drifted to op 0x1ac save handler). See docs/engine-re.md gfx op-contract table." +summary = "0x1a2 (handle) — gfx cmd-type 3. Handler gfx_op_0x1a2_registry_insert @0x42d360: builds key '%c%8.8x'(3, operand-desc) and INSERTS operand 1 into the op-0x215 query registry (FUN_0042cf70, open-addressing hash; native stores map[handle]=handle). This is the SOLE populator of the registry op 0x215 queries — the geometry SET/draw ops (0x217/0x219/0x1ff/0x1fb/0x202/...) do NOT register. VM impl: GfxState.Register(handle) (a separate set from the geometry object store). Conflating the two (registering on every GetOrCreate) was the retained-mode geometry bug: CG handles wrongly read back as 'existing' and collapsed to (-400,-600). NOT save/scene (raw Kelebek VA 0x428010 drifted to op 0x1ac save handler). See docs/engine-re.md gfx op-contract table." noop_headless = false source = "investigation" confidence = "high" @@ -5249,7 +5249,7 @@ abi_source = "kelebek+decode-validated" [opcode.semantics] name = "query-gfx-object?" category = "draw" -summary = "0x215 (out)(handle_id) — native graphics command-buffer op. Real handler FUN_0042a0b0 (Ghidra-resolved via the dispatch table ctx[0x26c93+op]; Kelebek's 0x421160 is VA-drift, lands in an unrelated fn). Does TWO things: (1) writes cmd-type 5 into the CURRENT gfx-object record `[ctx+0x53d88 + ctx[0x53d14]*0x78]` (a command-buffer registration, parallel to op 0x1a2→type 3); (2) returns `out = map.find(handle_id)` over an engine-internal associative registry (found value, else 0xffffffff=not-found), sign-tested (gre/lt 0) to drive label_12649's slot-select branch + set working slot G[0x62452]. So `out` is NATIVE COMMAND-BUFFER STATE (the registry is populated by sibling gfx ops — op 0x1a2→FUN_0042cf70 is the hash insert), NOT the VM global bank → seeding story-state CANNOT reproduce it. Stubbed → constant return → every draw collapses to slot 0 → anchor-preserve reads foreign-sized textures → the cumulative bg/sprite drift. SETTLES the drift as (b) a genuine native op, NOT (a) state-divergence. Faithful fix = model the gfx command-buffer (record array + handle→object registry) and run the gfx ops instead of stubbing — static/Frida-free (handlers now readable; inserts are bytecode-driven). Full decode + verdict: docs/engine-re.md (op 0x215 section)." +summary = "0x215 (out)(handle_id) — native graphics command-buffer op. Real handler FUN_0042a0b0 (Ghidra-resolved via the dispatch table ctx[0x26c93+op]; Kelebek's 0x421160 is VA-drift, lands in an unrelated fn). Does TWO things: (1) writes cmd-type 5 into the CURRENT gfx-object record `[ctx+0x53d88 + ctx[0x53d14]*0x78]` (a command-buffer registration, parallel to op 0x1a2→type 3); (2) returns `out = map.find(handle_id)` over an engine-internal associative registry (found value, else 0xffffffff=not-found), sign-tested (gre/lt 0) to drive label_12649's slot-select branch + set working slot G[0x62452]. So `out` is NATIVE COMMAND-BUFFER STATE (the registry is populated by sibling gfx ops — op 0x1a2→FUN_0042cf70 is the hash insert), NOT the VM global bank → seeding story-state CANNOT reproduce it. Stubbed → constant return → every draw collapses to slot 0 → anchor-preserve reads foreign-sized textures → the cumulative bg/sprite drift. SETTLES the drift as (b) a genuine native op, NOT (a) state-divergence. Faithful fix = model the gfx command-buffer (record array + handle→object registry) and run the gfx ops instead of stubbing — static/Frida-free (handlers now readable; inserts are bytecode-driven). Full decode + verdict: docs/engine-re.md (op 0x215 section). RETAINED-MODE FIX (2026-07-07): the registry MUST be separate from the geometry object store — it is populated ONLY by op 0x1a2, never by the geometry SET/draw ops. VM: QuerySlot returns the registered value (=handle) or -1, NOT a fabricated per-object slot. CG handles are never 0x1a2-registered → query returns -1 → label_12649 takes its FRESH branch (anchor from the INIT2 arrays) → dst=(0,0). The prior GfxState.GetOrCreate-assigns-AcquireSlot model made CG handles read as 'existing' → existing branch called get-texture-size on the wrong slot (0) → dst=(-400,-600) off-screen (the '2nd CG off-screen' bug)." noop_headless = false source = "investigation" confidence = "high"