cocos2d-cli

cocos2d-cli

Cocos Creator 2.4.x scene/prefab command-line tool.

With this skill, AI can directly read and write .fire and .prefab files, support generating scenes/prefabs from simplified JSON or HTML, and preview UI structures via screenshots.

Quick Start

# 1. 查看帮助
cd <项目目录>
node scripts/tree.js --help

# 2. 查看节点树
node scripts/tree.js assets/main.fire

# 3. 创建预制体
node scripts/create-prefab.js panel.json assets/Panel.prefab

4. Screenshot Preview

node scripts/screenshot.js panel.json -o ./screenshots --width 750 --height 1334


## 命令全集

### tree - 查看节点树

```bash
node scripts/tree.js <场景.fire | 预制体.prefab>

Outputs the node tree structure in JSON format, including node names, child nodes, and component lists.

Note：

Default JSON output, AI can parse directly
Output format:{"name":"Canvas","children":[...],"components":[...]}
Custom script components depend on the mapping generated by the build command

get - Get properties (in development)

node scripts/get.js <文件> <节点路径> [属性名|组件类型]

Without the third parameter: returns all basic properties
Third parameter is a component type: returns all properties of that component
Third parameter is a property name: returns a single property

Node path format:Canvas、Canvas/MidNode、Canvas/GameScene/NodeA

set - Modify node properties (in development)

node scripts/set.js <文件> <节点路径> <属性名> <值>

Supported properties:name, active, x, y, width, height, anchorX, anchorY, opacity, scaleX, scaleY, rotation

set-component - Modify component properties (in development)

node scripts/set-component.js <文件> <节点路径> <组件类型> <属性名> <值>

Example:

node scripts/set-component.js assets/main.fire Canvas/Label Label string "Hello"

add - Add node (in development)

node scripts/add.js <文件> <父节点路径> <节点名称> [选项]

Options:--x=, --y=, --width=, --height=, --scaleX=, --scaleY=, --rotation=, --active=, --type=sprite|label|button, --string=, --fontSize=

remove / add-component / remove-component (in development)

node scripts/remove.js <文件> <节点路径>
node scripts/add-component.js <文件> <节点路径> <类型>
node scripts/remove-component.js <文件> <节点路径> <类型>

start-scene - Get the start scene path

node scripts/start-scene.js [项目路径]

Output format:db:assets/scene/main.fire

Without parameters, automatically detects the project root from the current directory

build - Build component mapping

node scripts/build.js <Cocos项目目录>

Scans library/imports, building a mapping from script hashes to class names. This must be executed before reading custom script components.

create-prefab - Create prefab (✅ Implemented)

# 从 JSON 创建
node scripts/create-prefab.js <json文件路径> <输出.prefab>

# 从 HTML 创建
node scripts/create-prefab.js <html文件路径> <输出.prefab>

create-scene - Create scene (in development)

node scripts/create-scene.js [JSON文件路径] <输出.fire>

When no JSON is passed, creates a default scene (with Canvas + Main Camera).

screenshot - JSON rendering screenshot (✅ Implemented)

node scripts/screenshot.js <json文件> [选项]

Options:

Parameter	Description	Default Value
`-o, --output <目录>`	Output directory	Current directory
`--width <数值>`	Viewport width	750
`--height <数值>`	Viewport height	1334
`--full-page`	Full-page screenshot	Enabled
`--no-full-page`	Viewport-only screenshot	-
`--debug-bounds`	Overlay node boundaries and names	-
`--timeout <毫秒>`	Screenshot timeout	30000
`--wait <毫秒>`	Wait after rendering	1000

Note: Depends on Playwright. Install it before first use:npx playwright install chromium

JSON Format Reference

Basic Structure

{
  "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 }
  ],
  "children": [
    {
      "name": "Btn",
      "width": 200,
      "height": 60,
      "components": ["sprite", "button"]
    }
  ]
}

Supported Node Fields

name, x, y, width, height, anchorX, anchorY, scaleX, scaleY, rotation, opacity, active, color(hexadecimal), components, children

Supported Component Types

Component Name	Key Configuration
`canvas`	-
`sprite`	-
`label`	`string`, `fontSize`, `lineHeight`, `horizontalAlign` (`left/center/right`), `verticalAlign`, `color`
`button`	-
`widget`	`isAlignLeft/Right/Top/Bottom`, `left/right/top/bottom`
`richText`	`string`, `fontSize`, `lineHeight`, `maxWidth`, `horizontalAlign`
`camera`	-

Coordinates and Layout Description

The default anchor point in Cocos Creator is at the node center (anchorX=0.5, anchorY=0.5），x/y is the offset relative to the parent node's center point.

Left alignment recommended:

{ "anchorX": 0, "horizontalAlign": "left" }

Right alignment recommended:

{ "anchorX": 1, "horizontalAlign": "right" }

Node Path Format

Canvas                          # 根节点
Canvas/MidNode                  # 二级节点
Canvas/GameScene/NodeA          # 三级节点

Automatic Project Root Detection

Before performing any operation, the tool automatically searches upward from the file path for the Cocos project root directory:

Searches upward starting from the directory containing the .fire / .prefab file
Finds the directory containing both assets/ and settings/project.json , which is the project root
After finding it, use it to locate data/script_map.json、library/imports/ and other project-level files

So when passing a file path, either a relative path or an absolute path is fine—the tool will automatically find the project root.

# 以下两种写法都能正确找到项目根
node scripts/tree.js assets/main.fire
node scripts/tree.js C:/Projects/MyGame/assets/ui/panel.prefab

Environment Requirements

Node.js >= 18
The project must be Cocos Creator 2.4.x
The screenshot command depends on Playwright:npx playwright install chromium

Notes

When AI executes commands, the working directory must be the Cocos project root directory (the directory containing assets/ and settings/ )
JSON input must be a file path; passing a JSON string is not supported
screenshot -o specifies the outputdirectory, not the image file name
set-component Whether it can be modified depends on whether the component class implements setProp
build needs to be run in a Cocos project directory with library/imports run in the Cocos project directory of
Creating a prefab/scene will automatically write the corresponding .meta file