# Rpgmaker Consistency

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

- Skill: `nightquill/rpgmaker-consistency` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nightquill/rpgmaker-consistency`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nightquill/rpgmaker-consistency/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: nightquill (https://skillmd.com/u/nightquill)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nightquill/rpgmaker-consistency

---


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

1. **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.

2. **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.

3. **validate_project.py is read-only.** It never modifies project files. No
   backup is needed before running it, but it is good practice anyway.

4. **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`](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`](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

```bash
# 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`](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`](references/validation-rules.md) | ERROR vs WARNING severity rules for each checker, global-switch heuristic, and umbrella runner behavior |
| [`../rpgmaker-core/SKILL.md`](../rpgmaker-core/SKILL.md) | Project structure, safety rules, MV/MZ detection |
| [`../rpgmaker-events/SKILL.md`](../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.*