@playcraft/cli 0.0.44 → 0.0.47

package/project-template/templates/gen-placeholders.template.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Batch placeholder generator for develop-stage asset materialization.
+ *
+ * Setup:
+ *   cp templates/gen-placeholders.template.mjs ta-workspace/scripts/gen-placeholders.mjs
+ *
+ * Run:
+ *   node ta-workspace/scripts/gen-placeholders.mjs
+ *   # or: npm run placeholder:gen
+ *
+ * Uses local gen-placeholder.py — outputs <stem>.webp + <stem>.json per row.
+ * See skills/playable-placeholder/SKILL.md for full Developer workflow.
+ * TA overwrites these files later — code should only reference contract paths.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = process.cwd();
+const GEN_SCRIPT = join(ROOT, 'skills/_shared/scripts/gen-placeholder.py');
+const BATCH_JSON = join(ROOT, 'ta-workspace/tmp/placeholders.batch.json');
+
+// Derive from layout-spec.md → assetMapping (or ring-1 minimal prototype list).
+// bg/fg: closest palette hex from layout-spec → palette.
+// label: elementId; role: optional purpose for TA (auto-inferred from prefix if omitted)
+// shape: auto | fill | rounded | circle | ellipse | diamond | ring | triangle-up | triangle-down
+const PLACEHOLDERS = [
+  {
+    path: 'assets/images/bg/bg_main.webp',
+    size: '750x1334',
+    bg: '1a1a2e',
+    fg: 'cccccc',
+    label: 'bg_main',
+    shape: 'fill',
+  },
+  {
+    path: 'assets/images/ui/btn_cta.webp',
+    size: '300x100',
+    bg: 'ff6b35',
+    fg: 'ffffff',
+    label: 'btn_cta',
+    shape: 'rounded',
+    role: 'CTA button · 主行动按钮',
+  },
+  {
+    path: 'assets/images/tiles/tile_gold.webp',
+    size: '128x128',
+    bg: 'ffcc00',
+    fg: '000000',
+    label: 'tile_gold',
+    shape: 'circle',
+  },
+  {
+    path: 'assets/images/tiles/tile_empty.webp',
+    size: '128x128',
+    bg: '333333',
+    fg: '888888',
+    label: 'tile_empty',
+    shape: 'circle',
+  },
+  // Add one row per missing visual resource expected by the minimal prototype.
+];
+
+function runBatch() {
+  mkdirSync(dirname(BATCH_JSON), { recursive: true });
+  writeFileSync(BATCH_JSON, `${JSON.stringify(PLACEHOLDERS, null, 2)}\n`, 'utf8');
+
+  const proc = spawnSync('python3', [GEN_SCRIPT, '--batch', BATCH_JSON], {
+    cwd: ROOT,
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+  if (proc.status !== 0) {
+    process.exit(proc.status ?? 1);
+  }
+}
+
+runBatch();

package/project-template/templates/intent-clarifications.template.md

@@ -21,7 +21,7 @@ Rules:
   - 提问必须具体，不能是"风格不对"这种模糊描述
   - 必须引用具体文件路径或 atomId，方便目标 Agent 定位
   - Confidence = low 的风格解读问题必须写入此表
-  - Developer 发现故事板与 layout-spec 坐标不一致时，必须向 PM 提问
+  - Developer 发现故事板与 layout-spec 坐标不一致时，必须向 Game Designer 提问
 -->
 
 ## Resolved
@@ -32,9 +32,9 @@ Rules:
 
 <!--
 Resolution examples:
-  - "已补充到 designer-log.md Style Intent Notes"
+  - "已补充到 artist-log.md Style Intent Notes"
   - "已更新 layout-spec.md zones 坐标"
-  - "PM 裁决：以故事板为准，layout-spec 将修正"
+  - "Game Designer 裁决：以故事板为准，layout-spec 将修正"
   - "双方同意保持现状，偏差在可接受范围"
 -->
 
@@ -44,15 +44,15 @@ Resolution examples:
 | ---------------------- | --------- |
 | Total questions raised | {{count}} |
 | Unresolved             | {{count}} |
-| By Designer            | {{count}} |
+| By Artist              | {{count}} |
 | By TA                  | {{count}} |
 | By Developer           | {{count}} |
-| By PM                  | {{count}} |
+| By Game Designer       | {{count}} |
 | By Reviewer            | {{count}} |
 
 <!--
-PM monitors this table:
+Game Designer monitors this table:
   - If single Agent receives >3 questions → intent transmission fault, record in DAG Revisions
-  - If unresolved >3 at any time → PM must intervene and assign priority
+  - If unresolved >3 at any time → Game Designer must intervene and assign priority
   - If Reviewer finds unresolved questions at review stage → deduct Intent Transmission score
 -->

package/project-template/templates/layout-spec.template.md

@@ -1,11 +1,14 @@
 # Layout Spec
 
 <!--
-  PM owns paths + specs (Gate #1 lock). CONTRACT only — zones, palette ids, assetMapping, atlas table, WxH/format.
-  Do NOT add: storyboard prose, Style Intent Notes, TA logs (→ designer-log / ta-log).
+  Game Designer owns paths + specs (ring 2 clarify lock). CONTRACT only — zones, palette ids, assetMapping, atlas table, WxH/format.
+  Do NOT add: storyboard prose, Style Intent Notes, TA logs (→ artist-log / ta-log).
+
+  **Slice-axis Ring 2**: layout **intent only** — Screen + Zones (+ optional palette ids).
+  Skip Asset Spec, Atlas grouping, Element Type Registry, Asset Mapping, and Text Assets until Ring 3+ or orchestrator discloses production lock.
 -->
 
-> Shared contract between Designer, TA, and Developer. All MUST follow this document.
+> Shared contract between Artist, TA, and Developer. All MUST follow this document.
 
 ## Screen
 
@@ -15,9 +18,9 @@
 
 ## Zones
 
-| id          | role          | rect (x, y, w, h)          | owner                       |
-| ----------- | ------------- | -------------------------- | --------------------------- |
-| {{zone_id}} | {{zone_role}} | {{x}}, {{y}}, {{w}}, {{h}} | {{Designer/Developer/both}} |
+| id          | role          | rect (x, y, w, h)          | owner                     |
+| ----------- | ------------- | -------------------------- | ------------------------- |
+| {{zone_id}} | {{zone_role}} | {{x}}, {{y}}, {{w}}, {{h}} | {{Artist/Developer/both}} |
 
 <!--
 Add one row per zone. Common zones:
@@ -46,7 +49,7 @@ ASCII diagram (update to match your zones):
 
 <!--
 - Element IDs are used by Developer in PGS config
-- Hex colors guide Designer's generation prompts
+- Hex colors guide Artist's generation prompts
 - Labels are human-readable names for the elements
 - Typically 4-6 elements for a playable ad
 -->
@@ -69,7 +72,7 @@ ASCII diagram (update to match your zones):
 Default runtime formats: images WebP, audio MP3. TA delivers atlas groups as .webp + .json sidecar.
 -->
 
-## Atlas grouping (Gate #1 — PM defines)
+## Atlas grouping (ring 2 clarify — Game Designer defines)
 
 | groupId | elementIds       | atlasPath                            | sidecarPath                          |
 | ------- | ---------------- | ------------------------------------ | ------------------------------------ |
@@ -88,7 +91,7 @@ Single-element groups stay as single-file paths; do not invent atlases for one t
 
 ## Element Type Registry (ASR capacity budget)
 
-Group `assetMapping` elementIds by **visual type** before Gate #1 lock. Designer needs **one representative per type** on ASR or MC Panel 1; color variants are `ta-extends`.
+Group `assetMapping` elementIds by **visual type** before ring 2 layout-spec lock. Artist needs **one representative per type** on ASR or MC Panel 1; color variants are `ta-extends`.
 
 | typeId   | elementIds (variants)        | Notes                           |
 | -------- | ---------------------------- | ------------------------------- |
@@ -96,7 +99,7 @@ Group `assetMapping` elementIds by **visual type** before Gate #1 lock. Designer
 
 **Budget**: aim for **≤ 20 unique types** and **≤ ~24 ASR physical slots** (ui board ~12 + element board ~12). If types > 12, plan `element_state_sheet_[X]_2.png` or extra `mc-crop` + `ta-extends` rows.
 
-Designer Coverage Matrix **elementType** column should match `typeId` here.
+Artist Coverage Matrix **elementType** column should match `typeId` here.
 
 ---
 
@@ -114,21 +117,30 @@ Designer Coverage Matrix **elementType** column should match `typeId` here.
 
 <!--
 CRITICAL: This mapping is the integration contract!
-- Designer saves files at EXACTLY these paths
+- Artist saves files at EXACTLY these paths
 - Developer references EXACTLY these paths in code
 - Path mismatch = integration failure
 - Use "—" for cells that don't apply
 
-Transparency convention (TA auto-derives from path — PM does NOT define):
+Transparency convention (TA auto-derives from path — Game Designer does NOT define):
   assets/images/bg/   → opaque, full-screen background (TA verifies edge-to-edge)
-  assets/images/ui/   → needs alpha (TA applies chroma key + remove-background)
-  assets/images/txt/  → needs alpha (TA applies chroma key + remove-background)
-  assets/images/vfx/  → needs alpha (TA applies chroma key + remove-background)
+  assets/images/ui/   → needs alpha (TA chooses chroma / dual-bg-diff / rgb-alpha-split)
+  assets/images/txt/  → needs alpha (TA chooses chroma / rgb-alpha-split)
+  assets/images/vfx/  → needs alpha (TA chooses rgb-alpha-split / black-add / chroma)
   assets/images/tiles/ → needs alpha by default (except card faces / board pieces)
   assets/audio/       → N/A (not image)
 
-TA determines chroma key color (green/blue/magenta) based on element color palette
-and color conflict rules — see ta-pipeline-cookbook.md Step 0e.
+TA records alphaStrategy in logs/ta-log.md:
+  chroma          → hard-edge assets on green/blue/magenta flat background
+  dual-bg-diff    → two geometry-identical renders with different flat backgrounds
+  rgb-alpha-split → left RGB (Red Green Blue, 红绿蓝) + right Alpha grayscale matte
+  black-add       → black-backed VFX (Visual Effects, 视觉特效) played with ADD blend
+  opaque          → no alpha needed
+
+Video assets use videoAlphaStrategy:
+  chroma-video / dual-bg-video / rgb-alpha-video / opaque-video
+
+See skills/playable-art/references/alpha-postprocess.md.
 -->
 
 ## Text Assets
@@ -143,7 +155,7 @@ All visible text is rendered as image assets — no font files in the final buil
 
 <!--
 Common static text: game title, CTA button label, tutorial instructions, "YOU WIN", stage labels.
-Designer includes all static text in the Master Composite concept panel.
+Artist includes all static text in the Master Composite concept panel.
 TA extracts each text element using segment and saves to the specified path.
 -->
 
@@ -154,10 +166,10 @@ TA extracts each text element using segment and saves to the specified path.
 - **Asset path**: `assets/images/txt/digits.webp` _(recommended: text-class lives under `images/txt/` per Transparency Classification)_
 - **Sidecar path (optional)**: `assets/images/txt/digits.json` _(only when laid out as multi-row grid; single-row strip can omit)_
 - **Layout**: single-row horizontal strip (default) — total width = `cell_w × frameCount`, height = `cell_h`
-- **Alpha**: required (channels = 4); TA uses **bluescreen** chroma (text typically gold/white — avoid green key)
+- **Alpha**: required (channels = 4); TA uses `chroma` bluescreen or `rgb-alpha-split` (text typically gold/white — avoid green key)
 
 <!--
-PM defines the character set based on what dynamic text the game needs.
+Game Designer defines the character set based on what dynamic text the game needs.
 
 Common sets (always include digits 0–9 first, then any symbols):
 - Score only:         "0123456789"                 (frameCount = 10)

package/project-template/templates/plan.template.md

@@ -0,0 +1,80 @@
+# Implementation Plan — {Game Name} (Slice Queue Explain View)
+
+<!--
+  NOT the daily dispatch axis — sliceState.slices[] + dispatchPacket drive execution.
+
+  This file is an optional human-readable explain view of the active slice queue:
+  - what each slice proves
+  - why slices are ordered this way
+  - which atoms/skills inform each slice (without mirroring the full atom graph)
+
+  Do:
+  - map sliceId → outcome → acceptance hints
+  - note engine/atom context that informed slice boundaries
+  - keep Ring 1 to 1–3 developer slices max
+  - Ring 2: 2–4 developer periphery slices (HUD / flow / tutorial hints — not full backlog)
+
+  Do not:
+  - replace sliceState or dispatchPacket
+  - dump file trees or TS interfaces
+  - compress the entire atom-tree into one Ring 1 mega-plan
+  - duplicate DESIGN.md or design-brief discovery prose
+-->
+
+**Slice queue source of truth**: `docs/project-state.json` → `sliceState` (via `npm run state:get -- --json dispatchPacket sliceState`)
+
+**Engine**: {engine or undecided}
+**Active slices (human summary)**: {list sliceIds in dispatch order}
+
+---
+
+## 1. Slice map (explain view)
+
+| sliceId                   | role      | doWhat (summary)               | verifier     | blockedBy / notes |
+| ------------------------- | --------- | ------------------------------ | ------------ | ----------------- |
+| {core-action-feedback-v1} | developer | {tap → feedback → progress +1} | verify:slice | first slice       |
+| {…}                       | developer | {…}                            | verify:slice | {optional}        |
+
+---
+
+## 2. Atom / skill context (not the full graph)
+
+> Full structured contract: `docs/atom-tree.json` (`meta.selectedAtoms`, `meta.skillsMatch`).
+> Ring 1 activated scope: `meta.activatedSlices[]` — do not expand to full product tree in one ring.
+
+| sliceId | Relevant atoms / skills        | Why it matters for this slice only |
+| ------- | ------------------------------ | ---------------------------------- |
+| {…}     | {engine atom / gameplay trunk} | {one line}                         |
+
+---
+
+## 3. Deferred to later rings
+
+- Layout / assetMapping → Ring 2+ (`layout-spec.md`)
+- Hook / CTA packaging → Ring 3+
+- Production assets → Ring 4
+- Full feature backlog → only after slice queue proves playable spine
+
+---
+
+## 4. Legacy feature sections (Ring 2+ only)
+
+<!--
+  Below sections apply when the project exits pure slice-axis Ring 1 seeding.
+  Do not fill Feature 详细清单 in Ring 1 — use slice map above instead.
+-->
+
+### Feature: {name — Ring 2+}
+
+- **Outcome**: {player-visible result}
+- **Depends On**: {sliceId or feature}
+- **Acceptance**: {2–4 verifiable checks}
+
+---
+
+## 5. Self-check
+
+- [ ] Slice map matches `sliceState.slices[]` ordering and roles
+- [ ] Ring 1 does not contain layout/style/CTA production plan
+- [ ] Atom-tree is referenced, not copied wholesale into this file
+- [ ] No TS interface / pseudo-code / file tree dump