OpenMaidEngine/docs/superpowers/specs/2026-07-07-gfx-animation-subsystem-design.md

# Design — sprite transform / animation subsystem (opening slice)

Date: 2026-07-07
Status: approved (brainstorming), pending implementation plan
Branch: `feat/gfx-command-buffer` (continues the gfx command-buffer work)

## Problem

The scene-completeness tracker (`tools/scene_opcode_coverage.py`, added 2026-07-07) makes SC0000's
un-implemented opcodes legible: instruction-weighted the VM handles ~94.8%, but **68 GAP opcodes** are
silently skipped. The largest rendering cluster of these is `0x21c–0x243` (+ `0x2bd/0x2bf`) — e.g.
`0x220`×66, `0x22f`×34, `0x228`×33, `0x21e`×25 static sites in SC0000.

Native RE (see `docs/engine-re.md`, "The `0x21c–0x243` sprite transform / ANIMATION cluster") resolved
**every** handler in the band through the anchored dispatch table (`ctx[0x26c93+op]`, from `FUN_00413860`)
and showed it is **one coherent subsystem: sprite transform + animation/tween**. Two members were already
named in prior RE — `0x234 gfx_op_0x234_anim_start`, `0x238 gfx_op_0x238_set_anim_clock`. The representative
SET ops `0x220`/`0x21e` (both `argc 6`, now annotated in Ghidra) write **cmd-type `0xd`**, fetch operands
1..6, and call a transform worker `(handle, op2, op3, float op4, float op5, float op6)`; `0x21e` normalizes
the floats by `/_DAT_00571c28` (→ scale/percentage). The worker `gfx_anim_set_channel`@`0x47eaa0` uses the
**same `gfx_object_get_or_create`** our `GfxState` already models and arms an animation channel on the object
record (`obj+0x3c=op2`, `obj+0x50=op3`, `obj+0x68=1` enable, `obj+0xac=vec3(op4,op5,op6)` target). Combined
with `anim_start`/`set_anim_clock`, this is a per-frame clock that interpolates the target over time — i.e.
**what makes `AE*` fades/effects animate instead of snap**. Today the Godot compositor blits every object
**opaque** with no transform and no time, so the opening's fade "explosion glow" stays put.

## Goal

Render the SC0000 opening's animated effect(s) — specifically the `AE*` fade — correctly: the effect
**animates over time** rather than snapping or staying opaque. Do it as the smallest verifiable slice, and
leave a clear, measurable trail (tracker GAP shrink) for expanding to the rest of the cluster later.

## Decisions (from brainstorming)

1. **Timing fidelity = wall-clock tween.** The VM records the animation channels (targets + durations) into
   `GfxState` deterministically; the Godot compositor interpolates them over its own frame delta. Rendering
   is frontend-only, so **headless VM trace parity is untouched**. We decode `anim_start`/`set_anim_clock`
   enough to get durations/targets but do **not** replicate the game's exact native tick.
2. **Scope = opening-driven subset first.** Trace what SC0000's booted opening actually executes, implement
   only those anim ops, verify the fade animates, then expand in follow-ups. Only model what we can confirm
   on screen.
3. **Architecture = passive `GfxState` + compositor-owned tween + alpha-aware blit.** The anim ops only
   record channel data on the object; the compositor owns all wall-clock/tween logic and the new alpha
   compositing. Keeps `GfxState`'s established passive-data-model role and folds in the deferred
   `0x202/0x203` alpha as a side effect.

## Non-goals / deferred

- Cluster ops that appear only in battle/debug scenes (`BTL`/`DEBUGADV`) and are **not** on the opening
  path — they stay on the `default` VM stub and keep showing as GAP in the tracker (honest remaining work).
- Scene-coroutine / script-yield timing ops (`0x7b`/`0x140`/`sleep 0xc8`). If the opening's fade is driven
  by a script poll-loop that needs these, we handle the *fire-and-forget* animation-command path and record
  the coupling; the coroutine model is a separate backlog item.
- The native DirectDraw workers (`FUN_0047xxxx`) — not modeled, consistent with the existing gfx family.
- Frame-exact reproduction of the game's animation clock.

## Invariants (must hold)

- **Headless VM parity:** anim ops are record-only on the VM side (like every existing gfx op); the
  non-Godot hosts (`CaptureHost`, test `RecHost`/`CountHost`) read none of the new state → `--selftest`,
  `sweep`, and existing engine tests stay byte-identical.
- **`GfxState` stays passive** — no time/`Tick`; it exposes recorded channel data, nothing more.
- **`opcodes.toml` is the source of truth** for op labels; the VM dispatches on `label` and the table is
  rebuilt via `opcodes_build.py --build` (never hand-edit generated files).

## Architecture

### A. RE step (executed first in the plan — the one real risk)

The chunk gates on two facts we don't yet have:

1. **Decode `0x234 anim_start` and `0x238 set_anim_clock`** (handler addresses already resolved in the
   `FUN_00413860` dispatch map). Recover their operand contract and which fields they set (duration/clock,
   the start trigger, which object/channel). Annotate the handlers in the Ghidra project (`gfx_op_0x234_*`,
   `gfx_op_0x238_*`) and record the contract in `docs/engine-re.md`.
2. **Trace the `--boot` opening** (`Age.Cli gfx --boot SC0000.BIN` and/or `play --boot --trace`) to confirm
   *which* cluster ops execute on the opening path, in what order relative to the `AE*` CG loads /
   `draw-texture` / `0x202`/`0x203`, and therefore **what quantity is being animated** — the transform vec3
   (`obj+0xac`) or the packed alpha from `0x202/0x203`.

Output: the confirmed op subset + an `engine-re.md` addendum. **If the trace shows the fade's alpha is
`0x202/0x203`-driven**, the chunk narrows to "alpha-blend compositing + those two ops" — even smaller — and
the transform ops become a later slice.

### B. Data model — `GfxState` / `GfxObject` extensions (`Age.Engine/Model/GfxState.cs`)

Extend `GfxObject` with the animation channel the worker revealed:

- `(long X, long Y, long Z) AnimTarget;` — the `obj+0xac` transform target (semantics per RE: scale, color,
  or offset; stored faithfully regardless).
- `long AnimParam1, AnimParam2;` — `obj+0x3c` (op2) and `obj+0x50` (op3).
- `bool AnimEnabled;` — `obj+0x68`.
- `long AnimDurationTicks;` — from `set_anim_clock`/`anim_start`.
- `long AnimGeneration;` — bumped every time `anim_start` fires on the object; the compositor's trigger to
  (re)start a tween.

New passive methods (mutate the object, bump generation where appropriate), called from the VM dispatch:

- `SetAnimTransform(long handle, long p1, long p2, (long,long,long) target, bool normalized)` — for
  `0x21e`/`0x220`. (Normalization: `0x21e` divides operands by the runtime divisor; store the fraction as the
  design's chosen fixed representation — decide the unit during RE, e.g. permille or a float field.)
- `StartAnim(long handle, …)` — for `0x234`; sets `AnimEnabled` + bumps `AnimGeneration`.
- `SetAnimClock(long handle_or_scope, long duration)` — for `0x238`.

`SnapshotVisibleObjects()` (and the `RenderObject` record) gain the anim channel + `AnimGeneration` +
`AnimDurationTicks` so the compositor can tween without reaching into `GfxState` internals.

### C. VM dispatch (`Age.Engine/Vm/VirtualMachine.cs` + `vm-map/opcodes.toml`)

- Add `label`s in `opcodes.toml` for the confirmed subset (dispatch keys on `label`, the `0x212–0x21a`
  precedent): e.g. `0x21e = set-anim-transform-norm`, `0x220 = set-anim-transform-abs`, `0x234 = anim-start`,
  `0x238 = set-anim-clock`, plus any opening-path query op. Rebuild `opcodes.json`/reference via
  `opcodes_build.py --build`.
- Add `case` arms in `Step` that read operands and call the `GfxState` methods, each returning `pc+1` —
  identical shape to the existing gfx ops. Everything else in the cluster stays on `default` (still GAP).

### D. Godot compositor — the visible payoff (`godot/Main.cs`)

- **Per-handle tween table** (frontend-only): `Dictionary<long, TweenState { Vector startTransform,
  targetTransform; float elapsed, duration; long generation; }>`.
- Each `_Process`/`Recomposite` frame: for each animated visible object, if its `AnimGeneration` differs from
  the tracked one → (re)initialize the tween (start = current on-screen transform, or identity on first
  sight); `elapsed += delta`; `t = clamp(elapsed / duration, 0, 1)`; interpolate; apply.
- **Alpha-aware blit:** replace the opaque `BlitRect` in `BlitLayer` with a composite that supports per-object
  **alpha** (Godot `Image.BlendRect` for straight alpha; manual per-pixel only if scale/offset is needed).
  First pass prioritizes **alpha (fades)** — the user-visible `AE*` defect; scale/position added only if the
  trace shows the opening needs them. This is where `0x202/0x203`'s stored packed color is finally applied.

## Data flow

```
VM thread (deterministic):
  set-anim-transform (0x21e/0x220)  -> GfxState.SetAnimTransform(handle, …, target)
  anim-start          (0x234)       -> GfxState.StartAnim(handle)   [bumps AnimGeneration]
  set-anim-clock      (0x238)       -> GfxState.SetAnimClock(…, duration)
        (records channel data on the object; no time)

Godot main thread, every _Process(delta):
  Recomposite():
    for each visible object o in SnapshotVisibleObjects() (ascending handle = z-order):
      if o.AnimGeneration != tween[o.Handle].generation:  start tween (capture start transform)
      advance tween.elapsed += delta; t = clamp(elapsed/duration)
      transform = lerp(start, target, t)
      BlitLayer(surface, srcRect, dst, alpha/scale from transform)   [alpha-aware]
```

## Testing / verification

- **Engine unit tests** on *synthesized* scenes (per the "synthesize, don't disable" rule,
  `ScriptAssembler`): assert `GfxState` records target/duration/generation from the anim ops; assert the
  non-Godot hosts stay byte-identical (parity). No real-scene golden is frozen.
- **Tracker:** `scene_opcode_coverage.py SC0000` — the implemented subset moves impl-ward and the GAP count
  drops; this is the chunk's completeness metric.
- **Visual:** extend the `--shot` capture to grab a few time offsets mid-tween (or capture at fixed elapsed
  points) and confirm the `AE*` glow **fades** across frames instead of staying opaque.
- **Headless parity:** existing `--selftest` and `sweep` outputs unchanged.

## Sequencing

RE (A) → data model (B) → dispatch (C) → compositor (D), running verification (tracker + tests +
screenshot) after each so a wrong assumption surfaces early. **A is the gate**: its trace result can shrink
the whole chunk (alpha-only) or confirm the transform-tween scope.

## Risks / open questions

- **What `obj+0xac` controls visually** (scale vs color vs offset) — resolved by the RE step; the data model
  stores it faithfully either way, so a wrong guess costs only the compositor's interpretation, not the
  recording.
- **Script-driven vs engine-driven animation.** In the real engine the script arms the anim then *yields*
  (coroutine/`sleep`) while the native loop ticks. Our VM runs straight through (sleep/coroutine stubbed),
  so we capture anim commands as fire-and-forget and tween them in the compositor. If the opening's fade
  instead relies on a script poll-loop we can't run headless, that's the scene-coroutine backlog, not this
  chunk — the RE trace tells us which.
- **Normalization unit** for `0x21e` (`/_DAT_00571c28`, runtime-init, static 0) — pin the divisor's runtime
  value (or infer from corpus `0x64`→1.0 scale) during RE; pick a stable stored representation.

## Canonical docs touched

- `docs/engine-re.md` — op-contract addendum for `0x234`/`0x238` + confirmed opening subset.
- `vm-map/opcodes.toml` — labels for the subset (then `opcodes_build.py --build`).
- `docs/phase-a-slice-plan.md` — A2b results for this slice.
- Status memory — milestone entry.