WorldBridge: the control API

WorldBridge (worldbridge/WorldBridgeModule.cs, with Hub.cs, Roam.cs and RoamNotecard.cs) is a non-shared OpenSimulator region module that opens an HTTP control channel into the live regions of its simulator. Everything in tools/ goes through it, via tools/wb.py.

The channel

• Binds 127.0.0.1 only. A non-loopback BindAddress is logged as a warning and forced back to loopback.
• Default port 9002. Config lives in [WorldBridge] in OpenSim.ini: Enabled, BindAddress, Port, MaxBodyBytes (default 65536), TokenFile, AllowConsole, FileRoots, and optionally AuthToken and the role tokens TokenObserver, TokenBuilder, TokenGaia (written by make_config.py from the .env keys WORLDBRIDGE_OBSERVER_TOKEN, _BUILDER_TOKEN, _GAIA_TOKEN when set). config.md has every key and its default.
• Every request is POST /<command> with a JSON body and Authorization: Bearer <token>.
• There is no built-in token. With no valid AuthToken, WorldBridge reads the gaia token from TokenFile (WorldBridge.token beside OpenSim), and on the first start generates a random one there. A token shorter than 16 characters, or the retired demo value paracosm-worldbridge-token, is refused. tools/wb.py and the MCP server read the file through WORLDBRIDGE_TOKEN_FILE.
• Status codes: 405 for a non-POST, 401 for a missing or unknown token, 403 when the token's role is too low (the body names the role needed and the role held), 403 for a file outside FileRoots or for console while AllowConsole is false, 413 for a body over MaxBodyBytes, 404 for an unknown command, 400 for invalid JSON or missing required fields, 409 when rez_item names a no-copy item, 429 when a token is over its rate limit (see worldbridge/HARDENING.md), 404 unknown region (listing the regions) for a region the simulator does not run, 503 with Retry-After when the request queue is full or the region is shutting down (below; nothing ran, so it is safe to send again), 500 with a detail when the scene throws.
• "The" avatar. An op that acts on an avatar (teleport, sit, stand, wear, unwear, worn, give_*, grant_estate_manager, local chat_send) uses the one visitor present when none is named. With several visitors and no avatar, or a name fragment matching several, it answers 400 "several visitors present: name the avatar" (listing them) instead of picking one. A uuid or an exact full name always resolves.
• HttpListener answers 411 to a POST with no Content-Length: send a body (even {}) on every call, including state. (tools/wb.py always does.)
• Roles. observer may call state, list, heightmap, avatars, chat, inspect, worn, contents, roam_notecard. builder adds spawn, recolor, rez_item and put_notecard. Every other command needs gaia. The token file's token (or AuthToken) is always a gaia token. Give an assistant the lowest role it needs.
• Every command is appended to WorldBridge.audit.log beside the binaries (UTC time, remote endpoint, role, tok: + the first 6 hex of SHA-256 of the token used, command, region, body truncated at 4000 characters, password values masked). It rotates at 16 MB, keeping one previous file.
• Large inputs are file paths, not bodies. Meshes, textures, sounds and animations are passed as a path the OpenSim process reads from its own disk, and the path must lie inside one of the FileRoots folders (default worldbridge-files beside OpenSim). Only LSL text travels in the body, so a script over the body limit gets a 413.
• Positions are clamped to the region's real size, so the same calls work on a 512 or 768 var region (worldbridge/VAR-REGIONS.md). The clamp keeps a position strictly inside (up to size - 0.01 m): a position ON the border would cross into a neighbouring region when there is one.

Several regions

One simulator can run several regions (one Regions.ini section each; config.md says how to add one). OpenSim makes one WorldBridge instance per region, and they share ONE listener on the one port (worldbridge/Hub.cs): the first region to finish loading opens it, and it closes when the last region is removed.

• Naming the region. ?region=<name or uuid> in the URL, or "region": "<name or uuid>" (a string) in the JSON body; the URL wins when both are given. Names match case-insensitively. With neither, the request goes to the DEFAULT region: the first one loaded (the first section of Regions.ini). A region the simulator does not run gets 404 {"error": "unknown region", "region": ..., "regions": [names]}. A boolean "region" is not a name: it is chat_send's region-wide flag, and keeps that meaning.
• Every command acts in its region: objects, avatars, terrain, the sky, chat heard, NPCs, the favor ledger. An object in another region is 404 no such object. Var regions are per region: a 512 region beside a 256 one clamps and defaults to its own size.
• state answers for its region, and lists every region: regions [{name, uuid, sizeX, sizeY, location {x,y} (grid cells), isDefault, stateFiles}].
• State files are per region. The default region keeps today's names (worldbridge-roam.json, ...); every other region has its own, the region's name inserted before .json (worldbridge-roam.GiftTest2.json, with any character other than a letter, digit, - or _ made _). So a house that adds a region keeps all it had, as long as the new section goes AFTER the existing one; put a new region first and it takes over the unsuffixed files. Which region is the default is fixed for the life of the process (a region restarted alone keeps its files).
• The audit log's region column names the region each command ran in.
• wb.py takes a body region=... per call, or WORLDBRIDGE_REGION for every call that names none; the MCP tools take a region argument (below).
• Not yet: lookups ACROSS regions (an object or avatar is found only in the region named), region-global coordinates, and moves or roams that cross a border on purpose (worldbridge/TODO.md).

The request queue

Every request is admitted by one accept thread (method, token, rate limit, role, body size, region) and then waits in one of two bounded lanes, each served by a small fixed pool of worker threads (worldbridge/Hub.cs):

• The reads have their own lane so a poller stays quick while a builder is busy: measured on a scratch server, state answered in a median 39 ms (max 165 ms) while 68 spawn_mesh calls queued for up to 10 s in the work lane.
• A lane that is full answers at once: 503 {"error": "busy", "command", "lane", "queued", "queueLimit", "workers", "retryAfterSec"} with a Retry-After header (whole seconds, at least 1). retryAfterSec estimates how long the lane ahead takes to drain. Nothing ran, and the rate-limit charge is given back. tools/wb.py waits and resends, as it does for a 429 (up to 10 tries, the wait spread by a random factor so a burst does not return together).
• A request that waited longer than QueueWaitSec (20 s) is answered 503 "waited too long" instead of run: its caller has probably given up, and a spawn run then would be one nobody saw succeed.
• Commands in the work lane run up to MaxConcurrent at once, by default ONE: world-changing commands still run one at a time, as they always did, while reads get their own lane and a burst queues instead of piling up. The scene tolerates more (the viewers' own threads act on it concurrently) and WorldBridge's own state is locked per piece, but only spawn, spawn_mesh and list were load-tested side by side, so raise it after testing your workload.
• The audit line is written when a command RUNS, with its region; a request refused with 401, 403, 404 unknown region, 413, 429 or 503 is not audited.
• Shutdown: a region that starts closing (the start of Scene.Close, before its last backup) stops taking requests (one still queued for it gets 503 "region shutting down") and waits up to 10 s for those running in it; the other regions go on being served. When the last region goes, the channel closes: queued requests get 503 "shutting down", running ones finish (up to 15 s), then the listener stops. A console shutdown sent through WorldBridge runs the shutdown on its own worker thread and is the one request not waited for (it gets no answer: the process exits).
• state reports the queue: queue {workers, queueLimit, running, queued, readWorkers, readQueueLimit, readRunning, readQueued, queueWaitSec, served, rejected}.

tools/wb.py:

from wb import wb, region_say
wb("state")
wb("spawn", x=128.0, y=128.0, z=25.0, shape="box", sx=1, sy=1, sz=1, r=1, g=0, b=0)
wb("set_script", uuid=u, name="flicker", script=lsl)   # raises ScriptCompileError on a compile failure
region_say(-40777, "on")                                 # talk to scripts' llListen (see scripts.md)
wb("list", region="Isle2")                               # a simulator with several regions: name one
region_say(-40777, "on", region="Isle2")

CLI: python tools/wb.py <command> key=value ... (values are parsed as JSON when they can be).

Endpoints

Positions are region metres. Colours and alpha are 0..1. "uuid" is an object (scene object group) id.

Reading the world (observer)

Two more read-only commands need gaia:

Building (builder, then gaia)

The region (gaia)

Avatars, NPCs and chat (gaia)

Objects to people, groups (gaia)

Rigged creatures (gaia)

Behaviour worth knowing

• Everything WorldBridge creates is owned by the estate owner. That is why scripts it adds pass owner checks, and why region_say (chat_send with region=True, spoken as the estate owner) can talk to owner-filtered listeners.

• set_script, put_inventory, put_notecard, bundle, contents and rez_item act on the root prim. A multi-prim object's children are not reached.

• A box of gifts is a box of copies. bundle keeps copies of objects in a box, contents lists them, rez_item takes a copy back out anywhere in the region (the item stays, so one box serves again and again), and put_notecard leaves a note beside them.

• A creature that carries its own roam. Roam knows a creature by its uuid, and a copy out of a box has a new one. So an object that enters the scene holding a notecard named exactly roam in its root prim registers itself, as the roam op would (worldbridge/RoamNotecard.cs): on a rez from a box or from inventory, rez_item, a duplicate, an OAR load (OnObjectAddedToScene), and once at startup after the saved configs are re-armed (OnPrimsLoaded; during the load itself the event is ignored). The notecard is the roam body as JSON without uuid. Any animation value (walk_anim, flee_anim, drink_anim, pause_anim, pauses[].anim, down_anim/up_anim: any key anim or ending _anim) may be an asset uuid or the NAME of an animation in the root prim; cx, cy default to where the object stands and radius to 16. No water: no drink trips. wary_of and hunts name kinds, so a world without them never triggers them; a leader that is not here leaves it to go its own way. The resolved body is saved by uuid (with "source": "notecard"), so a restart re-arms that and never reads the notecard again; an object already registered keeps its config. A notecard that is not JSON, or names an animation the object does not hold, is logged as a warning and the object is not registered. Example:

  {"walk_anim": "walk", "pauses": [{"anim": "graze", "kind": "graze"}, {"anim": "idle", "kind": "idle"}],
   "speed": 0.75, "clear": 1.9, "max_slope": 0.6, "height": 3.1, "body_len": 3.0, "body_wid": 2.2,
   "leg_min": 10, "leg_max": 28, "pause_min": 25, "pause_max": 70, "kind": "elephant", "radius": 24}
  

  roam_notecard {uuid} writes that text from a live, tuned roamer.

• The wander and behaviour configs are re-armed on OnPrimsLoaded, not in RegionLoaded. Re-arming in RegionLoaded ran before the stored objects were in the scene, so every lookup missed and every config was pruned: the whole herd silently stopped on every restart.

• The module keeps its own state in small JSON files in the server's bin/ (the share group, the favor ledger, the sky baselines, the wander, behaviour and roam configs: worldbridge-share.json, worldbridge-favor.json, worldbridge-sky.json, worldbridge-wander.json, worldbridge-behavior.json, worldbridge-roam.json), one set per region: these names are the default region's, and any other region's carry its name (worldbridge-roam.<Region>.json, see "Several regions"). The first three are written to OpenSim's working directory, the rest beside the binaries; both are bin/ when OpenSim is started from there, as tools/run_server.py does. tools/backup.py copies them all (every worldbridge-*.json).

• set_script's superseded-asset check looks at every region of the simulator (they share one asset store): a task item in any region, and everyone in any region's favor ledger, keeps an old script asset.

The MCP server

mcp/worldbridge_mcp.py speaks MCP over stdio (newline-delimited JSON-RPC 2.0), uses only the Python standard library, and is configured by WORLDBRIDGE_URL and WORLDBRIDGE_TOKEN or WORLDBRIDGE_TOKEN_FILE (it reads the token once, at start), and optionally WORLDBRIDGE_REGION. Every world_* tool (world_call too) takes an optional region argument (name or uuid), sent as ?region=, so it never collides with a body field; without one the call goes to WORLDBRIDGE_REGION, else the simulator's default region. It exposes 26 tools:

Whichever token you give it determines what it can do; a builder token gets 403 on world_terrain. Setup: quickstart.md section 10.

Changing the module

build/build_server.py builds WorldBridge as part of the server. To rebuild only the module against an existing server: dotnet build worldbridge/WorldBridge.csproj -c Release -p:OpenSimBin=<bin>/ (net8.0; OpenSimBin defaults to ../opensim-src/bin/, the original checkout's layout), which writes worldbridge/bin/Release/WorldBridge.dll. Swap it into bin/ during a restart. See operations.md for the region-module attributes Mono.Addins requires and for a swap that does not race a supervisor. A quick way to confirm a new DLL is live: call a command only the new build knows; the old build answers 404, the new one 400 (missing fields).