Handbook: building a world with this OpenSimulator fork

This handbook is the distilled experience of building one standalone OpenSimulator region (a 256 x 256 m island with a cottage and mill, a climbable stone tower, a harbour, a grown woodland, birds, weather, seasons, rain, snow and thunder) almost entirely headless, by an AI assistant driving the region through the WorldBridge control API in this repo, with a human walking the result in a real viewer.

It is written for the next assistant (and its human) who builds a world with this fork, so that you start from what was already learned instead of rediscovering it. Almost every lesson below cost at least one visible failure in the real viewer. Each lesson states the rule, the failure that taught it (when the build logs record one), and the file or tool in this repo that embodies it.

Nothing here is speculative. Where the sources in this repo disagree with each other, the disagreement is listed in handbook/CONFLICTS.md instead of being resolved silently.

First principles

These recur in every chapter. If you remember nothing else, remember these.

1. Look through the real viewer early, and again after every deploy that matters. Every headless proxy in this project (software skinning, numeric round-trips, OpenSim's own asset decoder, offline renders) verified only that the encoder agreed with itself. The viewer then found what they could not: a whole herd of rigged animals rendered as collapsed sheets while every check passed at 0.000004; one night of "all offline renders pass" still produced five viewer-only faults (a tower's walls invisible, bird wings shredded to specks, reeds through a jetty, a woodpile on a block, vegetables tinted white). Anything the viewer interprets (a mesh asset, a skin block, an .anim, a texture, a sound mix) is proven only in the viewer. See verification.md.

2. When a foreign format fights you, make the real tool emit a known-good specimen and decode it. Reasoning about the SL mesh format cost weeks. Uploading one asset through the viewer's own uploader, pulling it out of Asset.db and diffing it against this repo's encoder found the missing TexCoord0Domain key in one pass, and later the exact skin-block convention. tools/cmp_mesh_struct.py and tools/decode_llmesh.py are the decoders; assets/firestorm-ref-skin.json is the decoded rigged reference.

3. A bench or checker only catches what it does not share with the thing it checks. The animesh bench used the same hand-written bone-parent table as the encoder, so a wrong parent passed at 0.00002 m while the viewer was 1.56 m out. Take the foreign system's structure (hierarchies, joint lists, conventions) from that system's own files, in both the encoder and the bench: tools/sl_skeleton.py reads the viewer's own avatar_skeleton.xml (vendored as tools/avatar_skeleton.xml). Any table written from memory is a hypothesis.

4. Prove a new path on the smallest possible object first. The UV bug was found on a 24-vertex box, not on the elephant. The rigging fix was proven on a 4 x 2 x 1 box folding on two bones (tools/make_bend_box.py) before any creature was rebuilt. A first sit pose was made diagnostic (one unmistakable joint) before a library of poses was built on it.

5. Make every change readable back, and read the real verdict, not the proxy's. set_script answers started=True even when the script failed to compile; OpenSim's own mesh decoder accepts assets the viewer rejects. Design each change so it has an observable channel (inspect colour and material, list position/size/description, the region log), and find where the real verdict is written (the YEngine lines in OpenSim.log, the viewer's own log).

6. Never derive a base value from a live read that may already be disturbed; keep recorded originals. A growth script that took its base size from a prim disturbed by testing compounded the error; a wet-stone script restarted in the rain would have darkened already-wet stone; a regrower that read its own grown output swelled the object every run; a terrace rebuild that read the cut terrain took its own cut for the hill; a sky blend that re-captured its baseline after a storm would compound the storm. Record the design values once (a JSON beside the builder, the builder's source constants) and rebuild from those.

What is in this repo

Before you run anything

• Start with quickstart.md. The server scripts (build/build_server.py, tools/make_config.py, tools/run_server.py, tools/backup.py, tools/wb.py) take their paths, accounts and tokens from .env.
• There is no built-in WorldBridge token. On its first start WorldBridge writes a random token to WorldBridge.token beside OpenSim; tools/wb.py and the MCP server read it through WORLDBRIDGE_TOKEN_FILE. The old demo token paracosm-worldbridge-token is refused. The early scripts in scenes/ and viewer/render_world.py still send it and will get 401.
• Repo paths come from one helper. The Python tools, scenes and viewer scripts take the repo root, assets/ and OpenSim's bin/ from tools/paths.py (PARACOSM_ROOT, PARACOSM_BIN; unset, the repo the tools sit in), so none of them spells out the original checkout C:/CLD/paracosm any more. The host-specific paths left (the Firestorm tree C:/fs, two sibling repos, a one-off C# test, Windows fonts) are listed in tools/PORTABILITY.md section 4.
• assets/ is not versioned except assets/firestorm-ref-skin.json and assets/boulders/originals.json. Builders write their meshes, textures and state files there; many builders expect an earlier builder to have run (for example tools/terrain_now.py reads assets/terrain_data.json, written by the terrain generator).
• WorldBridge reads files from its own disk. spawn_mesh, upload_texture, upload_sound and store_anim take a file PATH that the OpenSim process opens, so the tools and the region must share a filesystem.
• tools/make_paracosm_terrain.js depends on an external terrain-simulation library that is not in this repo. The rest of the terrain pipeline (a RAW32 heightmap loaded with the console terrain load) does not.

Chapters

Setting up and running a world:

Building a world: