@playcraft/cli 0.0.53 → 0.0.55

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

@@ -0,0 +1,795 @@
+# Playable Template - Three.js
+
+基于 Three.js 的可玩广告开发模板，支持 TypeScript，适合 3D 游戏开发。
+
+## 技术栈
+
+- [Three.js](https://threejs.org/) - 强大的 3D 图形库
+- [@playcraft/adsdk](https://git.woa.com/ua_playable_game/playable-template/playable-sdk) - 可玩广告 SDK，提供标准化事件和方法
+- [@playcraft/devkit](https://git.woa.com/ua_playable_game/playable-template/playable-scripts) - 构建和开发工具
+
+## 功能特性
+
+- ✅ Three.js 集成，支持高性能 3D 渲染
+- ✅ TypeScript 支持
+- ✅ 开发环境热更新 (HMR)
+- ✅ SDK 事件处理（resize、pause、resume、volume 等）
+- ✅ 安装按钮实现
+- ✅ 交互追踪
+- ✅ **响应式适配** - 自动适配横竖屏和不同设备
+- ✅ **主题配置系统** - 支持多主题切换，配置与代码分离
+- ✅ **PreloadScene** - 标准的资源预加载流程
+- ✅ **批量构建** - 支持多主题、多渠道批量打包
+- ✅ 图片 WebP 转换工具
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+### 2. 启动开发服务器
+
+```bash
+# 默认预览模式
+npm run dev
+
+# 指定渠道调试（调试特定渠道的 SDK 行为）
+npm run dev bigoads      # 调试 BigoAds
+npm run dev ironsource   # 调试 IronSource (MRAID)
+npm run dev google       # 调试 Google Ads
+```
+
+开发服务器默认运行在 `http://localhost:8080`
+
+### 3. 构建生产版本
+
+#### 单渠道构建
+
+```bash
+npm run build -- <network>
+
+# 示例
+npm run build -- google      # Google Ads
+npm run build -- facebook    # Facebook
+npm run build -- unity       # Unity Ads
+npm run build -- applovin    # AppLovin
+npm run build -- ironsource  # IronSource
+npm run build -- tiktok      # TikTok
+npm run build -- moloco      # Moloco
+npm run build -- liftoff     # Liftoff
+npm run build -- bigoads     # BigoAds
+```
+
+#### 批量构建（多渠道）
+
+**方式1: 使用默认配置（无主题切换）**
+
+```bash
+npm run build:all
+# 或
+npm run builds
+```
+
+自动构建所有渠道，输出到 `dist-all/` 目录。
+
+**方式2: 使用配置文件（支持主题切换）**
+
+```bash
+# 1. 创建配置文件
+cp builds.config.example.js builds.config.js
+
+# 2. 修改配置（根据项目需求）
+vi builds.config.js
+
+# 3. 运行批量构建
+npm run builds
+
+# 4. 高级用法：指定主题和渠道
+npm run builds -- -t "theme1,theme2"       # 构建指定主题
+npm run builds -- -c "google,facebook"     # 构建指定渠道
+npm run builds -- -t "theme1" -c "google"  # 组合使用
+```
+
+**配置示例**（`builds.config.js`）：
+
+```javascript
+module.exports = {
+  // 项目基本信息
+  projectName: 'My Three Game',
+  projectCode: '0001',
+
+  // 渠道列表
+  channels: [
+    'google',
+    'facebook',
+    'tiktok',
+    'applovin',
+    'ironSource',
+    'unity',
+    'moloco',
+    'liftoff',
+    'bigoads',
+  ],
+
+  // 主题配置（可选）
+  themes: {
+    enabled: true, // 是否启用主题切换
+    sourceDir: 'src/theme', // 主题目录
+    entryFile: 'src/index.ts', // 入口文件
+    whitelist: (name) => true, // 主题白名单（可选）
+  },
+
+  // 文件命名配置
+  naming: {
+    language: 'EN',
+    format: '无',
+    supplier: 'AIX',
+    follower: 'ZQL',
+  },
+};
+```
+
+**输出示例**：
+
+```
+dist-all/
+  ├── My-Three-Game/              # 项目名称目录
+  │   ├── facebook/
+  │   │   └── My-Three-Game-EN-无-2月-20260224-AIX-ZQL-facebook.html
+  │   ├── tiktok/
+  │   │   └── tiktok.zip
+  │   └── google/
+  │       └── google.zip
+
+  # 或启用主题切换后：
+  ├── theme1/
+  │   ├── facebook/
+  │   │   └── theme1-EN-无-2月-20260224-AIX-ZQL-facebook.html
+  │   └── google/
+  │       └── google.zip
+  └── theme2/
+      └── ...
+```
+
+## 脚本命令
+
+| 命令                         | 说明                                   |
+| ---------------------------- | -------------------------------------- |
+| `npm run dev`                | 启动开发服务器 (端口 8080)             |
+| `npm run dev <network>`      | 启动开发服务器并指定渠道调试           |
+| `npm run build -- <network>` | 构建指定渠道                           |
+| `npm run build:all`          | 批量构建（使用默认配置）               |
+| `npm run builds`             | 批量构建（使用配置文件）               |
+| `npm run webp`               | 将 assets 目录下的图片转换为 WebP 格式 |
+| `npm run webp:80`            | 以 80% 质量转换为 WebP 格式            |
+
+## 项目结构
+
+### 基础结构
+
+```
+playable-template-three/
+├── assets/              # 游戏资源目录（模型、纹理等）
+│   ├── textures/        # 纹理贴图
+│   ├── models/          # 3D 模型
+│   └── ...
+├── scripts/
+│   ├── theme-builds.js      # 批量构建脚本（支持主题切换）
+│   └── convert-to-webp.js   # WebP 转换脚本
+├── src/
+│   ├── config/              # 配置文件
+│   │   ├── LoadingConfig.ts # Loading 页面配置
+│   │   └── ThemeConfig.ts   # 主题配置接口 ★
+│   ├── scenes/              # 场景类 ★
+│   │   └── PreloadScene.ts  # 预加载场景
+│   ├── theme/               # 主题配置 ★
+│   │   ├── current.ts       # 当前主题入口
+│   │   ├── blue-theme.ts    # 蓝色主题
+│   │   ├── green-theme.ts   # 绿色主题
+│   │   └── red-theme.ts     # 红色主题
+│   ├── managers/
+│   │   └── AudioManager.ts  # 音频管理器
+│   ├── index.ts             # 入口文件，SDK 初始化
+│   ├── Game.ts              # 游戏主逻辑
+│   ├── index.css            # 样式文件
+│   └── index.html           # HTML 模板
+├── build.json               # 构建配置
+├── builds.config.example.js # 批量构建配置模板
+├── package.json
+└── tsconfig.json
+```
+
+### 主题系统
+
+模板提供了完整的主题配置系统，支持：
+
+- **配置与代码分离**：主题是纯数据配置文件
+- **类型安全**：TypeScript 接口确保配置正确
+- **易于扩展**：添加新主题只需创建配置文件
+- **批量构建**：自动为每个主题构建所有渠道
+
+**主题配置示例**：
+
+```typescript
+// src/theme/blue-theme.ts
+import { ThemeConfig } from '../config/ThemeConfig';
+
+const config: ThemeConfig = {
+  name: '蓝色主题',
+  id: 'blue',
+
+  // 场景配置
+  sceneBackground: 0x001a2d, // 深蓝色背景
+
+  // 光照配置
+  ambientLightColor: 0xffffff,
+  ambientLightIntensity: 2,
+  directionalLightColor: 0xffffff,
+  directionalLightIntensity: 2,
+
+  // UI 配置
+  uiPrimaryColor: '#4a90e2',
+  uiTextColor: '#ffffff',
+  buttonStyle: {
+    fontSize: '35px',
+    fontWeight: 'bold',
+    textShadow: 'rgb(255 252 106 / 63%) 4px 3px 9px',
+  },
+
+  // 游戏配置
+  modelScale: 0.5,
+  rotationSpeed: 0.01,
+};
+
+export default config;
+```
+
+**使用主题配置**：
+
+```typescript
+import themeConfig from './theme/current';
+
+// 设置场景背景色
+this.scene.background = new THREE.Color(themeConfig.sceneBackground);
+
+// 使用光照配置
+const ambientLight = new THREE.AmbientLight(
+  themeConfig.ambientLightColor,
+  themeConfig.ambientLightIntensity,
+);
+
+// 使用 UI 配置
+button.style.color = themeConfig.uiTextColor;
+button.style.fontSize = themeConfig.buttonStyle.fontSize;
+```
+
+详细说明请查看 [src/theme/README.md](./src/theme/README.md)
+
+## 资源加载流程
+
+模板使用标准的 **PreloadScene** 模式进行资源加载：
+
+### 加载流程
+
+1. **PreloadScene 启动** - 显示 Loading UI
+2. **预加载资源** - 在 `preloadResources()` 中加载所有资源
+3. **等待完成** - 资源加载完成 + 最小显示时间到达
+4. **启动游戏** - 隐藏 Loading UI，初始化游戏场景
+5. **通知 SDK** - 调用 `sdk.start()` 通知游戏开始
+
+### 添加新资源
+
+在 `src/scenes/PreloadScene.ts` 的 `preloadResources()` 方法中添加：
+
+```typescript
+// 加载图片
+const image = new Image();
+image.src = imageAsset;
+image.onload = () => {
+  this.resources.myImage = image;
+  checkComplete();
+};
+
+// 加载 3D 模型
+const loader = new GLTFLoader();
+loader.load(modelAsset, (gltf) => {
+  this.resources.myModel = gltf;
+  checkComplete();
+});
+
+// 加载音频
+const audio = new Audio(audioAsset);
+audio.onloadeddata = () => {
+  this.resources.myAudio = audio;
+  checkComplete();
+};
+```
+
+### Loading 配置
+
+可以在 `src/config/LoadingConfig.ts` 中修改 Loading 页面的显示内容：
+
+```typescript
+export const LoadingConfig = {
+  LOGO_IMAGE: logoImage, // Logo 图片
+  APP_TITLE: 'Vita Mahjong', // 应用标题
+  APP_STARS: '★★★★★', // 评分星星
+  APP_DESC: 'Relaxing Vita Mahjong...', // 应用描述
+  LOADING_TEXT: 'Loading Playable Ads', // 加载文字
+  SCENE_DURATION: 100, // 最小显示时长（毫秒）
+  // ...
+};
+```
+
+## Three.js 基础示例
+
+### 创建简单 3D 场景
+
+```typescript
+import * as THREE from 'three';
+import { sdk } from '@playcraft/adsdk';
+
+export class Game {
+  private renderer: THREE.WebGLRenderer;
+  private scene: THREE.Scene;
+  private camera: THREE.PerspectiveCamera;
+  private cube: THREE.Mesh;
+
+  constructor(width: number, height: number) {
+    // 创建渲染器
+    this.renderer = new THREE.WebGLRenderer({ antialias: true });
+    this.renderer.setSize(width, height);
+    document.body.appendChild(this.renderer.domElement);
+
+    // 创建场景
+    this.scene = new THREE.Scene();
+
+    // 创建相机
+    this.camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
+    this.camera.position.z = 5;
+
+    // 创建立方体
+    const geometry = new THREE.BoxGeometry(1, 1, 1);
+    const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
+    this.cube = new THREE.Mesh(geometry, material);
+    this.scene.add(this.cube);
+
+    // 开始渲染循环
+    this.animate();
+
+    // 通知 SDK 游戏已准备好
+    sdk.start();
+  }
+
+  private animate = () => {
+    requestAnimationFrame(this.animate);
+
+    // 旋转立方体
+    this.cube.rotation.x += 0.01;
+    this.cube.rotation.y += 0.01;
+
+    this.renderer.render(this.scene, this.camera);
+  };
+
+  public resize(width: number, height: number): void {
+    this.camera.aspect = width / height;
+    this.camera.updateProjectionMatrix();
+    this.renderer.setSize(width, height);
+  }
+}
+```
+
+## 响应式适配
+
+### 处理窗口尺寸变化
+
+```typescript
+// index.ts
+sdk.on('resize', (size) => {
+  game.resize(size.width, size.height);
+});
+
+// Game.ts
+public resize(width: number, height: number): void {
+  // 更新相机宽高比
+  this.camera.aspect = width / height;
+  this.camera.updateProjectionMatrix();
+
+  // 更新渲染器尺寸
+  this.renderer.setSize(width, height);
+}
+```
+
+### 横竖屏适配建议
+
+对于 Three.js 项目：
+
+1. **使用 PerspectiveCamera**：自动根据宽高比调整视野
+2. **动态调整相机距离**：根据屏幕尺寸调整相机位置
+3. **UI 元素使用 CSS 定位**：将 UI 层与 3D 场景分离
+
+```typescript
+public resize(width: number, height: number): void {
+  const isLandscape = width > height;
+
+  // 横屏：相机距离较近
+  // 竖屏：相机距离较远（以看到更多内容）
+  this.camera.position.z = isLandscape ? 5 : 8;
+
+  this.camera.aspect = width / height;
+  this.camera.updateProjectionMatrix();
+  this.renderer.setSize(width, height);
+}
+```
+
+## 主题化批量构建
+
+### 什么是主题化构建？
+
+当你的 3D 游戏需要创建多个变体（如不同风格、不同配色）时，可以使用主题化构建功能。主题系统通过**配置文件**的方式抽离颜色、光照、样式等数据，而不需要重写整个游戏逻辑。
+
+### 主题配置 vs 完整代码
+
+**✅ 推荐：主题配置方式**（当前模板使用）
+
+```
+src/theme/
+├── current.ts       # 主题入口（批量构建时自动切换）
+├── blue-theme.ts    # 蓝色主题配置（纯数据）
+├── green-theme.ts   # 绿色主题配置（纯数据）
+└── red-theme.ts     # 红色主题配置（纯数据）
+```
+
+**优点**：
+
+- 配置简单，只需修改颜色、参数等数据
+- 游戏逻辑共享，代码量少
+- 易于维护和扩展
+
+**❌ 不推荐：完整代码方式**
+
+```
+src/theme/
+├── level1/
+│   └── index.ts     # 完整游戏代码
+├── level2/
+│   └── index.ts     # 完整游戏代码（重复）
+└── level3/
+    └── index.ts     # 完整游戏代码（重复）
+```
+
+**缺点**：
+
+- 代码重复，维护困难
+- 修改游戏逻辑需要同步所有主题
+- 文件体积大
+
+### 使用场景
+
+#### 场景1: 单主题项目（无需配置）
+
+只需要为多个渠道打包：
+
+```bash
+npm run build:all
+```
+
+#### 场景2: 多主题项目（使用主题配置）
+
+项目有多个主题，需要为每个主题 × 每个渠道打包：
+
+```bash
+# 1. 添加新主题配置
+# 在 src/theme/ 下创建 purple-theme.ts
+
+# 2. 运行批量构建（会自动识别所有主题）
+npm run builds
+
+# 3. 高级用法：指定主题和渠道
+npm run builds -- -t "blue-theme,green-theme"  # 只构建指定主题
+npm run builds -- -c "google,facebook"          # 只构建指定渠道
+```
+
+### 添加新主题
+
+**步骤1: 创建主题配置文件**
+
+```bash
+# 在 src/theme/ 下创建新文件
+touch src/theme/purple-theme.ts
+```
+
+**步骤2: 编写主题配置**
+
+```typescript
+// src/theme/purple-theme.ts
+import { ThemeConfig } from '../config/ThemeConfig';
+
+const config: ThemeConfig = {
+  name: '紫色主题',
+  id: 'purple',
+
+  sceneBackground: 0x2d1a3d, // 深紫色背景
+  ambientLightColor: 0xffccff,
+  ambientLightIntensity: 1.8,
+  directionalLightColor: 0xffaaff,
+  directionalLightIntensity: 2.1,
+
+  uiPrimaryColor: '#9b59b6',
+  uiTextColor: '#ffffff',
+  buttonStyle: {
+    fontSize: '35px',
+    fontWeight: 'bold',
+    textShadow: 'rgb(200 150 255 / 70%) 4px 3px 9px',
+  },
+
+  modelScale: 0.5,
+  rotationSpeed: 0.01,
+};
+
+export default config;
+```
+
+**步骤3: 测试主题**
+
+```typescript
+// 修改 src/theme/current.ts
+import config from './purple-theme'; // 切换到新主题
+export default config;
+```
+
+运行 `npm run dev` 预览效果
+
+**步骤4: 批量构建**
+
+```bash
+npm run builds  # 会自动识别并构建 purple-theme
+```
+
+### 工作原理
+
+批量构建脚本会：
+
+1. **扫描主题目录**：`src/theme/` 下所有 `*-theme.ts` 文件
+2. **遍历构建**：为每个主题 × 每个渠道进行构建
+3. **自动切换**：修改 `src/theme/current.ts` 的 import 语句
+4. **恢复原状**：构建完成后恢复原始文件
+
+完整文档请参考 [builds.config.example.js](./builds.config.example.js) 和 [src/theme/README.md](./src/theme/README.md)
+
+## SDK 事件
+
+模板已集成以下 SDK 事件：
+
+- `resize` - 屏幕尺寸变化（已实现响应式适配）
+- `pause` - 游戏暂停
+- `resume` - 游戏恢复
+- `volume` - 音量变化
+- `finish` - 游戏结束
+- `interaction` - 用户交互计数
+
+## SDK 生命周期集成
+
+- `sdk.init()` - 初始化，获取容器尺寸
+- `sdk.start()` - 游戏资源加载完成后调用
+- `sdk.finish()` - 游戏结束时调用
+- `sdk.install()` - 跳转应用商店
+
+## 配置说明
+
+`build.json` 配置项：
+
+| 字段          | 说明                           |
+| ------------- | ------------------------------ |
+| app           | 应用名称                       |
+| name          | 概念名称                       |
+| version       | 版本号                         |
+| language      | 语言                           |
+| googlePlayUrl | Google Play 链接               |
+| appStoreUrl   | App Store 链接                 |
+| filename      | 输出文件名（单渠道构建时使用） |
+
+## 性能优化建议
+
+### 1. 几何体优化
+
+```typescript
+// ✅ 推荐：复用几何体
+const geometry = new THREE.BoxGeometry(1, 1, 1);
+for (let i = 0; i < 100; i++) {
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+}
+
+// ❌ 避免：每次创建新几何体
+for (let i = 0; i < 100; i++) {
+  const geometry = new THREE.BoxGeometry(1, 1, 1); // 重复创建
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+}
+```
+
+### 2. 材质优化
+
+```typescript
+// ✅ 使用简单材质
+const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
+
+// ⚠️ 避免过多光照材质
+const material = new THREE.MeshPhongMaterial({
+  color: 0x00ff00,
+  specular: 0x111111,
+  shininess: 30,
+});
+```
+
+### 3. 纹理优化
+
+```typescript
+// 使用 WebP 纹理
+const textureLoader = new THREE.TextureLoader();
+const texture = textureLoader.load('assets/texture.webp');
+
+// 设置纹理过滤
+texture.minFilter = THREE.LinearFilter;
+texture.magFilter = THREE.LinearFilter;
+```
+
+### 4. 渲染优化
+
+```typescript
+// 开启抗锯齿
+this.renderer = new THREE.WebGLRenderer({ antialias: true });
+
+// 设置像素比（避免模糊）
+this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+
+// 限制帧率（移动设备）
+const fps = 30;
+const fpsInterval = 1000 / fps;
+let lastTime = Date.now();
+
+function animate() {
+  requestAnimationFrame(animate);
+
+  const now = Date.now();
+  const elapsed = now - lastTime;
+
+  if (elapsed > fpsInterval) {
+    lastTime = now - (elapsed % fpsInterval);
+    renderer.render(scene, camera);
+  }
+}
+```
+
+## 工具脚本
+
+### WebP 图片转换
+
+```bash
+# 使用默认质量（100%）
+npm run webp
+
+# 指定质量（80%，推荐）
+npm run webp:80
+```
+
+**优化效果**：
+
+- PNG → WebP: 减少 30-50% 文件大小
+- JPG → WebP: 减少 20-40% 文件大小
+
+## 常见问题
+
+### Q1: Three.js 场景为什么是黑色的？
+
+**A**: 可能原因：
+
+1. 没有添加光源（使用 MeshPhongMaterial 等需要光照的材质时）
+2. 相机位置或方向不对
+3. 对象在相机视野外
+
+**解决方案**：
+
+```typescript
+// 添加环境光
+const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
+scene.add(ambientLight);
+
+// 添加方向光
+const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
+directionalLight.position.set(1, 1, 1);
+scene.add(directionalLight);
+```
+
+### Q2: 如何加载 3D 模型？
+
+**A**: 使用 GLTFLoader：
+
+```typescript
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+const loader = new GLTFLoader();
+loader.load('assets/models/model.glb', (gltf) => {
+  scene.add(gltf.scene);
+});
+```
+
+### Q3: 移动端性能差怎么办？
+
+**A**:
+
+1. 降低多边形数量
+2. 使用简单材质（MeshBasicMaterial）
+3. 减少光源数量
+4. 限制帧率到 30fps
+5. 使用 LOD (Level of Detail)
+
+### Q4: 如何实现点击 3D 对象？
+
+**A**: 使用 Raycaster：
+
+```typescript
+const raycaster = new THREE.Raycaster();
+const mouse = new THREE.Vector2();
+
+renderer.domElement.addEventListener('click', (event) => {
+  // 计算鼠标位置
+  mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+
+  // 更新射线
+  raycaster.setFromCamera(mouse, camera);
+
+  // 检测相交对象
+  const intersects = raycaster.intersectObjects(scene.children);
+
+  if (intersects.length > 0) {
+    console.log('Clicked:', intersects[0].object);
+  }
+});
+```
+
+### Q5: 支持哪些渠道？
+
+**A**:
+
+- google (Google Ads)
+- facebook (Facebook)
+- tiktok (TikTok)
+- applovin (AppLovin)
+- ironSource (IronSource)
+- unity (Unity Ads)
+- moloco (Moloco)
+- liftoff (Liftoff)
+- bigoads (BigoAds)
+
+## 环境要求
+
+- Node.js >= 16.0.0
+- npm >= 7.0.0
+
+## 参考资料
+
+### 官方文档
+
+- [Three.js 官方文档](https://threejs.org/docs/)
+- [Three.js 示例](https://threejs.org/examples/)
+- [@playcraft/adsdk 文档](https://git.woa.com/ua_playable_game/playable-sdk)
+
+### 学习资源
+
+- [Three.js Fundamentals](https://threejs.org/manual/)
+- [Three.js Journey](https://threejs-journey.com/) (推荐)
+
+### 内部资源
+
+- [项目命名规范](https://iwiki.woa.com/p/4017321768)
+- [可玩广告最佳实践](https://iwiki.woa.com/ua_playable)
+
+## 许可证
+
+MIT