@playcraft/cli 0.0.44 → 0.0.47

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

@@ -0,0 +1,201 @@
+# Decompose FX — Prompt & Post-Process Reference
+
+## gpt-image-2/edit (WaveSpeed)
+
+```json
+{
+  "prompt": "<see template>",
+  "images": ["data:image/png;base64,..."],
+  "aspect_ratio": "1:1",
+  "resolution": "4k",
+  "quality": "low",
+  "output_format": "png"
+}
+```
+
+`POST https://api.wavespeed.ai/api/v3/openai/gpt-image-2/edit`  
+Poll `GET …/predictions/{id}/result` until `completed`.
+
+### Which reference to pass
+
+| Gameplay                           | `images[0]`                                                                                        |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Single fixed prop (coin, crate)    | That in-game PNG                                                                                   |
+| **Variable faces (mahjong tiles)** | **Blank ivory tile** — `assets/reference/tile_blank_face.png`                                      |
+| No reference yet                   | Build blank from any tile: strip red chars → ivory fill (`build-blank-tile-crack.py` creates this) |
+
+**Never** pass a numbered/character tile (e.g. 三萬) as edit ref when board shows mixed faces — module row may still be neutral, but state row will encode wrong glyphs unless post-processed to overlay-only.
+
+---
+
+## Prompt template — fixed subject
+
+```
+Image 1 is the reference {SUBJECT} from the game.
+Match its exact art style, colors, lighting, and proportions.
+Create a NEW sprite sheet on perfectly flat pure {BG_COLOR} background.
+Strict {ROWS} rows x {COLS} columns, exactly {N} cells, at least {GAP}px gap between cells.
+No dividers, no labels, no watermarks, no motion blur trails.
+
+Row 1 — STATE PROGRESSION ({STATE_COUNT} cells):
+Same {SUBJECT}, same camera, same scale, centered in each cell.
+Cell 0: intact, matching Image 1.
+Cell 1..{STATE_COUNT-1}: progressive damage; subject stays one piece until last state.
+
+Row 2 — SEPARATED MODULES ({MODULE_COUNT} cells):
+One broken piece per cell from the same {SUBJECT}.
+Pieces occupy at most 45% of each cell. NOT the whole {SUBJECT}.
+{MODULE_LAYOUT_HINT}
+
+All cells: identical lighting and palette.
+NOT unrelated illustrations. NOT duplicate whole subjects in module row.
+```
+
+---
+
+## Prompt template — blank board (variable tile faces)
+
+Use when runtime composes on **real board tiles** (overlay mode).
+
+```
+Image 1 is a BLANK mahjong tile face — warm ivory/cream front, golden-amber side edge,
+NO engraved characters, NO numbers, NO symbols. 2D mobile game look.
+
+Create a NEW sprite sheet on perfectly flat pure magenta (#FF00FF) background.
+Strict 2 rows x 4 columns, 8 square cells, at least 100px gap between cells.
+
+Row 1 — FRONT CRACK on the SAME blank ivory tile (centered, same size):
+Cell 0: intact blank ivory face (no characters).
+Cell 1: thin hairline cracks on ivory only.
+Cell 2: cracks spreading, still one piece.
+Cell 3: heavy cracks, about to break apart.
+
+Row 2 — QUADRANT MODULES from that blank tile (one shard per cell):
+Cells 4–7: ivory/brown shards, NO character strokes, ≤45% cell each.
+Row 2 must NOT contain a whole tile.
+
+All 8 cells: identical lighting and palette.
+```
+
+After WaveSpeed: **always** run `build-blank-tile-crack.py` to convert row 1 into transparent crack overlays and delogo modules.
+
+---
+
+## Post-process: `build-blank-tile-crack.py`
+
+```bash
+cd test13 && python3 scripts/build-blank-tile-crack.py
+```
+
+Pipeline:
+
+1. **Blank reference** — delogo red characters from tile PNG → `tile_blank_face.png`
+2. **f1–f3** — delogo each state cell; extract crack ink via luminance diff vs blank baseline → **RGBA overlay** (dark brown cracks, transparent elsewhere)
+3. **f4–f7** — delogo modules (strip red strokes → neutral ivory shards)
+4. **Repack** overlay frames on shared centered canvas (stable anchor)
+5. Backup previous frames → `assets/reference/shard_debris-pre-blank-*`
+
+`generate-shard-debris.py` invokes this automatically after slicing.
+
+### Crack overlay extraction (concept)
+
+```python
+# blank_intact = delogo(reference tile)
+# cracked = delogo(state_frame)
+# alpha where luminance(blank) - luminance(cracked) > threshold
+# rgb = dark brown crack color; feather alpha slightly
+```
+
+---
+
+## Shared-anchor repack (state / overlay group)
+
+After chroma removal + per-cell crop:
+
+```python
+def repack_state_frames(frames: list[Image.Image], pad: int = 16) -> list[Image.Image]:
+    max_w = max(im.size[0] for im in frames)
+    max_h = max(im.size[1] for im in frames)
+    out_w, out_h = max_w + 2 * pad, max_h + 2 * pad
+    out = []
+    for im in frames:
+        canvas = Image.new("RGBA", (out_w, out_h), (0, 0, 0, 0))
+        canvas.alpha_composite(im, ((out_w - im.size[0]) // 2, (out_h - im.size[1]) // 2))
+        out.append(canvas)
+    return out
+```
+
+---
+
+## Module direction maps
+
+**Quadrant (4 modules)** — test13 `shard_debris`:
+
+```javascript
+[-Math.PI * 0.75, -Math.PI * 0.25, Math.PI * 0.75, Math.PI * 0.25]; // TL TR BL BR
+```
+
+Module index `i` → `moduleKeys[i]` + `angles[i]`. No random texture index. No `random * 2π`.
+
+---
+
+## Runtime wiring (overlay mode)
+
+**match-system.js** — do NOT hide tiles at impact; pass into FX:
+
+```javascript
+MatchFx.playTileShatter(scene, { midX, midY, fromA, fromB, tiles: [tile1, tile2], ... });
+```
+
+**match-fx.js** — `_spawnTileCrack(scene, cx, cy, depth, tiles, onComplete)`:
+
+1. Spawn sprite `fx_shard_debris_f1`, scale to `TILE_W × TILE_H`, NORMAL, α≈0.92
+2. Play `anim_tile_crack` (keys f1,f2,f3 @ ~28 fps)
+3. On `animationcomplete`: destroy overlay; `tiles.forEach(t => t.setVisible(false))`; spawn modules
+
+**boot-scene.js** anim:
+
+```javascript
+createAnim(
+  'anim_tile_crack',
+  ['fx_shard_debris_f1', 'fx_shard_debris_f2', 'fx_shard_debris_f3'],
+  28,
+  0,
+);
+```
+
+**particle-lab** — demo ghost tile under overlay (gameplay uses real tiles).
+
+---
+
+## Chroma → transparent (NORMAL sprites)
+
+```python
+# #FF00FF or near-black → alpha 0; crop to content bbox
+# Never leave alpha=255 on background for NORMAL blend
+```
+
+---
+
+## When to use which API
+
+| Situation                 | API                                                                |
+| ------------------------- | ------------------------------------------------------------------ |
+| Fixed in-game subject     | `gpt-image-2/edit` + that PNG                                      |
+| Variable tile/board faces | `gpt-image-2/edit` + **blank face** → overlay post-process         |
+| Generic glow, no subject  | `gpt-image-2/text-to-image` on black (ADD pipeline)                |
+| Edit fails twice          | Increase cell padding in prompt; do not switch to random fragments |
+
+---
+
+## Timing defaults (tile shatter, test13)
+
+| Param                       | Value                |
+| --------------------------- | -------------------- |
+| `anim_tile_crack` frameRate | 28                   |
+| Crack keys                  | f1, f2, f3 (skip f0) |
+| Module duration             | 190–310 ms           |
+| Module stagger              | ~10 ms               |
+| `aftermathMs`               | ~260 ms              |
+
+Adjust via `ANIM_CONFIG.tile.matchShatter` + catalog `scale` min/max.

package/project-template/skills/playable-fx-decompose/requirements.txt

@@ -0,0 +1,2 @@
+numpy>=1.24
+Pillow>=10.0

package/project-template/skills/playable-fx-decompose/scripts/build-blank-tile-crack.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+Build blank-tile decompose assets for shard_debris:
+  f1-f3 → transparent crack-line overlays (for compositing on any real tile face)
+  f4-f7 → neutral ivory/brown module shards (no character strokes)
+
+Uses wan_3 geometry; strips red character pixels. Does not require WaveSpeed.
+
+Usage:
+  python3 scripts/build-blank-tile-crack.py
+"""
+
+from __future__ import annotations
+
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter
+
+ROOT = Path(__file__).resolve().parent.parent
+FX_DIR = ROOT / "assets" / "images" / "fx"
+REF_DIR = ROOT / "assets" / "reference"
+TILE_REF = ROOT / "assets" / "images" / "tiles" / "wan_3.png"
+IVORY = np.array([245, 230, 200], dtype=np.uint8)
+CRACK_RGB = np.array([72, 48, 36], dtype=np.uint8)
+
+
+def is_red_char(r: np.ndarray, g: np.ndarray, b: np.ndarray) -> np.ndarray:
+    return (r.astype(int) > 120) & (r > g + 28) & (r > b + 28)
+
+
+def luminance(arr: np.ndarray) -> np.ndarray:
+    rgb = arr[:, :, :3].astype(np.float32)
+    return 0.299 * rgb[:, :, 0] + 0.587 * rgb[:, :, 1] + 0.114 * rgb[:, :, 2]
+
+
+def alpha_bbox(alpha: np.ndarray, threshold: int = 32) -> tuple[int, int, int, int] | None:
+    ys, xs = np.where(alpha > threshold)
+    if len(xs) == 0:
+        return None
+    return int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1
+
+
+def delogo_rgba(img: Image.Image) -> np.ndarray:
+    """Remove engraved characters; keep ivory face + amber body."""
+    arr = np.array(img.convert("RGBA")).copy()
+    r, g, b, a = arr[:, :, 0], arr[:, :, 1], arr[:, :, 2], arr[:, :, 3]
+    red = is_red_char(r, g, b) & (a > 32)
+    arr[red, 0:3] = IVORY
+    return arr
+
+
+def fit_canvas(im: Image.Image, size: tuple[int, int]) -> Image.Image:
+    canvas = Image.new("RGBA", size, (0, 0, 0, 0))
+    im.thumbnail(size, Image.Resampling.LANCZOS)
+    ox = (size[0] - im.width) // 2
+    oy = (size[1] - im.height) // 2
+    canvas.alpha_composite(im, (ox, oy))
+    return canvas
+
+
+def build_blank_intact() -> np.ndarray:
+    tile = Image.open(TILE_REF).convert("RGBA")
+    return delogo_rgba(tile)
+
+
+def crack_overlay_from_states(blank_intact: np.ndarray, cracked: np.ndarray) -> np.ndarray:
+    """Crack lines only — transparent PNG for overlay on real board tiles."""
+    h = max(blank_intact.shape[0], cracked.shape[0])
+    w = max(blank_intact.shape[1], cracked.shape[1])
+
+    def pad(a: np.ndarray) -> np.ndarray:
+        out = np.zeros((h, w, 4), dtype=np.uint8)
+        out[: a.shape[0], : a.shape[1]] = a
+        return out
+
+    b = pad(blank_intact)
+    c = pad(cracked)
+    face = (b[:, :, 3] > 32) | (c[:, :, 3] > 32)
+    lb = luminance(b)
+    lc = luminance(c)
+    # Darker than delogged baseline → crack / fracture ink
+    delta = np.clip(lb - lc, 0, 255)
+    crack = (delta > 14) & face
+    # Also pick up explicit dark stroke pixels on the ivory face
+    dark = (lc < 95) & face & (b[:, :, 3] > 32)
+    crack = crack | dark
+
+    out = np.zeros((h, w, 4), dtype=np.uint8)
+    out[crack, :3] = CRACK_RGB
+    out[crack, 3] = np.clip(delta[crack] * 2.2 + 80, 0, 255).astype(np.uint8)
+    # Feather slightly for softer composite
+    alpha = Image.fromarray(out[:, :, 3], mode="L").filter(ImageFilter.GaussianBlur(radius=0.6))
+    out[:, :, 3] = np.array(alpha)
+    return out
+
+
+def neutral_module(arr: np.ndarray) -> np.ndarray:
+    """Generic ivory shard — strip red character remnants."""
+    out = delogo_rgba(Image.fromarray(arr))
+    r, g, b, a = out[:, :, 0], out[:, :, 1], out[:, :, 2], out[:, :, 3]
+    # Soften any leftover saturated red fringe
+    fringe = is_red_char(r, g, b) & (a > 0)
+    out[fringe, 0:3] = IVORY
+    return out
+
+
+def repack_state_canvas(frames: list[np.ndarray], pad: int = 16) -> list[np.ndarray]:
+    if not frames:
+        return frames
+    bboxes = [alpha_bbox(f[:, :, 3]) for f in frames]
+    bboxes = [b for b in bboxes if b]
+    if not bboxes:
+        return frames
+    max_w = max(b[2] - b[0] for b in bboxes)
+    max_h = max(b[3] - b[1] for b in bboxes)
+    cw, ch = max_w + 2 * pad, max_h + 2 * pad
+    packed: list[np.ndarray] = []
+    for f in frames:
+        bbox = alpha_bbox(f[:, :, 3])
+        if bbox is None:
+            packed.append(f)
+            continue
+        x0, y0, x1, y1 = bbox
+        crop = f[y0:y1, x0:x1]
+        canvas = np.zeros((ch, cw, 4), dtype=np.uint8)
+        px = (cw - crop.shape[1]) // 2
+        py = (ch - crop.shape[0]) // 2
+        canvas[py : py + crop.shape[0], px : px + crop.shape[1]] = crop
+        packed.append(canvas)
+    return packed
+
+
+def backup_existing() -> None:
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = REF_DIR / f"shard_debris-pre-blank-{stamp}"
+    backup.mkdir(parents=True, exist_ok=True)
+    for i in range(8):
+        src = FX_DIR / f"shard_debris_frame{i:02d}.png"
+        if src.exists():
+            shutil.copy(src, backup / src.name)
+    print(f"[backup] -> {backup.relative_to(ROOT)}")
+
+
+def main() -> None:
+    REF_DIR.mkdir(parents=True, exist_ok=True)
+    backup_existing()
+
+    blank_intact = build_blank_intact()
+    blank_path = REF_DIR / "tile_blank_face.png"
+    Image.fromarray(blank_intact).save(blank_path)
+    print(f"[blank] {blank_path.relative_to(ROOT)}")
+
+    # f0 kept on disk for diff reference; runtime skips it
+    f0_path = FX_DIR / "shard_debris_frame00.png"
+    if f0_path.exists():
+        f0_blank = delogo_rgba(Image.open(f0_path))
+        blank_intact = f0_blank
+        Image.fromarray(f0_blank).save(REF_DIR / "shard_debris_f0_blank.png")
+
+    crack_frames: list[np.ndarray] = []
+    for i in (1, 2, 3):
+        src = FX_DIR / f"shard_debris_frame{i:02d}.png"
+        if not src.exists():
+            print(f"[WARN] missing {src}")
+            continue
+        cracked = delogo_rgba(Image.open(src))
+        overlay = crack_overlay_from_states(blank_intact, cracked)
+        crack_frames.append(overlay)
+
+    crack_frames = repack_state_canvas(crack_frames, pad=12)
+    for idx, overlay in enumerate(crack_frames, start=1):
+        out = FX_DIR / f"shard_debris_frame{idx:02d}.png"
+        Image.fromarray(overlay).save(out)
+        print(f"  crack overlay f{idx}: {out.name} {overlay.shape[1]}x{overlay.shape[0]}")
+
+    for i in (4, 5, 6, 7):
+        src = FX_DIR / f"shard_debris_frame{i:02d}.png"
+        if not src.exists():
+            continue
+        arr = neutral_module(np.array(Image.open(src).convert("RGBA")))
+        out = FX_DIR / f"shard_debris_frame{i:02d}.png"
+        Image.fromarray(arr).save(out)
+        print(f"  module f{i}: {out.name} (neutral)")
+
+    print("[build-blank-tile-crack] done")
+
+
+if __name__ == "__main__":
+    main()

package/project-template/skills/playable-fx-decompose/scripts/fix-shard-debris-frames.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Make shard_debris particle frames transparent + tight-crop for sprite_burst."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+ROOT = Path(__file__).resolve().parent.parent
+FX_DIR = ROOT / "assets" / "images" / "fx"
+LUM_THRESHOLD = 40
+PAD = 12
+
+
+def content_mask(arr: np.ndarray) -> np.ndarray:
+    rgb_max = arr[:, :, :3].max(axis=2)
+    alpha = arr[:, :, 3].astype(np.float32) / 255.0
+    lum = rgb_max.astype(np.float32) * np.maximum(alpha, 0.05)
+    return lum > LUM_THRESHOLD
+
+
+def fix_frame(path: Path) -> tuple[int, int]:
+    img = Image.open(path).convert("RGBA")
+    arr = np.array(img)
+    mask = content_mask(arr)
+    if not mask.any():
+        raise ValueError(f"no visible content in {path}")
+
+    # Near-black background -> fully transparent (NORMAL blend particles).
+    arr[~mask, :3] = 0
+    arr[~mask, 3] = 0
+
+    ys, xs = np.where(mask)
+    x0 = max(0, int(xs.min()) - PAD)
+    y0 = max(0, int(ys.min()) - PAD)
+    x1 = min(arr.shape[1], int(xs.max()) + 1 + PAD)
+    y1 = min(arr.shape[0], int(ys.max()) + 1 + PAD)
+    cropped = Image.fromarray(arr).crop((x0, y0, x1, y1))
+    cropped.save(path)
+    return cropped.size
+
+
+def main() -> None:
+    frames = sorted(FX_DIR.glob("shard_debris_frame*.png"))
+    if not frames:
+        print("ERROR: no shard_debris_frame*.png found", file=sys.stderr)
+        sys.exit(1)
+
+    for path in frames:
+        w, h = fix_frame(path)
+        print(f"  {path.name}: {w}x{h}")
+
+    print(f"[fix-shard-debris] updated {len(frames)} frames")
+
+
+if __name__ == "__main__":
+    main()