lua-ui-to-json · diff
git:20261008.12ce13c to git:20261009.89747c7
10 added, 8 removed. Audit A to A.
---
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 检查、预览异常时读取。
+ - [NanoVG 提取与回放](references/nanovg.md)：原始 nvg 自绘、曲线、渐变图层的提取、编辑与引擎接入。
- [检查命令](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 | 在提取结果通过检查后，接入项目现有加载包装并迁移行为绑定 |
+ | 用户任务 | 行为 |
+ | ---------------------------- | ----------------------------------------------------------------------------------- |
+ | 没有 UI JSON，想在编辑器使用 | 调查活动页面，提取页面壳、必要组件和动态模板；保持游戏入口不变 |
+ | 已有 UI JSON | 先检查现有文件及调用方，保留用户编辑；不要重新生成覆盖 |
+ | NanoVG 自绘 UI | 读取 NanoVG 指引，按命名绘图层捕获；保留原路径和渐变，不用 Panel 或截图冒充矢量支持 |
+ | 预览缺图、缺节点、布局错误 | 先运行检查，再按排错表区分导出、资源、编辑器、引擎和动态状态问题 |
+ | 明确要求游戏使用 JSON | 在提取结果通过检查后，接入项目现有加载包装并迁移行为绑定 |
## 必须完成的闭环
1. **调查**：确定游戏根目录、活动 UI 入口、设计尺寸、工厂函数、主题、加载器版本和初始化后的样式修改。不可仅遍历文件名猜活动页面。先读取 `.project/project.json` 的 `taptap_publish.screen_orientation`，再从 UI 根节点、布局包装或 `scripts/` 中确认设计分辨率；方向和分辨率必须写入转换记录，不能让编辑器用默认竖屏猜测。
- 2. **转换**：按转换规范保留约束和资源路径。区分页面、组件、模板与行为；不强制把同图片拆成组件，不因预览不支持而改变节点类型。
+ 2. **转换**：按转换规范保留约束和资源路径。区分页面、组件、模板与行为；固定菜单、配置定义的页签不能仅因使用循环就导出成空列表。自绘页面须提取实际绘图层，不能只登记面板矩形。
3. **已有文件对照**：同名文件存在时比较来源和用户改动。无法确认时停在差异说明，不覆写；复用现有 ID 和加载包装。
- 4. **静态检查**：运行本目录脚本，逐项修复确定性错误，审阅警告。检查只读、不执行 Lua，也不自动写文件。
+ 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` 必须随报告交付。