@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 体积

使用方式

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 - config.json 对象

相关文档

• 构建架构设计
• 平台规格对照表
• 优化对照

License

MIT

支持的平台

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

使用

基础用法

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);

平台适配器

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：类型定义用于参数校验