Arenula

nyx000.github.io/arenula-mcp

MCP server suite for the s&box game engine. Connects AI coding assistants to the s&box editor — reading scenes, creating objects, compiling code, managing assets, and more.

Designed following Anthropic's MCP best practices: omnibus tools with action enums, rich descriptions with negative guidance, trimmed responses, actionable errors.

Arenula — Latin for "grain of sand". One grain in the sandbox.

Response envelope

Mutation tools return JSON with these fields:

• message — short human-readable confirmation.
• verified — (optional) read-back of state after the mutation, so callers can confirm the change actually stuck. E.g. after component.add: { "component_exists": true, "component_type": "ModelRenderer" }. After terrain.configure_clutter: { "clutter_assigned": "volcano_ground", "seed": 42, "mode": "Infinite" }. When this field is missing the caller should assume the mutation is unverified.
• warnings — (optional) array of per-field partial-success notes, each { field, message, suggestion? }. Used where the main operation succeeded but some sub-step was skipped — e.g. networking.add_helper with a mix of valid and invalid spawn-point IDs will return the helper wired up and a warning per bad ID.

Errors still return the standard { error, action, suggestion } body with isError: true. Any user-facing value that can't be resolved to a real engine resource now errors with an actionable suggestion rather than silently no-op'ing.

Servers

Server	What it does	Runtime	Transport
Editor	Scene manipulation, compilation, assets, terrain	C# plugin inside s&box	SSE :8098
API	Offline type/member reference (~1,800 types, ~15,000 members), PBR texture fetching	Node.js	stdio
Docs	Narrative docs from sbox.game (raw markdown via .md endpoints)	Node.js	stdio

Setup

1. Clone Arenula-MCP

Clone or download this repo somewhere on your machine. This is where the API and Docs servers will live — they don't need to be inside your s&box project.

C:\Projects\Arenula-MCP\       <-- can be anywhere you like
  editor/                      goes into your s&box project (step 2)
  api/                         stays here, runs from here
  docs/                        stays here, runs from here

2. Editor plugin

Copy editor/ into your s&box project's Libraries folder:

YourProject/
  Libraries/
    arenula_mcp/               <-- copy the contents of editor/ here
      Editor/
        Core/
        Handlers/
      sbox_mcp.sbproj

Open s&box — Arenula compiles automatically and starts the MCP server on port 8098.

3. Build API & Docs

From the Arenula-MCP root, install and build both Node.js servers:

npm run setup        # installs dependencies and builds both servers

This builds api/dist/index.js and docs/dist/index.js — those are the files your AI client will point to.

4. Configure your AI client

Add a .mcp.json file to your s&box project root (or copy .mcp.json.example). Update the paths to where you cloned Arenula-MCP:

{
  "mcpServers": {
    "editor": {
      "type": "sse",
      "url": "http://localhost:8098/sse"
    },
    "api": {
      "command": "node",
      "args": ["C:/Projects/Arenula-MCP/api/dist/index.js"],
      "env": {
        "SBOX_API_URL": "https://cdn.sbox.game/releases/..."
      }
    },
    "docs": {
      "command": "node",
      "args": ["C:/Projects/Arenula-MCP/docs/dist/index.js"]
    }
  }
}

Replace C:/Projects/Arenula-MCP with wherever you cloned the repo. Get the latest API schema URL from sbox.game/api/schema (click Download, copy URL).

Tools appear as mcp__editor__*, mcp__api__*, mcp__docs__* in your AI client.

Editor Tools

23 omnibus tools, 182 actions. Each tool takes a required action parameter.

Tool	Actions	Count
scene	summary, hierarchy, statistics, find, find_in_radius, get_details, prefab_instances	7
gameobject	create, destroy, duplicate, reparent, rename, enable, set_tags, set_transform, batch_transform	9
component	add, remove, set_property, set_enabled, get_properties, get_types, copy	7
compile	trigger, status, errors, generate_solution, wait	5
prefab	instantiate, get_structure, get_instances, break, update, create, save_overrides, revert, get_overrides	9
asset_query	browse, search, open, get_dependencies, get_model_info, get_material_properties, get_mesh_info, get_bounds, get_unsaved, get_status, get_json, get_references	12
asset_manage	create, delete, rename, move, save, reload, get_references	7
editor	select, get/set_selected, clear/frame_selection, get_play_state, start/stop_play, get_log, save_scene, save_scene_as, save_all, undo/redo, console_list, console_run, open_code_file, get/set_preferences	19
session	list, set_active, load_scene	3
lighting	create, configure, create_skybox, set_skybox	4
physics	add_collider, configure_collider, add_rigidbody, create_model_physics, create_character_controller, create_joint	6
audio	create, configure	2
effects	create, configure_particle, configure_post_processing, configure_sprite, configure_prop, configure_world_panel	6
camera	create, configure, capture_viewport, capture_tour, orbit_capture	5
mesh	create_block, create_plane, create_cylinder, create_wedge, create_arch, create_clutter, extrude_faces, remove_faces, add_face, clip_faces, scale_mesh, thicken_faces, bevel_edges, bevel_vertices, split_edges, quad_slice_faces, dissolve_edges, bridge_edges, connect_vertices, flip_faces, extend_edges, set_face_material, set_texture_params, vertex ops, get_info	27
navmesh	create_agent, create_area, create_link, generate, generate_tile, unload_tile, set_defer_generation, get_status, query_path	9
cloud	search, get_package, get_versions, mount	4
project	get_collision, set_collision_rule, get_input, get_info	4
terrain	create, configure, get_info, get_height, get_height_region, set_height, noise, erode, stamp, add/remove_material, get_material_at, blend_materials, set_hole, paint_material, import/export_heightmap, sync, configure_clutter, regenerate_clutter, clear_clutter	21
trace	ray, sphere_cast, box_cast, sample_grid, multi_ray	5
player	create, configure_movement, configure_camera, configure_body, configure_interaction	5
networking	add_helper, configure_object, get_status	3
schema	export, info, clear	3

Architecture

33 C# source files — 9 core infrastructure, 24 per-tool handlers (incl. ConsoleHandler).

Attribution

• Editor based on Ozmium MCP Server by ozmium7 (GPL-3.0)
• API based on sbox-api-mcp by sofianebel (MIT)
• Docs based on sbox-docs-mcp by sofianebel (MIT)

License

GPL-3.0 (Editor) · MIT (API, Docs)