Latest revision as of 13:55, 7 July 2026

OpenSimulator Internals/Code Map/Scene

Overview

Scene is the central object of the region simulator. One Scene instance exists per region. It holds all in-world state and coordinates between the physics engine, script engine, client connections, storage, and grid services.

Class hierarchy:

Scene → SceneBase → RegionApplicationBase

Source: OpenSim/Region/Framework/Scenes/Scene.cs

Scene.cs is a partial class -- additional methods are in other files in the same directory.

Constructor

Two constructors:

Scene(RegionInfo regInfo)  -- base constructor
Scene(RegionInfo, AgentCircuitManager, ISimulationDataService, IEstateDataService, IConfigSource, string version)  -- full constructor

Base constructor:

Creates SceneGraph (holds all entities and physics)
Hooks SceneGraph.UnRecoverableError -- triggers RestartNow() on physics crash
Sets defaults: PhysicalPrims=true, CollidablePrims=true, PhysicsEnabled=true, AllowAvatarCrossing=true, PeriodicBackup=true
Creates EventManager
Creates ScenePermissions

Full constructor (called from OpenSimBase.CreateScene()):

Loads RegionSettings from SimulationDataService -- sets default terrain textures if missing, copies classic textures to PBR slots if PBR not set
Loads EstateSettings from EstateDataService
Creates SceneGridInfo from config and ServerURI
Hooks EventManager land object events to SimulationDataService storage
Reads [Startup] config -- draw distances, prim limits, physics flags, script engine, persistence timings, frame rate, viewer allow/deny lists, coarse location update interval, terrain update interval, backup interval
Reads [EntityTransfer] config -- AllowAvatarCrossing, DisableObjectTransfer
Reads [InterestManagement] config -- update prioritization scheme, reprioritization settings, object culling by distance
Creates SimStatsReporter
Starts timer watchdog

Service References

All grid services are accessed through lazy-loaded properties backed by RequestModuleInterface<T>(). They throw if the service is not available (except EstateDataServiceSafe which returns null).

Property	Interface	Notes
AssetService	IAssetService	throws if missing
InventoryService	IInventoryService	throws if missing, with detailed error message about config
GridService	IGridService	throws if missing
SimulationDataService	ISimulationDataService	throws if missing
EstateDataService	IEstateDataService	throws if missing
UserAccountService	IUserAccountService	null if missing
PresenceService	IPresenceService	null if missing
AuthenticationService	IAuthenticationService	null if missing
AvatarService	IAvatarService	null if missing
GridUserService	IGridUserService	null if missing
AgentPreferencesService	IAgentPreferencesService	null if missing
AuthorizationService	IAuthorizationService	null if missing
LibraryService	ILibraryService	null if missing
SimulationService	ISimulationService	null if missing

Module references (set by SetModuleInterfaces() after modules load):

Property	Interface
EntityTransferModule	IEntityTransferModule -- teleport and region crossing
AttachmentsModule	IAttachmentsModule
AgentTransactionsModule	IAgentAssetTransactions
UserManagementModule	IUserManagement
AvatarFactory	IAvatarFactoryModule
CapsModule	ICapabilitiesModule

The Main Loop (Heartbeat)

The scene runs one thread: the Heartbeat thread. Started by Start():

Heartbeat()
  TriggerOnRegionStarted()
  Update(1)  -- first frame, watchdog not yet active
  Watchdog alarm enabled
  Update(-1)  -- runs until shutdown

Update() loop runs once per frame:

Per frame (every frame unless noted):

CheckTerrainUpdates() -- every 4 frames
UpdateTerrain() -- every m_update_terrain frames (default 1000)
UpdatePreparePhysics() -- physics pre-step
SendCoarseLocations() -- every 5 frames, async via thread pool
UpdatePhysics(FrameTime) -- main physics step, returns physicsFPS
CheckAtTargets() -- check llMoveToTarget / llRotLookAt
UpdateObjectGroups() -- send queued object updates to clients
UpdatePresences() -- send presence updates to clients
CleanTempObjects() -- every 180 frames, async
UpdateEvents() -- fires EventManager.OnFrame
UpdateStorageBackup() -- every 200 frames, async
Frame 20: enable logins, inform neighbours region is up, set Ready=true, GC compact

Frame timing: FrameTime defaults to 0.0908s (~11fps). Sleep is calculated to hit target frame time. Stats normalized to 55fps for viewer display.

Backup runs asynchronously every 200 frames. Objects are only persisted if they have been changed for at least MinimumTimeBeforePersistenceConsidered (default 60s) and no longer than MaximumTimeBeforePersistenceConsidered (default 600s).

Startup Sequence (called from OpenSimBase.CreateRegion)

After construction:

scene.SetModuleInterfaces() -- wires up module references from loaded region modules
loadAllLandObjectsFromStorage() -- loads parcels from region database
LoadPrimsFromStorage() -- loads all objects, calls AddRestoredSceneObject() for each
RegisterRegionWithGrid() -- calls GridService.RegisterRegion(), throws on failure
CreateScriptInstances() -- starts script engine for all loaded objects
scene.Start() -- starts Heartbeat thread

AllModulesLoaded() is called after all modules are loaded. Pushes simulator feature data to ISimulatorFeaturesModule (FPS, prim limits, grid info, search URL, etc).

Region Crossing and Teleport

All teleport and crossing logic is delegated to EntityTransferModule:

RequestTeleportLocation()  →  EntityTransferModule.Teleport()
CrossAgentToNewRegion()    →  EntityTransferModule.Cross()
TeleportClientHome()       →  EntityTransferModule.TeleportHome()

Incoming objects and attachments from crossings:

IncomingCreateObject()     →  EntityTransferModule.HandleIncomingSceneObject()
IncomingAttechments()      →  EntityTransferModule.HandleIncomingAttachments()

Note: IncomingAttechments() -- the typo is in the source. See WTF file.

OtherRegionUp() is called when a neighbouring region comes online. If within border distance, enables child agents in that region for all current root avatars via EntityTransferModule.EnableChildAgent().

Avatar Connection (NewUserConnection)

Called by the login service or another simulator to initiate a connection. Not triggered by the viewer directly.

Checks logins enabled
Checks viewer allow/deny lists
Handles existing ScenePresence (zombie root agents, race conditions during teleport)
Clamps start position within region bounds
CheckLandPositionAccess() -- checks telehub, parcel access, agent limit
VerifyUserPresence() -- checks PresenceService for active session
AuthorizeUser() -- checks estate ban, public access, access list, group membership
Sets up CAPS via CapsModule
ActivateCaps()

Connection is activated later when the viewer sends UseCircuitCodePacket UDP packet.

Avatar Removal (RemoveClient)

Sends shutdown notice to child agents if root
Avatar stands up if seated
Closes child agent connections on neighbouring regions (async)
Triggers ClientClosed and OnRemovePresence events
De-rezzes attachments (root only)
Sends KillObject to all clients
Removes agent transactions
Removes circuit, scene presence, client manager entry, CAPS

Shutdown (Close)

Deregisters from GridService
Kicks all root avatars with shutdown message
Sets m_shuttingDown = true
Sleeps 500ms to let kick messages reach clients
Closes all agents
Triggers SceneShuttingDown event
Backup(true) -- force persist all pending changes
Closes SceneGraph
Disposes PhysicsScene last (scripts may reference physics during shutdown)

Object Management

Key methods:

Method	Notes
AddNewPrim()	Creates a new prim via raycast. Checks permissions. Uses entity creator registry if available, else creates SceneObjectGroup directly. Applies user default permissions from AgentPreferencesService.
AddRestoredSceneObject()	Adds object loaded from storage. Delegates to SceneGraph.
AddNewSceneObject()	Adds newly created object. Delegates to SceneGraph. Triggers ObjectAddedToScene event.
DeleteSceneObject()	Removes scripts, keyframe motion, email listeners, physics actors. Unlinks from scene. Triggers ObjectBeingRemovedFromScene.
UnlinkSceneObject()	Removes record from scene without destroying. On hard delete, removes from database.
IncomingCreateObject()	Handles object arriving from region crossing. Delegates to EntityTransferModule.
ForceSceneObjectBackup()	Synchronous backup of a single object. Used for deletes and link/unlink.

Client Event Subscriptions

SubscribeToClientEvents() wires all viewer protocol events to scene handlers:

Terrain events (currently empty)
Prim events: position, rotation, scale, shape, texture, name, material, link/unlink, duplicate, permissions, grab, spin, undo/redo
Prim rez events: OnAddPrim → AddNewPrim(), OnRezObject → RezObject()
Inventory events: folder and item CRUD, task inventory, rez script
Teleport events: OnTeleportLocationRequest → RequestTeleportLocation()
Script events: reset, get/set running
Parcel events: return objects, set clean time, buy
Grid events: money transfer
Network events: stats update, viewer effect

Note: UnSubscribeToClientEvents() is defined but marked FIXME -- not called anywhere. See WTF file.

Health Monitoring

GetHealth() returns an integer 1-5:

Value	Meaning
0	Starting up
1	HTTP alive but heartbeat stopped -- possible lockup
2	Heartbeat running (frame tick < 4s ago)
3	One packet thread running
4	Both packet threads running
5	New user logged in within last 4 minutes

TimerWatchdog runs every second. Pushes health and root agent count to etcd if the IEtcdModule is present.

Persistence

Objects are persisted via EventManager.OnBackup → SimulationDataService. Objects qualify for persistence if:

HasGroupChanged = true
Time since last change > MinimumTimeBeforePersistenceConsidered (default 60s)
Time since last change < MaximumTimeBeforePersistenceConsidered (default 600s) OR forced=true

Auto-return queued in m_returns dictionary. Return messages sent via IMessageTransferModule on next backup cycle.

Notable Details

MegaRegions (CombineContiguousRegions) are explicitly rejected on startup with a fatal error
The restart console command is registered but disabled -- marked unreliable in source
IncomingAttechments() has a typo -- see WTF file for both file locations
GOTO is used in AuthorizeUser() for group access checks -- commented in source as "some say GOTO is ugly"
Heartbeat restart limit: if heartbeat thread dies and restarts more than 10 times, Environment.Exit(1)
GC.Collect() is called explicitly at frame 20 and on map tile regeneration
etcd integration is optional -- IEtcdModule only -- used for external health monitoring

OpenSimulator Internals/Code Map/Scene: Difference between revisions