io.github.SerifeusStudio/rpgmaker-xp-mcp

Add a single command to an event page (for Show Text prefer add_show_text). Common XP codes: 101=Show Text first line (401=continuation lines), 102=Show Choices [[texts...],cancelType] (each 402 branch repeats its choice text and must stay in sync), 111=Conditional Branch, 121=Control Switches, 122=Control Variables, 123=Control Self Switch [ch,0=on/1=off], 125=Change Gold, 126=Change Items, 201=Transfer Player, 209=Set Move Route (509=continuation), 223=Change Screen Color Tone, 355=Script. indent must increase by 1 inside branch blocks; the trailing code-0 terminator is preserved automatically.

Add a Show Text message to an event page. Handles XP's 101/401 structure automatically: first line of each box is code 101, continuation lines are 401, and text longer than 4 lines is split into multiple message boxes. Use \n for line breaks.

Paint an autotile (slot 0..6 = tileset autotile_names index) and compute the correct edge variant per cell from 8-neighbour connectivity (seamless coastlines/paths/cliffs). Supply ONE of: `blob` (organic roundish shape — USE for ponds/lakes/forest patches); `path` (autotile-safe road/trail/river through waypoints, width >=2); `cells` (arbitrary [x,y] list); or `region` (rect — only for rectangular floors). All shapes are auto-sanitized to be autotile-safe (4-connected, no diagonal pinches or 1-cell holes) so they never render broken/pinched. The border ring of existing same-autotile cells is recomputed so it blends. Preview with render_map.

Inspect a PNG before import and report whether it is a native RMXP asset. Goes beyond canvas dimensions: fingerprints the filename ($/! object sprites, MV/MZ A1-A5 autotile sheets, 48px-divisible MV dimensions) AND detects the true CONTENT tile size via edge-periodicity (16/24/32/48/64px). Catches assets that look fine by size but render 1.5x/2x too large in RMXP's 32px grid, and assets that are not tilesets at all. Returns tier, recommended conversion op, target category, and flags. No writes.

Create a new actor with RMXP defaults (linear stat growth curves unless a parameters Table is provided)

Create a new armor (appended to Armors.rxdata). kind: 0=shield, 1=helmet, 2=body, 3=accessory. Defaults match the RMXP editor; override any field.

Create a damage-dealing skill (simplified). Set physical=true for ATK/PDEF based damage, otherwise INT/MDEF based (magic). Engine formula: damage = (power + ATK*atk_f/100 - PDEF*pdef_f/200 - MDEF*mdef_f/200) * (20 + STR*str_f/100 + DEX*dex_f/100 + AGI*agi_f/100 + INT*int_f/100) / 20. Reference: default-DB Fire is power 140, sp 75.

Create a healing skill (simplified). In XP healing is negative power. Amount healed = power * (20 + INT*int_f/100) / 20 with int_f=50 (default-DB convention), so it scales with the caster's INT. Reference: default-DB Heal is power 150, sp 80.

Create a new map. SIZE IS THE FIRST DESIGN DECISION: a map is N screens of 20x15 tiles, so pass a `purpose` (interior/room/town/dungeon/overworld/region) to get a sensible default size, or set width/height explicitly. Returns the new map id and a size_advisory (screens, target focal-point count, scatter density, oversize warnings) plus the design guide. Writes the next-free MapXXX.rxdata (blank Table[w,h,3]) + MapInfos entry. Paint with apply_autotile / scatter_tiles / set_map_tiles, preview with render_map.

Create a new event on a map. If pages are omitted, a default empty page is created.

Create a new RGSS script. By default it is inserted just above "Main" (the conventional slot for custom scripts).

Create a new skill with full control over RPG::Skill fields. XP has no damage formulas: damage = power scaled by stat influence rates (atk_f/str_f for physical, int_f for magical). Negative power heals.

Create a state-inflicting skill (poison, sleep, etc.). State IDs come from States.rxdata (XP defaults: 3=poison, 5=blind, 6=silence, 7=confuse, 8=sleep, 9=paralyze).

Create a review bundle for one tileset that separates engine facts from semantic claims. Produces the exact source sheet, isolated transparent tile images, source-row strips, manifest.json (priority, passage flags, alpha bounds), catalog templates, and an interactive index.html for identifying single tiles and rectangular multi-tile objects. Use this before assigning map-design roles to an uncataloged tileset.

Wire two maps together: create a Transfer Player (command 201) event at (x,y) on a map that warps the player to (targetX,targetY) on targetMapId. trigger 0 = action button (a door — give it a graphic); trigger 1 = player touch (an edge teleport — leave it invisible). Validates both endpoints exist and are in-bounds before writing. Use validate_connectivity afterwards to check the whole world graph.

Create a new weapon (appended to Weapons.rxdata). Defaults match the RMXP editor; override any field. Equippable in the weapon slot.

Fill a rectangle of a layer with one tile id (or the whole layer if `rect` is omitted). Tile id 0 clears. For autotiles this places the base variant (P1) — smart edges come with apply_autotile.

Get a specific actor by ID, including its 6x100 parameters table (MaxHP, MaxSP, STR, DEX, AGI, INT per level)

Get all actors from the RPG Maker XP project (parameter tables omitted)

Get all armors from the project

List all entries of a database file. Kinds: classes, states, enemies, troops, common_events, tilesets, animations (also actors/skills/items/weapons/armors). Tables and command lists are summarized; use get_database_entry for full data.

Get one full database entry by ID, including Tables (tileset passages/priorities/terrain_tags, enemy element_ranks, class element_ranks) and event command lists (common events, troop pages)

Get the game title (from Game.ini)

Get all items from the project

Get map data by ID (Data/MapXXX.rxdata). Tile data is summarized unless includeTiles is true.

Return the level/map design guide (MAP-DESIGN.md): layer roles (z0 terrain / z1 ground clutter / z2 overhead), tile priority & passability, the multi-tile-object no-overlap rule, composition principles, and the authoring workflow. Load this before authoring or editing maps.

Get a specific event from a map

Get all events from a specific map

Get information about all maps (names, parent, order)

Size advisory for an EXISTING map: screens (ceil(w/20)*ceil(h/15)), target focal-point and path-junction counts, recommended scatter density, approx clutter tile budget, and oversize/purpose-mismatch warnings. Use this first when editing a map so size and tile budget guide the design. Optionally pass a purpose to check the size against its sweet spot.

Read a map's tile ids as a 2D grid (rows top-to-bottom). Returns one layer if `layer` is given, else all three. Tile id 0 = empty, 48..383 = autotiles, >=384 = regular tiles. Use `region` to crop and avoid large payloads.

Get an RGSS script's Ruby source code by index

List all RGSS scripts in Scripts.rxdata (index, name, source length)

Get a specific skill by ID

Get all skills from the project

Get all game switch names (index = switch ID)

Get system data (System.rxdata: party, elements, switches, variables, vocabulary, start position, audio settings)

Read the structured semantic catalog for a tileset together with its generated engine-fact manifest and validation summary. Absence from the catalog means unreviewed, not safe to infer.

Get all game variable names (index = variable ID)

Get all weapons from the project

Create a Tilesets.rxdata entry for a graphic already in Graphics/Tilesets, sizing the passability/priority/terrain Tables to the image (384 + height/4). GUARDED: refuses object sprites, MV A-series sheets, non-256px-wide, or non-32px-content assets (pass force:true to override). This is the gate that keeps mis-classified art out of the database.

Render a map's tile layers to a flat top-down PNG preview (outside the editor) and return the file path. Composites all 3 tile layers using the tileset graphic and autotiles. Use this to SEE a map you built/edited and self-check it. Layout preview only: no priority/overhead draw-order, fog/panorama/weather, autotile animation (frame 0), or event sprites. Reads project Graphics/ then falls back to the RTP (override base with RPGMAKER_RTP_PATH). Writes to Data/.mcp-preview/ by default; Read the returned path to view it.

Render a labeled atlas of a tileset to a PNG: the tileset graphic scaled with a grid, each regular tile's id burned in, passability indicators, and the 7 autotile slots. This is a quick numeric reference, not semantic proof; use create_tileset_identification_harness before assigning map-design roles.

Validate and save reviewed semantic findings for a tileset. Accepts incremental tile/object/autotile arrays or the complete catalog JSON exported by the review page. Generated engine facts cannot be overwritten by catalog claims.

Scatter clutter tile ids over a region with natural random distribution at a target density (fraction of cells), skipping occupied cells. Optional focal point with falloff for a density gradient (denser near a landmark). Use for flowers/bushes/rocks/tall grass instead of hand-placing lone tiles — fixes sparse/corner-clustered decoration. Deterministic given seed.

Search actors by name

Search items, weapons and armors by name or description

Search events on a map by name

Search all RGSS script sources with a regex pattern; returns matching lines with script name and line number

Search skills by name or description