SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场psd-to-cocos

psd-to-cocos

设计与创作

查看项目

更新于 10-16 08:56

技能介绍

PSD to Cocos 是一个将 Photoshop 设计稿一键转换为 Cocos Creator 可用布局参考的技能。

用途

将 PSD 设计稿转换为 Cocos Creator 的布局参考数据，自动导出 PNG 切片并生成坐标 JSON，支持中文图层名。

工作流程

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

主要能力

  • 将 PSD 图层结构转换为 Cocos 坐标布局 JSON。
  • 自动导出 PNG 切片并关联图片文件。
  • 支持中文图层名（通过 psd-layer-reader 的映射功能处理）。
  • 新版 CLI 支持批量处理、中文文件名转拼音、冲突策略、失败重试、进度显示、原子操作等增强功能。

使用方式

方式 1：AI 调用

当用户需要转换 PSD 时：确认 PSD 文件路径；运行完整转换流程：

python .claude/skills/psd-to-cocos/scripts/psd_to_cocos.py <psd_file> -o <output_dir>

输出结果给用户。

方式 2：命令行直接使用（旧版 - 基础功能）

基础用法

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

方式 3：新版 CLI（推荐 - 增强功能）

支持批量处理、中文文件名转拼音、冲突策略、失败重试等增强功能。

单个文件转换

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

新版 CLI 功能特性：批量处理（支持目录级批量转换，自动识别所有 PSD 文件）；中文转拼音（自动将中文 PSD 文件名转为拼音输出目录，如 首页.psd → shouye/）；冲突策略（支持 overwrite 覆盖、skip 跳过、rename 重命名、ask 询问）；失败重试（自动记录失败文件，支持 --retry 参数重试）；进度显示（实时显示转换进度和结果汇总）；原子操作（使用临时目录确保操作安全，失败不残留脏数据）。

依赖

必需技能：psd-layer-reader（导出 PSD 图层结构）、psd-slicer（导出 PNG 切片）。

Python 依赖：pip install psd-tools Pillow

输出格式

文件结构：

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

cocos_layout.json 结构示例：

{ "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" } ] }

坐标转换说明

PSD 和 Cocos 使用不同的坐标系：PSD 原点在左上角，Y 轴向下；Cocos 原点在左下角，Y 轴向上；PSD 无锚点，Cocos 锚点为中心 (0.5, 0.5)。

转换公式：

PSD bbox [x1, y1, x2, y2] → Cocos position

width = x2 - x1 height = y2 - y1 x = x1 + width / 2 y = (canvas_height - y2) + height / 2

脚本说明

scripts/psd_to_cocos.py：CLI 入口，协调完整转换流程。

scripts/converter.py：坐标转换模块，提供 bbox_to_cocos_position() 函数。

scripts/layout_generator.py：JSON 生成器，将 psd-layers.json 转换为 cocos_layout.json。

在 Cocos Creator 中使用

方式 A：手动创建（基础）

  1. 将 images/ 文件夹复制到 Cocos 项目的 assets/ 目录。
  2. 打开 cocos_layout.json 查看每个元素的坐标。
  3. 在 Cocos 场景中创建 Sprite 节点。
  4. 根据 cocos_position 设置节点位置。
  5. 根据 image_file 关联对应的图片资源。

方式 B：使用 PSDImporter 扩展（推荐）

本技能提供 Cocos 编辑器扩展，可一键自动导入。

  1. 安装扩展：将 assets/PSDImporter.ts 复制到你的 Cocos 项目：

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

  1. 准备资源：确保资源目录结构如下：

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

  1. 使用扩展：在 Cocos 场景中创建空节点（右键 → Create Empty Node）；选中节点，在 Inspector 面板点击 Add Component；选择 Custom Script → PSDImporter；在 Inspector 中配置：Layout Json 拖入 cocos_layout.json 文件，Images Path 图片资源路径（默认：psd-output/images），Verbose 是否显示详细日志；点击 Import To Scene 按钮。

  2. 自动导入：扩展会自动创建根节点（以 PSD 文件名命名）；为每个元素创建 Sprite 节点；自动设置位置、尺寸、锚点；自动加载并关联图片资源；在 Console 显示导入进度。

注意：图片资源需要在 Cocos 中先导入（拖入 assets 目录），扩展才能正确引用。

适用场景

适用于需要将 Photoshop 设计稿转换为 Cocos Creator 布局参考的游戏或应用 UI 开发流程，尤其适合包含中文图层名的设计稿。

限制与注意事项

  • 仅导出可见图层。
  • 中文图层名通过 psd-layer-reader 的映射功能处理。
  • 本技能不生成 .prefab 或 .scene 文件，仅生成参考 JSON。
  • 实际布局仍需在 Cocos 编辑器中手动完成。
  • 坐标基于 Cocos 3.8.4 的坐标系（锚点中心）。

故障排除

错误：psd-tools not installed → pip install psd-tools

错误：psd-layer-reader not found → 确保 psd-layer-reader 技能已安装在 .claude/skills/ 目录。

错误：无法提取画布尺寸 → 检查 PSD 文件是否包含有效的根图层边界框。