msw-ui-system

msw-ui-system

MSW .ui 单一入口——将设计指南＋组件 API＋构建器调用＋运行时模式整合为一个技能。

与现有技能的分工：

技能	职责
msw-ui-system（本技能）	所有 .ui 相关内容——设计（选什么／何时用／为什么）、组件 API／枚举（是什么）、构建器调用（如何修改）、运行时 mlua 模式。.ui 修改必须始终通过本技能的构建器完成
references/templates/	预构建样式包——.ui + ruid-map + 按钮处理程序包

---

0. 路由

根据请求关键词跳转到相应的子参考文档。

触发词	参考文档
“anchor/pivot/coordinates/why is the position wrong”、“RectTransform”、“stretch”	references/ui-fundamentals.md §1–§8
“mobile”、“safe area”、“1920”、“MobileOnly”、“ActivePlatform”、“touch size”、“PC reserved zone”、“font size by device”	references/ui-fundamentals.md §9
“UIGroup”、“above popup”、“z-order”、“displayOrder”、“CanvasGroup”、“opacity propagation”、“Enable vs Visible”	references/ui-hierarchy.md；如需在运行时重新排序同级元素，也请阅读 references/runtime-patterns.md §7
“which component”、“Sprite vs Text vs Button”、“9-slice”、“scroll list”、“GridView vs ScrollLayoutGroup”	references/component-api.md §“Component Selection Guide”
“sprite pivot”、“9-slice border”、“slice boundary”、“set sliced asset metadata”、“resource storage properties”	直接通过 msw-mcp 的 asset_update_resource_storage_info 设置资源端元数据；.ui 端请参阅 references/component-api.md §“SpriteGUIRenderer — ImageType Selection”
“make a HUD”、“popup placement”、“toast”、“menu”、“inventory grid”、“scroll list”、“ranking”、“leaderboard”、“quest list”、“friend list”、“mailbox”	references/layout-recipes.md
“connect .mlua after building with .ui builder”、“property default UUID”、“binding without drag”	../msw-general/references/builder-protocol-ui.md §3.6 Binding Injection（统一入口——请与 builder-protocol.md 核心文档一起加载）
运行时 UI 组件字段读写、组件属性名称／类型（ButtonComponent.Colors、TextGUIRendererComponent.Overflow、SpriteGUIRendererComponent.FillAmount……）	每次通过 .mlua 访问 UI 组件字段前，都必须阅读 references/component-api.md
枚举值（AlignmentType、TextOverflowMode、ImageType、UIBasicParticleType……）	references/component-api.md §Enums
运行时 mlua 模式（弹窗打开／关闭、Toast 渐隐、HP 条、GridView、拖拽、标签页、冷却）；运行时 UI 注意事项（仅限客户端、服务端为 nil 等）	references/runtime-patterns.md
.ui 构建器调用方法（UIBuilder API、锚点预设、写入时自动 lint、组件添加／修补／移除）	../msw-general/references/builder-protocol-ui.md §3 UIBuilder（统一入口——请与 builder-protocol.md 核心文档一起加载；.map MapBuilder／.model ModelBuilder 位于同级的各构建器文件中）
“sound”、“sfx”、“click sound”、“hover sound”、“button audio”、“PlaySound”	references/ui-sound.md

---

1. 基本工作流

(1) Clarify intent       Layout sketch (ASCII or verbal) + which group to attach to
(2) Check design guide   Match at least one of ui-fundamentals / ui-hierarchy / component-api §Component Selection Guide
(3) Builder Preflight    Read ../msw-general/references/builder-protocol.md (core) + builder-protocol-ui.md §3 (unified call-protocol entry point)
(4) Match recipe          Select the closest template from layout-recipes.md
(5) Invoke builder        Create/patch via scripts/msw_ui_builder.cjs (protocol: builder-protocol-ui.md §3)
(6) Inject bindings       Auto-inject .mlua property default UUIDs via b.write(path, { bind: {...} }) or b.injectBindings(...) (builder-protocol-ui.md §3.6 Binding Injection)
(7) Self-verify           write() auto-runs scripts/ui_lint.cjs (strict ON by default)
(8) Preview               Visual check via scripts/preview_ui_layout.cjs
(9) Sound pass            For any interactive button, offer click/hover SFX wiring (references/ui-sound.md)
(10) Maker Refresh         Apply to engine

2. 全局规则

禁止事项

1. 不要直接编辑 .ui JSON — 创建/修改 .ui 必须通过 scripts/msw_ui_builder.cjs。手动编辑会破坏 UUID、ValueType 与 @components 的一致性，并导致内容被静默丢弃。
2. 读取现有 .ui 文件也要通过构建器 — 使用 UIBuilder.read(filepath) / .find() / .listEntities() 查询。不要直接搜索或解析原始 JSON。
   • 注册的防护机制会阻止直接 Read .ui 文件，以及 cat / type / Get-Content / rg / grep / sed / awk / cp / mv 等 shell 命令。读取请使用 UIBuilder.read/load/snapshot，写入请使用 b.write()。构建器没有删除整个 .ui 文件的 API — 使用 node -e "require('fs').unlinkSync('ui/<File>.ui')" 删除，然后执行 refresh（防护机制会阻止 shell rm / cat；不会阻止通过 node -e 调用构建器）。
3. 直接设置 Position — 仅使用 anchoredPosition（Position 由引擎管理）
4. 在固定锚点（AnchorsMin == AnchorsMax）上通过 OffsetMin/Max 表示尺寸，同时使用 anchoredPosition — 不要混用两种模式
5. 构建器会创建新的 UUID，但不会更新 .mlua 属性默认值 — 绑定会失效

始终遵守

1. 构建器协议预检 — 在修改任何 .ui 之前，必须将 ../msw-general/references/builder-protocol.md（核心）和 ../msw-general/references/builder-protocol-ui.md §3 纳入上下文（仅当本会话中尚未加载或因压缩而丢失时才阅读）（UIBuilder API、写入时自动 lint、位置/锚点规则、绑定注入、覆盖缺口）。核心文档包含共享约定和跨构建器工作流；.map MapBuilder / .model ModelBuilder 的内容位于各自的构建器专属文件中 — 由于跨流程相互关联，因此使用统一入口。
2. 调用构建器前，至少查阅一份设计指南（ui-fundamentals / ui-hierarchy / component-api §Component Selection Guide）
3. 优先匹配现有方案；只有在最后不得已时才从头构建
4. 边缘位置使用公式：pos = ±(margin + size/2)
5. 将弹出窗口和提示消息放在各自独立的 .ui 根 UIGroup 中，并单独显示/隐藏；内部容器使用 empty() / panel()，切勿嵌套 group()
6. “我把它居中了，但它还是贴在左侧” → 文本带有显式的 UpperLeft(0) 对齐值 — 设置为 MiddleCenter(4)。两代文本组件的对齐默认值都是居中
7. 按钮触摸目标尺寸 ≥ 88×88（支持移动设备）
8. 创建任何可交互按钮后 — 主动建议通过 references/ui-sound.md 为其接入点击/悬停音效（可用默认 UI SFX RUID）。仅当用户明确选择不接入，或按钮纯属装饰时才跳过。
9. 树形结构应嵌套构建，而不是扁平构建。 同一单元的控件（窗口 + 标题/关闭按钮、行 + 标签/数值、槽位 + 图标/数量）必须通过 "Parent/Child" 路径共享一个父节点，以便作为一个整体移动 / 淡入淡出 / 切换 / 绑定。先创建每个父节点，再创建其子节点；父节点缺失会导致 lint 失败（L025 ERROR）。
10. 不要在根级文本上叠放同级盒子。 ui_lint 会将此情况报告为 L030 WARN。将文本嵌套到盒子下；对于可点击的带标签盒子，使用 button()；或者通过 panel() / sprite() 的 text 选项直接添加标签。

3. 子文档

• references/ui-fundamentals.md — 坐标系、RectTransform 的 3 个元素、锚点模式判定（§1–§8）+ 分辨率、安全区域、PC 预留区域、触控目标、字体大小、平台区分（§9）
• references/ui-hierarchy.md — UIGroup / displayOrder / CanvasGroup / Enable 与 Visible
• references/component-api.md — §「组件选择指南」（选哪个／何时选／为什么选）+ 完整的组件属性／方法／事件表（有什么）+ 所有 UI 相关枚举值（§Enums）
• references/layout-recipes.md — 布局模板集合
• references/runtime-patterns.md — .mlua 运行时模式（弹窗／Toast／HP／网格／拖拽……）+ 运行时 UI 注意事项
• references/ui-sound.md — UI 音效集成（_SoundService:PlaySound、点击／悬停钩子、默认 UI SFX RUID）
• ../msw-general/references/builder-protocol-ui.md §3 — .ui CJS 构建器调用协议（统一入口——需与 builder-protocol.md 核心一同加载） — .map MapBuilder / .model ModelBuilder 位于同级的各构建器文件中。panel / text / sprite / button / slider / scroll / script / group / mask / grid / avatar / touchReceive / skeleton / areaParticle / basicParticle、组件 CRUD、锚点预设、写入时自动 lint，以及 .mlua 属性 UUID 自动绑定，均位于 §3 + §3.6。
• references/templates/templates.md — 预构建样式包索引（style-N-* .ui、ruid-map.md、Popupbutton.mlua）

4. 脚本

• scripts/msw_ui_builder.cjs — .ui 构建器核心（UIBuilder 类）。使用前请阅读 ../msw-general/references/builder-protocol.md（核心）+ ../msw-general/references/builder-protocol-ui.md §3（统一入口）。
• scripts/preview_ui_layout.cjs — .ui 布局可视化检查 + 触控目标警告
• scripts/ui_lint.cjs — .ui 文件自检（由 write() 自动调用）
• scripts/ui_recipe.cjs — 基于配方的脚手架

---

范围之外

• .map / .model / .tileset 构建器 — 不属于此技能的范围
• .ui JSON 架构（原始字段结构、@type/@components 包装、AlignmentOption 0–15 映射等）— 由构建器在内部处理。用户／AI 无需直接了解
• 无障碍模式（替代文本、屏幕阅读器提示、焦点顺序）— 未涵盖
• 错误状态 UI 模式（Transition.Disabled 之外的禁用按钮样式、验证消息、加载旋转图标）— 未涵盖；请根据项目自行设计
• ui_lint.cjs 和 preview_ui_layout.cjs 之外的自动化 UI 测试／布局断言 — 未提供
• 自定义着色器材质（MaterialId）— 已提供字段，但着色器编写不属于此技能的范围