---
name: lua-ui-to-json
description: 将 UrhoX Lua UI 提取为 .ui.json，检查已有导出文件，并诊断编辑器预览缺图、缺节点或布局差异。用于 UI 数据化与导出验收，不用于重写玩法或把任意 Lua 编译为 JSON。
---

# UrhoX UI 转换与检查

目标是保留原 UI 的视觉结构、布局约束和行为边界，而不是生成“能解析”的截图快照。
默认只提取文件，不改游戏入口；用户明确要求接入时，才迁移加载与绑定。

## 使用随包资料

本 Skill 随 Maker MCP 和客户端插件分发，不需要下载独立编辑器仓库。
通过 `taptap-maker status --target-dir <游戏根目录>` 获取当前安装的 Skill 路径，按任务读取：

- [转换规范与用例](references/conversion.md)：转换或接入游戏前读取。
- [检查与排错](references/diagnostics.md)：已有 JSON 检查、预览异常时读取。
- [检查命令](scripts/check-ui.cjs) 与 [共享规则](scripts/ui-json-check.cjs)：两个脚本随包提供。

检查脚本要求 Node.js 22，无需安装依赖。直接运行提供的脚本，不另写一份近似检查器。
相对链接以本 skill 目录为基准，不以用户游戏目录为基准。

## Maker 项目与编辑器

- 使用用户指定或控制台当前选中的游戏根目录，全程绑定同一项目；不能把 MCP 安装目录当游戏目录。
- 输出放在该项目 `assets/ui/` 下；新增资源和 UI 文件后显式调用 Maker MCP `generate_resource_meta`，保留已有有效 meta。
- 在 Maker 控制台「UI 编辑器」点击「刷新文件」打开结果。可用控制台 URL 的 `page=ui-editor&ui=assets/相对路径` 定位文档，保留当前项目参数并编码路径。
- 编辑器直接保存当前项目，默认不修改游戏加载入口。顶部问号链接到外部示例，仅供参考。
- 设计稿拆图、PNG 素材组装使用 `maker-ui-workflow`；本 Skill 负责已有 Lua UI 的提取与检查。

## 根据任务选择入口

| 用户任务 | 行为 |
|---|---|
| 没有 UI JSON，想在编辑器使用 | 调查活动页面，提取页面壳、必要组件和动态模板；保持游戏入口不变 |
| 已有 UI JSON | 先检查现有文件及调用方，保留用户编辑；不要重新生成覆盖 |
| 预览缺图、缺节点、布局错误 | 先运行检查，再按排错表区分导出、资源、编辑器、引擎和动态状态问题 |
| 明确要求游戏使用 JSON | 在提取结果通过检查后，接入项目现有加载包装并迁移行为绑定 |

## 必须完成的闭环

1. **调查**：确定游戏根目录、活动 UI 入口、设计尺寸、工厂函数、主题、加载器版本和初始化后的样式修改。不可仅遍历文件名猜活动页面。先读取 `.project/project.json` 的 `taptap_publish.screen_orientation`，再从 UI 根节点、布局包装或 `scripts/` 中确认设计分辨率；方向和分辨率必须写入转换记录，不能让编辑器用默认竖屏猜测。
2. **转换**：按转换规范保留约束和资源路径。区分页面、组件、模板与行为；不强制把同图片拆成组件，不因预览不支持而改变节点类型。
3. **已有文件对照**：同名文件存在时比较来源和用户改动。无法确认时停在差异说明，不覆写；复用现有 ID 和加载包装。
4. **静态检查**：运行本目录脚本，逐项修复确定性错误，审阅警告。检查只读、不执行 Lua，也不自动写文件。

   ```bash
   node <skill目录>/scripts/check-ui.cjs --project "<游戏根目录>" --format json
   ```

   检查单文件：

   ```bash
   node <skill目录>/scripts/check-ui.cjs --project "<游戏根目录>" --file assets/ui/page.ui.json --format json
   ```

   这一步必须在导出后执行，不能只确认 JSON 可解析。检查报告中的项目配置、页面方向、资源错误和模板警告都要保留；发现 `UI_DESIGN_ORIENTATION`、解析错误或缺图时，先修导出结果再交付。

5. **覆盖与视觉验收**：按项目配置选择横屏/竖屏设备，逐个打开所有页面和被引用模板，点击编辑器“适应”，对照活动源页面、初始化状态、不同长宽比、模板默认值和边界数据。编辑器检查按钮只检查当前文档，不能替代全项目 CLI 检查。没有引擎运行条件时明确记为未验证。含 `$repeat`、模板参数或运行时插入节点的页面必须标成“静态壳已预览 / 动态内容待运行时验证”；缺少运行时数据时显示空态是预期，不得为了填满画布伪造列表项或把页面判为完整。
6. **交付**：给出新增/修改文件、页面与源代码对应关系、留在 Lua 的行为、错误/警告数量、未验证项，以及“仅提取”还是“已接入游戏”。引用实际输出，不编造通过结果。

## 不可用修补掩盖的问题

- 不为填满预览而展开存档驱动列表、强制 `visible: true` 或给透明根加底色。
- 不忽略项目横竖屏配置，也不把方向错误造成的留白或白屏归因于 JSON 缺失；先检查设计分辨率、设备选择和适应视图。
- 不把百分比/flex/相对定位全部冻结成某个屏幕上的坐标。
- 不统一强制某个项目的设计分辨率、图片路径、主题颜色或九宫格参数。
- 不将 `onClick`、函数、事件订阅或业务状态序列化成字符串。
- 不把编辑器 `$repeat` 或预览参数回写成引擎已经支持的事实。
- 不自动安装工具、提交、推送、部署或修改用户未授权的游戏入口。

## 验收等级

区分“结构与已实现规则通过”“编辑器预览通过”“引擎视觉/交互通过”。
脚本退出 0 只表示**执行到的静态规则没有 error**，不是全面正确；警告和 `skipped` 必须随报告交付。