npm package: @playcraft/build
Description: PlayCraft 构建系统核心包，提供 Playable Ads 的构建、打包和优化功能。
Latest version: 0.0.27

# @playcraft/build

PlayCraft 构建系统核心包，提供 Playable Ads 的构建、打包和优化功能。

## 功能特性

### 🎯 核心功能

- **多平台支持**：支持 10+ 主流广告平台（Facebook、Snapchat、ironSource 等）
- **场景过滤**：智能分析场景依赖，只打包选中场景使用的资源
- **资源优化**：自动精简资源元数据，显著减少 config.json 体积
- **两阶段构建**：基础构建 + 渠道适配，灵活高效

### 📦 config.json 优化

`config.json` 是 PlayCanvas 项目的核心配置文件，包含所有资源的元数据。在大型项目中，这个文件可能达到 2MB 甚至更大，严重影响 Playable Ads 的加载性能。

#### 优化策略

**1. 资源元数据精简（默认启用）**

自动删除运行时不需要的字段，包括：
- `tags` - 编辑器标签
- `i18n` - 国际化数据
- `meta` - 编辑器元数据
- `thumbnails` - 缩略图
- `revision` - 版本号
- `created_at` / `updated_at` - 时间戳
- `user` / `branch_id` - 用户和分支信息

**预期效果**：减少 30-50% 的 config.json 体积

**2. 场景依赖分析**

结合场景过滤功能，只包含选中场景实际使用的资源。

**预期效果**：减少 40-70% 的资源数量

**3. 组合优化**

同时启用元数据精简和场景过滤，可以实现最佳优化效果。

**预期效果**：总体减少 60-80% 的 config.json 体积

#### 使用方式

```typescript
import { generateConfig } from '@playcraft/build';

// 默认启用元数据精简
const config = await generateConfig(projectConfig, {
  selectedScenes: ['MainScene'],  // 场景过滤
  projectDir: './project',
  stripMetadata: true,  // 元数据精简（默认 true）
});

// 禁用元数据精简（保留完整元数据）
const configFull = await generateConfig(projectConfig, {
  stripMetadata: false,
});
```

#### 优化效果示例

```
🗜️  元数据精简统计:
  - 原始大小: 2048.5 KB
  - 精简后: 1024.3 KB
  - 节省: 1024.2 KB (50.0%)

📊 资源过滤统计:
  - 总资源数: 450
  - 场景依赖: 180
  - 将节省: 270 个资源 (60.0%)
```

#### 运行时兼容性

精简后的 config.json 完全兼容 PlayCanvas 引擎，所有运行时需要的字段都会保留：

- ✅ 资源 URL 和文件信息
- ✅ 纹理过滤和寻址模式
- ✅ 材质配置
- ✅ 模型映射信息
- ✅ 脚本加载配置
- ✅ 动画和音频时长
- ✅ 字体和精灵配置

#### 高级优化方案

如果需要进一步优化，可以考虑：

**方案二：数据压缩**
- 使用 lz4/gzip 压缩 config.json
- 运行时解压
- 预期减少 60-70% 体积

**方案三：按需加载**
- 只在 config.json 中保留资源引用
- 详细元数据按需加载
- 预期减少 70-80% 体积

## API 文档

### generateConfig(projectConfig, options?)

生成 PlayCanvas 构建产物格式的 config.json。

**参数**：
- `projectConfig`: PlayCanvasProject | PlayCraftProject - 项目配置
- `options`: GenerateConfigOptions - 可选配置
  - `selectedScenes?: string[]` - 选中的场景 ID 或名称列表
  - `projectDir?: string` - 项目目录（用于加载完整场景文件）
  - `stripMetadata?: boolean` - 是否精简资源元数据（默认 true）

**返回值**：Promise<any> - config.json 对象

## 相关文档

- [构建架构设计](../../docs/cli/build-architecture.md)
- [平台规格对照表](../../docs/cli/各渠道Playable规格对照表.md)
- [优化对照](../../docs/cli/playable-ads-optimization.md)

## License

MIT

## 支持的平台

- Facebook
- Snapchat
- ironSource
- AppLovin
- Google Ads
- TikTok/Pangle
- Unity Ads
- Liftoff
- Moloco
- BIGO Ads

## 使用

### 基础用法

```typescript
import { BaseBuilder, ViteBuilder, type BuildOptions } from '@playcraft/build';

// 阶段1：Base Build
const baseBuilder = new BaseBuilder('/path/to/project', {
  outputDir: './build',
});
const baseBuildResult = await baseBuilder.build();

// 阶段2：Channel Build
const buildOptions: BuildOptions = {
  platform: 'facebook',
  format: 'html',
  outputDir: './dist',
};

const viteBuilder = new ViteBuilder(baseBuildResult.outputDir, buildOptions);
const outputPath = await viteBuilder.build();
const sizeReport = viteBuilder.getSizeReport();

console.log('输出:', outputPath);
console.log('大小报告:', sizeReport);
```

### 平台适配器

```typescript
import { createPlatformAdapter } from '@playcraft/build';

const adapter = createPlatformAdapter({
  platform: 'facebook',
  format: 'html',
});

console.log(adapter.getName());          // "Facebook"
console.log(adapter.getSizeLimit());     // 2097152 (2MB)
console.log(adapter.getDefaultFormat()); // "html"
```

## 架构

```
@playcraft/build
├── BaseBuilder       # 阶段1：生成多文件构建产物
├── ViteBuilder       # 阶段2：Vite 单文件打包
├── PlayableBuilder   # 阶段2：旧构建器（兼容）
├── platforms/        # 平台适配器
│   ├── FacebookAdapter
│   ├── SnapchatAdapter
│   ├── IronSourceAdapter
│   ├── AppLovinAdapter
│   ├── GoogleAdapter
│   ├── TikTokAdapter
│   ├── UnityAdapter
│   ├── LiftoffAdapter
│   ├── MolocoAdapter
│   └── BigoAdapter
└── vite/             # Vite 插件
    ├── plugin-playcanvas
    ├── plugin-platform
    └── plugin-model-compression
```

## 依赖方

- `@playcraft/cli`：CLI 工具
- `@playcraft/worker`：队列消费与异步构建
- `@playcraft/backend`：类型定义用于参数校验