msw-general

What this skill does

# 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)) → 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)) 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).

---

## 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 — **you must `Read` [references/builder-protocol.md](references/builder-protocol.md) IN FULL FIRST** (no `offset` / `limit`). No exceptions.

`builder-protocol.md` is the single entry point that consolidates the call protocol of all three builders (`MapBuilder` / `ModelBuilder` / `UIBuilder`) into one document. **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) — and the three are interlocked through cross-flow (model authoring → map placement → ui binding), which is why they share one document.

Triggers (intentionally broad — `Read` builder-protocol.md 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** builder-protocol.md — they are not substitutes (domain context + call protocol are a pair). **Do not skip on the grounds that you read it in a prior turn** — re-read every turn.

---

## 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 — **you must `Read` [references/model.md](references/model.md) IN FULL FIRST*