cocos2d-cli 1.6.1 → 1.6.3

package/README.md

@@ -1,142 +1,491 @@
-# cocos2d-cli
+# cocos2d-cli
 
-Cocos Creator 场景/预制体命令行操作工具，支持通过 CLI 或 AI 自动化创建和编辑游戏界面。
+Cocos Creator 2.4.x 场景 / 预制体命令行工具。
 
-## 功能
+它可以直接操作 `.fire` 和 `.prefab` 文件，也支持从简化 JSON 生成场景、预制体，以及通过截图方式快速预览 UI 结构。
 
-- 创建场景和预制体
-- 添加/删除节点和组件
-- 修改节点和组件属性
-- 查看节点树结构
-- 从简化 JSON 创建复杂界面
+适用场景：
+
+- 批量修改 Cocos Creator 资源
+- 通过脚本或 AI 自动生成 UI
+- 在不打开编辑器的情况下预览 JSON 描述的界面
+
+## 特性
+
+- 查看场景 / 预制体节点树
+- 查询节点属性和组件属性
+- 修改节点属性
+- 修改组件属性
+- 添加 / 删除节点
+- 添加 / 删除组件
+- 从 JSON 创建预制体
+- 从 JSON 创建场景
+- 构建脚本组件映射
+- 将 JSON 渲染为截图
+
+## 环境要求
+
+- Node.js >= 14
+- Cocos Creator 2.4.x
+
+> `screenshot` 命令依赖 `playwright`。
 
 ## 安装
 
+全局安装：
+
 ```bash
 npm install -g cocos2d-cli
 ```
 
-## 使用
+或在项目中直接使用：
+
+```bash
+npx cocos2d-cli --help
+```
+
+## 快速开始
+
+查看帮助：
+
+```bash
+cocos2d-cli --help
+```
+
+查看节点树：
+
+```bash
+cocos2d-cli tree assets/main.fire
+cocos2d-cli tree assets/panel.prefab
+```
+
+从 JSON 预览并生成预制体：
+
+```bash
+cocos2d-cli screenshot panel.json -o ./screenshots --width 750 --height 1334
+cocos2d-cli create-prefab panel.json assets/Panel.prefab
+```
+
+## 命令说明
+
+### tree
+
+查看场景或预制体的节点树。
+
+```bash
+cocos2d-cli tree <scene.fire | prefab.prefab>
+```
+
+示例：
+
+```bash
+cocos2d-cli tree assets/main.fire
+```
+
+### get
+
+获取节点属性，或获取节点上某个组件的属性。
+
+```bash
+cocos2d-cli get <文件> <节点路径> [属性名 | 组件类型]
+```
+
+说明：
+
+- 不传第三个参数：返回该节点全部基础属性
+- 第三个参数是组件类型：返回该组件全部属性
+- 第三个参数是属性名：返回该节点的单个属性
+
+示例：
+
+```bash
+cocos2d-cli get assets/main.fire Canvas
+cocos2d-cli get assets/main.fire Canvas/MidNode x
+cocos2d-cli get assets/main.fire Canvas/Label Label
+```
+
+### set
+
+修改节点属性。
+
+```bash
+cocos2d-cli set <文件> <节点路径> <属性名> <值>
+```
+
+当前支持的常用节点属性：
+
+- `name`
+- `active`
+- `x`
+- `y`
+- `width`
+- `height`
+- `anchorX`
+- `anchorY`
+- `opacity`
+- `scaleX`
+- `scaleY`
+- `rotation`
+
+示例：
+
+```bash
+cocos2d-cli set assets/main.fire Canvas/MidNode x 100
+cocos2d-cli set assets/main.fire Canvas/MidNode width 200
+cocos2d-cli set assets/main.fire Canvas/MidNode active false
+```
+
+### set-component
+
+修改节点上某个组件的属性。
+
+```bash
+cocos2d-cli set-component <文件> <节点路径> <组件类型> <属性名> <值>
+```
+
+示例：
+
+```bash
+cocos2d-cli set-component assets/main.fire Canvas/Label Label string "Hello"
+cocos2d-cli set-component assets/main.fire Canvas/Label Label fontSize 32
+cocos2d-cli set-component assets/main.fire Canvas/Sprite Sprite sizeMode 0
+```
+
+> 不同组件是否支持修改，取决于该组件类是否实现了 `setProp`。
+
+### add
+
+在指定父节点下添加新节点。
+
+```bash
+cocos2d-cli add <文件> <父节点路径> <节点名称> [选项]
+```
+
+支持选项：
+
+- `--x=<数值>`
+- `--y=<数值>`
+- `--width=<数值>`
+- `--height=<数值>`
+- `--scaleX=<数值>`
+- `--scaleY=<数值>`
+- `--rotation=<角度>`
+- `--active=true|false`
+- `--type=sprite|label|button`
+- `--string=<文本>`（配合 `--type=label`）
+- `--fontSize=<数值>`（配合 `--type=label`）
+
+示例：
+
+```bash
+cocos2d-cli add assets/main.fire Canvas NewSprite --type=sprite --x=100 --y=50 --width=120 --height=120
+cocos2d-cli add assets/main.fire Canvas Title --type=label --string=Hello --fontSize=32
+```
+
+### remove
+
+删除指定节点。
+
+```bash
+cocos2d-cli remove <文件> <节点路径>
+```
+
+示例：
+
+```bash
+cocos2d-cli remove assets/main.fire Canvas/MidNode
+```
+
+> 不能删除根节点。
+
+### add-component
+
+给节点添加组件。
+
+```bash
+cocos2d-cli add-component <文件> <节点路径> <组件类型>
+```
+
+当前命令中支持的组件类型：
+
+- `canvas`
+- `widget`
+- `sprite`
+- `label`
+- `button`
+- `camera`
+
+示例：
 
 ```bash
-cocos2d-cli help          # 查看帮助
-cocos2d-cli --help        # 同上
+cocos2d-cli add-component assets/main.fire Canvas/NewNode sprite
+cocos2d-cli add-component assets/main.fire Canvas/Main Camera camera
 ```
 
-### 创建预制体
+### remove-component
+
+删除节点上的组件。
 
-### 创建预制体
+```bash
+cocos2d-cli remove-component <文件> <节点路径> <组件类型>
+```
+
+示例：
 
 ```bash
-# 创建空预制体
-cocos2d-cli create-prefab ./MyPrefab.prefab
+cocos2d-cli remove-component assets/main.fire Canvas/NewNode sprite
+```
+
+### create-prefab
 
-# 从 JSON 创建预制体
-cocos2d-cli create-prefab ./ui.json ./MyPrefab.prefab
+创建预制体。
+
+```bash
+cocos2d-cli create-prefab [JSON文件路径] <输出路径.prefab>
 ```
 
-### 创建场景
+行为说明：
+
+- 只传输出路径：创建默认预制体
+- 传入 JSON 文件：根据 JSON 创建预制体
+- 会自动生成对应 `.meta` 文件
+
+示例：
 
 ```bash
-# 创建默认场景（含 Canvas 和 Main Camera）
-cocos2d-cli create-scene ./MyScene.fire
+cocos2d-cli create-prefab assets/NewNode.prefab
+cocos2d-cli create-prefab panel.json assets/Panel.prefab
+```
 
-# 从 JSON 创建场景
-cocos2d-cli create-scene ./ui.json ./MyScene.fire
+### create-scene
+
+创建场景。
+
+```bash
+cocos2d-cli create-scene [JSON文件路径] <输出路径.fire>
 ```
 
-### 节点操作
+行为说明：
+
+- 只传输出路径：创建默认场景
+- 默认场景包含 `Canvas` 和 `Main Camera`
+- 若能在上级目录找到 `settings/project.json`，会读取设计分辨率
+- 会自动生成对应 `.meta` 文件
+
+示例：
 
 ```bash
-# 添加节点
-cocos2d-cli add ./MyPrefab.prefab Root NewNode --type=sprite --width=100 --height=100
+cocos2d-cli create-scene assets/Main.fire
+cocos2d-cli create-scene scene.json assets/Scene.fire
+```
+
+### build
 
-# 删除节点
-cocos2d-cli remove ./MyPrefab.prefab Root/NewNode
+扫描 Cocos Creator 项目的 `library/imports`，构建脚本哈希到类名的映射文件，用于更好地识别自定义脚本组件。
 
-# 查看节点树
-cocos2d-cli tree ./MyPrefab.prefab
+```bash
+cocos2d-cli build <项目目录>
 ```
 
-### 组件操作
+示例：
 
 ```bash
-# 添加组件
-cocos2d-cli add-component ./MyPrefab.prefab Root label
+cocos2d-cli build D:/my-cocos-project
+```
+
+输出文件默认写到：
 
-# 删除组件
-cocos2d-cli remove-component ./MyPrefab.prefab Root label
+```text
+cocos2d-cli/data/script_map.json
+```
+
+### screenshot
+
+将 JSON 渲染为页面并截图。
+
+```bash
+cocos2d-cli screenshot <json文件> [选项]
 ```
 
-### 属性操作
+支持选项：
+
+- `-o, --output <目录>` 输出目录，默认当前目录
+- `--width <数值>` 视口宽度，默认 `750`
+- `--height <数值>` 视口高度，默认 `1334`
+- `--full-page` 全页截图（默认）
+- `--no-full-page` 仅视口截图
+- `--debug-bounds` 叠加节点边界和名称
+- `--timeout <毫秒>` 默认 `30000`
+- `--wait <毫秒>` 默认 `1000`
+
+示例：
 
 ```bash
-# 获取属性
-cocos2d-cli get ./MyPrefab.prefab Root width
-cocos2d-cli get ./MyPrefab.prefab Root label.string
+cocos2d-cli screenshot data.json
+cocos2d-cli screenshot data.json -o ./screenshots
+cocos2d-cli screenshot data.json --width 1080 --height 1920
+cocos2d-cli screenshot data.json --debug-bounds
+```
+
+> `-o` / `--output` 是输出目录，不是输出图片文件名。
+
+## 节点路径格式
 
-# 设置属性
-cocos2d-cli set ./MyPrefab.prefab Root width 200
-cocos2d-cli set ./MyPrefab.prefab Root label.string "Hello"
+节点路径使用 `/` 分隔：
+
+```text
+Canvas
+Canvas/MidNode
+Canvas/GameScene/NodeA
 ```
 
-## 简化 JSON 格式
+如果路径首段和根节点同名，工具会自动兼容。
+
+## JSON 格式
 
-AI 可以通过简化 JSON 描述界面结构：
+### 基本示例
 
 ```json
 {
-  "name": "MyButton",
-  "width": 200,
-  "height": 60,
-  "components": ["sprite", "button"],
+  "name": "Panel",
+  "width": 400,
+  "height": 300,
+  "x": 0,
+  "y": 0,
+  "anchorX": 0.5,
+  "anchorY": 0.5,
+  "color": "#336699",
+  "opacity": 255,
+  "components": [
+    "sprite",
+    { "type": "label", "string": "Hello", "fontSize": 28, "horizontalAlign": "center" }
+  ],
   "children": [
     {
-      "name": "Label",
-      "components": [
-        {
-          "type": "label",
-          "string": "Click Me",
-          "fontSize": 24
-        }
-      ]
+      "name": "Btn",
+      "width": 200,
+      "height": 60,
+      "components": ["sprite", "button"]
     }
   ]
 }
 ```
 
-### 支持的组件类型
+### 常用节点字段
+
+- `name`
+- `x`, `y`
+- `width`, `height`
+- `anchorX`, `anchorY`
+- `scaleX`, `scaleY`
+- `rotation`
+- `opacity`
+- `active`
+- `color`
+- `components`
+- `children`
+
+### JSON 中支持的组件类型
+
+- `canvas`
+- `widget`
+- `sprite`
+- `label`
+- `button`
+- `camera`
+- `richText`
+
+### 组件示例
+
+`label`：
+
+```json
+{
+  "type": "label",
+  "string": "文本内容",
+  "fontSize": 28,
+  "lineHeight": 40,
+  "horizontalAlign": "left",
+  "verticalAlign": "center",
+  "color": "#ffffff"
+}
+```
+
+`richText`：
+
+```json
+{
+  "type": "richText",
+  "string": "普通<color=#ff0000>红色</color>文字<br/>第二行",
+  "fontSize": 28,
+  "lineHeight": 40,
+  "maxWidth": 600,
+  "horizontalAlign": "left"
+}
+```
+
+`widget`：
+
+```json
+{
+  "type": "widget",
+  "isAlignLeft": true,
+  "isAlignRight": true,
+  "isAlignTop": true,
+  "isAlignBottom": true,
+  "left": 0,
+  "right": 0,
+  "top": 0,
+  "bottom": 0
+}
+```
+
+## 坐标与布局说明
 
-- `canvas` - Canvas
-- `widget` - Widget
-- `sprite` - Sprite
-- `label` - Label
-- `button` - Button
-- `camera` - Camera
+Cocos 默认锚点在节点中心：
 
-### 节点属性
+- `anchorX = 0.5`
+- `anchorY = 0.5`
 
-| 属性 | 说明 |
-|------|------|
-| `name` | 节点名称 |
-| `active` | 是否激活 |
-| `x`, `y` | 位置 |
-| `width`, `height` | 尺寸 |
-| `scaleX`, `scaleY` | 缩放 |
-| `rotation` | 旋转角度 |
-| `anchorX`, `anchorY` | 锚点 |
-| `opacity` | 透明度 |
-| `color` | 颜色 (十六进制如 "#ff0000") |
+因此 `x / y` 通常是相对父节点中心点的偏移。
 
-## 架构
+对于左对齐 / 右对齐文本，更推荐：
 
+- `anchorX: 0` + `horizontalAlign: "left"`
+- `anchorX: 1` + `horizontalAlign: "right"`
+
+示例：
+
+```json
+{
+  "name": "Amount",
+  "anchorX": 1,
+  "x": 330,
+  "width": 300,
+  "components": [
+    { "type": "label", "string": "¥40.00", "horizontalAlign": "right" }
+  ]
+}
 ```
-输入                      内存模型                    输出
-─────                     ────────                   ─────
-简化JSON ──→ json-parser ──→ CCNode树 ─┬─→ CCSceneAsset ──→ .fire
-编辑器文件 ──→ fromJSON ──→ CC对象树 ──┘─→ CCPrefab ──→ .prefab
+
+## 注意事项
+
+1. JSON 输入必须是文件路径，不支持直接传 JSON 字符串
+2. `screenshot` 的输出参数是目录，不是图片路径
+3. `set-component` 是否可修改，取决于组件类是否实现 `setProp`
+4. `create-scene` 不传 JSON 时，会创建默认场景（含 `Canvas` 和 `Main Camera`）
+5. `create-prefab` / `create-scene` 会自动写入 `.meta` 文件
+6. `build` 生成的脚本映射会写入项目内的 `data/script_map.json`
+
+## 项目结构
+
+```text
+bin/cocos2d-cli.js     # CLI 入口
+src/commands/          # 各命令实现
+src/lib/               # 场景/节点/组件处理逻辑
+data/script_map.json   # 脚本组件映射
 ```
 
 ## License
 
-MIT
+MIT

package/bin/cocos2d-cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/**     
+/**       
  * Cocos Creator CLI
  * Command-line tools for AI to read and manipulate Cocos Creator 2.4.x project scenes
  */
@@ -81,41 +81,21 @@ add 支持的选项:
   --string=<文字>        Label 文字内容 (配合 --type=label)
   --fontSize=<数值>      Label 字体大小 (配合 --type=label)
 
-JSON 格式 (create-prefab / create-scene):
-  注意: 参数必须是 JSON 文件路径，不支持直接传递 JSON 字符串
-
+JSON 格式:
+  详见 SKILL.md 完整文档。简要示例：
   {
-    "name": "节点名称",
-    "width": 400,
-    "height": 300,
-    "x": 0,
-    "y": 0,
-    "color": "#336699",
-    "opacity": 255,
+    "name": "Node",
+    "width": 400, "height": 300,
+    "x": 0, "y": 0,
+    "anchorX": 0, "color": "#336699",
     "components": [
-      "sprite",
-      { "type": "widget", "top": 0, "left": 0, "right": 0, "bottom": 0 },
-      { "type": "label", "string": "Hello", "fontSize": 32 }
+      { "type": "label", "string": "Hello", "horizontalAlign": "left" },
+      { "type": "richText", "string": "<color=#3cb034>绿色</color>" }
     ],
     "children": [...]
   }
 
-  节点属性: name, width, height, x, y, color, opacity, anchorX, anchorY, rotation, scaleX, scaleY, active
-
-  组件写法:
-    简写: "sprite" 或 "label"
-    完整: { "type": "sprite", "sizeMode": 1 }
-    完整: { "type": "label", "string": "文本", "fontSize": 32, "color": "#fff" }
-
-  组件类型:
-    sprite   - 精灵（默认白色方块，节点设置什么颜色就显示什么颜色）
-    label    - 文本，支持 string, fontSize, color(兼容)
-    button   - 按钮，通常配合 sprite 使用才能看见
-    widget   - 对齐，支持 top, bottom, left, right
-    layout   - 布局，自动排列子节点
-    canvas   - 画布，根节点使用
-    camera   - 相机
-    particle - 粒子效果
+  提示：配合 anchorX + horizontalAlign 实现靠左/靠右布局（见 SKILL.md）
 
 示例:
   cocos2d-cli tree assets/main.fire
@@ -141,7 +121,7 @@ JSON 格式 (create-prefab / create-scene):
 
   # 截图
   cocos2d-cli screenshot data.json
-  cocos2d-cli screenshot data.json -o ./screenshots -w 1080 -h 1920
+  cocos2d-cli screenshot data.json -o ./screenshots --width 1080 --height 1920
 `);
 }
 

package/package.json

@@ -1,10 +1,10 @@
 {
-  "name": "cocos2d-cli", 
-  "version": "1.6.1",
+  "name": "cocos2d-cli",
+  "version": "1.6.3",
   "description": "Command-line tools for AI to read and manipulate Cocos Creator 2.4.x project scenes",
   "main": "bin/cocos2d-cli.js",
   "bin": {
-    "cocos2d-cli": "./bin/cocos2d-cli.js"
+    "cocos2d-cli": "bin/cocos2d-cli.js"
   },
   "files": [
     "bin",