# @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
