msw-ui-kit

msw-ui-kit

复用官方 MSWPackages 资源来构建视觉协调的 UI：从已发布的世界中选用主题 RUID 配色，并使用预构建的交互组件库。其前提是：同一资源包中提供的部件已经经过统一美术指导，彼此匹配；从同一主题中挑选，优于通过搜索临时拼凑 RUID。

分工：

技能	职责
msw-ui-kit（本技能）	选用哪些资源——主题部件 RUID、示例屏幕参考、预构建组件集成
msw-ui-system	.ui 文件本身——所有 .ui 的创建和修改都通过其 UIBuilder 完成；包括布局、锚点、组件
msw-packages	功能系统（库存逻辑、商店逻辑、排名数据……）——本技能仅涵盖外观和交互组件

---

0. 路由

触发条件	阅读内容
“精致 / 好看 / 游戏品质 UI”、“主题屏幕”、已选择主题	references/themes/<theme>.md——先通过 §1 表格选择主题
查找特定部件（“这个主题的关闭按钮 / 箭头 / 插槽变体 / 仪表”）	主题文档中的部件列表；较难查找的内容 → 按名称关键词 grep data/themes/<theme>.ruids.json
“复选框 / 单选框 / 开关 / 切换组 / 下拉菜单 / 分页 / 进度条 / 滚动选择器 / 时间选择器 / 数字键盘 / 微调器”	references/widgets.md
整屏结构参考（“制作一个像真实游戏中的库存 / 商店 / 排名屏幕”）	主题文档 §Sample screens → 阅读随附的树结构 data/samples/<theme>/<Screen>.txt
同上，但功能来自官方包（库存 / 商店 / 邮件 / 排名 / 任务 / 对话……）	references/package-screens.md → data/packages/<package>/<Screen>.txt
屏幕背后的功能逻辑（添加 / 移除库存物品、购买流程……）	转至 msw-packages 技能

1. 主题选择

每个世界（至少每类屏幕）选择一个主题并始终保持一致。每个主题内的所有部件都经过统一美术指导，彼此匹配。

主题	来源世界	风格 / 适用场景	库存
supersimple	Getting Over It Maker	简洁极简的实用型 UI；轻量级游戏、工具类屏幕	9 个核心套件，19 个示例屏幕
simplefantasy	MapleSlash	奇幻动作 RPG，资源最丰富的套件（装备 / 技能 / 抽卡 / 星力屏幕）	11 个核心套件，42 个示例屏幕
casualrpg	MapleSoulHero	休闲 RPG 全套内容（库存、任务、收藏、关卡地图）	11 个核心套件，20 个示例屏幕
casualsurvival	Durango The Lost Island	生存 / 制作（研究、制作、小地图、状态）	10 个核心套件，15 个示例屏幕
cutecasual	ChuChuBurger	可爱圆润的经营 / 大亨风格，示例集最大	10 个核心套件，28 个示例屏幕
cardgame	Maple Duel	卡牌对战（卡牌、随从、排位赛、套牌）	8 个核心套件，12 个示例屏幕
minimalcombat	Maple Auto Battler	精简的核心套件（图标、插槽、色调）——用于点缀	5 个核心套件，无示例

如果用户没有偏好：实用型 / 轻量级世界选用 supersimple，RPG 风格世界选用 simplefantasy。用一句话说明选择及原因。

2. 工作流

(1) Pick theme          §1 table (ask only if genuinely ambiguous)
(2) Load palette        references/themes/<theme>.md
(3) Structure first     building a standard screen (inventory/shop/ranking/HUD/dialog…)?
                        read data/samples/<theme>/<Screen>.txt BEFORE laying anything out
                        (large files say so in their header — read top-level sections, not all)
                        feature comes from an official package? use data/packages/ instead
                        (references/package-screens.md indexes them)
(4) Map screen parts    panel → surface part, actions → button parts, lists → slot/unit parts,
                        gauges → slider parts, glyphs → tint/icon parts
(5) Build via builder   msw-ui-system UIBuilder, passing image_ruid per part
(6) Widgets if needed   references/widgets.md (binding groups + assets/widgets/trees/ blueprint)

3. 规则

ALWAYS

1. 每个屏幕只使用一种主题，并在编写时确定。 此技能假设你编写 .ui 时就已选定主题，且运行时不会改变——正因如此，ALWAYS #4 才能把“这段文字是否位于主题美术资源上”当作构建时可检查的事实。切勿在同一个屏幕上混用两种主题的部件；缺少某个部件时，先在主题的 data/themes/<theme>.ruids.json 长尾条目中执行 grep，再用尺寸不同的同主题部件替代，最后才使用 msw-search。如果主题确实会在运行时切换，这个假设就不成立：你编写的普通面板之后可能会出现在主题美术资源下方。这时，要么让可切换的界面和其上的文字属于同一套主题，要么让这部分外框完全不参与切换，并修正其颜色。
2. 遵循原生尺寸。 非 Sliced 部件要保持其原生宽高比（等比缩放）。(Sliced) 部件可以调整尺寸，但 9-slice 只能保证边框清晰——绘制在美术资源内部的色带、分隔线或内框会随中间部分一起拉伸，并横跨内容；你或 lint 都无法察觉。对于通用窗口／弹窗背景，请从主题文档的部件列表中选择原生宽高比最接近目标矩形的部件。复用示例树中的背景前，先在数据 JSON 中 grep 其 RUID："kind": "S" 表示它只存在于示例屏幕中——它是该布局的夹具，不是通用表面。(Tiled) 部件会通过重复延展——但有一个例外：对于标记为 (Tiled) 的仪表／条形背景，当条形宽度不同于原生尺寸时，请使用 sprite_type: 1（Sliced）（平铺会在末尾裁掉一段不完整的图案，导致错位）。大面积装饰性图案填充（BG_Pattern 风格）仍使用 Tiled。调整尺寸的表面默认规则：任何以非原生尺寸使用的表面类部件（窗口背景、面板、列表／行背景、底板），无论标记为何，都使用 sprite_type: 1；有 9-slice 边框时边框渲染清晰，没有时渲染效果与 Simple 相同，因此绝不会比 Simple 更差。图标／插画不是表面——应等比缩放。(Filled) 是记录，不是指令：它表示源内容在原生尺寸下通过 FillAmount 处理该美术资源，通常位于 SliderComponent 中。制作自己的线性仪表时，请遵循 msw-ui-system 的规则——调整填充精灵的宽度，而不是填充它，因为 Filled 会裁切 UV，并扭曲任何 9-slice 边框。先使用 sprite_type: 1；仪表填充通常是细长的渐变，往往没有切片边框，因此如果填充看起来被拉伸或模糊，请改用 sprite_type: 2（Tiled），以干净地重复图案。Filled 仅用于径向扫掠效果（冷却环）。切勿保持 (Filled) 部件的原生宽高比——这类美术资源的比例可能极端到 48:1，因此等比缩放可能根本无法得到可用的条形。
3. 每个主题部件都必须显式设置 color。 仅传入 image_ruid 会让构建器在精灵上使用默认的深色半透明皮肤颜色，使美术资源变成几乎不可见的幽灵效果——传入 "#FFFFFF"（button／slider／textInput 上的 bg_color），让部件按原样渲染，包括运行时会替换图像的单元格和图标（主题文档中列出 color: 值的部件应改用该值）。Tint_* 部件是单色字形——使用构建器的 color 选项应用符合主题的强调色，而不是另找彩色图标。表面也遵循这一规则：某些面板／行／单位背景是与 Tint_* 条目共用 RUID 的中性白色遮罩——直接使用时会渲染为纯白（或几乎不可见）的填充，并遮住文字。凡是主题文档中列有 color: 值的部件，都必须将该颜色（或有意选择的、符合主题的替代色）传给构建器；切勿直接渲染裸 RUID。遮罩 RUID 在数据 JSON 中标记为 "tint": true。
4. 切勿在主题美术资源上自行指定字体颜色。 精灵的亮度对你不可见——静态检查无法发现浅色背景上的白字或深色背景上的暗字。请使用主题文档中该部件对应的 text: 配色：其中列出了源世界实际用于该美术资源的所有字体颜色，并按使用频率从高到低排序，同时附有计数。带有 +o#RRGGBB（描边）或 +s#RRGGBB（纯色光晕）的配色是一体的——这些素材包中许多浅色字体只有依靠这圈效果才能看清，因此只取颜色、不带效果就会重现问题。将描边作为文本节点上的 outline／outline_color／outline_width 传入；光晕则通过 patchComponent 设置 Underlay + UnderlayColor，偏移量为 0（纯色环，而非投影）。如果该部件没有配色，请从主题的“Text colors”部分中选择（匹配最接近的使用情境）。只有在自制纯色面板上才退而使用纯黑／纯白。标记为 [split surface] 的部件（数据 JSON 中为 "split_text": true）同时包含浅色和深色区域——例如浅色主体上方有标题栏——因此其列出的颜色不能互换：应匹配文字所在区域；不确定时优先使用较深的选项，它在浅色区域上仍清晰可读。
5. 所有 .ui 修改都必须通过 msw-ui-system 的 UIBuilder 进行——此技能只提供 RUID／尺寸／结构。其设计规则（锚点、嵌套、UIGroup 根节点）仍然适用。
6. 示例屏幕和包屏幕是结构参考，不是可复制的文件——研究其部件构成，然后用构建器重建。包屏幕使用该包自带的美术资源，因此应沿用其构成并传入你的主题 RUID；如果功能本身来自该包，优先使用包屏幕，因为其脚本会绑定到对应的树结构。

绝对不要

1. 不要安装或复制 ui-resource-* 包——它们的 RUID 会按原样从 MSW 资源存储中解析。只有小组件会复制到工作区，其来源是此技能的 assets/widgets/（见 references/widgets.md）——绝不要从网络获取任何内容。
2. 不要手动编辑小组件预制件的内部结构（脚本名称、子项名称）——绑定依据名称进行。

4. 子文档

• references/themes/ — 各主题的部件调色板：supersimple.md、simplefantasy.md、casualrpg.md、casualsurvival.md、cutecasual.md、cardgame.md、minimalcombat.md
• references/widgets.md — 预制交互小组件：集成、各小组件 API、绑定组、事件、注意事项
• references/package-screens.md — 官方功能包界面索引（背包、商店、邮件、排行、任务……），其树结构已整理到 data/packages/<package>/<Screen>.txt
• data/themes/<theme>.ruids.json — 各主题的完整 RUID 注册表（便于机器检索的长尾数据；每行一个 JSON 对象：名称、类别、kind（该美术资源出现在哪些模型中——C 表示仅在核心调色板中，S 表示仅在示例界面中，CS 表示两者都有）、尺寸和 type——记录的是源世界如何呈现该美术资源，并非对你如何使用它的建议；实际应传入什么，请参见 ALWAYS #2——此外，分类为拉伸适配表面的部件带有 "surface": true——这些是 ALWAYS #2 中默认采用 Sliced 的目标——需要显式指定 color 的中性遮罩带有 "tint": true——这些是 ALWAYS #3 中的目标——此外还有 "text"，记录源世界在该美术资源上使用的字体颜色及其计数和 +o/+s 环绕标记；如果这些颜色横跨浅色和深色，则标有 "split_text": true——这些是 ALWAYS #4 中的目标）
• data/samples/<theme>/<Screen>.txt — 源世界生产环境界面的完整实体树整理稿（结构配方）
• assets/widgets/ — 随附的小组件源文件：UIComponent/**/*.mlua + Util/Util.mlua（复制到工作区）以及 trees/**.txt 预制件结构整理稿（使用主题部件重建视觉效果）

不在范围内

• .ui 构建机制、锚点、组件、运行时模式——msw-ui-system
• 功能／系统包（背包、商店、邮件、排行逻辑……）——msw-packages
• 在主题之外自由搜索精灵图——msw-search；绘制新精灵图——msw-painter