WorldBridge on OpenSimulator var regions

WorldBridge now works on OpenSimulator var regions (the modern "mega regions": one Scene that is 512 x 512 = 2x2, 768 x 768 = 3x3, and so on), not only the classic 256 x 256. Every region-coordinate default and clamp reads the bound Scene's real size (m_scene.RegionInfo.RegionSizeX / RegionSizeY). Heightmap indexing uses the heightmap's own Width / Height. A 256 region behaves exactly as before. The one visible difference there is two new response fields: state gains sizeX/sizeY, and heightmap gains samplesX/samplesY.

Facts about var regions in this OpenSim (from OpenSim/Framework/RegionInfo.cs, DoRegionSizeSanityChecks): each side is a multiple of 256, up to Constants.MaximumRegionSize = 4096, and the region is forced square because of viewer limits. So RegionSizeX == RegionSizeY in practice. The code still reads both, in case a future OpenSim lifts that rule.

Helpers added

WorldBridgeModule.cs:1001-1004: RegionSizeX, RegionSizeY (float metres, falling back to Constants.RegionSize if no scene is bound yet), RegionMidX, RegionMidY (half of each; 128 on a 256 region). Roam.cs shares them through the partial class.

Every site changed

Line numbers are on branch ship/var-regions, with the old line on 2c9f690 in brackets.

Later (2026-09-27, multi-region, ship/p2-wb): the position clamps in rows 6-9 and rez_item stop at RegionMaxX/Y = size - 0.01 m instead of the size itself. OpenSim's region is [0, size): a position clamped to 256.0 sat on the border, and beside a neighbouring region an object moved there crossed into it (seen on a two-region test server). The roam range centre (row 11) still clamps to the size; it is a centre, not a position.

Build: dotnet build worldbridge/WorldBridge.csproj -c Release -p:OpenSimBin=C:/CLD/paracosm/opensim-src/bin/ gives 0 warnings, 0 errors. The -p:OpenSimBin= override is needed only in a worktree, which has no opensim-src/. It points the HintPaths at the live bin, read-only. The csproj is unchanged.

The heightmap op contract

Request body is optional: {} or { "grid": N }.

• N is the number of samples along the region's longer side. It defaults to 64 and is clamped to [8, 512]. Unparseable JSON is treated as {}, because the op ignored its body before and old callers must still work.
• There is one square step for both axes: step = ceil(max(width, height) / N) metres, and stepX == stepY == step.
• Samples are point samples: grid[row][col] = height(x = col*step, y = row*step) in metres, rounded to 0.01. The last column sits at x = width - step, not width - 1. That is unchanged from before.
• The response is { ok, width, height, stepX, stepY, samplesX, samplesY, grid }. width/height are the heightmap's size in metres, which equals the region's size. samplesX/samplesY are grid[0].length and grid.length.

Why this option: the default keeps the output shape stable (64 x 64) on every size, so existing renderers still get a grid they can draw. grid lets a client ask for enough resolution on a big region, where 12 m point samples alias small features like a jetty or a narrow sandbar. The 512 cap bounds a response to 262k numbers (about 2 MB of JSON). One square step was chosen over independent per-axis steps so that cells stay square even if a non-square region ever becomes legal. On today's forced-square regions the two choices are identical.

Walk-grid cost on a 768 region (roam)

The walk grid is N x N one-metre cells. N is the range window, capped by the heightmap to at most side - 3: 253 on 256, 509 on 512, 765 on 768. The things that fill it are:

• ordinary ranges: radius <= 180 by default use. N = 2R+4, so it does not depend on region size at all (R = 40 gives N = 84 on any region);
• big ranges: now allowed up to 540 m on a 768 region;
• water trips: the Trip grid spans the range plus the pool, with radius dist/2 + R + 8, and that radius was never clamped. On a 256 region the heightmap held this grid to 253^2; on a 768 region it can reach 765^2.

Measured on the live 256 region (OpenSim.log, 2026-09-27): a 157 x 157 grid builds in 0.3-0.7 s. That is about 30 us per cell for one downward physics ray and five bilinear ground reads. The worst case on a 768 region, N = 765 (585k cells), comes to:

• held: 9 B/cell (Blocked + ClearDist + Slope), about 5.3 MB per grid;
• build: about 585k rays, roughly 15-20 s on its own background thread (WorldBridge-walkgrid). Each ubODE ray is queued to the physics step, so a build competes with other raycasts, but it never blocks the 1 Hz tick;
• per journey planned on it: dist/len/prev are 12 B/cell, about 7 MB allocated, twice if the scramble (relax) pass runs. A full N^2 scan picks the goal. The Dijkstra flood itself stays bounded by LegMax * 1.8. Trip plans happen once per thirst cycle (900-1800 s by default), so this is occasional large-object-heap churn, not a steady load.

These costs are sane for 768. Past 1024 on a side, which only happens on a var region bigger than 4x4 (OpenSim allows up to 4096), a 4093^2 grid would be about 150 MB held and 200 MB per plan. MaxWalkGridSide = 1024 caps N, so the worst case anywhere is 1M cells: about 9.4 MB held, 12.6 MB per plan, and about 30 s to build. Cells outside a cropped grid are simply not walkable, because Usable's g.In() check rejects them. A water trip longer than about 1 km on such a region will fail to plan and retry a minute later. It will not hang or throw.

Region-size-dependent things left alone, and why

• set_sit_target (:2272), x/y/z clamped to [-256, 256]: this is a sit offset in the prim's local frame, not a region coordinate. 256 m is far beyond any usable sit offset on any region size.
• scale_object (:2439), clamped to [0.01, 256]: this is the prim size limit, which matches OpenSim's NonPhysicalPrimMax default of 256. It is not the region footprint.
• z clamps of 4096 (teleport, move_object, npc_*): this is the region height (Constants.RegionHeight / RegionSizeZ), which var regions do not change.
• spawn, spawn_mesh, terrain (x, y, cx, cy clamped to [0, 10000]), wander cx/cy clamp, and raycast origin (+/-1e4): these were already wider than the largest var region (4096), so they are var-safe as they are. terrain, wander (ApplyWander) and roam's Ground() already index the heightmap by its own Width/Height.
• wander radius max 120 m: this is the size of a creature's loop, not a region bound. The legacy wander samples one height per waypoint (at most 64 steps), so a much larger loop would float over the terrain. roam is the tool for big ranges.
• roam journey sizes (leg_min/leg_max <= 250, flee <= 60, stalk 32 m, set-down search +/-15 cells): these are about the animal, not the region.
• raycast length max 1000 m: this is already four times a 256 region. A 768 region's diagonal is 1086 m, so a full corner-to-corner ray needs two casts. That was left as is.
• list stops at 5000 objects: a 768 region can hold nine times the prims of a 256 one. The cap is a response bound, not a size assumption, but a big built-up var region may hit it. count in the response shows when it did.
• Sky, water and wind (ApplySky, ApplyWater, WindNow): these are region environment settings with no spatial extent.
• One Scene per module: WorldBridge binds a single Scene (see TODO.md, multi-region). The sizes read are that Scene's. A var region is one Scene, so this is correct. Cross-region junctions (a 3x3 beside a 2x2) are a separate multi-region problem and are out of scope here.

Client-side 256 assumptions found in passing were not changed, because the scope here is the module:

• tools/terrain_restore.py:26 computes step = 256 // len(g) and iterates range(0,256,step). It should read stepX and width from the response.
• scenes/plant_grove.py has cx, cy = 128, 128.
• tools/wb.py documents "64x64".
• The MCP world_heightmap tool (mcp/worldbridge_mcp.py:62) has an empty input schema, so it cannot pass grid.
• scenes/plant_grove.py and viewer/render_world.py already use stepX/stepY and the grid's length, and are fine.

How to test on a 512 x 512 region

Region config (bin/Regions/Regions.ini, one section per region):

[Ocean512]
RegionUUID = <new uuid>
Location = 1000,1000          ; grid units of 256 m: this region covers 1000..1001 x 1000..1001
SizeX = 512                   ; multiple of 256; must equal SizeY (OpenSim forces square)
SizeY = 512
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9000
AllowAlternatePorts = False
ExternalHostName = SYSTEMIP

Neighbours of a var region must sit at least SizeX/256 grid units away. For a 3x3 the keys are SizeX = 768 and SizeY = 768. Do not confuse var regions with the old CombineContiguousRegions "megaregions", which are a different, retired mechanism. The console prints Region Ocean512 size set to <512,512> on start. Use a var-region-aware viewer.

Checks, in order (each one is a WorldBridge POST):

1. state returns sizeX: 512, sizeY: 512.
2. heightmap {} returns width 512, stepX 8, samplesX 64, samplesY 64. {"grid":256} gives step 2 and 256 samples. {"grid":512} gives step 1 and 512 samples. Compare a few samples to terrain save output.
3. teleport {"x":480,"y":480,"z":40} should land at (480,480), where it was clamped to 256 before. With no x/y it should land at (256,256).
4. move_object {"uuid":..., "x":500, "y":20}: the object should be at x 500. "x":600 clamps to 512 (the edge), so prefer 511 when testing.
5. npc_create {} should spawn at (256,256,30). Then npc_move {"npc":..., "x":450, "y":450} should walk there.
6. chat_send {"message":"hi"} with no avatar is spoken from (256,256,30). Stand within 20 m of the middle to hear it in local chat.
7. raycast {"land":true, "dx":0, "dz":-1, "length":60} should hit land under (256,256).
8. wander {"uuid":...} with no cx/cy should loop around (256,256).
9. roam with cx:400, cy:400, radius:100: the log should show roam walk grid (400,400) r100: 204x204 cells ... and the creature should walk there. Also try radius:300 (clamped to 180 before, accepted now), and a water pool across the region. Check that the logged trip grid is <= 509 x 509 and note the build time. It should be seconds, and the region's frame rate should hold while it builds.
10. create_account for a throwaway user: the GridUser HomePosition should be the default region's middle, which is (256,256,26) if that is the 512 region.
11. terrain {"cx":450,"cy":450,"radius":10,"amount":2} should report changed > 0. This op was already var-safe and is here as a regression check.

Run the 256-region regression too: heightmap {} is still 64 x 64 at step 4, teleport {} still goes to (128,128,30), and the live roamers' grid log lines keep the same sizes as before, for example (105,115) r76: 157x157.