PlayCraft 构建系统核心包,提供 Playable Ads 的构建、打包和优化功能。
npm install @playcraft/buildPlayCraft 构建系统核心包,提供 Playable Ads 的构建、打包和优化功能。
- 多平台支持:支持 10+ 主流广告平台(Facebook、Snapchat、ironSource 等)
- 场景过滤:智能分析场景依赖,只打包选中场景使用的资源
- 资源优化:自动精简资源元数据,显著减少 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% 体积
生成 PlayCanvas 构建产物格式的 config.json。
参数:
- projectConfig: PlayCanvasProject | PlayCraftProject - 项目配置options
- : GenerateConfigOptions - 可选配置selectedScenes?: string[]
- - 选中的场景 ID 或名称列表projectDir?: string
- - 项目目录(用于加载完整场景文件)stripMetadata?: boolean
- - 是否精简资源元数据(默认 true)
返回值:Promise
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`:类型定义用于参数校验
-