create_npc
Create a complete, placed NPC event on a map with a single call. Provide dialogue text or explicit commands; the tool auto-builds the Show Text sequence, sprite, trigger, and direction.
Instructions
Create a complete, placed NPC event on a map in one call — a graphic + trigger + a talk list. Provide text (built into a Show Text sequence, with optional face/speaker) or an explicit commands array (commands wins if both given). Defaults to a solid, action-button NPC facing down. Warns (never blocks) on an unknown characterName, and on NO graphic at all (an NPC with no characterName is invisible in-game — use create_map_event for an intentionally-invisible trigger). The one-shot "make a talking NPC that says X" primitive.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | X tile position | |
| y | Yes | Y tile position | |
| name | Yes | Event name (editor label) | |
| text | No | Dialogue lines shown when the NPC is triggered (built as Show Text) | |
| force | No | Write even if validation finds structural problems (wrong parameter count, unterminated command list). Off by default: such a write is refused and nothing is written. Advisory warnings never block regardless. | |
| mapId | Yes | The ID of the map to place the NPC on | |
| dryRun | No | Preview only: return a diff of what would change without writing to disk. | |
| pattern | No | Sprite frame 0–2 (default 1 = idle when a sprite is set) | |
| through | No | Let the player pass through (default false) | |
| trigger | No | What starts the event (default action_button) | |
| commands | No | Explicit command list (from the build_* tools); overrides `text` if given | |
| faceName | No | text: face image basename (from list_assets("faces")) | |
| priority | No | Stacking vs. the player (default same = solid) | |
| direction | No | Facing direction (default down) | |
| faceIndex | No | text: face index 0–7 | |
| speakerName | No | text: MZ name-box speaker name | |
| characterName | No | Sprite sheet basename (from list_assets("characters")) | |
| characterIndex | No | Sprite index 0–7 in the sheet |