msw-scripting

msw-scripting covers authoring MapleStory Worlds scripts in the .mlua language, together with integrated playtest and debugging. mlua is Lua-based but adds MSW-specific annotations (@Component, @Logic, @ExecSpace, @Sync), a lifecycle, and an execution-space model, so general Lua knowledge alone will not produce working code. All work is done by editing files in the workspace directly, and code is validated in the order build logs then runtime logs.

The skill lays out core principles that must be followed. Existing scripts come first: before creating a new .mlua, search under ./RootDesk/MyDesk/ for an existing script with the same purpose, because extending an existing file is always the first choice. New scripts must live under a feature or category subfolder following the path shape ./RootDesk/MyDesk/<FeatureFolder>/<ScriptName>.mlua, reusing folders like Player/, UI/, or Combat/ and never dumping files into catch-all folders such as Scripts/, Misc/, Common/, New/, or temp/. APIs must never be guessed, since a wrong name, parameter, or return type silently fails at runtime; the required order is to check the .d.mlua signature under ./Environment/NativeScripts/ (Component, Service, Event, Logic, Enum, Misc folders), use msw-search for semantics if needed, then write and let LSP diagnostics run. A mlua-diagnose hook runs LSP diagnose automatically after every create or modify, and iteration continues until error-severity diagnostics reach zero. Generated .codeblock files must never be touched, and Maker MCP refresh must be called after any .mlua change.

A dedicated section warns that MSW is not Unity, so applying Unity or generic patterns compiles fine but silently fails at runtime; examples include @Logic having no self.Entity, physics colliders never emitting TouchEvent, UI being client-only with server-to-UI going through @ExecSpace("Client") RPC, and spawning requiring _SpawnService:SpawnByModelId with a required server-only parent. The skill documents script types, including @Component scripts attached to an entity that use self.Entity and may extend Component, AttackComponent, or HitComponent, and @Logic scripts that are global singletons accessed by name. It also enforces a builder-protocol preflight whenever a turn touches .map, .model, or .ui files, and requires every method to carry a description comment as the first line inside its body, because the mlua parser binds a comment above a declaration to the previous one.