SuperAPI AI Directory
Partner中文AI newsFavorites
Skillspsd-to-cocos

psd-to-cocos

Design & creation

View repository

Updated 10-16 08:56

About this skill

PSD to Cocos

Convert Photoshop designs into layout references usable by Cocos Creator with one click.

Workflow

PSD 文件
    ↓
psd-layer-reader (已有技能) → psd_layers.json (图层结构)
    ↓
psd-slicer (已有技能) → images/*.png (PNG 切片)
    ↓
psd-to-cocos (本技能) → cocos_layout.json (Cocos 坐标)

Usage

Method 1: AI invocation

When the user needs to convert a PSD:

  1. Confirm the PSD file path
  2. Run the complete conversion process: 
    python .claude/skills/psd-to-cocos/scripts/psd_to_cocos.py <psd_file> -o <output_dir>
  3. Output the result to the user

Method 2: Direct command-line usage (old version - basic features)

# 基础用法
python scripts/psd_to_cocos.py design.psd

# 指定输出目录
python scripts/psd_to_cocos.py design.psd -o ./assets/ui/

# 详细输出
python scripts/psd_to_cocos.py design.psd -v

Method 3: New CLI (recommended - enhanced features)

Supports batch processing, conversion of Chinese file names to pinyin, conflict policies, failure retry, and other enhanced features.

# 单个文件转换
python scripts/run_cli.py convert design.psd

# 指定输出目录
python scripts/run_cli.py convert design.psd -o ./output/

# 批量处理目录（交互式选择）
python scripts/run_cli.py convert psd-folder/

# 批量处理目录（全部转换）
python scripts/run_cli.py convert psd-folder/ --all

# 递归扫描子目录
python scripts/run_cli.py convert psd-folder/ --recursive

# 指定冲突策略（覆盖/跳过/重命名/询问）
python scripts/run_cli.py convert design.psd --conflict=skip

# 重试之前失败的文件
python scripts/run_cli.py convert psd-folder/ --retry

# 详细输出
python scripts/run_cli.py convert design.psd --verbose

New CLI features

  • Batch processing: Supports directory-level batch conversion, automatically identifying all PSD files
  • Chinese to pinyin: Automatically converts Chinese PSD file names to pinyin output directories (e.g. 首页.psd → shouye/）
  • Conflict policy: Supports overwrite(overwrite),skip(skip),rename(rename),ask(ask)
  • Failure retry: Automatically records failed files, supports the --retry parameter for retry
  • Progress display: Displays conversion progress and result summary in real time
  • Atomic operations: Uses a temporary directory to ensure operation safety, leaving no dirty data on failure

Dependencies

Required skills

  • psd-layer-reader - Export PSD layer structure
  • psd-slicer - Export PNG slices

Python dependencies

pip install psd-tools Pillow

Output format

File structure

output/
├── psd_layers.json       # 图层树（psd-layer-reader 生成）
├── images/               # PNG 切片（psd-slicer 生成）
│   ├── btn_login.png
│   └── ...
└── cocos_layout.json     # Cocos 布局参考（本技能生成）

cocos_layout.json structure

{
  "metadata": {
    "version": "1.0.0",
    "psd_file": "design.psd",
    "canvas_size": [1920, 1080],
    "export_time": "2026-02-15T10:30:00",
    "element_count": 25
  },
  "elements": [
    {
      "id": "btn_login",
      "name": "btn_login",
      "original_name": "按钮_登录",
      "type": "sprite",
      "visible": true,
      "psd_bbox": [100, 200, 300, 260],
      "cocos_position": { "x": 200.0, "y": 850.0 },
      "cocos_size": { "width": 200, "height": 60 },
      "cocos_anchor": { "x": 0.5, "y": 0.5 },
      "image_file": "images/btn_login.png"
    }
  ]
}

Coordinate conversion notes

PSD and Cocos use different coordinate systems:

Property PSD Cocos
Origin Top-left corner Bottom-left corner
Y-axis direction Downward Upward
Anchor point None Center (0.5, 0.5)

Conversion formula:

# PSD bbox [x1, y1, x2, y2] → Cocos position
width = x2 - x1
height = y2 - y1
x = x1 + width / 2
y = (canvas_height - y2) + height / 2

Script description

scripts/psd_to_cocos.py

CLI entry point, coordinating the complete conversion process.

scripts/converter.py

Coordinate conversion module, providing the bbox_to_cocos_position() function.

scripts/layout_generator.py

JSON generator, converting psd-layers.json to cocos_layout.json.

Using in Cocos Creator

Method A: Manual creation (basic)

  1. Copy the images/ folder to the Cocos project's assets/ directory
  2. Open cocos_layout.json to view the coordinates of each element
  3. Create a Sprite node in the Cocos scene
  4. According to cocos_position , set the node position
  5. According to image_file , associate the corresponding image asset

Method B: Use the PSDImporter extension (recommended)

This skill provides a Cocos editor extension, enabling one-click automatic import:

1. Install the extension

Copy assets/PSDImporter.ts to your Cocos project:

cp .claude/skills/psd-to-cocos/assets/PSDImporter.ts \
   <your-cocos-project>/assets/scripts/editor/

2. Prepare resources

Ensure the resource directory structure is as follows:

assets/
├── psd-output/              # Python 技能生成的输出
│   ├── images/              # PNG 切片
│   │   ├── btn_login.png
│   │   └── ...
│   └── cocos_layout.json    # 布局数据
└── scripts/
    └── editor/
        └── PSDImporter.ts   # 编辑器扩展

3. Use the extension

  1. Create an empty node in the Cocos scene (right-click → Create Empty Node)
  2. Select the node, in the Inspector panel click Add Component
  3. Select Custom Script → PSDImporter
  4. Configure in the Inspector:
    • Layout Json: drag in the cocos_layout.json file
    • Images Path: image resource path (default:psd-output/images）
    • Verbose: whether to show detailed logs
  5. Click the Import To Scene button

4. Automatic import

The extension will automatically:

  • Create a root node (named after the PSD file name)
  • Create a Sprite node for each element
  • Automatically set position, size, and anchor point
  • Automatically load and associate image resources
  • Display import progress in the Console

Note: image resources need to be imported into Cocos first (drag into the assets directory) before the extension can reference them correctly.

Notes

  • Only export visible layers
  • Chinese layer names are handled through the mapping function of psd-layer-reader mapping function processing
  • This skill does not generate .prefab or .scene files, only generates reference JSON
  • The actual layout still needs to be completed manually in the Cocos editor
  • Coordinates are based on the Cocos 3.8.4 coordinate system (anchor point center)

Troubleshooting

Error: psd-tools not installed

pip install psd-tools

Error: psd-layer-reader not found

Ensure the psd-layer-reader skill is installed in the .claude/skills/ directory.

Error: unable to extract canvas size

Check whether the PSD file contains a valid root layer bounding box.