@playcraft/cli 0.0.44 → 0.0.47

package/project-template/skills/playable-focus/templates/playground/vfx-catalog.template.json

@@ -0,0 +1,280 @@
+{
+  "version": 1,
+  "description": "VFX 按渲染类型穷举。新增特效 = 加 spec 条目，不加 html。",
+  "renderTypes": {
+    "frame": {
+      "label": "帧动画",
+      "harness": "/focus-lab/frame.html",
+      "sceneKey": "FrameLabScene",
+      "viewport": { "width": 720, "height": 800 },
+      "loopMs": 1800,
+      "validateDimensions": [
+        "切格/竖缝",
+        "anchor对齐",
+        "peakFootprint",
+        "blendMode",
+        "scale",
+        "frameRate",
+        "alpha衰减"
+      ]
+    },
+    "particle": {
+      "label": "粒子/迸发",
+      "harness": "/focus-lab/particle.html",
+      "sceneKey": "ParticleLabScene",
+      "viewport": { "width": 720, "height": 800 },
+      "loopMs": 2000,
+      "validateDimensions": ["密度", "lifespan", "tint", "blendMode", "轨迹/重力"]
+    },
+    "model": {
+      "label": "3D 模型",
+      "harness": "/focus-lab/model.html",
+      "sceneKey": "ModelLabScene",
+      "viewport": { "width": 720, "height": 800 },
+      "loopMs": 3000,
+      "status": "reserved",
+      "validateDimensions": ["光照", "材质", "动画混合"]
+    }
+  },
+  "specs": [
+    {
+      "id": "match_burst",
+      "renderType": "frame",
+      "label": "祥云爆发 v1",
+      "animKey": "anim_match_burst",
+      "firstFrame": "fx_match_burst_f0",
+      "frames": [
+        "fx_match_burst_f0",
+        "fx_match_burst_f1",
+        "fx_match_burst_f2",
+        "fx_match_burst_f3",
+        "fx_match_burst_f4",
+        "fx_match_burst_f5"
+      ],
+      "frameRate": 14,
+      "repeat": 0,
+      "blendMode": "ADD",
+      "scale": 0.38,
+      "usedIn": ["tile_shatter"]
+    },
+    {
+      "id": "match_burst_v2",
+      "renderType": "frame",
+      "label": "祥云爆发 v2",
+      "animKey": "anim_match_burst_v2",
+      "firstFrame": "fx_match_burst_v2_f0",
+      "frames": [
+        "fx_match_burst_v2_f0",
+        "fx_match_burst_v2_f1",
+        "fx_match_burst_v2_f2",
+        "fx_match_burst_v2_f3",
+        "fx_match_burst_v2_f4",
+        "fx_match_burst_v2_f5"
+      ],
+      "frameRate": 14,
+      "repeat": 0,
+      "blendMode": "ADD",
+      "scale": 0.45,
+      "peakIndex": 3,
+      "peakFrame": "fx_match_burst_v2_f3",
+      "frameCanvas": [468, 468],
+      "usedIn": ["tile_shatter"]
+    },
+    {
+      "id": "combo_ring",
+      "renderType": "frame",
+      "label": "Combo 光环",
+      "animKey": "anim_combo_ring",
+      "firstFrame": "fx_combo_ring_f0",
+      "frames": [
+        "fx_combo_ring_f0",
+        "fx_combo_ring_f1",
+        "fx_combo_ring_f2",
+        "fx_combo_ring_f3",
+        "fx_combo_ring_f4"
+      ],
+      "frameRate": 10,
+      "repeat": 0,
+      "blendMode": "ADD",
+      "scale": 0.55,
+      "peakIndex": 3,
+      "peakFrame": "fx_combo_ring_f3",
+      "frameCanvas": [1024, 1024],
+      "usedIn": ["combo_milestone"]
+    },
+    {
+      "id": "victory_ray",
+      "renderType": "frame",
+      "label": "胜利光柱 v1",
+      "animKey": "anim_victory_ray",
+      "firstFrame": "fx_victory_ray_f0",
+      "frames": [
+        "fx_victory_ray_f0",
+        "fx_victory_ray_f1",
+        "fx_victory_ray_f2",
+        "fx_victory_ray_f3"
+      ],
+      "frameRate": 6,
+      "repeat": -1,
+      "blendMode": "ADD",
+      "scale": 1.4,
+      "usedIn": ["endcard"]
+    },
+    {
+      "id": "victory_ray_v2",
+      "renderType": "frame",
+      "label": "胜利光柱 v2",
+      "animKey": "anim_victory_ray_v2",
+      "firstFrame": "fx_victory_ray_v2_f0",
+      "frames": [
+        "fx_victory_ray_v2_f0",
+        "fx_victory_ray_v2_f1",
+        "fx_victory_ray_v2_f2",
+        "fx_victory_ray_v2_f3"
+      ],
+      "frameRate": 6,
+      "repeat": -1,
+      "blendMode": "ADD",
+      "scale": 1.4,
+      "peakIndex": 3,
+      "peakFrame": "fx_victory_ray_v2_f3",
+      "frameCanvas": [1024, 1024],
+      "usedIn": ["endcard"]
+    },
+    {
+      "id": "golden_dragon",
+      "renderType": "frame",
+      "label": "金龙",
+      "animKey": "anim_golden_dragon",
+      "firstFrame": "fx_golden_dragon_f0",
+      "frames": [
+        "fx_golden_dragon_f0",
+        "fx_golden_dragon_f1",
+        "fx_golden_dragon_f2",
+        "fx_golden_dragon_f3"
+      ],
+      "frameRate": 8,
+      "repeat": 0,
+      "blendMode": "NORMAL",
+      "scale": 0.6,
+      "peakIndex": 2,
+      "peakFrame": "fx_golden_dragon_f2",
+      "frameCanvas": [1024, 1024],
+      "usedIn": ["bonus_reward"]
+    },
+    {
+      "id": "firework_burst",
+      "renderType": "frame",
+      "label": "烟花爆发",
+      "animKey": "anim_firework_burst",
+      "firstFrame": "fx_firework_burst_f0",
+      "frames": [
+        "fx_firework_burst_f0",
+        "fx_firework_burst_f1",
+        "fx_firework_burst_f2",
+        "fx_firework_burst_f3",
+        "fx_firework_burst_f4",
+        "fx_firework_burst_f5"
+      ],
+      "frameRate": 12,
+      "repeat": 0,
+      "blendMode": "ADD",
+      "scale": 0.5,
+      "peakIndex": 2,
+      "peakFrame": "fx_firework_burst_f2",
+      "frameCanvas": [1024, 1024],
+      "usedIn": ["reward_toast"]
+    },
+    {
+      "id": "xianyun_swirl",
+      "renderType": "frame",
+      "label": "祥云旋涡",
+      "animKey": "anim_xianyun_swirl",
+      "firstFrame": "fx_xianyun_swirl_f0",
+      "frames": [
+        "fx_xianyun_swirl_f0",
+        "fx_xianyun_swirl_f1",
+        "fx_xianyun_swirl_f2",
+        "fx_xianyun_swirl_f3"
+      ],
+      "frameRate": 8,
+      "repeat": -1,
+      "blendMode": "ADD",
+      "scale": 0.5,
+      "peakIndex": 3,
+      "peakFrame": "fx_xianyun_swirl_f3",
+      "frameCanvas": [1024, 1024],
+      "usedIn": ["endcard_bg"]
+    },
+    {
+      "id": "match_dust",
+      "renderType": "particle",
+      "label": "消牌尘土",
+      "pattern": "emitter",
+      "texture": "particle_spark",
+      "emitter": {
+        "speed": { "min": 60, "max": 140 },
+        "angle": { "min": 225, "max": 315 },
+        "scale": { "start": 0.25, "end": 0 },
+        "alpha": { "start": 0.5, "end": 0 },
+        "lifespan": { "min": 180, "max": 320 },
+        "quantity": 8,
+        "blendMode": "ADD",
+        "tint": [16766720, 13944376]
+      },
+      "usedIn": ["tile_shatter"]
+    },
+    {
+      "id": "gold_sparkles",
+      "renderType": "particle",
+      "label": "金色火花",
+      "pattern": "graphics_burst",
+      "quantity": 5,
+      "colors": [16766720, 13944376, 16772648],
+      "radius": { "min": 3, "max": 8 },
+      "dist": { "min": 30, "max": 100 },
+      "duration": { "min": 200, "max": 400 },
+      "usedIn": ["tile_shatter"]
+    },
+    {
+      "id": "shard_debris",
+      "renderType": "particle",
+      "label": "牌面碎裂（开裂+模块）",
+      "pattern": "decompose",
+      "crackMode": "overlay",
+      "note": "f1-f3 transparent crack lines composited on real tile; f4-f7 neutral ivory modules",
+      "textureKeys": [
+        "fx_shard_debris_f0",
+        "fx_shard_debris_f1",
+        "fx_shard_debris_f2",
+        "fx_shard_debris_f3",
+        "fx_shard_debris_f4",
+        "fx_shard_debris_f5",
+        "fx_shard_debris_f6",
+        "fx_shard_debris_f7"
+      ],
+      "moduleKeys": [
+        "fx_shard_debris_f4",
+        "fx_shard_debris_f5",
+        "fx_shard_debris_f6",
+        "fx_shard_debris_f7"
+      ],
+      "crackKeys": ["fx_shard_debris_f1", "fx_shard_debris_f2", "fx_shard_debris_f3"],
+      "count": 4,
+      "scale": { "min": 0.28, "max": 0.36 },
+      "speed": { "min": 280, "max": 520 },
+      "spreadDeg": 55,
+      "gravityDrop": 120,
+      "usedIn": ["tile_shatter"]
+    }
+  ],
+  "composites": [
+    {
+      "id": "tile_shatter",
+      "label": "消牌碎裂（多层合成）",
+      "primitives": ["match_burst_v2", "match_dust", "shard_debris", "gold_sparkles"],
+      "miniG": "integration:EVENT:match-once",
+      "note": "L 步先拆 primitive 在 frame/particle harness 验；composite 仅 Integration 前快检"
+    }
+  ]
+}

package/project-template/skills/playable-fx-decompose/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: playable-fx-decompose
+description: >-
+  Break/shatter/decompose FX for playables (state row + modules). Agent MUST
+  run ensure-project, use blank-board overlay for variable tile faces, build
+  scripts in skill, then playground clean:particle + match-once G1. Use when
+  user asks to fix tile shatter, black box shards, wrong tile overlay, or
+  random particle debris. User never runs build scripts manually.
+---
+
+# Playable Decompose FX
+
+> **用户**：「用 decompose-fx 优化消牌碎裂 / shard_debris」  
+> **Agent**：ensure-project → 白板/reference 决策 → build 脚本 → 语义 gate → match-once。
+
+---
+
+## Agent 入口
+
+### 0. 自举
+
+```bash
+npm run ensure:project
+pip install -r ../skills/playable-fx-decompose/requirements.txt
+```
+
+### 1. 选模式（Decision tree 摘要）
+
+| 盘面            | 模式                                             |
+| --------------- | ------------------------------------------------ |
+| 多种牌面 / 图标 | **白板 crack overlay** — 禁止三萬 overlay 到九萬 |
+| 单一主体        | edit 游戏内 PNG → state + modules                |
+
+详见下文 Decision tree。
+
+### 2. 生成/后处理（Agent 执行 skill 内脚本）
+
+```bash
+python3 ../skills/playable-fx-decompose/scripts/build-blank-tile-crack.py
+# 或 WaveSpeed 链路见 generate-shard-debris.py
+```
+
+### 3. 语义 gate（L1）
+
+- [ ] 状态行 progressive damage，非 random 8 帧
+- [ ] 模块无黑框、无错 glyph
+- [ ] `npm run playground -- record clean:particle:shard_debris --headed`
+
+### 4. G1
+
+```bash
+npm run playground -- record integration:EVENT:match-once --headed
+```
+
+写 `validate/focus/particle/shard_debris.md`。
+
+---
+
+**Core rule**: A break effect is not “spawn N random sprites.” It is **one subject decomposed into states + modules**, then **composed in two phases**.
+
+Applies to tile shatter, block crack, coin burst, panel break, prop explode — any FX where a recognizable object falls apart.
+
+## Decision tree
+
+```
+Object breaks in gameplay?
+├─ Yes → Subject always identical on screen (one coin art, one crate)?
+│         edit from that in-game PNG → state row + module row
+│         Runtime: state anim → hide subject → modules
+│
+├─ Yes → Subject VARIES (e.g. many mahjong faces, swappable icons)?
+│         edit from BLANK/neutral reference (白板) — NO characters/symbols on state row
+│         Post-process state row → transparent CRACK OVERLAY only
+│         Runtime: KEEP real subject visible → overlay crack anim → hide → modules
+│         NEVER flash intact reference face (f0) if it ≠ board art
+│
+└─ Glow/spark/dust only (no recognizable subject)?
+          Use ADD sheet on black; frame-anim pipeline OK
+          Do NOT reuse decompose pattern
+```
+
+## Sheet layout (general contract)
+
+| Group       | Purpose                           | Cell rules                                                                        | Runtime                               |
+| ----------- | --------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------- |
+| **States**  | In-place damage before separation | Same camera/scale/anchor; damage grows                                            | Frame anim **or** transparent overlay |
+| **Modules** | Pieces after separation           | One piece per cell; ≤40–50% cell; NO whole subject; **neutral** (no wrong glyphs) | Directional burst                     |
+
+Typical grid: **states row 1**, **modules row 2** (e.g. 4+4 in 2×4).
+
+**Generation**: Prefer `gpt-image-2/edit` with reference PNG as `images[0]`:
+
+- **Fixed subject** → actual game asset
+- **Variable subject (tiles)** → **blank ivory face** (`tile_blank_face.png`), not a numbered tile
+
+Prompt + post-process — see [reference.md](reference.md).
+
+## Blank-board overlay pattern (test13 tile shatter)
+
+When the board shows **many different faces** but FX art was authored from **one** reference tile:
+
+| Mistake                                     | Fix                                                                                         |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Overlay full tile with 三萬 on a 九萬 match | Generate from **blank board**; post-process f1–f3 to **crack lines only** (transparent PNG) |
+| Play f0 intact reference cover              | **Skip f0** in `anim_*_crack`; start at first damage frame                                  |
+| Hide board tile before crack                | **Keep real tiles visible** until crack anim completes, then hide → modules                 |
+| Modules carry red character strokes         | Strip glyphs in post-process → neutral ivory/brown shards                                   |
+
+**Scripts (canonical in skill)**:
+
+```bash
+python3 ../skills/playable-fx-decompose/scripts/build-blank-tile-crack.py
+python3 ../skills/playable-fx-decompose/scripts/generate-shard-debris.py
+```
+
+- `assets/reference/tile_blank_face.png` — canonical blank edit reference
+
+**Catalog**:
+
+```json
+{
+  "pattern": "decompose",
+  "crackMode": "overlay",
+  "crackKeys": ["fx_shard_debris_f1", "fx_shard_debris_f2", "fx_shard_debris_f3"],
+  "moduleKeys": ["fx_shard_debris_f4", "..."]
+}
+```
+
+**Runtime timing (tile shatter)**:
+
+- Crack anim ~28 fps, 3 frames (f1→f3) — snappy; double frameRate if feels slow
+- Module tween duration ~½ legacy (e.g. 190–310 ms); stagger ~10 ms
+- Do **not** use `random * 2π` for modules; quadrant map TL/TR/BL/BR
+
+## Failure modes (universal)
+
+| Symptom                | Root cause                                | Fix                                                    |
+| ---------------------- | ----------------------------------------- | ------------------------------------------------------ |
+| Black boxes / halos    | Opaque bg on **NORMAL** blend             | Chroma/near-black → α=0; never peak-repack particles   |
+| 乱七八糟 / random spin | Unrelated cells + random rotation         | State/module sheet; index→angle map                    |
+| **牌面对不上**         | Full reference tile overlay on wrong face | Blank board + crack overlay; keep real tile visible    |
+| f0 flash wrong art     | Intact cell = edit reference              | Skip f0 in runtime anim keys                           |
+| State anim jitter      | Per-frame crop shifts anchor              | Repack state/overlays on shared canvas                 |
+| False L1 pass          | “particles exist”                         | Semantic gate: progressive crack + predictable modules |
+
+## Post-process by render type
+
+| Render type                    | Background  | Blend  | Pipeline                                                     |
+| ------------------------------ | ----------- | ------ | ------------------------------------------------------------ |
+| Frame FX (burst, ring)         | `#000000`   | ADD    | Slice → edge fade; **peak-repack OK**                        |
+| Decompose modules              | `#FF00FF`   | NORMAL | Chroma → crop → transparent; **delogo** neutral shards       |
+| Decompose states (full tile)   | `#FF00FF`   | NORMAL | Chroma → shared-anchor repack                                |
+| Decompose states (**overlay**) | transparent | NORMAL | `build-blank-tile-crack.py`: luminance diff → crack ink only |
+
+Always backup raw sheet + frames under `assets/reference/`.
+
+## Runtime composition (Phaser)
+
+### Phase 1 — States (overlay mode)
+
+1. **Keep** real subject visible (e.g. matched tiles at gather midpoint).
+2. Spawn crack **overlay** sprite at subject anchor; scale to subject footprint; NORMAL blend.
+3. Play `anim_*_crack` once (f1→f3, no f0).
+4. On complete: destroy overlay; **then** hide real subject(s).
+
+### Phase 1 — States (full-tile mode)
+
+Use when subject is fixed: spawn state sprite → anim → hide subject.
+
+### Phase 2 — Modules
+
+1. On state anim complete, spawn one sprite per `moduleKeys[i]`.
+2. **Predetermined directions** — quadrant / radial map; jitter ≤0.12 rad.
+3. Rotation ≈ flight vector ± small offset.
+4. Stagger 10–25 ms.
+
+Never random-pick from combined state+module texture pool.
+
+## Validation
+
+1. Record harness + **integration match** (not lab only).
+2. Check recording:
+   - [ ] Real subject visible under cracks (overlay mode)
+   - [ ] No wrong reference face (三萬 on 筒/条)
+   - [ ] No opaque halos on modules
+   - [ ] Modules fly TL/TR/BL/BR (or coded map)
+   - [ ] Timing feels snappy (~100 ms crack + ~250 ms modules)
+3. Do not mark pass on “sprites spawned.”
+
+## Workflow checklist
+
+```
+- [ ] Fixed vs variable subject? → pick full-tile vs blank overlay path
+- [ ] Reference: game PNG OR tile_blank_face (never numbered tile for variable board)
+- [ ] Generate sheet via edit (1 call)
+- [ ] Slice → chroma → build-blank-tile-crack.py (if overlay)
+- [ ] Repack overlay frames on shared canvas
+- [ ] catalog: crackMode, crackKeys (no f0), moduleKeys
+- [ ] Runtime: tiles visible → crack → hide → modules
+- [ ] Record & semantic review
+```
+
+## Related skills
+
+- `playable-fx-peak` — ADD 光效；**禁止**用于 decompose 模块
+- `playable-art` — chroma, atlas, icon crop
+- `playable-animate` — frameRate, stagger, easing after wiring
+
+## Additional resources
+
+- Prompt, API, build script: [reference.md](reference.md)
+- Examples: [examples.md](examples.md)

package/project-template/skills/playable-fx-decompose/examples.md

@@ -0,0 +1,89 @@
+# Decompose FX — Pattern Examples
+
+These illustrate the **pattern**, not a fixed asset spec. Adapt counts, names, and paths to the project.
+
+## Example A — Mahjong tile shatter (test13, blank overlay)
+
+**Problem (test12)**: 8 unrelated GPT fragments; opaque black repack; random 360° spin; full 三萬 sheet overlaid on 筒/条 matches.
+
+**Solution (test13)**:
+
+| Layer      | Asset                                                   | Runtime                                |
+| ---------- | ------------------------------------------------------- | -------------------------------------- |
+| Board tile | Real `Tile.face` texture                                | Visible through gather + crack         |
+| Crack      | f1–f3 **transparent overlays** (from blank-board sheet) | `anim_tile_crack` @ 28fps; **skip f0** |
+| Modules    | f4–f7 neutral ivory shards (delogo)                     | Quadrant burst after crack             |
+
+**Reference for WaveSpeed**: `tile_blank_face.png`, not `wan_3.png`.
+
+**Scripts**: `generate-shard-debris.py` → `build-blank-tile-crack.py`.
+
+**Integration gate**: match-once recording — viewer sees **correct face + cracks**, not wrong reference cover.
+
+**Timing**: ~2× faster than initial test13 (28fps crack, halved module tweens).
+
+---
+
+## Example B — Fixed coin / gem burst
+
+- **Reference**: single coin sprite (same art everywhere)
+- **Sheet**: 2 states + 6 radial modules
+- **Runtime**: full-tile state anim → hide coin → radial modules
+- **Lesson**: Overlay mode **not needed** when subject art is always identical
+
+---
+
+## Example C — UI panel crack (no particles)
+
+- **Reference**: panel chrome PNG
+- **Sheet**: 4 states only
+- **Runtime**: frame anim; panel hidden after last frame
+- **Lesson**: Decompose reduces to state row when separation is not needed
+
+---
+
+## Example D — ADD glow burst (NOT decompose)
+
+- **Sheet**: 6 frames on black, ADD blend
+- **Pipeline**: `playable-fx-peak`
+- **Lesson**: No chroma overlay, no two-phase module burst
+
+---
+
+## Anti-pattern summary
+
+| Anti-pattern                           | Why it fails                                     |
+| -------------------------------------- | ------------------------------------------------ |
+| “8 random broken pieces” text-to-image | Unrelated cells                                  |
+| Edit from 三萬, play on mixed board    | **牌面对不上**                                   |
+| Show f0 intact reference in anim       | Wrong cover flash                                |
+| Hide board tile before crack overlay   | Loses real face; overlay must carry all identity |
+| Same pool for anim + particles         | Whole tile flies as “shard”                      |
+| `rotation = Math.random() * 2π`        | Destroys quadrant semantics                      |
+| Peak-repack opaque canvas on particles | Black boxes (NORMAL blend)                       |
+| L1 pass = “sprites spawned”            | Misses break readability                         |
+
+---
+
+## Validation questions (any decompose FX)
+
+1. Can a viewer identify **what** broke?
+2. Does damage grow **before** pieces separate?
+3. (**Overlay mode**) Is the **real** subject visible under cracks?
+4. Do pieces move in **predictable** directions?
+5. Are halos/black boxes absent on the in-game background?
+6. Is timing snappy enough for playable (crack ≤150 ms feel)?
+
+---
+
+## test13 file map
+
+| Path                                      | Role                                       |
+| ----------------------------------------- | ------------------------------------------ |
+| `scripts/generate-shard-debris.py`        | WaveSpeed edit (blank prompt)              |
+| `scripts/build-blank-tile-crack.py`       | Overlay extraction + neutral modules       |
+| `assets/reference/tile_blank_face.png`    | Blank edit reference                       |
+| `game/gameplay/match-fx.js`               | `_spawnTileCrack` + `_spawnShardModules`   |
+| `game/gameplay/match-system.js`           | Keep tiles visible; pass `tiles[]`         |
+| `playground/vfx-catalog.json`             | `pattern: decompose`, `crackMode: overlay` |
+| `focus-lab/harness/particle-lab-scene.js` | Ghost tile + overlay demo                  |