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

Design: A2b-Background — Engine-Driven Background Layer (SC0000)

Status: approved (design) · Date: 2026-07-06 Related: docs/phase-a-slice-plan.md (A2), the A2a Godot project (godot/), engine/Age.Engine, build/data/CGINIT.json, extracted/DATA1/AGF2BMP2AGF.exe, extracted/DATA2|DATA5/*.AGF.

Problem / goal

A2a plays SC0000's dialogue on a black screen. A2b-Background renders the scene's background layer, driven by the bytecode — the VM's create/set/draw-texture ops execute for real, the Godot backend renders the slots whose resource it can resolve through a data map, and the background appears because those ops ran (remove them → nothing draws). This is not a pinned/hardcoded image; it is the first real graphics op-path promoted from stub to backend, with resolution as growable profile data.

Scope

In: the single background layer for SC0000 — promote create-texture/set-texture/ draw-texture to typed IHost methods; a resourceId → AGF resolution map (seeded for SC0000's bg via investigation); offline AGF→image conversion; Godot composites the resolved full-screen background behind the dialogue. Out: the other ~239 draws (full sprite/UI/effects compositor), general resolution for all resources, per-op fade/blend semantics, voice, choices, non-SC0000 scenes. These follow later; the resolution map and rendered slots grow over time.

The engine-driven principle (why this isn't a pin)

The bytecode drives every texture op. The backend keeps a slot → texture table; SetTexture(resId,slot) resolves resId via the map and loads the (pre-converted) image into that slot; DrawTexture(slot,…) renders a resolved full-screen slot into the background node. Unresolved slots (the other 239 draws) render nothing yet. The background shows only because set-texture/draw-texture executed and resId resolved. The map is per-game profile data, not a code shortcut; coverage grows as we map more resources.

Architecture

Engine — promote texture ops (Age.Engine)

Add to IHost (mirrors the WaitForInput addition; CaptureHost no-ops them so A1 trace-diff + A2a selftest stay green):

void CreateTexture(int slot, int width, int height);
void SetTexture(long resourceId, int slot);
void DrawTexture(int slot, int x, int y, int width, int height);

In VirtualMachine.Step, replace the OnStub fall-through for these opcodes with handlers that read the operands and call the host (operand roles are inferred from disassembly — Phase 1 confirms/adjusts):

• create-texture args (slot, w, h, ?) → CreateTexture(Read(a0), (int)Read(a1), (int)Read(a2))
• set-texture args (resId, slot, ?) → SetTexture(Read(a0), (int)Read(a1))
• draw-texture args (fade, slot, x, y, w, h, ?, ?) → DrawTexture((int)Read(a1), (int)Read(a2), (int)Read(a3), (int)Read(a4), (int)Read(a5))

Opcode numbers (from vm-map/opcodes.toml): create-texture, set-texture, draw-texture are named Kelebek ops; the VM dispatches on those labels exactly as it does show-text.

Resolution map (profile data)

build/resources.json (or a profile dir): { "<resourceId hex>": "<AGF filename>" }, seeded by Phase 1 for SC0000's background. Format is tentative — Phase 1 may show ids are scene-scoped (then keyed {scene: {id: agf}}) rather than global. Lives on the backend/profile side, never in the VM core.

AGF → image pipeline

Offline: run AGF2BMP2AGF.exe <name>.AGF (verified: produces an 800×600 24-bit BMP) on the mapped AGFs, into a Godot-loadable assets dir (e.g. build/textures/). Godot loads with Image.LoadFromFile + ImageTexture.CreateFromImage. (A tiny tools/convert_agf.py wrapper converts the set named in resources.json.)

Godot backend + compositing (godot/)

Main adds a background TextureRect behind the dialogue Label (full-rect, StretchMode = keep-aspect- covered), created before the dialogue label so it's z-behind. GodotAdvHost implements the texture ops:

• SetTexture(resId, slot) → resolve resId in the map; if found, CallDeferred load the pre-converted image into a slot → ImageTexture dict (main thread).
• DrawTexture(slot, x, y, w, h) → if the slot has a texture and the draw is full-screen (≈800×600), CallDeferred set the background TextureRect's texture. Unresolved/non-fullscreen slots: ignore.
• CreateTexture → record slot dimensions (used to distinguish full-screen bg from small textures).

Phase 1 — Investigation (gated; the real unknown)

Goal: resolve SC0000's background AGF and document the resourceId → AGF mechanism.

1. Static: confirm the operand roles of create/set/draw-texture; identify which full-screen draw is the visible background (SC0000 draws slot 3 cross-context and slot 0xe from local set-texture 0x21); probe the resolution — SYS4INI (ALF filename index), *INIT tables, any id→name path. (CGINIT is a per-CG numeric record table, not a direct filename map, so resolution is likely a runtime path.)
2. Frida (if static is inconclusive): attach to the running translated game on SC0000; hook the graphic-load call; capture the actual resourceId → AGF filename for the background draw. This yields both the mechanism and a ground-truth oracle.
3. Confirm: convert the resolved AGF, eyeball that it is SC0000's intro background; seed resources.json.

Gate: Phase 1's result confirms the operand mapping + resolution shape before the engine handlers and map format are finalized. Expect Frida to be needed (first Frida use in the project).

Validation

• Headless resolve-oracle: a test runs SC0000 with a recording host and asserts the background draw path fires SetTexture with the expected resource id, and the map resolves it to the expected AGF (Phase 1 ground truth) — validates engine-driven resolution without pixels.
• Regression: dotnet test engine/AgeEngine.sln stays green and the A2a --selftest still prints SELFTEST OK (new IHost methods no-op in CaptureHost).
• Manual visual (human): the converted background renders behind SC0000's dialogue in the Godot window and looks like the intro art; dialogue still advances on click/Enter.

Risks

• Resolution is the crux and uncertain-sized. CGINIT isn't a filename map and SC0000's primary bg slot is loaded cross-context; static RE may quickly stall → Frida. Mitigation: the machinery (op wiring, pipeline, compositing, map-lookup) is built independently of how the map is populated; Phase 1 only has to yield SC0000's one bg entry to unblock the visual.
• Draw-op operand roles are inferred — Phase 1 confirms before the handlers are trusted; the headless oracle (which resId the bg path resolves) catches a wrong mapping.
• No pixel oracle — background correctness is human-eyeballed; the resolve-oracle is the automatable proxy. Frida capture is the strongest available ground truth.
• First Frida use — attaching to the packed AGE.EXE at runtime (packer is bypassed once running); budget setup time. If Frida is impractical, static-plus-eyeball is the fallback for this one bg.
• Trace parity — adding IHost texture methods must not change Steps/Emitted; guaranteed by CaptureHost no-ops (verified by the A1 trace-diff regression).

Out of scope (later slices)

Full draw compositor (all 239 draws, layers, blends, fades), general/automated resolution for all resources, sprite/CG/UI rendering, voice + BGM, choices, call-script/state seeding, non-SC0000 scenes.