# Rpgmaker Dialog > Use this skill when writing, editing, or reviewing NPC dialog in an RPG Maker MV or MZ project. Triggers: editing CommonEvents.json or MapXXX.json dialog, writing character lines, reviewing text escape codes like \N[] or \V[], or when the user mentions dialog, NPC lines, conversation, text, cutscene dialog, or character voice in an RPG Maker context. Provides: dialog command code reference, text escape codes, voice consistency workflow, and helper scripts for extraction, injection, and validation. - Skill: `nightquill/rpgmaker-dialog` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add nightquill/rpgmaker-dialog` - Raw SKILL.md: https://api.skillmd.com/api/skills/nightquill/rpgmaker-dialog/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - License: MIT - Author: nightquill (https://skillmd.com/u/nightquill) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/nightquill/rpgmaker-dialog --- # RPG Maker Dialog Skill This skill covers reading, writing, and editing NPC dialog in RPG Maker MV and MZ projects. It teaches agents where dialog lives in the project files, what the event command structure looks like, and how to maintain character voice consistency when drafting new lines. All dialog suggestions generated by this skill are **drafts for developer review** — never authoritative final copy. --- ## Where Dialog Lives Dialog is stored as structured event commands in three locations: ### 1. `data/CommonEvents.json` Reusable dialog sequences — inn conversations, quest hand-ins, shop greetings. This file is a JSON array where **index 0 is always null**. Each event object has an `id`, `name`, and `list` of event commands. ```json [ null, { "id": 1, "name": "Innkeeper Dialog", "trigger": 0, "switchId": 0, "list": [ { "code": 101, "indent": 0, "parameters": ["Actor1", 0, 0, 2] }, { "code": 401, "indent": 0, "parameters": ["Welcome to the village inn!"] }, { "code": 0, "indent": 0, "parameters": [] } ] } ] ``` ### 2. `data/MapXXX.json` event pages NPC dialog attached to a specific map. Each map file has an `events` array (null at index 0). Each event has a `pages` array, and each page has a `list` of event commands. ```json { "events": [ null, { "id": 1, "name": "Innkeeper", "pages": [ { "list": [ { "code": 101, "indent": 0, "parameters": ["Actor1", 0, 0, 2] }, { "code": 401, "indent": 0, "parameters": ["Hello traveler!"] }, { "code": 0, "indent": 0, "parameters": [] } ] } ] } ] } ``` ### 3. `data/System.json` terms UI text — menu labels, battle messages, status names. Not NPC dialog, but text fields agents may need to review or update. Modify with care; this file also holds the currency unit name (`currencyUnit`) and other engine settings. --- ## Dialog Command Codes Every dialog block follows this structure. For the full command code reference, see [`../shared/references/event-command-codes.md`](../shared/references/event-command-codes.md). ### Code 101 — Show Text (header) Starts a dialog block. Sets the face portrait and window position. ```json { "code": 101, "indent": 0, "parameters": ["Actor1", 0, 0, 2] } ``` Parameters: `[faceName: string, faceIndex: int, backgroundType: int, positionType: int]` | Parameter | Values | |-----------|--------| | `faceName` | Filename of the face sprite sheet (e.g., `"Actor1"`) | | `faceIndex` | 0–7: which portrait in the 4×2 sprite sheet | | `backgroundType` | 0 = window, 1 = dim, 2 = transparent | | `positionType` | 0 = top, 1 = middle, 2 = bottom | ### Code 401 — Show Text (line) One line of dialog text. Must follow a code 101. Multiple 401s form a multi-line message (RPG Maker shows up to 4 lines per text window). ```json { "code": 401, "indent": 0, "parameters": ["Please, \\N[1], you must help us!"] } ``` Parameters: `[text: string]` — one entry per visible line. ### Code 102 — Show Choices Presents the player with a choice menu. ```json { "code": 102, "indent": 0, "parameters": [["Yes", "No"], 1, 0, 2, 0] } ``` Parameters: `[choices: string[], cancelType: int, defaultType: int, positionType: int, background: int]` `cancelType`: -1 = disallow cancel, 0–N = cancel maps to that choice index. ### Code 402 — When [Choice] Branch block for one specific choice. Indent increases by 1. ```json { "code": 402, "indent": 1, "parameters": [0, "Yes"] } ``` ### Code 403 — When Cancel Branch executed when the player presses cancel (if `cancelType` ≠ -1). ```json { "code": 403, "indent": 1, "parameters": [] } ``` ### Code 404 — End Choice Closes the choice block. Indent returns to the level of the 102. ```json { "code": 404, "indent": 1, "parameters": [] } ``` ### Code 0 — List Terminator Every event command list **must end with this entry**. Insert new dialog blocks **before** the code-0 terminator, never after it. ```json { "code": 0, "indent": 0, "parameters": [] } ``` ### Complete Example ```json [ { "code": 101, "indent": 0, "parameters": ["Actor1", 0, 0, 2] }, { "code": 401, "indent": 0, "parameters": ["Would you like to rest? It's 50 gold."] }, { "code": 102, "indent": 0, "parameters": [["Yes", "No"], 1, 0, 2, 0] }, { "code": 402, "indent": 1, "parameters": [0, "Yes"] }, { "code": 101, "indent": 2, "parameters": ["Actor1", 0, 0, 2] }, { "code": 401, "indent": 2, "parameters": ["Sweet dreams!"] }, { "code": 402, "indent": 1, "parameters": [1, "No"] }, { "code": 101, "indent": 2, "parameters": ["Actor1", 0, 0, 2] }, { "code": 401, "indent": 2, "parameters": ["Come back anytime."] }, { "code": 404, "indent": 1, "parameters": [] }, { "code": 0, "indent": 0, "parameters": [] } ] ``` --- ## Text Escape Codes RPG Maker text supports inline escape codes for dynamic content. The most critical codes to know: | Code | Effect | Example | |------|--------|---------| | `\N[n]` | Actor name by ID | `\N[1]` → "Hero" | | `\V[n]` | Variable value | `\V[1]` → current value of variable 1 | | `\C[n]` | Text color | `\C[1]` = blue, `\C[0]` = default white | | `\I[n]` | Inline icon | `\I[64]` → icon 64 from IconSet.png | Full table: [`../shared/references/text-codes.md`](../shared/references/text-codes.md) **NEVER strip or modify text codes during extraction or editing.** Preserve them verbatim. `\N[1]` in the source must appear as `\N[1]` in extracted output and any re-injected content. In JSON files, backslashes are escaped: the source text `\N[1]` is stored as `\\N[1]` in the JSON string. When reading with `json.load()`, Python gives you the raw `\N[1]` string. --- ## Voice Consistency Workflow Before drafting new dialog for any character, always extract and review their existing lines first. This is the single most important rule for maintaining believable character voice. Quick summary: 1. Extract existing lines with `extract_npc_lines.py` 2. Analyze tone, vocabulary, sentence length, verbal tics 3. Draft new lines matching the identified voice patterns 4. Validate that all `\N[id]` and `\I[id]` references point to real entries Full step-by-step guide: [`references/character-voice.md`](references/character-voice.md) --- ## Never Fabricate References Before using `\N[id]` or `\I[id]` in any dialog line: - Check `data/Actors.json` to confirm the actor ID exists - Check `data/Items.json` to confirm the item ID exists - Never invent IDs. A non-existent `\N[99]` displays a blank string in-game and corrupts voice/immersion silently. `\V[n]` (variable) and `\C[n]` (color) do not require database cross-checks — variables are runtime values, colors are engine constants (0–31). Run `validate_dialog_refs.py` before finalizing any dialog changes. --- ## Helper Scripts These scripts live in `skills/rpgmaker-dialog/scripts/`. Run them from the repository root with `PYTHONPATH=. python skills/rpgmaker-dialog/scripts/