docsReading time: 8 minutes


General

Basics

Advanced

Tutorials


MCP Server Integration & Tool Reference

utiLITI includes an embedded Model Context Protocol (MCP) server running on port 8088 (default). The server provides Dual API Surfaces for scene composition, level design, and editor automation:

  1. Level B: Raw Scene-Building & Editor Primitives (~60+ Tools): Granular, atomic editor operations for direct scene node/entity manipulation, property editing, raw tile writing, and editor control (inspired by Godot MCP workflows like godot-mcp-go).
  2. Level A: High-Level Semantic Map Mutation API (32 Tools): Intent-oriented, batch-capable, revision-tracked, and 100% stateless map operations optimized for autonomous LLM agents.

Design Choice: Use Level B Raw Primitives for direct, step-by-step entity placement, fine-grained property tweaks (set-entity-property), and Godot-style node tree composition. Use Level A Semantic Tools for bulk map generation, spatial region queries, multimodal visual rendering, and atomic transaction dry-runs.

Overview & Architecture

  • Endpoint: http://localhost:8088/mcp
  • SSE Stream: http://localhost:8088/sse
  • Protocol Specification: MCP JSON-RPC 2.0 with JSON Schema 2020-12 (SEP-1613)
  • Live Editor Integration: All mutations run directly inside the active utiLITI editor instance with full Undo/Redo integration and live AWT viewport refresh.

Level B: Raw Scene Building & Editor Primitives

Level B tools provide raw, direct access to utiLITI editor operations and map objects.

1. Scene & Entity Placement (Raw Nodes)

Tool NameDescriptionKey Parameters
add-propSpawns a native Prop entity onto the active map layer.spritesheetName (string), material (string), addShadow (bool), x (number), y (number), width (number), height (number), layer (string), name (string).
add-creatureSpawns a native Creature NPC or enemy entity.spritesheetName (string), scaleSprite (bool), x (number), y (number), width (number), height (number), layer (string).
add-triggerSpawns an interactive Trigger entity with message and target binding.message (string), activation (COLLISION/INTERACT/TOGGLE), targets (string or array), cooldown (int), oneTime (bool), x (number), y (number).
add-lightSpawns a dynamic LightSource entity.color (hex string), intensity (int 0-255), shape (CIRCLE/RECTANGLE/FAN), active (bool), x (number), y (number), width (number), height (number).
add-spawnpointSpawns a player or creature Spawnpoint.spawnType (string), direction (UP/DOWN/LEFT/RIGHT), x (number), y (number).
add-collisionboxSpawns a static CollisionBox physics obstacle.x (number), y (number), width (number), height (number).
add-areaSpawns a rectangular MapArea region for zone triggers and script boundaries.name (string), x (number), y (number), width (number), height (number).
add-sound-sourceSpawns a positional 2D SoundSource emitter.soundName (string), volume (float 0-1), loop (bool), range (float), x (number), y (number).
add-emitterSpawns a particle Emitter entity.emitterType (string), x (number), y (number).
add-entityGeneric map object creator for custom TMX entity types.type (string, required), name (string), x (number), y (number), width (number), height (number), layer (string).
batch-add-entitiesBulk places an array of raw entity definitions onto the active map in a single call.entities (array of entity objects, required).

2. Entity Inspection & Property Editing

Tool NameDescriptionKey Parameters
set-entity-propertySets any custom TMX or built-in property on an entity by ID or name.id (integer) or name (string), property (string, required), value (string/number/bool, required).
configure-propConfigures prop-specific attributes.id (integer) or name (string), spritesheetName (string), material (valid: WOOD, STONE, STEEL, PLASTIC, CERAMIC, FLESH, FOLIAGE, UNDEFINED), addShadow (bool).
configure-creatureConfigures creature-specific attributes.id (integer) or name (string), spritesheetName (string), scaleSprite (bool).
configure-triggerConfigures trigger-specific attributes.id (integer) or name (string), message (string), activation (string), targets (string), cooldown (int), oneTime (bool).
configure-lightConfigures light source attributes.id (integer) or name (string), color (hex string), intensity (int), shape (string), active (bool).
configure-collisionConfigures collision box physics attributes.id (integer) or name (string), collision (bool), collisionType (STATIC/DYNAMIC), collisionboxWidth (float), collisionboxHeight (float).
move-entityMoves entity to absolute coordinates or by relative delta offsets.id (integer) or name (string), x (number), y (number), dx (number), dy (number).
resize-entityResizes entity width and height dimensions.id (integer) or name (string), width (number, required), height (number, required).
remove-entityDeletes an entity from the active map by ID or name.id (integer) or name (string).
get-entity-infoReturns complete transform, type, and custom property key-value map for an entity.id (integer) or name (string).

3. Map & Layer Control

Tool NameDescriptionKey Parameters
create-mapCreates a new map with dimensions, tile size, tilesets, initial layers, and overwrite option. Tilesets must be attached here in GID order before the map can be painted.name (string), width (int), height (int), tileWidth (int), tileHeight (int), tilesets (array), initialLayers (array), overwrite (bool).
select-mapSwitches the active editor view and environment to the target map.name (string, required).
delete-mapRemoves a map from the project file.name (string, required).
save-projectSaves all map and asset changes to the .litidata project file.None
load-projectOpens a project .litidata file into the editor.path (string, required).
get-layersLists all tile and object layers on the active map.None
add-layerAdds a new tile or object layer to the map.name (string, required), type (tile/object).
remove-layerDeletes a layer by name.name (string, required).
set-tileSets single tile GID cell coordinate on a tile layer.layer (string), x (int), y (int), gid (int).
fill-tilesFills a rectangular tile grid region with a tile GID.layer (string), x (int), y (int), width (int), height (int), gid (int).
list-terrainsLists Wang terrain sets, terrain names, local tile assignments, and painting guidance for a project tileset.tileset (string, required).
paint-terrainPaints a named Wang terrain, resolving neighboring transitions automatically. The referenced tileset must already be attached to the active map.tileset, set, terrain, layer (strings, required), plus cells, regions, or x, y, width, height.

Tileset attachment rule: create-map is currently the API operation that attaches project tilesets to a map. Include existing project tileset names in its tilesets array (for example, ["tiles-hospital"]) and create at least one tile layer before calling paint-terrain. An existing map with tilesets: [] cannot be terrain-painted until tileset attachment is added through the editor or a future map-attachment API.

Level A: High-Level Semantic Level-Design API

Level A tools provide stateless, batch-capable map operations with optimistic revision control.

1. Context & Inspection

Tool NameDescriptionKey Parameters
get_project_contextReturns complete project state: map list, tile sizes, tilesets, blueprints, valid materials list, and categorized spritesheets catalog (props, creatures).None
get_mapRetrieves detailed map structure, dimensions, layer list, and revision lock.mapId (string, required).
query_regionSpatial bounding-box query returning entities, tile GIDs, and collision bounds in region (x, y, w, h).mapId (string, required), x, y, width, height.
search_entitiesSemantic entity search by query string, type, layer, or tag.mapId (string, required), query (string).
render_tilesetRenders a project tileset atlas with grid lines and enlarged local tile IDs. Returns JSON metadata/base64 plus native MCP image content.tileset (string, required), scale (int, default 4).
find_tile_usageFinds a tileset’s use across maps and reports directional neighbor frequencies for tile-family inference.tileset (string, required), mapId, tileId.
render_tile_contextRenders a local tile neighborhood as a selected layer, composited layers, or a layer-stack contact sheet. Returns native MCP image content.mapId, layer, x, y, radius, mode, scale.
preview_tile_editsRenders transient candidate tile edits without persisting them, reporting affected bounds, collision-bearing tiles, and warnings. Returns native MCP image content.mapId, layer, edits, padding, scale.

2. Batch Entity & Tile Mutations

Tool NameDescriptionKey Parameters
create_entitiesBatch creates entities with explicit properties and prop collision auto-setup.mapId (string), entities (array), expectedRevision (int).
update_entitiesBatch updates entity transforms and properties.mapId (string), updates (array), expectedRevision (int).
edit_tilesSparse tile GID placement on a tile layer.mapId (string), layer (string), tiles (array of {x, y, gid}).
fill_regionFills rectangular region with tile GID.mapId (string), layer (string), x, y, width, height, gid.
set_ambient_lightSets map-wide ambient light hex color and alpha opacity intensity.mapId (string), color (hex string), alpha (0-255).
scatter_floor_detailsScatters detail tiles (blood stains, rust, grime) across floor region.mapId (string), layer (string), x, y, width, height, gids (array), density (float).

3. Rendering & Diagnostics

Tool NameDescriptionKey Parameters
render_mapRenders complete map canvas and returns Base64 PNG image string.mapId (string, required).
render_regionRenders bounding-box region PNG for visual audit.mapId (string), x, y, width, height.
analyze_mapRuns automated validation checks (duplicate IDs, unlinked targets, missing assets).mapId (string, required).
analyze_collisionAnalyzes collision layer geometry to detect isolated/inaccessible areas.mapId (string, required).
analyze_playabilityValidates player-footprint-aware collision, spawn, and required-target reachability. FAIL contains hard gameplay failures.mapId, actorProfile (width, height, optional clearance), requiredTargets.
get_navigation_graphReturns computed navigation connectivity and required-target reachability using the supplied actor footprint.mapId, actorProfile, requiredTargets.
render_playabilityRenders collision in magenta, reachable cells in green, and unreachable cells in red. Returns native MCP image content.mapId, actorProfile, requiredTargets.

Scene Composition Examples (Godot Parity)

Example 1: Direct Raw Node Placement (Level B)

// 1. Create Prop
{"tool": "add-prop", "arguments": {"name": "hospital_bed_1", "spritesheetName": "prop-bed3-intact", "material": "STEEL", "x": 128, "y": 64, "width": 32, "height": 32}}

// 2. Set Custom Property
{"tool": "set-entity-property", "arguments": {"name": "hospital_bed_1", "property": "searchable", "value": "true"}}

// 3. Add Light Source
{"tool": "add-light", "arguments": {"name": "room_light", "color": "#ffaa44", "intensity": 180, "shape": "CIRCLE", "x": 128, "y": 64, "width": 64, "height": 64}}

// 4. Save Project
{"tool": "save-project"}

Example 2: High-Level Semantic Room Authoring (Level A)

// 1. Set Atmospheric Ambient Light
{"tool": "set_ambient_light", "arguments": {"mapId": "triage_room", "color": "#3c0029", "alpha": 200}}

// 2. Batch Place Props & Creatures
{"tool": "create_entities", "arguments": {
  "mapId": "triage_room",
  "entities": [
    {"type": "PROP", "name": "bed1", "spritesheetName": "bed3", "material": "STEEL", "x": 64, "y": 64, "width": 32, "height": 32, "collision": true},
    {"type": "CREATURE", "name": "zombie1", "spritesheetName": "zombie-doctor", "x": 96, "y": 64, "width": 16, "height": 16}
  ]
}}

// 3. Scatter Blood Stains
{"tool": "scatter_floor_details", "arguments": {"mapId": "triage_room", "layer": "details", "x": 4, "y": 4, "width": 10, "height": 10, "gids": [140, 141, 142], "density": 0.25}}

steffen-wilkeLast updated 1 week ago

Feedback / Collaborate



Edit on GitHub


Give feedback
On this page