AI-Accelerated Creation

What the Vastopia MCP server is#

Vastopia ships a Model Context Protocol (MCP) server inside the editor install. MCP is the open standard AI apps such as Claude Code, Claude Desktop and Cursor use to call external tools. Once it is connected, your assistant can read and write a Vastopia game the same way the editor does: create items, NPCs and objects, sculpt and bake terrain, place spawners, write server scripts, author shops, quests, dialogue and interfaces, and push builds to the platform.

The server is a standalone program (no Node.js install needed) that lives next to the editor at tools/vastopia-mcp/ — vastopia-mcp-win.exe on Windows and vastopia-mcp-macos on macOS. It works on the project files on disk, which means two things:

• It is editor-optional. An assistant can build a game with the editor closed. Every tool writes the same JSON, INI, scene and binary files the editor would, in the editor's own format, so you can open the result in the editor at any time.
• It also works with the editor open. When you enable AI from the editor, the editor starts a local loopback "bridge". The assistant can then see which editor and map you are looking at, refresh the open map after writing to it, point your camera at what it just made, take a screenshot of your viewport, render inventory icons through your editor, and run Play Local for you.

Nothing about the project changes when you use it: a game authored by an assistant is an ordinary project directory with an assets/ half (client) and a server/ half (server), exactly as described in Project structure.

What an assistant can do#

The server exposes just over a hundred tools, grouped by what they touch. The complete list with arguments is in the Tools reference; this is the shape of it.

Alongside the tools, the server registers five prompts your AI app can offer as one-click recipes — new-enemy, build-shop, quest-from-description, populate-map and generate-terrain — and three read-only resources (vastopia://project/summary, vastopia://assets, and vastopia://map/{map}/layout) that an app can attach to a conversation as context.

What it cannot do#

The server is honest about its limits, and it is worth knowing them before you plan a session:

• It cannot create art. It can import models, sprites and audio you already have, pull them from the cloud library, or record what is still needed with request_asset (those requests show in the editor's Library tab under AI Asset Requests, and close automatically when a matching import arrives).
• It cannot sculpt the Terrain3D surface directly. Terrain is authored as a working heightfield that bake_terrain turns into walkability data plus a heightmap the editor imports automatically the next time the map is opened (or immediately, over the bridge).
• Some things need a live editor. play_local and screenshot_editor drive your open editor and have no headless equivalent. export_pck and render_item_icon prefer the editor but fall back to a throwaway Godot process when a Godot 4.6 binary is available.
• It cannot write client-side code. Vastopia has no client scripting; interfaces are server-driven, as covered in Scripting overview.

How a session fits your workflow#

A typical session looks like this:

1. Open your game in the editor and enable AI (see Setup). The top-bar chip changes from AI Off to AI · YourGame.
2. Commit your project to git. The server's own instructions ask the assistant to request this before a substantial session, because a commit is the only thing that makes a whole session free to undo. The platform's cloud project save is a single latest-wins snapshot per game, not a history you can roll back through.
3. Ask for what you want in plain language. The assistant orients itself with get_project_summary, list_assets and get_map_layout before writing, because the server tells it to.
4. Look at the result. Placement tools refresh your open map automatically (never over unsaved work), and show_in_editor points your camera at the new content.
5. Test it with Play Local (the assistant can trigger it with play_local), or push a test build as described in Workflows.

Safety and guardrails#

The server is designed so that an assistant can be trusted with a real project. These are the rules it enforces, not suggestions it makes.

IDs are allocated, never invented#

Every entity tool — create_item, create_npc, create_object, and the placement tools that create region elements — allocates the next id itself and returns it. Ids are permanent and never re-used, even after a delete, because player saves store inventory, equipment and bank as bare item ids. Re-using an id would silently turn every saved reference into the new entity.

Dual export stays in sync#

Items, NPCs and objects exist in two files each: the client half in assets/data/ (models, icons, animations) and the server half in server/data/ (stats, drops, scripts). The authoring tools always write both. validate_project reports anything that exists on only one side, along with placements that reference deleted entities, script bindings pointing at missing files, and drop tables rolling for items that no longer exist.

Preview before writing#

Almost every writing tool accepts dryRun: true, which returns the exact file changes without touching disk. Destructive tools — remove_element, delete_entity, delete_schema_entity, delete_server_script, delete_interface, delete_asset, restore_backup, promote_build, rollback_build — additionally refuse to act until called with confirm: true, and the confirmation spells out what will be lost; for delete_entity and delete_asset it lists everything still referencing the target.

Every write is backed up and logged#

Writes are atomic (temp file plus rename) and leave a .bak beside the file. Each tool call's files are also snapshotted as one generation under .vastopia_backups/ in the project before they are overwritten, and every mutation is appended to audit_log.jsonl with who made it, which tool, when, and whether it succeeded. get_change_log shows both; restore_backup rolls a whole generation back (and snapshots the current state first, so a restore can itself be undone).

Rate limiting#

Mutating calls are capped at 120 per actor per minute by default (VASTOPIA_RATE_MAX). A runaway loop is refused with a readable error rather than hammering your project, and the refusal is recorded in the audit log.

Publishing is opt-in#

The editor only writes your platform credential into the AI config when Allow publishing is checked in the AI Assistant window. Unchecked, the server runs in author-only mode: publishing tools are still listed, but each one fails with a clear message instead of acting. Going live with promote_build always needs confirm: true, and the server instructs the assistant to run validate_project first and to mention deleted content in the release notes.

Live games are save migrations#

Because saves hold bare ids, deleting an item from a game people already play leaves it in every inventory that holds it as an entry with no name, icon or stats. The server tells the assistant to prefer making content unobtainable (out of drop tables and shops) over deleting it, and check_references shows exactly what points at an id before anything is changed.

Where to go next#

• Setup — enable AI from the editor, or configure the server by hand.
• Tools reference — every tool, its purpose and its key arguments.
• Workflows — worked examples: a map from nothing, a fighting NPC, an item with an auto-rendered icon, a test build.
• Scripting overview — what the C# scripts the assistant writes can and cannot do.
• Builds and versions — what a build is before you let an assistant ship one.