region-simulator-core summary

← Back to docs · Architecture · Decisions · Previous: Grid portal · Next: Prim meshing

Status: accepted (Phase 3). All 7 task groups in openspec/changes/region-simulator-core/tasks.md are checked. Commits 759e3c6 through 129d401. Second review verdict: CONDITIONAL PASS.

What was built

The region simulator: scene graph, LLUDP client stack, HTTP capabilities, terrain, persistence and the welkin-region binary. It hosts one or more regions per process, accepts viewer connections, serves terrain and objects, and saves state to a C#-compatible region database.

Not included (later phases): land/parcels, permissions, chat, IM, estate management, archiver, scripting hooks, other CoreModules.

Architecture

viewer --UDP--> welkin-net (server, client, dispatch, handlers)
viewer --HTTP-> welkin-caps (seed cap, event queue, cap handlers)
                    |
                    v
             welkin-scene (Scene -> groups -> parts, presences, terrain)
                    |                    |
                    v                    v
         welkin-physics (trait)   welkin-data (SimulationDataStore, sqlx)
                    ^
         welkin-region (binary: config, regions, listeners, shutdown)
  • One Scene per region. RegionManager runs several in one process.
  • LLUDP dispatch is a table keyed on message id, calling typed handler functions. Wire codecs come from welkin-msg.
  • Persistence stores objects as XML2 and uses the existing regionstore tables, so a C#-created database loads without migration. persist.rs (f94dacd) wires backup_dirty_objects into the heartbeat loop (every 60 ticks, about 3 seconds) and flushes all dirty objects on graceful shutdown. The conversion maps 85 prim fields and 30 shape fields from SceneObjectPart to the database row types.

Key modules

CrateModuleRole
welkin-scenescene.rsRegion heartbeat, entity maps, update dispatch, spatial queries (position, owner, name), dirty tracking and periodic backup
group.rsSceneObjectGroup: linked prim set, root part, link/unlink, bounding box
part.rsSceneObjectPart: shape, texture entry, extra params, properties, flags, inventory stub
presence.rsScenePresence: position, rotation, velocity, controls, animation, sit, appearance
xml2.rsXML2 object serializer and parser, interchange format shared with C#
terrain.rsHeightfield channel, variable region size, patch dirty tracking
terrain_io.rsLLRAW, RAW32 and PNG import/export
terrain_brush.rsRaise, lower, flatten, smooth, noise, revert
terrain_compress.rsLayerData patch compression for the viewer
region_manager.rs, shutdown.rsMulti-region host, graceful persist/deregister/close
welkin-netserver.rsUDP listener, accept, per-client routing
client.rsPer-viewer state: acks, resend queue, sequence numbers, lifecycle
dispatch.rsHandler table keyed on message id
handlers.rsViewer handlers (UseCircuitCode, CompleteAgentMovement, AgentUpdate, object and avatar messages)
circuit.rs, throttle.rsPhase 1 circuit and throttle, reused
welkin-capsserver.rsPer-session seed cap and cap URL dispatch via axum
event_queue.rsLLSD long-poll event queue, enqueue and poll/ack cycle
handlers.rsTexture/mesh fetch, region info, agent preferences, upload caps
welkin-datasimulation.rsSimulationDataStore trait and sqlx implementation (objects, terrain, region settings, spawn points)
welkin-regionmain.rsConfig, database init, scenes, LLUDP and caps startup, grid registration, shutdown

Tests

Counted from #[test] and #[tokio::test] attributes:

CrateUnit and inlineIntegration files
welkin-scene137scene_proof.rs, xml2_proof.rs
welkin-net30lludp_roundtrip.rs (conformance)
welkin-caps16none
welkin-data18simulation_roundtrip.rs, csharp_compat.rs
welkin-region11acceptance.rs

Totals shown include integration test files under each crate's tests/ directory where present. Proof coverage: scene graph operations, XML2 round-trip against C#-serialized objects, loading a C# region database and checking object positions, and an end-to-end acceptance run (connect, terrain, rezzed object, avatar movement).

Security review

Independent second review of persistence and client stack protocol handling. Verdict: CONDITIONAL PASS. Three HIGH findings in the network stack must be fixed before production use:

  1. Bounded client map: the per-server client table has no size cap, so a flood of circuit codes can exhaust memory.
  2. Bounded mpsc: channels between the receive loop and clients are unbounded, so a slow client can grow queues without limit.
  3. Stale session reaping: sessions that stop responding are not removed on a timer.

Until these land the region binary is not for public exposure; restrict it by network. Persistence code had no HIGH findings.

Known gaps

  • The three HIGH findings above are open.
  • Cap handlers beyond the seed cap and event queue are thin; texture and mesh fetch and upload caps need real asset-service wiring.
  • Avatar and object handlers cover the core viewer flow; permission checks are now enforced on 14 object mutation handlers (69f0db4). Land and chat are absent by scope.
  • Capacity assessor benchmark/model/live modules are still stubs; they can now be built on this simulator (see decision C1).
  • Test counts for welkin-net and welkin-caps are modest relative to the protocol surface; fuzzing of the new handlers is not yet set up.