msw-ui-system

A single entry point for everything related to MSW (MapleStory Worlds) .ui work, bundling design guidance, component API and enum reference, builder invocation, and runtime .mlua patterns into one skill. It covers the RectTransform model (anchor, pivot, anchoredPosition), the UIGroup/CanvasGroup hierarchy and z-ordering, layout recipes for HUDs, popups, toasts, menus, inventory grids, and scroll lists, and full API tables for components such as ButtonComponent, TextComponent, SpriteGUIRendererComponent, ScrollLayoutGroup, GridView, TextInput, Slider, Mask, and AvatarGUIRenderer, alongside UI enums like AlignmentType, OverflowType, ImageType, and FillAmount. Runtime topics include popup open/close, toast fade, HP bars, GridView, drag, tabs, cooldowns, and world nametags, plus the caveat that UI is client-only and nil on the server with no RPC.

The skill is organized as a router: based on request keywords it branches to sub-reference documents — ui-fundamentals for coordinates and anchors and mobile/safe-area concerns, ui-hierarchy for UIGroup/displayOrder/CanvasGroup, component-api for component selection and property/method/enum tables, layout-recipes for ready-made layouts, runtime-patterns for .mlua behavior, and ui-sound for click and hover SFX. The component-api reference is required reading before any .mlua access to UI component fields, and the builder protocol lives in a shared msw-general/references/builder-protocol.md document alongside the .map MapBuilder and .model ModelBuilder because the cross-flows are interlocked.

A strict set of global rules governs mutations. All .ui creation and modification must go through scripts/msw_ui_builder.cjs, and even reads must use UIBuilder.read/find/listEntities rather than grep or cat, since direct file access is blocked by a registered guard to preserve UUID, ValueType, and @components consistency. Other rules forbid setting Position directly (use anchoredPosition), mixing fixed-anchor offsets with anchoredPosition, and leaving .mlua property-default UUIDs unsynced after the builder mints new ones — bindings are auto-injected via b.write with a bind option or b.injectBindings. The recommended ten-step workflow runs from clarifying intent and checking a design guide through builder preflight, recipe matching, building, binding injection, automatic lint via ui_lint.cjs, preview, a sound pass for interactive buttons, and an engine refresh. Touch targets are required to be at least 88x88 for mobile.