@playcraft/cli 0.0.39 → 0.0.41
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +66 -3
- package/dist/atom-plan/validate-atom-plan.js +298 -0
- package/dist/cli-root-help.js +1 -1
- package/dist/commands/3d.js +363 -0
- package/dist/commands/create.js +337 -0
- package/dist/commands/fix-ids.js +17 -3
- package/dist/commands/fix-ids.test.js +264 -0
- package/dist/commands/image.js +1337 -43
- package/dist/commands/login.js +60 -2
- package/dist/commands/recommend.js +1 -1
- package/dist/commands/remix.js +213 -0
- package/dist/commands/skills.js +1379 -0
- package/dist/commands/tools-3d.js +473 -0
- package/dist/commands/tools-generation.js +454 -0
- package/dist/commands/tools-project.js +400 -0
- package/dist/commands/tools-research.js +37 -0
- package/dist/commands/tools-research.test.js +216 -0
- package/dist/commands/tools-utils.js +164 -0
- package/dist/commands/tools.js +7 -616
- package/dist/config.js +2 -0
- package/dist/index.js +20 -2
- package/dist/utils/agent-api-client.js +52 -16
- package/package.json +9 -3
- package/project-template/.claude/agents/designer.md +116 -0
- package/project-template/.claude/agents/developer.md +133 -0
- package/project-template/.claude/agents/pm.md +164 -0
- package/project-template/.claude/agents/refs/README.md +67 -0
- package/project-template/.claude/agents/refs/designer-art-style-catalog.md +533 -0
- package/project-template/.claude/agents/refs/designer-color-audio-recipes.md +153 -0
- package/project-template/.claude/agents/refs/designer-deliverable-spec.md +167 -0
- package/project-template/.claude/agents/refs/designer-dimension-axis.md +27 -0
- package/project-template/.claude/agents/refs/designer-handoff-v2-checklist.md +68 -0
- package/project-template/.claude/agents/refs/designer-master-composite-recipes.md +216 -0
- package/project-template/.claude/agents/refs/designer-style-exploration-flow.md +37 -0
- package/project-template/.claude/agents/refs/developer-dev-handoff.md +109 -0
- package/project-template/.claude/agents/refs/developer-impl-cookbook.md +134 -0
- package/project-template/.claude/agents/refs/developer-phase1-flow.md +211 -0
- package/project-template/.claude/agents/refs/pm-workflow-detail.md +545 -0
- package/project-template/.claude/agents/refs/reviewer-six-dimension-eval.md +286 -0
- package/project-template/.claude/agents/refs/ta-3d-flip-recipe.md +85 -0
- package/project-template/.claude/agents/refs/ta-atlas-deliverable-standard.md +46 -0
- package/project-template/.claude/agents/refs/ta-batch-pipeline-recipes.md +120 -0
- package/project-template/.claude/agents/refs/ta-image-generation-detail.md +356 -0
- package/project-template/.claude/agents/refs/ta-image-ops-reference.md +495 -0
- package/project-template/.claude/agents/refs/ta-pipeline-cookbook.md +699 -0
- package/project-template/.claude/agents/refs/ta-tools-reference.md +111 -0
- package/project-template/.claude/agents/refs/ta-vfx-preset-catalog.md +365 -0
- package/project-template/.claude/agents/reviewer.md +103 -0
- package/project-template/.claude/agents/technical-artist.md +111 -0
- package/project-template/.claude/hooks/README.md +36 -0
- package/project-template/.claude/hooks/validate-atom-plan.mjs +224 -0
- package/project-template/.claude/hooks/validate-workflow-stop.mjs +258 -0
- package/project-template/.claude/settings.json +32 -0
- package/project-template/.claude/settings.local.json +4 -0
- package/project-template/.claude/skills/playcraft-ad-psychology/SKILL.md +182 -0
- package/project-template/.claude/skills/playcraft-art-style-guide/SKILL.md +123 -0
- package/project-template/.claude/skills/playcraft-asset-state-sheet/SKILL.md +141 -0
- package/project-template/.claude/skills/playcraft-audio-generation/SKILL.md +280 -0
- package/project-template/.claude/skills/playcraft-batch-pipeline/SKILL.md +184 -0
- package/project-template/.claude/skills/playcraft-build-optimizer/SKILL.md +306 -0
- package/project-template/.claude/skills/playcraft-image-generation/SKILL.md +229 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs +123 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs +254 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs +235 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs +97 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs +118 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/process-batch.template.mjs +137 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/prompt-cookbook.md +397 -0
- package/project-template/.claude/skills/playcraft-image-generation/reference/validate-sprite-sheet.template.mjs +296 -0
- package/project-template/.claude/skills/playcraft-image-ops/SKILL.md +122 -0
- package/project-template/.claude/skills/playcraft-masking/SKILL.md +373 -0
- package/project-template/.claude/skills/playcraft-research/SKILL.md +212 -0
- package/project-template/.claude/skills/playcraft-sprite-generation/SKILL.md +423 -0
- package/project-template/.claude/skills/playcraft-storyboard/SKILL.md +148 -0
- package/project-template/.claude/skills/playcraft-style-qa/SKILL.md +270 -0
- package/project-template/.claude/skills/playcraft-text-rendering/SKILL.md +236 -0
- package/project-template/.claude/skills/playcraft-vfx-animation/SKILL.md +130 -0
- package/project-template/.claude/skills/playcraft-workflow/SKILL.md +396 -0
- package/project-template/.cursor/hooks.json +17 -0
- package/project-template/.cursor/rules/playcraft-orchestrator.mdc +87 -0
- package/project-template/.cursor/rules/playcraft-subagent-boundary.mdc +18 -0
- package/project-template/CLAUDE.md +240 -0
- package/project-template/assets/audio/bgm/.gitkeep +0 -0
- package/project-template/assets/audio/sfx/.gitkeep +0 -0
- package/project-template/assets/bundles/.gitkeep +0 -0
- package/project-template/assets/images/bg/.gitkeep +0 -0
- package/project-template/assets/images/reference/.gitkeep +0 -0
- package/project-template/assets/images/storyboard/.gitkeep +0 -0
- package/project-template/assets/images/tiles/.gitkeep +0 -0
- package/project-template/assets/images/ui/.gitkeep +0 -0
- package/project-template/assets/images/vfx/.gitkeep +0 -0
- package/project-template/assets/models/.gitkeep +0 -0
- package/project-template/docs/team/agent-conduct.md +105 -0
- package/project-template/docs/team/agent-runtime-matrix.md +62 -0
- package/project-template/docs/team/atom-plan-format.md +74 -0
- package/project-template/docs/team/collaboration.md +288 -0
- package/project-template/docs/team/core-model.md +50 -0
- package/project-template/docs/team/platform-capabilities.md +15 -0
- package/project-template/docs/team/workflow-changelog.md +51 -0
- package/project-template/docs/team/workflow-consistency-checklist.md +128 -0
- package/project-template/game/config/.gitkeep +0 -0
- package/project-template/game/gameplay/.gitkeep +0 -0
- package/project-template/game/scenes/.gitkeep +0 -0
- package/project-template/logs/.gitkeep +0 -0
- package/project-template/ta-workspace/logs/.gitkeep +0 -0
- package/project-template/ta-workspace/scripts/.gitkeep +0 -0
- package/project-template/ta-workspace/tmp/.gitkeep +0 -0
- package/project-template/templates/atom-plan.template.json +26 -0
- package/project-template/templates/atom-plan.template.md +76 -0
- package/project-template/templates/design-brief.template.md +195 -0
- package/project-template/templates/design-lens-checklist.reference.md +117 -0
- package/project-template/templates/design-methodology.md +99 -0
- package/project-template/templates/designer-log.template.md +98 -0
- package/project-template/templates/developer-log.template.md +140 -0
- package/project-template/templates/five-axis-framework.md +186 -0
- package/project-template/templates/intent-clarifications.template.md +58 -0
- package/project-template/templates/layout-spec.template.md +132 -0
- package/project-template/templates/project-state.template.md +219 -0
- package/project-template/templates/review-report.template.md +166 -0
- package/project-template/templates/style-exploration.template.md +93 -0
- package/project-template/templates/ta-log.template.md +205 -0
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Developer Log
|
|
2
|
+
|
|
3
|
+
## Upstream Intake
|
|
4
|
+
|
|
5
|
+
> **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.** Summarize what PM/Designer/TA already decided so implementation matches intent.
|
|
6
|
+
|
|
7
|
+
| Doc | Read ✓ | One-line takeaway (what you will implement from it) |
|
|
8
|
+
| --------------------------- | ------ | ------------------------------------------------------ |
|
|
9
|
+
| `docs/project-state.md` | ☐ | {{e.g. integration, Wave 2 done, no spec-gap}} |
|
|
10
|
+
| `docs/design-brief.md` | ☐ | {{e.g. PGS=match-3, tutorial 2 taps, first level win}} |
|
|
11
|
+
| `docs/layout-spec.md` | ☐ | {{e.g. board zone, tile atlas path + frameIds}} |
|
|
12
|
+
| `docs/atom-plan.json` | ☐ | {{e.g. 6 Developer atoms, skillRef memory_match}} |
|
|
13
|
+
| `docs/atom-plan.md` | ☐ | Impl Skill Context + acceptance criteria |
|
|
14
|
+
| `docs/style-exploration.md` | ☐ | {{e.g. MC panel1 UI layout, Hook frame contrast}} |
|
|
15
|
+
| `logs/designer-log.md` | ☐ | {{e.g. motion: slow-mo near-win}} |
|
|
16
|
+
| `logs/ta-log.md` | ☐ | {{e.g. Compliance green, tile atlas 8 frames}} |
|
|
17
|
+
|
|
18
|
+
**MUST NOT** start Skill Preflight until every row is checked with a non-empty takeaway.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Skill Preflight
|
|
23
|
+
|
|
24
|
+
> **Ph.1 gate — before any `game/` edits.** Per `docs/atom-plan.json` `atoms[]` (`assignTo: Developer`, non-null `skillRef`). See `refs/developer-phase1-flow.md` Step 3.
|
|
25
|
+
|
|
26
|
+
| skillRef | access | `ref/` files read (paths) | `scaffold` included |
|
|
27
|
+
| ------------ | --------------------- | ----------------------------------------------- | ------------------- |
|
|
28
|
+
| {{skillRef}} | linked / cli-fallback | {{e.g. .claude/skills/.../ref/pgs-schema.json}} | yes / no |
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# Paste actual CLI output snippets (or summary) below — empty section = Ph.1 incomplete
|
|
32
|
+
{{skills_read_and_scaffold_output}}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
<!--
|
|
36
|
+
Rules:
|
|
37
|
+
- One row per non-dash skillRef from atom-plan
|
|
38
|
+
- access: `linked` = read `.claude/skills/<skillRef>/`; `cli-fallback` = soft link missing, used `playcraft skills read` + Package Skills Root
|
|
39
|
+
- If skillRef = — for an atom, note "skills match" or playcraft-research in Impl Skill Context instead
|
|
40
|
+
- Do NOT mark GameplayAtom/ConfigAtom done in atom-plan until this table is filled
|
|
41
|
+
-->
|
|
42
|
+
|
|
43
|
+
## Delivery Summary
|
|
44
|
+
|
|
45
|
+
- **Assigned**: {{total_assigned}}
|
|
46
|
+
- **Completed**: {{total_completed}}
|
|
47
|
+
- **Bindings resolved**: {{resolved}}/{{total_bindings}}
|
|
48
|
+
|
|
49
|
+
## Experience Flow → Code Mapping
|
|
50
|
+
|
|
51
|
+
> **Step 0c — Mandatory. Map each storyboard frame to code scene.**
|
|
52
|
+
> Read `docs/style-exploration.md` concept mockup + storyboard composite image before implementing.
|
|
53
|
+
> The storyboard is a single composite image with 4 frames in a grid — study each frame's position.
|
|
54
|
+
|
|
55
|
+
| Storyboard Frame | Scene/State | Code Location | Visual Intent |
|
|
56
|
+
| ------------------------- | ---------------- | ------------------------- | ----------------------------- |
|
|
57
|
+
| Hook (0-3s) | `scene.hook` | `game/scenes/hook.ts` | {{visual_intent_description}} |
|
|
58
|
+
| Tutorial (3-10s) | `scene.tutorial` | `game/scenes/tutorial.ts` | {{visual_intent_description}} |
|
|
59
|
+
| Gameplay+NearWin (10-25s) | `scene.gameplay` | `game/scenes/gameplay.ts` | {{visual_intent_description}} |
|
|
60
|
+
| EndCard (25-30s) | `scene.endcard` | `game/scenes/endcard.ts` | {{visual_intent_description}} |
|
|
61
|
+
|
|
62
|
+
<!--
|
|
63
|
+
Rules:
|
|
64
|
+
- Every scene code file MUST have a top comment referencing the storyboard:
|
|
65
|
+
// Visual reference: assets/images/storyboard/storyboard_confirmed.png (frame: top-left=Hook)
|
|
66
|
+
- If storyboard frame visuals conflict with layout-spec zones coordinates:
|
|
67
|
+
→ storyboard takes precedence, ask PM in intent-clarifications.md
|
|
68
|
+
- Visual Intent column should capture the EMOTION and ATTENTION FLOW, not just mechanics
|
|
69
|
+
-->
|
|
70
|
+
|
|
71
|
+
## Per-Atom Delivery
|
|
72
|
+
|
|
73
|
+
### {{atom_id}} — {{slot_name}}
|
|
74
|
+
|
|
75
|
+
- **Status**: {{status}}
|
|
76
|
+
- **Reference Skill**: {{skillRef}} (Skill Preflight: linked or cli-fallback + ref/)
|
|
77
|
+
- **Output path**: {{file_path}}
|
|
78
|
+
- **Test results**: {{passed}}/{{total}} passed
|
|
79
|
+
- **Notes**: {{implementation_notes}}
|
|
80
|
+
|
|
81
|
+
<!--
|
|
82
|
+
Repeat for each atom.
|
|
83
|
+
For GameplayAtom: include PGS path + test results
|
|
84
|
+
For ConfigAtom: include config path + parameter summary
|
|
85
|
+
-->
|
|
86
|
+
|
|
87
|
+
## Binding Status
|
|
88
|
+
|
|
89
|
+
| Binding Target | Source Atom | File | Status |
|
|
90
|
+
| ---------------------------- | ------------------ | ------------------- | -------------------------- |
|
|
91
|
+
| {{scene_path_or_config_key}} | {{source_atom_id}} | {{asset_file_path}} | {{bound/missing/mismatch}} |
|
|
92
|
+
|
|
93
|
+
<!--
|
|
94
|
+
List every asset reference in your code:
|
|
95
|
+
- Every image loaded from assets/images/
|
|
96
|
+
- Every audio file referenced from assets/audio/
|
|
97
|
+
- Every config value from layout-spec
|
|
98
|
+
|
|
99
|
+
Status values:
|
|
100
|
+
bound — File exists and is correctly referenced
|
|
101
|
+
missing — File not found at expected path
|
|
102
|
+
mismatch — File exists but wrong dimensions/format
|
|
103
|
+
-->
|
|
104
|
+
|
|
105
|
+
## Dev self-check
|
|
106
|
+
|
|
107
|
+
> After `npm run dev` — record each integration pass. See `refs/developer-dev-handoff.md`.
|
|
108
|
+
|
|
109
|
+
- **devUrl**: {{http://localhost:...}}
|
|
110
|
+
- **devLastChecked**: {{ISO timestamp}}
|
|
111
|
+
- **UI vs MC + layout-spec**: {{pass/fail — notes}}
|
|
112
|
+
- **Gameplay vs design-brief + PGS**: {{pass/fail — notes}}
|
|
113
|
+
- **Runtime** (no white screen, CTA, audio, state machine): {{pass/fail — notes}}
|
|
114
|
+
- **Ready for Reviewer**: {{yes/no}}
|
|
115
|
+
|
|
116
|
+
## Upstream blockers
|
|
117
|
+
|
|
118
|
+
| Path | Issue | Expected | routeTo | Status |
|
|
119
|
+
| -------- | --------- | -------------- | ------------------ | --------------- |
|
|
120
|
+
| {{path}} | {{issue}} | {{acceptance}} | TA / Designer / PM | open / resolved |
|
|
121
|
+
|
|
122
|
+
<!--
|
|
123
|
+
When any row is open:
|
|
124
|
+
- Set project-state devStatus: blocked_upstream
|
|
125
|
+
- Write intent-clarifications.md with acceptance criteria
|
|
126
|
+
- STOP — wait for orchestrator rework invoke
|
|
127
|
+
-->
|
|
128
|
+
|
|
129
|
+
## Technical Self-Check (static)
|
|
130
|
+
|
|
131
|
+
- [ ] Board dimensions match layout-spec `zones["board"].rect`?
|
|
132
|
+
- [ ] Element IDs match layout-spec `colorPalette.tileColors[].id`?
|
|
133
|
+
- [ ] All asset paths match layout-spec `assetMapping`?
|
|
134
|
+
- [ ] Zero external network requests (no fetch/XHR/external scripts)?
|
|
135
|
+
- [ ] CTA handler implemented with multi-platform fallback?
|
|
136
|
+
- [ ] `game/index.html` has viewport meta with user-scalable=no?
|
|
137
|
+
- [ ] All CSS/JS inline (no external resources)?
|
|
138
|
+
- [ ] First level guarantees player success?
|
|
139
|
+
|
|
140
|
+
> **Not required for integration complete**: `playcraft build` (future delivery path only).
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Five-Axis Analysis Framework
|
|
2
|
+
|
|
3
|
+
> **When to read**: PM reads this during Step 4 (Five-Axis Evaluation).
|
|
4
|
+
> Every playable ad request must be classified along all five orthogonal axes before generating options.
|
|
5
|
+
|
|
6
|
+
The five axes are **orthogonal** — each is an independent decision. The same Match-3 game can be Flat 2D or 2.5D, Tap-only or Drag, L0 or L1, Competence Arc or Challenge Arc. PM evaluates all five internally, then presents 2-3 complete options (covering all axes) for the user to choose from.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Axis 1 — Mechanic (Gameplay Fusion Types)
|
|
11
|
+
|
|
12
|
+
| Type | Definition | Tutorial Overhead | Risk |
|
|
13
|
+
|------|-----------|-------------------|------|
|
|
14
|
+
| **Single** | One mechanic, no fusion | Baseline | None |
|
|
15
|
+
| **Type A — Visual Fusion** | Mechanics unchanged; elements re-skinned to another game's visual language | None | Very Low |
|
|
16
|
+
| **Type B1 — Passive Borrowing** | Primary mechanic + secondary mechanic auto-triggers (no extra user gesture) | Minimal | Low |
|
|
17
|
+
| **Type B2 — Active Borrowing** | Primary mechanic + secondary mechanic requires user activation (1.5 core gestures) | Slight increase | Medium |
|
|
18
|
+
| **Type C — Sequential Fusion** | Two mechanic sets appear in sequence (includes rotation/alternating mode) | High | High |
|
|
19
|
+
| **Type D — Parallel Fusion** | Two mechanic sets active simultaneously, sharing the screen | Extreme | Extreme (almost never viable for ads) |
|
|
20
|
+
|
|
21
|
+
### Pseudo-Fusion Technique
|
|
22
|
+
|
|
23
|
+
When the user insists on Type C/D, recommend pseudo-fusion: **visually appear as two systems, but the underlying mechanic is single**. Example: Match-3 elimination count drives a monster HP bar — the user only performs match-3 the entire time, but perceives "elimination + combat."
|
|
24
|
+
|
|
25
|
+
### Decision Rules
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
User prompt contains fusion intent?
|
|
29
|
+
YES → Classify A / B1 / B2 / C / D
|
|
30
|
+
Type C/D → Auto-generate downgrade option (pseudo-fusion B1) as recommended
|
|
31
|
+
NO → Single gameplay → PGS priority check:
|
|
32
|
+
1. Implemented PGS (Match-3, Triple Match, Path Elimination, Arrow Pick Match) — lowest risk
|
|
33
|
+
2. Existing Skill (ball_sort, bubble_shooter, etc.) — medium risk
|
|
34
|
+
3. Needs new development — highest risk
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Axis 2 — Dimension (Gameplay Dimension Spectrum)
|
|
40
|
+
|
|
41
|
+
| Dimension | Description | Designer Impact | Developer Impact | Risk Delta |
|
|
42
|
+
|-----------|------------|----------------|-----------------|------------|
|
|
43
|
+
| **Flat 2D** | Pure 2D sprites, no depth | Standard 2D illustration assets | Standard 2D logic | None |
|
|
44
|
+
| **2.5D Visual** | 3D rendered look, but game logic remains 2D grid (depth is decorative) | 3D-feel rendering / model textures, ~3x cost | Logic stays 2D, add depth rendering | +Medium |
|
|
45
|
+
| **Isometric** | Fixed 45° angle, depth is aesthetic not mechanic | Isometric assets, strict pixel alignment required | Isometric coordinate transforms | +Low |
|
|
46
|
+
| **True 3D** | Z-axis is a live mechanic (rotation/depth participates in interaction) | Full 3D models via AI (`generate-3d`) or white model + texture pipeline; 3–5x cost | 3D engine, physics, camera management; all existing PGS invalidated | +High (tool support available, not BLOCKED) |
|
|
47
|
+
|
|
48
|
+
### Key Judgment
|
|
49
|
+
|
|
50
|
+
Is the dimension upgrade "purely visual decoration" (2.5D Visual) or "Z-axis participates in mechanics" (True 3D)? The former only affects Designer asset cost; the latter requires entirely new PGS — fundamentally different risk profiles.
|
|
51
|
+
|
|
52
|
+
### True 3D Tool Support (Available as of 2026-05)
|
|
53
|
+
|
|
54
|
+
True 3D is **High Risk** but no longer blocked. Designer has two asset pipelines:
|
|
55
|
+
|
|
56
|
+
**Pipeline A — AI Generation (best quality, ~1–5 min per model)**
|
|
57
|
+
```bash
|
|
58
|
+
playcraft tools generate-3d --prompt "low-poly wooden crate" --output assets/models/crate.glb
|
|
59
|
+
playcraft 3d optimize --input crate.glb --output crate_opt.glb
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Pipeline B — White Model + Texture (fastest, predictable UV)**
|
|
63
|
+
```bash
|
|
64
|
+
playcraft 3d list-models # sphere, cube, cylinder, cone, torus, plane, capsule
|
|
65
|
+
playcraft tools generate-image --prompt "texture" --output tex.png
|
|
66
|
+
playcraft 3d apply-texture --model cube --texture tex.png --output crate.glb
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Decision Rules
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
Z-axis is a live mechanic (rotation/depth affects gameplay)?
|
|
73
|
+
→ True 3D — tool pipeline available (Pipeline A or B above)
|
|
74
|
+
still recommend generating 2.5D Visual option as fallback
|
|
75
|
+
3D visual feel but 2D interaction grid?
|
|
76
|
+
→ 2.5D Visual (Designer cost ~3x, Developer logic unchanged)
|
|
77
|
+
Fixed isometric perspective?
|
|
78
|
+
→ Isometric
|
|
79
|
+
Otherwise → Flat 2D (default, zero additional risk)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Axis 3 — Interaction Modality
|
|
85
|
+
|
|
86
|
+
| Modality | Description | Tutorial Time | Audience Width | Risk Delta |
|
|
87
|
+
|----------|------------|--------------|---------------|------------|
|
|
88
|
+
| **Tap Only** | Single-finger single-tap | ≤1s | Broadest (includes elderly, children) | None |
|
|
89
|
+
| **Tap + Swipe** | Tap + directional swipe | ~3s | Broad | +Low |
|
|
90
|
+
| **Drag** | Press-hold and drag to target | ~5s | Medium | +Low |
|
|
91
|
+
| **Tap + Hold** | Tap + long-press with timing | ~5s | Medium | +Medium |
|
|
92
|
+
| **Multi-touch** | Two or more fingers simultaneously | ≥10s | Very narrow | +Extreme (almost never viable for ads) |
|
|
93
|
+
|
|
94
|
+
### Key Insight
|
|
95
|
+
|
|
96
|
+
The **same mechanic** can have different interaction implementations. Arrow gameplay can be "tap a cell" (Tap Only) or "drag to draw a path" (Drag) — Tutorial time differs by 5x, audience width differs dramatically.
|
|
97
|
+
|
|
98
|
+
### Decision Rules
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
What gesture does the mechanic naturally map to?
|
|
102
|
+
→ Select the most natural modality
|
|
103
|
+
Does a simpler modality (Tap Only) serve the mechanic adequately?
|
|
104
|
+
→ If yes, prefer simpler — wider audience, shorter tutorial
|
|
105
|
+
Multi-touch required?
|
|
106
|
+
→ Flag as high risk for 30s ad; recommend single-touch alternative
|
|
107
|
+
Note tutorial time budget: Tap=1s / Tap+Swipe=3s / Drag=5s / Tap+Hold=5s
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Axis 4 — Narrative Level
|
|
113
|
+
|
|
114
|
+
| Level | Definition | Designer Impact | Tutorial Method | 30s Fitness |
|
|
115
|
+
|-------|-----------|----------------|----------------|------------|
|
|
116
|
+
| **L0 Pure Mechanic** | No character, no story, pure gameplay showcase | No character assets | Highlight hints + text | High (concise) |
|
|
117
|
+
| **L1 Character Present** | Protagonist exists but no plot ("help the kitten match!") | 1 character sprite set needed | Character performs demo action | **Highest (recommended)** |
|
|
118
|
+
| **L2 Scenario Wrapper** | Character + problem scenario ("princess trapped, clear obstacles") | Protagonist + scenario narrative assets | Character dialogue + demo | Medium (must be tight) |
|
|
119
|
+
| **L3 Story-Driven** | Narrative is core, mechanics serve the story | Heavy story assets + storyboards | Cinematic storytelling | Low (almost never fits 30s) |
|
|
120
|
+
|
|
121
|
+
### Key Insights
|
|
122
|
+
|
|
123
|
+
- **L1 is the sweet spot for playable ads** — emotional connection without time overhead.
|
|
124
|
+
- L1+ means Designer needs character assets; PM must define character concept.
|
|
125
|
+
- L3 is **incompatible with 30s format** — auto-downgrade to L2 with explanation.
|
|
126
|
+
|
|
127
|
+
### Decision Rules
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
User mentions character / hero / story? → L1 or L2
|
|
131
|
+
Game genre typically story-heavy (RPG, adventure)? → L2 recommended
|
|
132
|
+
No character signal, generic product? → L0 or L1
|
|
133
|
+
Default for playable ads: L1
|
|
134
|
+
L2+: flag that Designer needs character asset set
|
|
135
|
+
L3: auto-downgrade to L2 — incompatible with 30s format
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Axis 5 — Emotional Arc
|
|
141
|
+
|
|
142
|
+
| Arc Type | Player Journey | Hook Design | Gameplay Feel | EndCard Tone |
|
|
143
|
+
|----------|---------------|-------------|--------------|-------------|
|
|
144
|
+
| **Competence** | Confused → Learned → "I'm smart!" | Show "looks hard but has a pattern" | Generous, guarantee success | "Easy and fun, keep playing" |
|
|
145
|
+
| **Challenge** | Looks hard → All-out effort → Achievement | Create difficult scenario | Difficulty ramp, allow failure | "Think you can beat it?" |
|
|
146
|
+
| **Curiosity** | What is this? → Aha! → Surprise | Show counter-intuitive mechanic | Full of surprises | "More to explore" |
|
|
147
|
+
| **Relaxation** | Enter flow → Enjoy rhythm → Satisfaction | Serene, beautiful imagery | Steady pace, low pressure | "Come relax anytime" |
|
|
148
|
+
| **Urgency** | Crisis → Frantic action → Narrow escape | Emergency scene, countdown | High pressure, fast pace | "One more round!" |
|
|
149
|
+
|
|
150
|
+
### Key Principle
|
|
151
|
+
|
|
152
|
+
The Emotional Arc is the **unified throughline** across Hook → Tutorial → Gameplay → EndCard. If the Hook creates curiosity but Gameplay delivers relaxation, the experience fractures. The arc must be locked at the PM stage; all downstream Agents execute along this arc.
|
|
153
|
+
|
|
154
|
+
### Decision Rules
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
Map user motivation type (JTBD) to arc:
|
|
158
|
+
Stress Relief → Relaxation or Competence Arc
|
|
159
|
+
Challenge/Mastery → Challenge Arc
|
|
160
|
+
Collection/Growth → Competence Arc
|
|
161
|
+
Creativity/Expression or Immersion/Escape → Curiosity Arc
|
|
162
|
+
Time pressure / urgency game → Urgency Arc
|
|
163
|
+
Select ONE arc. Lock it as the throughline for all 4 stages.
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Option Generation (After All Five Axes)
|
|
169
|
+
|
|
170
|
+
After completing all five internal classifications, generate 2-3 complete options:
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
Each option includes:
|
|
174
|
+
- Mechanic Axis (type + PGS coverage)
|
|
175
|
+
- Dimension Axis (type + Designer impact)
|
|
176
|
+
- Interaction Modality (modality + tutorial time estimate)
|
|
177
|
+
- Narrative Level (level + asset impact)
|
|
178
|
+
- Emotional Arc (arc type + Hook/EndCard tone)
|
|
179
|
+
- Overall Risk Rating (Low / Medium / High / Extreme)
|
|
180
|
+
|
|
181
|
+
Option A (recommended) = lowest-risk viable option, listed first
|
|
182
|
+
Option B = stronger visual/experience but with extra cost
|
|
183
|
+
Option C = user's original request (if extreme risk, mark with warning)
|
|
184
|
+
|
|
185
|
+
User only needs to answer "choose A/B/C" or "agree with recommendation"
|
|
186
|
+
```
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Intent Clarifications
|
|
2
|
+
|
|
3
|
+
> **Living Document**: Agent 间异步澄清的共享空间。
|
|
4
|
+
> 所有 Agent 可读;提问 Agent 和目标 Agent 可写。
|
|
5
|
+
> 不阻塞流水线 — 提问 Agent 先用合理推断继续,回答到达后评估是否调整。
|
|
6
|
+
|
|
7
|
+
## Open Questions
|
|
8
|
+
|
|
9
|
+
| # | From | To | Atom/Topic | Question | Raised At | Status |
|
|
10
|
+
| ----- | -------------- | ---------------- | -------------------- | --------------------- | -------------- | ------ |
|
|
11
|
+
| {{n}} | {{agent_name}} | {{target_agent}} | {{atom_id_or_topic}} | {{specific_question}} | {{stage_name}} | open |
|
|
12
|
+
|
|
13
|
+
<!--
|
|
14
|
+
Status values:
|
|
15
|
+
open — 等待目标 Agent 回答
|
|
16
|
+
pending — 目标 Agent 已看到,正在处理
|
|
17
|
+
answered — 目标 Agent 已回答,提问 Agent 尚未确认
|
|
18
|
+
resolved — 双方达成一致,已移入 Resolved 表
|
|
19
|
+
|
|
20
|
+
Rules:
|
|
21
|
+
- 提问必须具体,不能是"风格不对"这种模糊描述
|
|
22
|
+
- 必须引用具体文件路径或 atomId,方便目标 Agent 定位
|
|
23
|
+
- Confidence = low 的风格解读问题必须写入此表
|
|
24
|
+
- Developer 发现故事板与 layout-spec 坐标不一致时,必须向 PM 提问
|
|
25
|
+
-->
|
|
26
|
+
|
|
27
|
+
## Resolved
|
|
28
|
+
|
|
29
|
+
| # | From | To | Question Summary | Answer | Resolution | Closed By |
|
|
30
|
+
| ----- | -------------- | ---------------- | -------------------- | --------------- | ----------------------- | -------------- |
|
|
31
|
+
| {{n}} | {{agent_name}} | {{target_agent}} | {{one_line_summary}} | {{answer_text}} | {{how_it_was_resolved}} | {{agent_name}} |
|
|
32
|
+
|
|
33
|
+
<!--
|
|
34
|
+
Resolution examples:
|
|
35
|
+
- "已补充到 designer-log.md Style Intent Notes"
|
|
36
|
+
- "已更新 layout-spec.md zones 坐标"
|
|
37
|
+
- "PM 裁决:以故事板为准,layout-spec 将修正"
|
|
38
|
+
- "双方同意保持现状,偏差在可接受范围"
|
|
39
|
+
-->
|
|
40
|
+
|
|
41
|
+
## Metrics
|
|
42
|
+
|
|
43
|
+
| Metric | Value |
|
|
44
|
+
| ---------------------- | --------- |
|
|
45
|
+
| Total questions raised | {{count}} |
|
|
46
|
+
| Unresolved | {{count}} |
|
|
47
|
+
| By Designer | {{count}} |
|
|
48
|
+
| By TA | {{count}} |
|
|
49
|
+
| By Developer | {{count}} |
|
|
50
|
+
| By PM | {{count}} |
|
|
51
|
+
| By Reviewer | {{count}} |
|
|
52
|
+
|
|
53
|
+
<!--
|
|
54
|
+
PM monitors this table:
|
|
55
|
+
- If single Agent receives >3 questions → intent transmission fault, record in DAG Revisions
|
|
56
|
+
- If unresolved >3 at any time → PM must intervene and assign priority
|
|
57
|
+
- If Reviewer finds unresolved questions at review stage → deduct Intent Transmission score
|
|
58
|
+
-->
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Layout Spec
|
|
2
|
+
|
|
3
|
+
<!--
|
|
4
|
+
PM owns paths + specs (Gate #1 lock). CONTRACT only — zones, palette ids, assetMapping, atlas table, WxH/format.
|
|
5
|
+
Do NOT add: storyboard prose, Style Intent Notes, TA logs (→ designer-log / ta-log).
|
|
6
|
+
-->
|
|
7
|
+
|
|
8
|
+
> Shared contract between Designer, TA, and Developer. All MUST follow this document.
|
|
9
|
+
|
|
10
|
+
## Screen
|
|
11
|
+
|
|
12
|
+
- Orientation: {{portrait/landscape}}
|
|
13
|
+
- Resolution: {{width}} x {{height}}
|
|
14
|
+
- Safe area: top {{top_safe}}px, bottom {{bottom_safe}}px
|
|
15
|
+
|
|
16
|
+
## Zones
|
|
17
|
+
|
|
18
|
+
| id | role | rect (x, y, w, h) | owner |
|
|
19
|
+
| ----------- | ------------- | -------------------------- | --------------------------- |
|
|
20
|
+
| {{zone_id}} | {{zone_role}} | {{x}}, {{y}}, {{w}}, {{h}} | {{Designer/Developer/both}} |
|
|
21
|
+
|
|
22
|
+
<!--
|
|
23
|
+
Add one row per zone. Common zones:
|
|
24
|
+
- header: HUD (score/progress), usually at top
|
|
25
|
+
- board: Main game area (grid/play field)
|
|
26
|
+
- footer: Extended background area
|
|
27
|
+
- endcard: CTA region, usually at bottom
|
|
28
|
+
|
|
29
|
+
ASCII diagram (update to match your zones):
|
|
30
|
+
┌─────────────────────────┐ y=0
|
|
31
|
+
│ {{zone_1}} │ {{h1}}px
|
|
32
|
+
├─────────────────────────┤
|
|
33
|
+
│ {{zone_2}} │ {{h2}}px
|
|
34
|
+
├─────────────────────────┤
|
|
35
|
+
│ {{zone_3}} │ {{h3}}px
|
|
36
|
+
└─────────────────────────┘
|
|
37
|
+
-->
|
|
38
|
+
|
|
39
|
+
## Color Palette
|
|
40
|
+
|
|
41
|
+
### Element Colors
|
|
42
|
+
|
|
43
|
+
| id | hex | label |
|
|
44
|
+
| -------------- | ------------- | ---------------- |
|
|
45
|
+
| {{element_id}} | {{hex_color}} | {{display_name}} |
|
|
46
|
+
|
|
47
|
+
<!--
|
|
48
|
+
- Element IDs are used by Developer in PGS config
|
|
49
|
+
- Hex colors guide Designer's generation prompts
|
|
50
|
+
- Labels are human-readable names for the elements
|
|
51
|
+
- Typically 4-6 elements for a playable ad
|
|
52
|
+
-->
|
|
53
|
+
|
|
54
|
+
### Other Colors
|
|
55
|
+
|
|
56
|
+
- Background: primary `{{bg_primary_hex}}`, secondary `{{bg_secondary_hex}}`
|
|
57
|
+
- UI: text `{{ui_text_hex}}`, accent `{{ui_accent_hex}}`
|
|
58
|
+
|
|
59
|
+
## Asset Spec
|
|
60
|
+
|
|
61
|
+
| Type | Dimensions | Format |
|
|
62
|
+
| --------------- | --------------------- | ------ |
|
|
63
|
+
| tileSize | {{tile_w}}x{{tile_h}} | webp |
|
|
64
|
+
| backgroundSize | {{bg_w}}x{{bg_h}} | webp |
|
|
65
|
+
| iconSize | {{icon_w}}x{{icon_h}} | webp |
|
|
66
|
+
| audio (BGM/SFX) | — | mp3 |
|
|
67
|
+
|
|
68
|
+
<!--
|
|
69
|
+
Default runtime formats: images WebP, audio MP3. TA delivers atlas groups as .webp + .json sidecar.
|
|
70
|
+
-->
|
|
71
|
+
|
|
72
|
+
## Atlas grouping (Gate #1 — PM defines)
|
|
73
|
+
|
|
74
|
+
| groupId | elementIds | atlasPath | sidecarPath |
|
|
75
|
+
| ------- | ---------------- | ------------------------------------ | ------------------------------------ |
|
|
76
|
+
| tiles | {{id1}}, {{id2}} | assets/images/tiles/tiles_atlas.webp | assets/images/tiles/tiles_atlas.json |
|
|
77
|
+
| ui | {{id3}}, {{id4}} | assets/images/ui/ui_atlas.webp | assets/images/ui/ui_atlas.json |
|
|
78
|
+
|
|
79
|
+
<!--
|
|
80
|
+
Rules: ≥2 elements in same logical class (tiles / ui / vfx) → ONE webp+json atlas.
|
|
81
|
+
Single large assets (full-screen bg) → one webp path only. Digit strip → separate webp (see Text Assets).
|
|
82
|
+
Each elementId in assetMapping uses atlasPath + frameId OR single visualAsset path.
|
|
83
|
+
-->
|
|
84
|
+
|
|
85
|
+
## Asset Mapping
|
|
86
|
+
|
|
87
|
+
| elementId | visualAsset / atlas | frameId | sfx |
|
|
88
|
+
| -------------- | ------------------------------------- | ------- | ------------------------------------- |
|
|
89
|
+
| {{element_id}} | assets/images/tiles/tiles_atlas.webp | tile_01 | {{sfx_path_or_dash}} |
|
|
90
|
+
| — | assets/images/bg/{{bg_filename}}.webp | — | — |
|
|
91
|
+
| — | — | — | assets/audio/sfx/{{sfx_filename}}.mp3 |
|
|
92
|
+
| — | — | — | assets/audio/bgm/{{bgm_filename}}.mp3 |
|
|
93
|
+
|
|
94
|
+
<!--
|
|
95
|
+
CRITICAL: This mapping is the integration contract!
|
|
96
|
+
- Designer saves files at EXACTLY these paths
|
|
97
|
+
- Developer references EXACTLY these paths in code
|
|
98
|
+
- Path mismatch = integration failure
|
|
99
|
+
- Use "—" for cells that don't apply
|
|
100
|
+
-->
|
|
101
|
+
|
|
102
|
+
## Text Assets
|
|
103
|
+
|
|
104
|
+
All visible text is rendered as image assets — no font files in the final build.
|
|
105
|
+
|
|
106
|
+
### Static Text (baked into Master Composite concept panel)
|
|
107
|
+
|
|
108
|
+
| id | text content | asset path | notes |
|
|
109
|
+
| ----------- | --------------- | --------------------------------------- | ------------------------ |
|
|
110
|
+
| {{text_id}} | {{text_string}} | assets/images/ui/{{text_filename}}.webp | TA extracts from concept |
|
|
111
|
+
|
|
112
|
+
<!--
|
|
113
|
+
Common static text: game title, CTA button label, tutorial instructions, "YOU WIN", stage labels.
|
|
114
|
+
Designer includes all static text in the Master Composite concept panel.
|
|
115
|
+
TA extracts each text element using segment and saves to the specified path.
|
|
116
|
+
-->
|
|
117
|
+
|
|
118
|
+
### Digit Sprite Strip (for dynamic numbers)
|
|
119
|
+
|
|
120
|
+
- **Characters**: `{{digit_characters}}`
|
|
121
|
+
- **Cell size**: {{cell_w}}x{{cell_h}}
|
|
122
|
+
- **Asset path**: `assets/images/ui/digits.webp`
|
|
123
|
+
|
|
124
|
+
<!--
|
|
125
|
+
PM defines the character set based on what dynamic text the game needs.
|
|
126
|
+
Common sets:
|
|
127
|
+
- Score only: "0123456789"
|
|
128
|
+
- Score + timer: "0123456789:."
|
|
129
|
+
- Score + multiplier: "0123456789x+,."
|
|
130
|
+
Designer generates a single horizontal strip image with all characters in order.
|
|
131
|
+
Developer slices by character index at runtime (char_x = index * cell_w).
|
|
132
|
+
-->
|