msw-scripting
MSW Scripting (.mlua) — Framework + File Workflow + Playtest & Debugging
mlua is Lua-based, but it has MSW-specific annotations, a lifecycle, and an execution-space model. 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 → runtime logs.
1. Core Principles (must follow)
1.1 Existing Script First
- Before creating a new
.mlua, you must search under./RootDesk/MyDesk/for an existing script with the same or similar purpose. - Use glob/keyword search (file names, symbols, comment keywords) as your discovery method.
- Duplicate implementations raise maintenance cost and conflict risk. Extending (modifying an existing file) is always the first choice.
1.2 Folder Structure for New Scripts — Never Dump Files Flat
When extending an existing script is not possible and a new .mlua must be created, organize it under a feature/category subfolder. Do not drop scripts directly into ./RootDesk/MyDesk/.
More from msw-git/msw-ai-coding-plugins-official
msw-general
Foundation skill for MSW (MapleStory Worlds). Read this FIRST before anything else in MSW.
111msw-search
MSW search integration — (1) vector search for API docs and implementation guides via the msw-mcp MCP server (mlua_api_retriever / mlua_document_retriever), (2) REST API search for resources (sprite / animation / sound / resource pack / avatar). Use for 'find details, examples, or related APIs not in .d.mlua', 'need a SpriteRUID', 'monster sprite', 'background image', 'find a sound', 'avatar rendering', etc. Keywords: document search, API details, examples, guide, retriever, resource, sprite, animation, sound, RUID, resource pack, avatar.
110msw-defaultplayer
MSW DefaultPlayer (character) management. Directly read/modify the DefaultPlayer.model file, add/remove components, configure movement speed / jump force / HP / camera, and per-map-mode movement components. Use for DefaultPlayer model, player components, movement speed, jump force, HP, camera, physics. Keywords: player, DefaultPlayer, speed, jump, HP, camera, gravity, revive, respawn, character.
110msw-avatar
MSW avatar management — costume (CostumeManagerComponent, 17 slots) + animation 3-layer pipeline (StateComponent → AvatarStateAnimationComponent → AvatarRendererComponent). Four-level distinction: State key (uppercase) / AvatarBodyActionStateName (lowercase) / MapleAvatarBodyActionState enum / sprite action ID (swingO1, shoot1). Two mapping systems via IsLegacy/ActionSheet/StateToAvatarBodyActionSheet. When PlayerControllerComponent auto state transitions collide with ActionStateChangedEvent, resolve via RemoveActionSheet / SetActionSheet / BodyActionStateChangeEvent. Applies to any avatar-bearing entity (NPC, monster, etc.), not only DefaultPlayer. Use for avatar costume get/set, 17 equip slots, animation state mapping, action override, weapon-specific attack motion, custom shoot/cast/dance action. Keywords: avatar, costume, animation, state, action, shoot, swing, weapon, equipment, bow, sword, fire, slash, custom action, block auto playback, remap, ActionStateChangedEvent, BodyActionStateChangeEvent, RemoveActionSheet, SetActionSheet, StateToAvatarBodyActionSheet, AvatarStateAnimationComponent, AvatarRendererComponent, MapleAvatarBodyActionState, PlayerControllerComponent.
88msw-combat-system
MSW combat system integration guide. Covers the Attack→Hit pipeline, damage model, i-frame, knockback, Hit Stop, Camera Shake, Sprite Flash, SFX, death/revive, damage skin, hit effect, avatar combat motion, custom events, and AI FSM — all based on MSW native APIs for 2D multi-genre coverage. Keywords: attack, hit, damage, combat, monster, hit effect, critical, projectile, damage skin, knockback, hit stop, combo, HP bar.
88msw-costume
MSW 아바타 코스튬 관리. 코스튬 조회/적용, CostumeManagerComponent 17슬롯, 아바타 유틸리티. DefaultPlayer뿐 아니라 모든 엔티티(NPC, 몬스터 등)에 적용 가능. Use for avatar costume get/set, CostumeManagerComponent 17 equip slots, avatar utilities. Keywords: costume, avatar, equip, slot, 코스튬, 아바타, 장비, 꾸미기, 모자, 상의, 하의, 무기.
23