@playcraft/devkit 1.0.15-beta.1 → 1.0.17

package/README.md

@@ -0,0 +1,259 @@
+# @tencent/playable-scripts
+
+HTML5 Playable Ads 构建工具，支持多广告渠道打包。
+
+## 特性
+
+- 🚀 **一键构建** - 轻松为不同广告渠道生成构建包
+- ⚡ **自动优化** - 包含压缩、Tree-shaking 和死代码消除
+- 🗜️ **fflate 压缩** - 编译时压缩，运行时解压，体积减少 40-60%
+- 🎯 **多渠道支持** - 支持 Google Ads、Meta、AppLovin、Unity、IronSource、BigoAds 等
+- 🎨 **主题系统** - 支持多主题批量构建
+- 🔄 **并发构建** - 智能并发，大幅提升构建效率
+
+## 快速开始
+
+### 安装
+
+```bash
+tnpm install --save-dev @tencent/playable-scripts
+```
+
+### 配置 package.json
+
+```json
+{
+  "scripts": {
+    "dev": "playable-scripts dev",
+    "build": "playable-scripts build",
+    "builds": "playable-scripts builds"
+  }
+}
+```
+
+### 启动开发服务器
+
+```bash
+npm run dev                 # 默认预览模式
+npm run dev bigoads         # 指定渠道调试
+npm run dev -- --port 8080  # 指定端口
+```
+
+### 构建指定渠道
+
+```bash
+npm run build google        # Google Ads
+npm run build facebook      # Meta
+npm run build unity         # Unity Ads
+npm run build bigoads       # BigoAds
+```
+
+### 批量构建
+
+```bash
+npm run builds                              # 构建所有渠道
+npm run builds -- -t "theme1,theme2"        # 指定主题
+npm run builds -- -c "google,facebook"      # 指定渠道
+npm run builds -- --parallel 4              # 指定并发数
+
+# Windows PowerShell 兼容格式（推荐）
+npm run builds -- "theme1" "google"         # 位置参数：主题 渠道
+npm run builds -- --themes="theme1,theme2" --channels="google,facebook"
+```
+
+## 支持的广告渠道
+
+| 渠道 | 命令 | 协议 |
+|------|------|------|
+| Preview (预览) | `preview` | none |
+| Google Ads | `google` | none |
+| Meta (Facebook) | `facebook` | none |
+| AppLovin | `applovin` | mraid |
+| Unity Ads | `unity` | mraid |
+| IronSource | `ironsource` | mraid/dapi |
+| TikTok / Pangle | `tiktok` | none |
+| BigoAds | `bigoads` | bigo-mraid |
+| Adikteev | `adikteev` | mraid |
+| Moloco | `moloco` | none |
+| Liftoff | `liftoff` | mraid (ZIP) |
+| InMobi | `inmobi` | mraid |
+| Snapchat | `snapchat` | snapchat |
+
+## CLI 参数
+
+| 参数 | 描述             | 默认值       |
+|------|----------------|-----------|
+| **广告渠道** | 目标广告渠道         | `preview` |
+| `--out-dir` | 输出目录           | `dist`    |
+| `--obfuscate-level` | 代码混淆等级 (1-4)   | `4`       |
+| `--fflate-compression` | 启用 fflate 压缩   | `true`    |
+| `--protocol` | 广告协议           | 渠道自动决定    |
+| `--zip` | ZIP 输出结果       | `false`   |
+| `--port` | 开发服务器端口        | `3000`    |
+| `--open` | 自动打开浏览器        | `false`   |
+| `--language` | 语言代码           | `en`      |
+| `--is-channel-fold2zip ` | 所有渠道输出为 ZIP 结果 | `false`   |
+
+## 配置文件
+
+支持两种配置文件（推荐使用 `builds.config.js`）：
+
+### builds.config.js（推荐）
+
+```javascript
+module.exports = {
+  // 项目基本信息
+  projectName: 'My-Game',                    // 可选，默认 'Phaser Game'
+  googlePlayUrl: 'https://play.google.com/...', // 可选
+  appStoreUrl: 'https://apps.apple.com/...',    // 可选
+  
+  // 渠道配置
+  channels: ['google', 'facebook', 'unity'],    // 可选，有默认值
+  
+  // 主题配置（可选）
+  themes: {
+    enabled: true,                              // 默认 false
+    sourceDir: 'src/theme',                     // 默认 'src/theme'
+    entryFile: 'src/theme/index.ts',          // 默认 'src/theme/index.ts'
+    whitelist: null,                            // 可选，过滤函数
+  },
+  
+  // 文件命名配置（可选）
+  naming: {
+    language: 'EN',                             // 默认 'EN'
+    format: '无',                               // 默认 '无'
+    supplier: 'AIX',                            // 默认 'AIX'
+    follower: 'ZQL',                            // 默认 'ZQL'
+    generator: null,                            // 可选，自定义生成函数
+  },
+  
+  // 构建配置（可选）
+  build: {
+    outputDir: 'dist-all',                      // 默认 'dist-all'
+    tempDirPrefix: 'dist-temp',                 // 默认 'dist-temp'
+    continueOnError: true,                      // 默认 true
+    cleanTemp: true,                            // 默认 true
+    parallel: undefined,                        // 默认自动计算（CPU核心数-1，最小2最大8）
+  },
+  cosConfig: {
+    enabled: true,                              // 是否启用 COS 上传
+    SecretId: 'YOUR_SECRET_ID',                 // 腾讯云 SecretId
+    SecretKey: 'YOUR_SECRET_KEY',               // 腾讯云 SecretKey
+    Bucket: 'your-bucket-1234567890',           // COS 存储桶名称
+    Region: 'ap-guangzhou',                     // COS 区域
+    CdnDomain: 'your-cdn-domain.com',           // CDN 域名（用于生成访问链接）
+    PathPrefix: 'playable/preview',             // COS 路径前缀（可选）
+  },
+  // 打包参数（可选）
+  obfuscateLevel: 4,                            // 默认 4
+  fflateCompression: false,                      // 默认 true
+};
+```
+
+### build.json（向后兼容）
+
+```json
+{
+  "app": "AppName",
+  "name": "ConceptName",
+  "google_play_url": "https://play.google.com/...",
+  "app_store_url": "https://apps.apple.com/..."
+}
+```
+
+### 配置优先级
+
+```
+命令行参数 > build.json > builds.config.js > 默认值
+```
+
+## 代码混淆等级
+
+| 等级 | 名称 | 说明 | 体积影响 |
+|------|------|------|----------|
+| **1** | terser-only | 仅 Terser 压缩 | 基准 |
+| **2** | basic | 控制流平坦化 + 字符串编码 | +5~10% |
+| **3** | dead-code | 等级 2 + 死代码注入 | +15~25% |
+| **4** | maximum | 全部拉满（默认） | +30~50% |
+
+## fflate 压缩
+
+| 指标 | 效果 |
+|------|------|
+| **压缩率** | 66-68% |
+| **体积减少** | 40-60% |
+| **解压速度** | 3-5ms |
+| **兼容性** | 99%+ 浏览器 |
+
+## 批量构建
+
+### 特性
+
+1. **智能并发** - 自动根据 CPU 核心数优化（默认：核心数-1，最小2最大8）
+2. **独立临时目录** - 每个任务使用独立目录，避免冲突
+3. **主题切换** - 自动切换主题入口文件
+4. **错误容忍** - 单个失败不影响其他构建
+
+### 命令行参数
+
+| 参数 | 缩写 | 描述 | 示例 |
+|------|------|------|------|
+| `--themes` | `-t` | 指定主题列表（逗号分隔） | `-t "theme1,theme2"` |
+| `--channels` | `-c` | 指定渠道列表（逗号分隔） | `-c "google,facebook"` |
+| `--parallel` | `-p` | 指定并发数 | `-p 4` |
+| 位置参数 | - | 第一个参数=主题，第二个=渠道 | `"theme1" "google"` |
+| `=` 格式 | - | Windows PowerShell 兼容 | `--themes="theme1"` |
+
+**注意**：
+- **Mac/Linux**：所有格式均可使用
+- **Windows PowerShell**：推荐使用位置参数或 `--themes=value` 格式
+- **Windows CMD**：所有格式均可使用
+
+### 输出结构
+
+```
+dist-all/
+├── theme1/
+│   ├── google/
+│   │   └── theme1-EN-无-3月-20260304-AIX-ZQL-google.html
+│   └── facebook/
+│       └── theme1-EN-无-3月-20260304-AIX-ZQL-facebook.html
+└── theme2/
+    └── ...
+```
+
+## 全局变量
+
+构建时自动注入：
+
+| 变量 | 描述 | 示例 |
+|------|------|------|
+| `__DEV__` | 开发模式标志 | `true` / `false` |
+| `AD_NETWORK` | 当前广告渠道 | `"google"`, `"bigoads"` |
+| `AD_PROTOCOL` | 当前广告协议 | `"none"`, `"mraid"` |
+| `GOOGLE_PLAY_URL` | Google Play 链接 | `"https://..."` |
+| `APP_STORE_URL` | App Store 链接 | `"https://..."` |
+
+## 配套 SDK
+
+配合 `@tencent/playable-sdk` 使用：
+
+```bash
+tnpm install @tencent/playable-sdk
+```
+
+```javascript
+import { sdk } from '@tencent/playable-sdk';
+
+sdk.init((width, height) => {
+  new Game(width, height);
+});
+
+sdk.start();              // 游戏开始
+sdk.finish();             // 游戏结束
+sdk.install();            // 跳转商店
+```
+
+## 许可证
+
+MIT License

package/cli/bin/playable-scripts.js

@@ -1,2 +1,45 @@
 #!/usr/bin/env node
-"use strict";process.on("unhandledRejection",err=>{throw err});const spawn=require("cross-spawn");const args=process.argv.slice(2);const scriptIndex=args.findIndex(x=>x==="build"||x==="dev"||x==="vite-dev"||x==="builds"||x==="pack");const script=scriptIndex===-1?args[0]:args[scriptIndex];const nodeArgs=scriptIndex>0?args.slice(0,scriptIndex):[];if(["build","dev","vite-dev","builds","pack"].includes(script)){const result=spawn.sync(process.execPath,nodeArgs.concat(require.resolve("../commands/"+script)).concat(args.slice(scriptIndex+1)),{stdio:"inherit"});if(result.signal){if(result.signal==="SIGKILL"){console.log("The build failed because the process exited too early. "+"This probably means the system ran out of memory or someone called "+"`kill -9` on the process.")}else if(result.signal==="SIGTERM"){console.log("The build failed because the process exited too early. "+"Someone might have called `kill` or `killall`, or the system could "+"be shutting down.")}process.exit(1)}process.exit(result.status)}else{console.log("Unknown script \""+script+"\".")}
+
+'use strict';
+
+process.on('unhandledRejection', (err) => {
+  throw err;
+});
+
+const spawn = require('cross-spawn');
+
+const args = process.argv.slice(2);
+
+const scriptIndex = args.findIndex((x) => x === 'build' || x === 'dev' || x === 'vite-dev' || x === 'builds' || x === 'pack');
+
+const script = scriptIndex === -1 ? args[0] : args[scriptIndex];
+const nodeArgs = scriptIndex > 0 ? args.slice(0, scriptIndex) : [];
+
+if (['build', 'dev', 'vite-dev', 'builds', 'pack'].includes(script)) {
+  const result = spawn.sync(
+    process.execPath,
+    nodeArgs.concat(require.resolve('../commands/' + script)).concat(args.slice(scriptIndex + 1)),
+    {
+      stdio: 'inherit'
+    }
+  );
+  if (result.signal) {
+    if (result.signal === 'SIGKILL') {
+      console.log(
+        'The build failed because the process exited too early. ' +
+          'This probably means the system ran out of memory or someone called ' +
+          '`kill -9` on the process.'
+      );
+    } else if (result.signal === 'SIGTERM') {
+      console.log(
+        'The build failed because the process exited too early. ' +
+          'Someone might have called `kill` or `killall`, or the system could ' +
+          'be shutting down.'
+      );
+    }
+    process.exit(1);
+  }
+  process.exit(result.status);
+} else {
+  console.log('Unknown script "' + script + '".');
+}

package/cli/commands/build.js

@@ -1,26 +1,131 @@
-"use strict";process.env.BABEL_ENV="production";process.env.NODE_ENV="production";const fs=require("fs");const path=require("path");const{runBuild}=require("../../core/webpack.build.js");const{runThemeValidation,restoreSchema}=require("../../core/utils/validateThemeData");const{runPreBuildChecks}=require("../../core/validators/pre-build-checker.js");/**
+'use strict';
+
+process.env.BABEL_ENV = 'production';
+process.env.NODE_ENV = 'production';
+
+const fs = require('fs');
+const path = require('path');
+const { runBuild } = require('../../core/webpack.build.js');
+const { runThemeValidation, restoreSchema } = require('../../core/utils/validateThemeData');
+const { runPreBuildChecks } = require('../../core/validators/pre-build-checker.js');
+
+/**
  * 从主题入口文件中检测当前主题名称。
  * 支持以下模式：
  *   export { default } from './themeName';
  *   import Theme from './themeName';
- */function detectCurrentTheme(projectRoot){// 尝试加载 builds.config.js 获取主题配置
-const buildsConfigPath=path.join(projectRoot,"builds.config.js");let themeConfig={sourceDir:"src/theme",entryFile:"src/theme/index.ts"};if(fs.existsSync(buildsConfigPath)){try{delete require.cache[buildsConfigPath];const config=require(buildsConfigPath);if(config.themes){themeConfig={...themeConfig,...config.themes}}}catch(e){// 忽略错误
-}}const entryPath=path.join(projectRoot,themeConfig.entryFile);if(!fs.existsSync(entryPath)){return{themeName:null,themeConfig}}const content=fs.readFileSync(entryPath,"utf8");// 匹配: export { default } from './themeName' 或 import ... from './themeName'
-const match=content.match(/from\s+['"]\.\/([^'"]+)['"]/);if(match){return{themeName:match[1],themeConfig}}return{themeName:null,themeConfig}}// --- 主流程 ---
-const projectRoot=process.cwd();const{themeName,themeConfig}=detectCurrentTheme(projectRoot);let schemaPathToRestore=null;// ============================================================
+ */
+function detectCurrentTheme(projectRoot) {
+  // 尝试加载 builds.config.js 获取主题配置
+  const buildsConfigPath = path.join(projectRoot, 'builds.config.js');
+  let themeConfig = { sourceDir: 'src/theme', entryFile: 'src/theme/index.ts' };
+
+  if (fs.existsSync(buildsConfigPath)) {
+    try {
+      delete require.cache[buildsConfigPath];
+      const config = require(buildsConfigPath);
+      if (config.themes) {
+        themeConfig = { ...themeConfig, ...config.themes };
+      }
+    } catch (e) {
+      // 忽略错误
+    }
+  }
+
+  const entryPath = path.join(projectRoot, themeConfig.entryFile);
+  if (!fs.existsSync(entryPath)) {
+    return { themeName: null, themeConfig };
+  }
+
+  const content = fs.readFileSync(entryPath, 'utf8');
+
+  // 匹配: export { default } from './themeName' 或 import ... from './themeName'
+  const match = content.match(/from\s+['"]\.\/([^'"]+)['"]/);
+  if (match) {
+    return { themeName: match[1], themeConfig };
+  }
+
+  return { themeName: null, themeConfig };
+}
+
+// --- 主流程 ---
+const projectRoot = process.cwd();
+const { themeName, themeConfig } = detectCurrentTheme(projectRoot);
+
+let schemaPathToRestore = null;
+
+// ============================================================
 // 📌 编译前检查（埋点验证等）
 // ============================================================
 // 支持通过环境变量控制是否跳过检查
 // - SKIP_PRE_BUILD_CHECKS=1: 强制跳过检查
 // - PLAYABLE_BATCH_MODE=1: 批量构建模式，子进程自动跳过检查（主进程已执行）
-const isBatchMode=process.env.PLAYABLE_BATCH_MODE==="1";const shouldSkipChecks=process.env.SKIP_PRE_BUILD_CHECKS==="1"||isBatchMode;async function runPreChecks(){if(shouldSkipChecks){console.log("\n\u26A0\uFE0F  \u8DF3\u8FC7\u7F16\u8BD1\u524D\u68C0\u67E5\uFF08SKIP_PRE_BUILD_CHECKS=1\uFF09\n");return}const checkResult=await runPreBuildChecks(projectRoot,{verbose:false,showDetails:true,failFast:false});if(!checkResult.success){console.error("\n\u274C \u7F16\u8BD1\u524D\u68C0\u67E5\u5931\u8D25\uFF0C\u7EC8\u6B62\u6784\u5EFA\u3002");console.error("\u63D0\u793A\uFF1A\u5982\u9700\u8DF3\u8FC7\u68C0\u67E5\uFF0C\u53EF\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF: SKIP_PRE_BUILD_CHECKS=1\n");process.exit(1)}}// 执行编译前检查（异步）
-runPreChecks().then(()=>{// 检查通过后继续原有流程
-continueWithBuild()}).catch(err=>{console.error("\n\u274C \u7F16\u8BD1\u524D\u68C0\u67E5\u51FA\u9519:",err);process.exit(1)});function continueWithBuild(){// In batch mode (PLAYABLE_BATCH_MODE=1), the parent process has already
-// executed runThemeValidation and overwritten theme.schema.json5 with merged data.
-// Running it again in child processes would cause a race condition:
-//   1. Child reads the already-overwritten schema (pure data, no "properties"/"default")
-//   2. extractDefaultsFromSchema returns {} (empty)
-//   3. Child overwrites schema with {} → file becomes empty object
-const isBatchMode=process.env.PLAYABLE_BATCH_MODE==="1";if(themeName&&!isBatchMode){const buildLog=(msg,level)=>{const colors={info:"\x1B[36m",success:"\x1B[32m",error:"\x1B[31m"};const reset="\x1B[0m";const color=colors[level]||"";console.log(`${color}[build] ${msg}${reset}`)};const{valid,schemaPath}=runThemeValidation(themeName,projectRoot,themeConfig,{log:buildLog});schemaPathToRestore=schemaPath;if(!valid){// 校验失败时恢复 schema（备份可能已创建）
-if(schemaPathToRestore)restoreSchema(schemaPathToRestore);process.exit(1)}}// 执行构建，无论成功或失败都恢复 schema
-runBuild().then(()=>{if(schemaPathToRestore)restoreSchema(schemaPathToRestore)}).catch(err=>{if(schemaPathToRestore)restoreSchema(schemaPathToRestore);console.error(err);process.exit(1)})}
+const isBatchMode = process.env.PLAYABLE_BATCH_MODE === '1';
+const shouldSkipChecks = process.env.SKIP_PRE_BUILD_CHECKS === '1' || isBatchMode;
+
+async function runPreChecks() {
+  if (shouldSkipChecks) {
+    console.log('\n⚠️  跳过编译前检查（SKIP_PRE_BUILD_CHECKS=1）\n');
+    return;
+  }
+
+  const checkResult = await runPreBuildChecks(projectRoot, {
+    verbose: false,
+    showDetails: true,
+    failFast: false
+  });
+
+  if (!checkResult.success) {
+    console.error('\n❌ 编译前检查失败，终止构建。');
+    console.error('提示：如需跳过检查，可设置环境变量: SKIP_PRE_BUILD_CHECKS=1\n');
+    process.exit(1);
+  }
+}
+
+// 执行编译前检查（异步）
+runPreChecks().then(() => {
+  // 检查通过后继续原有流程
+  continueWithBuild();
+}).catch((err) => {
+  console.error('\n❌ 编译前检查出错:', err);
+  process.exit(1);
+});
+
+function continueWithBuild() {
+  // In batch mode (PLAYABLE_BATCH_MODE=1), the parent process has already
+  // executed runThemeValidation and overwritten theme.schema.json5 with merged data.
+  // Running it again in child processes would cause a race condition:
+  //   1. Child reads the already-overwritten schema (pure data, no "properties"/"default")
+  //   2. extractDefaultsFromSchema returns {} (empty)
+  //   3. Child overwrites schema with {} → file becomes empty object
+  const isBatchMode = process.env.PLAYABLE_BATCH_MODE === '1';
+
+  if (themeName && !isBatchMode) {
+    const buildLog = (msg, level) => {
+      const colors = { info: '\x1b[36m', success: '\x1b[32m', error: '\x1b[31m' };
+      const reset = '\x1b[0m';
+      const color = colors[level] || '';
+      console.log(`${color}[build] ${msg}${reset}`);
+    };
+
+    const { valid, schemaPath } = runThemeValidation(themeName, projectRoot, themeConfig, { log: buildLog });
+    schemaPathToRestore = schemaPath;
+
+    if (!valid) {
+      // 校验失败时恢复 schema（备份可能已创建）
+      if (schemaPathToRestore) restoreSchema(schemaPathToRestore);
+      process.exit(1);
+    }
+  }
+
+  // 执行构建，无论成功或失败都恢复 schema
+  runBuild()
+    .then(() => {
+      if (schemaPathToRestore) restoreSchema(schemaPathToRestore);
+    })
+    .catch((err) => {
+      if (schemaPathToRestore) restoreSchema(schemaPathToRestore);
+      console.error(err);
+      process.exit(1);
+    });
+}

package/cli/commands/builds.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
-"use strict";/**
+
+'use strict';
+
+/**
  * Batch Builds Command for playable-scripts
  * 
  * 支持：
@@ -13,4 +16,12 @@
  * playable-scripts builds -c "google,facebook"        # 指定渠道
  * playable-scripts builds -t "theme1" -c "google"     # 指定主题和渠道
  * playable-scripts builds --parallel 3                 # 设置并发数
- */process.on("unhandledRejection",err=>{throw err});const{buildBatch}=require("../../core/batch-build");buildBatch();
+ */
+
+process.on('unhandledRejection', (err) => {
+  throw err;
+});
+
+const { buildBatch } = require('../../core/batch-build');
+
+buildBatch();

package/cli/commands/dev.js

@@ -1 +1,7 @@
-"use strict";process.env.BABEL_ENV="development";process.env.NODE_ENV="development";const{runDev}=require("../../core/webpack.dev.js");runDev();
+'use strict';
+
+process.env.BABEL_ENV = 'development';
+process.env.NODE_ENV = 'development';
+
+const { runDev } = require('../../core/webpack.dev.js');
+runDev();