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.

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

{
  "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.

Code 101 — Show Text (header)

Starts a dialog block. Sets the face portrait and window position.

{ "code": 101, "indent": 0, "parameters": ["Actor1", 0, 0, 2] }

Parameters: [faceName: string, faceIndex: int, backgroundType: int, positionType: int]

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

{ "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.

{ "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.

{ "code": 402, "indent": 1, "parameters": [0, "Yes"] }

Code 403 — When Cancel

Branch executed when the player presses cancel (if cancelType ≠ -1).

{ "code": 403, "indent": 1, "parameters": [] }

Code 404 — End Choice

Closes the choice block. Indent returns to the level of the 102.

{ "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.

{ "code": 0, "indent": 0, "parameters": [] }

Complete Example

[
  { "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:

Full table: ../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

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/<script>.py.

All write operations default to dry-run mode. Pass --apply to write changes. A .bak backup is created automatically before any modification.

Quick usage

# Extract all dialog lines for the Hero NPC
PYTHONPATH=. python skills/rpgmaker-dialog/scripts/extract_npc_lines.py \
  --project fixtures/example-mv-project --npc Hero

# Inject new dialog into CommonEvent 1 (dry run)
PYTHONPATH=. python skills/rpgmaker-dialog/scripts/inject_dialog.py \
  --project fixtures/example-mv-project \
  --target common-event:1 \
  --lines "Good morning, traveler." "The weather's fine today."

# Validate all dialog references in the project
PYTHONPATH=. python skills/rpgmaker-dialog/scripts/validate_dialog_refs.py \
  --project fixtures/example-mv-project

Navigation

All dialog suggestions generated by this skill are drafts for developer review. The developer makes the final creative and structural decisions.