msw-ui-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

msw-ui-system

MSW UI系统

MSW

.ui

single entry point — design guide + component API + builder invocation + runtime patterns bundled into one skill.

Role division with existing skills:

Skill	Responsibility
`msw-ui-system` (this skill)	Everything `.ui` — design (which/when/why), component API/enum (what), builder invocation (how to mutate), runtime mlua patterns. `.ui` mutations must always go through this skill's builder
`references/templates/`	Pre-built style bundles — `.ui` + ruid-map + button handler packages

MSW

.ui

单一入口点 —— 整合了设计指南 + 组件API + 构建器调用 + 运行时模式的一站式技能。

与现有技能的职责划分：

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

0. Routing

0. 路由规则

Branch to sub-references based on request keywords.

Trigger	Reference Document
"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` ; for runtime sibling reorder also read `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"
"make a HUD", "popup placement", "toast", "menu", "inventory grid", "scroll list"	`references/layout-recipes.md`
"connect .mlua after building with .ui builder", "property default UUID", "binding without drag"	`references/builder-protocol.md` §"Binding Injection"
Runtime UI component field read/write, component property name/type ( `ButtonComponent.Colors` , `TextComponent.Overflow` , `SpriteGUIRendererComponent.FillAmount` …)	`references/component-api.md` required before every `.mlua` access to UI component fields
Enum values ( `AlignmentType` , `OverflowType` , `ImageType` , `UIBasicParticleType` …)	`references/component-api.md` §Enums
Runtime mlua patterns (popup open/close, toast fade, HP bar, GridView, drag, tab, cooldown), Runtime UI Caveats (client-only, server-side nil, etc.)	`references/runtime-patterns.md`
`.ui` builder invocation methods (UIBuilder API, anchor presets, write auto-lint, component add/patch/remove)	`references/builder-protocol.md`

根据请求关键词跳转至子参考文档。

触发关键词	参考文档
"anchor/pivot/coordinates/位置为什么不对"、"RectTransform"、"stretch"	`references/ui-fundamentals.md` §1–§8
"mobile"、"安全区域"、"1920"、"MobileOnly"、"ActivePlatform"、"触摸尺寸"、"PC预留区域"、"按设备设置字体大小"	`references/ui-fundamentals.md` §9
"UIGroup"、"弹窗层级"、"z-order"、"displayOrder"、"CanvasGroup"、"透明度继承"、"Enable与Visible的区别"	`references/ui-hierarchy.md` ；若涉及运行时同级重排序，还需阅读 `references/runtime-patterns.md` §7
"选哪个组件"、"Sprite vs Text vs Button"、"9-slice"、"滚动列表"、"GridView vs ScrollLayoutGroup"	`references/component-api.md` 中的「组件选择指南」章节
"制作HUD"、"弹窗定位"、"提示框"、"菜单"、"背包网格"、"滚动列表"	`references/layout-recipes.md`
"用.ui构建器创建后关联.mlua"、"属性默认UUID"、"无需拖拽的绑定"	`references/builder-protocol.md` 中的「绑定注入」章节
运行时UI组件字段读写、组件属性名称/类型（ `ButtonComponent.Colors` 、 `TextComponent.Overflow` 、 `SpriteGUIRendererComponent.FillAmount` …）	`references/component-api.md` 每次用.mlua访问UI组件字段前必须查阅
枚举值（ `AlignmentType` 、 `OverflowType` 、 `ImageType` 、 `UIBasicParticleType` …）	`references/component-api.md` 中的「枚举」章节
.mlua运行时模式（弹窗开关、提示框淡入淡出、血条、GridView、拖拽、标签页、冷却计时）、运行时UI注意事项（仅客户端可用、服务器端为nil等）	`references/runtime-patterns.md`
`.ui` 构建器调用方法（UIBuilder API、锚点预设、写入自动校验、组件添加/修补/移除）	`references/builder-protocol.md`

1. Basic Workflow

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) Match recipe          Select the closest template from layout-recipes.md
(4) Invoke builder        Create/patch via scripts/msw_ui_builder.cjs (protocol: builder-protocol.md)
(5) Inject bindings       Auto-inject .mlua property default UUIDs via b.write(path, { bind: {...} }) or b.inject_bindings(...) (builder-protocol.md §"Binding Injection")
(6) Self-verify           write() auto-runs scripts/ui_lint.cjs (strict ON by default)
(7) Preview               Visual check via scripts/preview_ui_layout.cjs
(8) Maker Refresh         Apply to engine

(1) 明确需求       布局草图（ASCII或文字描述）+ 要挂载的组
(2) 查阅设计指南   至少匹配ui-fundamentals / ui-hierarchy / component-api中的「组件选择指南」章节
(3) 匹配布局方案    从layout-recipes.md中选择最接近的模板
(4) 调用构建器        通过scripts/msw_ui_builder.cjs创建/修改（协议参考builder-protocol.md）
(5) 注入绑定       通过b.write(path, { bind: {...} })或b.inject_bindings(...)自动注入.mlua属性默认UUID（参考builder-protocol.md的「绑定注入」章节）
(6) 自我验证           write()会自动运行scripts/ui_lint.cjs（默认开启严格模式）
(7) 预览               通过scripts/preview_ui_layout.cjs进行视觉检查
(8) 刷新编辑器         应用到引擎

2. Global Rules

2. 全局规则

NEVER

禁止操作

Do not directly edit
.ui
JSON —
```
.ui
```
creation/modification must go through
```
scripts/msw_ui_builder.cjs
```
. Manual editing breaks UUID·ValueType·
```
@components
```
consistency and causes silent drops.
Read existing
.ui
files through the builder too — Query via
```
UIBuilder.read(filepath)
```
/
```
.find()
```
/
```
.list_entities()
```
. Do not directly grep/parse raw JSON.
- ```
.ui
```
  direct
```
Read
```
  and shell commands such as
```
cat
```
  /
```
type
```
  /
```
Get-Content
```
  /
```
rg
```
  /
```
grep
```
  /
```
sed
```
  /
```
awk
```
  /
```
cp
```
  /
```
mv
```
  are blocked by the registered guard. Use
```
UIBuilder.read/load/snapshot
```
  for reads and
```
b.write()
```
  for writes. Deleting an entire
```
.ui
```
  file is a separate explicit deletion action, not a builder mutation.
Set
```
Position
```
directly — Use only
```
anchoredPosition
```
(Position is engine-managed)
Express size via OffsetMin/Max on fixed anchors (AnchorsMin == AnchorsMax) while also using
```
anchoredPosition
```
— Do not mix the two modes
Builder creates new UUIDs but
```
.mlua
```
property defaults are not updated — Binding breaks

禁止直接编辑
.ui
JSON文件 ——
```
.ui
```
的创建/修改必须通过
```
scripts/msw_ui_builder.cjs
```
进行。手动编辑会破坏UUID·ValueType·
```
@components
```
的一致性，导致静默丢失数据。
读取现有
.ui
文件也必须通过构建器 —— 通过
```
UIBuilder.read(filepath)
```
/
```
.find()
```
/
```
.list_entities()
```
查询。禁止直接查找/解析原始JSON。
- 直接读取
```
.ui
```
  文件和使用
```
cat
```
  /
```
type
```
  /
```
Get-Content
```
  /
```
rg
```
  /
```
grep
```
  /
```
sed
```
  /
```
awk
```
  /
```
cp
```
  /
```
mv
```
  等shell命令已被防护机制阻止。读取请使用
```
UIBuilder.read/load/snapshot
```
  ，写入请使用
```
b.write()
```
  。删除整个
```
.ui
```
  文件是独立的显式操作，不属于构建器修改范畴。
直接设置
```
Position
```
—— 仅使用
```
anchoredPosition
```
（Position由引擎管理）
在固定锚点（AnchorsMin == AnchorsMax）模式下同时用OffsetMin/Max定义尺寸和
```
anchoredPosition
```
—— 禁止混合两种模式
构建器生成新UUID但未更新
```
.mlua
```
属性默认值 —— 会导致绑定失效

ALWAYS

必须遵守

Check at least one design guide before invoking the builder (
```
ui-fundamentals
```
/
```
ui-hierarchy
```
/
```
component-api
```
§Component Selection Guide)
Match a recipe first; build from scratch only as a last resort
For edge placement use the formula:
```
pos = ±(margin + size/2)
```
Separate popups and toasts into their own UIGroup, standalone show/hide
Verify text
```
Alignment
```
default is
```
UpperLeft(0)
```
— 95% of "I centered it but it sticks to the left" issues
Button touch target ≥ 88×88 (mobile support)

调用构建器前至少查阅一份设计指南（
```
ui-fundamentals
```
/
```
ui-hierarchy
```
/
```
component-api
```
中的「组件选择指南」章节）
优先匹配现有布局方案；仅在万不得已时才从零开始构建
边缘定位使用公式：
```
pos = ±(margin + size/2)
```
将弹窗和提示框单独放入专属UIGroup，独立控制显示/隐藏
验证文本
```
Alignment
```
默认值为
```
UpperLeft(0)
```
—— 95%的「我设置了居中但它靠左」问题源于此
按钮触摸目标区域≥88×88（适配移动端）

3. Sub-documents

3. 子文档

```
references/ui-fundamentals.md
```
— Coordinate system, RectTransform 3 elements, anchor mode determination (§1–§8) + Resolution·safe area·PC reserved zones·touch targets·font sizes·platform separation (§9)
```
references/ui-hierarchy.md
```
— UIGroup / displayOrder / CanvasGroup / Enable vs Visible
```
references/component-api.md
```
— §"Component Selection Guide" (which/when/why) + full component property/method/event tables (what) + all UI-related enum values (§Enums)
```
references/layout-recipes.md
```
— Layout template collection
```
references/runtime-patterns.md
```
—
```
.mlua
```
runtime patterns (popup/toast/HP/grid/drag…) + Runtime UI Caveats
```
references/builder-protocol.md
```
—
```
.ui
```
CJS builder call protocol (panel/text/sprite/button/slider/scroll/script/group/mask/grid/avatar/touch_receive/skeleton/area_particle/basic_particle, component add/replace/patch/remove, anchor presets, write auto-lint,
```
.mlua
```
property UUID auto-binding)

references/templates/templates.md

— Pre-built style bundle index (

style-N-*

.ui

ruid-map.md

Popupbutton.mlua

)

```
references/ui-fundamentals.md
```
—— 坐标系、RectTransform三要素、锚点模式判定（§1–§8）+ 分辨率·安全区域·PC预留区域·触摸目标·字体大小·平台区分（§9）
```
references/ui-hierarchy.md
```
—— UIGroup / displayOrder / CanvasGroup / Enable与Visible的区别
```
references/component-api.md
```
—— 「组件选择指南」章节（选什么/何时用/为什么用）+ 完整组件属性/方法/事件表（是什么）+ 所有UI相关枚举值（「枚举」章节）
```
references/layout-recipes.md
```
—— 布局模板集合
```
references/runtime-patterns.md
```
——
```
.mlua
```
运行时模式（弹窗/提示框/血条/网格/拖拽…）+ 运行时UI注意事项
```
references/builder-protocol.md
```
——
```
.ui
```
CJS构建器调用协议（面板/文本/精灵/按钮/滑块/滚动/脚本/组/遮罩/网格/头像/触摸接收/骨骼/区域粒子/基础粒子，组件添加/替换/修补/移除，锚点预设，写入自动校验，
```
.mlua
```
属性UUID自动绑定）

references/templates/templates.md

—— 预构建样式包索引（

style-N-*

.ui

、

ruid-map.md

、

Popupbutton.mlua

）

4. Scripts

4. 脚本工具

```
scripts/msw_ui_builder.cjs
```
—
```
.ui
```
builder core (UIBuilder class). Read
```
references/builder-protocol.md
```
for the call protocol before use
```
scripts/preview_ui_layout.cjs
```
—
```
.ui
```
layout visual check + touch target warnings
```
scripts/ui_lint.cjs
```
—
```
.ui
```
file self-verification (auto-called by
```
write()
```
)
```
scripts/ui_recipe.cjs
```
— Recipe-based scaffolding

```
scripts/msw_ui_builder.cjs
```
——
```
.ui
```
构建器核心（UIBuilder类）使用前请阅读
```
references/builder-protocol.md
```
中的调用协议
```
scripts/preview_ui_layout.cjs
```
——
```
.ui
```
布局视觉检查 + 触摸目标区域警告
```
scripts/ui_lint.cjs
```
——
```
.ui
```
文件自我验证（由
```
write()
```
自动调用）
```
scripts/ui_recipe.cjs
```
—— 基于布局方案的脚手架工具

Out of Scope

超出范围的内容

```
.map
```
/
```
.model
```
/
```
.tileset
```
builders — Outside this skill's scope
```
.ui
```
JSON schema (raw field shapes,
```
@type
```
/
```
@components
```
wrapping, AlignmentOption 0–15 mapping, etc.) — Handled internally by the builder. Users/AI do not need to know directly
Accessibility patterns (alt text, screen-reader hints, focus order) — Not covered
Error-state UI patterns (disabled-button styling beyond
```
Transition.Disabled
```
, validation messages, loading spinners) — Not covered; design ad-hoc per project
Automated UI testing / layout assertions beyond
```
ui_lint.cjs
```
and
```
preview_ui_layout.cjs
```
— Not provided
Custom shader materials (
```
MaterialId
```
) — Field is exposed but authoring shaders is outside this skill's scope

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