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.
MCP get_skill({ skillId: "rpg-maker-database-skill-bf9ef807" })Use this skill with your agent
Create a free account and connect via MCP
# 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.*
Related Skills
More skills in Game Development
Game Developer
Use when building game systems, implementing Unity/Unreal Engine features, or optimizing game performance. Invoke to implement ECS architecture, configure physics systems and colliders, set up multiplayer networking with lag compensation, optimize frame rates to 60+ FPS targets, develop shaders, or apply game design patterns such as object pooling and state machines. Trigger keywords: Unity, Unreal Engine, game development, ECS architecture, game physics, multiplayer networking, game optimization, shader programming, game AI.
Game Engine
Expert skill for building web-based game engines and games using HTML5, Canvas, WebGL, and JavaScript. Use when asked to create games, build game engines, implement game physics, handle collision detection, set up game loops, manage sprites, add game controls, or work with 2D/3D rendering. Covers techniques for platformers, breakout-style games, maze games, tilemaps, audio, multiplayer via WebRTC, and publishing games.
Godot Gdscript Patterns
Master Godot 4 GDScript patterns including signals, scenes, state machines, and optimization. Use when building Godot games, implementing game systems, or learning GDScript best practices.
Minecraft Modpack Server
Host modded Minecraft servers (CurseForge, Modrinth).
Minecraft Modpack Server Setup
Host modded Minecraft servers (CurseForge, Modrinth).
Minecraft Plugin Development
Use this skill when building or modifying Minecraft server plugins for Paper, Spigot, or Bukkit, including plugin.yml setup, commands, listeners, schedulers, player state, team or arena systems, persistent progression, economy or profile data, configuration files, Adventure text, and version-safe API usage. Trigger for requests like "build a Minecraft plugin", "add a Paper command", "fix a Bukkit listener", "create plugin.yml", "implement a minigame mechanic", "add a perk or quest system", or "debug server plugin behavior".
Explore Other Categories
Skills from other categories with shared topics
Soul
Embody this digital identity. Read SOUL.md first, then STYLE.md, then examples/. Become the person—opinions, voice, worldview.
.NET Backend Development Patterns
Master C#/.NET backend development patterns for building robust APIs, MCP servers, and enterprise applications. Covers async/await, dependency injection, Entity Framework Core, Dapper, configuration, caching, and testing with xUnit. Use when developing .NET backends, reviewing C# code, or designing API architectures.
/math - Unified Math Capabilities
Unified math capabilities - computation, solving, and explanation. I route to the right tool.