@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.
Files changed (121) hide show
  1. package/README.md +66 -3
  2. package/dist/atom-plan/validate-atom-plan.js +298 -0
  3. package/dist/cli-root-help.js +1 -1
  4. package/dist/commands/3d.js +363 -0
  5. package/dist/commands/create.js +337 -0
  6. package/dist/commands/fix-ids.js +17 -3
  7. package/dist/commands/fix-ids.test.js +264 -0
  8. package/dist/commands/image.js +1337 -43
  9. package/dist/commands/login.js +60 -2
  10. package/dist/commands/recommend.js +1 -1
  11. package/dist/commands/remix.js +213 -0
  12. package/dist/commands/skills.js +1379 -0
  13. package/dist/commands/tools-3d.js +473 -0
  14. package/dist/commands/tools-generation.js +454 -0
  15. package/dist/commands/tools-project.js +400 -0
  16. package/dist/commands/tools-research.js +37 -0
  17. package/dist/commands/tools-research.test.js +216 -0
  18. package/dist/commands/tools-utils.js +164 -0
  19. package/dist/commands/tools.js +7 -616
  20. package/dist/config.js +2 -0
  21. package/dist/index.js +20 -2
  22. package/dist/utils/agent-api-client.js +52 -16
  23. package/package.json +9 -3
  24. package/project-template/.claude/agents/designer.md +116 -0
  25. package/project-template/.claude/agents/developer.md +133 -0
  26. package/project-template/.claude/agents/pm.md +164 -0
  27. package/project-template/.claude/agents/refs/README.md +67 -0
  28. package/project-template/.claude/agents/refs/designer-art-style-catalog.md +533 -0
  29. package/project-template/.claude/agents/refs/designer-color-audio-recipes.md +153 -0
  30. package/project-template/.claude/agents/refs/designer-deliverable-spec.md +167 -0
  31. package/project-template/.claude/agents/refs/designer-dimension-axis.md +27 -0
  32. package/project-template/.claude/agents/refs/designer-handoff-v2-checklist.md +68 -0
  33. package/project-template/.claude/agents/refs/designer-master-composite-recipes.md +216 -0
  34. package/project-template/.claude/agents/refs/designer-style-exploration-flow.md +37 -0
  35. package/project-template/.claude/agents/refs/developer-dev-handoff.md +109 -0
  36. package/project-template/.claude/agents/refs/developer-impl-cookbook.md +134 -0
  37. package/project-template/.claude/agents/refs/developer-phase1-flow.md +211 -0
  38. package/project-template/.claude/agents/refs/pm-workflow-detail.md +545 -0
  39. package/project-template/.claude/agents/refs/reviewer-six-dimension-eval.md +286 -0
  40. package/project-template/.claude/agents/refs/ta-3d-flip-recipe.md +85 -0
  41. package/project-template/.claude/agents/refs/ta-atlas-deliverable-standard.md +46 -0
  42. package/project-template/.claude/agents/refs/ta-batch-pipeline-recipes.md +120 -0
  43. package/project-template/.claude/agents/refs/ta-image-generation-detail.md +356 -0
  44. package/project-template/.claude/agents/refs/ta-image-ops-reference.md +495 -0
  45. package/project-template/.claude/agents/refs/ta-pipeline-cookbook.md +699 -0
  46. package/project-template/.claude/agents/refs/ta-tools-reference.md +111 -0
  47. package/project-template/.claude/agents/refs/ta-vfx-preset-catalog.md +365 -0
  48. package/project-template/.claude/agents/reviewer.md +103 -0
  49. package/project-template/.claude/agents/technical-artist.md +111 -0
  50. package/project-template/.claude/hooks/README.md +36 -0
  51. package/project-template/.claude/hooks/validate-atom-plan.mjs +224 -0
  52. package/project-template/.claude/hooks/validate-workflow-stop.mjs +258 -0
  53. package/project-template/.claude/settings.json +32 -0
  54. package/project-template/.claude/settings.local.json +4 -0
  55. package/project-template/.claude/skills/playcraft-ad-psychology/SKILL.md +182 -0
  56. package/project-template/.claude/skills/playcraft-art-style-guide/SKILL.md +123 -0
  57. package/project-template/.claude/skills/playcraft-asset-state-sheet/SKILL.md +141 -0
  58. package/project-template/.claude/skills/playcraft-audio-generation/SKILL.md +280 -0
  59. package/project-template/.claude/skills/playcraft-batch-pipeline/SKILL.md +184 -0
  60. package/project-template/.claude/skills/playcraft-build-optimizer/SKILL.md +306 -0
  61. package/project-template/.claude/skills/playcraft-image-generation/SKILL.md +229 -0
  62. package/project-template/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs +123 -0
  63. package/project-template/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs +254 -0
  64. package/project-template/.claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs +235 -0
  65. package/project-template/.claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs +97 -0
  66. package/project-template/.claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs +118 -0
  67. package/project-template/.claude/skills/playcraft-image-generation/reference/process-batch.template.mjs +137 -0
  68. package/project-template/.claude/skills/playcraft-image-generation/reference/prompt-cookbook.md +397 -0
  69. package/project-template/.claude/skills/playcraft-image-generation/reference/validate-sprite-sheet.template.mjs +296 -0
  70. package/project-template/.claude/skills/playcraft-image-ops/SKILL.md +122 -0
  71. package/project-template/.claude/skills/playcraft-masking/SKILL.md +373 -0
  72. package/project-template/.claude/skills/playcraft-research/SKILL.md +212 -0
  73. package/project-template/.claude/skills/playcraft-sprite-generation/SKILL.md +423 -0
  74. package/project-template/.claude/skills/playcraft-storyboard/SKILL.md +148 -0
  75. package/project-template/.claude/skills/playcraft-style-qa/SKILL.md +270 -0
  76. package/project-template/.claude/skills/playcraft-text-rendering/SKILL.md +236 -0
  77. package/project-template/.claude/skills/playcraft-vfx-animation/SKILL.md +130 -0
  78. package/project-template/.claude/skills/playcraft-workflow/SKILL.md +396 -0
  79. package/project-template/.cursor/hooks.json +17 -0
  80. package/project-template/.cursor/rules/playcraft-orchestrator.mdc +87 -0
  81. package/project-template/.cursor/rules/playcraft-subagent-boundary.mdc +18 -0
  82. package/project-template/CLAUDE.md +240 -0
  83. package/project-template/assets/audio/bgm/.gitkeep +0 -0
  84. package/project-template/assets/audio/sfx/.gitkeep +0 -0
  85. package/project-template/assets/bundles/.gitkeep +0 -0
  86. package/project-template/assets/images/bg/.gitkeep +0 -0
  87. package/project-template/assets/images/reference/.gitkeep +0 -0
  88. package/project-template/assets/images/storyboard/.gitkeep +0 -0
  89. package/project-template/assets/images/tiles/.gitkeep +0 -0
  90. package/project-template/assets/images/ui/.gitkeep +0 -0
  91. package/project-template/assets/images/vfx/.gitkeep +0 -0
  92. package/project-template/assets/models/.gitkeep +0 -0
  93. package/project-template/docs/team/agent-conduct.md +105 -0
  94. package/project-template/docs/team/agent-runtime-matrix.md +62 -0
  95. package/project-template/docs/team/atom-plan-format.md +74 -0
  96. package/project-template/docs/team/collaboration.md +288 -0
  97. package/project-template/docs/team/core-model.md +50 -0
  98. package/project-template/docs/team/platform-capabilities.md +15 -0
  99. package/project-template/docs/team/workflow-changelog.md +51 -0
  100. package/project-template/docs/team/workflow-consistency-checklist.md +128 -0
  101. package/project-template/game/config/.gitkeep +0 -0
  102. package/project-template/game/gameplay/.gitkeep +0 -0
  103. package/project-template/game/scenes/.gitkeep +0 -0
  104. package/project-template/logs/.gitkeep +0 -0
  105. package/project-template/ta-workspace/logs/.gitkeep +0 -0
  106. package/project-template/ta-workspace/scripts/.gitkeep +0 -0
  107. package/project-template/ta-workspace/tmp/.gitkeep +0 -0
  108. package/project-template/templates/atom-plan.template.json +26 -0
  109. package/project-template/templates/atom-plan.template.md +76 -0
  110. package/project-template/templates/design-brief.template.md +195 -0
  111. package/project-template/templates/design-lens-checklist.reference.md +117 -0
  112. package/project-template/templates/design-methodology.md +99 -0
  113. package/project-template/templates/designer-log.template.md +98 -0
  114. package/project-template/templates/developer-log.template.md +140 -0
  115. package/project-template/templates/five-axis-framework.md +186 -0
  116. package/project-template/templates/intent-clarifications.template.md +58 -0
  117. package/project-template/templates/layout-spec.template.md +132 -0
  118. package/project-template/templates/project-state.template.md +219 -0
  119. package/project-template/templates/review-report.template.md +166 -0
  120. package/project-template/templates/style-exploration.template.md +93 -0
  121. package/project-template/templates/ta-log.template.md +205 -0
@@ -0,0 +1,182 @@
1
+ ---
2
+ name: playcraft-ad-psychology
3
+ description: 可玩广告心理设计指南。涵盖四大心理钩子(好奇心缺口/FOMO/即时满足/进度错觉)、60-30-10 色彩法则、CTA 设计规范、各阶段情感设计目标与常见错误。按游戏类型配色方案和音频情绪弧参数见 refs/designer-color-audio-recipes.md。
4
+ triggers: 广告心理,ad psychology,钩子,hook设计,FOMO,近胜,near-win,CTA设计,色彩法则,60-30-10,颜色策略,配色方案,情感弧,emotional arc,安装率,CTR,转化率,EndCard设计,进度条设计,游戏广告设计
5
+ ---
6
+
7
+ # 可玩广告心理设计完整指南
8
+
9
+ ## 0. 核心认知:优化目标是 CTR,不是游戏时长
10
+
11
+ **最重要的一句话**:可玩广告的成功指标是**安装点击率(CTR > 3%)**,不是玩家在广告内的游戏时长或互动率。
12
+
13
+ 这意味着:
14
+
15
+ - EndCard 不应该是"胜利满足感",而应该是"还没玩够"
16
+ - Tutorial 的目标不是让玩家学会玩,而是让玩家感到"我可以玩"
17
+ - Gameplay 不需要公平,需要的是让玩家觉得"再给我一次机会"
18
+ - 每一帧设计都要服务于最终的 CTA 点击
19
+
20
+ ---
21
+
22
+ ## 1. 四大心理钩子
23
+
24
+ ### 钩子 1:好奇心缺口(Curiosity Gap)
25
+
26
+ **心理原理**:人脑对"未完成"状态有强烈的认知驱动——看到一个悬而未决的问题,大脑会持续寻求解答。
27
+
28
+ **视觉设计指令**:
29
+
30
+ - Near-Win 状态:关键元素差一步就能达成(最后一块砖、差 1 颗星、进度条 95%)
31
+ - 不展示解法:只给出问题和"差一点"的状态,**不给解答**
32
+ - 制造张力:用视觉聚焦(模糊背景、高亮关键元素)引导注意力到未解决点
33
+
34
+ **Prompt 关键词**:`near win moment`, `almost there`, `one step away`, `progress bar at 95%`, `last piece missing`, `unresolved puzzle state`
35
+
36
+ **错误做法**:在 Gameplay 帧展示"已解决"的完美状态(会消除好奇心,减少安装动机)
37
+
38
+ ---
39
+
40
+ ### 钩子 2:FOMO + 损失厌恶(Fear of Missing Out)
41
+
42
+ **心理原理**:人对"失去"的感受比对"获得"的感受强 2 倍(Kahneman 损失厌恶理论)。
43
+
44
+ **视觉设计指令**:
45
+
46
+ - EndCard 展示"未拿到的奖励":宝箱半开、金币散落地面、奖励图标模糊显示
47
+ - 不展示胜利:不要"恭喜通关"、不要奖励动画播放完毕的满足状态
48
+ - 制造"差一步就错过"感:宝箱即将关闭、计时器快到零、稀有道具即将消失
49
+
50
+ **Prompt 关键词**:`treasure chest half open`, `rewards about to expire`, `coins scattered uncollected`, `rare item visible but unreachable`, `countdown almost zero`, `last chance visual`
51
+
52
+ **EndCard 设计原则**:
53
+
54
+ 1. 主视觉 = 最有价值的游戏内奖励(大宝箱/稀有角色/大金币堆)
55
+ 2. 这些奖励处于"触手可及但尚未到手"的状态
56
+ 3. CTA 按钮 = 唯一能拿到这些奖励的路径
57
+
58
+ ---
59
+
60
+ ### 钩子 3:即时满足(Instant Gratification)
61
+
62
+ **心理原理**:人类偏好立即的小奖励胜过未来的大奖励。Tutorial 阶段的核心任务是让玩家在 3-5 秒内体验到"做对了"的反馈。
63
+
64
+ **视觉设计指令**:
65
+
66
+ - Tutorial 帧必须"一眼看懂":画面信息密度最低(只显示 1-2 个可交互元素)
67
+ - 手势引导要大而清晰:手指点击图标 / 虚线箭头 / 高亮光圈,尺寸不小于元素的 1.5 倍
68
+ - 交互结果要夸张:正确操作的视觉反馈(爆炸、星星、得分)要比实际游戏中更夸张
69
+ - 色温略暖:相比 Hook 帧,Tutorial 帧整体色温偏暖,降低压迫感
70
+
71
+ **Prompt 关键词**:`large finger tap indicator`, `glowing highlight around target`, `bright tutorial arrow`, `warm color temperature`, `simplified single element focus`, `satisfying immediate feedback animation`
72
+
73
+ **Tutorial 禁忌**:
74
+
75
+ - 不要出现文字说明(玩家不读广告里的文字)
76
+ - 不要出现超过 3 个可交互元素(信息过载)
77
+ - 不要让 Tutorial 让玩家失败(第一次操作必须成功)
78
+
79
+ ---
80
+
81
+ ### 钩子 4:进度错觉(Progress Illusion)
82
+
83
+ **心理原理**:看到已完成的进度会激励继续完成,人们对"快完成了"比对"刚开始"更有动力。
84
+
85
+ **视觉设计指令**:
86
+
87
+ - 进度条设计在 75-90% 满格状态(而不是 0% 或 50%)
88
+ - 血条/能量条接近满格但不满(如 85%)
89
+ - 积分显示接近整数关卡(如 "980/1000" 而不是 "100/1000")
90
+ - 成就/收集类:显示"5/6 已收集"而不是"收集了 5 个"
91
+
92
+ **Prompt 关键词**:`progress bar 80% full`, `health bar nearly complete`, `score counter almost at milestone`, `collection 5 of 6 complete`, `achievement nearly unlocked`
93
+
94
+ ---
95
+
96
+ ## 2. 各阶段情感设计目标
97
+
98
+ | 阶段 | 时段 | 情感目标 | 关键视觉指标 |
99
+ | ------------ | ------ | ----------- | ---------------------------------- |
100
+ | **Hook** | 0–3s | 震撼 + 好奇 | 最高对比度,最大动感,主视觉冲击 |
101
+ | **Tutorial** | 3–10s | 安全 + 自信 | 最低信息密度,暖色调,大手势图标 |
102
+ | **Gameplay** | 10–25s | 沉浸 + 紧张 | 进度错觉,Near-Win,最高信息密度 |
103
+ | **EndCard** | 25–30s | 遗憾 + 渴望 | 奖励可见但未得,CTA 高对比,未竟感 |
104
+
105
+ ---
106
+
107
+ ## 3. 60-30-10 色彩法则(可玩广告版)
108
+
109
+ ### 三色分配
110
+
111
+ ```
112
+ 总画面配色 = 60% 主色(背景/场景) + 30% 辅色(游戏主元素) + 10% 强调色(CTA专用)
113
+ ```
114
+
115
+ **"对比稀缺性"原则**:强调色(10%)只出现在 CTA 按钮上时,玩家视线会被自动吸引到 CTA——强调色越少出现在其他地方,CTA 的吸引力越强。
116
+
117
+ **违规示例**:在游戏元素上大量使用橙色,然后 CTA 按钮也用橙色 → CTA 消失在视觉噪音中。
118
+
119
+ **正确示例**:游戏用蓝绿主色调,只有 CTA 按钮使用金橙色 → CTA 一眼突出。
120
+
121
+ ## 4. CTA 设计规范
122
+
123
+ ### 尺寸与位置
124
+
125
+ | 规范项 | 要求 | 原因 |
126
+ | ------------ | -------------------------- | -------------------------------- |
127
+ | 最小点击区域 | 48×48 px(设备物理像素) | 手指触控目标尺寸,防止误触 |
128
+ | 距屏幕边缘 | ≥ 48 px | 防止被平台 UI 遮挡,避免误触边框 |
129
+ | 视觉建议尺寸 | 200–400 px 宽(9:16 屏幕) | 足够显眼但不干扰游戏区域 |
130
+ | 位置 | 底部 1/4 区域,水平居中 | 符合拇指操作习惯 |
131
+
132
+ ### 对比度规范
133
+
134
+ CTA 按钮与其背景的对比度必须 **≥ 4.5:1**(WCAG AA 标准)。
135
+
136
+ ```
137
+ 常见合规组合(按钮色/背景色):
138
+ - 金橙 #F5A623 / 深蓝 #0D1B2A → 对比度 ~8.5:1 ✅
139
+ - 纯白 #FFFFFF / 主色按钮 → 白色文字在深色按钮上 ✅
140
+ - 鲜绿 #00C851 / 深灰 #222222 → 对比度 ~6.2:1 ✅
141
+ - 浅黄 #FFFF99 / 白色背景 → 对比度 ~1.2:1 ❌(不合规)
142
+ ```
143
+
144
+ 快速验证工具:告诉 Designer 用 `playcraft tools research --query "color contrast checker [color1] vs [color2]"` 快速查询。
145
+
146
+ ### 文案优先级
147
+
148
+ | 优先级 | 文案 | 适用场景 |
149
+ | --------- | -------------- | ------------------------- |
150
+ | 1(最优) | `Play Now` | 休闲/消除游戏(情感驱动) |
151
+ | 2 | `Install Free` | 强调免费降低决策成本 |
152
+ | 3 | `Download` | 通用,略弱于上两者 |
153
+ | 4(避免) | `Click Here` | 无情感引导,降低 CTR |
154
+
155
+ **Google Ads 限制**:不可将 "Download" 或 "Install" 文字**直接叠加在图片上**(会被审核拒绝)。应将文案放在按钮内的独立颜色区域。
156
+
157
+ ### CTA 动画建议
158
+
159
+ - 使用 `pulse` 动画(参考 `playcraft-vfx-animation` Skill)引导注意力
160
+ - 脉冲频率:1.5-2 秒一次(过快令人烦躁,过慢不引人注意)
161
+ - 第一次脉冲时机:EndCard 出现后 0.5 秒开始
162
+
163
+ ---
164
+
165
+ ## 5. 常见设计错误
166
+
167
+ | 错误 | 原因 | 正确做法 |
168
+ | -------------------------- | ----------------------------------------- | -------------------------------- |
169
+ | EndCard 展示胜利/满足状态 | 消除了 FOMO,玩家觉得"看完了,不用下载了" | 展示"差一步"的遗憾状态 |
170
+ | Tutorial 有文字说明 | 玩家不读广告文字 | 用图形化引导(手势图标/箭头) |
171
+ | CTA 颜色与游戏主色相同 | 对比稀缺性失效,CTA 不显眼 | CTA 用画面中唯一一种高对比强调色 |
172
+ | Gameplay 展示玩家失败 | 让玩家觉得游戏太难,不想下载 | 展示"即将成功"的 Near-Win 状态 |
173
+ | Hook 超过 3 秒才出现主视觉 | 用户已划走 | 0 帧就要高对比主视觉,无过渡铺垫 |
174
+ | 信息密度全帧均等 | 视觉无重点,注意力分散 | 每帧只有一个视觉焦点 |
175
+
176
+ ---
177
+
178
+ ## 6. 按游戏类型配色方案与音频情绪弧
179
+
180
+ 按游戏类型的配色方案(休闲消除、策略战争、益智解谜、RPG 奇幻,含 hex 值与情感定位)和完整音频情绪弧设计参数(BGM 各阶段 BPM、垂直重编排、SFX 时长标准、音频-视觉对齐检查清单):
181
+
182
+ 详见 `refs/designer-color-audio-recipes.md`。
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: playcraft-art-style-guide
3
+ description: 可玩广告美术风格选择与应用指南。涵盖 9 种主流风格的视觉特征、选型决策树(按游戏类型/受众/品牌调性)、风格对生产流水线的影响、以及各风格的 prompt 核心策略。Designer 在 Phase 1 确定美术方向前必读。
4
+ triggers: 美术风格,art style,像素风,pixel art,写实,realistic,卡通,cartoon,扁平,flat,科技风,tech,科幻,sci-fi,赛博朋克,cyberpunk,奇幻,fantasy,中国风,chinese,水彩,watercolor,手绘,Q版,chibi,风格选择,style direction,视觉风格
5
+ ---
6
+
7
+ # PlayCraft 美术风格选择与应用指南
8
+
9
+ ## 0. 风格选择的设计思考
10
+
11
+ 美术风格不是"好看就行"——它直接影响:
12
+
13
+ - **CTR 表现**:风格与目标受众的审美期待是否匹配
14
+ - **生产成本**:不同风格对 AI 生图质量要求和后处理复杂度差异极大
15
+ - **文件体积**:像素风天然小,写实风天然大——直接影响 5MB 预算分配
16
+ - **TA 管线**:像素风需要整数倍缩放 + 限色板;写实风需要高分辨率 + 精细抠图
17
+
18
+ **风格决策时机**:PM 在 `design-brief.md` 的 StyleDirection 中定义方向,Designer 在 Phase 1 具体化并生成样本验证。
19
+
20
+ ---
21
+
22
+ ## 1. 风格选型决策树
23
+
24
+ ```
25
+ 游戏类型 + 目标受众?
26
+
27
+ ├─ 休闲消除/益智 + 全年龄
28
+ │ ├─ 追求高辨识度/IP感 → Q版/Chibi
29
+ │ ├─ 追求简洁现代 → 扁平卡通
30
+ │ └─ 追求怀旧/独特 → 像素风
31
+
32
+ ├─ 卡牌/棋牌/麻将 + 成年用户
33
+ │ ├─ 中国市场 → 中国传统风
34
+ │ ├─ 全球市场/高端感 → 写实/半写实
35
+ │ └─ 年轻用户/轻量感 → 扁平卡通
36
+
37
+ ├─ 动作/射击/跑酷 + 年轻男性
38
+ │ ├─ 现代/都市 → 赛博朋克/科技风
39
+ │ ├─ 太空/未来 → 科幻风
40
+ │ └─ 魔法/剑与盾 → 奇幻风
41
+
42
+ ├─ 模拟经营/养成 + 女性/全年龄
43
+ │ ├─ 追求温暖治愈 → 水彩/手绘
44
+ │ ├─ 追求可爱萌系 → Q版/Chibi
45
+ │ └─ 追求清新文艺 → 扁平卡通
46
+
47
+ └─ RPG/冒险 + 核心玩家
48
+ ├─ 西方奇幻 → 奇幻风
49
+ ├─ 东方仙侠 → 中国传统风
50
+ └─ 暗黑/硬核 → 写实/半写实
51
+ ```
52
+
53
+ ---
54
+
55
+ ## 2. 九种风格速览
56
+
57
+ | # | 风格 | 视觉特征 | 体积倾向 | AI 生图难度 | 最佳模型 |
58
+ | --- | ------------------- | ------------------------------------ | -------- | ---------------- | -------------------- |
59
+ | 1 | **像素风** | 方块化、限色板(8-32色)、无抗锯齿 | 极小 | 中(需严格限色) | gpt-image-2 |
60
+ | 2 | **扁平卡通** | 粗描边、纯色填充、几何化、无渐变阴影 | 小 | 低 | 任意模型 |
61
+ | 3 | **Q版/Chibi** | 大头身比(2-3头)、圆润形状、夸张表情 | 小-中 | 低 | 任意模型 |
62
+ | 4 | **写实/半写实** | 真实光影、材质细节、自然比例 | 大 | 高(细节要求高) | gpt-image-2 |
63
+ | 5 | **中国传统风** | 水墨笔触、留白、金色装饰、书法元素 | 中 | 中(需文化细节) | gpt-image-2 |
64
+ | 6 | **赛博朋克/科技风** | 霓虹光、暗底、几何线条、HUD 叠加 | 中 | 中 | gpt-image-2 / gemini |
65
+ | 7 | **科幻风** | 金属质感、星空、全息UI、冷色调 | 中 | 中 | gpt-image-2 |
66
+ | 8 | **奇幻/魔法** | 发光粒子、魔法阵、饱和色彩、神秘光 | 中-大 | 中 | gpt-image-2 |
67
+ | 9 | **水彩/手绘** | 纸质纹理、渗透感、不规则边缘、柔和 | 中 | 中(边缘控制难) | gpt-image-2 |
68
+
69
+ ---
70
+
71
+ ## 3. 风格对 TA 管线的影响
72
+
73
+ | 风格 | 缩放策略 | 抠图难度 | VFX 适配 | 特殊注意 |
74
+ | ----------- | ------------------------------------- | ----------------- | ------------------------ | ------------------------------- |
75
+ | 像素风 | 整数倍(`--scale 2/4/8`),禁止分数缩放 | 低(硬边) | `pixelate` 后 VFX | 缩放后禁用抗锯齿 |
76
+ | 扁平卡通 | 任意缩放 | 低(粗描边清晰) | 所有 VFX 兼容 | 描边粗细要统一 |
77
+ | Q版/Chibi | 任意缩放 | 低-中 | 所有 VFX 兼容 | 头身比一致性 |
78
+ | 写实/半写实 | 只降不升(原图需高分辨率) | 高(毛发/半透明) | 写实 VFX 慎用卡通预设 | 需 AI 去背(--method ai) |
79
+ | 中国传统风 | 任意缩放 | 中(水墨渐变边) | glow/sparkle 适合 | 文字必须楷体/行书 |
80
+ | 赛博朋克 | 任意缩放 | 中(发光溢出) | glow/starburst 适合 | 发光边缘保留,不要过度 trim |
81
+ | 科幻风 | 任意缩放 | 中 | glow/impact_ring 适合 | 金属质感需 reference-image 锁定 |
82
+ | 奇幻/魔法 | 任意缩放 | 中(魔法粒子) | sparkle/glow/starburst | 粒子效果保留半透明 |
83
+ | 水彩/手绘 | 任意缩放 | 高(不规则边缘) | 慎用——VFX 可能破坏手绘感 | trim threshold 要高(30+) |
84
+
85
+ ---
86
+
87
+ ## 4. Prompt 核心策略(按风格)
88
+
89
+ 每种风格的 prompt 都遵循公式:`[主体] + [风格关键词] + [技术约束] + [负面约束]`
90
+
91
+ | 风格 | 核心关键词 | 必加约束 | 必加负面 |
92
+ | --------- | ------------------------------------------------------------------------------ | ----------------------- | ----------------------------------------------------- |
93
+ | 像素风 | `pixel art, 8-bit, limited N-color palette, sharp pixels, no anti-aliasing` | 指定色板数量 | `no smooth gradients, no anti-aliasing, no blur` |
94
+ | 扁平卡通 | `flat 2D vector, bold outlines, solid color fills, minimal shading` | 描边粗细(如 3px) | `no gradient, no 3D effect, no realistic shading` |
95
+ | Q版/Chibi | `chibi style, cute, 2.5-head proportion, round shapes, big eyes` | 头身比 | `no realistic proportion, no thin limbs` |
96
+ | 写实 | `photorealistic, detailed textures, natural lighting, high resolution` | 光源方向 | `no cartoon, no flat color, no cel-shading` |
97
+ | 中国传统 | `Chinese traditional ink painting, brush strokes, elegant, gold accents` | 留白比例 | `no western fantasy, no neon, no modern UI` |
98
+ | 赛博朋克 | `cyberpunk, neon glow, dark background, holographic, circuit patterns` | 发光色(如 cyan/magenta) | `no nature, no warm colors, no daylight` |
99
+ | 科幻 | `sci-fi, metallic surfaces, space, holographic UI, cold blue lighting` | 材质(金属/玻璃) | `no organic textures, no warm wood, no fantasy magic` |
100
+ | 奇幻 | `fantasy art, magical glow, ethereal, mystical atmosphere, rich colors` | 光源类型(魔法光) | `no modern technology, no sci-fi, no urban` |
101
+ | 水彩 | `watercolor painting, soft edges, paper texture, transparent washes, artistic` | 纸张纹理 | `no hard edges, no digital look, no sharp outlines` |
102
+
103
+ ---
104
+
105
+ ## 5. 风格一致性检查点
106
+
107
+ 生成样本后,对照以下维度确认风格执行是否到位:
108
+
109
+ | 维度 | 检查方法 | 不通过时调整 |
110
+ | -------- | ---------------------------- | ------------------------ |
111
+ | **色板** | 肉眼对比概念图主色 | prompt 加具体 hex 值 |
112
+ | **描边** | 放大看边缘处理 | 加/减 `bold outline Npx` |
113
+ | **光影** | 对比光源方向和阴影风格 | 明确光照描述 |
114
+ | **材质** | 对比表面纹理(哑光/光泽/粗糙) | 加材质修饰词 |
115
+ | **比例** | 对比元素间大小关系 | 加尺寸约束描述 |
116
+
117
+ ---
118
+
119
+ ## 6. 详细参考
120
+
121
+ 每种风格的完整 prompt 示例、模型推荐、TA 管线详细配置、常见错误与修正:
122
+
123
+ > **Read `refs/designer-art-style-catalog.md`**
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: playcraft-asset-state-sheet
3
+ description: PlayCraft 资产状态参考精灵图板(ASR / Asset State Reference Sheet)生成指南。Designer 在 Gate #2a 后输出两张 4K 参考精灵图:UI 组件状态板 + 玩法元素状态板,供 TA crop 量产。
4
+ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element state sheet,组件状态图,状态精灵图,精灵图板,参考精灵图,authoring sprite sheet,design handoff sheet,TA参考图,状态参考板,playcraft-asset-state-sheet
5
+ ---
6
+
7
+ # PlayCraft 资产状态参考精灵图板(ASR)
8
+
9
+ > **ASR** = **Asset State Reference Sheet**(资产状态参考精灵图板)
10
+ > **Authoring sprite sheet**(制作期精灵图板):单张 PNG、规则网格、每格一种状态;与 TA 产出的 **runtime atlas**(`.webp` + `.json`)不同。
11
+
12
+ ## 0. 前置条件(硬门禁)
13
+
14
+ - **仅在 Gate #2a 通过、`selectedMcOption` 已写入 `project-state.md` 之后** 才能生成 ASR
15
+ - **禁止**为未选中的 MC 方案生成 ASR
16
+ - 两张板均使用已确认 MC 作 `--reference-image`,且 `--image-model` 与 MC 一致
17
+
18
+ ## 1. 交付物:两张状态参考板
19
+
20
+ | 交付物 | 文件 | 内容 |
21
+ | --------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
22
+ | **UI State Reference Sheet** | `assets/images/reference/ui_state_sheet_[X].png` | 各 **UI/HUD 组件** 在所需交互态下的外观(非玩法棋子) |
23
+ | **Element State Reference Sheet** | `assets/images/reference/element_state_sheet_[X].png` | 各 **玩法视觉元素** 在特殊/事件态下的外观 |
24
+
25
+ `[X]` = `selectedMcOption`(A/B/C)。
26
+
27
+ ### UI State Reference Sheet — 放什么
28
+
29
+ - CTA 按钮、安装条、HUD 条、进度/分数框、手指引导、高亮框、徽章、弹窗底板等
30
+ - 每个组件占 **一个或多个相邻槽位**,每槽 **一种状态**,例如:
31
+ - `cta_install`: default | pressed | disabled
32
+ - `finger_guide`: idle | tap-down
33
+ - `highlight_frame`: off | on
34
+
35
+ ### Element State Reference Sheet — 放什么
36
+
37
+ - 棋子、牌面、角色、道具、匹配特效关键帧等(MC 概念面板里出现的玩法元素)
38
+ - 每个元素类型 **2–3 个代表状态**(完整全集由 TA 在 `production` 扩展),例如:
39
+ - `tile_gold`: idle | selected | matched
40
+ - `panda_char`: idle | happy | win
41
+
42
+ **元素总数**:每张板独立统计,每板 **8–12 个状态槽**(宁可少槽、加大间距,也不要重叠)。
43
+
44
+ ## 2. 布局策略 — 规则网格、零重叠
45
+
46
+ 1. **零重叠**:任意两格 bounding box 不得相交
47
+ 2. **网格化**:每行 3–4 槽;每槽固定矩形空白区;元素居中;四周 **≥80px** 边距
48
+ 3. **行间距 ≥120px**,**列间距 ≥100px**
49
+ 4. 禁止层叠、散落堆叠、透视干扰
50
+
51
+ ### UI 板示例布局
52
+
53
+ ```
54
+ Row 1: [CTA default] [CTA pressed] [CTA disabled] [HUD bar]
55
+ Row 2: [finger idle] [finger tap] [badge] [highlight on]
56
+ ```
57
+
58
+ ### 元素板示例布局
59
+
60
+ ```
61
+ Row 1: [tile A idle] [tile A selected] [tile A matched] [tile B idle]
62
+ Row 2: [char idle] [char happy] [char win] (empty)
63
+ ```
64
+
65
+ ## 3. Prompt 模板
66
+
67
+ **UI 板** — 在 prompt 中显式写 `UI component state reference sprite sheet`:
68
+
69
+ ```
70
+ UI component state reference sprite sheet for [GAME_TYPE] playable ad.
71
+ 3840x1152 canvas, [BG_COLOR] flat background.
72
+
73
+ STRICT LAYOUT: orthographic grid, fixed non-overlapping cells. Each UI widget state in exactly one cell, 80px margin, 100px column gap, 120px row gap. NO overlapping.
74
+
75
+ Row 1 — CTA / HUD:
76
+ - CTA install button, default state: ...
77
+ - CTA install button, pressed state: ...
78
+ ...
79
+
80
+ Art style: [SAME as Master Composite]. Front-facing UI, crisp edges, consistent lighting.
81
+ ```
82
+
83
+ **元素板** — 写 `gameplay element state reference sprite sheet`:
84
+
85
+ ```
86
+ Gameplay element state reference sprite sheet for [GAME_TYPE].
87
+ [same STRICT LAYOUT block]
88
+
89
+ Row 1 — Core tiles/items:
90
+ - [Element] idle: ...
91
+ - [Element] selected: ...
92
+ - [Element] matched: ...
93
+ ...
94
+
95
+ Art style: [SAME as Master Composite].
96
+ ```
97
+
98
+ **Prompt 必须包含**:`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素。
99
+
100
+ ## 4. 生成命令
101
+
102
+ ```bash
103
+ # UI 组件状态板
104
+ playcraft tools generate-image \
105
+ --prompt "<UI sheet prompt>" \
106
+ --output assets/images/reference/ui_state_sheet_[X].png \
107
+ --reference-image assets/images/storyboard/master_composite_option_[X].png \
108
+ --image-model <与 MC 相同> \
109
+ --aspect-ratio 16:9 \
110
+ --image-size 4K
111
+
112
+ # 玩法元素状态板
113
+ playcraft tools generate-image \
114
+ --prompt "<Element sheet prompt>" \
115
+ --output assets/images/reference/element_state_sheet_[X].png \
116
+ --reference-image assets/images/storyboard/master_composite_option_[X].png \
117
+ --image-model <与 MC 相同> \
118
+ --aspect-ratio 16:9 \
119
+ --image-size 4K
120
+ ```
121
+
122
+ ## 5. 核查清单
123
+
124
+ | # | 核查项 | 标准 |
125
+ | --- | ------ | ---------------------------------------- |
126
+ | 1 | 时机 | `selectedMcOption` 已设置 |
127
+ | 2 | 数量 | UI 板 + 元素板各一张 |
128
+ | 3 | 视觉 | 两板均无重叠;有重叠则重生成 |
129
+ | 4 | 语义 | UI 板无玩法棋子;元素板无整屏 HUD 截屏 |
130
+ | 5 | 清单 | `designer-log` 含每张板的状态→槽位映射表 |
131
+
132
+ ## 6. 与 TA 的协作协议
133
+
134
+ Designer:风格与 MC 一致;在 `designer-log.md` 标注每张 ASR **已覆盖的状态** vs **TA 需扩展的状态**。
135
+
136
+ TA 提取(详见 `playcraft-masking`):
137
+
138
+ | 来源图 | 推荐方式 | 说明 |
139
+ | -------------------- | -------------------------- | ----------------------------------------------------------------------------------- |
140
+ | **ASR**(规则网格) | `playcraft image crop` | 槽位坐标来自 `designer-log` ASR State Inventory;**禁止**对 ASR 用纯 text `segment` |
141
+ | **Master Composite** | `decompose-layers` 或 crop | ASR 未覆盖的类型从此补提取 |