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.
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.
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
# 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 |
Actor fields: classId cross-reference, equips array, face/character sprite indexes |
references/skill-schema.md |
Skill fields: scope/occasion/hitType codes, damage sub-object details |
references/item-schema.md |
Item fields: itypeId codes, consumable flag, effects array |
references/weapon-schema.md |
Weapon fields: wtypeId, params bonuses, animationId |
references/armor-schema.md |
Armor fields: atypeId, etypeId slot codes, params bonuses |
references/enemy-schema.md |
Enemy fields: params base stats, dropItems structure, actions array |
references/state-schema.md |
State fields: restriction codes, removal timing, motion/overlay indexes |
references/damage-formulas.md |
Formula DSL variables, damage.type codes, common patterns, Python pitfall |
references/balance-heuristics.md |
Per-category metrics, 2-SD method, worked examples, anti-patterns |
../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.
1---2name: rpgmaker-database3description: 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.4license: MIT5---67# RPG Maker Database Skill89This skill covers reading and modifying RPG Maker MV and MZ database files. It10teaches agents what each database file contains, how damage formulas work, how11to detect balance outliers, and how to safely append new entries without12corrupting cross-file references.1314All database suggestions generated by this skill are **drafts for developer review** — never authoritative final content.1516---1718## Database Files Overview1920All database files in `data/` are JSON arrays where **index 0 is always21`null`**. Each entry's `id` field equals its array index. The two exceptions22are `System.json` (single object) and `MapInfos.json` (positional array but23append-only — see rpgmaker-core).2425| File | Content | Key Fields | Notes |26|------|---------|-----------|-------|27| `Actors.json` | Playable characters | `classId`, `equips`, `traits` | `equips` cross-refs Weapons/Armors |28| `Classes.json` | Character class definitions | `expParams`, `params`, `traits` | Stat growth curves per level |29| `Skills.json` | Learnable abilities | `damage.formula`, `mpCost`, `scope` | `damage.formula` is JavaScript |30| `Items.json` | Consumables and key items | `itypeId`, `consumable`, `effects` | `itypeId: 2` = key item (unsellable) |31| `Weapons.json` | Equippable weapons | `wtypeId`, `params`, `animationId` | `params` = stat bonuses (not base stats) |32| `Armors.json` | Equippable armor/accessories | `atypeId`, `etypeId`, `params` | `etypeId` determines equipment slot |33| `Enemies.json` | Enemy battlers | `params`, `exp`, `dropItems` | `params` = base stats (not bonuses) |34| `Troops.json` | Enemy group definitions | `members`, `pages` | Battle event pages |35| `States.json` | Status effects | `restriction`, `autoRemovalTiming` | `restriction: 4` = cannot act |36| `Animations.json` | Battle animations | `frames`, `timings` | Referenced by `animationId` fields |37| `Tilesets.json` | Map tile configuration | `tilesetNames`, `flags` | Passage/terrain tag data |38| `CommonEvents.json` | Reusable event scripts | `trigger`, `list` | Call from maps or other events |39| `System.json` | Global game settings | `switches`, `variables`, `elements` | Single object — not a positional array |40| `MapInfos.json` | Map tree for the editor | `parentId`, `order` | **Append-only** — never reorder or delete |4142---4344## Positional Array Rules4546These rules apply to every database file except `System.json` and `MapInfos.json`:4748- **Index 0 is always `null`.** Do not remove it. RPG Maker requires it.49- **Each entry's `id` field equals its array index.** Changing either value50 breaks every cross-file reference silently.51- **Never renumber, reorder, or compact the array.** Deleted entries become52 `null` (tombstone), not removed.53- **New entries are appended.** Assign `new_id = len(array)` before appending.5455---5657## The Params Array5859The `params` field is an 8-element integer array used by Enemies (base stats),60Weapons and Armors (stat bonuses), and Classes (growth curves).6162| Index | Stat Name | Abbreviation |63|-------|-----------|-------------|64| 0 | Max HP | MHP |65| 1 | Max MP | MMP |66| 2 | Attack | ATK |67| 3 | Defense | DEF |68| 4 | Magic Attack | MAT |69| 5 | Magic Defense | MDF |70| 6 | Agility | AGI |71| 7 | Luck | LUK |7273> **Enemies vs. Weapons/Armors:** For enemies, `params` is the enemy's **base74> stats**. For weapons and armors, `params` is **stat bonuses** added on top of75> the actor's class curve. The same indexes, very different semantics.7677---7879## Damage Formula DSL8081The `damage.formula` field in Skills.json is a **JavaScript expression**82evaluated at runtime by the RPG Maker engine. The variables `a` (attacker)83and `b` (target) expose the battler's current stats.8485| Variable | Meaning |86|----------|---------|87| `a.atk` | Attacker's Attack stat |88| `a.mat` | Attacker's Magic Attack |89| `a.luk` | Attacker's Luck |90| `b.def` | Target's Defense |91| `b.mdf` | Target's Magic Defense |92| `b.hp` | Target's current HP |9394Common formula patterns:9596| Type | Formula |97|------|---------|98| Physical damage | `a.atk * 4 - b.def * 2` |99| Magical damage | `a.mat * 4 - b.mdf * 2` |100| Strong magic | `a.mat * 5 - b.mdf * 2` |101| HP restore | `a.mat * 2 + 20` |102| Percent HP | `b.hp * 0.1` |103104`damage.type` codes control what the formula affects:105106| Code | Effect |107|------|--------|108| 0 | None |109| 1 | HP damage |110| 2 | MP damage |111| 3 | HP recover |112| 4 | MP recover |113| 5 | HP drain |114| 6 | MP drain |115116For full formula reference and the pitfall of evaluating these as Python, see117[`references/damage-formulas.md`](references/damage-formulas.md).118119---120121## Note Field Safety122123The `note` field in every database entry is an **opaque string** used by the124plugin ecosystem (Yanfly Engine Plugins, VisuStella MZ, and others). Plugins125store their configuration in this field using `<tag>value</tag>` syntax.126127**Never parse, strip, reformat, or validate `note` field contents.** Write it128back byte-for-byte. `json.load()` followed by `json.dump()` preserves all129content including embedded newlines and Unicode characters.130131When adding a new entry via `add_skill.py` or `add_enemy.py`, accept the note132value verbatim from the caller via `--note`. Default to `""` if omitted.133134---135136## Balance Checking137138Balance checking uses **statistical outlier detection**: compute the relevant139metric per entry in a category, then flag any entry more than 2 standard140deviations above the mean. This approach adapts to whatever power level the141project uses — no hardcoded thresholds.142143Three categories are supported:144145| Category | Metric | What It Catches |146|----------|--------|----------------|147| Skills | Damage per MP (`formula_damage / mpCost`) | Overpowered spells relative to their cost |148| Weapons | Price per power point (`price / (ATK + MAT)`) | Overpriced weapons for their stats |149| Enemies | HP per EXP (`params[0] / exp`) | Unrewarding tanks |150151Only HP-damage skills (`damage.type == 1`) with `mpCost > 0` are included in152skill analysis. Skills with `mpCost == 0` (physical) or `damage.type != 1`153(heals, drains) are excluded.154155For the statistical method, worked examples, and anti-patterns, see156[`references/balance-heuristics.md`](references/balance-heuristics.md).157158---159160## Helper Scripts161162These scripts live in `skills/rpgmaker-database/scripts/`. Run from the163repository root with `PYTHONPATH=.`.164165| Script | Usage | Purpose |166|--------|-------|---------|167| `scripts/balance_check.py` | `--project <path> [--category skills\|weapons\|enemies\|all]` | Flags balance outliers; exit 0 = clean, exit 1 = outliers found |168| `scripts/add_skill.py` | `--project <path> --name <name> [--formula <formula>] [--mp-cost <n>] [--note <note>] [--apply]` | Appends a new skill to Skills.json |169| `scripts/add_enemy.py` | `--project <path> --name <name> [--hp <n>] [--atk <n>] [--exp <n>] [--note <note>] [--apply]` | Appends a new enemy to Enemies.json |170| `scripts/validate_database.py` | `--project <path>` | Validates all database JSON files against `schemas/*.schema.json` |171172All write operations default to **dry-run mode**. Pass `--apply` to write.173A `.bak` backup is created automatically before any write.174175### Quick usage176177```bash178# Check balance of all categories179PYTHONPATH=. python scripts/balance_check.py \180 --project fixtures/example-mv-project181182# Add a new skill (dry run)183PYTHONPATH=. python scripts/add_skill.py \184 --project fixtures/example-mv-project \185 --name "Blizzard" --formula "a.mat * 6 - b.mdf * 2" --mp-cost 12186187# Add a new skill (write)188PYTHONPATH=. python scripts/add_skill.py \189 --project fixtures/example-mv-project \190 --name "Blizzard" --formula "a.mat * 6 - b.mdf * 2" --mp-cost 12 \191 --apply192193# Validate all database files194PYTHONPATH=. python scripts/validate_database.py \195 --project fixtures/example-mv-project196```197198---199200## Navigation201202| Document | Contents |203|----------|---------|204| [`references/actor-schema.md`](references/actor-schema.md) | Actor fields: classId cross-reference, equips array, face/character sprite indexes |205| [`references/skill-schema.md`](references/skill-schema.md) | Skill fields: scope/occasion/hitType codes, damage sub-object details |206| [`references/item-schema.md`](references/item-schema.md) | Item fields: itypeId codes, consumable flag, effects array |207| [`references/weapon-schema.md`](references/weapon-schema.md) | Weapon fields: wtypeId, params bonuses, animationId |208| [`references/armor-schema.md`](references/armor-schema.md) | Armor fields: atypeId, etypeId slot codes, params bonuses |209| [`references/enemy-schema.md`](references/enemy-schema.md) | Enemy fields: params base stats, dropItems structure, actions array |210| [`references/state-schema.md`](references/state-schema.md) | State fields: restriction codes, removal timing, motion/overlay indexes |211| [`references/damage-formulas.md`](references/damage-formulas.md) | Formula DSL variables, damage.type codes, common patterns, Python pitfall |212| [`references/balance-heuristics.md`](references/balance-heuristics.md) | Per-category metrics, 2-SD method, worked examples, anti-patterns |213| [`../rpgmaker-core/SKILL.md`](../rpgmaker-core/SKILL.md) | Project structure, safety rules, MV/MZ detection, safe_write.py |214215---216217*All database suggestions generated by this skill are **drafts for developer review**. The developer makes the final creative and structural decisions.*
nightquill