@playcraft/cli 0.0.52 → 0.0.55

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

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

@@ -0,0 +1,381 @@
+# Playable Template - Phaser
+
+基于 Phaser 3 游戏框架的可玩广告开发模板，使用 PlayCraft 平台架构，支持 TypeScript。
+
+## 技术栈
+
+- [Phaser 3](https://phaser.io/) - 高性能 2D 游戏框架
+- [@playcraft/adsdk](https://www.npmjs.com/package/@playcraft/adsdk) - 可玩广告 SDK
+- [@playcraft/devkit](https://www.npmjs.com/package/@playcraft/devkit) - 构建工具
+- [Vite](https://vitejs.dev/) - 本地开发服务器（支持 HMR）
+
+## 功能特性
+
+- ✅ Phaser 3 集成，支持高性能 2D 游戏开发
+- ✅ TypeScript 支持
+- ✅ **配置化主题系统** - JSON5 Schema + 覆盖配置
+- ✅ **Vite 本地开发** - 超快的 HMR 热更新
+- ✅ **响应式适配** - 自动适配横竖屏和不同设备
+- ✅ **批量构建** - 支持多主题、多渠道批量打包
+- ✅ SDK 事件处理（resize、pause、resume、volume 等）
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+### 2. 启动开发服务器
+
+```bash
+# 使用 Vite 开发服务器（推荐，速度快，支持 HMR）
+npm run dev
+
+# 使用 playable-scripts 开发服务器（与构建环境一致）
+npm run dev:wp
+```
+
+开发服务器默认运行在 `http://localhost:3000`（Vite）或 `http://localhost:8080`（playable-scripts）
+
+### 3. 构建生产版本
+
+#### 单渠道构建
+
+```bash
+npm run build -- <network>
+
+# 示例
+npm run build -- google      # Google Ads
+npm run build -- facebook    # Meta
+npm run build -- unity       # Unity Ads
+```
+
+#### 批量构建
+
+```bash
+npm run builds                                # 构建所有主题和渠道
+npm run builds -- -t "theme1,theme2"          # 构建指定主题
+npm run builds -- -c "google,facebook"        # 构建指定渠道
+npm run builds -- -t "theme1" -c "google"     # 组合使用
+```
+
+#### 打包为 PlayCraft 模板
+
+```bash
+npm run pack-to-playcraft-template-zip
+```
+
+## 脚本命令
+
+| 命令                                     | 说明                             |
+| ---------------------------------------- | -------------------------------- |
+| `npm run dev`                            | 启动 Vite 开发服务器（推荐）     |
+| `npm run dev:wp`                         | 启动 playable-scripts 开发服务器 |
+| `npm run build -- <network>`             | 构建指定渠道                     |
+| `npm run builds`                         | 批量构建所有主题和渠道           |
+| `npm run pack-to-playcraft-template-zip` | 打包为 PlayCraft 模板 ZIP        |
+| `npm run webp`                           | 将图片转为 WebP 格式（质量 90）  |
+| `npm run webp:80`                        | 将图片转为 WebP 格式（质量 80）  |
+
+## 项目结构
+
+```
+playable-template-phaser/
+├── assets/                     # 公共资源目录
+│   └── logo.webp
+├── src/
+│   ├── theme/                  # 主题系统
+│   │   ├── theme.schema.json5  # 配置协议（默认值）
+│   │   ├── theme.metadata.md   # 主题元数据
+│   │   ├── blue-theme/         # 蓝色主题
+│   │   │   ├── index.ts        # 主题入口
+│   │   │   ├── theme.data.json5 # 配置覆盖
+│   │   │   └── assets/         # 主题资源
+│   │   ├── green-theme/        # 绿色主题
+│   │   ├── red-theme/          # 红色主题
+│   │   └── index.ts            # 主题统一出口
+│   ├── scenes/                 # Phaser 场景
+│   │   ├── PreloadScene.ts     # 预加载场景
+│   │   └── MainScene.ts        # 主游戏场景
+│   ├── config/                 # 配置管理
+│   │   ├── ThemeConfig.ts      # 主题配置获取器
+│   │   └── LoadingConfig.ts    # Loading 配置
+│   ├── managers/               # 管理器
+│   │   └── AudioManager.ts     # 音频管理器
+│   ├── ui/                     # UI 组件
+│   ├── Game.ts                 # Phaser.Game 配置
+│   ├── index.ts                # 入口文件
+│   ├── index.css               # 样式文件
+│   └── json5.d.ts              # JSON5 类型声明
+├── vite.config.ts              # Vite 配置
+├── index.html                  # Vite 入口 HTML
+├── builds.config.js            # 批量构建配置
+├── tsconfig.json               # TypeScript 配置
+├── globals.d.ts                # 全局类型声明
+├── .playcraftignore            # 构建排除配置
+├── CLAUDE.md                   # 项目说明（详细版）
+└── package.json
+```
+
+## 主题系统
+
+### 配置化架构
+
+项目采用 PlayCraft 平台的配置化架构：
+
+1. **配置协议**（`theme.schema.json5`）- 定义所有可配置项及默认值
+2. **配置覆盖**（`theme.data.json5`）- 各主题只需写与默认值不同的配置
+3. **资源映射**（`assetRecordByPath`）- 自动将配置中的路径解析为真实 URL
+
+### 配置优先级
+
+```
+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` 切换主题
+
+### 主题列表
+
+| 主题 ID | 难度 | 提示 | 说明                                  |
+| ------- | ---- | ---- | ------------------------------------- |
+| blue    | 5    | ✅   | 蓝色主题 - 适合海洋、天空、科技类游戏 |
+| green   | 3    | ✅   | 绿色主题 - 适合自然、森林、环保类游戏 |
+| red     | 7    | ❌   | 红色主题 - 适合动作、冒险、激情类游戏 |
+
+## 配置系统
+
+### 读取配置
+
+使用 `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
+```
+
+## 响应式适配
+
+模板采用 `WIDTH_CONTROLS_HEIGHT` 缩放模式：
+
+- ✅ 固定设计宽度（1280px）
+- ✅ 高度自适应
+- ✅ 自动画布缩放
+- ✅ 横竖屏切换时自动刷新
+
+```typescript
+// Game.ts
+const DESIGN_WIDTH = 1280;
+
+export class Game extends Phaser.Game {
+  constructor(width: number, height: number) {
+    const gameWidth = DESIGN_WIDTH;
+    const gameHeight = height * (DESIGN_WIDTH / width);
+
+    super({
+      width: gameWidth,
+      height: gameHeight,
+      scale: {
+        mode: Phaser.Scale.WIDTH_CONTROLS_HEIGHT,
+        autoCenter: Phaser.Scale.CENTER_BOTH,
+      },
+    });
+  }
+}
+```
+
+## SDK 使用
+
+### 初始化
+
+```typescript
+import { sdk } from '@playcraft/adsdk';
+import ThemeConfig from './theme/theme.schema.json5';
+import Theme from './theme';
+
+// 1. 设置配置（必须在 playcraftInit 之前）
+sdk.setConfig([ThemeConfig, Theme.themeData], {
+  assetRecordByPath: Theme.assetRecordByPath,
+});
+
+// 2. 初始化 SDK
+sdk.playcraftInit((width: number, height: number) => {
+  const game = new Game(width, height);
+
+  // 3. 监听事件
+  sdk.on('playcraftResize', game.resize, game);
+  sdk.on('playcraftPause', game.pause, game);
+  sdk.on('playcraftResume', game.resume, game);
+  sdk.on('playcraftVolume', game.volume, game);
+  sdk.on('playcraftFinish', game.finish, game);
+});
+```
+
+### SDK 事件
+
+| 事件              | 说明         |
+| ----------------- | ------------ |
+| `playcraftResize` | 屏幕尺寸变化 |
+| `playcraftPause`  | 游戏暂停     |
+| `playcraftResume` | 游戏恢复     |
+| `playcraftVolume` | 音量变化     |
+| `playcraftFinish` | 游戏结束     |
+
+### SDK 生命周期
+
+```typescript
+sdk.playcraftInit(); // 初始化，获取容器尺寸
+sdk.start(); // 游戏资源加载完成后调用
+sdk.finish(); // 游戏结束时调用
+sdk.install(); // 跳转应用商店
+```
+
+## 批量构建配置
+
+创建 `builds.config.js`：
+
+```javascript
+module.exports = {
+  // 项目名称（用于 html title 生成）
+  title: 'Phaser-Template',
+
+  // 可玩广告对应的 App 名称
+  appName: 'Sola Mahjong',
+
+  // 商店链接（可选）
+  googlePlayUrl: 'https://play.google.com/...',
+  appStoreUrl: 'https://apps.apple.com/...',
+
+  // 渠道列表（可选，有默认值）
+  channels: ['google', 'facebook', 'unity', 'bigoads'],
+
+  // 主题配置（可选）
+  themes: {
+    enabled: true,
+    sourceDir: 'src/theme',
+    entryFile: 'src/theme/index.ts',
+  },
+
+  // 文件命名（可选，有默认值）
+  naming: {
+    language: 'EN',
+    format: '无',
+    supplier: 'AIX',
+    follower: 'ZQL',
+  },
+
+  // 构建配置（可选，有默认值）
+  build: {
+    outputDir: 'dist-all',
+    continueOnError: true,
+  },
+
+  // 混淆配置（可选）
+  obfuscate: {
+    level: 2, // 0=不混淆, 1=简单, 2=标准, 3=最高
+  },
+};
+```
+
+## 支持的渠道
+
+- google (Google Ads)
+- facebook (Meta)
+- tiktok (TikTok)
+- applovin (AppLovin)
+- ironSource (IronSource)
+- unity (Unity Ads)
+- moloco (Moloco)
+- liftoff (Liftoff)
+- bigoads (BigoAds)
+- adikteev (Adikteev)
+- inmobi (InMobi)
+- snapchat (Snapchat)
+
+## 环境要求
+
+- Node.js >= 16.0.0
+- npm >= 7.0.0
+
+## 常见问题
+
+### Q1: 资源 URL 为空
+
+**原因**：`assetRecordByPath` 缺少路径映射
+
+**解决**：在主题 `index.ts` 中添加资源映射
+
+### Q2: 配置值为 undefined
+
+**原因**：`theme.schema.json5` 缺少该字段的 `default` 值
+
+**解决**：在 schema 中添加字段定义及默认值
+
+### Q3: 模块顶层缓存导致配置为空
+
+**原因**：在模块加载时立即读取配置，此时 `sdk.setConfig()` 还没执行
+
+**解决**：使用 getter 延迟获取，或在运行时获取配置
+
+## 相关技能
+
+如需进行以下操作，请加载对应技能：
+
+- **SDK 埋点检查**：`playable-sdk-tracking`
+- **构建产物检查**：`playable-output-checker`
+- **项目初始化**：`playable-project-scaffold`
+- **资源提取/重打包**：`game-asset-extractor`
+
+## 参考资料
+
+- [Phaser 3 官方文档](https://photonstorm.github.io/phaser3-docs/)
+- [Phaser 3 示例](https://phaser.io/examples)
+- [PlayCraft 平台改造指南](./playable-template/skills/playable-platform-refactor/SKILL.md)
+- [项目详细说明](./CLAUDE.md)
+
+## 许可证
+
+MIT