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

# Sprite Transform/Animation Subsystem (Opening Slice) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make SC0000's opening `AE*` fade actually animate — implement the sprite transform/animation ops the booted opening executes, tweened over wall-clock time in the Godot compositor with alpha.

**Architecture:** The VM records animation-channel data on gfx objects (passive `GfxState`, no time) exactly like the existing gfx command-buffer ops, so headless trace parity is untouched. The Godot compositor owns a per-handle tween table, interpolates the recorded target over its frame delta, and applies alpha in the blit. Native DirectDraw workers are not modeled.

**Tech Stack:** C# / .NET 8 (`Age.Engine`, xUnit), Godot 4.7 .NET (`godot/`), Python 3.11 tooling (`opcodes_build.py`, `scene_opcode_coverage.py`), Ghidra+MCP for the RE gate.

## Global Constraints

- **Run Python as** `py -3.11 -X utf8 tools/<name>.py …` (cp932 needs utf8 mode on Windows).
- **Never hand-edit generated files.** Edit `vm-map/opcodes.toml`, then `py -3.11 -X utf8 tools/opcodes_build.py --build` regenerates `build/opcodes.json` + `tools/age_opcodes_himegari.py` + `docs/opcode-reference.md`.
- **VM dispatches on the opcode's top-level `label`** in `opcodes.toml` (the `0x208`/`0x215` precedent). Setting a `label` to a dispatch name is how an op becomes handled.
- **Headless parity is sacred:** the VM must only *record* gfx state; non-Godot hosts (`CaptureHost`, test `RecordingHost`/`CountHost`) read none of it. Existing `--selftest`, `sweep`, and engine tests must stay byte-identical.
- **`GfxState` stays a passive data model** — no time/`Tick`; it exposes recorded data only.
- **Ghidra: annotate as you RE** — rename `FUN_...` → `gfx_op_0x<op>_<role>`, add a plate comment with the decode, `save_program`. The Ghidra program is `range_00400000.bin` (Raw x86:LE:32:default @0x400000); handler for op N = the value stored to `param_1[0x26c93 + N]` in `FUN_00413860`.
- **Test commands:** all engine tests `dotnet test engine/AgeEngine.sln --nologo`; one class `dotnet test engine/AgeEngine.sln --nologo --filter "FullyQualifiedName~<ClassName>"`.
- **Branch:** continue on `feat/gfx-command-buffer`. Commit after each task.

---

## File Structure

- `docs/engine-re.md` — RE addendum: `anim_start`/`set_anim_clock` operand contract + confirmed opening op subset (Task 1).
- `engine/Age.Engine/Model/GfxState.cs` — animation-channel fields + `SetAnimTransform`/`StartAnim`/`SetAnimClock`; `RenderObject` gains an `AnimState` (Tasks 2, 5).
- `vm-map/opcodes.toml` — labels for `0x21e`/`0x220`/`0x234`/`0x238` (Task 3).
- `engine/Age.Engine/Vm/VirtualMachine.cs` — `case` arms for the four ops (Tasks 3, 4).
- `engine/Age.Engine.Tests/GfxAnimationTests.cs` — unit tests (Tasks 2–5).
- `godot/Main.cs` — tween table + alpha-aware blit in `Recomposite`/`BlitLayer` (Task 6).
- `docs/phase-a-slice-plan.md`, status memory — results (Task 7).

---

## Task 1: RE gate — decode `anim_start`/`set_anim_clock` + confirm the opening subset

**Files:**
- Modify: `docs/engine-re.md` (append to the "0x21c–0x243 sprite transform / ANIMATION cluster" section)
- Ghidra project `range_00400000.bin` (annotations only)

**Interfaces:**
- Produces: **the operand contract** for `anim-start` (op `0x234`) and `set-anim-clock` (op `0x238`) — for each: `argc`, and the role of each operand (handle? duration/ticks? channel index?). Also: **the confirmed list of cluster ops SC0000's `--boot` opening actually executes**, and **which quantity the fade animates** (the `0x21e/0x220` transform vec3 at `obj+0xac`, vs the packed alpha from `0x202/0x203`). Tasks 3–6 consume this.

- [ ] **Step 1: Resolve the two handler addresses.** In Ghidra, open `FUN_00413860` (`decompile_function` at `0x00413860`). The dispatch slot for op N is `param_1[0x26c93 + N]`. Read the value at index `0x26ec7` (= `0x234`, `gfx_op_0x234_anim_start`) and `0x26ecb` (= `0x238`, `gfx_op_0x238_set_anim_clock`). They sit between `LAB_00423cf0` (op `0x233`) and `FUN_00423e40` (op `0x235`), and between `FUN_004240a0` (op `0x237`) and `FUN_00424120` (op `0x239`) respectively.

- [ ] **Step 2: Decompile both handlers.** `decompile_function` at each address. Read the cmd-type they write (`*(ctx + 0x53d88 + ctx[0x53d14]*0x78) = <cmd>`), the operand fetches (`FUN_0041b940(i)`, 1-based), and the worker they call. Compare to the decoded `0x220`/`0x21e` (both write cmd-type `0xd`, call a transform worker). Determine: does `anim_start` take a handle + start the channel (`obj+0x68`/a "playing" flag)? Does `set_anim_clock` set a duration/tick count (and on which object/scope)?

- [ ] **Step 3: Annotate in Ghidra.** `rename_function_by_address` each to `gfx_op_0x234_anim_start` / `gfx_op_0x238_set_anim_clock` (if not already), `set_plate_comment` with the decode (argc, operand roles, cmd-type, worker), then `save_program`.

- [ ] **Step 4: Confirm the opening's executed op subset + animated quantity.** Statically inspect the opening path in `build/disasm/SC0000.asm` around the `AE*` CG loads (search the `set-texture`/`draw-texture` sites near the fade), and cross-check dynamically:

Run: `py -3.11 -X utf8 tools/sys4load.py "$(py -3.11 -X utf8 -c "import sys;sys.path.insert(0,'tools');import paths;print(paths.scripts()['SC0000.BIN'])")" --json > build/sc0000.json` is optional; the reliable read is the disasm. Grep the disasm for the cluster ops near the fade:

Run: `py -3.11 -X utf8 -c "import re;lines=open('build/disasm/SC0000.asm',encoding='utf8').read().splitlines();[print(l) for l in lines if re.search(r'op 0x(21e|220|234|238|202|203|204)\b', l)][:60]"`
Expected: shows whether the fade region uses `0x21e/0x220` (transform) and/or `0x202/0x203` (color/alpha), and whether `0x234`/`0x238` appear. Record the finding.

- [ ] **Step 5: Write the addendum + decision.** Append to `docs/engine-re.md`: the two operand contracts, the confirmed opening op subset, and the **scope decision** — if the fade's alpha is `0x202/0x203`-driven (not the transform ops), note that Task 6 must apply that packed alpha and the transform ops become a secondary concern; otherwise confirm the transform-tween scope. This decision is the input to Tasks 3/4/6.

- [ ] **Step 6: Commit**

```bash
git add docs/engine-re.md
git commit -m "docs(gfx): decode anim_start/set_anim_clock + confirm SC0000 opening anim subset"
```

---

## Task 2: `GfxState` animation-channel data model

**Files:**
- Modify: `engine/Age.Engine/Model/GfxState.cs`
- Test: `engine/Age.Engine.Tests/GfxAnimationTests.cs` (create)

**Interfaces:**
- Consumes: nothing (pure model).
- Produces: on `GfxState.GfxObject` — fields `(long X,long Y,long Z) AnimTarget`, `long AnimParam1`, `long AnimParam2`, `bool AnimNormalized`, `bool AnimEnabled`, `long AnimDurationTicks`, `long AnimGeneration`. Methods `void SetAnimTransform(long handle, long p1, long p2, (long X,long Y,long Z) target, bool normalized)`, `void StartAnim(long handle)`, `void SetAnimClock(long handle, long durationTicks)`. Consumed by Tasks 3, 4, 5.

- [ ] **Step 1: Write the failing tests** — create `engine/Age.Engine.Tests/GfxAnimationTests.cs`:

```csharp
using Age.Engine.Model;
using Xunit;

public class GfxAnimationTests
{
    [Fact]
    public void SetAnimTransform_RecordsTargetParamsAndEnables()
    {
        var g = new GfxState();
        g.SetAnimTransform(0x1000, p1: 7, p2: 9, target: (100, 100, 100), normalized: true);
        var o = g.TryGet(0x1000)!;
        Assert.Equal((100L, 100L, 100L), o.AnimTarget);
        Assert.Equal(7, o.AnimParam1);
        Assert.Equal(9, o.AnimParam2);
        Assert.True(o.AnimNormalized);
        Assert.True(o.AnimEnabled);
    }

    [Fact]
    public void StartAnim_BumpsGenerationEachCall()
    {
        var g = new GfxState();
        g.SetAnimTransform(0x1000, 0, 0, (0, 0, 0), false);
        var gen0 = g.TryGet(0x1000)!.AnimGeneration;
        g.StartAnim(0x1000);
        g.StartAnim(0x1000);
        Assert.Equal(gen0 + 2, g.TryGet(0x1000)!.AnimGeneration);
    }

    [Fact]
    public void SetAnimClock_SetsDurationTicks()
    {
        var g = new GfxState();
        g.SetAnimClock(0x1000, 30);
        Assert.Equal(30, g.TryGet(0x1000)!.AnimDurationTicks);
    }
}
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `dotnet test engine/AgeEngine.sln --nologo --filter "FullyQualifiedName~GfxAnimationTests"`
Expected: FAIL — `GfxObject` has no `AnimTarget` etc. (compile error).

- [ ] **Step 3: Add the fields to `GfxObject`.** In `GfxState.cs`, inside `public sealed class GfxObject`, after the existing `public bool Visible;` line add:

```csharp
        // ---- animation channel (0x21e/0x220 transform-set, 0x234 anim-start, 0x238 set-anim-clock;
        // native worker gfx_anim_set_channel@0x47eaa0 writes obj+0xac target / +0x3c,+0x50 params / +0x68 enable).
        // Passive: recorded here, interpolated by the Godot compositor over wall-clock. See
        // docs/superpowers/specs/2026-07-07-gfx-animation-subsystem-design.md. ----
        public (long X, long Y, long Z) AnimTarget;
        public long AnimParam1, AnimParam2;
        public bool AnimNormalized;         // 0x21e (operand/_DAT_00571c28, ~percent) vs 0x220 (absolute)
        public bool AnimEnabled;            // obj+0x68
        public long AnimDurationTicks;      // from set-anim-clock (0x238)
        public long AnimGeneration;         // bumped by anim-start (0x234); the compositor's re-trigger
```

- [ ] **Step 4: Add the methods.** In `GfxState.cs`, after the `BindDraw` method, add:

```csharp
    /// <summary>Op 0x21e/0x220 (set-anim-transform): record the transform target + params on the object and
    /// enable its animation channel. normalized = 0x21e (operands are ~percent, /_DAT_00571c28); absolute = 0x220.
    /// Native: gfx_anim_set_channel@0x47eaa0 sets obj+0x3c=p1, +0x50=p2, +0xac=target, +0x68=1.</summary>
    public void SetAnimTransform(long handle, long p1, long p2, (long X, long Y, long Z) target, bool normalized)
    {
        lock (_lock)
        {
            var o = GetOrCreate(handle);
            o.AnimParam1 = p1; o.AnimParam2 = p2; o.AnimTarget = target;
            o.AnimNormalized = normalized; o.AnimEnabled = true;
        }
    }

    /// <summary>Op 0x234 (anim-start): begin the object's animation. Bumps AnimGeneration — the compositor
    /// (re)starts a wall-clock tween whenever this changes.</summary>
    public void StartAnim(long handle)
    {
        lock (_lock) { var o = GetOrCreate(handle); o.AnimEnabled = true; o.AnimGeneration++; }
    }

    /// <summary>Op 0x238 (set-anim-clock): set the animation duration (in game ticks/frames) for the object.</summary>
    public void SetAnimClock(long handle, long durationTicks)
    {
        lock (_lock) { GetOrCreate(handle).AnimDurationTicks = durationTicks; }
    }
```

- [ ] **Step 5: Run tests to verify they pass**

Run: `dotnet test engine/AgeEngine.sln --nologo --filter "FullyQualifiedName~GfxAnimationTests"`
Expected: PASS (3 tests).

- [ ] **Step 6: Run the full engine suite for parity**

Run: `dotnet test engine/AgeEngine.sln --nologo`
Expected: PASS, all prior tests still green (adding fields/methods touches nothing existing).

- [ ] **Step 7: Commit**

```bash
git add engine/Age.Engine/Model/GfxState.cs engine/Age.Engine.Tests/GfxAnimationTests.cs
git commit -m "feat(gfx): GfxState animation-channel model (transform target + clock + generation)"
```

---

## Task 3: Label + dispatch the transform-set ops `0x21e`/`0x220`

**Files:**
- Modify: `vm-map/opcodes.toml` (ops `0x21e`, `0x220`, `0x234`, `0x238`)
- Modify: `engine/Age.Engine/Vm/VirtualMachine.cs` (add `case` arms)
- Test: `engine/Age.Engine.Tests/GfxAnimationTests.cs` (add)

**Interfaces:**
- Consumes: `GfxState.SetAnimTransform` (Task 2).
- Produces: opcode labels `set-anim-transform-norm` (0x21e), `set-anim-transform-abs` (0x220), `anim-start` (0x234), `set-anim-clock` (0x238) in the rebuilt `build/opcodes.json`; VM `case` arms for the two transform ops. Consumed by Tasks 4, 5.

- [ ] **Step 1: Set the labels in `opcodes.toml`.** For each of the four ops, set the top-level `label` and the `[opcode.semantics]` `name`/`category`/`summary`/`source`/`confidence`. Op `0x220` block:

```toml
op = 0x220
label = "set-anim-transform-abs"
argc = 6
```
and its `[opcode.semantics]`:
```toml
name = "set-anim-transform-abs"
category = "graphics"
summary = "(handle)(p1)(p2)(x)(y)(z) — set sprite transform/anim channel, absolute; cmd-type 0xd, worker 0x47ecc0. Cluster 0x21c-0x243."
noop_headless = false
source = "investigation"
confidence = "high"
```
Do the same for `0x21e` (`label = "set-anim-transform-norm"`, summary notes `/_DAT_00571c28` normalization, worker `gfx_anim_set_channel@0x47eaa0`), `0x234` (`label = "anim-start"`, category `graphics`), `0x238` (`label = "set-anim-clock"`, category `graphics`). Keep each op's existing `argc` unless Task 1 found otherwise for `0x234`/`0x238`.

- [ ] **Step 2: Rebuild the generated opcode files**

Run: `py -3.11 -X utf8 tools/opcodes_build.py --build`
Expected: `build: wrote build/opcodes.json, …`. Then `py -3.11 -X utf8 tools/opcodes_build.py --lint` → `lint: 0 errors, 0 warnings`.

- [ ] **Step 3: Write the failing dispatch test.** First, at the **top of `GfxAnimationTests.cs`** (with the existing `using Age.Engine.Model; using Xunit;`), add the usings this and later tasks need:

```csharp
using System.Collections.Generic;
using Age.Engine.Sys4;
using Age.Engine.Vm;
```

Then add these helpers + test **inside the `GfxAnimationTests` class**:

```csharp
    private static OpcodeTable T() => OpcodeTableJson.Load(Paths.OpcodesJson);
    private static Operand G(int a) => new(3, a);
    private static Operand I(long v) => new(0, v);
    private static (int, Operand[]) MovGI(int d, long v) => (0x55, new[] { G(d), I(v) });
    private static (int, Operand[]) Exit() => (0x2, System.Array.Empty<Operand>());

    [Fact]
    public void SetAnimTransformAbs_DispatchRecordsChannel()
    {
        var t = T();
        // handle g[1]=0x1000; p1 g[2]=7; p2 g[3]=9; target g[4,5,6]=(800,500,0)
        var scene = ScriptAssembler.Assemble(t, "ANIM", new List<(int, Operand[])>
        {
            MovGI(1, 0x1000), MovGI(2, 7), MovGI(3, 9), MovGI(4, 800), MovGI(5, 500), MovGI(6, 0),
            (0x220, new[] { G(1), G(2), G(3), G(4), G(5), G(6) }),
            Exit(),
        }, System.Array.Empty<string>());
        var vm = new VirtualMachine(scene, t, new RecordingHost());
        vm.Run();
        var o = vm.Gfx.TryGet(0x1000)!;
        Assert.Equal((800L, 500L, 0L), o.AnimTarget);
        Assert.False(o.AnimNormalized);
        Assert.True(o.AnimEnabled);
    }
```

- [ ] **Step 4: Run to verify it fails**

Run: `dotnet test engine/AgeEngine.sln --nologo --filter "FullyQualifiedName~SetAnimTransformAbs_DispatchRecordsChannel"`
Expected: FAIL — op `0x220` hits the `default` stub, so `AnimTarget` stays `(0,0,0)`.

- [ ] **Step 5: Add the `case` arms.** In `VirtualMachine.Step`, alongside the other gfx ops (before `default:`), add:

```csharp
            case "set-anim-transform-abs":   // 0x220 (handle)(p1)(p2)(x)(y)(z)
                Gfx.SetAnimTransform(Read(a[0]), Read(a[1]), Read(a[2]),
                    (Read(a[3]), Read(a[4]), Read(a[5])), normalized: false); return pc + 1;
            case "set-anim-transform-norm":  // 0x21e — same, operands are ~percent (/_DAT_00571c28)
                Gfx.SetAnimTransform(Read(a[0]), Read(a[1]), Read(a[2]),
                    (Read(a[3]), Read(a[4]), Read(a[5])), normalized: true); return pc + 1;
```

- [ ] **Step 6: Run to verify it passes + full suite parity**

Run: `dotnet test engine/AgeEngine.sln --nologo`
Expected: PASS, all green (audio/gfx CLI + selftest unaffected — new ops only write GfxState, which `RecordingHost` ignores).

- [ ] **Step 7: Commit**

```bash
git add vm-map/opcodes.toml build/opcodes.json tools/age_opcodes_himegari.py docs/opcode-reference.md engine/Age.Engine/Vm/VirtualMachine.cs engine/Age.Engine.Tests/GfxAnimationTests.cs
git commit -m "feat(gfx): dispatch set-anim-transform 0x21e/0x220 into GfxState"
```

---

## Task 4: Dispatch `anim-start` (0x234) + `set-anim-clock` (0x238)

**Files:**
- Modify: `engine/Age.Engine/Vm/VirtualMachine.cs`
- Test: `engine/Age.Engine.Tests/GfxAnimationTests.cs` (add)

**Interfaces:**
- Consumes: Task 1's operand contract for `0x234`/`0x238`; `GfxState.StartAnim`/`SetAnimClock` (Task 2); labels from Task 3.
- Produces: `case "anim-start"` / `case "set-anim-clock"` arms.

> **Operand mapping — reconcile with Task 1's `engine-re.md` addendum before coding.** The code below assumes `anim-start` = `(handle)` and `set-anim-clock` = `(handle)(durationTicks)`. If Task 1 found `set-anim-clock` is argc-1 (duration only, applied to the current object), use `Gfx.SetAnimClock(Gfx.CurrentObject, Read(a[0]))` instead. Adjust the indices to match the documented contract; the test asserts whatever mapping Task 1 confirmed.

- [ ] **Step 1: Write the failing test** — add to `GfxAnimationTests.cs` (using the mapping Task 1 confirmed; shown here for `(handle)` / `(handle)(ticks)`):

```csharp
    [Fact]
    public void AnimStartAndClock_DispatchBumpGenerationAndSetDuration()
    {
        var t = T();
        var scene = ScriptAssembler.Assemble(t, "ANIM", new List<(int, Operand[])>
        {
            MovGI(1, 0x1000), MovGI(2, 30),
            (0x238, new[] { G(1), G(2) }),       // set-anim-clock(handle=0x1000, ticks=30)
            (0x234, new[] { G(1) }),             // anim-start(handle=0x1000)
            Exit(),
        }, System.Array.Empty<string>());
        var vm = new VirtualMachine(scene, t, new RecordingHost());
        vm.Run();
        var o = vm.Gfx.TryGet(0x1000)!;
        Assert.Equal(30, o.AnimDurationTicks);
        Assert.Equal(1, o.AnimGeneration);
        Assert.True(o.AnimEnabled);
    }
```

- [ ] **Step 2: Run to verify it fails**

Run: `dotnet test engine/AgeEngine.sln --nologo --filter "FullyQualifiedName~AnimStartAndClock"`
Expected: FAIL — both ops hit `default`; `AnimDurationTicks`/`AnimGeneration` stay 0.

- [ ] **Step 3: Add the `case` arms** (matching Task 1's contract):

```csharp
            case "anim-start":      // 0x234 (handle) — begin the object's animation
                Gfx.StartAnim(Read(a[0])); return pc + 1;
            case "set-anim-clock":  // 0x238 (handle)(durationTicks)
                Gfx.SetAnimClock(Read(a[0]), Read(a[1])); return pc + 1;
```

- [ ] **Step 4: Run to verify it passes + full suite**

Run: `dotnet test engine/AgeEngine.sln --nologo`
Expected: PASS, all green.

- [ ] **Step 5: Commit**

```bash
git add engine/Age.Engine/Vm/VirtualMachine.cs engine/Age.Engine.Tests/GfxAnimationTests.cs
git commit -m "feat(gfx): dispatch anim-start 0x234 + set-anim-clock 0x238"
```

---

## Task 5: Surface the anim channel to the compositor (`RenderObject.AnimState`)

**Files:**
- Modify: `engine/Age.Engine/Model/GfxState.cs` (`RenderObject`, `AnimState`, `SnapshotVisibleObjects`)
- Test: `engine/Age.Engine.Tests/GfxAnimationTests.cs` (add)

**Interfaces:**
- Consumes: the `GfxObject` anim fields (Task 2).
- Produces: `public readonly record struct AnimState(bool Enabled, bool Normalized, long TX, long TY, long TZ, long DurationTicks, long Generation);` and `RenderObject` gains a trailing `AnimState Anim` member. Consumed by Task 6.

- [ ] **Step 1: Write the failing test** — add to `GfxAnimationTests.cs`:

```csharp
    [Fact]
    public void SnapshotCarriesAnimStateForVisibleObject()
    {
        var t = T();
        // make object 0xA visible via set/draw-texture, then arm an anim channel + clock + start.
        var scene = ScriptAssembler.Assemble(t, "ANIM", new List<(int, Operand[])>
        {
            MovGI(1, 0xA), MovGI(2, 4), MovGI(7, 0x25), MovGI(3, 800), MovGI(4, 600), MovGI(5, 0), MovGI(6, 0),
            (0x1f9, new[] { G(7), G(2), I(0) }),                       // set-texture resId 0x25 -> slot 4
            (0x1fb, new[] { G(1), G(2), I(0), I(0), G(3), G(4), G(5), G(6) }),  // draw-texture: object 0xA visible
            MovGI(8, 0), MovGI(9, 30),
            (0x220, new[] { G(1), G(5), G(6), G(3), G(4), G(8) }),     // anim target (800,600,0)
            (0x238, new[] { G(1), G(9) }),                            // clock 30
            (0x234, new[] { G(1) }),                                  // start
            Exit(),
        }, System.Array.Empty<string>());
        var vm = new VirtualMachine(scene, t, new RecordingHost());
        vm.Run();
        var vis = vm.Gfx.SnapshotVisibleObjects();
        Assert.Single(vis);
        Assert.True(vis[0].Anim.Enabled);
        Assert.Equal((800L, 600L, 0L), (vis[0].Anim.TX, vis[0].Anim.TY, vis[0].Anim.TZ));
        Assert.Equal(30, vis[0].Anim.DurationTicks);
        Assert.Equal(1, vis[0].Anim.Generation);
    }
```

- [ ] **Step 2: Run to verify it fails**

Run: `dotnet test engine/AgeEngine.sln --nologo --filter "FullyQualifiedName~SnapshotCarriesAnimState"`
Expected: FAIL — `RenderObject` has no `Anim` member (compile error).

- [ ] **Step 3: Add `AnimState` + extend `RenderObject`.** In `GfxState.cs`, replace the `RenderObject` record declaration with:

```csharp
public readonly record struct AnimState(bool Enabled, bool Normalized, long TX, long TY, long TZ,
                                        long DurationTicks, long Generation);

/// <summary>A renderable view of one visible gfx object … (existing summary).</summary>
public readonly record struct RenderObject(long Handle, long SurfaceResId, long ColorKey,
                                           int SrcX, int SrcY, int W, int H, int DstX, int DstY,
                                           AnimState Anim);
```

- [ ] **Step 4: Populate it in `SnapshotVisibleObjects`.** In that method's loop, change the `list.Add(...)` to include the anim state:

```csharp
                list.Add(new RenderObject(kv.Key, resId, ck, o.SrcRect.X, o.SrcRect.Y, o.SrcRect.W, o.SrcRect.H,
                                          (int)o.V24.X, (int)o.V24.Y,
                                          new AnimState(o.AnimEnabled, o.AnimNormalized,
                                                        o.AnimTarget.X, o.AnimTarget.Y, o.AnimTarget.Z,
                                                        o.AnimDurationTicks, o.AnimGeneration)));
```

- [ ] **Step 5: Run to verify it passes + full suite.** The existing `SetThenDrawTextureMakesAVisibleObjectFromTheSurface` test in `GfxCommandBufferTests` constructs `RenderObject` positionally only via the snapshot (not `new`), so it stays valid.

Run: `dotnet test engine/AgeEngine.sln --nologo`
Expected: PASS, all green.

- [ ] **Step 6: Commit**

```bash
git add engine/Age.Engine/Model/GfxState.cs engine/Age.Engine.Tests/GfxAnimationTests.cs
git commit -m "feat(gfx): surface anim channel to the compositor via RenderObject.AnimState"
```

---

## Task 6: Godot compositor — wall-clock tween + alpha blit

**Files:**
- Modify: `godot/Main.cs` (`Recomposite`, `BlitLayer`; add a tween table + `TweenState`)

**Interfaces:**
- Consumes: `RenderObject.Anim` (Task 5).
- Produces: animated, alpha-composited rendering. Verified visually (Godot; no unit test).

> **Scope from Task 1:** if Task 1 found the opening fade's alpha comes from `0x202/0x203` (packed color on the object) rather than the transform vec3, drive the blit alpha from `RenderObject.ColorKey`/the object color instead of (or in addition to) the tweened target. The tween mechanics below are unchanged; only the *source of the alpha value* differs. Wire whichever Task 1 confirmed.

- [ ] **Step 1: Add the tween state + table.** In `Main.cs`, add fields near the other compositor fields:

```csharp
    // Per-handle wall-clock tween of the animation channel. Re-armed whenever an object's AnimGeneration or
    // target changes (the VM records those; the compositor owns time). See the gfx-animation-subsystem spec.
    private sealed class TweenState
    {
        public long Generation = long.MinValue;
        public double Elapsed, Duration;
        public (double X, double Y, double Z) Start, Target;
    }
    private readonly System.Collections.Generic.Dictionary<long, TweenState> _tweens = new();
    private const double GameTickSeconds = 1.0 / 60.0;   // duration ticks -> seconds (confirm FPS in Task 1)
```

- [ ] **Step 2: Advance tweens + compute the current alpha in `Recomposite`.** Replace the body of the `foreach (var v in _vm.Gfx.SnapshotVisibleObjects())` loop so each object computes an alpha (1.0 when not animating) and passes it to the blit:

```csharp
        foreach (var v in _vm.Gfx.SnapshotVisibleObjects())   // ascending handle = z-order
        {
            if (v.SurfaceResId == 0) continue;                 // render-target/blank surface
            var bmp = _host.ResolveResIdTexture(v.SurfaceResId);
            if (bmp == null) continue;

            float alpha = 1f;
            if (v.Anim.Enabled)
            {
                var tw = _tweens.TryGetValue(v.Handle, out var t) ? t : (_tweens[v.Handle] = new TweenState());
                if (tw.Generation != v.Anim.Generation)        // (re)arm the tween
                {
                    double norm = v.Anim.Normalized ? 100.0 : 1.0;   // 0x21e ~percent; confirm divisor in Task 1
                    tw.Generation = v.Anim.Generation;
                    tw.Elapsed = 0;
                    tw.Duration = System.Math.Max(1, v.Anim.DurationTicks) * GameTickSeconds;
                    tw.Target = (v.Anim.TX / norm, v.Anim.TY / norm, v.Anim.TZ / norm);
                    tw.Start = (1, 1, 1);                       // fade-from-full default; refine per Task 1
                }
                tw.Elapsed += _lastDelta;
                double p = System.Math.Clamp(tw.Elapsed / tw.Duration, 0, 1);
                // First interpretation: the target's Z (or X) channel is opacity. Task 1 pins which channel.
                double a = tw.Start.Z + (tw.Target.Z - tw.Start.Z) * p;
                alpha = (float)System.Math.Clamp(a, 0, 1);
            }
            BlitLayer(bmp, v.SrcX, v.SrcY, v.W, v.H, v.DstX, v.DstY, alpha);
        }
```

Add a `private double _lastDelta;` field and set it at the top of `_Process`: `_lastDelta = delta;`.

- [ ] **Step 3: Make `BlitLayer` alpha-aware.** Change its signature to `BlitLayer(string bmpPath, int srcX, int srcY, int w, int h, int dstX, int dstY, float alpha = 1f)`. Keep the fast opaque path when `alpha >= 0.999f` (existing `BlitRect`). Otherwise blend over the raw RGBA byte buffer:

```csharp
        if (alpha >= 0.999f) { _screen.BlitRect(src, new Rect2I(srcX, srcY, sw, sh), new Vector2I(dstX, dstY)); return; }
        byte[] dst = _screen.GetData(); byte[] ss = src.GetData();
        int dw = _screen.GetWidth(), sfw = src.GetWidth();
        int ia = (int)(alpha * 255);
        for (int y = 0; y < sh; y++)
        for (int x = 0; x < sw; x++)
        {
            int di = ((dstY + y) * dw + (dstX + x)) * 4;
            int si = ((srcY + y) * sfw + (srcX + x)) * 4;
            if (di < 0 || di + 3 >= dst.Length) continue;
            int sa = ss[si + 3] * ia / 255;                    // source alpha * object alpha
            for (int c = 0; c < 3; c++) dst[di + c] = (byte)((ss[si + c] * sa + dst[di + c] * (255 - sa)) / 255);
            dst[di + 3] = (byte)System.Math.Min(255, dst[di + 3] + sa);
        }
        _screen.SetData(dw, _screen.GetHeight(), false, _screen.GetFormat(), dst);
```

- [ ] **Step 4: Build + import Godot**

Run: `dotnet build godot/Himegari.csproj -v q` then `godot --headless --path godot --import`
Expected: build succeeds, import completes.

- [ ] **Step 5: Capture the opening fade across frames.** Grab the fade page at a couple of time offsets and eyeball that it changes (fades) rather than staying opaque:

Run: `godot --path godot -- --boot --shot build/shot-anim-p2.png --shot-page 2`
Expected: a PNG is written; opening CG present. Compare against a pre-change capture (`git stash` the Godot change, capture, unstash) — the animated effect should differ across the tween where before it was static/opaque. Record the observation.

- [ ] **Step 6: Commit**

```bash
git add godot/Main.cs
git commit -m "feat(gfx): Godot wall-clock tween + alpha-aware blit for the anim channel"
```

---

## Task 7: Verify the slice + update the living docs

**Files:**
- Modify: `docs/phase-a-slice-plan.md`, `~/.claude/…/memory/himegari-port-status.md`, `~/.claude/…/memory/MEMORY.md`

**Interfaces:** none (verification + docs).

- [ ] **Step 1: Confirm the tracker GAP shrank.**

Run: `py -3.11 -X utf8 tools/scene_opcode_coverage.py SC0000`
Expected: the implemented ops (`0x21e`,`0x220`,`0x234`,`0x238`) now report **impl**, not GAP; the GAP count dropped by that many (from 68). Record the new number.

- [ ] **Step 2: Confirm full headless parity.**

Run: `dotnet test engine/AgeEngine.sln --nologo` → all green.
Run: `godot --headless --path godot -- --selftest` → `SELFTEST OK`.
Run: `dotnet run --project engine/Age.Cli -- sweep` → same 294 exit / 3 LOOP as before (anim ops are record-only).
Expected: no regressions.

- [ ] **Step 3: Update `docs/phase-a-slice-plan.md`.** In the A2b section, add a short subsection recording: the ops implemented, the tween/alpha approach, the tracker GAP delta, the screenshot result, and any Task-1 corrections (operand contracts, animated channel, divisor/FPS).

- [ ] **Step 4: Update the status memory.** In `himegari-port-status.md`, append a milestone entry (ops done, GAP shrink, what's still deferred — the rest of the `0x21c–0x243` cluster + scene-coroutine timing) and refresh its one-line `MEMORY.md` index entry. Convert relative dates to absolute.

- [ ] **Step 5: Commit**

```bash
git add docs/phase-a-slice-plan.md
git commit -m "docs(gfx): record the anim-subsystem opening slice results"
```

---

## Self-review notes (for the executor)

- **Task 1 is the gate.** Do not skip it — Tasks 4 and 6 explicitly reconcile against its findings (operand contract for `0x234`/`0x238`; whether the fade alpha is transform- or `0x202/0x203`-driven; the normalization divisor and game FPS). The plan's default assumptions are the current best hypotheses, not confirmed facts.
- **Parity guard**: after every C# task, `dotnet test engine/AgeEngine.sln --nologo` must stay fully green — the anim ops only write `GfxState`, which non-Godot hosts never read.
- **YAGNI**: only the four opening ops are wired; the rest of `0x21c–0x243` stays on the `default` stub and keeps showing as GAP in the tracker (intentional, measurable remaining work).