npm package: @playcraft/cli
Description: > PlayCraft 命令行工具 - 本地开发助手与 Playable Ads 打包工具
Latest version: 0.0.27

# @playcraft/cli

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

[![npm version](https://img.shields.io/npm/v/@playcraft/cli.svg)](https://www.npmjs.com/package/@playcraft/cli)
[![npm downloads](https://img.shields.io/npm/dm/@playcraft/cli.svg)](https://www.npmjs.com/package/@playcraft/cli)

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

## ✨ 特性

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

## 📦 安装

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

```bash
npx @playcraft/cli <command>
```

### 全局安装

```bash
npm install -g @playcraft/cli
```

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

```bash
playcraft <command>
```

## 🚀 快速开始

### 1. 初始化配置

```bash
npx @playcraft/cli init
```

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

### 2. 启动本地开发服务

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

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

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

### 3. 打包 Playable Ads

```bash
# 交互式打包（推荐）
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 |

## 💡 使用示例

### 本地开发模式

```bash
# 1. 初始化配置
playcraft init

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

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

### 打包 Playable Ads

```bash
# 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
```

### 构建优化

```bash
# 🎬 场景选择（推荐！可减小 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`：

```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 会自动提供交互式场景选择：

```bash
playcraft build --platform facebook
```

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

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

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

**命令行模式**：
```bash
# 指定单个场景
playcraft build --platform facebook --scenes MainScene

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

详见：[场景选择功能文档](../../docs/cli/scene-selection-feature.md)

## 🔗 相关链接

- [PlayCraft 项目](https://github.com/your-org/playcraft)
- [完整文档](../../docs/cli/README.md)
- [快速开始指南](../../docs/cli/quick-start.md)
- [构建命令详解](../../docs/cli/build.md)
- [场景选择功能](../../docs/cli/scene-selection-feature.md)
- [配置文件说明](../../docs/cli/config.md)
- [平台规格对照](../../docs/cli/各渠道Playable规格对照表.md)

## 📝 许可证

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**Made with ❤️ by PlayCraft Team**