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.

For the full code table with parameter details, see ../shared/references/event-command-codes.md.

The Most Commonly Needed Codes

Common Event Patterns

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

Full JSON for each pattern with parameter tables and notes: references/event-patterns.md

Switches, Variables, and Self-Switches

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

MV vs MZ Differences

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

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

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

Quick Usage

# 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

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