OpenSimulator Internals/Code Map/OpenSim

Overview

OpenSim.exe is the region simulator process. It loads configuration, initialises the physics and script engines, loads region modules, connects to ROBUST services, and runs one or more regions.

In standalone mode, service implementations run in-process. In grid mode, service connectors make HTTP calls to ROBUST. The same code runs both ways -- only the config differs.

Class hierarchy:

OpenSim → OpenSimBase → RegionApplicationBase

Source repository: https://github.com/opensim/opensim

Entry Point

OpenSim/Region/Application/OpenSim.cs -- class OpenSim, StartupSpecific()

OpenSim.cs handles the interactive simulator layer:

Sets up console -- local, basic, rest, or GUI-driven based on config
Calls base.StartupSpecific() (see OpenSimBase below)
Registers HTTP handlers on MainServer.Instance:
- /simstatus -- returns "OK"
- /SHA1(osSecret) -- extended stats JSON
- /userStatsURI -- stats at user-configured path (optional)
- /robots.txt -- returns "# go away, Disallow: /"
- /index.php -- IndexPHPHandler for viewer login and capability discovery
Optional: registers managed stats endpoint
Hooks watchdog timeout handler
Prints startuplogo.txt if present
Selects default console region (root if multiple, the single region if only one)
Runs startup command script if configured
Starts timed script timer if configured

Console commands registered: force update, change region, save/load xml/xml2/oar, edit scale, rotate/scale/translate scene, kick user, show users/connections/circuits/pending-objects/modules/regions/ratings, backup, create region, restart (disabled), command-script, remove-region, delete-region, estate create/set owner/set name/link region.

Note: restart command is registered but disabled -- marked unreliable in the source.

Shutdown: runs shutdown command script if configured, disposes timed script timer, calls base.ShutdownSpecific().

OpenSimBase

OpenSim/Region/Application/OpenSimBase.cs -- class OpenSimBase

StartupSpecific() sequence:

Refuses to run if CombineContiguousRegions (MegaRegions) is set -- explicitly unsupported, fatal exit
Creates PID file if configured
Reads Stats_URI, SecurePermissionsLoading, permission modules, managed stats config from [Startup]
Loads SimulationDataStore plugin from [SimulationDataStore] -- throws if missing
Loads EstateDataStore plugin from [EstateDataStore] or [EstateService] -- throws if missing
Calls base.StartupSpecific() -- see RegionApplicationBase
Loads application plugins from /OpenSim/Startup extension point
Calls PostInitialise() on all plugins
Adds plugin commands to console

Initialize() sequence (called from base.StartUp()):

Starts WorkManager.JobEngine if enabled
Handles SSL cert creation or renewal if configured
Handles PEM to PKCS12 cert conversion if configured
Sets HTTP server port and SSL flag from [Network]
Hooks SceneManager.OnRestartSim
Enables MemoryWatchdog and Watchdog only when all regions are ready -- avoids false positives during startup

Region Creation

OpenSim/Region/Application/OpenSimBase.cs -- CreateRegion()

Called once per region on startup, and again on restart. Sequence:

Gets IRegionModulesController from ApplicationRegistry -- fatal exit if missing
Sets region ServerURI from ExternalHostName and HTTP port
Calls SetupScene() -- creates AgentCircuitManager and Scene instance (see Scene below)
Calls controller.AddRegionToModules(scene) -- loads all region modules
Verifies required permissions modules are loaded if SecurePermissionsLoading = true -- fatal exit if missing
Calls scene.SetModuleInterfaces() -- wires up module references
Calls SetUpEstateOwner() if estate has no owner -- prompts console interactively
Calls scene.loadAllLandObjectsFromStorage() -- loads parcels from region database
Calls scene.LoadPrimsFromStorage() -- loads all objects from region database
Adds RegionStatsSimpleHandler to MainServer
Calls scene.RegisterRegionWithGrid() -- registers with ROBUST GridService -- fatal exit on failure
Calls scene.CreateScriptInstances() -- starts script engine for loaded objects
Adds scene to SceneManager
Hooks scene.EventManager.OnShutdown

Estate owner setup (SetUpEstateOwner()):

Checks [Estates] config for DefaultEstateOwnerName, UUID, email, password
If not found, prompts console interactively
If user does not exist and UserAccountService is a local service, creates the user account
Stores estate settings with owner UUID

PopulateRegionEstateInfo():

Loads estate settings for region from database
If no estate assigned: checks TargetEstate in Regions.ini, then DefaultEstateName in [Estates] config, then prompts console interactively
Can create a new estate or join an existing one

Scene Creation

OpenSim/Region/Application/OpenSimBase.cs -- SetupScene() → CreateScene()

protected Scene SetupScene(RegionInfo regionInfo, int proxyOffset, IConfigSource configSource)
{
    AgentCircuitManager circuitManager = new AgentCircuitManager();
    Scene scene = CreateScene(regionInfo, m_simulationDataService, m_estateDataService, circuitManager);
    scene.LoadWorldMap();
    return scene;
}

protected override Scene CreateScene(...)
{
    return new Scene(regionInfo, circuitManager, simDataService, estateDataService, Config, m_version);
}

Scene constructor takes: RegionInfo, AgentCircuitManager, ISimulationDataService, IEstateDataService, IConfigSource, version string.

See OpenSimulator Internals/Code Map/Scene for Scene internals.

Config Loading

OpenSim/Region/Application/OpenSimBase.cs -- LoadConfigSettings()
OpenSim/Region/Framework/ConfigurationLoader.cs

Same layered config mechanism as ROBUST. Config loaded via ConfigurationLoader.LoadConfigSettings(). Architecture selected via Include-Architecture in OpenSim.ini -- determines standalone vs grid mode.

HTTP Handlers

Registered on MainServer.Instance during startup:

Path	Handler	Notes
/simstatus	SimStatusHandler	Returns "OK" -- health check
/SHA1(osSecret)	XSimStatusHandler	Extended stats as JSON -- path is a hash for mild obscurity
/userStatsURI	UXSimStatusHandler	Same stats at user-configured path -- optional
/robots.txt	SimRobotsHandler	Blocks all web crawlers
/index.php	IndexPHPHandler	Viewer login and capability discovery -- see OpenSimulator Internals/Code Map/Shared

Shutdown

ShutdownSpecific():

Sends XmlRpc Stop to proxy if configured
Calls SceneManager.Close() -- closes all scenes
Disposes all application plugins
Calls base.ShutdownSpecific()