Msw General

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` core + `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.

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.

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` core + `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/model.md §1.

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.