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: 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.

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.

8 Core Rules (must memorize)

1. If you don't align TileMapMode ↔ Body mapping, the entity will not move (no error) → 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)

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

Platform rules / map / physics

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

Absolute Principles (apply to every task)

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