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: pick the closest template from the catalog → Read → replace the 3 identifiers (EntryKey, Id, Name) → customize Components/Values → save under a typed subfolder of RootDesk/MyDesk/Models/ (e.g. Models/Monsters/{Name}.model, never directly under MyDesk/) → refresh. Detailed catalog and substitution procedure: references/model.md §2.

Every template includes a consistent MODNativeType assembly string — this avoids the most common mistake of writing ValueType by hand and producing a silent failure.

For a monster, start with models/MonsterCanonical.model and references/monster.md. The other monster templates (ChaseMonster / MoveMonster / StaticMonster) leave ActionSheet empty and use defaults that silently fail (uppercase keys, SortingLayer="Default", IsLegacy=true).

---

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. In .map Entities[], each instance sets modelId + origin.entry_id to the same id, with only TransformComponent (and any per-instance overrides) in @components.
3. refresh.

Details and the inline-vs-modelId comparison: references/entity.md "Two-Step Map Editing Workflow", references/model.md §1.

---

Entity Work Preflight — MUST

If the task involves an entity in any way, you must read references/entity.md first. No exceptions.

---

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. Open that .map file directly and read MapComponent.TileMapMode as a number. 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에 'RigidbodyComponent'가 없습니다.
1	RectTileMap (RectTile, top-down)	KinematicbodyComponent	[LEA-3004] MissingComponent : Entity에 'KinematicbodyComponent'가 없습니다.
2	SideViewRectTileMap (SideViewRectTile, side-view tile)	SideviewbodyComponent	[LEA-3004] MissingComponent : Entity에 '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.

Details: references/platform.md §4 (mapping + check protocol), references/platform.md §11 (troubleshooting table), references/entity.md "Map Work Preflight".

---

8 Core Rules (must memorize)

1. If you don't align TileMapMode ↔ Body mapping, the entity will not move (no error) or raises [LEA-3004] MissingComponent at runtime → references/platform.md §4
2. User scripts only work as a .mlua + .codeblock pair — .codeblock is generated by Maker Refresh
3. If SpriteRUID is an empty string, the entity is invisible on screen (no error)
4. When calling SpawnByModelId, not passing a map entity (self.Entity.CurrentMap) as parent causes a runtime error
5. Coordinates are in world units (1 unit = 100 px). Pixel values are off by 100x
6. Maker only scans RootDesk/ — user files placed in Global/ will not be recognized
7. Do not modify .d.mlua or .codeblock. For .map/.ui/.model, prefer dedicated builders/editors over direct JSON editing
8. CoreVersion is 26.3.0.0 — do not work if there is a mismatch

---

MCP Tool Quick Reference (msw-maker-mcp)

Tool	Purpose
play / stop	Enter / exit play mode
refresh	Sync Maker after file change (not allowed during play)
logs / clear_logs	Read / clear runtime and build logs
screenshot	Call only when explicitly requested by the user
keyboard_input / mouse_input	Simulate input in play mode

Usage limits, parameters, async behavior detail → references/mcp-tools.md On MCP call failure / "MCP connection" / "API Key" requests → msw-env-setup skill

---

Per-task routing — which reference to read

Environment / domain understanding

What you want to know	File to read
MCP tool detail (parameters, constraints, async)	references/mcp-tools.md
World instance, Room, workspace, hierarchy, file paths, play mode	references/workspace.md

Platform rules / map / physics

What you want to know	File to read
TileMapMode ↔ Body, file pairs, coordinate system, layers, SpriteRUID, spawn rules	references/platform.md §1-8
MapleTile/RectTile/SideViewRectTile physics, movement, collision per map type	references/platform.md §9
Troubleshooting (not visible / not moving / floating in air / passing through walls, etc.)	references/platform.md §11
.directory, ID generation, EntryKey, .config, CoreVersion	references/platform.md §2,14-16

File authoring (.map / .model / .ui / .dataset)

Task	File to read
File authoring routing / shared principles	references/authoring.md
.map tile maps and tile sets (TileMapMode, tileMap, .tileset)	references/tile.md
.model templates (components, Properties, Values, Children)	references/model.md
.map entity placement / spawn / hierarchy	references/entity.md
.map JSON schema detail	references/entity/map-schema.md
.model JSON schema detail	references/model/model-schema.md
.ui authoring (anchors, UITransform, button/text/image/scroll)	references/ui.md
.ui schema, component API, enums, real-world patterns	references/ui/ui-schema.md, ui/ui-components.md, ui/ui-enums.md, ui/ui-patterns.md
.userdataset / .localedataset authoring	references/dataset.md
Template catalog when creating a new .model (monsters/NPCs/players/terrain/UI/sound, etc.)	references/model.md §2.1 → models/*.model
Monster authoring (canonical 11 components, ActionSheet lowercase keys stand/move/attack/hit/die/jump, HitComponent / IsLegacy / SortingLayer required overrides)	references/monster.md → models/MonsterCanonical.model

---

Absolute Principles (apply to every task)

0. If the task involves an entity, read references/entity.md first. No exceptions.
1. Visual polish — never leave SpriteRUID empty. Use msw-search to find resources.
2. refresh after every file change (if in play mode, stop first).
3. Never modify Environment/*.d.mlua — API definitions are read-only.
4. Never create or modify .codeblock by hand — Maker refresh generates it from .mlua.
5. Do not create new user files in Global/ — Maker will not recognize them. User files belong under RootDesk/MyDesk/.
6. Edit large files partially — never overwrite a .map/.model/.ui in full.
7. Entity reference binding (Entity/EntityRef property) — the AI injects the UUID string directly. Do not ask the user to drag in Maker.
8. Stop work on CoreVersion mismatch — first verify CoreVersion in Global/WorldConfig.config is 26.3.0.0.
9. Call screenshot only when the user explicitly requests it. Never call it automatically after task completion.
10. If a workflow step fails mid-flow, stop later steps — fix the root cause first.
11. Two-or-more = make a model. Whenever the same entity composition is placed ≥2 times in a map, author a .model first and instance it via modelId. Inline @components duplication is reserved for genuine one-off entities.
12. Models live in typed subfolders. Save new .model files under a category subfolder of RootDesk/MyDesk/Models/ (e.g. Models/Monsters/, Models/NPCs/, Models/Terrain/, Models/MapObjects/, Models/Particles/, Models/UI/) — never directly under MyDesk/ or Models/. When a needed subfolder does not exist, create it together with a .directory file at the same level (see references/platform.md §2).

---

Related Skills

Skill	Purpose
msw-env-setup	.mcp.json creation, API Key setup, MCP server connection
msw-scripting	.mlua authoring, @Component/@Logic, ExecSpace, @Sync, lifecycle, playtest / debugging
msw-search	Vector search for RUIDs, assets, docs, API
msw-defaultplayer	Player model, movement speed, jump force, HP, camera
msw-avatar	Avatar costume slots, equipment