Select the RPG Maker MV project folder to work on (the folder containing Game.rpgproject and data/). Must be called before other tools unless the server was started with --project. Discards any open changeset (its staged edits are lost).
Parameterspathrequired
get_project_info
Get project info
Summary of the current project: game title, database record counts, map count, and plugin count.
Takes no parameters.
list_records
List database records
List all records of a database type as {id, name} summaries. Use get_record for full data.
Parameterstyperequired
get_record
Get database record
Get the full JSON of one database record by id.
Parametersidrequiredtyperequired
update_record
Update database record
Update a database record. By default the given fields are shallow-merged into the existing record; set merge=false to replace it entirely. The record's id always stays fixed to match its array position.
Parametersidrequireddatarequiredtyperequiredmerge
create_record
Create database record
Append a new record to a database. The new record's fields are copied from `data`; missing fields should be filled in to match the shape of existing records (fetch one with get_record as a template first). Returns the new id.
Parametersdatarequiredtyperequired
get_system
Get System.json
Read System.json (game title, starting party/position, terms, sounds, switches, variables, etc.). Optionally return only one top-level key.
Parameterskey
set_switch_name
Name a switch
Set the editor name of a game switch in System.json (e.g. switch 5 = 'Opened Chest'). The switches array grows if the id is beyond its current size.
Parametersidrequirednamerequired
set_variable_name
Name a variable
Set the editor name of a game variable in System.json (e.g. variable 3 = 'Quest Progress'). The variables array grows if the id is beyond its current size.
Parametersidrequirednamerequired
update_system
Update System.json
Shallow-merge the given top-level fields into System.json (e.g. gameTitle, startMapId, startX, startY, switches, variables).
Parametersdatarequired
List all maps from MapInfos.json as {id, name, parentId, order}.
Takes no parameters.
Read a map's properties (size, tileset, music, encounters, notes) and event summaries. Tile data is omitted unless includeTileData=true (it is large: width*height*6 integers).
ParametersmapIdrequiredincludeTileData
update_map
Update map properties
Shallow-merge fields into a map's JSON (e.g. displayName, note, bgm, encounterList). Refuses to touch 'data' or 'events' — use the event tools for events and paint_tiles for tiles. To switch tilesets prefer set_map_tileset.
ParametersdatarequiredmapIdrequired
Get the full JSON of one event on a map, including all pages and command lists.
ParametersmapIdrequiredeventIdrequired
update_event
Update map event
Replace an event on a map with the given event JSON (same shape as returned by get_event). The event's id and its array position stay in sync automatically. See event_command_reference for command codes.
ParameterseventrequiredmapIdrequiredeventIdrequired
create_event
Create map event
Add a new event to a map at (x, y). If no pages are given, a single empty page (action-button trigger, no commands) is created. Returns the new event id.
ParametersxrequiredyrequirednamerequirednotemapIdrequiredpages
delete_event
Delete map event
Delete an event from a map. The slot is set to null so other event ids are unaffected (matches editor behavior).
ParametersmapIdrequiredeventIdrequired
add_event_command
Add event commands
Insert commands into an event page's command list without resending the whole event. Commands are inserted before the page's terminating {code: 0} entry (or at `index` if given). Multi-line constructs work naturally, e.g. Show Text is one code-101 command followed by code-401 commands. See event_command_reference for codes.
ParametersindexmapIdrequiredeventIdrequiredcommandsrequiredpageIndex
Add spoken dialogue to an event page in one call — builds the Show Text (101) and text-line (401) commands automatically, splitting into multiple message boxes every 4 lines. Inserted before the page's end, like add_event_command.
ParameterslinesrequiredmapIdrequiredeventIdrequiredfaceNamepositionfaceIndexpageIndexbackground
Create a new map: writes MapXXX.json and registers it in MapInfos.json. The map starts empty unless `fill` is given (a ground tile for layer 0); afterwards use paint_tiles to paint it, get_tileset_info to choose tiles and add events with the event tools. Returns the new map id.
ParametersfillnamerequiredwidthheightparentIdtilesetId
event_command_reference
Event command reference
Reference table of RPG Maker MV event command codes and their parameters. Consult this before writing or editing event command lists.
Takes no parameters.
get_tileset_info
Get tileset info
Describe a tileset so you can choose tiles to paint: which image is assigned to each sheet (A1-A5, B-E), the tile id ranges, and for autotile sheets every kind with its type, position on the sheet image and passability. Without `sheet` you get an overview; pass `sheet` for the detail of one sheet (for A5/B-E that includes a passability grid laid out like the image: o passable, x blocked, * drawn above characters, p partly blocked). Use get_tileset_image to see what the tiles look like. `tileIds` decodes passability and terrain flags for specific tile ids.
ParameterssheettileIdstilesetIdrequired
get_tileset_image
Get tileset sheet image
Return one tileset sheet (A1-A5, B-E) as an image so you can see which tile looks like what, together with its grid layout (48px tiles). Use get_tileset_info for the matching tile ids and kinds.
ParameterssheetrequiredtilesetIdrequired
set_map_tileset
Set map tileset
Switch a map to another tileset (which sheets/tile images it uses). Existing tile ids are kept as they are, so they will show the new tileset's graphics - repaint with paint_tiles if the layouts differ.
ParametersmapIdrequiredtilesetIdrequired
paint_tiles
Paint map tiles
Paint tiles onto a map. Takes a list of operations applied in order: `cells` (individual positions), `rect` (filled or hollow rectangle) and `fill` (flood fill from a cell). Tiles are chosen as {sheet:'A2', kind:N} (autotile sheets A1-A4), {sheet:'B', index:N} (A5/B-E) or a raw tile id; 0 erases. Autotile edge, corner and wall shapes are calculated automatically, including re-shaping neighbours, just like painting in the editor. Layers: 0-1 ground, 2-3 upper tiles, 4 shadows, 5 regions. Typical map: fill layer 0 with a ground kind from A2, then place water/walls/objects on top. Use get_tileset_info / get_tileset_image to pick tiles and render_map to check the result.
ParametersmapIdrequiredoperationsrequired
render_map
Render map as text
Show a map's tiles as text so you can check what you painted. mode 'symbols' (default) draws one character per cell using the topmost tile of layers 0-3 (or only `layer`) with a legend naming each symbol; mode 'ids' prints raw tile ids of one layer. Use x/y/width/height to look at a region (default: up to 100x60 from the top-left).
ParametersxymodelayermapIdrequiredwidthheight
render_map_image
Render map as image
Render a map to a PNG image so you can SEE what it looks like: all tile layers with correct autotile shapes, shadows and tiles that draw above characters, optionally the events' character sprites, coloured event markers with their ids, region ids, a tile grid and a passability overlay (red = blocked in at least one direction). This is the visual counterpart of render_map (text) - use it after paint_tiles / create_event / connect_maps to check your work. Marker colours: blue = event with a Transfer Player command (door/exit), orange = shows text, magenta = autorun/parallel, green = anything else. Needs the tileset images in img/tilesets (sheets without an image are drawn as flat colours and listed). Large maps are shrunk to fit ~1600px; pass x/y/width/height to zoom into a region and raise tileSize for detail.
ParametersxymapIdrequiredwidthheightshowGridtileSizeshowEventsshowRegionsshowPassability
render_diff
Render map changes
Show what changed on a map compared with an earlier version: a text summary (changed tile cells, added/removed/moved/edited events) plus a PNG of the CURRENT map with changed cells outlined yellow and added or moved events outlined green. By default it compares with the most recent backup session that contains the map (the state before this session's first edit); pass against.session to pick a session folder from list_backups, or against.changeset to compare with the pre-image of a committed changeset. Use it after bulk painting or generation to review exactly what you touched. If the map has no earlier version this session, it says so.
ParametersmapIdrequiredagainsttileSize
List all plugins registered in js/plugins.js with status and parameters.
Takes no parameters.
configure_plugin
Configure plugin
Enable/disable a registered plugin and/or merge new values into its parameters (parameter values are always strings in RPG Maker MV).
Parametersnamerequiredstatusparameters
add_plugin
Register plugin
Register an existing js/plugins/<name>.js file in the plugin list. Fails if the file does not exist (use create_plugin to make a new one).
Parametersnamerequiredstatusparametersdescription
remove_plugin
Unregister plugin
Remove a plugin from js/plugins.js. The plugin's .js file is NOT deleted.
Parametersnamerequired
create_plugin
Create plugin
Create a new plugin file in js/plugins/ and register it. If no code is given, a standard MV plugin scaffold (with @plugindesc header) is written. Fails if the file already exists.
Parameterscodenamerequiredstatusdescription
read_plugin
Read plugin source
Read the JavaScript source of js/plugins/<name>.js.
Parametersnamerequired
write_plugin
Write plugin source
Overwrite the JavaScript source of an existing js/plugins/<name>.js.
Parameterscoderequirednamerequired
playtest_start
Start playtest
Start a playtest of the current project. mode 'nwjs' launches the game with an NW.js runtime (pass runtimePath, e.g. the Game.exe inside the RPG Maker MV install's nwjs-win folder) and captures its stdout/stderr. mode 'browser' serves the project over a local HTTP server and returns a URL to open. Any previous playtest is stopped first.
ParametersmodeportruntimePath
playtest_status
Playtest status
Whether a playtest is running, in which mode, and its URL/PID.
Takes no parameters.
Recent stdout/stderr lines from an NW.js playtest process.
Parameterstail
playtest_stop
Stop playtest
Stop the running playtest process and/or HTTP server.
Takes no parameters.
create_damage_skill
Create damage skill
Create a complete damaging skill in one call. The formula uses MV damage syntax where `a` is the user and `b` the target, e.g. 'a.mat * 4 - b.mdf * 2' or 'a.atk * 2 - b.def'. Returns the new skill id.
ParametersnamerequirednotescopempCosttpCosttpGainformularequiredhitTypestypeIdcriticaloccasionvariance+5 more
create_healing_skill
Create healing skill
Create a complete healing skill in one call. The formula uses MV damage syntax (`a` = user), e.g. 'a.mat * 2 + 200'. Heals HP or MP; optionally also removes states (e.g. a cure spell).
ParametersnamerequirednotescopempCosttpCostformularequiredstypeIdoccasionvarianceiconIndexanimationIddescription+2 more
create_buff_skill
Create buff/debuff skill
Create a skill that applies parameter buffs and/or debuffs. Parameter ids: 0 Max HP, 1 Max MP, 2 Attack, 3 Defense, 4 M.Attack, 5 M.Defense, 6 Agility, 7 Luck. If only debuffs are given the scope defaults to one enemy, otherwise one ally.
ParametersnamerequirednotebuffsscopempCosttpCostdebuffsstypeIdoccasioniconIndexanimationIddescription
create_state_skill
Create state skill
Create a skill that adds or removes states (poison, sleep, etc.) on the target, each with its own success chance. State ids come from the States database (list_records type=states).
ParametersnamerequirednotescopeactionmpCoststatesrequiredtpCoststypeIdoccasioniconIndexanimationIddescription
search_records
Search database records
Case-insensitive substring search across database records (name, nickname, description, note, profile, messages). Searches one type, or all types when type is omitted. Returns {type, id, name, matchedIn} summaries.
Parameterstypelimitqueryrequired
search_map_events
Search map events
Case-insensitive substring search across events on one map or every map. Matches event names and notes; with searchCommands=true it also searches inside event command parameters (message text, script lines, plugin commands). Returns {mapId, mapName, eventId, name, x, y, matchedIn}.
ParameterslimitmapIdqueryrequiredsearchCommands
List automatic backup sessions in <project>/.mcp-backups. A file is snapshotted there the first time each server session modifies it, so every session can be rolled back with restore_backup.
Takes no parameters.
restore_backup
Restore backup
Restore project files from a backup session (see list_backups). Restores one file (project-relative path like 'data/Actors.json') or, with no file given, every file in the session. The current state is itself backed up first, so a restore can be undone. Refused while a changeset is open (commit or discard it first). The RPG Maker editor must stay closed while files are restored.
Parametersfilesession
editor_status
Editor status
Check whether the RPG Maker MV editor appears to be running and which files this server wrote have since been changed by something else (usually the editor saving over them). Report only: it never blocks or undoes any edit.
Takes no parameters.
validate_project
Validate project
Integrity check of the whole project: parses every database file, verifies MapInfos entries have map files (and finds orphaned map files), checks registered plugins have source files, and scans event commands for references to missing common events or transfer destinations. Returns errors (broken) and warnings (suspicious).
Takes no parameters.
begin_changeset
Begin changeset
Start a transactional batch of edits. While a changeset is open, every edit tool stages its result in memory: nothing is written to disk until commit_changeset, and all reads (get_map, get_record, list_plugins, ...) reflect the staged edits. Commit writes every staged file in one step (all or nothing) and can be rolled back later with undo_changeset; discard_changeset drops the staged edits. Only one changeset can be open at a time; restore_backup is refused while one is open and set_project discards it. Playtests read from disk, so they only see committed edits. The RPG Maker editor must stay closed while the server edits the project.
Parameterslabelrequired
commit_changeset
Commit changeset
Write every file staged by the open changeset to disk as one unit and return a per-file summary (created/modified, event/tile/record counts). Staged .json files are validated first: if any is invalid, nothing is written and the changeset stays open. Pre-images are journaled under .mcp-backups/changesets/<id>/ so undo_changeset can roll the commit back; a commit interrupted by a crash is rolled back automatically the next time the project is opened (the files found on disk are backed up first). Other edits are refused while the commit runs. If a commit fails and its files cannot all be restored, the changeset is closed and every edit is refused until undo_changeset has restored them. Until this is called, nothing of the changeset is on disk and reads reflect the staged edits. The RPG Maker editor must stay closed while the server edits the project.
Takes no parameters.
discard_changeset
Discard changeset
Drop every edit staged by the open changeset. Nothing on disk changes (nothing of the changeset was on disk yet), and reads go back to the files on disk. The RPG Maker editor must stay closed while the server edits the project.
Takes no parameters.
undo_changeset
Undo last changeset
Roll back the most recently committed changeset from its journal: modified files are restored byte-for-byte, files it created are deleted. Call repeatedly to step back through earlier commits. Edits made to those files after the commit are overwritten too. Refused while a changeset is open (while one is open, reads reflect its staged edits and nothing is on disk until commit). The RPG Maker editor must stay closed while the server edits the project.
Takes no parameters.
connect_maps
Connect two maps
Link two maps with Transfer Player events in both directions in one call. A door event is placed on each map; stepping on (or pressing OK at) the door on map A moves the player to map B's spawn tile and vice versa. Give each side its `door` tile; add `spawn` when the player should appear next to the door instead of on it (always do this for doors drawn into walls). Both maps are validated before anything is written, and a door is refused if another event already stands on that tile (allowOverlap overrides). Use twoWay=false for a one-way link (map A's door only). Check the result with render_map_image (doors show as blue markers) and list_map_connections.
ParametersarequiredbrequiredfadesoundtwoWaytriggerdoorNameallowOverlap
list_map_connections
List map connections
Scan every map's events for Transfer Player commands and show how the maps are linked: each door with its destination, one-way links without a way back, transfers to maps that do not exist, and maps that cannot be reached from the game's start map. Transfers whose target is chosen by variables are listed as dynamic and cannot be followed, so 'unreachable' is a hint, not proof.
ParametersmapId
bulk_update_records
Bulk update records
Change one or more fields on many database records at once, with a diff. Example - all weapons +10% attack: {type: 'weapons', changes: [{field: 'params.atk', op: 'percent', value: 10}]}. Select records with `ids` and/or `where` conditions (all must match); with neither, every record is selected. Fields are paths such as 'price', 'params.atk' (mhp/mmp/atk/def/mat/mdf/agi/luk), 'params[2]', 'damage.formula', 'traits[0].value'. Ops: set (any value), add, multiply, percent (+value%) - numeric ops round to whole numbers for integer fields (round: auto), with optional min/max clamps. DRY RUN BY DEFAULT: nothing is written until you pass dryRun=false, so show the diff to the user first. If any record fails, nothing is written.
ParametersidstyperequiredwheredryRunchangesrequiredmaxPreview
generate_param_curve
Generate class parameter curve
Generate stat curves over levels and (optionally) write them into a class. Each curve goes from `start` at minLevel to `end` at maxLevel with a shape: linear, ease-in (slow start), ease-out (fast start), ease-in-out, exponential (constant growth factor) or logistic (S-curve). Without classId this is a pure preview of the numbers. With classId the class's params table is rewritten for minLevel..maxLevel (other levels are untouched) - dry run by default, pass dryRun=false to apply. Follow up with balance_report to see how the new curve plays against enemies.
ParameterscurvesrequireddryRunclassIdmaxLevelminLevel
generate_enemy_scaling
Generate enemy scaling
Spread enemy stats along a curve for smooth difficulty progression. Give the enemies ordered from weakest to strongest; the first gets each curve's `start`, the last its `end`, the rest are interpolated with the chosen shape. Curves can target any parameter (mhp, mmp, atk, def, mat, mdf, agi, luk) plus `exp` and `gold`. Dry run by default - shows before and after per enemy; pass dryRun=false to write.
ParameterscurvesrequireddryRunenemyIdsrequired
balance_report
Balance report
Measure the game's balance from its data: (1) class stat curves at chosen levels, (2) the attack skill's damage by level against a reference enemy, (3) a matrix of attackers vs enemies (average damage and hits to kill) and (4) enemy threat vs the same characters (damage of the enemy's best attack and hits to kill them). Ends with warnings: unevaluable damage formulas, curves that go down, enemies killed in one hit or immune, enemies that one-shot a character. Attackers default to the starting party. Numbers are averages with no variance, crits or misses and ignore states, items and elements beyond what the skill/traits specify - use simulate_battle for a full fight.
ParameterslevelsclassIdsenemyIdsattackersreferenceEnemyId
simulate_battle
Simulate a battle
Run many simulated battles of a troop against a party and report win rate, turns, how much HP the party keeps and who does the damage or dies. Uses the project's real stats (class curves, equipment, traits), damage formulas, variance, critical hits, hit/evasion rates, agility turn order, target weighting (TGR) and enemy action ratings. Party members use `skillIds` in order (first affordable one, healing only when an ally is below 60% HP), falling back to the Attack skill. Not modelled: states, buffs, items, guarding, TP, enemy conditions on states/switches (treated as false). Seeded, so results are reproducible. Default party: the starting party at their initial level.
ParametersrunsseedlevelpartytroopIdrequiredmaxTurns
export_texts
Export all game texts
Export every translatable text of the project to a CSV or JSON file inside the project (default localization/texts.csv) with columns key, context, original, translation. Covers database names/descriptions/messages, System terms and type names, the game title, map display names, and event text (dialogue boxes as one row each with lines joined by newlines, choices, scrolling text, actor name/nickname/profile commands) in maps, common events and troop battle events. If the file already exists its translations are carried over by key, so re-exporting after changes never loses work. Fill in the translation column (leave empty to keep the original), then use import_texts. See the rpgmaker-localization skill for rules about control codes and message length.
Parametersfilescopeformat
import_texts
Import translated texts
Apply the translation column of a file written by export_texts back into the project's data. DRY RUN BY DEFAULT: reports what would change and nothing is written until dryRun=false. Rows with an empty translation are skipped. A row whose `original` no longer matches the project text (the text changed after export) is skipped unless force=true. Dialogue translations longer than 4 lines are split into several message boxes automatically; choices are kept in sync. Control codes (\C[n], \V[n], \N[n] ...) are compared with the original and mismatches are reported as warnings.
ParametersfilerequiredforcedryRun
audit_assets
Audit project assets
Checks that every image and audio file the project references exists on disk, and optionally lists files nothing references. Scanned references: Actors (characterName, faceName, battlerName); Enemies battlerName (img/enemies, or img/sv_enemies when System optSideView is on); Tilesets tilesetNames; Maps (parallaxName, bgm, bgs, battleback1Name, battleback2Name, event page images); event commands 101 (face), 132/133/139/140 (battle BGM, victory ME, defeat ME, vehicle BGM), 231 (picture), 241/245/249/250 (BGM/BGS/ME/SE), 283 (battle back), 284 (parallax), 322 (actor graphics) and 323 (vehicle image) in map events, common events and troops; System (title1Name, title2Name, battleback1Name, battleback2Name, titleBgm, battleBgm, victoryMe, defeatMe, gameoverMe, boat/ship/airship bgm, sounds). Anything else is listed under notScanned, so 'unused' can include files used only by plugins or scripts. Audio is satisfied by either an .ogg or an .m4a file. caseMismatch means the file exists only with different letter case: it works on Windows but breaks on Linux, macOS and web deployments. Each list is capped at 200 entries; truncated gives the omitted counts.
ParametersincludeUnused
lint_events
Lint event command lists
Statically checks event command lists in map events, common events and troop pages. Rules: unterminated-list and block-structure (missing code 0 terminator, unclosed or mismatched choices/branches/loops, indent jumps; error), unreachable-command (a command right after Exit Event Processing at the same indent; warning), long-message-line (a Show Text line too long for the window; warning), transfer-missing-map and transfer-out-of-bounds (direct Transfer Player to a map not in MapInfos or outside its size; error), missing-common-event (Common Event call to an id that does not exist; error), unnamed-switch and unnamed-variable (Control Switches/Variables on ids with no name in System.json; info). Variable-designated transfers are not checked. long-message-line removes message control codes (\C[n], \V[n], \N[n], \P[n], \I[n], \{ \} \. \| \! \> \< \^) and compares the remaining character count with maxLineChars; the default of 50 is only an approximation, since real fit depends on the font, face graphic and window width. Findings carry location {kind, mapId, eventId, page, index}; page and index are 0-based positions in the event's pages and command list (common events use page 0, troops use the troop id as eventId). minSeverity defaults to warning, so info findings appear only when requested. scope defaults to all; mapId limits the map part to one map. Maps whose file cannot be read are listed in skippedMaps. Results are sorted by severity then location and capped at 300 findings; counts cover all findings and truncated is the number cut.
ParametersmapIdscopeminSeveritymaxLineChars
simulate_event
Simulate an event
Dry-runs one map event page against a hypothetical game state and returns what it would do, without touching the project or running the game. Supported commands: Show Text (101/401), Show Choices (102/402/403/404), Conditional Branch (111/411/412: switch, variable, self switch, gold, item), Loop/Break (112/113/413), Exit Event Processing (115), Common Event (117, nested up to 8 deep), comments, Control Switches (121), Control Variables (122: constant, variable and random operands), Control Self Switch (123), Change Gold (125), Change Items (126), Transfer Player (201, ends the run) and Plugin Command (356, listed in changes as 'plugin: ...'). Battle Processing (301) is not fought: the branch picked by battleResult runs (win, escape or lose; default win) and the others are skipped; a missing branch adds 'battle: no <result> branch' to changes. A Battle Processing without branches (what the editor writes when neither Can Escape nor Continue when Loss is on) is a single command: nothing is skipped and the next command runs. Label (118) and Jump to Label (119) work: a jump goes to the first label of that name in the current command list and counts as a step, so a label loop ends 'stepLimit'; a missing label is listed in unsupported and the run continues. Presentation commands (Set Movement Route 205, animation and balloon 212/213, screen fades, tint, flash and shake 221-225, wait 230, show/move/erase picture 231/232/235, weather 236, play/fade audio 241/242/245/246/249/250/251, 505 route rows) are ignored and only counted in cosmetic, not listed in unsupported; the one exception is the switch ON/OFF steps of a Set Movement Route, which do change the simulated switches (changes: 'switch N → ON (move route)'; only the first 1000 route entries are scanned, each costing one step, and a longer route adds an unsupported note). A battleResult of escape or lose on a battle that cannot be escaped or lost still runs the branch but adds a note to changes. Everything else (script 3
ParametersgoldpageseeditemsmapIdrequiredchoiceseventIdrequiredswitchesvariablesbattleResultselfSwitchesunknownCondition
Lists everywhere one switch, variable, item, weapon, armor, skill, state, actor, class, enemy, troop, common event or map is read, written or used, and warns about dead ends. Use it before renaming, deleting or reusing an id. reads: page conditions, Conditional Branch (111), variable operands and \V[n] text escapes; writes: Control Switches/Variables (121/122), Change Items/Weapons/Armors (126-128), Change Party Member (129), Change State/Skill (313/318), set-switch route steps; uses: Transfer Player (201), Common Event (117), Battle Processing (301), shops (302/605), actor commands, enemy drops and actions, class learnings, actor equipment, troop members, item/skill effects, map encounter lists, System startMapId and partyMembers. It reads staged changeset data. Each location is a string: 'Map003 event 5 page 1 command index 12', 'CommonEvent 4 command index 7', 'Troop 2 page 1 command index 3', 'Enemies #4 dropItems', 'System startMapId', 'Map003 encounterList'. Map ids, event ids, common event ids and troop ids are the real ids and pages are 1-based like the editor shows them, but 'command index N' is the 0-based position in the command list (the index lint_events reports). A location without a command index is a page condition. counts are the true totals; each list is cut at limit entries and truncated gives the omitted counts. warnings cover: a switch or variable that is read but never set, or set but never read; a common event never called (autorun and parallel common events are exempt); a map nothing transfers to; and an id with no name or record (unknown id, not an error). Script commands (355), plugin commands (356), variable-designated transfers and battles, notetags and plugin parameters are not understood, so every 'never ...' warning carries a note when the project has script or plugin commands (or truncated range commands) that could act on the id. Only the 121/122 ids up to 1000 per command are indexed.
Parametersidrequiredkindrequiredlimit
check_references
Check references
Finds references that point at records which do not exist: a Battle Processing (301) on a missing troop, a shop item (302/605), Change Items/Weapons/Armors (126-128), Learn/Forget Skill (318), Change State (313), Change Party Member (129) and the other actor commands, Common Event calls (117), Transfer Player (201) or Set Vehicle Location (202) to a missing map, page conditions on a missing item or actor, enemy drops and actions, class learnings, actor class and equipment, troop members, item and skill effects, map encounter lists and System startMapId and partyMembers. It uses the same index as find_usages, so it checks exactly the references find_usages lists (staged changeset data included). A record exists when its database file (Items, Weapons, Armors, Skills, States, Actors, Classes, Enemies, Troops, CommonEvents) holds a non-null row whose id field is that id (not its array position, as in find_usages), or MapInfos.json lists the map. Id 0 means 'none' (an empty equipment slot, no drop) and is never reported. Switches and variables are not checked (plain numbers; lint_events reports unnamed ones). Run it before a release and after deleting or renaming records, and use find_usages on one reported id to see every place. Returns {summary, missing: [{kind, id, count, locations, severity: 'error'}], truncated, counts: {distinctMissing, references}, notes}. missing is grouped by kind and id, ordered by kind (item, weapon, armor, skill, state, actor, class, enemy, troop, commonEvent, map) then id; count is the number of references and locations lists at most 3 of them (same format as find_usages). missing is cut at limit groups and truncated is the number cut. A database file that is missing or unreadable is named in notes and its references are NOT reported as missing. notes also state what is not checked: references made by script commands, plugin commands, notetags, plugin parameters, damage formulas, trait codes and variable-designated transfers and battles (wit
Parameterslimit
analyze_progression
Analyze progression
Answers 'can the player get from the start map to X, and what can never happen?' for the whole project, without running the game.
Model (an over-approximation): starting at System startMapId, a page may run whenever its page conditions could hold, and when it runs ALL of its commands take effect. Switches only ever turn ON, items are never lost, and conditions inside event commands (branches, choices) are ignored. So 'unreachable' (maps, pages, goals) is a proof under the model, while 'reachable' only means 'not ruled out'.
It cannot see script commands (355), plugin commands (356), variable-designated transfers or battles, enabled plugins (parameters, notetags) or anything else a plugin does. Each of those, an unreadable map or an unreadable js/plugins.js lowers uncertainty.confidence to 'low'; only trust 'unreachable' and 'dead' results when confidence is 'high'.
Returns reachableMaps, unreachableMaps, deadEndMaps (no exit), deadPages (pages that can never run, with the first unmet condition), switches/variables read-but-never-set and set-but-never-read, edges (direct transfers), notes, a plain-language summary and names (map id to name).
goal (exactly one of switch, mapId or event) adds a verdict with up to 10 blockedBy reasons. includeGraph adds a Mermaid flowchart of the map transfers. Lists are cut at limit (the summary counts stay exact); truncated is also set when an analysis cap was hit (see notes). Staged changeset data is analysed.
ParametersgoallimitincludeGraph
build_dialogue_tree
Build dialogue tree
Compiles a nested tree of nodes into correctly indented event commands and optionally inserts it into an event page, so you never hand-write indents, block terminators or move-route rows. Covers dialogue, branching, switches and variables, cutscenes (screen effects, audio, pictures, animations, move routes) and game flow (battles, shops, items, gold, party, scenes, labels). With mapId + eventId the commands are inserted at indent 0 before the page's end (or at `index`), like add_event_command; without them, or with dryRun, nothing is written and the compiled commands are returned in `preview`. `tree` is an array of nodes; every node is an object with one main key, and unknown keys are rejected. choices, if and battle bodies nest at most 8 levels deep (each body counts as a level). A node that is invalid anywhere in the tree fails the whole call and nothing is written. Node vocabulary, in three groups. (1) MESSAGES AND FLOW: {say: string | string[], face?: {name, index}, background?: 0|1|2, position?: 0|1|2} (4 lines per message box; "\n" splits lines; control codes like \C[2] are kept as written); {choices: [{label, then?: Node[]}] (1-6), cancel?: "disallow" (default) | "branch" | choiceIndex}; {if: Condition, then?: Node[], else?: Node[]} with Condition = {switch, is?} | {variable, op: "eq"|"ne"|"gt"|"gte"|"lt"|"lte", value} | {selfSwitch: "A".."D", is?} | {gold} (party has at least) | {item} (party has item); {setSwitch: {id, value}} | {setVariable: {id, op: "set"|"add"|"sub", value}} | {setSelfSwitch: {ch, value}} | {transfer: {mapId, x, y, direction?: 0|2|4|6|8, fade?: 0|1|2}} | {raw: [{code, indent?, parameters?}]} (indent is relative to the node's position). Example: [{"say":"Will you help?","face":{"name":"Actor1","index":0}},{"choices":[{"label":"Yes","then":[{"setSwitch":{"id":5,"value":true}},{"say":"Thank you!"}]},{"label":"No","then":[{"say":"A pity."}]}],"cancel":"branch"}]. (2) CUTSCENE, where target is "player" | "this" (the running event) | a positiv
ParameterstreerequiredindexmapIddryRuneventIdpageIndex
create_event_from_template
Create event from template
Creates a complete, ready-to-use map event at (x, y) from a template, in one write. Refuses out-of-bounds tiles, and refuses a tile that already holds an event unless allowStack is true. Graphics default to none: events are INVISIBLE in game until an image is supplied (chest: closedImage/openImage, npc: image; locked_door, inn, shop and save_point never get a graphic and are meant to sit on a tile that already looks right). Templates and their params: chest {reward: {gold?, item?: {type: item|weapon|armor, id, count?}}, message?, closedImage?, openImage?} (two pages: the action button opens it and sets self switch A, then an empty opened page; if only closedImage is given, openImage defaults to the same graphic with direction 8 - the opened-chest frame of the standard chest sheets); locked_door {keyItemId, destination: {mapId, x, y, direction?: 0|2|4|6|8}, lockedMessage?, consumeKey?} (transfers the player if the party holds the key); inn {price, greeting?} (Stay/Leave choice; staying charges gold, fades out, restores the party, fades in); shop {goods: [{type: item|weapon|armor, id, price?}] (1-40; price defaults to the database price), purchaseOnly?}; save_point {} (opens the save screen); npc {lines: string[], face?: {name, index}, image?}. Image = {characterName, characterIndex (0-7), direction?: 2|4|6|8, pattern?: 0|1|2}. Returns { eventId, name, pages }.
ParametersxrequiredyrequiredfacenamegoodsimagelinesmapIdrequiredpricerewardmessagegreeting+9 more
Procedurally generate a dungeon (rooms joined by corridors) or a cave (organic, one connected region) and paint it with a tile profile. Give exactly one of `mapId` (generate into an existing map, using its size and tileset) or `create` (make a new map and register it in MapInfos.json). An existing map that has any tile or any event is refused unless `overwrite` is true; overwrite resets every tile layer and removes all events. `seed` makes the result repeatable; when omitted a random seed is picked, and the seed used is always returned. The profile (floor, wall, optional wallTop, optional weighted decor) defaults to suggestTileProfile, which works from the tileset's data only: the lowest-numbered walkable A2 kind as floor (else the first walkable A5 tile), the lowest-numbered blocking A4 wall kind as wall with the floor-rule A4 kind above it as wall top (else the first blocking A5 or B tile), and no decor. The profile used and the reasoning are returned as profileUsed and profileNotes. Nothing is written when the profile's floor is not walkable, its wall or wall top does not block movement, a sheet has no image, or the painted map is not fully reachable from the entrance. Markers are empty placeholder events at priority 0 (below characters, so they never block the player) named Entrance, Exit and Chest 1..n, placed on floor cells; chests are random floor cells away from the entrance and exit, chosen so that no chest cuts off any part of the map. `markers` defaults to {entrance: true, exit: true, chests: 0}. The result lists each marker's eventId and position under `markers`. Afterwards: call render_map_image to look at the result (consider showPassability); wire doors to other maps with connect_maps using the returned entrance and exit coordinates; fill the chest markers with create_event_from_template or the event tools. A marker occupies its tile: delete it with delete_event before placing a door or chest there, or pass allowOverlap (connect_maps) / allowStack (cr
ParameterskindrequiredseedmapIdcreatemarkersprofileoverwrite
capture_stamp
Capture stamp
Save a rectangle of a map as a reusable stamp in <project>/.mcp-stamps/<name>.json: all six layers (tiles, shadow bits, regions) and, with includeEvents (default true), the events standing inside it. Use place_stamp to paste it onto any map of the same tileset. Width and height are 1-64 and the whole rectangle must lie inside the map. Names are 1-64 characters (letters, digits, space, _ and -, starting with a letter or digit). An existing stamp is only replaced when overwrite is true. Stamps are written like any project file, so inside an open changeset they are only staged until commit_changeset. Add .mcp-stamps/ to .gitignore next to .mcp-backups/ unless you want to share stamps.
ParametersxrequiredyrequirednamerequiredmapIdrequiredwidthrequiredheightrequiredoverwriteincludeEvents
Paste a stamp made with capture_stamp onto a map with its top-left corner at (x, y). The whole stamp must fit inside the map (it is never clipped) and the map must use the same tileset the stamp was captured from. The rectangle is REPLACED on every layer: empty stamp cells erase what was there. Autotile cells (A1-A4) are re-shaped so their edges blend with the surroundings, including the cells next to the stamp; all other tiles, shadow bits and regions are copied as they are. With includeEvents (default true) the stamp's events are added with new ids and moved to the placement; if one would land on a cell that already has an event, nothing is placed and the cells are listed (includeEvents: false places only the tiles). There is no rotate or mirror. A backup of the map is kept.
ParametersxrequiredyrequirednamerequiredmapIdrequiredincludeEvents
List the stamps saved in <project>/.mcp-stamps/ (name, size, tilesetId, event count), sorted by name. Stamps captured inside a changeset that is still open are not listed until it is committed.
Takes no parameters.
Copy an image or sound file from this computer into the project: <project>/<folder>/<name>.<ext>. source must be an absolute local path to a regular file (no relative paths, network/UNC shares, devices or symbolic links). The type is read from the file's header, never its extension: img/* folders take files with a PNG header (max 32 MiB; only the signature + IHDR is checked, not the whole image), audio/* folders take files whose header is Ogg (OggS) or ISO-BMFF/M4A (ftyp) (max 128 MiB; only the header is checked, not the codec or the full file); the extension (.png, .ogg, .m4a) is chosen from the detected header. name defaults to the source file name without its extension and must be 1-64 characters from A-Z a-z 0-9 space _ ! $ ( ) - (no dots, no path); a '$' prefix on a character sheet means one character per sheet, '!' means no offset. An existing file with the same name (letter case ignored) is only replaced with overwrite: true; the session backup (list_backups / restore_backup) keeps the file as it was before this server session first touched it (until set_project is called again, which starts the snapshots over), so a file that was itself created or changed earlier in the same session has no backup of that intermediate version. Nothing is converted or resized; warnings flag sheet sizes that do not fit the folder's layout, and for audio a missing sibling format (MV's web build needs both .ogg and .m4a). Refused while a changeset is open (binary files cannot be staged): commit or discard it first.
Parametersnamefolderrequiredsourcerequiredoverwrite
List the image and sound files in the project's asset folders (img/* and audio/*, 18 folders; all of them or one `folder`). Each file shows its name (without extension), ext, size in bytes and, for images, the pixel size read from the PNG header, plus warnings (a header that does not match the extension, or a sheet size that does not fit the folder). Only the first 64 bytes of each file are read, so a sound's type is judged from its header alone, not the codec or the whole file. Sub-directories and files with other extensions (.rpgmvp, .txt, ...) are skipped. With includeUsage (default true), files in the folders the reference scan covers (all except img/system and img/animations) get usedBy (at most 3 places, e.g. 'Actor 1', 'Map003 event 5') and unused (true when nothing in the database, maps, common events or troops references the name). Names are matched case-sensitively, so a reference that differs only in letter case shows the file as unused: run audit_assets to find case mismatches and missing files. A plugin or script that loads a file by name is not seen, so check before deleting. Files with names outside the import rule (dots, non-ASCII) are listed too, but preview_asset cannot open them. Interlaced PNGs are flagged in warnings. A folder that cannot be read gets an `error` on its entry instead of failing the listing. Files are sorted by name; each folder shows at most `limit` files and `truncated` counts the rest.
ParameterslimitfolderincludeUsage
preview_asset
Preview asset
Show a PNG from an img/* folder as an image so you can see it, with its pixel size, file size and, for img/characters and img/faces, the sheet layout implied by the name and size. name is the file name without .png and must match an existing file exactly (see list_assets). The image is scaled down (nearest neighbour, aspect kept) to at most maxSize pixels on its longer edge; smaller images are shown as they are. Files over 32 MiB or 16 million pixels, interlaced PNGs and files that are not valid PNGs are refused. Only names that pass the asset name rule (1-64 characters from A-Z a-z 0-9 space _ ! $ ( ) -) can be opened, even though list_assets may show files with other names. Audio cannot be previewed.
ParametersnamerequiredfolderrequiredmaxSize
install_skills
Install skill files
Copy the bundled RPG Maker skill files (workflow guides for map building, event writing, balancing, localization, plugins) into the project's .claude/skills folder so Claude Code picks them up automatically in that project. The same files are always available as resources (rpgmaker://skills/<name>). Existing skill folders are skipped unless overwrite=true.
Parametersscopeskillsoverwrite