OpenSimulator Internals/Code Map/OpenSim

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:

1. Sets up console -- local, basic, rest, or GUI-driven based on config
2. Calls base.StartupSpecific() (see OpenSimBase below)
3. 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
4. Optional: registers managed stats endpoint
5. Hooks watchdog timeout handler
6. Prints startuplogo.txt if present
7. Selects default console region (root if multiple, the single region if only one)
8. Runs startup command script if configured
9. 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:

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

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

1. Starts WorkManager.JobEngine if enabled
2. Handles SSL cert creation or renewal if configured
3. Handles PEM to PKCS12 cert conversion if configured
4. Sets HTTP server port and SSL flag from [Network]
5. Hooks SceneManager.OnRestartSim
6. 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:

1. Gets IRegionModulesController from ApplicationRegistry -- fatal exit if missing
2. Sets region ServerURI from ExternalHostName and HTTP port
3. Calls SetupScene() -- creates AgentCircuitManager and Scene instance (see Scene below)
4. Calls controller.AddRegionToModules(scene) -- loads all region modules
5. Verifies required permissions modules are loaded if SecurePermissionsLoading = true -- fatal exit if missing
6. Calls scene.SetModuleInterfaces() -- wires up module references
7. Calls SetUpEstateOwner() if estate has no owner -- prompts console interactively
8. Calls scene.loadAllLandObjectsFromStorage() -- loads parcels from region database
9. Calls scene.LoadPrimsFromStorage() -- loads all objects from region database
10. Adds RegionStatsSimpleHandler to MainServer
11. Calls scene.RegisterRegionWithGrid() -- registers with ROBUST GridService -- fatal exit on failure
12. Calls scene.CreateScriptInstances() -- starts script engine for loaded objects
13. Adds scene to SceneManager
14. 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():

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

---

See Also

• OpenSimulator Internals/Code Map
• OpenSimulator Internals/Code Map/ROBUST
• OpenSimulator Internals/Code Map/Shared
• OpenSimulator Internals/Reading the Code
• OpenSimulator Internals/Architecture Overview
• OpenSimulator Internals/Connector Architecture