# Rpgmaker Database

> Use this skill when reading or writing RPG Maker MV or MZ database files (Actors.json, Skills.json, Items.json, Weapons.json, Armors.json, Enemies.json, States.json, Troops.json, Classes.json, Animations.json, Tilesets.json, CommonEvents.json, System.json). Triggers: any modification to data/*.json database entries, adding skills/enemies/items/actors, balance checking, schema validation, or when the user mentions database, stats, formulas, balance, notetags, or data entry in an RPG Maker context. Provides: database file schemas, damage formula DSL, balance heuristics, and helper scripts for safe entry addition, validation, and outlier detection.

- Skill: `nightquill/rpgmaker-database` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add nightquill/rpgmaker-database`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nightquill/rpgmaker-database/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-database

---


# RPG Maker Database Skill

This skill covers reading and modifying RPG Maker MV and MZ database files. It
teaches agents what each database file contains, how damage formulas work, how
to detect balance outliers, and how to safely append new entries without
corrupting cross-file references.

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

---

## Database Files Overview

All database files in `data/` are JSON arrays where **index 0 is always
`null`**. Each entry's `id` field equals its array index. The two exceptions
are `System.json` (single object) and `MapInfos.json` (positional array but
append-only — see rpgmaker-core).

| File | Content | Key Fields | Notes |
|------|---------|-----------|-------|
| `Actors.json` | Playable characters | `classId`, `equips`, `traits` | `equips` cross-refs Weapons/Armors |
| `Classes.json` | Character class definitions | `expParams`, `params`, `traits` | Stat growth curves per level |
| `Skills.json` | Learnable abilities | `damage.formula`, `mpCost`, `scope` | `damage.formula` is JavaScript |
| `Items.json` | Consumables and key items | `itypeId`, `consumable`, `effects` | `itypeId: 2` = key item (unsellable) |
| `Weapons.json` | Equippable weapons | `wtypeId`, `params`, `animationId` | `params` = stat bonuses (not base stats) |
| `Armors.json` | Equippable armor/accessories | `atypeId`, `etypeId`, `params` | `etypeId` determines equipment slot |
| `Enemies.json` | Enemy battlers | `params`, `exp`, `dropItems` | `params` = base stats (not bonuses) |
| `Troops.json` | Enemy group definitions | `members`, `pages` | Battle event pages |
| `States.json` | Status effects | `restriction`, `autoRemovalTiming` | `restriction: 4` = cannot act |
| `Animations.json` | Battle animations | `frames`, `timings` | Referenced by `animationId` fields |
| `Tilesets.json` | Map tile configuration | `tilesetNames`, `flags` | Passage/terrain tag data |
| `CommonEvents.json` | Reusable event scripts | `trigger`, `list` | Call from maps or other events |
| `System.json` | Global game settings | `switches`, `variables`, `elements` | Single object — not a positional array |
| `MapInfos.json` | Map tree for the editor | `parentId`, `order` | **Append-only** — never reorder or delete |

---

## Positional Array Rules

These rules apply to every database file except `System.json` and `MapInfos.json`:

- **Index 0 is always `null`.** Do not remove it. RPG Maker requires it.
- **Each entry's `id` field equals its array index.** Changing either value
  breaks every cross-file reference silently.
- **Never renumber, reorder, or compact the array.** Deleted entries become
  `null` (tombstone), not removed.
- **New entries are appended.** Assign `new_id = len(array)` before appending.

---

## The Params Array

The `params` field is an 8-element integer array used by Enemies (base stats),
Weapons and Armors (stat bonuses), and Classes (growth curves).

| Index | Stat Name | Abbreviation |
|-------|-----------|-------------|
| 0 | Max HP | MHP |
| 1 | Max MP | MMP |
| 2 | Attack | ATK |
| 3 | Defense | DEF |
| 4 | Magic Attack | MAT |
| 5 | Magic Defense | MDF |
| 6 | Agility | AGI |
| 7 | Luck | LUK |

> **Enemies vs. Weapons/Armors:** For enemies, `params` is the enemy's **base
> stats**. For weapons and armors, `params` is **stat bonuses** added on top of
> the actor's class curve. The same indexes, very different semantics.

---

## Damage Formula DSL

The `damage.formula` field in Skills.json is a **JavaScript expression**
evaluated at runtime by the RPG Maker engine. The variables `a` (attacker)
and `b` (target) expose the battler's current stats.

| Variable | Meaning |
|----------|---------|
| `a.atk` | Attacker's Attack stat |
| `a.mat` | Attacker's Magic Attack |
| `a.luk` | Attacker's Luck |
| `b.def` | Target's Defense |
| `b.mdf` | Target's Magic Defense |
| `b.hp` | Target's current HP |

Common formula patterns:

| Type | Formula |
|------|---------|
| Physical damage | `a.atk * 4 - b.def * 2` |
| Magical damage | `a.mat * 4 - b.mdf * 2` |
| Strong magic | `a.mat * 5 - b.mdf * 2` |
| HP restore | `a.mat * 2 + 20` |
| Percent HP | `b.hp * 0.1` |

`damage.type` codes control what the formula affects:

| Code | Effect |
|------|--------|
| 0 | None |
| 1 | HP damage |
| 2 | MP damage |
| 3 | HP recover |
| 4 | MP recover |
| 5 | HP drain |
| 6 | MP drain |

For full formula reference and the pitfall of evaluating these as Python, see
[`references/damage-formulas.md`](references/damage-formulas.md).

---

## Note Field Safety

The `note` field in every database entry is an **opaque string** used by the
plugin ecosystem (Yanfly Engine Plugins, VisuStella MZ, and others). Plugins
store their configuration in this field using `<tag>value</tag>` syntax.

**Never parse, strip, reformat, or validate `note` field contents.** Write it
back byte-for-byte. `json.load()` followed by `json.dump()` preserves all
content including embedded newlines and Unicode characters.

When adding a new entry via `add_skill.py` or `add_enemy.py`, accept the note
value verbatim from the caller via `--note`. Default to `""` if omitted.

---

## Balance Checking

Balance checking uses **statistical outlier detection**: compute the relevant
metric per entry in a category, then flag any entry more than 2 standard
deviations above the mean. This approach adapts to whatever power level the
project uses — no hardcoded thresholds.

Three categories are supported:

| Category | Metric | What It Catches |
|----------|--------|----------------|
| Skills | Damage per MP (`formula_damage / mpCost`) | Overpowered spells relative to their cost |
| Weapons | Price per power point (`price / (ATK + MAT)`) | Overpriced weapons for their stats |
| Enemies | HP per EXP (`params[0] / exp`) | Unrewarding tanks |

Only HP-damage skills (`damage.type == 1`) with `mpCost > 0` are included in
skill analysis. Skills with `mpCost == 0` (physical) or `damage.type != 1`
(heals, drains) are excluded.

For the statistical method, worked examples, and anti-patterns, see
[`references/balance-heuristics.md`](references/balance-heuristics.md).

---

## Helper Scripts

These scripts live in `skills/rpgmaker-database/scripts/`. Run from the
repository root with `PYTHONPATH=.`.

| Script | Usage | Purpose |
|--------|-------|---------|
| `scripts/balance_check.py` | `--project <path> [--category skills\|weapons\|enemies\|all]` | Flags balance outliers; exit 0 = clean, exit 1 = outliers found |
| `scripts/add_skill.py` | `--project <path> --name <name> [--formula <formula>] [--mp-cost <n>] [--note <note>] [--apply]` | Appends a new skill to Skills.json |
| `scripts/add_enemy.py` | `--project <path> --name <name> [--hp <n>] [--atk <n>] [--exp <n>] [--note <note>] [--apply]` | Appends a new enemy to Enemies.json |
| `scripts/validate_database.py` | `--project <path>` | Validates all database JSON files against `schemas/*.schema.json` |

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

### Quick usage

```bash
# Check balance of all categories
PYTHONPATH=. python scripts/balance_check.py \
  --project fixtures/example-mv-project

# Add a new skill (dry run)
PYTHONPATH=. python scripts/add_skill.py \
  --project fixtures/example-mv-project \
  --name "Blizzard" --formula "a.mat * 6 - b.mdf * 2" --mp-cost 12

# Add a new skill (write)
PYTHONPATH=. python scripts/add_skill.py \
  --project fixtures/example-mv-project \
  --name "Blizzard" --formula "a.mat * 6 - b.mdf * 2" --mp-cost 12 \
  --apply

# Validate all database files
PYTHONPATH=. python scripts/validate_database.py \
  --project fixtures/example-mv-project
```

---

## Navigation

| Document | Contents |
|----------|---------|
| [`references/actor-schema.md`](references/actor-schema.md) | Actor fields: classId cross-reference, equips array, face/character sprite indexes |
| [`references/skill-schema.md`](references/skill-schema.md) | Skill fields: scope/occasion/hitType codes, damage sub-object details |
| [`references/item-schema.md`](references/item-schema.md) | Item fields: itypeId codes, consumable flag, effects array |
| [`references/weapon-schema.md`](references/weapon-schema.md) | Weapon fields: wtypeId, params bonuses, animationId |
| [`references/armor-schema.md`](references/armor-schema.md) | Armor fields: atypeId, etypeId slot codes, params bonuses |
| [`references/enemy-schema.md`](references/enemy-schema.md) | Enemy fields: params base stats, dropItems structure, actions array |
| [`references/state-schema.md`](references/state-schema.md) | State fields: restriction codes, removal timing, motion/overlay indexes |
| [`references/damage-formulas.md`](references/damage-formulas.md) | Formula DSL variables, damage.type codes, common patterns, Python pitfall |
| [`references/balance-heuristics.md`](references/balance-heuristics.md) | Per-category metrics, 2-SD method, worked examples, anti-patterns |
| [`../rpgmaker-core/SKILL.md`](../rpgmaker-core/SKILL.md) | Project structure, safety rules, MV/MZ detection, safe_write.py |

---

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