@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/.claude/agents/refs/game-designer-gameplay-sufficiency.md

@@ -0,0 +1,123 @@
+# Gameplay Sufficiency Self-Check
+
+> **When to read**: Game Designer reads this after a candidate direction is selected and before writing final `docs/design.md`. This is a **blocking gate** — do not write the design contract until all angles pass.
+>
+> **Pattern**: Modeled on Flow B's "玩法核心充分性 Review" — 8 angles covering MDA, Game Feel, visual readability, and Playable Ad flow completeness.
+
+---
+
+## Purpose
+
+Verify that the chosen direction contains enough gameplay depth to support `docs/design.md`, module selection, and downstream production. This check prevents the common failure mode of "proceeding with a technically plausible but experientially shallow design."
+
+**Why before Five-Axis**: Five-Axis evaluation and Style Direction must serve the core gameplay. If the gameplay itself is underspecified, five-axis choices become disconnected from player experience.
+
+---
+
+## 8-Angle Review Table
+
+For each angle, answer the core question. If the answer is unclear or only partially addressed by the chosen direction / draft design → mark ❌ and return to brainstorm for targeted clarification.
+
+| #   | Angle                  | Core Question                                                                            | ✅ Pass Signal                                                                                             | ❌ Fail Signal                                                                       |
+| --- | ---------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| 1   | **MDA / Mechanics**    | Core rules, player operations, legal/illegal actions — are they explicit?                | Can state: "player does X → system checks Y → result Z" with no ambiguity                                  | Only describes features/functions, never states rules                                |
+| 2   | **MDA / Dynamics**     | What strategy, rhythm, risk, or feedback loop emerges from consecutive play?             | Can describe: "after 3-5 operations, player experiences {tension/flow/escalation} because {mechanism}"     | Single operation is clear but no loop or decision pressure described                 |
+| 3   | **MDA / Aesthetics**   | Which 2-3 emotion types does this game primarily deliver?                                | Specific emotions named with source (e.g., "Sensation from cascade VFX + Challenge from near-win")         | Only "fun" / "exciting" / "engaging" without identifying emotion source              |
+| 4   | **Game Feel / Juice**  | Is the input → response → satisfaction chain planned?                                    | Each core interaction has: what feedback (visual + audio), when it fires, how it escalates on combo/streak | "Click something → something happens" — no feedback specifics                        |
+| 5   | **Visual Readability** | Can player instantly distinguish: clickable / unclickable / target / risk / progress?    | Direction or design describes HOW each gameplay state is visually communicated to the player               | Only describes art style or tech stack, not how visuals serve gameplay understanding |
+| 6   | **Level Progression**  | Do levels serve gameplay teaching and challenge escalation, or are they just data files? | Each level/stage has stated intent: "level 1 teaches X, level 2 tests Y, level 3 introduces Z"             | Only lists level count or says "difficulty increases" without per-level purpose      |
+| 7   | **Playable Ad Flow**   | Does Hook → Tutorial → Gameplay → EndCard form a 15-30s emotional closed loop?           | All four stages named with emotional beat, timing, and transition triggers                                 | Only describes the gameplay loop, no ad-specific rhythm (hook, CTA, sequel feeling)  |
+| 8   | **Data Derivation**    | Are data structures derived FROM gameplay rules, or do they drive/constrain gameplay?    | Rules/player-experience described first; data representation follows naturally                             | JSON schema / config format / solver algorithm appears before "how to play"          |
+
+---
+
+## Output Format
+
+Write self-check results in handoff summary or internal notes. Do not add a full self-check table to `docs/design-brief.md`:
+
+```markdown
+### Gameplay Sufficiency Self-Check
+
+| Angle              | Result | Notes                                                                                                       |
+| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------- |
+| MDA / Mechanics    | ✅     | Tap to unscrew → color-match to hole → gravity release when all screws removed                              |
+| MDA / Dynamics     | ✅     | Buffer management creates "which screw to remove first" strategy                                            |
+| MDA / Aesthetics   | ✅     | Sensation (satisfying unscrew SFX + gravity cascade) + Challenge (buffer full = lose)                       |
+| Game Feel / Juice  | ❌     | Success cascade feedback not specified — need to define what happens on multi-release                       |
+| Visual Readability | ✅     | Color = screw-hole match affordance; glow = removable; grey = blocked                                       |
+| Level Progression  | ✅     | L1: single color; L2: two colors; L3: introduce blocking order                                              |
+| Playable Ad Flow   | ✅     | Hook: show stuck board → Tutorial: guided first screw → Gameplay: 3-level cascade → EndCard: "more puzzles" |
+| Data Derivation    | ✅     | Rules defined first; level JSON is just instantiation of rule parameters                                    |
+
+**Result**: 7/8 pass. ❌ Game Feel → return to Step 1 for targeted clarification on cascade feedback design.
+```
+
+---
+
+## Decision
+
+- **All 8 ✅** → Proceed to Step 3 (Five-Axis Evaluation)
+- **Any ❌** → Return to Step 1 with specific angle as the brainstorm target. Ask user only about the gap (not re-do entire brainstorm).
+
+---
+
+## Reference Frameworks (Condensed for Playable Ads)
+
+### MDA — 8 Aesthetics Taxonomy (Playable Ad Relevance)
+
+| #   | Type           | Relevance  | Role in Playable Ads                                              |
+| --- | -------------- | ---------- | ----------------------------------------------------------------- |
+| 1   | **Sensation**  | ⭐⭐⭐⭐⭐ | Core — visual juice + audio feedback is the baseline for every ad |
+| 2   | **Challenge**  | ⭐⭐⭐⭐⭐ | Core — "one more try" / near-win is the #1 conversion driver      |
+| 3   | **Submission** | ⭐⭐⭐⭐   | Casual/relaxing ads — low-pressure flow, "mindless but addictive" |
+| 4   | **Discovery**  | ⭐⭐⭐     | Puzzle/reveal ads — "aha, that's how it works!" moment            |
+| 5   | **Fantasy**    | ⭐⭐       | Theme wrapping only — 15s too short for deep immersion            |
+| 6   | **Expression** | ⭐⭐       | Dress-up/customization ads — niche                                |
+| 7   | **Narrative**  | ⭐         | Almost never fits in 30s                                          |
+| 8   | **Fellowship** | ⭐         | Playable ads are single-player                                    |
+
+**Design questions:**
+
+1. "Which 2-3 aesthetics does this game primarily deliver?"
+2. "What does the player feel at second 5? At second 15? At second 25?"
+3. "Can the player experience one complete emotional cycle in 15-30s?"
+
+### 5-Component Filter (Quick Scoring)
+
+Evaluate each core mechanic against 5 components:
+
+| Component        | Core Question                    | ⭐⭐⭐ (Excellent)             | ❌ (Fail)               |
+| ---------------- | -------------------------------- | ------------------------------ | ----------------------- |
+| **Clarity**      | Can player understand in 3s?     | Zero-tutorial comprehension    | 5s+ still confused      |
+| **Motivation**   | Why does player want to act?     | Can't stop, intrinsic drive    | "Why should I do this?" |
+| **Response**     | Feedback within 100ms?           | Multi-channel instant feedback | Action → silence        |
+| **Satisfaction** | Does success feel "juicy"?       | Want "one more time"           | Success feels empty     |
+| **Fit**          | Mechanic matches theme/audience? | Inseparable from the game      | Feels "bolted on"       |
+
+**Minimum bar for Playable Ads**: All 5 components ≥ ⭐⭐. Any ❌ = redesign needed.
+
+### Game Feel — 6-Component Diagnostic
+
+When something "feels off" but can't be named, check:
+
+| Component         | Symptom                              | Fix Direction                                                                   |
+| ----------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
+| Real-Time Control | Sluggish, unresponsive               | Reduce input delay; enable animation interrupts                                 |
+| Simulated Space   | Floaty, unpredictable movement       | Make physics internally consistent (can be unrealistic but MUST be predictable) |
+| Polish (Juice)    | Technically correct but lifeless     | Add particles, screen shake, squash/stretch, sound layers                       |
+| Metaphor          | Feedback feels "wrong" for the world | Align audio/visual feedback with what real-world physics would suggest          |
+| Juiciness         | Actions feel powerless               | Amplify output-to-input ratio; small tap → big response                         |
+| Mastery           | Gets boring fast                     | Ensure control depth allows skill expression over time                          |
+
+**Playable Ad note**: In 15-30s, focus on components 1-5. Component 6 (Mastery) manifests as "perceived depth" — player should feel "I could get better at this" which drives install.
+
+---
+
+## Common Failure Patterns
+
+| Pattern                  | Example                                                                         | How to Fix                                                                              |
+| ------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Feature-list design**  | "Has scoring, timer, 3 levels, power-ups" — no rules/emotions                   | Ask: "When player does X, what happens and how does it FEEL?"                           |
+| **Tech-first design**    | "Uses physics engine with rigid bodies and constraints" — no player perspective | Ask: "What does the PLAYER see and do? Forget the implementation."                      |
+| **Single-moment design** | "Player taps tiles to match" — no loop/escalation/arc                           | Ask: "After the 5th successful match, what's different? What pressure builds?"          |
+| **Borrowed assumption**  | "It's like Candy Crush" without specifying which aspects                        | Ask: "WHICH aspects of Candy Crush? Swap mechanic? Cascade? Level goals? Visual juice?" |

package/project-template-v2/.claude/agents/refs/ta-3d-flip-recipe.md

@@ -0,0 +1,88 @@
+# TA 3D Flip & Material Reskin Recipe
+
+> Read by Technical Artist when dealing with:
+>
+> - Material/texture swap while preserving symbols (mahjong white→ice/metal/wood)
+> - Card/tile flip animations (16-frame sprite sheets)
+> - Any task requiring the 3D white model pipeline
+
+---
+
+## Option C: Material Reskin — Preserve Symbols, Swap Base Texture
+
+**THE most common TA task for sprite sheet style variants.**
+
+- Use when: mahjong white→ice, white→metal, white→wood
+- Key insight: symbols are face textures, base material is a separate layer
+
+```bash
+# Step 1: Split the original sprite sheet into individual tiles
+playcraft image sprite-split \
+  --input assets/images/tiles/original_sheet.png \
+  --output-dir assets/images/tiles/split_frames \
+  --auto-detect --hint "mahjong tiles, uniform grid"
+# → 44 individual PNGs + split-meta.json
+
+# Step 2: Generate ONE new base material texture (reused for all tiles)
+playcraft tools generate-image \
+  --prompt "ice crystal frosted glass texture, blue-white cold, seamless, top-down" \
+  --output assets/textures/ice_base.png
+
+# Step 3: Create white model with new base material
+playcraft 3d apply-texture \
+  --model plane \
+  --texture assets/textures/ice_base.png \
+  --output assets/models/ice_tile_base.glb
+
+# Step 4: For EACH tile — render white model + original symbol as face texture
+# (Uses the software rasterizer from playcraft-3d-flip-sprite SKILL)
+# face texture = the split frame from Step 1 (preserves symbol exactly)
+node render.mjs assets/models/ice_tile_base.glb \
+  assets/images/tiles/reskinned/tile_001.png \
+  assets/images/tiles/split_frames/frame_r0_c0.png
+# Repeat for all 44 tiles — write a ta-workspace script for this step
+
+# Step 5: Reassemble into sprite sheet (same grid as original)
+playcraft image sprite-sheet \
+  --inputs assets/images/tiles/reskinned/tile_001.png,tile_002.png,... \
+  --output assets/images/tiles/ice_sheet \
+  --columns <original_columns> \
+  --cell-width <W> --cell-height <H>
+```
+
+**Style switching efficiency**:
+
+- To switch to METAL: only redo Step 2 (new texture) + Step 3-5
+- To switch to WOOD: same — just one new base texture
+- Symbols never change, never touch AI regeneration
+
+---
+
+## Option D: Batch 3D Flip Sprite Sheet (e.g., 34 mahjong flip animations)
+
+Read `playcraft-3d-flip-sprite` SKILL for the full rendering pipeline.
+(Software rasterizer: no Puppeteer/headless-gl needed)
+
+**Per-tile workflow**: white model GLB + face texture → 16-frame flip sprite sheet
+
+```
+1. Flatten base GLB (remove surface geometry of original design)
+2. Generate face texture per tile variant
+3. Render 16-frame flip animation with soft rasterizer
+4. Output sprite sheet PNG
+```
+
+See `.claude/skills/playcraft-3d-flip-sprite/` for complete instructions.
+
+---
+
+## Mahjong Tile Example: All 4 Workflows Compared
+
+| Scenario                                             | Method                                                    | When                  |
+| ---------------------------------------------------- | --------------------------------------------------------- | --------------------- |
+| One concept mockup → all 34 tiles                    | Sprite Generation (AI batch with reference-image)         | Starting from scratch |
+| Existing white tiles → Ice style (symbols preserved) | 3D path (Option C above)                                  | Material/texture swap |
+| Existing white tiles → Metal style                   | 3D path (swap ice→metal texture, rerun Step 3-5)          | Style variant         |
+| Existing tiles → Pixel art style (symbols redrawn)   | Sprite Remix (per-frame AI)                               | Full creative restyle |
+| Existing tiles → Darker mood                         | Image Processing (`tint` + `overlay`)                     | Color/mood shift      |
+| Flip animation (16 frames per tile)                  | Option D (3D flip sprite, playcraft-3d-flip-sprite SKILL) | Animation             |

package/project-template-v2/.claude/agents/refs/ta-atlas-deliverable-standard.md

@@ -0,0 +1,67 @@
+# TA Atlas Deliverable Standard
+
+> **When**: ring 4 `loop: build` Wave 2 branch in `technical-artist.md` § Runtime.  
+> **Contract source**: `layout-spec.md` atlas groups + `assetMapping` (ring 2 layout-spec lock).
+
+## Defaults
+
+| Asset type          | Delivery format                                                                              |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| Runtime images      | **WebP** (`.webp`) — not PNG for final runtime assets                                        |
+| Multi-element class | **One atlas per logical group** → `.webp` + `.json` sidecar (`playcraft image sprite-sheet`) |
+| Single large asset  | One `.webp` (full-screen bg, etc.)                                                           |
+| Audio (BGM/SFX)     | **MP3** only after TA post-process                                                           |
+| Digit strip         | Single horizontal **WebP** at `layout-spec` path (not merged into UI atlas)                  |
+
+## Atlas grouping rules
+
+1. Read Game Designer's **atlas grouping table** in `layout-spec.md` (group name → elementIds → `atlasPath`).
+2. **≥2 elements in same group** → TA MUST deliver **one** `.webp` + `.json`; map each element via `frameId` in assetMapping.
+3. **Do not** split one group into scattered files.
+4. **Exceptions** (single file OK): full-screen background, digit strip, MC/ASR reference (non-runtime), animation-only atlases (one animation = one atlas).
+
+## Production pipeline
+
+1. Spec Quick-Check → Style Interpretation → micro-batch (≥3) per group.
+2. Batch generate frames → `playcraft image sprite-sheet` → convert to **WebP** if needed:
+   ```bash
+   playcraft image convert --input atlas.png --output assets/images/tiles/tiles_atlas.webp --quality 85
+   ```
+3. Validate sidecar JSON: frame count = element count in group; grid params in `ta-log.md`.
+4. Audio: Artist MP3 → `playcraft audio compress/trim/loop/fade` → output **MP3**; verify with `playcraft audio info`.
+
+## Transparency requirements
+
+| Asset category                | Alpha required | Chroma key strategy                                  | Post-verify                               |
+| ----------------------------- | -------------- | ---------------------------------------------------- | ----------------------------------------- |
+| UI overlay (icons, text, HUD) | ✅ channels=4  | Per color conflict matrix (see ta-pipeline-cookbook) | Dark-bg overlay verify (no white/residue) |
+| VFX atlas (glow, particles)   | ✅ channels=4  | Blue screen #0000FF (VFX常含金/橙色)                 | Per-frame dark-bg verify                  |
+| Game element atlas (tiles)    | ✅ channels=4  | Per color conflict matrix                            | Dark-bg overlay verify                    |
+| Card/board piece (rect body)  | ❌ opaque OK   | N/A (white bg is part of the asset)                  | N/A                                       |
+| Full-screen background        | ❌ opaque OK   | N/A                                                  | Edge-to-edge full-coverage check          |
+| Digit strip                   | ✅ channels=4  | Blue screen #0000FF (digits often gold/white)        | Dark-bg overlay verify                    |
+
+**Color conflict matrix** — choose chroma key color to avoid edge residue:
+
+- Gold/yellow/orange/green assets → **blue screen #0000FF** (never green)
+- Blue/purple assets → **green screen #00FF00** (never blue)
+- Multi-color/rainbow → **magenta #FF00FF** (last resort)
+- All others → green screen #00FF00 (default)
+
+## Compliance (TA)
+
+| Check           | Pass criteria                                                                  |
+| --------------- | ------------------------------------------------------------------------------ |
+| Atlas coverage  | Every runtime element resolves to atlas+frame or single webp path              |
+| Sidecar         | `.json` exists beside each multi-element atlas                                 |
+| Format          | WebP for images; MP3 for audio (unless layout-spec explicit exception)         |
+| ta-log          | One manifest row per atlas group: path, frames, cols/frameW/frameH/frameCount  |
+| **Alpha check** | All transparent assets have `channels=4` (verified via `playcraft image info`) |
+| **Dark-bg OK**  | All transparent assets pass dark-background (#1A1A2E) overlay — no residue     |
+| **BG coverage** | Full-screen backgrounds: edge-to-edge, no fade/vignette/white corners          |
+
+## Developer handoff
+
+Developer loads `atlasPath` once, uses `frameId` from layout-spec / JSON — not per-element file paths for grouped assets.
+
+See also: `ta-pipeline-cookbook.md`, `playcraft-sprite-generation` SKILL (final delivery extension = `.webp`).

package/project-template-v2/.claude/agents/refs/ta-batch-pipeline-recipes.md

@@ -0,0 +1,120 @@
+> 本文件是 batch/pipeline 的实用配方集。选型决策树和基础语法见 `playcraft-batch-pipeline` skill。
+
+# Batch / Pipeline 实用配方集
+
+---
+
+## Batch 配方
+
+### 批量 resize + 转换格式
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw_tiles/ \
+  --output-dir assets/images/tiles/ \
+  --glob "*.png" \
+  --steps "resize --width 128 --height 128, trim" \
+  --parallel 8
+```
+
+### 批量去背（绿幕）
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw_sprites/ \
+  --output-dir assets/images/sprites/ \
+  --steps "remove-background --method floodfill --tolerance 40" \
+  --parallel 4
+```
+
+### 批量统一色调（制作主题变体）
+
+```bash
+# 生成蓝色主题版本
+playcraft image batch \
+  --input-dir assets/images/tiles/ \
+  --output-dir assets/images/tiles_blue_theme/ \
+  --steps "tint --color #4466BB" \
+  --parallel 6
+```
+
+### 断点续传（大批量任务中断后恢复）
+
+```bash
+# 第一次运行中断了
+playcraft image batch \
+  --input-dir assets/images/raw/ \
+  --output-dir assets/images/processed/ \
+  --steps "resize --width 256 --height 256, grayscale" \
+  --parallel 4 \
+  --skip-existing    # 再次运行时跳过已完成的文件
+```
+
+---
+
+## Pipeline 配方
+
+### 配方 A: 去背 + 统一尺寸 + 合并精灵图
+
+```yaml
+# ta-workspace/tile_pipeline.yaml
+input:
+  dir: assets/images/raw_tiles/
+  glob: '*.png'
+
+steps:
+  - command: remove-background
+    method: floodfill
+    tolerance: 40
+  - command: trim
+    threshold: 10
+  - command: resize
+    width: 128
+    height: 128
+  - command: pad
+    all: 4
+
+output:
+  dir: ta-workspace/tmp/tiles_processed/
+
+assemble:
+  sprite-sheet:
+    output: assets/images/tiles_atlas
+    columns: 6
+    padding: 2
+```
+
+```bash
+playcraft image pipeline --config ta-workspace/tile_pipeline.yaml
+```
+
+### 配方 B: 多个主题色版本
+
+为同一套素材生成不同色调的主题变体：
+
+```bash
+# 蓝色主题
+playcraft image pipeline --config ta-workspace/theme_blue.yaml
+
+# 红色主题（修改 tint color 即可）
+sed 's/#4466BB/#BB4444/' ta-workspace/theme_blue.yaml > ta-workspace/theme_red.yaml
+playcraft image pipeline --config ta-workspace/theme_red.yaml
+```
+
+### 配方 C: 批量缩略图生成
+
+```yaml
+input:
+  dir: assets/images/concept/
+  glob: '*.png'
+steps:
+  - command: resize
+    width: 240
+    height: 240
+    fit: cover
+  - command: convert
+    format: webp
+    quality: 80
+output:
+  dir: assets/images/thumbnails/
+```