@playcraft/cli 0.0.53 → 0.0.56

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

@@ -0,0 +1,194 @@
+# 主题系统说明
+
+## 概述
+
+主题系统允许你为同一个游戏创建多个视觉风格变体，通过配置文件的方式抽离颜色、样式等数据，而不需要重写整个游戏逻辑。
+
+## 目录结构
+
+```
+src/theme/
+├── README.md               # 本文档
+├── current.ts              # 当前主题入口（批量构建时自动切换）
+├── blue-theme/             # 蓝色主题文件夹
+│   ├── index.ts            # 蓝色主题配置
+│   └── assets/             # 蓝色主题专属资源
+├── green-theme/            # 绿色主题文件夹
+│   ├── index.ts            # 绿色主题配置
+│   └── assets/             # 绿色主题专属资源
+└── red-theme/              # 红色主题文件夹
+    ├── index.ts            # 红色主题配置
+    └── assets/             # 红色主题专属资源
+```
+
+**为什么使用文件夹结构？**
+
+每个主题是一个独立的文件夹，不仅可以包含配置文件，还可以包含主题专属的资源（如图片、音频等），扩展性更强。
+
+## 使用方法
+
+### 开发时切换主题
+
+修改 `current.ts` 的 import 语句：
+
+```typescript
+// 使用蓝色主题
+import config from './blue-theme';
+
+// 使用绿色主题
+import config from './green-theme';
+
+// 使用红色主题
+import config from './red-theme';
+```
+
+### 批量构建多主题
+
+参考根目录的 `builds.config.example.js` 配置主题批量构建。
+
+## 配置说明
+
+每个主题文件夹需要包含一个 `index.ts` 文件，导出 `ThemeConfig` 对象：
+
+```typescript
+// src/theme/blue-theme/index.ts
+import { ThemeConfig } from '../../config/ThemeConfig';
+
+// 如果有主题专属资源，可以这样引入
+import customBg from './assets/background.png';
+import customButton from './assets/button.png';
+
+const config: ThemeConfig = {
+  // 基础信息
+  name: '主题名称',
+  id: 'theme-id',
+
+  // 颜色配置
+  backgroundColor: 0x4a90e2,
+  primaryColor: 0x2c7be5,
+  textColor: '#ffffff',
+
+  // 字体配置
+  fontSize: {
+    title: '48px',
+    body: '24px',
+    button: '32px',
+  },
+
+  // 可选：主题专属资源
+  customAssets: {
+    background: customBg,
+    button: customButton,
+  },
+};
+
+export default config;
+```
+
+### 主题专属资源
+
+将主题特定的资源放在 `assets/` 目录下：
+
+```
+blue-theme/
+├── index.ts
+└── assets/
+    ├── background.png      # 主题专属背景
+    ├── button.png          # 主题专属按钮
+    └── theme-music.mp3     # 主题专属音乐
+```
+
+在配置文件中引用：
+
+```typescript
+import customBg from './assets/background.png';
+import customMusic from './assets/theme-music.mp3';
+
+const config: ThemeConfig = {
+  // ...
+  customAssets: {
+    background: customBg,
+    music: customMusic,
+  },
+};
+```
+
+## 添加新主题
+
+1. 在 `src/theme/` 下创建新文件夹，如 `purple-theme/`
+2. 在文件夹内创建 `index.ts` 和 `assets/` 目录
+3. 复制现有主题的 `index.ts` 内容并修改配置
+4. （可选）添加主题专属资源到 `assets/` 目录
+5. 在 `current.ts` 中切换到新主题测试
+6. 批量构建时会自动识别新主题
+
+**示例**：
+
+```bash
+# 创建新主题文件夹
+mkdir -p src/theme/purple-theme/assets
+
+# 创建配置文件
+touch src/theme/purple-theme/index.ts
+```
+
+```typescript
+// src/theme/purple-theme/index.ts
+import { ThemeConfig } from '../../config/ThemeConfig';
+
+const config: ThemeConfig = {
+  name: '紫色主题',
+  id: 'purple',
+  backgroundColor: 0x9b59b6,
+  primaryColor: 0x8e44ad,
+  textColor: '#ffffff',
+  fontSize: {
+    title: '48px',
+    body: '24px',
+    button: '32px',
+  },
+};
+
+export default config;
+```
+
+## 配置项说明
+
+| 配置项            | 类型    | 说明                              |
+| ----------------- | ------- | --------------------------------- |
+| `name`            | string  | 主题名称（用于显示）              |
+| `id`              | string  | 主题唯一标识（用于文件命名）      |
+| `backgroundColor` | number  | 背景颜色（十六进制，如 0x4a90e2） |
+| `primaryColor`    | number  | 主色调                            |
+| `secondaryColor`  | number? | 辅助色（可选）                    |
+| `textColor`       | string  | 文字颜色（CSS 颜色）              |
+| `fontSize`        | object  | 字体大小配置                      |
+| `customAssets`    | object? | 主题专属资源（可选）              |
+
+## 在游戏中使用主题
+
+```typescript
+import themeConfig from './theme/current';
+
+// 设置背景色
+this.cameras.main.setBackgroundColor(themeConfig.backgroundColor);
+
+// 使用文字颜色
+this.add.text(x, y, 'Hello', {
+  fontSize: themeConfig.fontSize.title,
+  color: themeConfig.textColor,
+});
+
+// 使用主题专属资源
+if (themeConfig.customAssets?.background) {
+  this.load.image('bg', themeConfig.customAssets.background);
+}
+```
+
+## 注意事项
+
+1. **主题是纯数据配置**：不要在主题文件中编写游戏逻辑
+2. **保持接口一致**：所有主题应该实现相同的配置接口
+3. **使用 TypeScript**：类型检查确保配置正确
+4. **资源管理**：主题专属资源放在 `assets/` 目录，公共资源放在项目根目录的 `assets/`
+5. **批量构建**：使用 `npm run builds` 会自动为每个主题构建所有渠道

package/project-templates/playable-template-phaser/src/theme/blue-theme/assets/.gitkeep

@@ -0,0 +1,24 @@
+# 主题专属资源目录
+
+将主题特定的资源文件放在这里，例如：
+- 特定的背景图片
+- 主题专属的UI元素
+- 特殊的音频文件
+
+示例：
+```
+assets/
+├── background.png
+├── button-special.png
+└── theme-music.mp3
+```
+
+在主题配置中引用：
+```typescript
+import backgroundImg from './assets/background.png';
+
+const config: ThemeConfig = {
+  // ...
+  customBackground: backgroundImg,
+};
+```

package/project-templates/playable-template-phaser/src/theme/blue-theme/index.ts

@@ -0,0 +1,27 @@
+/**
+ * 🎨 蓝色主题
+ * 适合海洋、天空、科技类游戏
+ */
+
+// 公共资源 import
+import logoWebp from 'assets/logo.webp';
+
+// 主题特定资源（如果有）
+// import customBg from './assets/background.png';
+// import customButton from './assets/button.png';
+
+// 主题配置覆盖（PlayCraft 平台）
+import themeData from './theme.data.json5';
+
+// 资源路径映射
+const assetRecordByPath: Record<string, string> = {
+  './assets/logo.webp': logoWebp,
+  // 如果有主题特定资源，在这里添加映射：
+  // './assets/background.png': customBg,
+  // './assets/button.png': customButton,
+};
+
+export default {
+  themeData,
+  assetRecordByPath,
+};

package/project-templates/playable-template-phaser/src/theme/blue-theme/theme.data.json5

@@ -0,0 +1,19 @@
+{
+  // 蓝色主题配置覆盖
+  // 只写与 schema 默认值不同的覆盖项
+
+  name: "蓝色主题",
+  id: "blue",
+
+  visual: {
+    backgroundColor: 0x4a90e2,
+    primaryColor: 0x2c3e50,
+    secondaryColor: 0x3498db,
+    textColor: "#ffffff",
+  },
+
+  gameplay: {
+    difficulty: 5,
+    enableHints: true,
+  },
+}

package/project-templates/playable-template-phaser/src/theme/green-theme/assets/.gitkeep

@@ -0,0 +1,3 @@
+# 主题专属资源目录
+
+将主题特定的资源文件放在这里。

package/project-templates/playable-template-phaser/src/theme/green-theme/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 🎨 绿色主题
+ * 适合自然、森林、环保类游戏
+ */
+
+// 公共资源 import
+import logoWebp from 'assets/logo.webp';
+
+// 主题配置覆盖（PlayCraft 平台）
+import themeData from './theme.data.json5';
+
+// 资源路径映射
+const assetRecordByPath: Record<string, string> = {
+  './assets/logo.webp': logoWebp,
+};
+
+export default {
+  themeData,
+  assetRecordByPath,
+};

package/project-templates/playable-template-phaser/src/theme/green-theme/theme.data.json5

@@ -0,0 +1,19 @@
+{
+  // 绿色主题配置覆盖
+  // 只写与 schema 默认值不同的覆盖项
+
+  name: "绿色主题",
+  id: "green",
+
+  visual: {
+    backgroundColor: 0x27ae60,
+    primaryColor: 0x1e8449,
+    secondaryColor: 0x52be80,
+    textColor: "#ffffff",
+  },
+
+  gameplay: {
+    difficulty: 3,
+    enableHints: true,
+  },
+}

package/project-templates/playable-template-phaser/src/theme/index.ts

@@ -0,0 +1 @@
+export { default } from './blue-theme';

package/project-templates/playable-template-phaser/src/theme/red-theme/assets/.gitkeep

@@ -0,0 +1,3 @@
+# 主题专属资源目录
+
+将主题特定的资源文件放在这里。

package/project-templates/playable-template-phaser/src/theme/red-theme/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 🎨 红色主题
+ * 适合动作、冒险、激情类游戏
+ */
+
+// 公共资源 import
+import logoWebp from 'assets/logo.webp';
+
+// 主题配置覆盖（PlayCraft 平台）
+import themeData from './theme.data.json5';
+
+// 资源路径映射
+const assetRecordByPath: Record<string, string> = {
+  './assets/logo.webp': logoWebp,
+};
+
+export default {
+  themeData,
+  assetRecordByPath,
+};

package/project-templates/playable-template-phaser/src/theme/red-theme/theme.data.json5

@@ -0,0 +1,19 @@
+{
+  // 红色主题配置覆盖
+  // 只写与 schema 默认值不同的覆盖项
+
+  name: "红色主题",
+  id: "red",
+
+  visual: {
+    backgroundColor: 0xe74c3c,
+    primaryColor: 0xc0392b,
+    secondaryColor: 0xec7063,
+    textColor: "#ffffff",
+  },
+
+  gameplay: {
+    difficulty: 7,
+    enableHints: false,
+  },
+}

package/project-templates/playable-template-phaser/src/theme/theme.metadata.md

@@ -0,0 +1,60 @@
+# 主题元数据
+
+## 主题列表
+
+| 主题 ID | 难度 | 提示 | 说明                                  |
+| ------- | ---- | ---- | ------------------------------------- |
+| blue    | 5    | ✅   | 蓝色主题 - 适合海洋、天空、科技类游戏 |
+| green   | 3    | ✅   | 绿色主题 - 适合自然、森林、环保类游戏 |
+| red     | 7    | ❌   | 红色主题 - 适合动作、冒险、激情类游戏 |
+
+## 配色方案
+
+### 蓝色主题
+
+- 背景色：`0x4a90e2` (深蓝)
+- 主色：`0x2c3e50` (深灰蓝)
+- 辅色：`0x3498db` (亮蓝)
+- 文字色：`#ffffff` (白色)
+
+### 绿色主题
+
+- 背景色：`0x27ae60` (绿色)
+- 主色：`0x1e8449` (深绿)
+- 辅色：`0x52be80` (亮绿)
+- 文字色：`#ffffff` (白色)
+
+### 红色主题
+
+- 背景色：`0xe74c3c` (红色)
+- 主色：`0xc0392b` (深红)
+- 辅色：`0xec7063` (浅红)
+- 文字色：`#ffffff` (白色)
+
+## 使用说明
+
+### 切换主题
+
+修改 `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. 更新主题特定资源（如有）
+4. 在 `theme/index.ts` 中切换到新主题
+
+## 配置说明
+
+所有主题共享 `theme.schema.json5` 定义的默认值。
+
+每个主题的 `theme.data.json5` 只需要写与默认值不同的配置项。
+
+配置优先级：`theme.data.json5` > `theme.schema.json5`

package/project-templates/playable-template-phaser/src/theme/theme.schema.json5

@@ -0,0 +1,149 @@
+{
+  // ⚠️ $schema 字段必须存在！SDK 通过它识别这是 JSON Schema（提取 default 值）
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "Phaser Template Configuration",
+  description: "可玩广告模板配置协议",
+  type: "object",
+  properties: {
+    // ========== 基础信息 ==========
+    name: {
+      type: "string",
+      default: "Default Theme",
+      description: "主题显示名称",
+    },
+    id: {
+      type: "string",
+      default: "default",
+      description: "主题唯一标识",
+    },
+
+    // ========== 资源配置 ==========
+    assets: {
+      type: "object",
+      properties: {
+        logo: {
+          type: "string",
+          default: "./assets/logo.webp",
+          description: "Logo 图片",
+          xplatform: { value_type: "path", mime_type: "image/webp" },
+        },
+        buttonImage: {
+          type: "string",
+          default: "",
+          description: "按钮图片（可选）",
+          xplatform: { value_type: "path", mime_type: "image/png" },
+        },
+        backgroundImage: {
+          type: "string",
+          default: "",
+          description: "背景图片（可选）",
+          xplatform: { value_type: "path", mime_type: "image/png" },
+        },
+      },
+    },
+
+    // ========== 视觉配置 ==========
+    visual: {
+      type: "object",
+      properties: {
+        backgroundColor: {
+          type: "integer",
+          default: 0xf7d37f,
+          description: "背景颜色（十六进制）",
+        },
+        primaryColor: {
+          type: "integer",
+          default: 0x4a90e2,
+          description: "主要颜色",
+        },
+        secondaryColor: {
+          type: "integer",
+          default: 0x3498db,
+          description: "次要颜色",
+        },
+        textColor: {
+          type: "string",
+          default: "#ffffff",
+          description: "文本颜色",
+        },
+      },
+    },
+
+    // ========== 字体配置 ==========
+    fontSize: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          default: "48px",
+          description: "标题字体大小",
+        },
+        body: {
+          type: "string",
+          default: "24px",
+          description: "正文字体大小",
+        },
+        button: {
+          type: "string",
+          default: "32px",
+          description: "按钮字体大小",
+        },
+      },
+    },
+
+    // ========== 游戏参数 ==========
+    gameplay: {
+      type: "object",
+      properties: {
+        difficulty: {
+          type: "integer",
+          default: 5,
+          description: "难度系数 (1-10)",
+        },
+        enableHints: {
+          type: "boolean",
+          default: true,
+          description: "是否启用提示",
+        },
+      },
+    },
+
+    // ========== Loading 配置 ==========
+    loading: {
+      type: "object",
+      properties: {
+        logoImage: {
+          type: "string",
+          default: "./assets/logo.webp",
+          description: "Loading 页面 Logo",
+          xplatform: { value_type: "path", mime_type: "image/webp" },
+        },
+        appTitle: {
+          type: "string",
+          default: "Sola Mahjong",
+          description: "应用标题",
+        },
+        appStars: {
+          type: "string",
+          default: "★★★★★",
+          description: "评分星星",
+        },
+        appDesc: {
+          type: "string",
+          default: "Sola Mahjong: Classic Tile\nPairing for a Relaxing Puzzle",
+          description: "应用描述",
+        },
+        loadingText: {
+          type: "string",
+          default: "Loading Playable Ads",
+          description: "加载文字",
+        },
+        sceneDuration: {
+          type: "integer",
+          default: 100,
+          description: "Loading 页面最小显示时长（毫秒）",
+        },
+      },
+    },
+  },
+}