@playcraft/cli

PlayCraft 命令行工具 - 本地开发助手与 Playable Ads 打包工具

PlayCraft CLI 是一个功能强大的命令行工具，支持本地代码与云端编辑器实时同步，以及将 PlayCanvas/PlayCraft 项目打包为多平台 Playable Ads。

✨ 特性

• 🚀 本地开发隧道 - 在本地 IDE 编写代码，云端编辑器实时预览与热更新
• 📦 Playable Ads 打包 - 支持 10 个主流广告平台的一键打包
• 🎬 智能场景选择 - 交互式场景选择，可减小 30-60% 文件大小（新功能）
• 🎯 两阶段构建 - Base Build + Channel Build，灵活可控
• ⚡ Vite 构建 - 使用 Vite 进行资源内联与压缩，性能优异
• 🖼️ 资源优化 - 自动图片压缩（PNG → WebP）、模型压缩（Draco）
• 🔧 交互式配置 - 友好的命令行交互，快速上手
• 📊 构建分析 - 生成详细的打包分析报告

📦 安装

使用 npx（推荐，无需安装）

npx @playcraft/cli <command>

全局安装

npm install -g @playcraft/cli

安装后可直接使用 playcraft 命令：

playcraft <command>

🚀 快速开始

1. 初始化配置

npx @playcraft/cli init

交互式创建 playcraft.config.json 配置文件。

2. 启动本地开发服务

# 前台运行
npx @playcraft/cli start --project <project-id>

# 后台运行（守护进程）
npx @playcraft/cli start --project <project-id> --daemon

启动后，云端编辑器会自动检测本地服务，直接读取本地文件进行运行与调试。

3. 打包 Playable Ads

# 交互式打包（推荐）
npx @playcraft/cli build

# 命令行打包
npx @playcraft/cli build --platform facebook --format html --output ./dist

📖 命令说明

开发相关

| 命令 | 说明 | 示例 | |------|------|------| | init | 交互式创建配置文件 | playcraft init | | start | 启动本地开发服务 | playcraft start --project <id> | | stop | 停止运行中的服务 | playcraft stop --project <id> | | status | 查看服务运行状态 | playcraft status | | logs | 查看服务日志 | playcraft logs --follow | | config | 读取/修改配置项 | playcraft config get --key projectId | | inspect | 检测项目类型与结构 | playcraft inspect . |

构建相关

| 命令 | 说明 | 示例 | |------|------|------| | build | 完整打包（阶段1 + 阶段2） | playcraft build --platform facebook | | build-base | 仅执行阶段1（生成多文件产物） | playcraft build-base ./src --output ./build | | build-playable | 仅执行阶段2（从多文件产物生成 Playable） | playcraft build-playable ./build --platform facebook | | analyze | 生成打包分析报告 | playcraft analyze --platform facebook |

🎯 支持的平台

现已支持 10 个主流广告平台：

| 平台 | 格式 | 大小限制 | SDK/API | |------|------|----------|---------| | Facebook | HTML/ZIP | HTML: 5MB / ZIP: 5MB（HTML < 2MB） | FbPlayableAd | | Snapchat | ZIP | 5MB | MRAID 2.0 | | ironSource | HTML | 5MB | MRAID + dapi | | AppLovin | HTML | 5MB | MRAID 2.0 | | Google Ads | ZIP | 5MB | ExitApi | | TikTok/Pangle | ZIP | 5MB | Pangle SDK | | Unity Ads | HTML | 5MB | MRAID 3.0 | | Liftoff | ZIP | 5MB | MRAID | | Moloco | HTML | 5MB | FbPlayableAd | | BIGO Ads | ZIP | 5MB | BIGO SDK |

💡 使用示例

本地开发模式

# 1. 初始化配置
playcraft init

# 2. 启动本地服务
playcraft start --project your-project-id

# 3. 在本地 IDE 编辑代码，云端编辑器自动同步

打包 Playable Ads

# Facebook 平台（单 HTML）
playcraft build --platform facebook --format html --output ./dist/facebook

# Snapchat 平台（ZIP）
playcraft build --platform snapchat --format zip --output ./dist/snapchat

# 批量打包所有平台
for platform in facebook snapchat ironsource applovin google tiktok unity liftoff moloco bigo; do
  playcraft build --platform $platform --output ./dist/$platform
done

构建优化

# 🎬 场景选择（推荐！可减小 30-60% 文件大小）
# 交互式选择（自动检测多个场景并提示）
playcraft build --platform facebook

# 指定特定场景
playcraft build --platform facebook --scenes BallGame

# 指定多个场景
playcraft build --platform facebook --scenes "MainMenu,Gameplay,Settings"

# 启用图片压缩
playcraft build --platform facebook --compress-images --image-quality 75

# 启用模型压缩
playcraft build --platform facebook --compress-models --model-compression draco

# 生成分析报告
playcraft build --platform facebook --analyze

# 组合使用（场景选择 + 图片压缩 + 分析）
playcraft build --platform facebook --scenes MainScene --compress-images --analyze

⚙️ 配置

配置文件 playcraft.config.json：

{
  "agent": {
    "projectId": "your-project-id",
    "token": "your-token",
    "port": 2468,
    "dir": "./"
  },
  "build": {
    "platform": "facebook",
    "format": "html",
    "outputDir": "./dist",
    "useVite": true,
    "compressImages": true,
    "imageQuality": 75,
    "convertToWebP": true,
    "compressModels": true,
    "modelCompression": "draco"
  }
}

配置优先级

1. CLI 参数（最高优先级）
2. 环境变量（PLAYCRAFT_PROJECT_ID/PLAYCRAFT_TOKEN/PLAYCRAFT_PORT）
3. 配置文件（playcraft.config.json）
4. 默认值

📁 数据目录

CLI 会在 ~/.playcraft/ 目录下存储：

• pids/ - 进程文件
• logs/ - 日志文件

🆕 最新功能

v0.0.9 - 场景选择优化 (2026-01-26)

当项目包含多个场景时，CLI 会自动提供交互式场景选择：

playcraft build --platform facebook

交互界面：

🎬 检测到 20 个场景
💡 提示: 只打包选中的场景可以显著减小文件大小（通常可减小 30-60%）

? 选择要打包的场景（使用空格选择，回车确认）:
❯◉ MainScene
 ◉ Gameplay
 ◯ TestScene
 ◯ DebugScene
 ...

优化效果：

• 🎯 单场景：减小 40-60%
• 🎯 2-3 个场景：减小 30-50%
• 🎯 自动过滤未使用的资源

命令行模式：

# 指定单个场景
playcraft build --platform facebook --scenes MainScene

# 指定多个场景
playcraft build --platform facebook --scenes "MainScene,Gameplay"

详见：场景选择功能文档

🔗 相关链接

• PlayCraft 项目
• 完整文档
• 快速开始指南
• 构建命令详解
• 场景选择功能
• 配置文件说明
• 平台规格对照

📝 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Made with ❤️ by PlayCraft Team