io.github.Redseb/rpgmaker-mz-mcp

Add a "learn skill at level" entry to a class (replaces the hack of attaching skills to an actor via an Add-Skill trait). Validates the skillId exists and keeps the learnings sorted by level. Warns (never blocks) when the skill's stypeId is not covered by an Add Skill Type trait ({ code: 41, dataId: stypeId, value: 1 }) on the class — without it the skill-type command never appears and actors cannot use the skill.

Add a command to an event page. Refuses the write (nothing is saved) if the resulting page is structurally invalid — e.g. the command has the wrong parameter count for its code. Pass force: true to override.

Append one battle-event page (e.g. the `page` from build_troop_page) to an existing troop without re-sending its other pages; `position` inserts it at that 0-based page index instead (the first page whose conditions hold runs, so order matters when triggers overlap). A structurally invalid page refuses the write (nothing is saved) — pass force: true to override; an HP condition on a troop slot past the troop's members, or a page with no condition enabled, is warned (never blocked). Returns { troop, pageIndex, warnings? }; fill it further with insert_event_commands target "troop_page".

Create many database records of one type in a single call and a single file write — the batch sibling of create_actor/create_item/create_weapon/create_armor/create_skill/create_enemy/create_state/create_class. Each entry in `records` takes the same fields its single create_* tool accepts (only `name` is required for most; omitted fields use the editor's defaults). Ids are allocated sequentially from the current max, so a record can reference a sibling created earlier in the same batch. Use this instead of N sequential create_* calls when authoring a cast, a loot table, or a skill list. Returns `{ type, count, created, warnings? }` (classes are summarized like create_class; enemy battlerName misses and record fields the create_* tool doesn't accept are warnings, never blocked). Throws — writing nothing at all — if any record references a database id that does not exist, naming the offending records[i].

Build an in-battle event command for a troop battle-event page (see build_troop_page / add_troop_page / insert_event_commands target "troop_page"): enemy_appear (335 — reveal a troop member added with hidden: true, i.e. a summon/reinforcement), enemy_state (333 — add/remove a state on one troop member or the whole troop, e.g. a telegraph "Gathering power" state), or abort_battle (340 — end the battle with no victory/defeat; the calling Battle Processing takes its Escape branch). `enemyIndex` is the 0-based troop slot (members[] order), NOT an enemy id; enemy_state also accepts -1 = entire troop. Read-only: returns { command }.

Build a Battle Processing (301) event command for insertion via insert_event_commands — start a battle against a troop (direct id, a variable holding the id, or "random" like the map encounters). canEscape/canLose gate the battle result branches. Read-only: returns { command }.

Build an actor stat-change scene command for insertion via insert_event_commands: hp (311), mp (312), state (313), recover_all (314), exp (315), or level (316). Targets a fixed actor (0 = whole party) or a variable. hp/mp/exp/level take an increase/decrease `operand` (constant or variable); state takes add/remove + `stateId`; recover_all takes nothing extra. Read-only: returns { command }.

Build a Change Gold (125) event command for insertion via insert_event_commands — increase or decrease party gold by a constant or variable amount. Read-only: returns { command }.

Build a Change Items (126), Change Weapons (127), or Change Armors (128) event command for insertion via insert_event_commands — gain/lose an item/weapon/armor by a constant or variable amount. includeEquip (weapon/armor only) also counts equipped copies when removing. Read-only: returns { command }.

Build a Change Party Member (129) event command for insertion via insert_event_commands — add or remove an actor from the party. initialize (add only) resets the actor to their initial state. Read-only: returns { command }.

Build a Show Animation (212) or Show Balloon Icon (213) event command for insertion via insert_event_commands, played over a character (characterId: -1 player, 0 this event, N event id). Read-only: returns { command }.

Build a Conditional Branch block (111 condition + then-branch + optional 411 Else + 412 closer, each branch terminated like the editor) for insertion via insert_event_commands. Condition types: switch, self_switch, variable, actor_in_party, gold, item. Provide thenBranch/elseBranch as EventCommand[] (e.g. from other builders). Read-only: returns { commands }.

Build a Control Switches (121) or Control Self Switch (123) event command for insertion via insert_event_commands. scope "switch": set a switch (or the inclusive switchId..endId range) on/off. scope "self_switch": set the current event's self switch A–D. Read-only: returns { command }.

Build a Control Variables (122) event command for insertion via insert_event_commands. Applies operation (set/add/sub/mul/div/mod) to a variable (or the inclusive variableId..endId range) using an operand: constant, another variable, a random range, or game_data (item/actor/party/… readouts). Read-only: returns { command }.

Build a single flow-control event command for insertion via insert_event_commands: wait (230, N frames), exit_event (115), label (118, a named jump target), or jump_to_label (119). Read-only: returns { command }.

Build a Name Input Processing (303) event command for insertion via insert_event_commands — open the name-entry screen for an actor. Read-only: returns { command }.

Build a Show Picture (231) or Erase Picture (235) event command for insertion via insert_event_commands. show: display `name` in slot `pictureId` with origin/position/scale/opacity/blend; erase: clear the slot. Read-only: returns { command }.

Build a Play BGM/BGS/ME/SE (241/245/249/250) event command for insertion via insert_event_commands. Warns (never blocks) when `name` is not a known audio asset for that channel (checked against list_assets). Returns { command, warnings? }.

Build a screen transition/effect event command for insertion via insert_event_commands: fadeout (221) / fadein (222) — no params; tint (223) & flash (224) — an [r,g,b,a] color over `duration` frames; shake (225) — power/speed over `duration`. `wait` holds the event until it finishes. Read-only: returns { command }.

Build a Shop Processing (302 + one 605 row per extra good) event-command sequence for insertion via insert_event_commands. Each good sells an item/weapon/armor at its database price, or a specified `price`. purchaseOnly hides the sell tab. Read-only: returns { commands }.

Build a Show Choices block (102 opener + a 402 branch per choice + optional 403 When-Cancel branch + 404 closer, each branch terminated like the editor) for insertion via insert_event_commands. Pass per-choice `branches` (each an EventCommand[] — e.g. from build_show_text) to fill the branch bodies. Read-only: returns { commands }.

Build a Show Text event-command sequence (101 setup + one 401 line per text line) for insertion via insert_event_commands. Supports face image (from list_assets("faces")), window background/position, and the MZ name-box speaker. MZ does NOT word-wrap: keep each line under ~55 chars (~38 with a face) or it is cut off at the window edge (warned, never blocked) — or pass `wrap: true` to word-wrap automatically to that same width (escape codes like \C[n] do not count) and split into as many 4-line message boxes as needed. Read-only: returns { commands, warnings? }, writes nothing.

Build a Transfer Player (201) event command for insertion via insert_event_commands — move the party to (x, y) on a map. With designation "variable", mapId/x/y are variable ids resolved at runtime. Read-only: returns { command }.

Build a troop battle-event page { conditions, list, span } from a compact trigger — no hand-built 12-field conditions object. `when` keys (ANDed, at least one): turn [a, b] (turn a + b*X; b 0 = only turn a), enemyHpBelow [enemyIndex, pct] (0-based troop slot, NOT enemy id), actorHpBelow [actorId, pct], switch id, turnEnd true. `span`: battle (runs once per battle, default), turn (once per turn), moment (re-runs while the condition holds — guard it with a switch). Timing (turn-based battles): an enemy action pattern with conditionType 1 / [a, b] is chosen during turn N's input phase (troop turnCount N-1, +1) and a troop page turn [a, b] is checked once turn N's action phase starts (turnCount N), so matching [a, b] land on the same battle turn N — the page runs before anyone acts; add turnEnd: true to run it after that turn resolves instead (the classic telegraph: warn at the end of the wind-up turn, strike next turn). Turn 0 = battle start. With b > 0 use span "turn", or a "battle" page fires only once. `commands` come from the build_* tools (build_show_text, build_battle_command, …); the end marker is appended. Read-only: returns { page } — land it with add_troop_page (or create_troop/update_troop `pages`).

Build a "Common Event" event command (code 117) that calls the given common event, for insertion into an event page via insert_event_commands. Validates the common event exists. Read-only: returns `{ command }` (matching the build_* tools, so it composes into a thenBranch/commands array); writes nothing.

Check whether a map cell can be walked onto, reproducing the engine's layered passage rule: the stacked tiles at (x, y) are examined upper-layer first, and the first non-[*] tile decides each direction. Reads the map's tileset flags. Returns per-direction passability (down/left/right/up — true = a character can walk off the cell that way), the cell's terrain tag, the stacked tile ids, and — when `direction` is given — a single `passable` boolean for that direction. Read-only.

Create a new actor in data/Actors.json. Only `name` is required; omitted fields use the editor's new-actor defaults (class 1, level 1-99, five empty equip slots, no traits). Allocates and returns the next unused actor id. NOTE: an actor's physical accuracy comes from its class + own traits — a class/actor with no Hit Rate trait (xparam id 0: trait { code: 22, dataId: 0, value: 0.95 }) always misses physical actions. The built-in class 1 has one; a custom class needs it added.

Create a new armor in data/Armors.json. Only `name` is required; omitted fields use the editor's new-armor defaults (Shield equip slot, no stat bonuses). `params` is a flat 8-length stat bonus; `etypeId` is the equip slot (System.json equipTypes: 2 Shield, 3 Head, 4 Body, 5 Accessory). Allocates and returns the next unused armor id.

Create a buff skill (simplified)

Create a complete, placed treasure chest on a map in one call — the two-page self-switch idiom done correctly, so the chest can never be looted twice. Page 1 (closed) is an action-button, priority-`same` event that optionally shows `text`, gives the contents, then flips its self switch; page 2 (opened) is gated on that self switch, shows the opened graphic and does nothing. `kind` picks the payout: item/weapon/armor (needs `id`) or gold. On the RTP `!Chest` sheet the open/closed states are the *direction* rows of one character block (down = closed, up = open), which is what closedDirection/openedDirection default to. Throws if the item/weapon/armor `id` does not exist; warns (never blocks) on an unknown characterName or a chest with no graphic.

Create a new character class in data/Classes.json. Only `name` is required; omitted fields use the editor's new-class defaults (EXP curve [30,20,30,30], no traits/learnings, a linear param curve to maxLevel). Allocates and returns the next unused class id. NOTE: a class with no Hit Rate trait (xparam id 0: trait { code: 22, dataId: 0, value: 0.95 }) makes its actors always miss physical actions — pass one in `traits` for a combat-ready class. Likewise every learned skill's stypeId needs an Add Skill Type trait ({ code: 41, dataId: stypeId, value: 1 }) or the skill-type command never appears (warned, never blocked).

Create a new common event (reusable event-command list) in data/CommonEvents.json. Only `name` is required; omitted fields use the editor's new-slot defaults (empty command list, trigger 0 = call-only, switchId 1). Allocates and returns the next unused id. A structurally invalid command list refuses the write (nothing is saved) — pass force: true to override.

Create a damage-dealing skill (simplified)

Create a new enemy in data/Enemies.json. Only `name` is required; omitted fields use the editor's new-enemy defaults (100 HP, one Attack action, no drops). Allocates the next unused enemy id and returns `{ enemy, warnings? }` (warn-by-default: a `battlerName` not found in img/enemies (img/sv_enemies for a side-view project) is flagged, never blocked). Throws if an `actions[].skillId` or a `dropItems[].dataId` (item/weapon/armor by `kind`) references a record that does not exist. NOTE: an enemy with no Hit Rate trait (xparam id 0: trait { code: 22, dataId: 0, value: 0.95 }) always misses physical actions — pass one in `traits` if the enemy should land basic attacks.

Create a healing skill (simplified)

Create a new item in data/Items.json. Only `name` is worth passing; omitted fields use the editor's new-item defaults (Regular Item, consumable, no effects). Allocates and returns the next unused item id. An effect referencing a missing record throws: Add/Remove State (code 21/22) → state, Learn Skill (43) → skill, Common Event (44) → common event.

Create a new blank map: writes a new data/MapNNN.json (all tiles unpainted) and registers it in the map tree (MapInfos.json). Allocates the next unused map id and returns it. Paint tiles afterward with paint_tiles/fill_area (autotile-aware) and add events with create_map_event/create_npc.

Create a new event on a map. Each page is merged onto a blank "New Event" page (trigger 0 action-button, priority 0 below characters, no graphic, empty command list, standing move type), so you only supply the fields that differ — pass e.g. `{ image: { characterName: 'Actor1', characterIndex: 0 }, trigger: 3, list: [...] }` and the rest is filled in. Nested `image`/`conditions` deep-merge; an omitted `list` becomes a valid empty (code-0-terminated) list. Omit `pages` entirely for a bare one-page event. For the common "talking NPC" case prefer create_npc. An action-button page meant to fire from facing (doors, entrances, signs) needs `priorityType: 1` — with the default 0 (below) it only fires when stood on, so on an impassable tile it can never trigger (this is refused, not written; pass force: true to override). A structurally invalid command list is refused the same way. A page with no graphic, priority 1 and through off on a walkable tile is an invisible wall — warned (not refused); give it priority 0 or through: true if it should be walked past. Exempt: an action-button page over a drawn upper-layer (B–E) object — the solid-landmark idiom. Page fields: `image` { characterName, characterIndex, direction (2 down/4 left/6 right/8 up), pattern, tileId }, `trigger` (0 action-button/1 player-touch/2 event-touch/3 autorun/4 parallel), `priorityType` (0 below/1 same/2 above), `moveType` (0 fixed/1 random/2 approach/3 custom), `conditions`, `list`.

Build a movement route from a named pattern (patrol/approach/flee/wander/custom) instead of raw move-command codes. Read-only: returns { moveRoute, warnings? }. Use the route as an event page’s autonomous moveRoute (update_map_event with moveType 3), or feed it to set_movement_route for a forced route in an event command list.

Create a complete, placed NPC event on a map in one call — a graphic + trigger + a talk list. Provide `text` (built into a Show Text sequence, with optional face/speaker; `wrap: true` word-wraps paragraphs into 4-line message boxes) or an explicit `commands` array (commands wins if both given). Defaults to a solid, action-button NPC facing down. Warns (never blocks) on an unknown characterName, and on NO graphic at all (an NPC with no characterName is invisible in-game — use create_map_event for an intentionally-invisible trigger). The one-shot "make a talking NPC that says X" primitive.

Build an RPG Maker MZ plugin command (event command code 357) for insertion into an event page via add_event_command. Validates against the plugins this project actually ships (scanned from their js/plugins/*.js @command/@arg annotations) merged over a small built-in allowlist — warn-by-default: an unknown plugin/command, a stray arg, or a plugin that is installed but disabled in js/plugins.js produces a warning but never blocks. Args are normalized to the editor’s string-valued shape. Read-only: returns { command, warnings? }, writes nothing.

Create a new skill with custom properties. Omitted fields use new-skill defaults: stypeId 1 (Magic), scope 1, occasion 1 (battle only), hitType derived — 0 certain for recovery or ally/user scopes, else 2 magical for Magic skills, else 1 physical if it deals damage, else 0. An effect referencing a missing record throws: Add/Remove State (code 21/22) → state, Learn Skill (43) → skill, Common Event (44) → common event.

Create a new state (status condition like Poison/Sleep) in data/States.json. Only `name` is required; omitted fields use the editor's new-state defaults (no restriction, priority 50, no auto-removal, 1-turn duration). Allocates and returns the next unused state id.

Create a state-inflicting skill (poison, sleep, etc.). Throws if `stateId` does not exist in States.json (create the state first with create_state).