Editing OpenSimulator Internals/Architecture Overview (section)

= 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 ==

{| class="wikitable"
! 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 ==

{| class="wikitable"
! 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.

----

== See Also ==

* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Data Dictionaries]]
* [[OpenSimulator Internals/GridService]]