OpenSimulator Internals/Architecture Overview

Overview

OpenSimulator is a virtual world server. It implements the Linden Lab Second Life protocol, allowing Second Life viewers and compatible clients to connect to independently operated grids.

The architecture separates grid-wide services from per-region simulation. This allows a single grid to scale across multiple machines while keeping region simulation contained and independent.

Two Processes

Process	Role	Default Ports
ROBUST.exe	Grid-wide services: accounts, inventory, assets, presence, region map	8002 (login), 8003 (services)
OpenSim.exe	Region simulation: avatars, objects, physics, scripting, terrain	9000+ (one per region)

In standalone mode both are combined into a single OpenSim.exe process. The connector layer abstracts this -- calling code is identical either way.

Multiple OpenSim.exe instances connect to a single ROBUST instance. Each OpenSim.exe can host one or more regions.

Services

ROBUST provides grid-wide services over HTTP. Each service is a separate plugin registered on startup from [ServiceList] in Robust.ini.

Services fall into two categories:

Must run in a single instance -- these maintain shared state and would give conflicting answers if load-balanced:

PresenceService -- who is online, which region, current session
UserAgentService -- HyperGrid travel management
AgentPreferencesService -- per-user preferences
GridUserService -- home region, last login location

Can be load-balanced -- stateless, safe to run on multiple machines behind a load balancer:

AssetService -- asset blob storage
InventoryService -- user inventory
GridService -- region map
UserAccountService -- user accounts
AuthenticationService -- login authentication
GroupsService -- groups

See OpenSimulator Internals/ROBUST Services for full details.

Database Split

Database	Owner	Contains
Grid database (e.g. osimdev_robust)	ROBUST	User accounts, inventory, assets, presence, region map, friends, groups
Region database (e.g. osimdev_t1)	OpenSim.exe (per region)	Parcels, objects, terrain, estate settings

Both databases typically live on the same MariaDB/MySQL instance but are kept separate. ROBUST never touches region databases. Simulators connect to ROBUST services over HTTP for grid data, and to their own region database directly for local data.

Connector Pattern

Every service call from simulator code goes through a connector. The connector abstracts whether the service is local (standalone) or remote (grid mode).

Simulator code
  -> Connector (OpenSim/Region/CoreModules/ServiceConnectorsOut)
     -> [standalone] Service implementation directly in-process
     -> [grid mode]  HTTP call to ROBUST
                       -> Handler (OpenSim/Server/Handlers)
                          -> Service implementation

The connector interface is identical in both cases. See OpenSimulator Internals/Connector Architecture for details.

Region Simulation

Each region runs as a Scene instance inside OpenSim.exe. A single OpenSim.exe can host multiple regions.

The Scene holds:

All in-world objects (SceneObjectGroups)
All avatars (ScenePresences)
Physics engine reference
Script engine reference
All service connector references (Scene.AssetService, Scene.GridService, etc.)

Regions are identified by a UUID and by their grid coordinates (X, Y in region units). Varregions occupy multiple coordinate units -- a 512x512 region occupies 2x2 units.

HyperGrid

HyperGrid allows avatars to teleport between independently operated grids. It overlays the normal service architecture:

The Gatekeeper service on each grid acts as the entry point for incoming HyperGrid teleports
UserAgentService tracks the avatar's home grid and current location across grids
Asset and inventory transfers between grids use HyperGrid-aware connector variants
HyperGrid links to remote regions are stored in the local GridService database with a Hyperlink flag

HyperGrid is optional. A grid can operate without it.

Region Crossing and Teleport

Avatar movement between regions is handled by the SimulationService. When an avatar crosses a region boundary or teleports:

Source region contacts the destination region's SimulationService
Destination creates an agent entry
Avatar state (position, attachments, appearance) is transferred
Source removes the local agent

For HyperGrid teleports the Gatekeeper service mediates the handoff between grids.

Region crossing at shared borders between adjacent regions on the same grid uses the same mechanism but is optimised for low latency. This is the area most sensitive to region placement and simulator load.

Startup

See OpenSimulator Internals/Reading the Code for the startup sequence of both ROBUST.exe and OpenSim.exe.