@tencent/playable-scripts

HTML5 Playable Ads 构建工具，支持多广告渠道打包。

特性

• 🚀 一键构建 - 轻松为不同广告渠道生成构建包
• ⚡ 自动优化 - 包含压缩、Tree-shaking 和死代码消除
• 🗜️ fflate 压缩 - 编译时压缩，运行时解压，体积减少 40-60%
• 🎯 多渠道支持 - 支持 Google Ads、Meta、AppLovin、Unity、IronSource、BigoAds 等
• 🎨 主题系统 - 支持多主题批量构建
• 🔄 并发构建 - 智能并发，大幅提升构建效率

快速开始

安装

tnpm install --save-dev @tencent/playable-scripts

配置 package.json

{
  "scripts": {
    "dev": "playable-scripts dev",
    "build": "playable-scripts build",
    "builds": "playable-scripts builds"
  }
}

启动开发服务器

npm run dev                 # 默认预览模式
npm run dev bigoads         # 指定渠道调试
npm run dev -- --port 8080  # 指定端口

构建指定渠道

npm run build google        # Google Ads
npm run build facebook      # Meta
npm run build unity         # Unity Ads
npm run build bigoads       # BigoAds

批量构建

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（推荐）

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（向后兼容）

{
  "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 使用：

tnpm install @tencent/playable-sdk

import { sdk } from '@tencent/playable-sdk';

sdk.init((width, height) => {
  new Game(width, height);
});

sdk.start();              // 游戏开始
sdk.finish();             // 游戏结束
sdk.install();            // 跳转商店

许可证

MIT License