内容
# 设计到Unity
[中文介绍](README.zh-CN.md)
[GitHub 仓库](https://github.com/Crackerrrrrr/design-to-unity) · `Crackerrrrrr/design-to-unity`
<p align="center">
<img src="docs/assets/design-to-unity-flow.svg" alt="Design to Unity 工作流图" width="100%">
</p>
设计到Unity是一个MCP服务器，用于将Lanhu、Figma和PSD / Photoshop UI设计转换为结构化的交接包、可下载的资产和Unity-ready UGUI预制件YAML快照。
对于设计和游戏团队来说，它充当设计源和游戏UI生产之间的桥梁。MCP可以读取Lanhu页面和切片、Figma文件和插件导出、PSD / PSB层文档和Photoshop UXP导出；保留布局、文本、资产、组件提示、视觉效果、可重复使用的部分和风险元数据；然后生成Unity源映射、预制件YAML和Unity编辑器导入器输入，AI代理或Unity工具可以继续使用。
服务器是为AI辅助UI实施工作流而构建的：
- 通过MCP工具公开设计结构、位置、文本、资产和语义提示
- 准备另一个Unity MCP可以消耗的Unity交接数据
- 可选地直接编写静态UGUI预制件YAML以供快速检查
- 在生成的预制件旁边保留源映射和验证元数据
- 保留源特定的意图，例如Lanhu切片位置、Figma自动布局、PSD层效果、Photoshop文本元数据、组件实例、变体和图像填充，可用于Unity重建
## 为什么选择设计到Unity
| 优势 | 生产中的含义 |
| --- | --- |
| 统一设计包 | Lanhu、Figma、PSD / PSB和插件导出都成为相同的AI可读交接格式，而不是单独的转换器。 |
| 为AI代理提供更好的上下文 | 每个重要节点都可以公开几何形状、文本、资产、组件提示、渲染策略、源语义、置信度和原因。 |
| Unity-ready但不限于Unity | 包是引擎中立的，而Unity输出获得实用的预制件YAML、源映射、TMP文本、UGUI提示和编辑器导入器支持。 |
| 默认情况下可重复使用 | 图像哈希、Figma图像引用、组件键、可重复使用的预制件候选者、变体和9切片提示减少重复资产和重复UI工作。 |
| 更安全的迭代 | 就绪报告、源映射、增量导入器保护和视觉差异支持使生成的UI更容易检查和更新。 |
| 专为游戏UI设计 | 按钮、滑块、切换、滚动视图、列表、选项卡、输入、下拉菜单、布局组、掩模和画布提示是一流的转换目标。 |
## 源覆盖
| 源 | 设计到Unity保留的内容 |
| --- | --- |
| Lanhu | 项目页面、设计页面结构、切片资产、节点位置、文本、交接注释和Unity布局/组件提示。 |
| Figma | REST文件、框架、组件、插件导出、自动布局、约束、图像填充、变体、变量、原型反应和复杂的视觉警告。 |
| PSD / PSB | 层树、边界、可编辑的文本元数据（如果可用）、混合/效果风险标记、分组资产和栅格备用切片。 |
| Photoshop UXP导出 | `design.json`、`preview.png`、层PNG资产、文本元数据、语义标记和复杂的组栅格化提示。 |
| Unity输出 | 引擎中立的包、资产清单、可重复使用的预制件注册表、源映射、UGUI预制件YAML、就绪报告和编辑器导入器输入。 |
## 功能
- Lanhu项目和设计页面提取
- 通过REST API或本地JSON快照的Figma文件/框架/组件提取
- 批量Figma页面/组件库包准备和预制件YAML写入
- Figma插件导出，用于选定的框架/组件、嵌入式预览图像、手动语义标签和渲染的复杂视觉资产
- 本地PSD / PSB包准备
- Photoshop / UXP导出文件夹摄入
- 资产清单和切片元数据
- Unity布局和组件提示
- Figma自动布局填充、间距、子对齐、控制、展开和子布局元素提示被YAML /编辑器导入器输出消耗
- 节点渲染策略、视觉边界和源语义证据
- 资产`content_hash`元数据，以便相同的精灵只导入一次
- 可重复使用的预制件注册表，用于重复的按钮、选项卡、滑块和其他UI组件
- Figma组件变体属性作为可重复使用的预制件实例覆盖和Unity预制件变体候选者公开
- Figma圆角/描边元数据可以推断`nine_slice_hint.border`用于可拉伸的按钮、面板和卡片
- 可选的Figma变量被规范为Unity主题/令牌绑定
- Figma原型反应被保留为Unity导航/事件提示
- Figma约束被映射到Unity RectTransform锚点提示并被YAML /编辑器导入器输出消耗
- Figma模糊、混合模式、渐变/多个填充和掩模风险在源语义、视觉边界和就绪报告中公开
- Figma插件导出器包括约束、自动布局子大小、组件变体、原型反应、丰富文本覆盖元数据和复杂的视觉导出触发器
- 直接UGUI预制件YAML写入
- 预制件到设计的源映射生成
- 静态预制件YAML验证
- 可选的Unity编辑器验证器脚本安装
- 用于比较Unity截图与Figma / PSD设计引用的视觉差异助手
## 多源到Unity工作流
该管道设计用于不仅仅是截图恢复：
- 在线模式读取实时Lanhu和Figma设计源，包括页面、框架、组件、切片、样式、图像填充和导出URL。
- 本地模式读取Figma快照、PSD / PSB文件、Photoshop UXP导出和插件导出的设计文件夹，用于离线回归测试。
- 导出模式捕获选定的设计内容、手动语义标签、预览PNG、文本元数据和应该栅格化的复杂矢量/图像资产。
- 包保留`render_strategy`、`render_rect`、`visual_bounds`、`source_semantics`、源特定布局提示、文本元数据和可重复使用的预制件候选者。
- Unity输出可以作为快速预制件YAML生成或通过`DesignToUnityPrefabImporter.cs`导入以创建基于编辑器API的预制件创建、可重复使用的定义、嵌套实例和变体预制件资产。
支持的Unity UI组件提示包括：
- `Image`
- `TextMeshProUGUI`
- `Outline`
- `Shadow`
- `Button`
- `Slider`
- `Toggle`
- `ToggleGroup`
- `TMP_InputField`
- `TMP_Dropdown`
- `ScrollRect`
- `Scrollbar`
- `RectMask2D`
- `VerticalLayoutGroup`
- `HorizontalLayoutGroup`
- `GridLayoutGroup`
- `CanvasGroup`
## 快速入门
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
```
在`.env`中为Lanhu设置`LANHU_COOKIE`和/或为Figma设置`FIGMA_TOKEN`，然后运行：
```bash
DesignToUnity
```
对于stdio客户端：
```bash
MCP_TRANSPORT=stdio DesignToUnity
```
## Lanhu工具
- `lanhu_design_list`
- `lanhu_design_prepare_packet`
- `lanhu_design_get_packet`
- `lanhu_design_get_summary`
- `lanhu_design_get_node_tree`
- `lanhu_design_get_node_detail`
- `lanhu_design_get_asset_manifest`
- `lanhu_design_get_slices`
- `lanhu_design_get_unity_plan`
- `lanhu_design_get_handoff_profile`
- `lanhu_design_write_unity_prefab_yaml`
- `lanhu_design_verify_unity_prefab_yaml`
## Figma工具
- `figma_design_list_pages`
- `figma_design_list_frames`
- `figma_design_list_components`
- `figma_design_list_variables`
- `figma_design_get_export_schema`
- `figma_design_validate_export`
- `figma_design_prepare_packet`
- `figma_design_prepare_batch_packets`
- `figma_design_prepare_export_packet`
- `figma_design_export_assets`
- `figma_design_prepare_snapshot_packet`
- `figma_design_prepare_batch_snapshot_packets`
- `figma_design_get_component_usage`
- `figma_design_get_packet`
- `figma_design_get_summary`
- `figma_design_get_node_tree`
- `figma_design_get_node_detail`
- `figma_design_get_asset_manifest`
- `figma_design_get_slices`
- `figma_design_get_unity_plan`
- `figma_design_get_unity_readiness_report`
- `figma_design_compare_unity_screenshot`
- `figma_design_write_unity_prefab_yaml`
- `figma_design_write_batch_unity_prefab_yaml`
- `figma_design_verify_unity_prefab_yaml`
- `figma_design_convert_to_unity_prefab`
- `figma_design_convert_export_to_unity_prefab`
- `figma_design_install_unity_editor_importer`
## Unity编辑器导入器
- `design_to_unity_install_unity_editor_importer`
这将`Assets/Editor/DesignToUnity/DesignToUnityPrefabImporter.cs`安装到Unity项目中。导入器读取生成的`*.design-to-unity.json`源映射，并通过Unity编辑器API创建一个UGUI预制件，包括基本的TMP文本、图像、按钮、滑块、切换、滚动矩形、布局组、可重复使用的预制件定义/嵌套实例输出和Figma变体预制件资产。
安装后，使用Unity菜单：
```text
Tools/Design To Unity/Import Prefab From Source Map
```
或使用以下命令运行Unity批处理模式：
```bash
Unity -batchmode \
-projectPath /path/to/UnityProject \
-executeMethod DesignToUnityPrefabImporter.ImportFromCommandLine \
-d2uSourceMap Assets/DesignToUnity/<packet>/Prefabs/<name>.design-to-unity.json \
-d2uOutputPrefab Assets/DesignToUnity/<packet>/Prefabs/<name>.editor-imported.prefab \
-d2uIncremental true \
-d2uReport Assets/DesignToUnity/<packet>/Prefabs/<name>.import-report.json
```
当使用`-d2uIncremental true`并且输出预制件已经存在时，导入器会匹配源映射的`unity_path`条目，更新设计拥有的字段，创建新节点，并默认保留未匹配的现有子节点。在可重复使用的预制件替换过程中，用户添加的子节点将被移动到新的嵌套预制件实例中，而源拥有的节点具有自定义组件或持久事件绑定将被保护不被替换并报告。生成的导入报告记录了创建、更新、保留、保护、可重复使用的预制件定义、重复使用的预制件实例和预制件变体计数。
对于页面/组件库批次：
```bash
Unity -batchmode \
-projectPath /path/to/UnityProject \
-executeMethod DesignToUnityPrefabImporter.ImportFromCommandLine \
-d2uSourceMaps "Assets/DesignToUnity/a/Prefabs/a.design-to-unity.json;Assets/DesignToUnity/b/Prefabs/b.design-to-unity.json" \
-d2uOutputDir Assets/DesignToUnity/ImportedPrefabs \
-d2uIncremental true \
-d2uBatchReport Assets/DesignToUnity/import-batch-report.json
```
您还可以传递`-d2uSourceMapDir Assets/DesignToUnity`以导入文件夹下的每个`*.design-to-unity.json`源映射，或者在需要显式输出预制件路径时传递`-d2uOutputPrefabs`。
## TMP字体映射
Figma / PSD文本默认生成为可编辑的`TextMeshProUGUI`。在编写工具时传递`tmp_font_asset_guid` / `tmp_font_asset_map_json`，或在`.env`中配置默认值：
```env
UNITY_TMP_FONT_ASSET_GUID=
UNITY_TMP_FONT_ASSET_MAP_JSON={"figma_font_to_tmp":{"Inter":"11111111111111111111111111111111"}}
UNITY_TMP_FONT_ASSET_MAP_PATH=/path/to/font-map.json
```
就绪报告包括`font_requirements`、`missing_tmp_font_mapping_count`和样本节点，以便在Unity导入前修复缺少的TMP映射。
## PSD / Photoshop工具
- `psd_design_get_export_schema`
- `psd_design_validate_export`
- `psd_design_prepare_packet`
- `psd_design_prepare_export_packet`
- `psd_design_get_summary`
- `psd_design_get_node_tree`
- `psd_design_get_node_detail`
- `psd_design_get_asset_manifest`
- `psd_design_get_slices`
- `psd_design_get_unity_plan`
- `psd_design_get_unity_readiness_report`
- `psd_design_compare_unity_screenshot`
- `psd_design_install_unity_editor_validator`
- `psd_design_write_unity_prefab_yaml`
- `psd_design_verify_unity_prefab_yaml`
- `psd_design_convert_to_unity_prefab`
- `psd_design_convert_export_to_unity_prefab`
## Figma插件导出器
`templates/figma-plugin-exporter`中包含一个Figma插件导出器。
它导出一个单独的`*-design-to-unity.json`文件，其中包含选定的节点树、预览PNG、手动语义标签和嵌入的base64矢量/图像资产。MCP可以使用`figma_design_prepare_export_packet`读取它或直接使用`figma_design_convert_export_to_unity_prefab`转换。
## Photoshop UXP导出器
`templates/photoshop-uxp-exporter`中包含一个Photoshop UXP导出器。
它导出：
- `design.json`
- `preview.png`
- 层PNG资产
- 可编辑的文本元数据（如果Photoshop公开）
- 复杂的组栅格化标记
MCP可以使用`psd_design_prepare_export_packet`读取导出文件夹或直接使用`psd_design_convert_export_to_unity_prefab`转换。
## 重用和重复扣除
每个包都包含两个重用层：
- 资产重用：图像资产携带`content_hash` / `file_hash`；Figma图像填充还保留`source_image_ref` / `image_fill` / `source_image_fill_url`。直接Unity YAML编写器复制相同内容、相同Figma图像引用或相同源的精灵一次，然后为后续引用记录`duplicate_of` / `deduped_unity_asset_path`。
- 节点重用：组件候选者携带`reusable_prefab_key`和`reusable_prefab`。包级`reusable_prefabs`注册表列出定义节点、实例节点、建议的预制件路径和实例覆盖字段。
- 变体重用：Figma组件变体签名被分组到`prefab_variant_groups`中，包括基础预制件路径、变体轴、变体节点ID和建议的Unity预制件变体资产路径。
- 9切片重用：Figma图像/复杂节点，看起来像可拉伸的按钮、面板或卡片，并且带有圆角或描边数据，获取`nine_slice_hint.border`；Unity YAML编写器发出Sprite `spriteBorder`。
Unity MCP可以读取`reusable_prefabs`，保存定义节点一次，实例化其余节点来自该预制件，并应用矩形/文本覆盖。然后它可以读取`prefab_variant_groups`以创建特定于状态的预制件变体。实验性的直接YAML编写器仍然为兼容性展开完整的静态层次结构；Unity编辑器导入器使用源映射保存可重复使用的定义、创建变体预制件资产，并用实际的嵌套预制件实例替换后续实例。
## 直接Unity预制件YAML
直接编写器可以创建：
- 复制的精灵文件在Unity `Assets/...`文件夹下
- 确定的`.png.meta`文件
- `.prefab` YAML文件
- 配套的`*.design-to-unity.json`源映射
- 需要时配套的`.prefab.meta`文件
此路径旨在用于静态UI恢复、预制件审查和AI辅助后续工作。项目特定的业务脚本、动画连接和自定义运行时行为应在Unity中添加。
