Rpgmaker Events

# RPG Maker MV/MZ Events Skill

This skill covers reading, writing, and editing event command lists in RPG
Maker MV and MZ projects. It teaches agents how events are structured in the
project files, which command codes to use for common behaviors, and how to use
switches, variables, and self-switches to gate event state.

All event patterns generated by this skill are **drafts for developer review**
— never authoritative final content.

---

## When to Use This Skill

Load this skill when:

- Editing the `list` array inside a CommonEvent or Map event page
- Creating NPC behaviors (wandering, dialog gating, shops, inns)
- Setting or checking switch, variable, or self-switch state
- Scaffolding a standard event pattern (chest, shop, inn, door, cutscene, wanderer)
- Expanding or debugging a conditional branch (code 111) structure
- The user mentions events, map events, common events, triggers, switches, or
  variables in an RPG Maker context

---

## Critical Safety Rules

These rules prevent silent data corruption. Apply them before writing any
event command JSON.

1. **Code-0 terminator is mandatory.** Every event command list must end with
   `{"code": 0, "indent": 0, "parameters": []}`. RPG Maker stops processing
   at code 0. Its absence causes undefined behavior without error messages.

2. **Never renumber event IDs.** Events in both `CommonEvents.json` and
   `MapXXX.json` have `id` fields that match their array index (MV) or object
   key (MZ). Changing either silently breaks every cross-file reference.

3. **Indent must match nesting.** The `indent` field is purely positional —
   RPG Maker uses it to determine block membership. Getting it wrong corrupts
   the event's logical structure and may crash the game.

4. **Self-switch params are strings, not integers.** Code 123 (Control Self
   Switch) takes `"A"`, `"B"`, `"C"`, or `"D"` for `params[0]`. Using
   integers (0, 1, 2, 3) silently fails at runtime.

5. **Use 412 to close a conditional branch, not 413.** Code 412 is End of
   Conditional Branch. Code 413 is Repeat Above (loop end — closes code 112).
   Using 413 to close a 111 corrupts event flow without error.

6. **Do not modify `note` field content.** Note fields are opaque strings
   used by plugins. Parse or alter them and plugin behavior breaks silently.

---

## Event Command Code Overview

Every event command has exactly three fields: `code`, `indent`, `parameters`.

| Range | Category | Key Codes |
|-------|----------|-----------|
| 100s | Dialog, flow control, switch/variable control, inventory | 101, 111, 121, 122, 123, 125, 126 |
| 200s | Map movement, screen effects, audio | 201, 205, 221, 222, 230, 241, 250 |
| 300s | Battle, actor modification, shop | 301, 302, 311, 355, 356, 357 |
| 500s | Move route sub-commands (inside code 205 route objects) | 1-4, 9, 10, 11 |
| 600s | Battle branch markers, shop goods | 601, 602, 603, 604, 605 |

For the full code table with parameter details, see
[`../shared/references/event-command-codes.md`](../shared/references/event-command-codes.md).

### The Most Commonly Needed Codes

| Code | Name | Quick Use |
|------|------|-----------|
| `101` | Show Text (header) | Opens dialog window, sets face portrait |
| `401` | Show Text (line) | One line of dialog |
| `102` | Show Choices | Branching player choice |
| `111` | Conditional Branch | If/else on switch, variable, self-switch, etc. |
| `121` | Control Switches | Set a switch ON or OFF |
| `122` | Control Variables | Set a variable to a value |
| `123` | Control Self Switch | Set self-switch A/B/C/D on current event |
| `126` | Change Items | Add or remove items from inventory |
| `201` | Transfer Player | Move player to a different map/position |
| `205` | Set Movement Route | Make a character move |
| `302` | Shop Processing | Open shop menu |

---

## Common Event Patterns

Six standard patterns cover most map event interactions. Each has required
parameters; scaffold_event.py generates the full command list JSON.

| Pattern | Description | CLI Example |
|---------|-------------|-------------|
| `chest` | One-time item pickup; uses self-switch A to mark opened | `python scripts/scaffold_event.py --project <path> --pattern chest --item-id 3` |
| `shop` | Opens the shop menu with configurable goods | `python scripts/scaffold_event.py --project <path> --pattern shop --shop-items "0,3" --shop-items "1,5"` |
| `inn` | Choice-gated rest for gold; heals HP/MP | `python scripts/scaffold_event.py --project <path> --pattern inn --cost 50` |
| `door` | Conditional door: open if self-switch A, else locked; transfers player | `python scripts/scaffold_event.py --project <path> --pattern door --map-id 2 --x 5 --y 10` |
| `cutscene` | Switch-gated dialog sequence; clears switch when done | `python scripts/scaffold_event.py --project <path> --pattern cutscene --switch-id 1` |
| `wanderer` | NPC with random movement route | `python scripts/scaffold_event.py --project <path> --pattern wanderer` |

Full JSON for each pattern with parameter tables and notes:
[`references/event-patterns.md`](references/event-patterns.md)

---

## Switches, Variables, and Self-Switches

| Type | Scope | Persistence | Max Count | Storage |
|------|-------|-------------|-----------|---------|
| Switch | Global (whole project) | Saved to savefile | Limited by System.json array | `System.json["switches"]` |
| Variable | Global (whole project) | Saved to savefile | Limited by System.json array | `System.json["variables"]` |
| Self-Switch | Per-event (A/B/C/D only) | Saved per event instance | Always 4 per event | Game save data (not JSON) |

Quick usage:
- **Set switch:** code 121 — `[startId, endId, 0=ON/1=OFF]`
- **Check switch:** code 111 with `params[0]=0` — `[0, switchId, 0=ON/1=OFF]`
- **Set variable:** code 122 — `[startId, endId, operation, operandType, value]`
- **Set self-switch:** code 123 — `["A"|"B"|"C"|"D", 0=ON/1=OFF]` (string params!)
- **Check self-switch:** code 111 with `params[0]=2` — `[2, "A"|"B"|"C"|"D", 0=ON/1=OFF]`

Full guide with page condition fields and script usage:
[`references/switch-and-variable.md`](references/switch-and-variable.md)

---

## MV vs MZ Differences

Most event code structure is identical between MV and MZ (~90% compatible).
The key differences:

| Feature | MV | MZ |
|---------|----|----|
| Plugin command code | `356` — single string `"PluginName cmd arg1"` | `357` — array `["Plugin", "Cmd", "", {args}]` |
| Map `events` field | Array (null at index 0) | Object keyed by string ID |
| `pluginCommands` field | Not present | Added to event command structure |

`scaffold_event.py` calls `project_detect.detect_version()` to automatically
select code 356 (MV) or 357 (MZ) for plugin commands.

---

## Helper Scripts

These scripts live in `scripts/`. Run from the repository root with `PYTHONPATH=.`.

| Script | Usage | Purpose |
|--------|-------|---------|
| `scaffold_event.py` | `--project <path> --pattern <name> [pattern flags]` | Print a scaffolded event command list JSON to stdout |
| `list_switches.py` | `--project <path>` | List all switch references across the project as a markdown table |
| `find_event_refs.py` | `--project <path> --switch-id N \| --var-id N \| --self-switch A\|B\|C\|D` | Find all references to a specific switch, variable, or self-switch |

All scripts are **read-only output** — no file modifications, no dry-run flag needed.

### Quick Usage

```bash
# Scaffold a chest event (item ID 3, quantity 1)
PYTHONPATH=. python scripts/scaffold_event.py \
  --project fixtures/example-mv-project \
  --pattern chest --item-id 3

# List all switch references in the project
PYTHONPATH=. python scripts/list_switches.py \
  --project fixtures/example-mv-project

# Find all references to switch ID 1
PYTHONPATH=. python scripts/find_event_refs.py \
  --project fixtures/example-mv-project --switch-id 1

# Find all references to self-switch A
PYTHONPATH=. python scripts/find_event_refs.py \
  --project fixtures/example-mv-project --self-switch A
```

---

## Navigation

| Document | Contents |
|----------|---------|
| [`references/event-patterns.md`](references/event-patterns.md) | Six parameterized event pattern templates with full JSON and CLI examples |
| [`references/switch-and-variable.md`](references/switch-and-variable.md) | Switch vs variable vs self-switch usage guide with command code cross-reference |
| [`references/map-event-structure.md`](references/map-event-structure.md) | Map event page structure, conditions object, trigger types |
| [`../shared/references/event-command-codes.md`](../shared/references/event-command-codes.md) | Full event command code table (100s–600s) with parameter details |
| [`../rpgmaker-core/SKILL.md`](../rpgmaker-core/SKILL.md) | Project structure, safety rules, MV/MZ detection |

---

*All event patterns generated by this skill are drafts for developer review.
The developer makes the final structural and gameplay decisions.*