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 + bX; 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).

Create a complete, placed map-transfer event in one call, using whichever of the two working idioms you pick. idiom: "action_button" (default) makes a priority-same event the player faces and presses — the right shape for a solid landmark (building, dungeon mouth, door); idiom: "player_touch" makes an invisible priority-below doormat the player walks onto — for interior exits and map-edge gaps. direction is the facing the player lands with, fade the screen transition. Throws if the destination map does not exist; warns if the destination tile is outside that map, if the characterName is unknown, or if the event can never fire from where it sits.

Create a new troop (enemy battle group) in data/Troops.json. name is required; members defaults to empty and pages to one blank battle-event page. Every member.enemyId must reference an existing enemy. A structurally invalid battle-event page refuses the write (nothing is saved) — pass force: true to override.

Create a new weapon in data/Weapons.json. Only name is required; omitted fields use the editor's new-weapon defaults (Weapon equip slot, no stat bonuses). params is a flat 8-length stat bonus [maxHP, maxMP, atk, def, mat, mdf, agi, luk]. Allocates and returns the next unused weapon id.

Delete a map: remove its entry from the map tree (MapInfos.json) and delete its data/MapNNN.json file. The deleted map's direct children are reparented onto its parent (not deleted), so removing one node doesn't wipe a whole sub-tree. Does not touch System.json.

Delete an event from a map by ID

Delete one database record (actor, class, skill, item, weapon, armor, enemy, troop, state, or common_event) by nulling its slot — ids never shift, so nothing else is renumbered. Reports every reference the deletion would leave dangling (an actor's class, a troop member, a Change Items / Shop / Battle Processing command, a skill effect, the starting party, …; found with the same audit validate_references runs, see coverage in the response) and REFUSES, writing nothing, when there are any — pass force: true to delete anyway, or dryRun: true to preview the references without throwing. Deleting skill 1 (Attack), skill 2 (Guard) or state 1 (Knockout) is always reported, since the engine hard-codes them. Returns { type, deleted: { id, name }, referenceCount, references[], coverage }.

Decode a raw RPG Maker MZ tile id into its tileset sheet (A1–A5, B–E), and for autotiles its kind + shape slot (0–47) and autotile geometry (floor/wall/waterfall). Read-only inspection helper — raw tile ids are opaque integers, this makes one legible. Returns { tileId, empty, sheet, sheetIndex, autotile, kind?, shape?, autotileType? }. Pass tilesetId to also inspect the sheet PNG and report transparent (true = the tile is see-through and needs an opaque base tile on a lower layer; painting it on layer 0 alone shows the map void) + transparentPercent.

Export a pruned HTML5 web deployment (for itch.io or any static host): copies index.html, js/, css/, fonts/, icon/ and data/.json, plus only the img/audio/movies files the game references (every string in data/.json, string literals in the core js and plugins, plugin @default annotations; img/system is always kept) and only the effects/*.efkefc Effekseer effects actually referenced (an animation's effectName, a Plugin Command argument, or a plugin parameter/string — not other data strings) together with the textures/models they list internally. Writes the folder to outDir and, by default, .zip with index.html at the archive root. Returns file/byte counts, kept/dropped asset counts (+ dropped paths), the screen size from System.advanced (the itch embed size), and warnings for itch's 1000-file / 200 MB-per-file limits. Writes nothing inside the project; outDir must be outside the project's copied folders, and an existing non-empty outDir is only replaced if it was a previous export_web output. Follow up with a playtest of the exported build.

Fill a rectangular area of a map with one tile id, with automatic autotiling — a filled autotile region borders itself correctly (and re-borders any same-kind tiles it touches). Flat tiles fill uniformly. Defaults to the lower ground layer (0). For region ids, fill layer 5 with the region number as tileId.

Find tiles in a tileset by a case-insensitive SUBSTRING match on their catalog name — a quick bridge from a name fragment like 'grass' or 'forest' to a paintable tile id. This is a literal substring match, NOT synonym/semantic search: 'water' matches 'Endless Waterfall' but not 'Sea' or 'Pond' (their names lack the substring). To browse the actual tile names first, use get_tile_catalog with a sheet filter, then search a fragment you see. Set searchDescriptions: true to also match the free-text description a project catalog carries (custom sheets named by the tileset-catalog skill — their names are terse, the descriptions say what the tile looks like); built-in RPG Maker entries have no description, so this only widens the search over custom sheets. Returns matching catalog entries (name, sheet, tile id, autotile kind, source, matchedIn [which fields matched], transparent [true = needs an opaque base on a lower layer], plus description/confidence/manual for project catalog drafts). Covers the default RPG Maker tilesets, non-default sheets with a .txt name sidecar in img/tilesets/ (DLC packs ship these; loaded automatically, source: 'sidecar'), plus custom sheets cataloged into data/tilecatalog/ (via the tileset-catalog skill). Read-only.

Read a database table in full: actors, classes, items, weapons, armors, skills, enemies, troops, states, or common_events. Returns the raw 1-indexed array (slot 0 is null), or — with id — that single record, or null if no such record exists. These are full records: prefer list_names for an id→name index, or search_actors/search_items/search_skills to find records by name, and reach for this only when you need every field. Maps and tilesets are not here: use get_map_infos/get_map and get_tilesets/get_tile_flags. Read-only.

Get the game title

Get map data by ID. The tile data array can be huge on a painted map (widthheight6 ints) and blow the MCP token limit, so pass includeData:false to omit it (you get dataTileCount instead) and read tiles with get_map_region when needed. includeData defaults to true for backward compatibility.

Get the width and height (in tiles) of a map

Get a specific event from a map

Get all events from a specific map

Get information about all maps

Read the raw tile ids in a rectangular window of one map layer — a token-cheap alternative to get_map for inspecting part of a painted map. Returns tiles as a 2D array (rows top→bottom, each left→right) of raw engine tile ids. The rectangle must lie fully within the map bounds (throws otherwise). layer defaults to 0 (see set_map_tile for the z-layer meanings).

Get the starting party — the actor ids the game begins with. Returns { partyMembers }, rhyming with set_party's input/output shape.

Get the project directory the server is currently operating on: its path, whether it is a valid RPG Maker MZ project, and the game title it holds.

Get the game starting position ({ mapId, x, y })

Get all game switch names

Get system data

Get the game vocabulary/terms: the basic, commands, params string arrays and the messages map (menu labels, system messages).

Get the semantic tile catalog for a tileset: the named tiles (e.g. 'Grassland A', 'Forest', 'Sea') in each of its image sheets, each with its representative tile id and a source ('builtin' = RPG Maker's own labels; 'sidecar' = authoritative names from an img/tilesets/.txt file shipped next to a non-default sheet, as DLC packs do; 'project' = a data/tilecatalog/ entry — a vision-bootstrap draft, or a human-verified manual one, which outranks a sidecar name). Project (custom-sheet) entries also carry the skill's description, confidence ('high'/'medium'/'low'), and manual (true = a human verified it) so you can gauge how trustworthy a draft name is. Autotile entries (A1–A4) return the kind's base tile id — feed it to a paint command, which recomputes the shape from neighbours. Covers the default RPG Maker tilesets, any non-default sheet with a .txt name sidecar in img/tilesets/ (loaded automatically), plus custom sheets cataloged into data/tilecatalog/ (via the tileset-catalog skill); still-uncovered sheets are omitted. Called WITHOUT sheet it returns only a per-sheet index (name + entry count) to stay within the tool-output limit — a full tileset can hold thousands of named tiles. Pass sheet (filename 'World_A2' or slot role 'A2') to list one sheet's actual tile entries. Sheet-filtered entries also carry transparent (true = the tile is see-through and needs an opaque base tile on a lower layer — painting it on layer 0 alone shows the map void; e.g. trees/objects/overlays). Read-only.

Decode a tileset's flag word for a single tile id into a legible view: 4-direction passability (down/left/right/up — true = walkable that way), the [*] 'star' overlay bit, ladder/bush/counter/damage-floor flags, and terrain tag (0–7). Read-only inspection of data/Tilesets.json flags[]. Note passability here is for the tile in isolation; a real cell's passability layers its stacked tiles — use check_passability for that. Returns { tilesetId, tileId, tile, flags }.

List every tileset in the project with its id, name, mode (0 world / 1 area), and the image sheets it uses (labelled A1–A4, A5, B–E; empty slots omitted). Use this to discover valid tilesetId values (needed by find_tile, get_tile_catalog, paint_tiles, fill_area, place_object, get_tile_flags, set_tile_flags, check_passability) and to see which sheets each tileset is built from. For a plain id→name list, list_names(type:"tilesets") is even cheaper. Read-only.

Get the title screen settings: title1Name/title2Name (background layers, from list_assets("titles1"/"titles2") — title2Name draws over title1Name), titleBgm (the AudioFile that plays while it is shown), and drawTitle (whether the game title text is drawn over the art).

Get one System.json type-name array — the named lists other data references by index: elements, skillTypes, weaponTypes, armorTypes, or equipTypes.

Get all game variable names

Insert a pre-built sequence of event commands (from the build_* builders) into any of the three command lists an MZ project has — the mutating companion to the read-only builders. Splices before the list’s end marker (or at position). target "map_event" (the default) needs mapId + eventId + pageIndex; "common_event" needs commonEventId; "troop_page" needs troopId + pageIndex. The resulting list is validated before writing: a structural problem (wrong parameter count for a command code, a list left unterminated) refuses the write and saves nothing — pass force: true to override. Advisory findings (unrecognized code, over-long text line) are returned as warnings and never block. Returns { target, id, listLength, listCodes, warnings? } — the resulting list as its length and its command CODES, which is what you verify a splice against; pass verbose: true for the full list with parameters, or read it back with get_map_event.

Show which switch / variable / common-event IDs are already spoken for, derived from the project's own JSON (never a hand-maintained list, which would drift the moment someone edited in the RPG Maker editor). An id counts as allocated if it is declared (a System.json label, a CommonEvents row) OR referenced anywhere — event page conditions and command lists, common events, troop pages, and Common Event skill/item effects. Use this before reusing an id, and pass id to answer "where is switch 23 actually used?" before touching it. Returns { count, highest, gaps, declaredCapacity, allocated[], coverage }. Read-only. To claim a fresh id instead, use next_free_id.

List the available asset filenames (extension stripped) for one asset kind — the exact names RPG Maker's data references (a sprite/face/tileset/audio name). Use it to validate a graphic or audio name before wiring it into an event; a wrong filename fails silently at runtime. Fails soft: an unused asset directory returns an empty list.

Cheap names-only index for a database table. Returns { id, name } entries instead of full records — use it to look up or sanity-check IDs before wiring them into events, without paying the token cost of a full get_*/search_* dump.

List every plugin command create_plugin_command can validate (plugin filename → command key → args): the plugins this project actually ships, scanned from their js/plugins/*.js annotations, merged over a small built-in allowlist. Pass pluginName to narrow to one plugin. Read-only. Use scan_plugins for the richer per-project view (arg types/defaults, enabled state); an unlisted plugin command can still be built, it just isn’t validated.

Reserve the next unallocated switch / variable / common-event ID(s) instead of picking one by hand. Ids are handed out strictly above every id already declared or referenced, so two sessions editing the same project over time cannot silently claim the same switch — a collision that never crashes and only surfaces hours into a playtest as a door that is inexplicably already open. Pass reuseGaps: true to fill holes below the highest id first (off by default: a hole is often an id claimed in notes but not yet written). Read-only — it suggests ids, it does not write them; name what you take with set_switch_name / set_variable_name so the next session sees the claim.

Expand a top-left flat tile id + a width×height size into the grid of tile ids that object occupies on the sheet — feed the returned tiles straight into place_object. This handles the flat sheets' two-half-column layout, where the tile below id N is NOT N+16 (indices 0–127 are the left half of the sheet, 128–255 the right), which is otherwise painful to compute by hand. Get the top-left id from find_tile/get_tile_catalog. Read-only. Throws if topLeftId isn't a flat id or the rectangle runs off the 16×16 sheet; warns if the tileset lacks that sheet.

Paint a whole map area from an ASCII blueprint in ONE call and one write. rows are equal-length strings (one glyph per cell); legend maps each glyph to what that cell holds: [[layer, tile], ...] pairs (multi-layer cells, e.g. ground on 0 + fence on 1); a bare string = a catalog tile name on layer 0; { wall: { top, side?, faceHeight?, layer? }, tiles?: [...] } = an A4 wall (or A3 roof) — every cell gets the wall-top kind and the bottom faceHeight (default 1) cell(s) of each vertical run get the wall-side kind (derived as top + 8 kinds = +384 ids unless side is given; a run continuing off the map's bottom edge gets no face); or null = leave the cell untouched. Tiles may be ids or catalog names (exact name, else a unique substring — unknown/ambiguous names are an error). Row lengths, unknown glyphs, names and fit are all validated before anything is written. With clearUpperLayers (default true) each painted cell zeroes the tile layers (0-3) above its lowest specified layer that it does not specify, so stale objects vanish ([] erases the cell). Autotiling is recomputed once per layer, as in paint_tiles. Returns cells painted per layer, cleared count, wall faces made, and a passability overview of the rectangle, judged like the engine's canPass (a step needs the source to allow leaving and the target to allow entry): rows with # = impassable — a cell with no walkable direction (face, water, solid object) or part of a region whose own edge flags refuse entry from the walkable cells around it (an A4 wall-top mass, a stair-less plateau) — and . = walkable ground, plus the impassable [x, y] cells. Stamp multi-tile B/C objects afterwards with place_object.

Paint specific tiles onto a map, with automatic autotiling. Each cell is set to its tile id; if that id is an autotile (A1-A4, e.g. a catalog 'kind' base from find_tile), its shape and its neighbours' shapes are recomputed from same-kind adjacency so borders/corners line up. Flat tiles are painted as-is. Defaults to the lower ground layer (0). Higher-level than set_map_tile, which is a single raw tile with no autotiling.

Place a multi-tile B/C object (a house, tree, fountain, …) on a map and report its passability. tiles is the object's block of flat tile ids as rows (top to bottom), each row left to right; a 0 leaves that cell untouched so L-shaped/irregular objects work. Stamped onto the upper tile layer (2) by default so it draws over the ground. Unlike paint_tiles this does NOT autotile (objects are flat sheet tiles) — instead it uses the tileset flags to warn when a footprint cell sits on impassable terrain or overwrites an existing tile, and returns the resulting per-cell passability plus the collision cells the object turns into a solid obstacle. Warn-by-default: never refuses a placement. Get tile ids from find_tile/get_tile_catalog.

Screenshot a map as the game actually draws it: boots the project headless, starts a new game on the map, and saves a PNG. Validators prove structure, not looks — use this to catch wrong wall/autotile kinds, void (unbased transparent tiles), odd sprites or missing images. Default renders the WHOLE map (canvas resized to width×height×48px, player hidden, autorun/parallel events frozen, map-name banner off); pass x+y for a normal 816×624 game-screen view centred on that tile. Returns the PNG path plus problems — console errors, page errors and HTTP 404s (missing assets — a missing image is drawn blank instead of stopping the engine on its load-error retry screen). Read-only. Needs the optional dependency playwright-core and a Chromium from the Playwright cache (npx playwright install chromium-headless-shell) or the RPGMAKER_MCP_CHROMIUM env var.

Clear a whole database table (actor, class, skill, item, weapon, armor, enemy, troop, state, or common_event) except the ids in keep — e.g. reset_table('skill', { keep: [1, 2] }) wipes the RTP skills but keeps Attack/Guard, the usual first step before authoring your own database with batch_create. Kept records stay at their own id; the rest become null and trailing empty slots are trimmed (the table is [null] when nothing is kept). Like delete_record it REFUSES, writing nothing, when the removal would leave references dangling (map events giving removed items, troops of removed enemies, …) unless force: true; use dryRun: true first to see what disappears and what would break. Returns { type, kept[], removedCount, removed[], referenceCount, references[], coverage } (lists are capped at 100).

Resize a map to new width/height, safely repadding every z-layer of its tile data (existing tiles kept where the old and new grids overlap; new cells blank; shrinking crops). This is the ONLY safe way to change a map's dimensions — update_map refuses a width/height change because it would not resize the tile array. Warns about any event left outside the new bounds.

Play the game headless from a script of steps and report what happened — the runtime check validators cannot do (does the door transfer, does the NPC say the right thing, does the choice branch, is there an invisible wall). One browser session runs the whole script; each step reports its outcome and the run stops at the first failing step. Steps: load {mapId,x,y,direction?,party?,level?,gold?,switches?,variables?,selfSwitches?,items?,equip?,encounters?} starts a fresh game there (random encounters off unless encounters:true); startEvent {eventId} starts a map event as if triggered and lets it run until it shows text or goes idle (waiting out any transfer — reported as transferredTo); advanceText {maxMs?} presses OK until the event is idle, STOPPING at an open choice list/battle — returns the map message lines shown and any open choices (text shown during a battle comes back separately as battleLines); choose {index} picks a 0-based choice; walk {direction, steps?} walks tile by tile, reporting where it ended (to); if a tile refused entry, stoppedAt (the player's tile) and blockedTile (the refused one); when a step fires a touch event (a door) it stops, waits out the transfer and reports transferredTo {mapId,x,y}, plus eventRunning/messageOpen if the event is still going; press {button, times?}; wait {ms}; autoBattle {troopId?, canEscape?, canLose?, maxMs? (default 60000)} fights (a started or new battle) on auto AI until it ends, returning the battle's message lines (troop events, victory text). Battles are fast-forwarded (20 engine frames per drawn frame: same logic, same odds, a 10-turn boss fight in seconds) unless the run sets realtime: true; screenshot {name?} saves a PNG; eval {script} evaluates a JS expression in the game page and returns its value (e.g. "$gameSwitches.value(3)"). Reported text reads as the message window shows it: \V[n]/\N[n]/\P[n]/\G expanded, control codes (\C[n], \I[n], ., | …) removed. Every step result carries ok; the response ends with finalState (scene, map, position, gold, party) and problems (console/page errors, HTTP 404s). Max 200 steps. Read-only: never writes the project. A run can take MINUTES (booting ~5-10 s, long cutscenes, realtime battles): clients should raise their request timeout, or send a progressToken with resetTimeoutOnProgress — the tool then sends a progress notification per step and every 5 s during long ones. Split long scripts into several runs if your client can do neither. Needs the optional dependency playwright-core and a Chromium from the Playwright cache (npx playwright install chromium-headless-shell) or the RPGMAKER_MCP_CHROMIUM env var.

Discover the plugin commands this project actually has, by parsing the @command/@arg annotations in js/plugins/*.js and the enabled/disabled state in js/plugins.js. Use it to find out what create_plugin_command can call and with which args — it reports every command's key, label, description and args (name/type/default), plus whether the plugin is enabled in the editor's Plugin Manager (a disabled plugin's commands never run). create_plugin_command validates against this scan automatically, so you don't need to call this first; it's for discovery. Pass pluginName to narrow to one plugin, or enabledOnly:true to skip plugins that are installed but switched off. Read-only. NOTE: MZ has no 'required argument' annotation, so scanned args are checked for unknown names only, never for missing ones.

Search actors by name or nickname

Search enemies by name (case-insensitive)

Search items by name or description

Search events on a map by name

Search skills by name or description

Search troops by name (case-insensitive)

Replace one of a class's 8 parameter growth curves. paramId is 0-7 ([maxHP,maxMP,atk,def,mat,mdf,agi,luk]); values must match the existing curve length (same max level).

Set the currency unit shown next to gold amounts (e.g. "G", "Gold").

Set a map's random-encounter list (replaces it wholesale) and optionally its encounterStep (average steps between encounters). Each encounter is { troopId, weight?, regionSet? }: weight biases the random pick (default 5), regionSet restricts it to those map region ids (empty/omitted = anywhere). Every troopId is validated against Troops.json — a non-existent troop throws. Prefer this over update_map for encounters (it validates and hides the on-disk shape).

Update an existing event page's graphic and behavior in one call, without rebuilding the whole page or touching its command list: sprite (characterName/characterIndex/direction/pattern or a tileId), trigger, priority, movement (type/speed/frequency/route), and the through/walkAnime/stepAnime/directionFix flags. Graphic fields merge onto the current image; warns (never blocks) on an unknown characterName. Refuses the write if the change would leave the event unreachable (an action-button page with priority below on an impassable tile) — pass force: true to override.

Set a single raw tile ID at (x, y) on a given z-layer (0-5). Note: tile IDs are raw engine integers; this is a low-level primitive without autotile/passability awareness.

Insert a forced "Set Movement Route" (event command 205, plus the 505 continuation rows the editor expects) into an event page’s command list, moving a character as part of that page. characterId: -1 player, 0 this event, N event id. Pass a moveRoute from create_move_route. A structurally invalid route or page refuses the write (nothing is saved) — pass force: true to override.

Set the starting party (the actor ids the game begins with, in order). Every id must reference an existing actor.

Point the server at a different RPG Maker MZ project directory for the rest of the session (overrides RPGMAKER_PROJECT_PATH until the server restarts). The directory must contain game.rmmzproject and data/System.json.

Set a switch name. Grows the project's switch list if the id is past the end (padded to the editor's 20-slot block), so an id from next_free_id can always be labelled. Naming a switch as soon as you claim it is what makes it visible to the next session — see list_allocated_ids.

Set one vocabulary term. For category 'basic'/'commands'/'params' the key is a numeric index (as a string); for 'messages' it's a message key (e.g. 'actorDamage'). Returns the updated terms.

Edit a tile's passability/terrain/behaviour flags in a tileset's flags[] array (the write side of get_tile_flags). Only the fields you pass change — everything else on the tile is preserved (a non-destructive merge onto the current flag word). passage is walkability (down/left/right/up, true = a character can walk off that way). Also settable: star ([*] overlay), ladder, bush, counter, damage (damage floor), and terrainTag (0–7). For an autotile id (A1–A4) the change is applied to all 48 shape slots of its kind by default (set applyToAutotileKind:false to touch only the exact id) so painting any border shape keeps the same passability. Writes data/Tilesets.json through the commit choke point (dry-run/diff). Returns { tilesetId, tileId, appliedTileCount, before, after }.

Rename one entry in a System.json type-name array (elements/skillTypes/weaponTypes/armorTypes/equipTypes). Index 0 is the conventional empty slot. Returns the updated array.

Set a variable name. Grows the project's variable list if the id is past the end (padded to the editor's 20-slot block), so an id from next_free_id can always be labelled. Naming a variable as soon as you claim it is what makes it visible to the next session — see list_allocated_ids.

Update an actor's properties

Update an armor's properties (shallow merge into the existing record)

Update a class's properties (shallow merge into the existing record). Use for name, expParams, traits, or to replace the whole learnings/params arrays; for targeted edits prefer add_class_learning / set_class_param_curve. Warns when a learned skill's stypeId has no Add Skill Type trait ({ code: 41 }).

Update a common event's properties (shallow merge into the existing record). Use for name, trigger, switchId, or to replace the whole command list. A structurally invalid command list refuses the write (nothing is saved) — pass force: true to override.

Update an enemy's properties (shallow merge into the existing record). Returns { enemy, warnings? } — a battlerName not found in img/enemies (img/sv_enemies for a side-view project) is flagged warn-by-default.

Update the game title

Update an item's properties (shallow merge into the existing record)

Update a map's top-level properties (name, display name, bgm, encounters, etc.). Does not repaint tiles. Cannot change width/height (that would desync the tile data array) — use resize_map for that. The echo omits the tile data array and the events map (neither is touched here) and reports dataTileCount/eventCount instead; pass verbose: true or use get_map for the full record.

Update a map event's properties. Refuses the write (nothing is saved) if the resulting event is structurally invalid — pass force: true to override.

Edit the map tree (MapInfos.json) only — reparent, reorder, rename, or expand/collapse maps without touching their tiles or events. Takes a batch of per-map updates; every referenced map (and any non-zero parentId) must exist, and the resulting tree must stay acyclic.

Update a skill's properties

Update the game starting position

Update a state's properties (shallow merge into the existing record)

Update the title screen: background layers (title1Name/title2Name, basenames from list_assets("titles1"/"titles2")), the BGM that plays while it is shown, and/or whether the game title text is drawn over the art. Only the provided fields are changed. Warns (never blocks) when an image/audio name is not a known asset. Returns the updated title screen settings.

Update a troop's properties (shallow merge). If members is provided, each enemyId is validated to exist. A structurally invalid battle-event page refuses the write (nothing is saved) — pass force: true to override.

Update a weapon's properties (shallow merge into the existing record)

Audit asset-filename integrity across the whole project (read-only, warn-by-default): every image/audio name field — actor characterName/faceName/battlerName, enemy battlerName, tileset sheets, map bgm/bgs/parallax/battlebacks, event page graphics, event Play BGM/BGS/ME/SE / Show Picture / Show Text face / Change Actor Images, and system titles/battlebacks/default audio/vehicle graphics — is checked against the files present under img/ and audio/. Catches a wrong filename (e.g. a battlerName with no matching img/enemies/*.png) before it becomes a runtime "Failed to load" error. An asset kind whose directory is empty/missing is skipped (not flagged). Complements validate_references (which checks id integrity). Returns { ok, warnings[] }.

Validate a single event's command lists against the known RPG Maker MZ command table, plus its placement against the tile it sits on: an action-button page with priority below on an impassable tile (can never trigger) and an invisible wall (a graphic-less, priority-same, non-through page on a walkable tile — the player bumps into nothing; an action-button page over a drawn B–E object is exempt, as the solid-landmark idiom). Read-only: reports warnings without changing anything.

Validate the event command lists of every map in the project, plus each event's placement (action-button-below on an impassable tile; graphic-less priority-same invisible walls on walkable tiles, except action-button pages over a drawn B–E object). Read-only: returns aggregated, map-tagged warnings for auditing before or after a batch of edits.

Audit cross-file reference integrity across the whole project (read-only, warn-by-default): Transfer Player targets and starting position point at existing maps; starting party, actor classes, class/enemy skills, troop members, enemy drops, and skill/item effects (states, learned skills, common events, animations) all resolve; event commands that name a record (Change Items/Weapons/Armors, Change Party Member, Battle Processing, Shop Processing, Change State/Skill, Common Event) and map random encounters point at existing rows; and the map tree has no dangling or cyclic parentId. Complements validate_project (which checks command shape). Returns { ok, warnings[] }.