@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/.claude/agents/refs/storyboard-generation-guide.md

@@ -0,0 +1,110 @@
+# Storyboard Generation Guide — MC 5-Panel 生产流程
+
+> **用途**：Orchestrator 在 **ring 3 `loop: clarify`** spawn storyboard subagent 时注入的执行指南。Subagent 按本文件流程，通过 Skill tool 加载具体规范，完成 Master Composite 生产。
+>
+> **产出终点**：≥2 套 MC 选项 + `style-exploration.md` § Master Composite 写入 + `artist-log.md` § Image Production Preflight 填写完毕。
+
+## 输入（由 Orchestrator 提供或 subagent 自行读取）
+
+| 文件                   | 关注内容                                                               |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `docs/design-brief.md` | 游戏类型、核心玩法、目标受众、Hook 策略、Style Direction、元素类型     |
+| `docs/DESIGN.md`       | 玩家体验契约、Experience Flow、元素种类                                |
+| `docs/atom-tree.json`  | `meta.selectedAtoms` 概览（了解哪些元素需要出现在 Panel 1）— if exists |
+
+> **Note**: `layout-spec.md` does not exist yet at ring 3 MC generation. Element types and style direction come from `design-brief.md` and `DESIGN.md`.
+
+---
+
+## Step 1 — Image Production Preflight
+
+**目标**：在生成任何图片前，系统性读取相关 Skills 并记录决策。
+
+**操作**：
+
+1. 使用 Skill tool 依次加载以下 Skills，每个读完后在 `logs/artist-log.md` § **Image Production Preflight** 标记 ✓ 并写一行决策摘要：
+
+| #   | Skill                        | 重点阅读段落                            | 决策内容                                   |
+| --- | ---------------------------- | --------------------------------------- | ------------------------------------------ |
+| 1   | `playcraft-storyboard`       | §0 尺寸原则、§1 五格内容、§3 模型白名单 | 布局选择（横排/网格）、分辨率档位（2K/4K） |
+| 2   | `playcraft-image-generation` | §3 模型选择决策树、§3.1 背景色幕策略    | 为 MC 选定模型（仅白名单内）               |
+| 3   | `playcraft-art-style-guide`  | 9 风格决策树                            | 为方案 A/B 各选定风格方向关键词            |
+| 4   | `playcraft-ad-psychology`    | Hook 类型 + 面板心理学映射              | Panel 2-5 的心理学策略选择                 |
+
+2. 在 `artist-log.md` 中确认：
+   - 每个 Skill 行 ✓ + 决策摘要
+   - 从 `docs/design-brief.md` / `docs/DESIGN.md` 统计的元素类型列表
+
+**禁止**：未完成 Preflight 就开始生成 MC。
+
+---
+
+## Step 2 — 生成 Master Composite（≥2 方案）
+
+**目标**：产出至少 2 套不同风格方向的 5-panel MC，供用户在 **ring 3 Ring Gate** 选择。
+
+**执行规范**（从 Skill 获得，此处仅为流程提示）：
+
+1. **Prompt 构造**：
+   - 按 `playcraft-storyboard` §2 Prompt 公式结构
+   - Panel 1（concept panel）：**必须包含 design-brief / DESIGN.md 中定义的所有 element type**
+   - Panels 2-5：根据 Step 1 选定的 Hook 心理学策略设计内容
+   - 游戏类型对应的 prompt 配方参考：`.claude/agents/refs/artist-master-composite-recipes.md`
+
+2. **生成参数**：
+   - 模型：**仅** `playcraft-storyboard` §3 白名单内（`mulerouter/gpt-image-2` 或 `mulerouter/nano-banana-2`）
+   - 尺寸：`--aspect-ratio 45:16 --width 3600 --height 1280`（2K）或 `--width 4096 --height 1455`（4K）
+   - 多方案差异来自 **prompt / 配色 / 构图 / 风格关键词**，不是换弱模型
+
+3. **生成后验收**（每张必做）：
+
+   ```bash
+   playcraft image info --input assets/images/storyboard/master_composite_option_[X].png
+   ```
+
+   - 总宽高比 width/height ≈ **2.81**（45:16）
+   - 单格推算 (width÷5) : height ≈ **9:16**（0.5625）
+   - 不合格 → **必须重生成**
+
+4. **输出命名**：
+   ```
+   assets/images/storyboard/master_composite_option_A.png
+   assets/images/storyboard/master_composite_option_B.png
+   ```
+
+---
+
+## Step 3 — 写入 style-exploration.md + 完成
+
+**目标**：将 MC 成果写入项目文档，为 ring 3 Ring Gate 准备材料。
+
+1. 在 `docs/style-exploration.md` 的 **Master Composite** 部分写入：
+   - 每套方案的图片路径
+   - 风格关键词
+   - 体验流文字说明（5 panels 的叙事逻辑）
+   - **此时不写 ASR 路径**（ASR 是后续 Artist 的工作）
+
+2. 确认所有 MC 文件已生成 + 验收通过。
+
+---
+
+## 完成条件
+
+| #   | 检查项               | 标准                                                         |
+| --- | -------------------- | ------------------------------------------------------------ |
+| 1   | Preflight            | `artist-log.md` § Image Production Preflight 4 行 Skill 均 ✓ |
+| 2   | MC 数量              | ≥2 方案（option_A + option_B 至少）                          |
+| 3   | MC 比例              | 每张 `playcraft image info` 验证通过（≈2.81）                |
+| 4   | Panel 1              | 包含 design-brief / DESIGN.md 所有 element type（目视）      |
+| 5   | style-exploration.md | MC 部分已写入路径 + 风格 + 体验流                            |
+| 6   | 模型合规             | 仅使用白名单模型（带 `mulerouter/` 前缀）                    |
+
+---
+
+## 注意事项
+
+- **不做 ASR** — 那是 Artist 在 ring 3 Ring Gate（MC 选定）后的工作
+- **不做音频** — 那是 Artist Phase 2 的工作
+- **不更新项目状态** — Orchestrator 负责通过 `npm run state:set` 做 handoff 更新
+- **英文 prompt** — 所有图片生成 prompt 使用英文
+- **JSON sidecar** — 生成后检查自动产生的 `.json` 文件，确认 aspectRatio/imageSize 正确

package/project-templates/threejs/.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-templates/threejs/.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-templates/threejs/.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/
+```