Foundation skill for MSW (MapleStory Worlds). Read this FIRST before anything else in MSW.

MSW General — Foundation Skill The foundation skill for MSW (MapleStory Worlds) creation, integrating shared tools, domain knowledge, platform rules, and file authoring . Every other MSW skill depends on it. Core Principle: Visual Polish MSW is a game creation platform . The goal is not a prototype where logic merely runs — it is a polished game players can enjoy. So whatever entity you create — monster, NPC, tower, item, background object — search for and apply appropriate resources (sprites, animations, sounds) that match its role and personality. Do not leave the default sprite in place or leave SpriteRUID empty. Resource application principle when creating an entity: 1. After creating the entity, use the msw search skill to find sprites/animations that fit it 2. Apply the RUID of the found resource to SpriteRendererComponent so the entity is visually represented 3. If there is combat, also set hit/explosion effects; if there is interaction, set sound effects Functionality implemented != finished. A polished game requires appropriate resources plus visual presentation. When making a .model — catalog first Do not start a new .model from an empty file. The skill local models/ folder contains validated templates organized by category — monsters ( ChaseMonster / MoveMonster / StaticMonster ), NPC ( StaticNPC ), players ( Player / DefaultPlayer ), terrain ( Foothold / Ladder / Rope / Portal ), map objects ( MapObject / SkeletonMapObject / ItemAsset ), particles ( BasicParticle / SpriteParticle / AreaParticle / AnimationPlayer ), sound ( Sound / SoundEffect ), tile map containers ( TileMap / RectTileMap ), UI ( UIButton / UIText / UISprite / UIGroup , etc.), external media ( WebSprite / YoutubePlayerWorld ). Workflow : Read [references/model.md](references/model.md) IN FULL FIRST (mandatory — see "Model Work Preflight — MUST" below) → pick the closest template from the catalog → load it via ModelBuilder (call protocol: [ references/builder protocol.md ](references/builder protocol.md) core + [ references/builder protocol model.md ](references/builder protocol model.md)) → replace the 3 identifiers ( EntryKey , Id , Name ) through the builder → customize Components / Values / Properties / Children through the builder → save under a typed subfolder of RootDesk/MyDesk/Models/ (e.g. Models/Monsters/{Name}.model , never directly under MyDesk/ ) → refresh . Detailed catalog and builder procedure: [references/model.md §2](references/model.md). The builder emits the required value metadata, so agents do not need to read or hand write .model format internals. For a monster, first pick a pattern in [references/animation state.md §0](references/animation state.md), then follow [references/monster.md §5](references/monster.md) for the recommended path. Pattern A (verified working canonical — Soldier reference setup, full source inlined in [ references/monster.md §7](references/monster.md)) : no template needed; assemble 11 components from scratch with a custom script.MyMonsterAI (SoldierAI style) instead of AIChase/AIWander. StateComponent.IsLegacy left at the default. Pattern B ( MonsterCanonical.model ) : AIChaseComponent + ActionSheet pipeline. StateComponent.IsLegacy=false mandatory. The other monster templates ( ChaseMonster / MoveMonster / StaticMonster ) leave ActionSheet empty and use defaults that silently fail under Pattern B (uppercase keys, SortingLayer="Default" , IsLegacy=true ). For any entity that has StateAnimationComponent (monster/NPC) or AvatarStateAnimationComponent (player) — or any .mlua that calls ChangeState / AddState / SetActionSheet — also read [references/animation state.md](references/animation state.md). The state machine ↔ animation pipeline, the two pattern split, default state registration rules, [LEA 3005] cause, and SetActionSheet vs ChangeState semantics live there (not duplicated into per entity docs). Placing multiple entities — model first If the same entity is going to appear twice or more in a map (5 monsters, 10 trees, 3 portals, …), author a .model first and place each instance via modelId rather than copy pasting inline @components . Instance count of same composition Choice 1 (truly one off decoration in a single map) inline @components is acceptable ≥2 .model + modelId instances (default) Spawned at runtime ( SpawnByModelId ) .model is required regardless of count Why this is the default: Edit once, propagate everywhere — change SpriteRUID /HP/ ActionSheet in the model and every instance updates. Inline copies require touching N entities each time. Smaller, reviewable .map diffs — modelId instances carry only Transform overrides; inline copies bloat the map by hundreds of lines per entity. Avoids drift — five inline copies silently diverge (one gets IsLegacy: true , another forgets SortingLayer: "MapLayer0" ). The model anchors the canonical values. Required for SpawnByModelId — without a registered model id, dynamic spawning fails. Workflow : 1. Author .model under RootDesk/MyDesk/Models/{Category}/{Name}.model (see folder rule above). 2. Place each instance via MapBuilder (call protocol: [ references/builder protocol.md ](references/builder protocol.md) core + [ references/builder protocol map.md ](references/builder protocol map.md)) so ids, paths, componentNames , origin metadata, and per instance component overrides stay synchronized. 3. refresh . Details and the inline vs modelId comparison: [references/entity.md "Two Step Map Editing Workflow"](references/entity.md), [references/model.md §1](references/model.md). Preflight read semantics — applies to every "MUST Read" in this skill "Read X FIRST" in the preflights and Absolute Principles means: X must be fully in context before the work starts — not "re read X every turn". Read the file IN FULL (no offset / limit , no cat / Get Content ) only if it was never loaded this session or was lost to context compaction. Do not re read a file that is already fully in context — presence in context is the requirement; re reading is waste. Memory or a summary of a file does not count as the file being in context, and a prior turn having loaded it does not exempt this turn from confirming it is still there. Entity Work Preflight — MUST If the task involves an entity in any way, you must read [references/entity.md](references/entity.md) first. No exceptions. Builder Protocol Preflight — MUST If the task creates or modifies any .map / .model / .ui file — directly, or as a side effect of writing .mlua that spawns / places / binds — [references/builder protocol.md](references/builder protocol.md) (core) plus the per builder file for each file type the task mutates — [references/builder protocol map.md](references/builder protocol map.md) ( .map ) / [references/builder protocol model.md](references/builder protocol model.md) ( .model ) / [references/builder protocol ui.md](references/builder protocol ui.md) ( .ui ) — must be fully in context FIRST (read semantics above). No exceptions. The protocol is one unified entry point split into a shared core ( builder protocol.md — routing, common workflow, chaining contract, §0 pre flight, §4 cross flow, §5 checklist) plus per builder files ( builder protocol map.md §1 / builder protocol model.md §2 / builder protocol ui.md §3). Knowing only one builder's protocol and then invoking another builder's .cjs bypasses that builder's write side contract ( componentNames sync, Values typeKey metadata, write time auto lint, placeModel component mirroring, child entity invariants) — the three are interlocked through cross flow (model authoring → map placement → ui binding), so cross flow work loads every matching per builder file. Triggers (intentionally broad — load the missing protocol file(s) whenever any match): .map changes (entity placement, component patching, tile / foothold inspection) .model changes (new authoring, value / component / property / child edits) .ui changes (new build, component CRUD, binding injection) Any call to MapBuilder / ModelBuilder / UIBuilder Requests shaped like "entity shaped" work — monster / NPC / projectile / map object / popup / HUD, etc. Any code using SpawnService (a spawnable model must be authored and placed first) The domain refs ( entity.md / model.md / msw ui system design references) are read alongside the protocol files — they are not substitutes (domain context + call protocol are a pair). Confirm they are still in context on every turn that fires a trigger — re read only what was never loaded or was lost to compaction. Model Work Preflight — MUST If the task involves authoring or editing a .model file in any way — including any call to ModelBuilder (any API), creating a new model from a template, mutating components/values/properties/children/event links on an existing model, or even a one line tweak — [references/model.md](references/model.md) must be fully in context FIRST (read semantics above). No exceptions. The builder's template catalog, the 3 identifier replacement rule ( EntryKey / Id / Name ), required value metadata, property/child/event link API surface, and the typed save folder layout under RootDesk/MyDesk/Models/ live only in [ references/model.md ](references/model.md). Calling the builder without reading [ references/model.md ](references/model.md) first silently produces broken models (missing value metadata, mismatched identifiers, wrong save folder, default value silent failures). Reading scattered template files or guessing the API from memory is not a substitute — at the start of every turn that touches a .model , confirm it is still in context and re read only if it was lost. Map Work Preflight (do this BEFORE any map work) Before starting any map related task — entity placement, spawn, movement scripts, model authoring, tile edits, etc. — you must complete these two steps in order: 1. Identify the target map — its path ( ./map/{mapname}.map ), its root entity, and its location in the Hierarchy. 2. Use MapBuilder to read MapComponent.TileMapMode as a number (call protocol: [ references/builder protocol.md ](references/builder protocol.md) core + [ references/builder protocol map.md ](references/builder protocol map.md)). Keep the value in mind for the rest of the session. Value Mode Required Body Runtime log on mismatch / missing Body : : 0 TileMap (MapleTile, side view + Foothold) RigidbodyComponent [LEA 3004] MissingComponent : Entity is missing 'RigidbodyComponent'. 1 RectTileMap (RectTile, top down) KinematicbodyComponent [LEA 3004] MissingComponent : Entity is missing 'KinematicbodyComponent'. 2 SideViewRectTileMap (SideViewRectTile, side view tile) SideviewbodyComponent [LEA 3004] MissingComponent : Entity is missing 'SideviewbodyComponent'. Never start map work without knowing the current TileMapMode . The three modes differ completely in Body component, gravity, collision, and event stacks. A mismatch is almost never a compile time error — it shows up either as a silent failure (entity doesn't move / passes through walls / invisible) or as one of the three [LEA 3004] MissingComponent runtime logs above. Whenever you see one of those three messages, suspect a TileMapMode ↔ entity Body mismatch first. Recommending the right mode — MUST when starting a new map or when the current mode is clearly wrong for the user's goal Whenever the user describes what game / map they want to build (new map authoring, "make a side scroller", "I want a top down dungeon", or you read the current .map and find its TileMapMode does not fit the user'

msw-general