RPG Maker MV/MZ Consistency Skill
This skill covers cross-file reference validation and consistency checking in
RPG Maker MV and MZ projects. It teaches agents how database IDs are referenced
across JSON data files, which reference types are checked, and how to detect
orphaned references and switch collisions that would cause silent bugs or
runtime crashes.
All consistency checks generated by this skill are drafts for developer review
-- never authoritative final content.
When to Use This Skill
Load this skill when:
- Validating a project's overall data integrity before shipping
- Checking whether item, actor, skill, weapon, armor, enemy, or troop IDs
referenced in events or database entries actually exist in the target file
- Finding orphaned items, skills, or database entries that no longer have
referencing events
- Detecting switch IDs that are SET in multiple maps (possible copy-paste
collision bugs)
- Running validation after any bulk edit operation that touched IDs or
restructured database files
- The user mentions consistency, validation, orphaned references, broken
references, switch collisions, or cross-file checks in an RPG Maker context
Critical Safety Rules
These rules prevent misuse of the validation scripts and ensure findings are
interpreted correctly.
Never auto-fix orphaned references. Removing or reassigning a reference
may break a quest chain, conditional branch, or plugin behavior the validator
cannot see. Flag the orphan and let the developer decide.
Switch collisions are warnings, not errors. The developer may
intentionally reuse a global switch across maps (e.g., a day/night toggle
set by both an outdoor map and an overworld map). Always confirm intent
before treating a collision as a bug.
validate_project.py is read-only. It never modifies project files. No
backup is needed before running it, but it is good practice anyway.
Always re-validate after any bulk edit operation. Adding enemies, moving
shop items, or renumbering actors can introduce new orphaned references that
were not present in the last validation pass.
Cross-File Reference Rules
Every database ID stored in a JSON field is a cross-file reference. If the
target entry does not exist at that array index, RPG Maker silently uses
fallback values or crashes.
| Reference Type |
Source Location |
Target File |
Check Method |
| Item pickup (code 126) |
Event params[0] |
Items.json |
ID in range and not null |
| Weapon change (code 127) |
Event params[0] |
Weapons.json |
ID in range and not null |
| Armor change (code 128) |
Event params[0] |
Armors.json |
ID in range and not null |
| Party member (code 129) |
Event params[0] |
Actors.json |
ID in range and not null |
| Shop goods (code 302) |
goods[n][1] |
Items/Weapons/Armors.json |
ID in range by type |
| Battle processing (code 301) |
Event params[0] |
Troops.json |
ID in range and not null |
| Control switches (code 121) |
Event params[0]-params[1] |
System.json switches |
ID within array length |
| Control variables (code 122) |
Event params[0]-params[1] |
System.json variables |
ID within array length |
| Actor name text code |
\N[id] in dialog |
Actors.json |
ID in range and not null |
| Icon text code |
\I[id] in dialog |
Items.json |
ID in range and not null |
| Enemy skill (database) |
Enemies.json actions[n].skillId |
Skills.json |
ID in range and not null |
| Troop member (database) |
Troops.json members[n].enemyId |
Enemies.json |
ID in range and not null |
| Class skill learn (database) |
Classes.json learnings[n].skillId |
Skills.json |
ID in range and not null |
| Actor class (database) |
Actors.json classId |
Classes.json |
ID in range and not null |
For the complete reference map with field paths and parameter layouts, see
references/cross-file-refs.md.
Validation Severity Levels
| Severity |
Meaning |
Exit Code |
Examples |
| ERROR |
Orphaned reference that would cause a runtime crash or silent data loss |
exit 1 |
Event references item ID 99 but Items.json only has IDs 1-3; enemy action references skill ID 50 which does not exist |
| WARNING |
Potential issue that may be intentional; developer should review |
exit 0 |
Switch ID 5 (unnamed) is SET in both Map001 and Map003 -- possible copy-paste collision |
For full severity rules by checker, see
references/validation-rules.md.
Helper Scripts
These scripts live in scripts/. Run from the repository root with PYTHONPATH=..
| Script |
Usage |
Purpose |
validate_project.py |
--project <path> |
Run all consistency checks; exit 0 = clean, exit 1 = errors |
check_orphaned_refs.py |
--project <path> |
Check cross-file references; exit 0 = clean, exit 1 = errors |
check_switch_collisions.py |
--project <path> |
Check for switch collision candidates; always exits 0 (warnings only) |
All scripts are read-only -- they never modify project files.
Quick Usage
# Run all consistency checks (recommended before shipping)
PYTHONPATH=. python scripts/validate_project.py --project path/to/project
# Check cross-file references only
PYTHONPATH=. python scripts/check_orphaned_refs.py --project path/to/project
# Check for switch collision candidates only
PYTHONPATH=. python scripts/check_switch_collisions.py --project path/to/project
Exit codes follow linting convention: 0 = no errors, 1 = one or more ERRORs.
Warnings never cause a non-zero exit.
Navigation
| Document |
Contents |
references/cross-file-refs.md |
Complete cross-file reference map: every field that stores a database ID, which file it points to, and the field path |
references/validation-rules.md |
ERROR vs WARNING severity rules for each checker, global-switch heuristic, and umbrella runner behavior |
../rpgmaker-core/SKILL.md |
Project structure, safety rules, MV/MZ detection |
../rpgmaker-events/SKILL.md |
Event command codes, switch/variable usage, event patterns |
All validation outputs from this skill are drafts for developer review. The
developer makes the final decisions about whether flagged issues need fixing.
1---2name: rpgmaker-consistency3description: Use this skill when validating cross-file references, checking for orphaned database entries, or detecting switch collisions in an RPG Maker MV or MZ project. Triggers: running project-wide validation, checking if item/actor/skill references resolve, finding switch ID conflicts across maps, or when the user mentions consistency, validation, orphaned references, broken references, switch collisions, or cross-file checks in an RPG Maker context. Provides: cross-file reference rules, orphaned reference detection, switch collision detection, and a master validate_project.py runner.4license: MIT5---67# RPG Maker MV/MZ Consistency Skill89This skill covers cross-file reference validation and consistency checking in10RPG Maker MV and MZ projects. It teaches agents how database IDs are referenced11across JSON data files, which reference types are checked, and how to detect12orphaned references and switch collisions that would cause silent bugs or13runtime crashes.1415All consistency checks generated by this skill are **drafts for developer review**16-- never authoritative final content.1718---1920## When to Use This Skill2122Load this skill when:2324- Validating a project's overall data integrity before shipping25- Checking whether item, actor, skill, weapon, armor, enemy, or troop IDs26 referenced in events or database entries actually exist in the target file27- Finding orphaned items, skills, or database entries that no longer have28 referencing events29- Detecting switch IDs that are SET in multiple maps (possible copy-paste30 collision bugs)31- Running validation after any bulk edit operation that touched IDs or32 restructured database files33- The user mentions consistency, validation, orphaned references, broken34 references, switch collisions, or cross-file checks in an RPG Maker context3536---3738## Critical Safety Rules3940These rules prevent misuse of the validation scripts and ensure findings are41interpreted correctly.42431. **Never auto-fix orphaned references.** Removing or reassigning a reference44 may break a quest chain, conditional branch, or plugin behavior the validator45 cannot see. Flag the orphan and let the developer decide.46472. **Switch collisions are warnings, not errors.** The developer may48 intentionally reuse a global switch across maps (e.g., a day/night toggle49 set by both an outdoor map and an overworld map). Always confirm intent50 before treating a collision as a bug.51523. **validate_project.py is read-only.** It never modifies project files. No53 backup is needed before running it, but it is good practice anyway.54554. **Always re-validate after any bulk edit operation.** Adding enemies, moving56 shop items, or renumbering actors can introduce new orphaned references that57 were not present in the last validation pass.5859---6061## Cross-File Reference Rules6263Every database ID stored in a JSON field is a cross-file reference. If the64target entry does not exist at that array index, RPG Maker silently uses65fallback values or crashes.6667| Reference Type | Source Location | Target File | Check Method |68|----------------|-----------------|-------------|--------------|69| Item pickup (code 126) | Event params[0] | Items.json | ID in range and not null |70| Weapon change (code 127) | Event params[0] | Weapons.json | ID in range and not null |71| Armor change (code 128) | Event params[0] | Armors.json | ID in range and not null |72| Party member (code 129) | Event params[0] | Actors.json | ID in range and not null |73| Shop goods (code 302) | goods[n][1] | Items/Weapons/Armors.json | ID in range by type |74| Battle processing (code 301) | Event params[0] | Troops.json | ID in range and not null |75| Control switches (code 121) | Event params[0]-params[1] | System.json switches | ID within array length |76| Control variables (code 122) | Event params[0]-params[1] | System.json variables | ID within array length |77| Actor name text code | `\N[id]` in dialog | Actors.json | ID in range and not null |78| Icon text code | `\I[id]` in dialog | Items.json | ID in range and not null |79| Enemy skill (database) | Enemies.json actions[n].skillId | Skills.json | ID in range and not null |80| Troop member (database) | Troops.json members[n].enemyId | Enemies.json | ID in range and not null |81| Class skill learn (database) | Classes.json learnings[n].skillId | Skills.json | ID in range and not null |82| Actor class (database) | Actors.json classId | Classes.json | ID in range and not null |8384For the complete reference map with field paths and parameter layouts, see85[`references/cross-file-refs.md`](references/cross-file-refs.md).8687---8889## Validation Severity Levels9091| Severity | Meaning | Exit Code | Examples |92|----------|---------|-----------|---------|93| **ERROR** | Orphaned reference that would cause a runtime crash or silent data loss | exit 1 | Event references item ID 99 but Items.json only has IDs 1-3; enemy action references skill ID 50 which does not exist |94| **WARNING** | Potential issue that may be intentional; developer should review | exit 0 | Switch ID 5 (unnamed) is SET in both Map001 and Map003 -- possible copy-paste collision |9596For full severity rules by checker, see97[`references/validation-rules.md`](references/validation-rules.md).9899---100101## Helper Scripts102103These scripts live in `scripts/`. Run from the repository root with `PYTHONPATH=.`.104105| Script | Usage | Purpose |106|--------|-------|---------|107| `validate_project.py` | `--project <path>` | Run all consistency checks; exit 0 = clean, exit 1 = errors |108| `check_orphaned_refs.py` | `--project <path>` | Check cross-file references; exit 0 = clean, exit 1 = errors |109| `check_switch_collisions.py` | `--project <path>` | Check for switch collision candidates; always exits 0 (warnings only) |110111All scripts are **read-only** -- they never modify project files.112113---114115## Quick Usage116117```bash118# Run all consistency checks (recommended before shipping)119PYTHONPATH=. python scripts/validate_project.py --project path/to/project120121# Check cross-file references only122PYTHONPATH=. python scripts/check_orphaned_refs.py --project path/to/project123124# Check for switch collision candidates only125PYTHONPATH=. python scripts/check_switch_collisions.py --project path/to/project126```127128Exit codes follow linting convention: `0` = no errors, `1` = one or more ERRORs.129Warnings never cause a non-zero exit.130131---132133## Navigation134135| Document | Contents |136|----------|---------|137| [`references/cross-file-refs.md`](references/cross-file-refs.md) | Complete cross-file reference map: every field that stores a database ID, which file it points to, and the field path |138| [`references/validation-rules.md`](references/validation-rules.md) | ERROR vs WARNING severity rules for each checker, global-switch heuristic, and umbrella runner behavior |139| [`../rpgmaker-core/SKILL.md`](../rpgmaker-core/SKILL.md) | Project structure, safety rules, MV/MZ detection |140| [`../rpgmaker-events/SKILL.md`](../rpgmaker-events/SKILL.md) | Event command codes, switch/variable usage, event patterns |141142---143144*All validation outputs from this skill are drafts for developer review. The145developer makes the final decisions about whether flagged issues need fixing.*
nightquill