@playcraft/cli 0.0.53 → 0.0.56

package/project-templates/phaser/templates/level-sketch.template.json

@@ -0,0 +1,56 @@
+{
+  "name": 1,
+  "row": 8,
+  "col": 8,
+  "levelTime": 0,
+  "trayCapacity": 7,
+  "matchCount": 3,
+  "colors": ["red", "red", "red", "blue", "blue", "blue"],
+  "arrows": [
+    [
+      [0, 0],
+      [1, 0],
+      [2, 0],
+      [3, 0],
+      [4, 0],
+      [5, 0]
+    ],
+    [
+      [7, 1],
+      [6, 1],
+      [5, 1],
+      [4, 1],
+      [3, 1],
+      [2, 1]
+    ],
+    [
+      [2, 2],
+      [2, 3],
+      [2, 4],
+      [2, 5],
+      [2, 6]
+    ],
+    [
+      [0, 7],
+      [1, 7],
+      [2, 7],
+      [3, 7],
+      [4, 7]
+    ],
+    [
+      [7, 6],
+      [6, 6],
+      [5, 6],
+      [4, 6],
+      [3, 6]
+    ],
+    [
+      [6, 3],
+      [6, 4],
+      [6, 5],
+      [5, 5],
+      [4, 5],
+      [3, 5]
+    ]
+  ]
+}

package/project-templates/phaser/templates/north-star.template.md

@@ -0,0 +1,43 @@
+# Creative North Star — {Game Name}
+
+<!--
+  Ring 1 creative discovery output (written by @creative-director).
+  @game-designer-spec copies §0 fields from this file into docs/DESIGN.md §0.
+  One-liner: verbatim. Micro-Story Spine: field-value match (trimmed per field).
+  Source: templates/north-star.template.md
+-->
+
+**Date**: {YYYY-MM-DD}
+
+---
+
+## Micro-Story Spine
+
+**Narrative level**: L1 | L2 <!-- default L1; L0 only when user explicitly opts out of story; L3 forbidden -->
+**Who**: {player identity; L0 may use n/a — pure mechanic showcase}
+**Situation**: {opening Hook frame — one glance readable scene/situation}
+**Stakes**: {what core pressure means in the player's world — not abstract game over}
+**Payoff image**: {first core payoff moment — must film a PGS beat: path slide out, fly to tray, or tray match burst}
+**Emotional arc**: {Urgency | Challenge | Competence | Curiosity | Relaxation}
+
+## One-liner
+
+{L1/L2: one vivid pitch — must name Who or Situation; no pure debt/bet abstract stacking.}
+{L0: Hook spectacle + mechanic payoff; Who optional.}
+
+## System Dynamic
+
+{One sentence — what system tension keeps the player acting.}
+
+## Why this fusion
+
+{2–3 sentences — how parent mechanics **serve** the idea above. Start with intent, not grid sizes.}
+
+## Rejected vibe
+
+- {Not this — e.g. not a casual match-3 binge}
+- {Not this — e.g. not a pure arrow logic puzzle with no payoff}
+
+## Design Intent
+
+{Phase 4 single line — must match One-liner verbatim when copied to DESIGN §0.}

package/project-templates/phaser/templates/project-state.template.md

@@ -55,7 +55,7 @@
 
 Each iteration runs inner loops: `clarify` → `build` → `verify` → **Ring Gate** (user acceptance) → next iteration.
 
-<!-- Iteration definitions: see CLAUDE.md § Growth-Ring Model -->
+<!-- Iteration definitions: see docs/team/collaboration.md (growth-rings-v1) -->
 
 ## Ring DoD (current iteration)
 

package/project-templates/phaser/vite.config.ts

@@ -12,11 +12,10 @@ export default defineConfig(({ command }) => ({
   },
   server: {
     host: "0.0.0.0",
-    // Preferred port; strictPort:false (the default, set explicitly here for
-    // intent) lets Vite auto-increment when 3000 is taken. The harness scripts
-    // (dev:start / verify:* / record:mp4) parse Vite's actual "Local:" URL, so
-    // port drift never needs to be tracked by hand. See dev-start.mjs.
-    port: 3000,
+    // Preferred port; avoid 6000 (Chromium ERR_UNSAFE_PORT). strictPort:false
+    // lets Vite auto-increment when 5173 is taken. Harness scripts parse the
+    // actual "Local:" URL. See dev-start.mjs.
+    port: 5173,
     strictPort: false,
     open: true,
   },

package/project-templates/playable-template-phaser/.playcraftignore

@@ -0,0 +1,10 @@
+# 构建时排除的文件/目录
+.git/
+scripts/
+node_modules/
+*.md
+*.backup
+.DS_Store
+vite.config.ts
+index.html
+tsconfig.json

package/project-templates/playable-template-phaser/CLAUDE.md

@@ -0,0 +1,178 @@
+# Phaser Playable Template - 项目说明
+
+本项目是基于 Phaser 的可玩广告模板，使用 PlayCraft 平台架构（`@playcraft/adsdk` + `@playcraft/devkit`）。
+
+## 架构特点
+
+- **SDK**：`@playcraft/adsdk` - 可玩广告运行时 SDK
+- **构建工具**：`@playcraft/devkit` - 可玩广告构建工具链
+- **本地开发**：Vite 开发服务器，支持 HMR 热更新
+- **主题系统**：配置化架构，支持 JSON5 Schema + 覆盖配置
+
+## 开发命令
+
+### 本地开发
+
+```bash
+# 使用 Vite 开发服务器（推荐，速度快，支持 HMR）
+npm run dev
+
+# 使用 playable-scripts 开发服务器（与构建环境一致）
+npm run dev:wp
+```
+
+### 构建
+
+```bash
+# 构建单个渠道（preview）
+npm run build
+
+# 批量构建所有渠道
+npm run builds
+
+# 打包为 PlayCraft 模板 ZIP
+npm run pack-to-playcraft-template-zip
+```
+
+### 资源处理
+
+```bash
+# 将图片转为 WebP 格式（质量 90）
+npm run webp
+
+# 将图片转为 WebP 格式（质量 80）
+npm run webp:80
+```
+
+## 目录结构
+
+```
+playable-template-phaser/
+├── src/
+│   ├── theme/                    # 主题系统
+│   │   ├── theme.schema.json5    # 配置协议（默认值）
+│   │   ├── theme.metadata.md     # 主题元数据
+│   │   ├── blue-theme/           # 蓝色主题
+│   │   │   ├── index.ts          # 主题入口
+│   │   │   ├── theme.data.json5  # 配置覆盖
+│   │   │   └── assets/           # 主题资源
+│   │   ├── green-theme/          # 绿色主题
+│   │   ├── red-theme/            # 红色主题
+│   │   └── index.ts              # 主题统一出口
+│   ├── config/                   # 配置管理
+│   │   ├── ThemeConfig.ts        # 主题配置获取器
+│   │   └── LoadingConfig.ts      # Loading 配置
+│   ├── scenes/                   # Phaser 场景
+│   ├── managers/                 # 管理器
+│   ├── ui/                       # UI 组件
+│   ├── Game.ts                   # 游戏主类
+│   └── index.ts                  # 入口文件
+├── assets/                       # 公共资源
+├── vite.config.ts                # Vite 配置
+├── index.html                    # Vite 入口 HTML
+├── builds.config.js              # 构建配置
+├── package.json                  # 项目配置
+└── tsconfig.json                 # TypeScript 配置
+```
+
+## 主题系统
+
+### 配置优先级
+
+```
+theme.data.json5（主题覆盖）> theme.schema.json5（默认值）
+```
+
+### 切换主题
+
+修改 `src/theme/index.ts`：
+
+```typescript
+export { default } from './blue-theme'; // 蓝色主题
+// export { default } from './green-theme';  // 绿色主题
+// export { default } from './red-theme';     // 红色主题
+```
+
+### 添加新主题
+
+1. 复制现有主题目录（如 `blue-theme`）
+2. 修改 `theme.data.json5` 配置
+3. 添加主题特定资源到 `assets/` 目录
+4. 更新 `index.ts` 的资源映射
+5. 在 `theme/index.ts` 切换主题
+
+## 配置系统
+
+### 读取配置
+
+使用 `sdk.getConfig()` 或封装的配置获取器：
+
+```typescript
+import { GameThemeConfig } from './config/ThemeConfig';
+
+// 获取配置值
+const backgroundColor = GameThemeConfig.BACKGROUND_COLOR;
+const difficulty = GameThemeConfig.DIFFICULTY;
+```
+
+### 资源路径解析
+
+资源路径通过 `assetRecordByPath` 自动解析为真实 URL：
+
+```typescript
+// theme.schema.json5 中定义路径
+assets: {
+  logo: {
+    default: "./assets/logo.webp"
+  }
+}
+
+// theme/index.ts 中映射路径
+import logoWebp from 'assets/logo.webp';
+const assetRecordByPath = {
+  './assets/logo.webp': logoWebp,
+};
+
+// 代码中获取 URL
+const logoUrl = GameThemeConfig.ASSET_LOGO;  // 解析后的真实 URL
+```
+
+## 相关技能
+
+如需进行以下操作，请加载对应技能：
+
+- **SDK 埋点检查**：`playable-sdk-tracking`
+- **构建产物检查**：`playable-output-checker`
+- **项目初始化**：`playable-project-scaffold`
+- **资源提取/重打包**：`game-asset-extractor`
+
+## 常见问题
+
+### Q1: 资源 URL 为空
+
+**原因**：`assetRecordByPath` 缺少路径映射
+
+**解决**：在主题 `index.ts` 中添加资源映射
+
+### Q2: 配置值为 undefined
+
+**原因**：`theme.schema.json5` 缺少该字段的 `default` 值
+
+**解决**：在 schema 中添加字段定义及默认值
+
+### Q3: 模块顶层缓存导致配置为空
+
+**原因**：在模块加载时立即读取配置，此时 `sdk.setConfig()` 还没执行
+
+**解决**：使用 getter 延迟获取，或在运行时获取配置
+
+## 技术栈
+
+- **游戏引擎**：Phaser 3.88.2
+- **语言**：TypeScript 5.7.2
+- **构建工具**：Vite 5.4.0 (本地) / @playcraft/devkit (生产)
+- **配置格式**：JSON5 (支持注释)
+
+## 更多信息
+
+详细的平台改造指南请参考：`playable-template/skills/playable-platform-refactor/SKILL.md`

package/project-templates/playable-template-phaser/PLAYCRAFT-MIGRATION.md

@@ -0,0 +1,328 @@
+# PlayCraft 平台改造总结
+
+本文档记录了 `playable-template-phaser` 从原有架构改造为 PlayCraft 平台架构的完整过程。
+
+## 改造概述
+
+**改造前**：使用 `@tencent/playable-sdk` + 硬编码配置
+
+**改造后**：使用 `@playcraft/adsdk` + JSON5 Schema 配置化架构
+
+## 改造内容
+
+### 1. SDK 依赖替换
+
+#### ✅ globals.d.ts
+
+```diff
+- /// <reference types="@tencent/playable-sdk/defines" />
+- /// <reference types="@tencent/playable-scripts/defines" />
++ /// <reference types="@playcraft/adsdk/defines" />
++ /// <reference types="@playcraft/devkit/defines" />
+```
+
+#### ✅ package.json
+
+- 添加 `vite`、`json5`、`typescript`、`@types/node`
+- 添加 `json5-loader` 等构建工具
+- 新增 `dev` 脚本（Vite）和 `dev:wp` 脚本
+
+### 2. 本地开发支持
+
+#### ✅ 新增文件
+
+- `vite.config.ts` - Vite 配置，支持 JSON5 插件和路径别名
+- `index.html` - Vite 入口 HTML
+- `src/json5.d.ts` - JSON5 模块类型声明
+
+### 3. 主题系统配置化
+
+#### ✅ 新增配置协议
+
+- `src/theme/theme.schema.json5` - 定义所有可配置项及默认值
+- `src/theme/theme.metadata.md` - 主题元数据文档
+
+#### ✅ 改造主题目录
+
+每个主题目录（blue-theme、green-theme、red-theme）：
+
+- 新增 `theme.data.json5` - 配置覆盖文件
+- 改造 `index.ts` - 导出 `themeData` 和 `assetRecordByPath`
+
+**改造前**：
+
+```typescript
+const config: ThemeConfig = {
+  name: '蓝色主题',
+  backgroundColor: 0x4a90e2,
+  // ... 大量硬编码配置
+};
+export default config;
+```
+
+**改造后**：
+
+```typescript
+import themeData from './theme.data.json5';
+const assetRecordByPath = {
+  /* 资源映射 */
+};
+export default { themeData, assetRecordByPath };
+```
+
+### 4. 配置获取方式改造
+
+#### ✅ ThemeConfig.ts
+
+- 从硬编码接口改为通过 `sdk.getConfig()` 获取
+- 使用 getter 延迟获取，避免模块顶层缓存问题
+
+**改造前**：
+
+```typescript
+export interface ThemeConfig {
+  backgroundColor: number;
+  // ...
+}
+```
+
+**改造后**：
+
+```typescript
+export const GameThemeConfig = {
+  get BACKGROUND_COLOR(): number {
+    return get('visual.backgroundColor', 0xf7d37f);
+  },
+  // ...
+};
+```
+
+#### ✅ LoadingConfig.ts
+
+- 同样改为通过 `sdk.getConfig()` 获取
+- 移除硬编码的资源 import
+
+### 5. 入口文件改造
+
+#### ✅ src/index.ts
+
+添加主题系统初始化：
+
+```typescript
+import ThemeConfig from './theme/theme.schema.json5';
+import Theme from './theme';
+
+sdk.setConfig([ThemeConfig, Theme.themeData], {
+  assetRecordByPath: Theme.assetRecordByPath,
+});
+
+sdk.playcraftInit((width, height) => {
+  // ...
+});
+```
+
+### 6. 场景文件改造
+
+#### ✅ src/scenes/MainScene.ts
+
+```diff
+- import themeConfig from '../theme/index';
++ import { GameThemeConfig } from '../config/ThemeConfig';
+
+- this.cameras.main.setBackgroundColor(themeConfig.backgroundColor);
++ this.cameras.main.setBackgroundColor(GameThemeConfig.BACKGROUND_COLOR);
+```
+
+### 7. 项目配置文件
+
+#### ✅ 新增/更新
+
+- `.playcraftignore` - 构建排除配置
+- `CLAUDE.md` - 详细项目说明
+- `PLAYCRAFT-MIGRATION.md` - 改造总结（本文档）
+- `新手开发指南.md` - 更新后的开发指南
+
+#### ✅ tsconfig.json
+
+添加路径别名：
+
+```json
+"paths": {
+  "assets/*": ["./assets/*"],
+  "@/*": ["./src/*"],
+  "src/*": ["./src/*"]
+}
+```
+
+#### ✅ README.md
+
+更新为 PlayCraft 平台说明
+
+## 改造后的优势
+
+### 1. 配置化
+
+- ✅ 主题配置集中管理
+- ✅ 配置与代码分离
+- ✅ 支持 PlayCraft 平台在线编辑
+
+### 2. 开发体验
+
+- ✅ Vite 极速 HMR 热更新
+- ✅ 更好的类型提示
+- ✅ 配置使用 JSON5（支持注释）
+
+### 3. 维护性
+
+- ✅ 配置优先级清晰（schema → data）
+- ✅ 资源路径自动解析
+- ✅ 避免模块顶层缓存问题
+
+### 4. 扩展性
+
+- ✅ 易于添加新主题（只需写差异配置）
+- ✅ 易于添加新配置项
+- ✅ 支持批量构建
+
+## 配置系统工作流程
+
+```
+1. sdk.setConfig([ThemeConfig, themeData], { assetRecordByPath })
+   ↓
+2. SDK 提取 schema 的 default 值作为基底配置
+   ↓
+3. 深度合并 基底配置 + themeData 覆盖值
+   ↓
+4. 递归解析资源路径（通过 assetRecordByPath 映射）
+   ↓
+5. sdk.getConfig() 返回最终配置
+```
+
+## 使用示例
+
+### 添加新配置项
+
+1. 在 `theme.schema.json5` 中定义：
+
+```json5
+gameplay: {
+  maxScore: {
+    type: "integer",
+    default: 1000,
+    description: "最高分数",
+  },
+}
+```
+
+2. 在 `ThemeConfig.ts` 中添加 getter：
+
+```typescript
+get MAX_SCORE(): number { return get('gameplay.maxScore', 1000); }
+```
+
+3. 在代码中使用：
+
+```typescript
+const maxScore = GameThemeConfig.MAX_SCORE;
+```
+
+### 添加新资源
+
+1. 在 `theme.schema.json5` 中定义路径：
+
+```json5
+assets: {
+  logo: {
+    type: "string",
+    default: "./assets/logo.webp",
+    xplatform: { value_type: "path", mime_type: "image/webp" },
+  },
+}
+```
+
+2. 在主题 `index.ts` 中映射：
+
+```typescript
+import logoWebp from 'assets/logo.webp';
+const assetRecordByPath = {
+  './assets/logo.webp': logoWebp,
+};
+```
+
+3. 在配置中获取：
+
+```typescript
+get ASSET_LOGO(): string { return get('assets.logo', ''); }
+```
+
+## 注意事项
+
+### ⚠️ 必须使用 getter
+
+配置获取器必须使用 getter 而非顶层常量：
+
+```typescript
+// ❌ 错误：模块加载时立即执行，此时 setConfig 还没调用
+const CONFIG = sdk.getConfig();
+
+// ✅ 正确：运行时获取
+get CONFIG() { return sdk.getConfig(); }
+```
+
+### ⚠️ schema 必须有 $schema 字段
+
+```json5
+{
+  $schema: 'http://json-schema.org/draft-07/schema#', // 必须！
+  // ...
+}
+```
+
+### ⚠️ 资源路径必须一致
+
+```json5
+// schema 中的路径
+default: "./assets/logo.webp"
+
+// assetRecordByPath 中的 key 必须完全一致
+'./assets/logo.webp': logoWebp
+```
+
+## 检查清单
+
+- [x] globals.d.ts 类型引用已更新
+- [x] package.json 依赖已更新
+- [x] vite.config.ts 已创建
+- [x] index.html 已创建
+- [x] src/json5.d.ts 已创建
+- [x] theme.schema.json5 已创建
+- [x] theme.metadata.md 已创建
+- [x] 所有主题已改造（theme.data.json5 + index.ts）
+- [x] src/index.ts 已添加 setConfig
+- [x] ThemeConfig.ts 已改为 sdk.getConfig()
+- [x] LoadingConfig.ts 已改为 sdk.getConfig()
+- [x] MainScene.ts 已更新配置引用
+- [x] tsconfig.json 已更新路径别名
+- [x] .playcraftignore 已创建
+- [x] CLAUDE.md 已创建
+- [x] README.md 已更新
+- [x] 所有 lint 错误已修复
+- [x] 新手开发指南已更新
+
+## 下一步
+
+1. 运行 `npm install` 安装新依赖
+2. 运行 `npm run dev` 测试 Vite 开发服务器
+3. 运行 `npm run dev:wp` 测试 playable-scripts 开发服务器
+4. 运行 `npm run builds` 测试批量构建
+
+## 参考文档
+
+- [PlayCraft 平台改造 Skill](../skills/playable-platform-refactor/SKILL.md)
+- [项目详细说明](./CLAUDE.md)
+- [开发指南](./新手开发指南.md)
+
+---
+
+改造完成时间：2026-04-24
+改造完成者：AI Assistant