Tools Reference

Every tool the Vastopia MCP server exposes, grouped by area, with its purpose and key arguments — from maps and entities to scripts, assets and builds.

19 min read

How to read this page#

Tool names below are the names your AI app shows (some apps prefix them, for example mcp__vastopia__create_item). Each table lists the tool, what it does, and the arguments that matter most; optional arguments are marked in the text. Conventions that apply across the board:

  • dryRun: true on a writing tool returns the exact file changes (or the request body, for platform tools) without writing or calling the API. Use it freely.
  • confirm: true is required by destructive tools. Without it they return a preview of what would be removed — and, for delete_entity and delete_asset, a list of everything still referencing the target.
  • Map ids are the map directory names from list_maps. Tiles are integer map tiles (one tile = 0.5 world units), centred on the origin — the standard map is tiles -64..63 on both axes. See Coordinate system.
  • Ids for items, NPCs, objects and placed elements are allocated by the tools. Never make one up.
  • Read-only tools are exempt from the rate limit and the audit log; everything else is rate-limited (120 calls per actor per minute by default) and logged to audit_log.jsonl.

Projects and workspace#

ToolPurposeKey arguments
list_projectsList every game in the workspace (directory, name, game_id), marking the active one.none
get_active_projectShow the selected game, plus the server's build stamp (version, commit, build time).none
select_projectSwitch the active game for the whole server process. Ambiguous names are refused.project (directory name, game name or game_id)
create_projectScaffold a new minimal game (project.vastopia, assets/, server/), initialise git with a .gitignore, and make it active.name; optional title, description, dir, git: false
get_project_summaryName, title, version, starting map, linked game_id, maps, and counts of items, NPCs and objects. Call first.none
get_project_configRead project.vastopia section by section ([project], [paths], [game], [platform]).none
update_game_configEdit game_config.json: title, description, version, developer, website, starting map. Only passed fields change.any of title, description, version, developer, website, starting_map
set_project_pathsChange [paths] keys in project.vastopia (for example maps_dir); the rest of the file is preserved byte for byte.paths (map of key to value)
set_starting_mapSet the map the game starts on in both project.vastopia and game_config.json; validates the map exists.map
validate_projectReport inconsistencies without changing anything: one-sided dual exports, placements of deleted entities, broken script bindings, drops of missing items, missing interface scenes, leftover temp files. Each issue names the tool that fixes it.none
check_referencesFind everywhere an item, NPC or object id is referenced (drop tables, shops, recipes, task triggers, dialogue, spawners, placements) before changing or deleting it.kind (item/npc/object), id
get_change_logThe audit log (who, which tool, when, success) and the backup generations that restore_backup takes.optional limit (default 50), path
restore_backupRoll a backup generation's files back to their pre-write contents. Snapshots the current state first, so a restore is itself undoable.generation, confirm: true; optional paths

Maps#

ToolPurposeKey arguments
list_mapsList the project's maps and identify the starting map.none
create_mapCreate a new, empty, editor-loadable map: regions.json, terrain_data.json, water.json, the height-layer and walkability binaries, and the <map>_region.tscn scene. Refuses to overwrite.map (letters, digits, -, _); optional size_tiles (multiple of 128, default 128), layers (names), water (enabled, level)
get_map_layoutEvery spawner, object (with its full footprint), location and trigger zone with tile coordinates, plus an ASCII grid of the map. walkability: true overlays the server's blocked tiles.map; optional resolution (default 48), walkability
activate_map_regionsGrow a map by activating 64x64-tile region cells. Region (0,0) is tiles 0..63; region (-1,-1) is tiles -64..-1.map, regions (list of {x, z} cells)
set_waterSet the water plane: on/off, level, colours, highlight, roughness. Water is off until enabled: true. Only passed fields change.map; optional enabled, level, water_color, deep_color, highlight_color, fresnel_power, highlight_strength, roughness, metallic

Terrain#

Terrain is authored on a working heightfield kept under terrain_work/ in the project (a server scratch file, not a game file). generate_terrain creates it, sculpt_terrain, apply_erosion and paint_terrain_material edit it, and bake_terrain commits it to the game: walkability into server/data/maps/flag_data/<map>.terrain, and heightmap.r16, control.raw and bake_meta.json into terrain_work/bake/<map>/ for the editor to import. A live editor imports the bake immediately; otherwise the editor imports it the next time the map is opened. There is no manual import step.

ToolPurposeKey arguments
generate_terrainBuild the working heightfield from an ordered op-stack (see the op table below). The field is centred on the map origin; a 513 grid covers tiles -256..256.map, ops; optional grid (size default 513, seed), origin_tile_x, origin_tile_z
sculpt_terrainBrush edit over a tile region: raise, lower, flatten, smooth, ramp, plateau. Returns before/after stats.map, op, region ({min,max} or {center,radius}); optional strength (0–1), falloff (0–1), targetHeight (world units — absolute for flatten/ramp/plateau, relative for raise/lower)
apply_erosionHydraulic (water-carved) or thermal (scree) erosion pass with a before/after slope histogram.map, method; optional intensity (0–1, default 0.5)
paint_terrain_materialAssign grass, rock, sand, snow, dirt or water where a selector matches (height, slope, region, gradient, radial).map, material, where (for example {selector:'slope', min_deg:35})
bake_terrainCommit the working heightfield: recompute walkability from slope, rewrite the flag data, export the heightmap and control map. dryRun returns the diff and validation without writing.map; optional ceiling_deg (walkable slope ceiling, default 45), origin_tile_x, origin_tile_z
read_terrainA statistical summary (walkable fraction, active regions, blocked tiles, height-layer offsets, water level) and an ASCII grid (. walkable, X blocked, ^ height layer).map; optional view (summary/ascii/both), resolution
sample_terrainExact facts for one tile: active region, walkable, each height layer's offset.map, x, z
query_terrain_regionPer-tile cells over an inclusive tile rectangle, plus a sub-summary. Large regions are truncated.map, min [x,z], max [x,z]
set_tile_walkabilityBlock or unblock tiles directly. Blocks made here are permanent (a bake only clears its own); an unblock can be re-blocked by the next bake if the slope exceeds the ceiling.map, walkable, tiles or bounds; optional layer (0 = ground, up to 7)

The ops list for generate_terrain accepts nine op types, applied in order:

Op typeWhat it doesFields
noiseGenerate the base field from a preset: plains (±3), rolling_hills (±8), mountains (ridged, ±40), eroded (warped, ±20), plateau (terraced, ±25).preset; optional heightScale, frequencyMul
maskName a region for later ops to target, by height, slope, gradient, region or radial selector.name, selector; selector fields min, max, min_deg, max_deg, direction, center, radius, softness
stampAdd a hill, mountain, mountain_range, crater, ridge or mesa.shape, position (or x, z), radius, amplitude; optional rotation, blend (add/max/replace), mask
erosionSame as apply_erosion, inside the stack.optional method, intensity
carve_riverCut a river along a tile polyline.path; optional profile (V/U), width, depth
carve_pathFlatten a corridor along a polyline.path; optional width
auto_riversCut channels along the flow field.optional threshold, depth, width
biomeAssign materials by elevation, moisture and slope.optional water_level, snow_level, rock_slope
paint_terrain_materialSame as the standalone tool, inside the stack.material, where (or the selector fields inline)

Height layers#

ToolPurposeKey arguments
create_height_layerAdd an elevated floor (bridge, balcony, upper storey). A new map has one layer; maximum seven.map; optional name (default "Layer N"), color [r,g,b,a] 0–255, default_height
set_height_layerSet a layer's height over a tile rectangle — flat with height, or sloped with ramp.map, layer (1–7), region {min,max}, and height or ramp {axis, from, to}

Placement#

All placement tools update the map's regions.json, re-derive the matching server export, and refresh a live editor showing that map (never over unsaved changes).

ToolPurposeKey arguments
place_npc_spawnerPlace an NPC spawner on a tile. Re-derives server/data/maps/npc_spawns.map, npc_id, tileX, tileZ; optional rotation_y, behavior (idle/wander/patrol), spawn_count, spawn_radius, respawn_time, wander_intensity, spawn_condition
place_object_on_mapPlace an object by its south-west tile; the footprint extends east and north by the object definition's tile_width/tile_depth. Re-derives object_spawns.map, object_id, tileX, tileZ; optional model_rotation_y, height_layer (default 0), interaction_type (use/examine/custom), interaction_radius, script_on_interact, is_persistent
define_locationCreate or edit (by name) a named area with optional fog, weather and difficulty overrides. Re-derives the server location_bounds export.map, name, bounds {min,max} or tiles; optional fog_enabled, fog_density, fog_height, difficulty_modifier, weather_type, script_path
define_trigger_zoneCreate or edit (by name) a zone that runs a script on enter, exit or stay. Writes regions.json only — there is no separate server export.map, name, bounds or polygon; optional trigger_type (on_enter/on_exit/on_stay), script_on_trigger, one_shot, cooldown, enabled
remove_elementRemove a placed spawner, object, location or trigger zone by element id.map, id, confirm: true
place_propsPlace decorative props (no id, no script, invisible to the server) by explicit placements or a deterministic seeded scatter. Writes props.bin and its server mirror.map, model_asset_id (or model_path); optional placements (tile/world, y, rotation_y, scale), scatter (bounds, count, seed, jitter, random_rotation, scale_range, avoid_blocked, spacing), multimesh (default true), replace
list_building_prefabsList saved buildings from the Building Editor with plot, real footprint, object vs prop piece counts, and missing object ids.none
stamp_building_prefabPlace a whole saved building in one call. Upper storeys get height layers created automatically (3.0 units per floor). Rotation must be a multiple of 90.map, prefab, tileX, tileZ; optional rotation_y, base_height_layer

Entities#

Entity tools write both halves of the dual export — assets/data/*.json and server/data/*.json — and allocate ids. Update tools change only the fields you pass and preserve everything the editor set.

ToolPurposeKey arguments
list_items / list_npcs / list_objectsId and name lists, optionally filtered by a name substring.optional query
get_item / get_npc / get_objectFull client and server variants of one definition. Objects report the tile_width/tile_depth you need before placing.item_id / npc_id / object_id
create_itemCreate an item. With a model_asset_id the inventory icon is rendered from the model automatically.name; optional description, is_equippable, stackable, slot, equip_mode, attach_bone, model_asset_id, icon_path, interact_options, tradeable, droppable, weight, value, equipment_stats, script_path, equipment_script_path, auto_icon
update_itemChange only the fields you pass.item_id plus any create_item field
create_npcCreate an NPC with a model, footprint, options, animation base and clip ids, scale, and a combat block. Bind an option to a dialogue with {label, dialogue_id}.name; optional model_asset_id, tiles, description, options, animation_base, idle_animation_id, walk_animation_id, run_animation_id, scale, combat (hitpoints, max_hit, combat_level, attack_speed, attack_distance, aggressive, attackable, respawn_ticks, accuracy/strength/defence by style, combat_script_path), script_path
update_npcChange only the fields you pass, including individual combat fields.npc_id plus any create_npc field
create_objectCreate a placeable object with its footprint, interaction actions, collision type and interaction distance.name; optional model_asset_id, tile_width, tile_depth, description, interact_actions, collision_type, interact_distance, interactable, scale, script_path
update_objectChange only the fields you pass, including the footprint.object_id plus any create_object field
delete_entityDelete an item, NPC or object from both halves. The id is retired permanently; references are listed, not rewritten.kind, id, confirm: true
list_animationsAnimation bases and the clips registered to each, with the per-base ids NPCs use.optional base
define_animation_baseRegister a rig that clips are retargeted to. Updating merges; existing clips are untouched.base (lowercase id); optional display_name, skeleton_path or skeleton_asset_id, mesh_path or mesh_asset_id, source_model
define_animationRegister one clip under a base in assets/data/animations.json and return its per-base id. The .tres must already be imported.base, name; optional resource_path or animation_asset_id, length_sec, tags, retarget_hint, in_place, animation_id (to update)
define_vfxRegister or edit a VFX entry in assets/data/vfx_database.json, optionally generating the particle scene from an archetype (burst, impact, stream, aura, swirl).vfx_id, name; optional scene_path, scale, scene (archetype plus amount, lifetime, one_shot, explosiveness, color, emission_radius, direction, spread, velocity, gravity, scale, particle_size, emission_energy, material)

Icons#

ToolPurposeKey arguments
render_item_iconRender an item's 3D model to assets/icons/{64,48,32}/<item_id>.png — through the open editor, or a throwaway Godot process when none is running. create_item does this automatically; call it to re-frame.item_id, model_asset_id or mesh_path; optional yaw (default 35), pitch (default 30), zoom, outline, outline_color, light_angle
generate_item_iconDraw a procedural icon for an item with no model: flat fills and facets in a 128x128 space, then an automatic finishing pass (outline, occlusion, light ramp, rim, contact shadow). Writes the same three sizes.item_id, shapes (polygon/ellipse/line/shade); optional finish overrides

Game data (schemas)#

These tools write the server's schema-backed tables under server/schemas/. Most replace the row with the given id, so read it first with get_schema_data when editing.

ToolPurposeKey arguments
get_schemaList schema names, or return one schema's fields, types and defaults.optional schema
get_schema_dataRead the rows of a table, one by id or all, with paging. count is always the full size.table; optional id, limit (max 500), offset
set_schema_rowWrite a row in any schema table, including ones with no dedicated tool (prayers, attack styles, …). Merges onto an existing row; unknown fields are refused.table, row (must include the primary field)
delete_schema_entityDelete a row by id. For skills, removes it from both client and server config.table, id, confirm: true
list_drop_tablesRow counts for all twelve drop tables (4 sources x 3 systems).none
set_drop_tableWrite loot for an NPC, item, object, or a standalone misc table, in one of three systems: independent (each drop rolls its own 0–100 chance), table (weighted tables with rolls), or wheel (groups whose weights total 100). Item and object sources take triggers (option clicks, or item_on for using an item on the object).source (default npc), system (default independent), npc_id/item_id/object_id/table_id, and drops, tables or groups; optional rolls, triggers, trigger_option, key_item_id, consume_source
define_shopA shop's stock and pricing. Every stocked item and the currency must exist.shop_id, name, stock (item_id, price, quantity); optional currency_id (required for the first shop), restocks, buys_items, buys_only_stock, buy_multiplier, sell_multiplier
define_recipeA crafting recipe: ingredients, products, activation, level gates and XP. Only skill_requirements and skill_rewards are read at runtime; a recipe with no skill_rewards grants no XP.recipe_id, name; optional category, skill_requirements, skill_rewards, ingredients/products or ingredient_groups/product_groups, activation_type, activation_data, crafting_ticks, animation_id, success_rate, tool_item_id, product_chance
define_dialogueA dialogue graph of text, choice, condition, action, input and reroute nodes. Needs start_node_id (defaults to the first node). Reach it from an NPC option's dialogue_id.dialogue_id, name, nodes; optional display_type, start_node_id
define_taskA tick-based activity bound to a script — the standard way to build fishing, mining and any channelled action. Break-on flags (movement, combat, damage, death, teleport, equip change) all default true.task_id, name, triggers (non-empty; types object_click, npc_click, item_click, command, location_enter, item_on_object, item_on_npc, item_on_item, player_join, npc_spawn, object_spawn, server_startup); optional script_path (relative to server/), task_type (entity/world), entity_type, delay_ticks (4 = 1 s), stop_after_ticks, repeating, enabled, the break_on_* flags, folder, group, description
define_buffA status effect the server applies each tick: damage_over_time or heal_over_time only.buff_id, name; optional type (buff/debuff/neutral), effect, power, tick_interval (default 4), default_duration (default 20), stackable, icon
define_specialA weapon special attack keyed by name.name; optional description, weapon_ids, energy_cost (default 50), damage, hit_count, apply_buff, buff_duration, buff_power
define_bossThe standard way to make any NPC fight: a fight with named attacks and optional phases, shown in the editor's Combat Scripts tool. An attack or the whole fight can delegate to a C# NpcCombatScript via custom_script.fight_id, name, npc_ids; optional max_hp, attack_speed (default 4), attack_distance (default 1), attacks (attack_id, style, hits, hit_delay, damage_mode, min_hit, max_hit, accuracy_mode, accuracy, animation, projectile_id, custom_script), phases (trigger_type, trigger_value, trigger_expression, attacks, default_attack_id), custom_script, folder
define_skillA skill in both client and server skills_config.json; also regenerates the in-game skills tab scene.skill_id, name; optional category (combat/gathering/artisan/support), max_level (default 99), icon, ordinal, script_path

The table names get_schema_data and delete_schema_entity accept: the twelve drop tables (npc_drops, npc_table_drops, npc_wheel_drops, item_drops, item_table_drops, item_wheel_drops, object_drops, object_table_drops, object_wheel_drops, misc_drops, misc_table_drops, misc_wheel_drops), drops (alias for npc_drops), shops, recipes, dialogues, tasks, buffs, specials, bosses, skills and vfx.

Interfaces#

ToolPurposeKey arguments
list_interfacesScreens in interface_database.json: id, name, scene path, type.none
get_interfaceOne screen's database row, the controls parsed from its .tscn, and the raw scene text. Read before redefining — define_interface replaces the scene.name
define_interfaceAuthor a screen headlessly: writes the .tscn under assets/interface/screens/ (tabs to screens/tabs/, chatbox to screens/_system/) and upserts both interface databases. The canvas is fixed: 600x400 for gamescreen/chatbox, 256x308 for tab; larger roots are rejected.name, size, nodes (types panel, label, button, vbox, hbox, grid, scroll, spacer, item_slot, item_grid, progress_bar, spawner, checkbox, line_edit, texture); optional type, anchor, offset
delete_interfaceDelete a screen's scene and its rows in both databases.name, confirm: true

Labels are addressable by name from server scripts, buttons carry an action_id delivered to IInterfaceScript.OnAction, and any node can carry context_options for a right-click menu. See Custom interfaces.

Server scripts#

ToolPurposeKey arguments
list_server_scriptsEvery .cs under server/scripts/ and server/modules/ with its category, class name and base class.none
read_server_scriptFull source of one script by project-relative path.path
get_script_apiIntrospect the real scripting API: an index of classes, or one class's methods and properties with signatures and which members are overridable hooks.optional class
write_server_scriptCreate a script from a base-class template: combat, npc, object, command, task, item, equipment, location, interface, or custom (you supply the body). Written to server/scripts/<category>/<Name>.cs after a structural check for unbalanced brackets and unterminated strings.kind, name; optional category, root (scripts/modules), body, overwrite, allow_lint_errors
move_server_scriptMove or rename a script. Reports files that still reference the old path as dangling_references.from, to
delete_server_scriptDelete a script (a .bak is kept).path, confirm: true
generate_script_projectWrite server/VastopiaScripts.csproj and server/_VastopiaGlobalUsings.g.cs so a C# editor gives IntelliSense, and building the project compile-checks every script before launch.optional server_dll, exclude

See IDE setup for what to do with the generated project.

Assets#

ToolPurposeKey arguments
list_assetsSearch the project's asset library. The only way to discover valid model_asset_id values. Types: SPRITE, MODEL_3D, AUDIO_SFX, AUDIO_MUSIC, TEXTURE, ANIMATION, UI_SCENE, SKELETON, OTHER.optional query, type, tags, limit (default 50)
import_assetImport a file from disk into the library with a new ULID. FBX and OBJ are converted to .glb with headless Blender when one is installed.source_path; optional name, type, tags, metadata
update_assetEdit a library entry's name, tags and metadata; never touches the file.asset; optional name, tags, add_tags, remove_tags, metadata
move_assetRelocate an asset's files under assets/ and update its recorded path.asset, to_folder
delete_assetDelete the library entry and its files (a model's whole folder). The confirmation lists everything still pointing at it.asset, confirm: true
browse_cloud_assetsSearch the public cloud asset library (models, textures, audio) with server-side paging. No credentials needed.optional query, type, tags, limit (default 40, max 100), skip, include_pulled
pull_cloud_assetDownload a cloud asset into the project (checksum-verified), optionally creating an object definition whose footprint is measured from the model. Idempotent.asset_id; optional name, make_prop, tile_width, tile_depth, interact_actions
request_assetRecord art the project still needs from a person. Shows in the editor's Library tab under AI Asset Requests; a matching import closes it.name, type; optional description, tags, for_use
list_asset_requestsPending requests by default; status: "all" for history.optional status
close_asset_requestClose a request by hand when the art arrived under a different name or is no longer needed.request_id, status (fulfilled/cancelled); optional asset_id, reason

Live editor#

All of these answer connected: false with an explanation when no editor is on the bridge.

ToolPurposeKey arguments
get_editor_statusActive editor mode, open map and its edit mode, unsaved editors and the files at risk, open project, sign-in state.none
refresh_editorRe-read the open map's region elements. Refuses over unsaved changes unless force: true.optional map, force
show_in_editorOpen a map in the Map Editor and optionally centre the camera on a tile.map; optional tile [x,z]
screenshot_editorA PNG of the editor viewport, downscaled to max_width (default 1024).optional max_width (64–4096)
play_localRun the game the way the Play button does — build the PCK, deploy server data, launch the client — and return the editor's diagnostic report (phase, timings, server log tail). Needs a live editor.optional timeout_ms (default 300000)
export_pckProduce the client PCK through the live editor, or through headless Godot when none is running. Default output packs/<game>.pck.optional out, game, prefer_headless

Builds and deployment#

These talk to the platform API and need a credential (see Setup). game_id defaults to the project's linked game everywhere.

ToolPurposeKey arguments
register_gameCreate or link a platform game and store its game_id in project.vastopia. Safe to repeat.optional name, game_id
update_game_listingEdit the storefront listing: name, description, excerpt, tags, visibility, content rating, genre, status, media URLs, multiplayer settings.optional game_id and any listing field
get_live_statusWhat is deployed right now (public): live build, PCK URL and hashes, server host/port/status.optional game_id, prefer_live
list_buildsBuilds newest first (id, number, name, status, size, when). include_deleted shows recently deleted ones.optional game_id, include_deleted, limit
build_server_packageZip server/data, server/modules, server/scripts and server/schemas into a deterministic _server_package.zip.optional out
create_buildStep 1: allocate a build and get presigned upload URLs for pck, serverPackage, gameConfig and manifest.build_name; optional game_id, game_name
upload_build_artifactsStep 2: upload local files to those URLs with SHA-256 checksums; returns sizes and hashes.artifacts (list of {kind, url, path})
upload_pck_multipartUpload a large PCK in parts (start, sign, put, complete; aborts on failure).build_id, path; optional game_id
finalize_buildStep 3: submit sizes and hashes so the platform verifies the uploads.build_id, artifacts ({kind, size, sha256}); optional additional_packs, game_id
deploy_test_buildRun a finalized build on a test server and return its host and port (a null host means the container is still starting). Test servers keep running until stopped.build_id; optional game_id
stop_test_serverStop a running test server.build_id; optional game_id
read_server_logsRecent log lines from the test (default), live or beta deployment, capped at 2000 (default 200), with contains/exclude/min_level filters.optional game_id, lines, mode, contains, exclude, min_level
promote_buildStep 4: deploy a finalized build live as an update (needs update_title and update_body) or a patch (needs patch_note), now or scheduled.build_id, type, confirm: true; optional update_title, update_body, patch_note, timing, game_id
rollback_buildRevert the live deploy to a previous build.build_id (the one to roll back to), confirm: true; optional game_id
get_deploy_statusStage, attempt, error and timings of the current or most recent deploy job; terminal: true means it will not change again.optional game_id
wait_for_deployBlock until the deploy finishes or a timeout passes, then report.optional game_id, timeout_seconds (default 300), poll_seconds (default 5)

For what these states mean on the platform side, see Builds and versions and Updates, patches and rollback.

Prompts and resources#

Besides tools, the server registers MCP prompts (ready-made multi-step requests your AI app can offer) and resources (read-only context an app can attach).

PromptWhat it asks the assistant to doArgument
new-enemyCreate a complete enemy NPC — model, combat stats, drops, optional placement — from a description.description
build-shopStand up a working shop: themed goods, a shop definition, and a shopkeeper NPC that trades.theme
quest-from-descriptionAssemble a simple quest — NPCs, dialogue, a task, trigger zones — from prose.text
populate-mapRead a map's layout and place themed NPCs and objects in its free, walkable space.map, theme
generate-terrainTurn a landscape description into a terrain op-stack, preview it, then bake it.map, description
ResourceContents
vastopia://project/summaryThe same overview get_project_summary returns.
vastopia://assetsThe project's asset catalog.
vastopia://map/{map}/layoutA map's regions, placements and free space (one per map).
Spotted a mistake or something missing?Tell us on Discord