@playcraft/cli 0.0.53 → 0.0.56

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

package/project-templates/playable-template-phaser/builds.config.js

@@ -0,0 +1,12 @@
+/**
+ * Phaser Template 批量构建配置
+ * 
+ * 支持多主题批量构建，适合 A/B 测试和版本迭代
+ */
+
+module.exports = {
+  // 项目名称（用于 html title生成）
+  title: 'Phaser-Template',
+  // 可玩广告对应的 App 名称
+  appName: 'Sola Mahjong',
+};

package/project-templates/playable-template-phaser/globals.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="@playcraft/adsdk/defines" />
+/// <reference types="@playcraft/devkit/defines" />

package/project-templates/playable-template-phaser/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+    <title>Phaser Template - Playable Ads</title>
+  </head>
+  <body>
+    <div id="game-container"></div>
+    <script type="module" src="/src/index.ts"></script>
+  </body>
+</html>

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

@@ -0,0 +1,45 @@
+{
+  "name": "playable-template-phaser",
+  "version": "1.0.0",
+  "description": "A starter template for creating playable ads using Phaser and @playcraft/adsdk with TypeScript support",
+  "scripts": {
+    "dev": "vite",
+    "dev:wp": "playable-scripts dev",
+    "build": "playable-scripts build",
+    "builds": "playable-scripts builds",
+    "pack-to-playcraft-template-zip": "playable-scripts pack",
+    "webp": "node scripts/convert-to-webp.js",
+    "webp:80": "node scripts/convert-to-webp.js 80"
+  },
+  "keywords": [
+    "playable",
+    "ads",
+    "template",
+    "phaser",
+    "webgl",
+    "2d",
+    "typescript",
+    "game"
+  ],
+  "author": "Smoud",
+  "dependencies": {
+    "@playcraft/adsdk": "*",
+    "phaser": "^3.88.2",
+    "json5": "^2.2.3"
+  },
+  "devDependencies": {
+    "@playcraft/devkit": "*",
+    "@types/node": "^22.10.5",
+    "vite": "^5.4.0",
+    "typescript": "~5.7.2",
+    "prettier": "^2.7.1",
+    "babel-loader": "^10.0.0",
+    "css-loader": "^7.1.2",
+    "esbuild-loader": "^4.4.1",
+    "json5-loader": "^4.0.1",
+    "style-loader": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}