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

| Script | Purpose |
|--------|---------|
| `extract_npc_lines.py` | Extract all dialog lines attributed to a named NPC across the whole project |
| `inject_dialog.py` | Inject a new dialog block into a CommonEvent or Map event |
| `validate_dialog_refs.py` | Validate that all `\N[id]` and `\I[id]` text code references exist in the database |

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

### Quick usage

```bash
# 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

| Document | Contents |
|----------|---------|
| [`references/character-voice.md`](references/character-voice.md) | Step-by-step voice consistency workflow with examples |
| [`../shared/references/text-codes.md`](../shared/references/text-codes.md) | Full text escape code reference table |
| [`../shared/references/event-command-codes.md`](../shared/references/event-command-codes.md) | Dialog event command code reference (101, 401, 102, 402, 403, 404) |
| [`../rpgmaker-core/SKILL.md`](../rpgmaker-core/SKILL.md) | Project structure, safety rules, MV/MZ detection |

---

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