OpenMaidEngine/docs/superpowers/specs/2026-07-06-a2b-graphics-geometry-design.md

Design: A2b — Graphics Geometry (the 0x208 keystone + blit compositor)

Status: approved (design) · Date: 2026-07-06 Related: docs/phase-a-slice-plan.md (A2b), docs/superpowers/specs/2026-07-06-a2b-background-design.md (the first-pass render this builds on), vm-map/opcodes.toml (op 0x208), engine/Age.Engine (Vm/VirtualMachine.cs, Hosting/IHost.cs), godot/{GodotAdvHost,Main}.cs, engine/Age.Cli/Program.cs, build/disasm/SC0000.asm (subroutine label_12649).

Problem / goal

A2b's first-pass render composites the full-screen event-CG layer correctly, but sprites and BG* backgrounds routed through the CG-load subroutine have garbage geometry — they land off-center and their sizes come out 0×0. The status doc framed the fix as implementing "the sprite position/registration/animation chain," implying a large native subsystem.

Recon overturns that. In SC0000.asm, the CG-load subroutine label_12649 computes all geometry in bytecode using ordinary add/sub/div/lookup-array the VM already executes correctly. The only missing native primitive is 0x208 = get-texture-size(slot) → (out_w, out_h). Because it is stubbed, the width/height output globals stay 0, so every downstream centering/anchoring computation operates on zeros → garbage dst, 0×0 sizes.

The load-bearing sequence (from label_12649):

0x126e1:  set-texture (G[0x62424]=resId) (slot=G[0x62452]) -1      ; load the AGF into the slot
0x126e8:  op 0x208 (slot G[0x62452]) → w=G[0x62453], h=G[0x62454]  ; GET TEXTURE SIZE  ← stubbed = 0,0
0x126ef:  div local = w / 2
0x126f6:  sub G[0x62498] = G[0x6249b] - w/2       ; top-left x = anchorX - w/2   (horizontal center)
0x126fd:  sub G[0x62499] = G[0x6249c] - h          ; top-left y = anchorY - h     (foot anchor)
0x1270b:  draw-texture (handle) (slot) 0 0 w h dstX=G[0x62498] dstY=G[0x62499]

Goal: implement 0x208 (host returns the real dimensions of the image loaded in a slot) and replace the TextureRect-per-slot approximation with a faithful immediate-mode blit compositor, so that sprites and backgrounds position and size correctly — driven entirely by the executed bytecode. Add a headless gfx diagnostic to verify computed geometry without launching Godot.

Scope

In:

• 0x208 promoted from stub to a real VM op that writes texture dims into its output operands, backed by a new IHost.GetTextureSize(slot) → (w, h).
• A screen backbuffer blit compositor in the Godot host: one mutable 800×600 Image; draw-texture blits the source slot's image (src rect → dst) into it in execution order; a single TextureRect displays it. Source images kept per slot (dict<slot, Image>) so the dims 0x208 returns come from the actually-loaded image.
• Age.Cli gfx <SCENE.BIN> [0xADDR=VAL ...] — dumps each executed set-texture/draw-texture/0x208 with resolved file + computed geometry (mirrors the audio diagnostic), for a headless numeric check.
• Trace/selftest parity preserved (see below).

Out (deferred, explicitly not this pass):

• Alpha/additive blend + AE* fades (0x202/0x203 and the fade/flash effects). The compositor is built to accept alpha later, but blend semantics are not implemented here — they need Frida to confirm op roles and would risk stalling this pass.
• Green chromakey for sprites (depends on whether AGF→BMP conversion already carries alpha; a separate question).
• True multi-surface compositing — resolving what the non-screen dest handles (the per-sprite lookup-array'd handles vs 0xcf08 = screen) actually mean. This pass collapses every draw-texture dest onto the one screen canvas (see below); genuine offscreen surfaces are a later, Frida-informed step.
• The sprite animation chain (0x217/0x218/0x21a write geometry globals for stored/animated records) beyond what static positioning needs. We treat these as they currently are unless a wrong picture forces otherwise.

Why 0x208 is the keystone (and why the math is already correct)

The VM already runs add/sub/div/lookup-array/lookup-array-2d with validated pointer/lvalue semantics (A0 RECOVER test). Every coordinate in label_12649 is derived by those ops from two inputs: the anchor globals and the texture width/height. The width/height are the only values the bytecode cannot compute itself — they come from the loaded image via 0x208. Supply them and the existing, already-correct arithmetic yields correct dst/w/h. No new positioning logic is written in C#; we provide one measurement primitive and let the bytecode do what it already does.

This also explains the two 0x208 calls around a set-texture: the engine preserves a center-x / bottom-y anchor across a texture swap — measure old size to derive the anchor, load the new texture, measure new size to re-derive the top-left. Both calls need real dims; a stub breaks both.

Architecture

Engine — 0x208 becomes a real op (Age.Engine)

IHost gains one method (mirrors the WaitForInput/texture-op additions):

(int Width, int Height) GetTextureSize(int slot);

VirtualMachine.Step replaces the default → OnStub fall-through for opcode 0x208 with a handler that reads the slot operand, queries the host, and writes both dims into the output operands:

case "get-texture-size":   // 0x208 (slot) (out_w) (out_h)
    var (w, h) = _host.GetTextureSize((int)Read(a[0]));
    Write(a[1], w); Write(a[2], h);
    return pc + 1;

(The opcode is renamed from u00420BF0 to get-texture-size in opcodes.toml, source = inference, with the label_12649 evidence; then opcodes_build.py --build regenerates the derived files.)

Non-Godot hosts (CaptureHost, test RecHost/CountHost) return (0, 0) → the handler writes 0/0, which equals the pre-change behavior (globals defaulted to 0 and were never written). So:

• --selftest (SC0000 show-text offset sequence) stays byte-identical.
• A1 trace-diff stays byte-identical (offsets + halt + step count — 0x208 was already one step via OnStub; it is still one step).
• Engine test count is preserved; add a TextureOps/geometry test asserting 0x208 writes host dims into its two output globals (with a fake host returning known dims).

Godot host — screen backbuffer blit compositor (godot/)

Replace the dict<slot, string bmpPath> + TextureRect-per-slot model with:

• GodotAdvHost: dict<int, Image> _slotImg — SetTexture(resId, slot) resolves via ResourceMap (unchanged), loads the pre-converted BMP into an Image, stores it, and records its dims. GetTextureSize(slot) returns the stored image's (GetWidth(), GetHeight()) (or (0,0) if empty).
• Main: one screen Image _screen (800×600, Format.Rgba8) shown by a single TextureRect. DrawTexture(slot, sx, sy, w, h, dx, dy) → CallDeferred a BlitSlot that _screen.BlitRect(_slotImg[slot], srcRect(sx,sy,w,h), new Vector2I(dx,dy)) and refreshes the TextureRect's ImageTexture. Execution order = paint order → correct z (full-frame bg first, sprites over it) with no separate layering logic.
• Dest-handle collapse: draw-texture's dest handle arg is ignored for now; every draw blits onto the one screen canvas. A sprite the real engine routes through an offscreen buffer still lands on screen at its computed dst. If this collapse visibly double-draws or misplaces, that is the signal to implement true multi-surface compositing (a later, Frida-informed pass).

IHost.DrawTexture already carries (slot, srcX, srcY, w, h, dstX, dstY); no signature change. The VM's draw-texture dispatch is unchanged — it already passes those operands.

CLI — the gfx diagnostic (Age.Cli)

Age.Cli gfx <SCENE.BIN> [0xADDR=VAL ...] runs the scene under a small recording host that implements GetTextureSize from a lightweight in-memory image-dims lookup (reads the pre-converted BMP headers for each resolved slot, no Godot) and logs, in execution order: each set-texture (slot ← resId → file), each 0x208 (slot → returned w×h), and each draw-texture (slot, src rect, computed dst, w×h, resolved file). Optional 0xADDR=VAL seeds globals (same as audio). This gives a headless numeric oracle: the background should resolve to (0,0) 800×500; sprites should be horizontally centered and foot-anchored at plausible on-screen coordinates. It reuses the same section resolver — no new resolution logic.

Data flow

bytecode (label_12649)                 host                                screen
──────────────────────                 ────                                ──────
set-texture(resId, slot)  ───────────► SetTexture: resolve → load BMP →
                                        _slotImg[slot] = Image (w×h known)
0x208(slot) → w,h globals ───────────► GetTextureSize(slot) → (w,h)
  (VM Writes w,h into globals)
add/sub/div (VM)  ── compute dst, size from anchor + w,h  ──►
draw-texture(_, slot, sx,sy,w,h, dx,dy) ─► BlitSlot: _screen.BlitRect(     ──► TextureRect shows _screen
                                            _slotImg[slot], (sx,sy,w,h), (dx,dy))

Error handling / edge cases

• Empty slot on 0x208 (the pre-set-texture call in the anchor-preserve path): host returns (0,0); the engine does the same when a slot has no texture. Acceptable — the second 0x208 (after load) drives the final draw.
• BMP missing / load failure: SetTexture leaves the slot empty (logs once); GetTextureSize → (0,0); draw-texture on an empty slot is a no-op blit. Fails soft, never throws.
• dst off-canvas / oversized src rect: clamp the blit to the screen bounds (Godot BlitRect already ignores out-of-bounds regions; verify and clamp srcRect to the source image size).
• Dims mismatch (AGF native vs converted BMP): the converted BMP is authoritative for what we render; 0x208 returns the BMP dims so geometry matches what is actually blitted.

Testing / verification

1. Engine unit test — 0x208 writes host-provided dims into its two output operands; parity assertions that CaptureHost.GetTextureSize returns (0,0) and leaves trace/step-count unchanged.
2. --selftest + A1 trace-diff — must stay byte-identical (SC0000 186-line offset sequence; all SC/SP step counts). This is the guardrail that the new op didn't perturb control flow.
3. gfx diagnostic — run Age.Cli gfx SC0000.BIN; assert (by eye, then a smoke check) the background resolves to (0,0) 800×500 and sprite draws are centered/foot-anchored at sane coordinates (not 0×0, not off-screen).
4. Eyeball in Godot — the opening renders with the background placed correctly and any sprites at plausible positions/sizes. This is the final human oracle (no machine oracle for pixels).
5. Frida cross-check (only if numbers look wrong) — capture the real game's draw-texture geometry and diff against the gfx dump.

Risks / open questions

• Dest-handle collapse is a simplification. If the opening relies on offscreen surfaces (sprite buffers composited to screen with transforms), collapsing to one canvas could double-draw or misplace. Mitigation: the gfx dump + eyeball surface it immediately; true multi-surface work is the designated follow-up.
• 0x217/0x218/0x21a (gfx-geom?) write geometry globals for stored/animated sprite records. Static positioning in label_12649 flows through draw-texture's explicit dst, so we expect these are not needed for a correct still. If a sprite is misplaced despite correct 0x208, these are the next suspects.
• Chromakey deferred: sprites may render with a visible background box until chromakey/alpha lands. This is expected and out of scope; note it when eyeballing so it isn't mistaken for a geometry bug.
• vm0.py divergence on branchy scenes (known): use the C# VM / gfx diagnostic for non-opening scenes, not vm0.py --settex.

Success criteria (this pass done)

• 0x208 implemented; IHost.GetTextureSize added; opcode renamed in opcodes.toml and rebuilt.
• Godot host uses the screen backbuffer blit compositor; source images kept per slot.
• --selftest and A1 trace-diff byte-identical; engine tests green (+1 geometry test).
• Age.Cli gfx SC0000.BIN shows the background at (0,0) 800×500 and sprite draws with non-zero, centered/foot-anchored geometry (no 0×0, no off-center background).
• Eyeball: SC0000 opening renders with correct background placement and plausibly-placed sprites.