docs: record SC0000 anim cluster coverage (opcodes + slice plan)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-08 22:13:56 -04:00
parent 165a9f616c
commit 620ffb4fb7
3 changed files with 64 additions and 42 deletions
--- a/docs/opcode-reference.md
+++ b/docs/opcode-reference.md
@@ -171,6 +171,26 @@ Native handler gfx_op_0x20c_present_frame (dispatch ctx[0x26c93+0x20c]) -> gfx_r
 - **summary:** (handle)(p1)(p2)(x)(y)(z) — set sprite transform channel, ABSOLUTE (raw floats); cmd-type 0xd, worker 0x47ecc0. Twin of 0x21e. SC0000 opening @0x18a5+ on INIT2 CG handles. Cluster 0x21c-0x243. Handler 0x4234e0; Kelebek VA 0x4215D0 is drift.
 - **grounding:** source=investigation, confidence=high

+### 0x228 `u00421940` (u00421940, argc 5)
+- **summary:** 0x228 query-position (succ)(handle)(outX)(outY)(outZ): read the object's current computed position into vars (worker FUN_0047cdd0). C# VM: writes V24 + success flag. See docs/engine-re.md §SC0000 anim cluster.
+- **grounding:** source=kelebek, confidence=low
+
+### 0x229 `u004219E0` (u004219E0, argc 5)
+- **summary:** 0x229 set-position2 (handle)(op2)(x)(y)(z): set object position/geometry directly (FUN_00472bb0/be0). C# VM: sets V24. See docs/engine-re.md §SC0000 anim cluster.
+- **grounding:** source=kelebek, confidence=low
+
+### 0x22f `u00421DD0` (u00421DD0, argc 5)
+- **summary:** 0x22f set-position (handle)(op2)(x)(y)(z): set the object base position (direct transform, not ping-pong). Worker gfx_worker_set_translation @0x472e90. C# VM: sets V24. See docs/engine-re.md §SC0000 anim cluster.
+- **grounding:** source=kelebek, confidence=low
+
+### 0x231 `u00421EA0` (u00421EA0, argc 4)
+- **summary:** 0x231 anim-srcrect (handle)(period)(gridW)(gridH): ping-pong the spritesheet cell across the grid over period ms. Worker gfx_worker_anim_srcrect @0x47eec0 -> interpolator SRC-RECT SCROLL channel. C# VM: GfxState.SetSrcRect. See docs/engine-re.md §SC0000 anim cluster.
+- **grounding:** source=kelebek, confidence=low
+
+### 0x232 `u00421EF0` (u00421EF0, argc 4)
+- **summary:** 0x232 anim-color (handle)(period)(alpha)(color): ping-pong the object color/alpha toward the packed target over period ms (pulsing GLOW). Worker gfx_worker_anim_color @0x47ef50 -> interpolator COLOR channel. C# VM: GfxState.SetColorAnim. See docs/engine-re.md §SC0000 anim cluster.
+- **grounding:** source=kelebek, confidence=low
+
 ### 0x234 `anim-start` (anim-start, argc 5)
 - **summary:** (handle)(duration)(x)(y)(z) — animate object toward target vec3 (x,y,z) over the GLOBAL clock; cmd-type 0xb, worker gfx_anim_start. op2=this object's duration (label_1235a maxes into the clock). SC0000 opening @0xdaf on INIT2 CG handles. Handler 0x423da0; Kelebek VA 0x422060 is drift.
 - **grounding:** source=investigation, confidence=high
@@ -179,6 +199,14 @@ Native handler gfx_op_0x20c_present_frame (dispatch ctx[0x26c93+0x20c]) -> gfx_r
 - **summary:** (duration) — set the GLOBAL animation clock: native ctx+0x51b78=0 (elapsed), +0x51b7c=duration. cmd-type 3. NON-BLOCKING: only configures; the render loop advances it and interpolates all animating objects. SC0000 opening @0x123bd/@0x13858. Handler 0x4240e0; Kelebek VA 0x422390 is drift.
 - **grounding:** source=investigation, confidence=high

+### 0x239 `u004223C0` (u004223C0, argc 6)
+- **summary:** 0x239 set-srcrect-cell (handle)(p3)(p4)(gridW)(gridH)(cell): set the spritesheet grid + static visible cell. Worker gfx_worker_set_srcrect_cell @0x47ed90. C# VM: GfxState.SetSrcRect (period 0). See docs/engine-re.md §SC0000 anim cluster.
+- **grounding:** source=kelebek, confidence=low
+
+### 0x23f `u00422930` (u00422930, argc 2)
+- **summary:** 0x23f query-object (out)(handle): return object status (FUN_0042a520; -1 if none). C# VM: 0 if the object exists else -1. See docs/engine-re.md §SC0000 anim cluster.
+- **grounding:** source=kelebek, confidence=low
+
 ## input

 ### 0x90 `hotspot-branch` (u0041BEB0, argc 7)
@@ -960,14 +988,6 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it "
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low

-### 0x228 `u00421940` (u00421940, argc 5)
- **summary:** —
- **grounding:** source=kelebek, confidence=low
-
-### 0x229 `u004219E0` (u004219E0, argc 5)
- **summary:** —
- **grounding:** source=kelebek, confidence=low
-
 ### 0x22a `u00421A90` (u00421A90, argc 3)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low
@@ -980,22 +1000,10 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it "
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low

-### 0x22f `u00421DD0` (u00421DD0, argc 5)
- **summary:** —
- **grounding:** source=kelebek, confidence=low
-
 ### 0x230 `u00421E70` (u00421E70, argc 1)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low

-### 0x231 `u00421EA0` (u00421EA0, argc 4)
- **summary:** —
- **grounding:** source=kelebek, confidence=low
-
-### 0x232 `u00421EF0` (u00421EF0, argc 4)
- **summary:** —
- **grounding:** source=kelebek, confidence=low
-
 ### 0x233 `u00421FB0` (u00421FB0, argc 5)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low
@@ -1004,10 +1012,6 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it "
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low

-### 0x239 `u004223C0` (u004223C0, argc 6)
- **summary:** —
- **grounding:** source=kelebek, confidence=low
-
 ### 0x23a `u00422420` (u00422420, argc 2)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low
@@ -1024,10 +1028,6 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it "
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low

-### 0x23f `u00422930` (u00422930, argc 2)
- **summary:** —
- **grounding:** source=kelebek, confidence=low
-
 ### 0x241 `u00422B80` (u00422B80, argc 5)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low
--- a/docs/phase-a-slice-plan.md
+++ b/docs/phase-a-slice-plan.md
@@ -629,3 +629,25 @@ smooth color-animation *interpolation* (the fade ramps snap to the correct end-s
 the `0x202` color channel's blit consumer + clock coupling is a dedicated dig) and **additive/glow blend**
 (`local_2c` mode 2/3; its object field isn't pinned). `BlendKind.Additive` is an unused seam. Next graphics
 slices unchanged: B (geometry/anchors — sprite *placement*) and C (render-targets).
+
+### A2b — SC0000 anim/transform/spritesheet cluster (partial) ✅ DONE (2026-07-08)
+
+The `0x21c`–`0x243` gfx cluster, scoped to a **tractable subset** after Task-1 RE revealed it's heterogeneous
+(setters + queries + matrix/scale + a movie op). Spec `docs/superpowers/specs/2026-07-08-sc0000-anim-transform-cluster-design.md`,
+plan `.../plans/2026-07-08-sc0000-anim-transform-cluster.md`, branch `feat/anim-transform-cluster`
+(engine 79/79, sweep exit=284/STEP-LIMIT=13 parity, `SELFTEST OK`, coverage SC0000 67→74/129 handled).
+
+**Key RE unlock:** the dispatch table `handler(op)=ctx[0x26c93+op]` recovered statically from `FUN_00413860`
+(the `opcodes.toml` `u004xxxx` labels are Kelebek drift). Full op→field map in `engine-re.md` §SC0000 anim cluster.
+
+**Built (hybrid: engine resolves, host blits):**
+- `GfxObject` gains src-rect (spritesheet) + animated-color channels; `GfxState.SetSrcRect` / `SetColorAnim`;
+  `BlendMath.PingPong`; `SnapshotVisibleObjects(long nowMs)` = a port of `gfx_object_anim_interpolate`
+  (ping-pong the spritesheet cell + color/glow), driven by the **`FrameClock`** (the "mach 5" pacing fix).
+- Wired 7 ops: `0x22f`/`0x229` position (direct V24 set), `0x239`/`0x231` spritesheet (static cell / animate),
+  `0x232` color glow (ping-pong), `0x228`/`0x23f` queries (geometry back to script vars).
+
+**Deferred (own follow-ups, per scope decision):** `0x21f`/`0x223` matrix/scale (need affine rendering),
+`0x236` timed/movie op, and the rare `0x21c/0x21d/0x224/0x242/0x243/0x23d/0x20a/0x20e` tail. Adjacent
+non-cluster gaps remain: `draw-string 0x204`×205 (on-screen text) and `play-sound-effect`. **Whole-scene
+visual validation is the user's call** (they deferred confirmation until the scene is coherent).
--- a/vm-map/opcodes.toml
+++ b/vm-map/opcodes.toml
@@ -5750,8 +5750,8 @@ abi_source = "kelebek+decode-validated"

 [opcode.semantics]
 name = "u00421940"
-category = "unknown"
-summary = ""
+category = "draw"
+summary = "0x228 query-position (succ)(handle)(outX)(outY)(outZ): read the object's current computed position into vars (worker FUN_0047cdd0). C# VM: writes V24 + success flag. See docs/engine-re.md §SC0000 anim cluster."
 noop_headless = false
 source = "kelebek"
 confidence = "low"
@@ -5791,8 +5791,8 @@ abi_source = "kelebek+decode-validated"

 [opcode.semantics]
 name = "u004219E0"
-category = "unknown"
-summary = ""
+category = "draw"
+summary = "0x229 set-position2 (handle)(op2)(x)(y)(z): set object position/geometry directly (FUN_00472bb0/be0). C# VM: sets V24. See docs/engine-re.md §SC0000 anim cluster."
 noop_headless = false
 source = "kelebek"
 confidence = "low"
@@ -5935,8 +5935,8 @@ abi_source = "kelebek+decode-validated"

 [opcode.semantics]
 name = "u00421DD0"
-category = "unknown"
-summary = ""
+category = "draw"
+summary = "0x22f set-position (handle)(op2)(x)(y)(z): set the object base position (direct transform, not ping-pong). Worker gfx_worker_set_translation @0x472e90. C# VM: sets V24. See docs/engine-re.md §SC0000 anim cluster."
 noop_headless = false
 source = "kelebek"
 confidence = "low"
@@ -5997,8 +5997,8 @@ abi_source = "kelebek+decode-validated"

 [opcode.semantics]
 name = "u00421EA0"
-category = "unknown"
-summary = ""
+category = "draw"
+summary = "0x231 anim-srcrect (handle)(period)(gridW)(gridH): ping-pong the spritesheet cell across the grid over period ms. Worker gfx_worker_anim_srcrect @0x47eec0 -> interpolator SRC-RECT SCROLL channel. C# VM: GfxState.SetSrcRect. See docs/engine-re.md §SC0000 anim cluster."
 noop_headless = false
 source = "kelebek"
 confidence = "low"
@@ -6033,8 +6033,8 @@ abi_source = "kelebek+decode-validated"

 [opcode.semantics]
 name = "u00421EF0"
-category = "unknown"
-summary = ""
+category = "draw"
+summary = "0x232 anim-color (handle)(period)(alpha)(color): ping-pong the object color/alpha toward the packed target over period ms (pulsing GLOW). Worker gfx_worker_anim_color @0x47ef50 -> interpolator COLOR channel. C# VM: GfxState.SetColorAnim. See docs/engine-re.md §SC0000 anim cluster."
 noop_headless = false
 source = "kelebek"
 confidence = "low"
@@ -6208,8 +6208,8 @@ abi_source = "kelebek+decode-validated"

 [opcode.semantics]
 name = "u004223C0"
-category = "unknown"
-summary = ""
+category = "draw"
+summary = "0x239 set-srcrect-cell (handle)(p3)(p4)(gridW)(gridH)(cell): set the spritesheet grid + static visible cell. Worker gfx_worker_set_srcrect_cell @0x47ed90. C# VM: GfxState.SetSrcRect (period 0). See docs/engine-re.md §SC0000 anim cluster."
 noop_headless = false
 source = "kelebek"
 confidence = "low"
@@ -6363,8 +6363,8 @@ abi_source = "kelebek+decode-validated"

 [opcode.semantics]
 name = "u00422930"
-category = "unknown"
-summary = ""
+category = "draw"
+summary = "0x23f query-object (out)(handle): return object status (FUN_0042a520; -1 if none). C# VM: 0 if the object exists else -1. See docs/engine-re.md §SC0000 anim cluster."
 noop_headless = false
 source = "kelebek"
 confidence = "low"