Editing OpenSimulator Internals/Code Map/OpenSim (section)

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

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

----