Editing OpenSimulator Internals/Simulator Services (section)

= Simulator Services =

Simulator services run inside OpenSim.exe and are scoped to the simulator process,
not the grid. They are distinct from [[OpenSimulator_Internals/ROBUST_Services|ROBUST services]],
which run in ROBUST.exe and serve the entire grid.

Each simulator service follows the same local/remote connector pattern used by
grid services: a local connector handles in-process calls; a remote connector
makes HTTP calls to another simulator. See
[[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]] for the
general pattern.

Config key for all three services is in the <code>[Modules]</code> section of
<code>OpenSim.ini</code>.

----

== Land Service ==

'''Interface:''' <code>ILandService</code> (OpenSim.Services.Interfaces)<br>
'''Config key:''' <code>LandServices</code>

=== Purpose ===

Retrieves parcel land data by region handle and coordinates. Used when a simulator
needs land data for a region it does not itself host -- for example, to resolve
access rules at a region border before a crossing completes.

=== Interface ===

<code>ILandService</code> exposes a single method:

 LandData GetLandData(UUID scopeID, ulong regionHandle, uint x, uint y, out byte regionAccess)

=== Connectors ===

{| class="wikitable"
|-
! Connector !! Class !! Used when
|-
| Local || <code>LocalLandServicesConnector</code> || Destination region is hosted by this simulator. Walks the local scene list, matches by world coordinates, returns <code>LandData</code> plus access level and dwell count.
|-
| Remote || <code>RemoteLandServicesConnector</code> || Destination region is on another simulator. Tries local first; falls back to HTTP call via <code>LandServicesConnector</code> base class.
|}

=== Notes ===

* The local connector iterates <code>m_Scenes</code> and matches by world coordinate
  bounds, not by region UUID. This matters for varregions where a single scene
  covers a range of coordinates.
* Dwell count is retrieved via <code>IDwellModule</code> if present; not part of
  the core land data.
* Returns <code>null</code> if no local scene matches and no remote call is
  configured.

----

== Library Service ==

'''Interface:''' <code>ILibraryService</code> (OpenSim.Services.Interfaces)<br>
'''Implementation:''' <code>OpenSim.Services.InventoryService.LibraryService</code><br>
'''Config section:''' <code>[LibraryService]</code>

=== Purpose ===

Provides the shared library inventory -- the read-only content visible to all
users under the Library folder. Backed by XML files on the local filesystem,
not the database.

=== Config ===

 [LibraryService]
 DefaultLibrary = inventory/Libraries.xml
 LibraryName = OpenSim Library

Both keys are optional; the values above are the defaults.

=== Interface ===

 InventoryFolderImpl LibraryRootFolder { get; }
 Dictionary<UUID, InventoryFolderImpl> GetAllFolders()
 InventoryItemBase GetItem(UUID itemID)
 InventoryItemBase[] GetMultipleItems(UUID[] itemIDs)

=== Notes ===

* Not a region module. Instantiated as a <code>ServiceBase</code> directly by
  the service infrastructure. No <code>[Modules]</code> config key.
* Singleton per process: static instance, initialized once regardless of how
  many regions the simulator hosts.
* Loaded from XML files under the <code>inventory/</code> directory at startup.
  Root folder UUID is a fixed constant (<code>00000112-000f-0000-0000-000100bba000</code>);
  all library UUIDs are fixed and do not vary between installations.
* No remote connector. No ROBUST equivalent. Library content is local to each
  simulator.
* The source explicitly notes this is a stopgap: "basically a hack to give us
  an Inventory library while we don't have an inventory server." Architecturally
  it should be a grid service with shared content across simulators; it has
  never been converted.

----

== Simulation Service ==

'''Interface:''' <code>ISimulationService</code> (OpenSim.Services.Interfaces)<br>
'''Config key:''' <code>SimulationServices</code>

=== Purpose ===

Handles simulator-to-simulator communication: creating and updating agents on
remote simulators, moving objects across region boundaries, and closing agents
when they leave. Used for teleports, region crossings, child agent maintenance,
and object crossings.

This is not a ROBUST service. It runs entirely between simulators.

=== Interface ===

Agent operations:

{| class="wikitable"
|-
! Method !! Purpose
|-
| <code>CreateAgent(source, destination, aCircuit, flags, ctx, out reason)</code> || Creates a new agent circuit on the destination simulator. Entry point for teleport and login-to-region.
|-
| <code>UpdateAgent(destination, AgentData, ctx)</code> || Full child agent update: position, appearance, animation state.
|-
| <code>UpdateAgent(destination, AgentPosition)</code> || Lightweight position-only update for child agents.
|-
| <code>QueryAccess(destination, agentID, homeURI, viaTeleport, position, features, ctx, out reason)</code> || Checks whether the destination will accept this agent. Called before <code>CreateAgent</code>.
|-
| <code>ReleaseAgent(originRegion, agentID, uri)</code> || Destination notifies origin that the client has connected. Origin clears its teleport-pending state.
|-
| <code>CloseAgent(destination, agentID, auth_token)</code> || Closes an agent circuit on the destination simulator.
|}

Object operations:

{| class="wikitable"
|-
! Method !! Purpose
|-
| <code>CreateObject(destination, newPosition, sog, isLocalCall)</code> || Sends a scene object to the destination simulator. Used for prim crossings and object teleport. If <code>isLocalCall</code> is true, the object is cloned before transfer; if false, it is used as received from the wire.
|}

=== Connectors ===

{| class="wikitable"
|-
! Connector !! Class !! Used when
|-
| Local || <code>LocalSimulationConnectorModule</code> || Destination region is hosted by this simulator. Dispatches directly to the target <code>Scene</code> by UUID lookup.
|-
| Remote || <code>RemoteSimulationConnectorModule</code> || Destination region is on another simulator. Tries local first; falls back to HTTP via <code>SimulationServiceConnector</code>.
|}

=== Notes ===

* The local connector maintains a <code>Dictionary&lt;UUID, Scene&gt;</code> keyed
  by region UUID. <code>GetScene()</code> has a fallback that returns the first
  available scene if the requested UUID is not found -- this masks bugs and is
  noted as a known issue in the source.
* <code>QueryAccess</code> enforces a version check: if the requesting simulator
  is running protocol version below 0.3 and the destination is a varregion
  (non-256x256), the request is denied. Older viewers crash on varregions.
* <code>RemoteSimulationConnectorModule</code> wraps a
  <code>LocalSimulationConnectorModule</code> instance as its local backend.
  All calls try local first, then fall through to HTTP only if the destination
  is confirmed not-local via <code>IsLocalRegion()</code>.
* <code>source</code> in <code>CreateAgent</code> may be null if the user logged
  in directly or arrived from an older simulator that does not send it.

----

== See Also ==

* [[OpenSimulator_Internals/ROBUST_Services|ROBUST Services]]
* [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]]
* [[OpenSimulator_Internals/Walkthroughs/Avatar_Transfer_Between_Regions|Walkthrough: Avatar Transfer Between Regions]]
* [[OpenSimulator_Internals/Walkthroughs/Avatar_Goes_HG|Walkthrough: Avatar Goes HG]]

[[Category:OpenSimulator Internals]]