Open Simulator Technical Help - User contributions [en]

OpenSimulator Internals/Connector Architecture

2026-07-09T07:14:19Z

Jwbshaw:

= OpenSimulator Internals/Connector Architecture =

== Overview ==

Connectors are the HTTP client layer that sits between region simulators and ROBUST grid services. Each connector implements a service interface (e.g. IAssetService, IPresenceService) using HTTP calls to the corresponding ROBUST handler.

The same interface may be implemented by:
* A local connector -- calls the service directly in-process (standalone mode or co-located services).
* A remote connector -- makes HTTP calls to a ROBUST server.
* An HG connector -- wraps the remote connector with hypergrid-specific logic.

Region code calls only the interface. Which implementation is loaded depends on configuration ([Architecture] section of the ini files).

Because every ROBUST service is stateless, each can be independently load-balanced or replicated without coordination between instances.

See [[OpenSimulator Internals/ROBUST Services]] for the server-side service implementations.

----

== Connector Pattern ==

All remote connectors follow the same pattern:

# Constructor receives IConfigSource and reads the service URL from config.
# Each method serialises parameters to a REST or XMLRPC request.
# Sends HTTP POST/GET/DELETE to the ROBUST handler endpoint.
# Deserialises the response and returns the result.

The HTTP client layer is WebUtil (OpenSim/Framework/WebUtil.cs), which handles serialisation, connection pooling, and error logging.

See [[OpenSimulator Internals/Connector Architecture/Asset Connector]] for a fully worked example of the pattern including both client and server-side handler code.

----

== Individual Connector Pages ==

{| class="wikitable"
! Connector !! Service Interface !! Notes
|-
| [[OpenSimulator Internals/Connector Architecture/Asset Connector]] || IAssetService || As of 0.9.2, the three region-side asset modules (LocalAssetServiceConnector, RemoteAssetServiceConnector, HGAssetBroker) were replaced by a single RegionAssetConnector. LocalAssetServiceConnector is retained for test use only. HGAssetBroker and RemoteAssetServiceConnector are no longer used in production. RegionAssetConnector behaviour is controlled by [AssetService] keys LocalGridAssetService and HypergridAssetService. See individual page for full detail including server-side handler code.
|-
| [[OpenSimulator Internals/Connector Architecture/GridUser Connector]] || IGridUserService || Tracks last position, login/logout timestamps, home region. Online status in GridUser is less accurate than in Presence, which is updated more frequently.
|-
| [[OpenSimulator Internals/Connector Architecture/Presence Connector]] || IPresenceService || Online status, session tracking, region assignment.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAccount Connector]] || IUserAccountService || User account CRUD. Known bug: CreateUser() sends first name as email value.
|-
| [[OpenSimulator Internals/Connector Architecture/Inventory Connector]] || IInventoryService || XInventory protocol. UpdateFolder() URL-encodes Name; AddFolder() does not.
|-
| HGInventoryService || IInventoryService || HG-only. Pre-suitcase implementation. Returns "My Suitcase" folder as root by name lookup. Does not enforce suitcase tree boundaries on operations. Adjusts CreatorData on item fetch to include home grid URL. Deletions and skeleton requests blocked. Present in current code but not recommended for new deployments.
|-
| HGSuitcaseInventoryService || IInventoryService || HG-only. Current implementation. Enforces strict suitcase tree boundaries on all folder and item operations. Creates system subfolders under suitcase on first use. Allows access to appearance items outside the suitcase tree. Caches suitcase tree and appearance data (5-minute expiry). Requires AvatarService in config in addition to UserAccountsService. Deletions blocked.
|-
| [[OpenSimulator Internals/Connector Architecture/Authentication Connector]] || IAuthenticationService || Password and token authentication, impersonation mechanism.
|-
| [[OpenSimulator Internals/Connector Architecture/Avatar Connector]] || IAvatarService || Appearance storage. ResetAvatar() log erroneously says "SetItems reply".
|-
| [[OpenSimulator Internals/Connector Architecture/Friends Connector]] || IFriendsService || Friend list, online notifications.
|-
| [[OpenSimulator Internals/Connector Architecture/Grid Connector]] || IGridService || Region registration, lookup, neighbour queries.
|-
| [[OpenSimulator Internals/Connector Architecture/Simulation Connector]] || ISimulationService || Inter-simulator agent and object transfer. QueryAccess, CreateAgent, UpdateAgent, CloseAgent, CreateObject.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAgent Connector]] || IUserAgentService || HG-only. Home region lookup, login to foreign grid, session verification.
|-
| [[OpenSimulator Internals/Connector Architecture/Gatekeeper Connector]] || IGatekeeperService || HG-only. Foreign grid entry point. GetHyperlinkRegion, LoginAgentToGrid.
|}

----

== HG Connectors ==

HyperGrid introduces additional connectors that wrap or replace the standard ones:

* UserAgent Connector -- used by the source grid to contact the avatar's home grid UserAgent service during HG teleport.
* Gatekeeper Connector -- used to contact a foreign grid's Gatekeeper during HG destination resolution.
* HGAsset Connector -- used by HGInventoryAccessModule to fetch/push assets between grids (via HGAssetMapper).
* HGInventoryService / HGSuitcaseInventoryService -- inventory access for visiting HG users. HGSuitcaseInventoryService is current; HGInventoryService is the pre-suitcase predecessor. Both block deletions.

Note: prior to 0.9.2, the HGAssetBroker region module handled the local/remote/foreign asset routing decision. It was retired in 0.9.2 and replaced by RegionAssetConnector. References to HGAssetBroker in older documentation and config examples are obsolete.

These are documented in the individual connector pages above and in:
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]

----

== Configuration ==

Connectors are selected in the [Architecture] ini include files:

* config-include/StandaloneCommon.ini -- standalone mode, services loaded in-process.
* config-include/GridCommon.ini -- grid mode, remote connectors used.
* config-include/HGCommon.ini -- hypergrid additions.

The [ServiceList] section of Robust.ini selects which ROBUST handlers are loaded. The [Modules] section of OpenSim.ini selects which connectors the simulator loads.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Code Map]]

OpenSimulator Internals/Code Map/LLUDPServer

2026-07-09T06:27:37Z

Jwbshaw: first

= Code Map: LLUDPServer =

'''Source:''' <code>OpenSim/Region/ClientStack/Linden/UDP/LLUDPServer.cs</code> 
'''Namespace:''' <code>OpenSim.Region.ClientStack.LindenUDP</code> 
'''Key classes:''' <code>LLUDPServer</code>, <code>LLUDPServerShim</code>

----

== Overview ==

<code>LLUDPServer</code> is the UDP transport layer for a single region. It handles
all inbound and outbound UDP traffic between the region and its connected viewers
using the Linden Lab UDP (LLUDP) protocol.

One instance exists per region. It is not shared across regions even when multiple
regions run in the same simulator process.

The region module entry point is <code>LLUDPServerShim</code>, a thin
<code>INonSharedRegionModule</code> wrapper that instantiates and owns
<code>LLUDPServer</code>. The shim handles the module lifecycle; the server
handles the actual network I/O.

----

== Threading Model ==

LLUDPServer runs three persistent threads per region:

{| class="wikitable"
|-
! Thread !! Started by !! Purpose
|-
| Inbound receive thread || <code>StartInbound()</code> via base class <code>OpenSimUDPBase</code> || Receives raw UDP datagrams from the OS socket and places them on <code>packetInbox</code>.
|-
| <code>IncomingPacketHandler</code> || <code>StartInbound()</code> || Drains <code>packetInbox</code>, dispatches packets to the correct <code>LLClientView</code> via <code>ProcessInPacket()</code>.
|-
| <code>OutgoingPacketHandler</code> || <code>StartOutbound()</code> || Drives per-client outbound queues, resends, ACKs, and pings on a timer loop.
|}

A fourth engine, <code>OqrEngine</code> (Outgoing Queue Refill Engine), runs as a
<code>JobEngine</code> thread pool to refill per-client outbound queues without
blocking the outgoing packet handler.

=== Inbound path ===

OS socket
→ base class receive thread (OpenSimUDPBase)
→ PacketReceived()
→ decode + zerodecode
→ pending cache check (UseCircuitCode handling)
→ client lookup by endpoint
→ ACK processing (appended ACKs, PacketAck packets)
→ duplicate detection (PacketArchive)
→ packetInbox.Add()
→ IncomingPacketHandler thread
→ LLClientView.ProcessInPacket()

UseCircuitCode packets are handled specially: they are dispatched via
<code>FireAndForget</code> to <code>HandleUseCircuitCode()</code>, which
authenticates the circuit, creates a new <code>LLClientView</code> and
<code>LLUDPClient</code>, and then reinjects any packets that arrived while
the client was being set up (held in a per-endpoint pending queue).

=== Outbound path ===

Scene code / region modules
→ LLClientView.SendXxx()
→ LLUDPServer.SendPacket() / SendPacketData() / SendUDPPacket()
→ optional zerocoding
→ OutgoingPacket constructed
→ LLUDPClient.EnqueueOutgoing()
if queue full or not throttled:
→ SendPacketFinal() → SyncSend() → OS socket
else:
→ sits in per-client priority queue
→ OutgoingPacketHandler → DequeueOutgoing() → SendPacketFinal()

----

== Key Structures ==

=== packetInbox ===

A <code>BlockingCollection<IncomingPacket></code>. The receive thread
produces; the <code>IncomingPacketHandler</code> thread consumes. Bounded only
by memory.

=== TokenBucket / ThrottleRates ===

<code>Throttle</code> is a scene-wide token bucket capping total outbound
bandwidth. <code>ThrottleRates</code> holds the per-client default rates for
each traffic category (resend, texture, asset, land, wind, cloud, task,
state, AvatarInfo). Both are configured from <code>[ClientStack.LindenUDP]</code>.

=== Pending cache ===

An <code>ExpiringCacheOS<IPEndPoint, Queue<UDPPacketBuffer>></code>
keyed by endpoint. While a new client is being set up after a UseCircuitCode,
all arriving packets for that endpoint are held here and reinjected once the
client is ready. Entries expire after 60 seconds.

=== OqrEngine ===

<code>JobEngine</code> instance named "Outgoing Queue Refill Engine". When a
client's outbound queue runs dry, a refill job is posted here rather than
blocking the outgoing packet handler thread. This prevents one slow client
from stalling outbound processing for all others.

----

== Outgoing Packet Handler Timer Loop ==

The <code>OutgoingPacketHandler</code> thread runs a continuous loop with
three chained timers:

{| class="wikitable"
|-
! Interval !! Action
|-
| 100ms || Check for unacked packets past their RTO; resend via <code>HandleUnacked()</code>.
|-
| 500ms || Send accumulated ACKs for all clients via <code>SendAcks()</code>.
|-
| 5000ms || Send ping checks to all clients via <code>SendPing()</code>.
|}

If no packet was sent in a loop iteration and there are connected clients,
the thread sleeps 15ms. If there are no clients, it sleeps 100ms.

----

== ACK Handling ==

Inbound ACKs arrive in two forms:
* Appended to the tail of any reliable packet (<code>Header.AppendedAcks</code>).
* As explicit <code>PacketAck</code> packets.

Both are processed in <code>PacketReceived()</code> and passed to
<code>LLUDPClient.NeedAcks.Acknowledge()</code>.

Outbound ACKs are accumulated in <code>LLUDPClient.PendingAcks</code> and
sent either appended to the next reliable outbound packet, or as a standalone
<code>PacketAck</code> by the 500ms timer, whichever comes first. The
threshold for immediate ACK sending is 2 * MTU bytes received since the last ACK.

----

== Reliability and Resends ==

Reliable packets are added to <code>LLUDPClient.NeedAcks</code> after send.
The 100ms timer calls <code>HandleUnacked()</code>, which retrieves all packets
whose age exceeds the client's current RTO and invokes their
<code>UnackedMethod</code> callback (default: <code>ResendUnacked()</code>).

<code>ResendUnacked()</code> sets the resent flag on the packet and re-enqueues
it in the <code>Resend</code> throttle category.

A client is disconnected if no packet of any kind is received within the ack
timeout (default 60 seconds; 300 seconds if the client is paused).

----

== MTU and Zerocoding ==

MTU is fixed at 1400 bytes. Max payload is 1200 bytes.

Packets marked <code>MSG_ZEROCODED</code> are compressed by run-length encoding
of zero bytes before send, and decoded on receive. If zerocoding makes a packet
larger than the unencoded form, the flag is stripped and the unencoded data
is sent instead.

Packets larger than the MTU are split into multiple datagrams via
<code>Packet.ToBytesMultiple()</code> where the packet type supports variable
blocks. <code>CoarseLocationUpdate</code> is explicitly excluded from splitting.

----

== Config ==

All keys are in <code>[ClientStack.LindenUDP]</code> in <code>OpenSim.ini</code>:

{| class="wikitable"
|-
! Key !! Default !! Purpose
|-
| <code>client_socket_rcvbuf_size</code> || 0 (OS default) || UDP receive buffer size passed to OS.
|-
| <code>scene_throttle_max_bps</code> || 6250000 || Scene-wide outbound bandwidth cap in bits/sec.
|-
| <code>TextureSendLimit</code> || 20 || Texture packets queued per OQR event.
|-
| <code>DefaultRTO</code> || 0 (auto) || Default retransmission timeout in ms.
|-
| <code>MaxRTO</code> || 0 (auto) || Maximum retransmission timeout in ms.
|-
| <code>AckTimeout</code> || 60 || Seconds before disconnecting a silent client.
|-
| <code>PausedAckTimeout</code> || 300 || Seconds before disconnecting a paused client.
|-
| <code>DisableFacelights</code> || false || Strip facelights from client updates.
|-
| <code>SupportViewerObjectsCache</code> || true || Enable viewer-side object cache support.
|}

----

== Statistics ==

LLUDPServer registers the following stats under the <code>clientstack</code>
category (visible via the <code>show stats</code> console command):

* <code>InboxPacketsCount</code> -- packets waiting in <code>packetInbox</code>.
* <code>IncomingUDPReceivesCount</code> -- total UDP datagrams received.
* <code>IncomingPacketsProcessedCount</code> -- packets dispatched to clients.
* <code>IncomingPacketsMalformedCount</code> -- packets that could not be parsed.
* <code>IncomingPacketsOrphanedCount</code> -- packets with no matching client.
* <code>IncomingPacketsResentCount</code> -- inbound packets flagged as resends by clients.
* <code>OutgoingUDPSendsCount</code> -- total UDP datagrams sent.
* <code>OutgoingPacketsResentCount</code> -- packets resent due to missing ACK.
* <code>OutgoingPacketsQueuedCount</code> -- packets queued across all clients.
* <code>OQRERequestsWaiting</code> -- jobs pending in the OqrEngine.
* <code>AverageUDPProcessTime</code> -- average ms per inbound UDP receive.
* <code>ClientLogoutsDueToNoReceives</code> -- forced disconnects due to ack timeout.

----

== See Also ==

* [[OpenSimulator_Internals/Package_Overview#OpenSim.Region.ClientStack|Package Overview: ClientStack]]
* [[OpenSimulator_Internals/Walkthroughs/Avatar_Rez_In_Region|Walkthrough: Avatar Rez In Region]]
* [[OpenSimulator_Internals/Walkthroughs/Avatar_Logs_Out|Walkthrough: Avatar Logs Out]]

[[Category:OpenSimulator Internals]]

OpenSimulator Internals/Useful Queries

2026-07-09T06:16:28Z

Jwbshaw: /* Regions */

= OpenSimulator Internals/Useful Queries =

== Overview ==

These queries are for grid administrators and developers working directly with MariaDB. Correlated subqueries are used to look up UUIDs by name so you don't have to remember them.

All queries assume osimdev_robust for grid data and osimdev_t1 for region data. Substitute your region database name as needed. Examples use "Test User" as the avatar name -- substitute as required.

----

== Connection ==

mysql -u opensim -p osimdev_robust
USE osimdev_t1;

----

== Grid Database (osimdev_robust) ==

=== Users ===

Find a user by first name:

SELECT PrincipalID, FirstName, LastName, Email, UserLevel,
FROM_UNIXTIME(Created) AS created
FROM UserAccounts
WHERE FirstName LIKE 'Test%';

Show login history by name:

SELECT FROM_UNIXTIME(Login) AS last_login,
FROM_UNIXTIME(Logout) AS last_logout,
Online
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Show home and last location by name:

SELECT HomePosition, HomeLookAt, LastPosition, LastLookAt,
HomeRegionID, LastRegionID
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Who is currently online:

SELECT UserID, RegionID, LastSeen FROM Presence;

=== Avatar Appearance ===

Show all appearance data for a user by name:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

Show worn wearables only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE 'Wearable%';

Show attachment points only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE '_ap_%';

=== Inventory ===

Count inventory items by asset type for a user:

SELECT assetType, COUNT(*) AS count
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
GROUP BY assetType
ORDER BY count DESC;

Find an inventory item by name:

SELECT inventoryName, assetType, assetID, parentFolderID
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND inventoryName LIKE '%house%';

List top-level inventory folders for a user:

SELECT folderName, type, folderID
FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND parentFolderID = (
SELECT folderID FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND type = 8
)
ORDER BY folderName;

=== Assets ===

Count all assets by type:

SELECT assetType, COUNT(*) AS count
FROM assets
GROUP BY assetType
ORDER BY count DESC;

Find assets created by a user:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE CreatorID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY create_time DESC;

Find an asset by name:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE name LIKE '%note%';

=== Friends ===

Show friends for a user:

SELECT Friend, Flags
FROM Friends
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

=== Tokens ===

The <code>tokens</code> table exists in the schema but is not used as of 0.9.x.
Do not rely on its contents.

=== Regions ===

'''Note:''' In standalone deployments the <code>regions</code> table is not
written. Region data exists only in memory for the duration of the process.
These queries return no rows on a standalone.

List all registered regions:

SELECT regionName,
locX/256 AS coord_x, locY/256 AS coord_y,
sizeX, sizeY, flags,
FROM_UNIXTIME(last_seen) AS last_seen
FROM regions;

Check if a region is online:

SELECT regionName, flags & 4 AS online
FROM regions
WHERE regionName = 'T1';

----

== Region Database (osimdev_t1) ==

=== Objects ===

List all objects with world position (root prims only):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
ORDER BY Name;

Count prims per object (root prims only, sorted by size):

SELECT p.Name, p.SceneGroupID,
p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ,
COUNT(*) AS prim_count
FROM prims p
WHERE p.UUID = p.SceneGroupID
GROUP BY p.SceneGroupID, p.Name, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
ORDER BY prim_count DESC;

Find an object by name:

SELECT UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND Name LIKE '%house%';

List all prims in a named object:

SELECT UUID, Name, LinkNumber, PositionX, PositionY, PositionZ
FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Brown House%'
LIMIT 1
)
ORDER BY LinkNumber;

Find objects owned by a specific user:

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

=== Object Contents (Task Inventory) ===

Show contents of a named object:

SELECT pi.name, pi.assetType, pi.assetID
FROM primitems pi
WHERE pi.primID IN (
SELECT UUID FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
)
);

Count task inventory items by type across all objects:

SELECT pi.assetType, COUNT(*) AS count
FROM primitems pi
GROUP BY pi.assetType
ORDER BY count DESC;

Show all objects that contain scripts:

SELECT DISTINCT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM prims p
JOIN primitems pi ON pi.primID = p.UUID
WHERE p.UUID = p.SceneGroupID
AND pi.assetType = 10
ORDER BY p.Name;

=== Prim Shape ===

Show shape for a named object:

SELECT p.Name, p.LinkNumber,
ps.ScaleX, ps.ScaleY, ps.ScaleZ,
ps.PCode, ps.Shape, ps.ProfileCurve, ps.PathCurve
FROM primshapes ps
JOIN prims p ON ps.UUID = p.UUID
WHERE p.SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name = 'Object'
LIMIT 1
)
ORDER BY p.LinkNumber;

=== Persistence State ===

Find objects with pending changes (not yet persisted):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND RezzerID IS NOT NULL
ORDER BY Name;

=== Land ===

Show all parcels:

SELECT LocalLandID, Name, OwnerUUID, Area, LandStatus,
UserLocationX, UserLocationY, UserLocationZ
FROM land;

=== Terrain ===

Check terrain revision and blob size:

SELECT RegionUUID, Revision, LENGTH(Heightfield) AS bytes
FROM terrain;

=== Estate ===

All estate tables are in the region database (osimdev_t1), not the grid database.

Show estate settings:

SELECT EstateID, EstateName, EstateOwner,
PublicAccess, AllowVoice, DenyMinors,
AllowDirectTeleport, AllowSetHome, AllowLandmark,
AllowParcelChanges, AllowEnviromentOverride,
FixedSun, SunPosition, UseGlobalTime,
DenyAnonymous, DenyIdentified, DenyTransacted
FROM estate_settings;

Show which region belongs to which estate:

SELECT r.regionName, m.EstateID, e.EstateName
FROM estate_map m
JOIN estate_settings e ON e.EstateID = m.EstateID
JOIN osimdev_robust.regions r ON r.uuid = m.RegionID;

List estate managers by name:

SELECT e.EstateName, em.uuid AS manager_uuid,
ua.FirstName, ua.LastName
FROM estate_managers em
JOIN estate_settings e ON e.EstateID = em.EstateID
LEFT JOIN osimdev_robust.UserAccounts ua ON ua.PrincipalID = em.uuid
ORDER BY e.EstateName, ua.LastName;

List allowed groups:

SELECT e.EstateName, eg.uuid AS group_uuid
FROM estate_groups eg
JOIN estate_settings e ON e.EstateID = eg.EstateID
ORDER BY e.EstateName;

List allowed users:

SELECT e.EstateName, eu.uuid AS user_uuid,
ua.FirstName, ua.LastName
FROM estate_users eu
JOIN estate_settings e ON e.EstateID = eu.EstateID
LEFT JOIN osimdev_robust.UserAccounts ua ON ua.PrincipalID = eu.uuid
ORDER BY e.EstateName, ua.LastName;

List ban entries:

SELECT e.EstateName,
eb.bannedUUID, eb.bannedIp, eb.bannedIpHostMask,
eb.banningUUID, FROM_UNIXTIME(eb.banTime) AS banned_at
FROM estateban eb
JOIN estate_settings e ON e.EstateID = eb.EstateID
ORDER BY e.EstateName, eb.banTime DESC;

== Cross-Database Queries ==

Objects owned by a named user (cross-database):

SELECT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM osimdev_t1.prims p
WHERE p.UUID = p.SceneGroupID
AND p.OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY p.Name;

Inventory items for an object currently in the region:

SELECT pi.name, pi.assetType, a.name AS asset_name
FROM osimdev_t1.primitems pi
JOIN osimdev_robust.assets a ON a.id = pi.assetID
WHERE pi.primID = (
SELECT UUID FROM osimdev_t1.prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
);

----

== Conversions ==

Unix timestamp to datetime:

SELECT FROM_UNIXTIME(1782133981);

Region metres to region coordinates:

SELECT locX/256 AS coord_x, locY/256 AS coord_y FROM regions;

Asset type numbers:

0 = texture
2 = sound
3 = landmark
5 = clothing
6 = object
7 = notecard
10 = script (LSL)
13 = body part
20 = animation
24 = link (inventory link)
25 = mesh

----

== See Also ==

* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Data Dictionaries]]

OpenSimulator Internals/Useful Queries

2026-07-09T06:12:23Z

Jwbshaw:

= OpenSimulator Internals/Useful Queries =

== Overview ==

These queries are for grid administrators and developers working directly with MariaDB. Correlated subqueries are used to look up UUIDs by name so you don't have to remember them.

All queries assume osimdev_robust for grid data and osimdev_t1 for region data. Substitute your region database name as needed. Examples use "Test User" as the avatar name -- substitute as required.

----

== Connection ==

mysql -u opensim -p osimdev_robust
USE osimdev_t1;

----

== Grid Database (osimdev_robust) ==

=== Users ===

Find a user by first name:

SELECT PrincipalID, FirstName, LastName, Email, UserLevel,
FROM_UNIXTIME(Created) AS created
FROM UserAccounts
WHERE FirstName LIKE 'Test%';

Show login history by name:

SELECT FROM_UNIXTIME(Login) AS last_login,
FROM_UNIXTIME(Logout) AS last_logout,
Online
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Show home and last location by name:

SELECT HomePosition, HomeLookAt, LastPosition, LastLookAt,
HomeRegionID, LastRegionID
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Who is currently online:

SELECT UserID, RegionID, LastSeen FROM Presence;

=== Avatar Appearance ===

Show all appearance data for a user by name:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

Show worn wearables only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE 'Wearable%';

Show attachment points only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE '_ap_%';

=== Inventory ===

Count inventory items by asset type for a user:

SELECT assetType, COUNT(*) AS count
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
GROUP BY assetType
ORDER BY count DESC;

Find an inventory item by name:

SELECT inventoryName, assetType, assetID, parentFolderID
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND inventoryName LIKE '%house%';

List top-level inventory folders for a user:

SELECT folderName, type, folderID
FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND parentFolderID = (
SELECT folderID FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND type = 8
)
ORDER BY folderName;

=== Assets ===

Count all assets by type:

SELECT assetType, COUNT(*) AS count
FROM assets
GROUP BY assetType
ORDER BY count DESC;

Find assets created by a user:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE CreatorID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY create_time DESC;

Find an asset by name:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE name LIKE '%note%';

=== Friends ===

Show friends for a user:

SELECT Friend, Flags
FROM Friends
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

=== Tokens ===

The <code>tokens</code> table exists in the schema but is not used as of 0.9.x.
Do not rely on its contents.

=== Regions ===

List all registered regions:

SELECT regionName,
locX/256 AS coord_x, locY/256 AS coord_y,
sizeX, sizeY, flags,
FROM_UNIXTIME(last_seen) AS last_seen
FROM regions;

Check if a region is online:

SELECT regionName, flags & 4 AS online
FROM regions
WHERE regionName = 'T1';

----

== Region Database (osimdev_t1) ==

=== Objects ===

List all objects with world position (root prims only):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
ORDER BY Name;

Count prims per object (root prims only, sorted by size):

SELECT p.Name, p.SceneGroupID,
p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ,
COUNT(*) AS prim_count
FROM prims p
WHERE p.UUID = p.SceneGroupID
GROUP BY p.SceneGroupID, p.Name, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
ORDER BY prim_count DESC;

Find an object by name:

SELECT UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND Name LIKE '%house%';

List all prims in a named object:

SELECT UUID, Name, LinkNumber, PositionX, PositionY, PositionZ
FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Brown House%'
LIMIT 1
)
ORDER BY LinkNumber;

Find objects owned by a specific user:

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

=== Object Contents (Task Inventory) ===

Show contents of a named object:

SELECT pi.name, pi.assetType, pi.assetID
FROM primitems pi
WHERE pi.primID IN (
SELECT UUID FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
)
);

Count task inventory items by type across all objects:

SELECT pi.assetType, COUNT(*) AS count
FROM primitems pi
GROUP BY pi.assetType
ORDER BY count DESC;

Show all objects that contain scripts:

SELECT DISTINCT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM prims p
JOIN primitems pi ON pi.primID = p.UUID
WHERE p.UUID = p.SceneGroupID
AND pi.assetType = 10
ORDER BY p.Name;

=== Prim Shape ===

Show shape for a named object:

SELECT p.Name, p.LinkNumber,
ps.ScaleX, ps.ScaleY, ps.ScaleZ,
ps.PCode, ps.Shape, ps.ProfileCurve, ps.PathCurve
FROM primshapes ps
JOIN prims p ON ps.UUID = p.UUID
WHERE p.SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name = 'Object'
LIMIT 1
)
ORDER BY p.LinkNumber;

=== Persistence State ===

Find objects with pending changes (not yet persisted):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND RezzerID IS NOT NULL
ORDER BY Name;

=== Land ===

Show all parcels:

SELECT LocalLandID, Name, OwnerUUID, Area, LandStatus,
UserLocationX, UserLocationY, UserLocationZ
FROM land;

=== Terrain ===

Check terrain revision and blob size:

SELECT RegionUUID, Revision, LENGTH(Heightfield) AS bytes
FROM terrain;

=== Estate ===

All estate tables are in the region database (osimdev_t1), not the grid database.

Show estate settings:

SELECT EstateID, EstateName, EstateOwner,
PublicAccess, AllowVoice, DenyMinors,
AllowDirectTeleport, AllowSetHome, AllowLandmark,
AllowParcelChanges, AllowEnviromentOverride,
FixedSun, SunPosition, UseGlobalTime,
DenyAnonymous, DenyIdentified, DenyTransacted
FROM estate_settings;

Show which region belongs to which estate:

SELECT r.regionName, m.EstateID, e.EstateName
FROM estate_map m
JOIN estate_settings e ON e.EstateID = m.EstateID
JOIN osimdev_robust.regions r ON r.uuid = m.RegionID;

List estate managers by name:

SELECT e.EstateName, em.uuid AS manager_uuid,
ua.FirstName, ua.LastName
FROM estate_managers em
JOIN estate_settings e ON e.EstateID = em.EstateID
LEFT JOIN osimdev_robust.UserAccounts ua ON ua.PrincipalID = em.uuid
ORDER BY e.EstateName, ua.LastName;

List allowed groups:

SELECT e.EstateName, eg.uuid AS group_uuid
FROM estate_groups eg
JOIN estate_settings e ON e.EstateID = eg.EstateID
ORDER BY e.EstateName;

List allowed users:

SELECT e.EstateName, eu.uuid AS user_uuid,
ua.FirstName, ua.LastName
FROM estate_users eu
JOIN estate_settings e ON e.EstateID = eu.EstateID
LEFT JOIN osimdev_robust.UserAccounts ua ON ua.PrincipalID = eu.uuid
ORDER BY e.EstateName, ua.LastName;

List ban entries:

SELECT e.EstateName,
eb.bannedUUID, eb.bannedIp, eb.bannedIpHostMask,
eb.banningUUID, FROM_UNIXTIME(eb.banTime) AS banned_at
FROM estateban eb
JOIN estate_settings e ON e.EstateID = eb.EstateID
ORDER BY e.EstateName, eb.banTime DESC;

== Cross-Database Queries ==

Objects owned by a named user (cross-database):

SELECT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM osimdev_t1.prims p
WHERE p.UUID = p.SceneGroupID
AND p.OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY p.Name;

Inventory items for an object currently in the region:

SELECT pi.name, pi.assetType, a.name AS asset_name
FROM osimdev_t1.primitems pi
JOIN osimdev_robust.assets a ON a.id = pi.assetID
WHERE pi.primID = (
SELECT UUID FROM osimdev_t1.prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
);

----

== Conversions ==

Unix timestamp to datetime:

SELECT FROM_UNIXTIME(1782133981);

Region metres to region coordinates:

SELECT locX/256 AS coord_x, locY/256 AS coord_y FROM regions;

Asset type numbers:

0 = texture
2 = sound
3 = landmark
5 = clothing
6 = object
7 = notecard
10 = script (LSL)
13 = body part
20 = animation
24 = link (inventory link)
25 = mesh

----

== See Also ==

* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Data Dictionaries]]

OpenSimulator Internals/Useful Queries

2026-07-09T06:01:00Z

Jwbshaw: /* Estate */

= OpenSimulator Internals/Useful Queries =

== Overview ==

These queries are for grid administrators and developers working directly with MariaDB. Correlated subqueries are used to look up UUIDs by name so you don't have to remember them.

All queries assume osimdev_robust for grid data and osimdev_t1 for region data. Substitute your region database name as needed. Examples use "Test User" as the avatar name -- substitute as required.

----

== Connection ==

mysql -u opensim -p osimdev_robust
USE osimdev_t1;

----

== Grid Database (osimdev_robust) ==

=== Users ===

Find a user by first name:

SELECT PrincipalID, FirstName, LastName, Email, UserLevel,
FROM_UNIXTIME(Created) AS created
FROM UserAccounts
WHERE FirstName LIKE 'Test%';

Show login history by name:

SELECT FROM_UNIXTIME(Login) AS last_login,
FROM_UNIXTIME(Logout) AS last_logout,
Online
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Show home and last location by name:

SELECT HomePosition, HomeLookAt, LastPosition, LastLookAt,
HomeRegionID, LastRegionID
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Who is currently online:

SELECT UserID, RegionID, LastSeen FROM Presence;

=== Avatar Appearance ===

Show all appearance data for a user by name:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

Show worn wearables only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE 'Wearable%';

Show attachment points only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE '_ap_%';

=== Inventory ===

Count inventory items by asset type for a user:

SELECT assetType, COUNT(*) AS count
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
GROUP BY assetType
ORDER BY count DESC;

Find an inventory item by name:

SELECT inventoryName, assetType, assetID, parentFolderID
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND inventoryName LIKE '%house%';

List top-level inventory folders for a user:

SELECT folderName, type, folderID
FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND parentFolderID = (
SELECT folderID FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND type = 8
)
ORDER BY folderName;

=== Assets ===

Count all assets by type:

SELECT assetType, COUNT(*) AS count
FROM assets
GROUP BY assetType
ORDER BY count DESC;

Find assets created by a user:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE CreatorID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY create_time DESC;

Find an asset by name:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE name LIKE '%note%';

=== Friends ===

Show friends for a user:

SELECT Friend, Flags
FROM Friends
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

=== Regions ===

List all registered regions:

SELECT regionName,
locX/256 AS coord_x, locY/256 AS coord_y,
sizeX, sizeY, flags,
FROM_UNIXTIME(last_seen) AS last_seen
FROM regions;

Check if a region is online:

SELECT regionName, flags & 4 AS online
FROM regions
WHERE regionName = 'T1';

----

== Region Database (osimdev_t1) ==

=== Objects ===

List all objects with world position (root prims only):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
ORDER BY Name;

Count prims per object (root prims only, sorted by size):

SELECT p.Name, p.SceneGroupID,
p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ,
COUNT(*) AS prim_count
FROM prims p
WHERE p.UUID = p.SceneGroupID
GROUP BY p.SceneGroupID, p.Name, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
ORDER BY prim_count DESC;

Find an object by name:

SELECT UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND Name LIKE '%house%';

List all prims in a named object:

SELECT UUID, Name, LinkNumber, PositionX, PositionY, PositionZ
FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Brown House%'
LIMIT 1
)
ORDER BY LinkNumber;

Find objects owned by a specific user:

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

=== Object Contents (Task Inventory) ===

Show contents of a named object:

SELECT pi.name, pi.assetType, pi.assetID
FROM primitems pi
WHERE pi.primID IN (
SELECT UUID FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
)
);

Count task inventory items by type across all objects:

SELECT pi.assetType, COUNT(*) AS count
FROM primitems pi
GROUP BY pi.assetType
ORDER BY count DESC;

Show all objects that contain scripts:

SELECT DISTINCT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM prims p
JOIN primitems pi ON pi.primID = p.UUID
WHERE p.UUID = p.SceneGroupID
AND pi.assetType = 10
ORDER BY p.Name;

=== Prim Shape ===

Show shape for a named object:

SELECT p.Name, p.LinkNumber,
ps.ScaleX, ps.ScaleY, ps.ScaleZ,
ps.PCode, ps.Shape, ps.ProfileCurve, ps.PathCurve
FROM primshapes ps
JOIN prims p ON ps.UUID = p.UUID
WHERE p.SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name = 'Object'
LIMIT 1
)
ORDER BY p.LinkNumber;

=== Persistence State ===

Find objects with pending changes (not yet persisted):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND RezzerID IS NOT NULL
ORDER BY Name;

=== Land ===

Show all parcels:

SELECT LocalLandID, Name, OwnerUUID, Area, LandStatus,
UserLocationX, UserLocationY, UserLocationZ
FROM land;

=== Terrain ===

Check terrain revision and blob size:

SELECT RegionUUID, Revision, LENGTH(Heightfield) AS bytes
FROM terrain;

=== Estate ===

All estate tables are in the region database (osimdev_t1), not the grid database.

Show estate settings:

SELECT EstateID, EstateName, EstateOwner,
PublicAccess, AllowVoice, DenyMinors,
AllowDirectTeleport, AllowSetHome, AllowLandmark,
AllowParcelChanges, AllowEnviromentOverride,
FixedSun, SunPosition, UseGlobalTime,
DenyAnonymous, DenyIdentified, DenyTransacted
FROM estate_settings;

Show which region belongs to which estate:

SELECT r.regionName, m.EstateID, e.EstateName
FROM estate_map m
JOIN estate_settings e ON e.EstateID = m.EstateID
JOIN osimdev_robust.regions r ON r.uuid = m.RegionID;

List estate managers by name:

SELECT e.EstateName, em.uuid AS manager_uuid,
ua.FirstName, ua.LastName
FROM estate_managers em
JOIN estate_settings e ON e.EstateID = em.EstateID
LEFT JOIN osimdev_robust.UserAccounts ua ON ua.PrincipalID = em.uuid
ORDER BY e.EstateName, ua.LastName;

List allowed groups:

SELECT e.EstateName, eg.uuid AS group_uuid
FROM estate_groups eg
JOIN estate_settings e ON e.EstateID = eg.EstateID
ORDER BY e.EstateName;

List allowed users:

SELECT e.EstateName, eu.uuid AS user_uuid,
ua.FirstName, ua.LastName
FROM estate_users eu
JOIN estate_settings e ON e.EstateID = eu.EstateID
LEFT JOIN osimdev_robust.UserAccounts ua ON ua.PrincipalID = eu.uuid
ORDER BY e.EstateName, ua.LastName;

List ban entries:

SELECT e.EstateName,
eb.bannedUUID, eb.bannedIp, eb.bannedIpHostMask,
eb.banningUUID, FROM_UNIXTIME(eb.banTime) AS banned_at
FROM estateban eb
JOIN estate_settings e ON e.EstateID = eb.EstateID
ORDER BY e.EstateName, eb.banTime DESC;

== Cross-Database Queries ==

Objects owned by a named user (cross-database):

SELECT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM osimdev_t1.prims p
WHERE p.UUID = p.SceneGroupID
AND p.OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY p.Name;

Inventory items for an object currently in the region:

SELECT pi.name, pi.assetType, a.name AS asset_name
FROM osimdev_t1.primitems pi
JOIN osimdev_robust.assets a ON a.id = pi.assetID
WHERE pi.primID = (
SELECT UUID FROM osimdev_t1.prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
);

----

== Conversions ==

Unix timestamp to datetime:

SELECT FROM_UNIXTIME(1782133981);

Region metres to region coordinates:

SELECT locX/256 AS coord_x, locY/256 AS coord_y FROM regions;

Asset type numbers:

0 = texture
2 = sound
3 = landmark
5 = clothing
6 = object
7 = notecard
10 = script (LSL)
13 = body part
20 = animation
24 = link (inventory link)
25 = mesh

----

== See Also ==

* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Data Dictionaries]]

OpenSimulator Internals/Simulator Services

2026-07-09T05:45:02Z

Jwbshaw: first

= 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) 
'''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) 
'''Implementation:''' <code>OpenSim.Services.InventoryService.LibraryService</code> 
'''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) 
'''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<UUID, Scene></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]]

Main Page

2026-07-08T21:23:59Z

Jwbshaw: missing some top level stuff

= OpenSimulator Internals =

This wiki documents the internal architecture of OpenSimulator for developers and contributors. It covers the database schema, service architecture, connector design, and code structure. Written from code and verified against developer discussion -- where the wiki and the code disagree, the code takes priority.

Maintained by Jagga Meredith. Contributions welcome.

----

== Source Repository ==

https://github.com/opensim/opensim

Only the '''master''' branch is active. All other branches are dead.

----

== Overview ==

OpenSimulator has two main components:

'''ROBUST.exe''' -- handles grid-wide services: user accounts, inventory, assets, presence, and region registration. Multiple simulators connect to a single ROBUST instance.

'''OpenSim.exe''' -- runs one or more regions. Handles objects, avatars, physics, scripting, and terrain. In standalone mode both processes are combined into OpenSim.exe.

The database layer is split to match: ROBUST owns the grid database, each simulator owns its own region database. Both live in the same database server instance as separate databases.

In standalone mode the connector calls the service directly in-process. In grid mode it makes an HTTP call to ROBUST. Same interface either way.

----

== Contents ==

* [[OpenSimulator Internals/Architecture Overview]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Package Overview]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Simulator Services]]
* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Data Dictionaries]]
* [[OpenSimulator Internals/Useful Queries]]
* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Walkthroughs]]

----

== Status ==

This document is a work in progress developed from code review and developer meeting notes. Where the existing wiki disagrees with the source code, the source code takes priority. Discrepancies are noted.

Contributors: Jagga Meredith

OpenSimulator Internals/Package Overview

2026-07-08T21:04:11Z

Jwbshaw: formatting

= Package Overview =

OpenSimulator's source tree is organized into a hierarchy of packages (C# projects).
This page gives a top-level map. For detailed internals of individual classes,
see the [[OpenSimulator_Internals/Code_Map|Code Map]] pages.

== OpenSim ==

The top-level package launches the region server and manages the console.

* '''Entry point:''' <code>OpenSim/Region/Application/Application.cs</code> — <code>Main()</code>
instantiates an <code>OpenSim</code> object, calls <code>Startup()</code> (which spins
up worker threads), then blocks the initial thread on the main console prompt.
* <code>OpenSim.Startup()</code> is inherited from
<code>OpenSim.Framework.Servers.BaseOpenSimServer</code>; it delegates to
<code>StartupSpecific()</code>.

== OpenSim.Addons ==

'''Note: not actively maintained. Use with caution.'''

* '''OpenSim.Addons.Groups''' — group support.
* '''OpenSim.Addons.OfflineIM''' — offline IM support.

== OpenSim.ApplicationPlugins ==

Application plugins: modular code that affects the entire region server
(as distinct from [[OpenSimulator_Internals/Package_Overview#OpenSim.Region.CoreModules|region modules]],
which affect individual regions).

== OpenSim.Capabilities ==

Basic data structures for capability (HTTPS/event-queue) support.

== OpenSim.ConsoleClient ==

REST console client for remote connection to a running OpenSimulator instance.
Not widely deployed; most operators use a <code>screen</code> session on Linux
or separate terminals on Windows.

== OpenSim.Data ==

All low-level database access code. Contains per-backend packages:

* '''OpenSim.Data.MySQL''' — MySQL/MariaDB backend (primary for grid deployments).
* '''OpenSim.Data.SQLite''' — SQLite backend (common for standalone/testing).

Each backend implements the <code>IAssetData</code> and sibling interfaces defined here.
The interface hierarchy is: <code>OpenSim.Data</code> defines the interfaces;
per-DB packages provide the implementations.

See also: [[OpenSimulator_Internals/Useful_Queries|Useful Queries]].

== OpenSim.Framework ==

General framework code shared across the simulator and ROBUST. Not region-specific.

Subpackages of note:

{| class="wikitable"
|-
! Subpackage !! Purpose
|-
| OpenSim.Framework.AssetLoader.Filesystem || Loads library assets from the local filesystem.
|-
| OpenSim.Framework.Console || Console infrastructure.
|-
| OpenSim.Framework.Monitoring || Statistics gathering and monitoring.
|-
| OpenSim.Framework.RegionLoader.FileSystem || Loads region config from filesystem (e.g. <code>bin/Regions/Regions.ini</code>).
|-
| OpenSim.Framework.RegionLoader.Web || Loads region config from a remote URL.
|-
| OpenSim.Framework.Serialization || OAR and IAR read/write infrastructure.
|-
| OpenSim.Framework.Servers || Generic server base classes, HTTP server infrastructure.
|}

Two subpackages handle configuration loading from HTTP and XML respectively;
neither is a current deployment path.

== OpenSim.Region ==

Most of the region-specific code lives here.

=== OpenSim.Region.ClientStack ===

Infrastructure for pluggable UDP client stacks. In practice only one stack exists
(LLUDP); the abstraction remains in case alternatives are ever needed.

* '''OpenSim.Region.ClientStack.LindenCaps''' — HTTP/capability side of the Second Life
protocol. Glues cap requests to region modules.
* '''OpenSim.Region.ClientStack.LindenUDP''' — UDP side of the Second Life protocol.
Glues UDP packets to scene and region module code.

Future Code Map page: [[OpenSimulator_Internals/Code_Map/LLUDPServer|LLUDPServer]] (planned).

=== OpenSim.Region.CoreModules ===

The bundled region modules. This is a large package covering a wide range of
functionality. Key modules documented in the Code Map:

* [[OpenSimulator_Internals/Code_Map/AttachmentsModule|AttachmentsModule]] — avatar attachment lifecycle.
* [[OpenSimulator_Internals/Code_Map/EntityTransferModule|EntityTransferModule]] — region crossings and teleports.
* [[OpenSimulator_Internals/Code_Map/HGEntityTransferModule|HGEntityTransferModule]] — Hypergrid teleport handling.
* [[OpenSimulator_Internals/Code_Map/InventoryAccessModule|InventoryAccessModule]] — inventory access during rez/derez.
* [[OpenSimulator_Internals/Code_Map/AvatarFactoryModule|AvatarFactoryModule]] — avatar appearance management.

=== OpenSim.Region.DataSnapshot ===

Generates an XML summary of region contents; can be exposed to external search engines.

=== OpenSim.Region.Framework ===

The core of the simulator: scene graph, [[OpenSimulator_Internals/Code_Map/ScenePresence|ScenePresence]],
scene object classes, inventory structures, and the [[OpenSimulator_Internals/Code_Map/Scene|Scene]] itself.

=== OpenSim.Region.OptionalModules ===

Region modules not considered core; could in principle be removed while retaining
a functional Second Life-compatible simulator.

=== OpenSim.Region.Physics ===

Physics framework and engine plugins: BulletSim, ubODE, ODE.

=== OpenSim.Region.ScriptEngine ===

Script engine infrastructure. Current engines: XEngine (older), YEngine (current).

=== OpenSim.Region.UserStatistics ===

Exposes simulator statistics via a web page.

== OpenSim.Server ==

Server infrastructure shared between the region simulator and ROBUST.

* '''OpenSim.Server.Base''' — common server infrastructure.
* '''OpenSim.Server.Handlers''' — translates raw incoming HTTP requests to
service calls. Used primarily in grid mode for ROBUST instances.
Example: <code>Asset/AssetServerGetHandler</code> translates an asset fetch
request into a call to the asset service and returns the result.

== OpenSim.Services ==

Service implementations and the connectors that invoke them remotely over HTTP.

* In '''grid mode''': service implementations run inside ROBUST instances.
* In '''standalone mode''': service implementations are instantiated directly
inside OpenSim.exe.

<code>OpenSim.Services.Connectors</code> contains the HTTP client code that
region simulators use to talk to remote ROBUST services.

See [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]]
for the full connector and service table.

== OpenSim.Tests ==

Test infrastructure and some standalone client test code.
Actual regression tests live in <code>*.Tests</code> subpackages throughout
the tree (e.g. <code>OpenSim.Region.Framework.Tests</code>).

== OpenSim.Tools ==

Utility tools associated with OpenSimulator but not used in normal operation.

== See Also ==

* [[OpenSimulator_Internals/Code_Map|Code Map]] — per-class internals
* [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]] — service/connector table
* [[OpenSimulator_Internals/Useful_Queries|Useful Queries]] — database reference
* [[OpenSimulator_Internals/Walkthroughs|Walkthroughs]] — runtime flow documentation

[[Category:OpenSimulator Internals]]

OpenSimulator Internals/Package Overview

2026-07-08T20:58:31Z

Jwbshaw: quibbles

# Draft: OpenSimulator Internals/Package Overview

Target URL: http://osimdev.org/wiki/index.php/OpenSimulator_Internals/Package_Overview

---

## Wiki markup

```mediawiki
= Package Overview =

OpenSimulator's source tree is organized into a hierarchy of packages (C# projects).
This page gives a top-level map. For detailed internals of individual classes,
see the [[OpenSimulator_Internals/Code_Map|Code Map]] pages.

== OpenSim ==

The top-level package launches the region server and manages the console.

* '''Entry point:''' <code>OpenSim/Region/Application/Application.cs</code> — <code>Main()</code>
instantiates an <code>OpenSim</code> object, calls <code>Startup()</code> (which spins
up worker threads), then blocks the initial thread on the main console prompt.
* <code>OpenSim.Startup()</code> is inherited from
<code>OpenSim.Framework.Servers.BaseOpenSimServer</code>; it delegates to
<code>StartupSpecific()</code>.

== OpenSim.Addons ==

'''Note: not actively maintained. Use with caution.'''

* '''OpenSim.Addons.Groups''' — group support.
* '''OpenSim.Addons.OfflineIM''' — offline IM support.

== OpenSim.ApplicationPlugins ==

Application plugins: modular code that affects the entire region server
(as distinct from [[OpenSimulator_Internals/Package_Overview#OpenSim.Region.CoreModules|region modules]],
which affect individual regions).

== OpenSim.Capabilities ==

Basic data structures for capability (HTTPS/event-queue) support.

== OpenSim.ConsoleClient ==

REST console client for remote connection to a running OpenSimulator instance.
Not widely deployed; most operators use a <code>screen</code> session on Linux
or separate terminals on Windows.

== OpenSim.Data ==

All low-level database access code. Contains per-backend packages:

* '''OpenSim.Data.MySQL''' — MySQL/MariaDB backend (primary for grid deployments).
* '''OpenSim.Data.SQLite''' — SQLite backend (common for standalone/testing).

Each backend implements the <code>IAssetData</code> and sibling interfaces defined here.
The interface hierarchy is: <code>OpenSim.Data</code> defines the interfaces;
per-DB packages provide the implementations.

See also: [[OpenSimulator_Internals/Useful_Queries|Useful Queries]].

== OpenSim.Framework ==

General framework code shared across the simulator and ROBUST. Not region-specific.

Subpackages of note:

{| class="wikitable"
|-
! Subpackage !! Purpose
|-
| OpenSim.Framework.AssetLoader.Filesystem || Loads library assets from the local filesystem.
|-
| OpenSim.Framework.Console || Console infrastructure.
|-
| OpenSim.Framework.Monitoring || Statistics gathering and monitoring.
|-
| OpenSim.Framework.RegionLoader.FileSystem || Loads region config from filesystem (e.g. <code>bin/Regions/Regions.ini</code>).
|-
| OpenSim.Framework.RegionLoader.Web || Loads region config from a remote URL.
|-
| OpenSim.Framework.Serialization || OAR and IAR read/write infrastructure.
|-
| OpenSim.Framework.Servers || Generic server base classes, HTTP server infrastructure.
|}

Two subpackages handle configuration loading from HTTP and XML respectively;
neither is a current deployment path.

== OpenSim.Region ==

Most of the region-specific code lives here.

=== OpenSim.Region.ClientStack ===

Infrastructure for pluggable UDP client stacks. In practice only one stack exists
(LLUDP); the abstraction remains in case alternatives are ever needed.

* '''OpenSim.Region.ClientStack.LindenCaps''' — HTTP/capability side of the Second Life
protocol. Glues cap requests to region modules.
* '''OpenSim.Region.ClientStack.LindenUDP''' — UDP side of the Second Life protocol.
Glues UDP packets to scene and region module code.

Future Code Map page: [[OpenSimulator_Internals/Code_Map/LLUDPServer|LLUDPServer]] (planned).

=== OpenSim.Region.CoreModules ===

The bundled region modules. This is a large package covering a wide range of
functionality. Key modules documented in the Code Map:

* [[OpenSimulator_Internals/Code_Map/AttachmentsModule|AttachmentsModule]] — avatar attachment lifecycle.
* [[OpenSimulator_Internals/Code_Map/EntityTransferModule|EntityTransferModule]] — region crossings and teleports.
* [[OpenSimulator_Internals/Code_Map/HGEntityTransferModule|HGEntityTransferModule]] — Hypergrid teleport handling.
* [[OpenSimulator_Internals/Code_Map/InventoryAccessModule|InventoryAccessModule]] — inventory access during rez/derez.
* [[OpenSimulator_Internals/Code_Map/AvatarFactoryModule|AvatarFactoryModule]] — avatar appearance management.

=== OpenSim.Region.DataSnapshot ===

Generates an XML summary of region contents; can be exposed to external search engines.

=== OpenSim.Region.Framework ===

The core of the simulator: scene graph, [[OpenSimulator_Internals/Code_Map/ScenePresence|ScenePresence]],
scene object classes, inventory structures, and the [[OpenSimulator_Internals/Code_Map/Scene|Scene]] itself.

=== OpenSim.Region.OptionalModules ===

Region modules not considered core; could in principle be removed while retaining
a functional Second Life-compatible simulator.

=== OpenSim.Region.Physics ===

Physics framework and engine plugins: BulletSim, ubODE, ODE.

=== OpenSim.Region.ScriptEngine ===

Script engine infrastructure. Current engines: XEngine (older), YEngine (current).

=== OpenSim.Region.UserStatistics ===

Exposes simulator statistics via a web page.

== OpenSim.Server ==

Server infrastructure shared between the region simulator and ROBUST.

* '''OpenSim.Server.Base''' — common server infrastructure.
* '''OpenSim.Server.Handlers''' — translates raw incoming HTTP requests to
service calls. Used primarily in grid mode for ROBUST instances.
Example: <code>Asset/AssetServerGetHandler</code> translates an asset fetch
request into a call to the asset service and returns the result.

== OpenSim.Services ==

Service implementations and the connectors that invoke them remotely over HTTP.

* In '''grid mode''': service implementations run inside ROBUST instances.
* In '''standalone mode''': service implementations are instantiated directly
inside OpenSim.exe.

<code>OpenSim.Services.Connectors</code> contains the HTTP client code that
region simulators use to talk to remote ROBUST services.

See [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]]
for the full connector and service table.

== OpenSim.Tests ==

Test infrastructure and some standalone client test code.
Actual regression tests live in <code>*.Tests</code> subpackages throughout
the tree (e.g. <code>OpenSim.Region.Framework.Tests</code>).

== OpenSim.Tools ==

Utility tools associated with OpenSimulator but not used in normal operation.

== See Also ==

* [[OpenSimulator_Internals/Code_Map|Code Map]] — per-class internals
* [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]] — service/connector table
* [[OpenSimulator_Internals/Useful_Queries|Useful Queries]] — database reference
* [[OpenSimulator_Internals/Walkthroughs|Walkthroughs]] — runtime flow documentation

[[Category:OpenSimulator Internals]]
```

OpenSimulator Internals/Package Overview

2026-07-08T20:52:30Z

Jwbshaw:

# Draft: OpenSimulator Internals/Package Overview

Target URL: http://osimdev.org/wiki/index.php/OpenSimulator_Internals/Package_Overview

---

## Wiki markup

```mediawiki
= Package Overview =

OpenSimulator's source tree is organized into a hierarchy of packages (C# projects).
This page gives a top-level map. For detailed internals of individual classes,
see the [[OpenSimulator_Internals/Code_Map|Code Map]] pages.

== OpenSim ==

The top-level package launches the region server and manages the console.

* '''Entry point:''' <code>OpenSim/Region/Application/Application.cs</code> — <code>Main()</code>
instantiates an <code>OpenSim</code> object, calls <code>Startup()</code> (which spins
up worker threads), then blocks the initial thread on the main console prompt.
* <code>OpenSim.Startup()</code> is inherited from
<code>OpenSim.Framework.Servers.BaseOpenSimServer</code>; it delegates to
<code>StartupSpecific()</code>.

== OpenSim.Addons ==

'''Note: not actively maintained. Use with caution.'''

* '''OpenSim.Addons.Groups''' — group support.
* '''OpenSim.Addons.OfflineIM''' — offline IM support.

== OpenSim.ApplicationPlugins ==

Application plugins: modular code that affects the entire region server
(as distinct from [[OpenSimulator_Internals/Package_Overview#OpenSim.Region.CoreModules|region modules]],
which affect individual regions).

== OpenSim.Capabilities ==

Basic data structures for capability (HTTPS/event-queue) support.

== OpenSim.ConsoleClient ==

REST console client for remote connection to a running OpenSimulator instance.
Not widely deployed; most operators use a <code>screen</code> session on Linux
or separate terminals on Windows.

== OpenSim.Data ==

All low-level database access code. Contains per-backend packages:

* '''OpenSim.Data.MySQL''' — MySQL/MariaDB backend (primary for grid deployments).
* '''OpenSim.Data.SQLite''' — SQLite backend (common for standalone/testing).
* '''OpenSim.Data.MSSQL''' — Microsoft SQL Server backend. Perpetually behind; use MySQL/MariaDB or SQLite.

Each backend implements the <code>IAssetData</code> and sibling interfaces defined here.
The interface hierarchy is: <code>OpenSim.Data</code> defines the interfaces;
per-DB packages provide the implementations.

See also: [[OpenSimulator_Internals/Useful_Queries|Useful Queries]].

== OpenSim.Framework ==

General framework code shared across the simulator and ROBUST. Not region-specific.

Subpackages of note:

{| class="wikitable"
|-
! Subpackage !! Purpose
|-
| OpenSim.Framework.AssetLoader.Filesystem || Loads library assets from the local filesystem.
|-
| OpenSim.Framework.Console || Console infrastructure.
|-
| OpenSim.Framework.Monitoring || Statistics gathering and monitoring.
|-
| OpenSim.Framework.RegionLoader.FileSystem || Loads region config from filesystem (e.g. <code>bin/Regions/Regions.ini</code>).
|-
| OpenSim.Framework.RegionLoader.Web || Loads region config from a remote URL.
|-
| OpenSim.Framework.Serialization || OAR and IAR read/write infrastructure.
|-
| OpenSim.Framework.Servers || Generic server base classes, HTTP server infrastructure.
|}

Two subpackages handle configuration loading from HTTP and XML respectively;
both may have decayed and are not considered current deployment paths.

== OpenSim.Region ==

Most of the region-specific code lives here.

=== OpenSim.Region.ClientStack ===

Infrastructure for pluggable UDP client stacks. In practice only one stack exists
(LLUDP); the abstraction remains in case alternatives are ever needed.

* '''OpenSim.Region.ClientStack.LindenCaps''' — HTTP/capability side of the Second Life
protocol. Glues cap requests to region modules.
* '''OpenSim.Region.ClientStack.LindenUDP''' — UDP side of the Second Life protocol.
Glues UDP packets to scene and region module code.

Future Code Map page: [[OpenSimulator_Internals/Code_Map/LLUDPServer|LLUDPServer]] (planned).

=== OpenSim.Region.CoreModules ===

The bundled region modules. This is a large package covering a wide range of
functionality. Key modules documented in the Code Map:

* [[OpenSimulator_Internals/Code_Map/AttachmentsModule|AttachmentsModule]] — avatar attachment lifecycle.
* [[OpenSimulator_Internals/Code_Map/EntityTransferModule|EntityTransferModule]] — region crossings and teleports.
* [[OpenSimulator_Internals/Code_Map/HGEntityTransferModule|HGEntityTransferModule]] — Hypergrid teleport handling.
* [[OpenSimulator_Internals/Code_Map/InventoryAccessModule|InventoryAccessModule]] — inventory access during rez/derez.
* [[OpenSimulator_Internals/Code_Map/AvatarFactoryModule|AvatarFactoryModule]] — avatar appearance management.

=== OpenSim.Region.DataSnapshot ===

Generates an XML summary of region contents; can be exposed to external search engines.

=== OpenSim.Region.Framework ===

The core of the simulator: scene graph, [[OpenSimulator_Internals/Code_Map/ScenePresence|ScenePresence]],
scene object classes, inventory structures, and the [[OpenSimulator_Internals/Code_Map/Scene|Scene]] itself.

=== OpenSim.Region.OptionalModules ===

Region modules not considered core; could in principle be removed while retaining
a functional Second Life-compatible simulator.

=== OpenSim.Region.Physics ===

Physics framework and engine plugins: BulletSim, ubODE, ODE.

=== OpenSim.Region.ScriptEngine ===

Script engine infrastructure. Current engines: XEngine (older), YEngine (current).

=== OpenSim.Region.UserStatistics ===

Exposes simulator statistics via a web page.

== OpenSim.Server ==

Server infrastructure shared between the region simulator and ROBUST.

* '''OpenSim.Server.Base''' — common server infrastructure.
* '''OpenSim.Server.Handlers''' — translates raw incoming HTTP requests to
service calls. Used primarily in grid mode for ROBUST instances.
Example: <code>Asset/AssetServerGetHandler</code> translates an asset fetch
request into a call to the asset service and returns the result.

== OpenSim.Services ==

Service implementations and the connectors that invoke them remotely over HTTP.

* In '''grid mode''': service implementations run inside ROBUST instances.
* In '''standalone mode''': service implementations are instantiated directly
inside OpenSim.exe.

<code>OpenSim.Services.Connectors</code> contains the HTTP client code that
region simulators use to talk to remote ROBUST services.

See [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]]
for the full connector and service table.

== OpenSim.Tests ==

Test infrastructure and some standalone client test code.
Actual regression tests live in <code>*.Tests</code> subpackages throughout
the tree (e.g. <code>OpenSim.Region.Framework.Tests</code>).

== OpenSim.Tools ==

Utility tools associated with OpenSimulator but not used in normal operation.

== See Also ==

* [[OpenSimulator_Internals/Code_Map|Code Map]] — per-class internals
* [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]] — service/connector table
* [[OpenSimulator_Internals/Useful_Queries|Useful Queries]] — database reference
* [[OpenSimulator_Internals/Walkthroughs|Walkthroughs]] — runtime flow documentation

[[Category:OpenSimulator Internals]]
```

OpenSimulator Internals/Package Overview

2026-07-08T20:48:17Z

Jwbshaw: first

= Package Overview =

OpenSimulator's source tree is organized into a hierarchy of packages (C# projects).
This page gives a top-level map. For detailed internals of individual classes,
see the [[OpenSimulator_Internals/Code_Map|Code Map]] pages.

== OpenSim ==

The top-level package launches the region server and manages the console.

* '''Entry point:''' <code>OpenSim/Region/Application/Application.cs</code> — <code>Main()</code>
instantiates an <code>OpenSim</code> object, calls <code>Startup()</code> (which spins
up worker threads), then blocks the initial thread on the main console prompt.
* <code>OpenSim.Startup()</code> is inherited from
<code>OpenSim.Framework.Servers.BaseOpenSimServer</code>; it delegates to
<code>StartupSpecific()</code>.

== OpenSim.Addons ==

Components originally from the Diva distribution; organized differently from the
main tree as a result.

* '''OpenSim.Addons.Groups''' — core group support.
* '''OpenSim.Addons.OfflineIM''' — core offline IM support.

== OpenSim.ApplicationPlugins ==

Application plugins: modular code that affects the entire region server
(as distinct from [[OpenSimulator_Internals/Package_Overview#OpenSim.Region.CoreModules|region modules]],
which affect individual regions).

== OpenSim.Capabilities ==

Basic data structures for capability (HTTPS/event-queue) support.

== OpenSim.ConsoleClient ==

REST console client for remote connection to a running OpenSimulator instance.
Not widely deployed; most operators use a <code>screen</code> session on Linux
or separate terminals on Windows.

== OpenSim.Data ==

All low-level database access code. Contains per-backend packages:

* '''OpenSim.Data.MySQL''' — MySQL/MariaDB backend (primary for grid deployments).
* '''OpenSim.Data.SQLite''' — SQLite backend (common for standalone/testing).
* '''OpenSim.Data.MSSQL''' — Microsoft SQL Server backend (tends to lag behind the others).

Each backend implements the <code>IAssetData</code> and sibling interfaces defined here.
The interface hierarchy is: <code>OpenSim.Data</code> defines the interfaces;
per-DB packages provide the implementations.

See also: [[OpenSimulator_Internals/Useful_Queries|Useful Queries]].

== OpenSim.Framework ==

General framework code shared across the simulator and ROBUST. Not region-specific.

Subpackages of note:

{| class="wikitable"
|-
! Subpackage !! Purpose
|-
| OpenSim.Framework.AssetLoader.Filesystem || Loads library assets from the local filesystem.
|-
| OpenSim.Framework.Console || Console infrastructure.
|-
| OpenSim.Framework.Monitoring || Statistics gathering and monitoring.
|-
| OpenSim.Framework.RegionLoader.FileSystem || Loads region config from filesystem (e.g. <code>bin/Regions/Regions.ini</code>).
|-
| OpenSim.Framework.RegionLoader.Web || Loads region config from a remote URL.
|-
| OpenSim.Framework.Serialization || OAR and IAR read/write infrastructure.
|-
| OpenSim.Framework.Servers || Generic server base classes, HTTP server infrastructure.
|}

Two subpackages handle configuration loading from HTTP and XML respectively;
both may have decayed and are not considered current deployment paths.

== OpenSim.Region ==

Most of the region-specific code lives here.

=== OpenSim.Region.ClientStack ===

Infrastructure for pluggable UDP client stacks. In practice only one stack exists
(LLUDP); the abstraction remains in case alternatives are ever needed.

* '''OpenSim.Region.ClientStack.LindenCaps''' — HTTP/capability side of the Second Life
protocol. Glues cap requests to region modules.
* '''OpenSim.Region.ClientStack.LindenUDP''' — UDP side of the Second Life protocol.
Glues UDP packets to scene and region module code.

Future Code Map page: [[OpenSimulator_Internals/Code_Map/LLUDPServer|LLUDPServer]] (planned).

=== OpenSim.Region.CoreModules ===

The bundled region modules. This is a large package covering a wide range of
functionality. Key modules documented in the Code Map:

* [[OpenSimulator_Internals/Code_Map/AttachmentsModule|AttachmentsModule]] — avatar attachment lifecycle.
* [[OpenSimulator_Internals/Code_Map/EntityTransferModule|EntityTransferModule]] — region crossings and teleports.
* [[OpenSimulator_Internals/Code_Map/HGEntityTransferModule|HGEntityTransferModule]] — Hypergrid teleport handling.
* [[OpenSimulator_Internals/Code_Map/InventoryAccessModule|InventoryAccessModule]] — inventory access during rez/derez.
* [[OpenSimulator_Internals/Code_Map/AvatarFactoryModule|AvatarFactoryModule]] — avatar appearance management.

=== OpenSim.Region.DataSnapshot ===

Generates an XML summary of region contents; can be exposed to external search engines.

=== OpenSim.Region.Framework ===

The core of the simulator: scene graph, [[OpenSimulator_Internals/Code_Map/ScenePresence|ScenePresence]],
scene object classes, inventory structures, and the [[OpenSimulator_Internals/Code_Map/Scene|Scene]] itself.

=== OpenSim.Region.OptionalModules ===

Region modules not considered core; could in principle be removed while retaining
a functional Second Life-compatible simulator.

=== OpenSim.Region.Physics ===

Physics framework and engine plugins: BulletSim, ubODE, ODE.

=== OpenSim.Region.ScriptEngine ===

Script engine infrastructure. Current engines: XEngine (older), YEngine (current).

=== OpenSim.Region.UserStatistics ===

Exposes simulator statistics via a web page.

== OpenSim.Server ==

Server infrastructure shared between the region simulator and ROBUST.

* '''OpenSim.Server.Base''' — common server infrastructure.
* '''OpenSim.Server.Handlers''' — translates raw incoming HTTP requests to
service calls. Used primarily in grid mode for ROBUST instances.
Example: <code>Asset/AssetServerGetHandler</code> translates an asset fetch
request into a call to the asset service and returns the result.

== OpenSim.Services ==

Service implementations and the connectors that invoke them remotely over HTTP.

* In '''grid mode''': service implementations run inside ROBUST instances.
* In '''standalone mode''': service implementations are instantiated directly
inside OpenSim.exe.

<code>OpenSim.Services.Connectors</code> contains the HTTP client code that
region simulators use to talk to remote ROBUST services.

See [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]]
for the full connector and service table.

== OpenSim.Tests ==

Test infrastructure and some standalone client test code.
Actual regression tests live in <code>*.Tests</code> subpackages throughout
the tree (e.g. <code>OpenSim.Region.Framework.Tests</code>).

== OpenSim.Tools ==

Utility tools associated with OpenSimulator but not used in normal operation.

== See Also ==

* [[OpenSimulator_Internals/Code_Map|Code Map]] — per-class internals
* [[OpenSimulator_Internals/Connector_Architecture|Connector Architecture]] — service/connector table
* [[OpenSimulator_Internals/Useful_Queries|Useful Queries]] — database reference
* [[OpenSimulator_Internals/Walkthroughs|Walkthroughs]] — runtime flow documentation

[[Category:OpenSimulator Internals]]

OpenSimulator Internals/Walkthroughs/Avatar Goes HG

2026-07-07T23:29:59Z

Jwbshaw: Added material from opensimulator.org wiki

OpenSimulator Internals/Connector Architecture

2026-07-07T23:25:37Z

Jwbshaw: updated with content from opensimulator.org wiki

= OpenSimulator Internals/Connector Architecture =

== Overview ==

Connectors are the HTTP client layer that sits between region simulators and ROBUST grid services. Each connector implements a service interface (e.g. IAssetService, IPresenceService) using HTTP calls to the corresponding ROBUST handler.

The same interface may be implemented by:
* A local connector -- calls the service directly in-process (standalone mode or co-located services).
* A remote connector -- makes HTTP calls to a ROBUST server.
* An HG connector -- wraps the remote connector with hypergrid-specific logic.

Region code calls only the interface. Which implementation is loaded depends on configuration ([Architecture] section of the ini files).

Because every ROBUST service is stateless, each can be independently load-balanced or replicated without coordination between instances.

See [[OpenSimulator Internals/ROBUST Services]] for the server-side service implementations.

----

== Connector Pattern ==

All remote connectors follow the same pattern:

# Constructor receives IConfigSource and reads the service URL from config.
# Each method serialises parameters to a REST or XMLRPC request.
# Sends HTTP POST/GET/DELETE to the ROBUST handler endpoint.
# Deserialises the response and returns the result.

The HTTP client layer is WebUtil (OpenSim/Framework/WebUtil.cs), which handles serialisation, connection pooling, and error logging.

See [[OpenSimulator Internals/Connector Architecture/Asset Connector]] for a fully worked example of the pattern including both client and server-side handler code.

----

== Individual Connector Pages ==

{| class="wikitable"
! Connector !! Service Interface !! Notes
|-
| [[OpenSimulator Internals/Connector Architecture/Asset Connector]] || IAssetService || As of 0.9.2, the three region-side asset modules (LocalAssetServiceConnector, RemoteAssetServiceConnector, HGAssetBroker) were replaced by a single RegionAssetConnector. LocalAssetServiceConnector is retained for test use only. HGAssetBroker and RemoteAssetServiceConnector are no longer used in production. RegionAssetConnector behaviour is controlled by [AssetService] keys LocalGridAssetService and HypergridAssetService. See individual page for full detail including server-side handler code.
|-
| [[OpenSimulator Internals/Connector Architecture/GridUser Connector]] || IGridUserService || Tracks last position, login/logout timestamps, home region. Online status in GridUser is less accurate than in Presence, which is updated more frequently.
|-
| [[OpenSimulator Internals/Connector Architecture/Presence Connector]] || IPresenceService || Online status, session tracking, region assignment.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAccount Connector]] || IUserAccountService || User account CRUD. Known bug: CreateUser() sends first name as email value.
|-
| [[OpenSimulator Internals/Connector Architecture/Inventory Connector]] || IInventoryService || XInventory protocol. UpdateFolder() URL-encodes Name; AddFolder() does not.
|-
| [[OpenSimulator Internals/Connector Architecture/Authentication Connector]] || IAuthenticationService || Password and token authentication, impersonation mechanism.
|-
| [[OpenSimulator Internals/Connector Architecture/Avatar Connector]] || IAvatarService || Appearance storage. ResetAvatar() log erroneously says "SetItems reply".
|-
| [[OpenSimulator Internals/Connector Architecture/Friends Connector]] || IFriendsService || Friend list, online notifications.
|-
| [[OpenSimulator Internals/Connector Architecture/Grid Connector]] || IGridService || Region registration, lookup, neighbour queries.
|-
| [[OpenSimulator Internals/Connector Architecture/Simulation Connector]] || ISimulationService || Inter-simulator agent and object transfer. QueryAccess, CreateAgent, UpdateAgent, CloseAgent, CreateObject.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAgent Connector]] || IUserAgentService || HG-only. Home region lookup, login to foreign grid, session verification.
|-
| [[OpenSimulator Internals/Connector Architecture/Gatekeeper Connector]] || IGatekeeperService || HG-only. Foreign grid entry point. GetHyperlinkRegion, LoginAgentToGrid.
|}

----

== HG Connectors ==

HyperGrid introduces additional connectors that wrap or replace the standard ones:

* UserAgent Connector -- used by the source grid to contact the avatar's home grid UserAgent service during HG teleport.
* Gatekeeper Connector -- used to contact a foreign grid's Gatekeeper during HG destination resolution.
* HGAsset Connector -- used by HGInventoryAccessModule to fetch/push assets between grids (via HGAssetMapper).

Note: prior to 0.9.2, the HGAssetBroker region module handled the local/remote/foreign asset routing decision. It was retired in 0.9.2 and replaced by RegionAssetConnector. References to HGAssetBroker in older documentation and config examples are obsolete.

These are documented in the individual connector pages above and in:
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]

----

== Configuration ==

Connectors are selected in the [Architecture] ini include files:

* config-include/StandaloneCommon.ini -- standalone mode, services loaded in-process.
* config-include/GridCommon.ini -- grid mode, remote connectors used.
* config-include/HGCommon.ini -- hypergrid additions.

The [ServiceList] section of Robust.ini selects which ROBUST handlers are loaded. The [Modules] section of OpenSim.ini selects which connectors the simulator loads.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Code Map]]

Main Page

2026-07-07T23:01:09Z

Jwbshaw: moved code map to second last

= OpenSimulator Internals =

This wiki documents the internal architecture of OpenSimulator for developers and contributors. It covers the database schema, service architecture, connector design, and code structure. Written from code and verified against developer discussion -- where the wiki and the code disagree, the code takes priority.

Maintained by Jagga Meredith. Contributions welcome.

----

== Source Repository ==

https://github.com/opensim/opensim

Only the '''master''' branch is active. All other branches are dead.

----

== Overview ==

OpenSimulator has two main components:

'''ROBUST.exe''' -- handles grid-wide services: user accounts, inventory, assets, presence, and region registration. Multiple simulators connect to a single ROBUST instance.

'''OpenSim.exe''' -- runs one or more regions. Handles objects, avatars, physics, scripting, and terrain. In standalone mode both processes are combined into OpenSim.exe.

The database layer is split to match: ROBUST owns the grid database, each simulator owns its own region database. Both live in the same database server instance as separate databases.

In standalone mode the connector calls the service directly in-process. In grid mode it makes an HTTP call to ROBUST. Same interface either way.

----

== Contents ==

* [[OpenSimulator Internals/Architecture Overview]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Data Dictionaries]]
* [[OpenSimulator Internals/Useful Queries]]
* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Walkthroughs]]

----

== Status ==

This document is a work in progress developed from code review and developer meeting notes. Where the existing wiki disagrees with the source code, the source code takes priority. Discrepancies are noted.

Contributors: Jagga Meredith

Main Page

2026-07-07T22:57:57Z

Jwbshaw: remove services

= OpenSimulator Internals =

This wiki documents the internal architecture of OpenSimulator for developers and contributors. It covers the database schema, service architecture, connector design, and code structure. Written from code and verified against developer discussion -- where the wiki and the code disagree, the code takes priority.

Maintained by Jagga Meredith. Contributions welcome.

----

== Source Repository ==

https://github.com/opensim/opensim

Only the '''master''' branch is active. All other branches are dead.

----

== Overview ==

OpenSimulator has two main components:

'''ROBUST.exe''' -- handles grid-wide services: user accounts, inventory, assets, presence, and region registration. Multiple simulators connect to a single ROBUST instance.

'''OpenSim.exe''' -- runs one or more regions. Handles objects, avatars, physics, scripting, and terrain. In standalone mode both processes are combined into OpenSim.exe.

The database layer is split to match: ROBUST owns the grid database, each simulator owns its own region database. Both live in the same database server instance as separate databases.

In standalone mode the connector calls the service directly in-process. In grid mode it makes an HTTP call to ROBUST. Same interface either way.

----

== Contents ==

* [[OpenSimulator Internals/Architecture Overview]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Data Dictionaries]]
* [[OpenSimulator Internals/Useful Queries]]
* [[OpenSimulator Internals/Walkthroughs]]

----

== Status ==

This document is a work in progress developed from code review and developer meeting notes. Where the existing wiki disagrees with the source code, the source code takes priority. Discrepancies are noted.

Contributors: Jagga Meredith
Contributors: Jagga Meredith

OpenSimulator Internals/Useful Queries

2026-07-07T22:51:33Z

Jwbshaw: more material

= OpenSimulator Internals/Useful Queries =

== Overview ==

These queries are for grid administrators and developers working directly with MariaDB. Correlated subqueries are used to look up UUIDs by name so you don't have to remember them.

All queries assume osimdev_robust for grid data and osimdev_t1 for region data. Substitute your region database name as needed. Examples use "Test User" as the avatar name -- substitute as required.

----

== Connection ==

mysql -u opensim -p osimdev_robust
USE osimdev_t1;

----

== Grid Database (osimdev_robust) ==

=== Users ===

Find a user by first name:

SELECT PrincipalID, FirstName, LastName, Email, UserLevel,
FROM_UNIXTIME(Created) AS created
FROM UserAccounts
WHERE FirstName LIKE 'Test%';

Show login history by name:

SELECT FROM_UNIXTIME(Login) AS last_login,
FROM_UNIXTIME(Logout) AS last_logout,
Online
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Show home and last location by name:

SELECT HomePosition, HomeLookAt, LastPosition, LastLookAt,
HomeRegionID, LastRegionID
FROM GridUser
WHERE UserID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

Who is currently online:

SELECT UserID, RegionID, LastSeen FROM Presence;

=== Avatar Appearance ===

Show all appearance data for a user by name:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

Show worn wearables only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE 'Wearable%';

Show attachment points only:

SELECT Name, Value
FROM Avatars
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND Name LIKE '_ap_%';

=== Inventory ===

Count inventory items by asset type for a user:

SELECT assetType, COUNT(*) AS count
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
GROUP BY assetType
ORDER BY count DESC;

Find an inventory item by name:

SELECT inventoryName, assetType, assetID, parentFolderID
FROM inventoryitems
WHERE avatarID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND inventoryName LIKE '%house%';

List top-level inventory folders for a user:

SELECT folderName, type, folderID
FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND parentFolderID = (
SELECT folderID FROM inventoryfolders
WHERE agentID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
AND type = 8
)
ORDER BY folderName;

=== Assets ===

Count all assets by type:

SELECT assetType, COUNT(*) AS count
FROM assets
GROUP BY assetType
ORDER BY count DESC;

Find assets created by a user:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE CreatorID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY create_time DESC;

Find an asset by name:

SELECT id, name, assetType, FROM_UNIXTIME(create_time) AS created
FROM assets
WHERE name LIKE '%note%';

=== Friends ===

Show friends for a user:

SELECT Friend, Flags
FROM Friends
WHERE PrincipalID = (
SELECT PrincipalID FROM UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
);

=== Regions ===

List all registered regions:

SELECT regionName,
locX/256 AS coord_x, locY/256 AS coord_y,
sizeX, sizeY, flags,
FROM_UNIXTIME(last_seen) AS last_seen
FROM regions;

Check if a region is online:

SELECT regionName, flags & 4 AS online
FROM regions
WHERE regionName = 'T1';

----

== Region Database (osimdev_t1) ==

=== Objects ===

List all objects with world position (root prims only):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
ORDER BY Name;

Count prims per object (root prims only, sorted by size):

SELECT p.Name, p.SceneGroupID,
p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ,
COUNT(*) AS prim_count
FROM prims p
WHERE p.UUID = p.SceneGroupID
GROUP BY p.SceneGroupID, p.Name, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
ORDER BY prim_count DESC;

Find an object by name:

SELECT UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND Name LIKE '%house%';

List all prims in a named object:

SELECT UUID, Name, LinkNumber, PositionX, PositionY, PositionZ
FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Brown House%'
LIMIT 1
)
ORDER BY LinkNumber;

Find objects owned by a specific user:

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY Name;

=== Object Contents (Task Inventory) ===

Show contents of a named object:

SELECT pi.name, pi.assetType, pi.assetID
FROM primitems pi
WHERE pi.primID IN (
SELECT UUID FROM prims
WHERE SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
)
);

Count task inventory items by type across all objects:

SELECT pi.assetType, COUNT(*) AS count
FROM primitems pi
GROUP BY pi.assetType
ORDER BY count DESC;

Show all objects that contain scripts:

SELECT DISTINCT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM prims p
JOIN primitems pi ON pi.primID = p.UUID
WHERE p.UUID = p.SceneGroupID
AND pi.assetType = 10
ORDER BY p.Name;

=== Prim Shape ===

Show shape for a named object:

SELECT p.Name, p.LinkNumber,
ps.ScaleX, ps.ScaleY, ps.ScaleZ,
ps.PCode, ps.Shape, ps.ProfileCurve, ps.PathCurve
FROM primshapes ps
JOIN prims p ON ps.UUID = p.UUID
WHERE p.SceneGroupID = (
SELECT UUID FROM prims
WHERE UUID = SceneGroupID AND Name = 'Object'
LIMIT 1
)
ORDER BY p.LinkNumber;

=== Persistence State ===

Find objects with pending changes (not yet persisted):

SELECT Name, UUID, GroupPositionX, GroupPositionY, GroupPositionZ
FROM prims
WHERE UUID = SceneGroupID
AND RezzerID IS NOT NULL
ORDER BY Name;

=== Land ===

Show all parcels:

SELECT LocalLandID, Name, OwnerUUID, Area, LandStatus,
UserLocationX, UserLocationY, UserLocationZ
FROM land;

=== Terrain ===

Check terrain revision and blob size:

SELECT RegionUUID, Revision, LENGTH(Heightfield) AS bytes
FROM terrain;

=== Estate ===

Show estate settings:

SELECT EstateName, EstateOwner, PublicAccess, AllowVoice,
DenyMinors, AllowDirectTeleport, AllowSetHome
FROM estate_settings;

----

== Cross-Database Queries ==

Objects owned by a named user (cross-database):

SELECT p.Name, p.UUID, p.GroupPositionX, p.GroupPositionY, p.GroupPositionZ
FROM osimdev_t1.prims p
WHERE p.UUID = p.SceneGroupID
AND p.OwnerID = (
SELECT PrincipalID FROM osimdev_robust.UserAccounts
WHERE FirstName = 'Test' AND LastName = 'User'
)
ORDER BY p.Name;

Inventory items for an object currently in the region:

SELECT pi.name, pi.assetType, a.name AS asset_name
FROM osimdev_t1.primitems pi
JOIN osimdev_robust.assets a ON a.id = pi.assetID
WHERE pi.primID = (
SELECT UUID FROM osimdev_t1.prims
WHERE UUID = SceneGroupID AND Name LIKE '%Box%'
LIMIT 1
);

----

== Conversions ==

Unix timestamp to datetime:

SELECT FROM_UNIXTIME(1782133981);

Region metres to region coordinates:

SELECT locX/256 AS coord_x, locY/256 AS coord_y FROM regions;

Asset type numbers:

0 = texture
2 = sound
3 = landmark
5 = clothing
6 = object
7 = notecard
10 = script (LSL)
13 = body part
20 = animation
24 = link (inventory link)
25 = mesh

----

== See Also ==

* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Data Dictionaries]]

OpenSimulator Internals/Walkthroughs

2026-07-07T22:41:41Z

Jwbshaw: remove stub

= OpenSimulator Internals/Walkthroughs =

== Overview ==
Each walkthrough traces a single user-facing action through code, connectors, and database writes. Where the Code Map and Databases pages describe components in isolation, these pages follow one operation end to end.

----

* [[OpenSimulator Internals/Walkthroughs/Bring Up Grid]]
* [[OpenSimulator Internals/Walkthroughs/Bring Up Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Change Outfit]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Logs Out]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Garbage Collection]]

----

== See Also ==

* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Architecture Overview]]

OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object

2026-07-07T22:40:07Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object =

== Overview ==

Traces what happens in code, connectors, and database when an avatar takes an object from the world into inventory (derez), or deletes it. Uses the box-with-notecard from [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]] as the concrete example.

This is a concrete instance of [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]. Read that page for the full code path.

----

== Case 1: Take (own object, no-copy) ==

Avatar right-clicks the box and selects Take.

=== 1. Viewer Sends DeRezObject ===

# Viewer sends DeRezObject packet with action=Take, objectLocalID=box local ID.
# Scene.DeRezObjects() validates permissions (CanTakeObject).
# Calls IInventoryAccessModule.CopyToInventory(DeRezAction.Take, folderID, [boxSOG], client, false).

=== 2. Object Serialised ===

BasicInventoryAccessModule.CopyBundleToInventory():
# Serialises box SOG to XML: SceneObjectSerializer.ToOriginalXmlFormat().
#* XML includes: prim data, shape, permissions, position, rotation, task inventory (the notecard reference is embedded in the XML as a primitems-equivalent block).
# Creates asset: AssetService.Store() -- new UUID, AssetType.Object, data = XML bytes.
# CreateItemForObject(Take): determines folder (original FromFolderID if owner taking back own item).
# AddPermissions(): same-owner path, preserves current permissions.
# Scene.AddInventoryItem(): InventoryService.AddItem() -- writes inventoryitems row.
# Sends SendInventoryItemCreateUpdate() to client.

; DB writes:
* assets -- INSERT: new object XML asset UUID
* inventoryitems -- INSERT: new item in Object folder (or original folder)

=== 3. Object Removed from Scene ===

DoPostRezWhenFromItem():
* Box was no-copy: InventoryService.DeleteItems() -- removes original inventoryitems row.

Scene.DeleteSceneObject(boxSOG, false):
* RemoveScriptInstances() -- no-op (no scripts).
* Removes physics actor.
* UnlinkSceneObject() -- removes from scene graph.
* SimulationDataService.RemoveObject(boxUUID, regionID).

; DB writes:
* inventoryitems -- DELETE: original no-copy item
* prims -- DELETE: box prim row
* primshapes -- DELETE: box shape row
* primitems -- DELETE: notecard task inventory row

=== 4. DB State After ===

Region database:
* prims: box row gone.
* primshapes: box shape row gone.
* primitems: notecard task inventory row gone.

Robust database:
* assets: new object XML asset (contains the notecard reference inside the serialised XML).
* inventoryitems: new item pointing to the new asset UUID.
* The notecard asset itself remains in assets table -- assets are never deleted on take.

----

== Case 2: Take Copy (copyable object) ==

Avatar right-clicks and selects Take Copy.

Same serialise-and-store process as above, but:
* DoPostRezWhenFromItem() does NOT delete the original inventory item (item has Copy permission).
* Scene.DeRezObjects() does NOT call DeleteSceneObject() -- object stays in world.

; DB writes:
* assets -- INSERT: new object XML asset
* inventoryitems -- INSERT: new item in Object folder

Region DB unchanged. The box stays in the world.

----

== Case 3: Delete (move to Trash) ==

Avatar right-clicks and selects Delete.

Calls CopyToInventory(DeRezAction.Delete):
* Destination folder: Trash (FolderType.Trash) if own object, Lost and Found if another's.
* Same serialise-and-store process.
* Scene.DeleteSceneObject() removes from scene and region DB.

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: item in Trash
* prims/primshapes/primitems -- DELETE

----

== Key DB Tables Affected ==

{| class="wikitable"
! Table !! Take (no-copy) !! Take Copy !! Delete
|-
| assets || INSERT (new) || INSERT (new) || INSERT (new)
|-
| inventoryitems || INSERT new + DELETE old || INSERT new only || INSERT (Trash)
|-
| prims || DELETE || unchanged || DELETE
|-
| primshapes || DELETE || unchanged || DELETE
|-
| primitems || DELETE || unchanged || DELETE
|}

Note: asset rows are never deleted from the assets table by any of these operations. Assets accumulate. Cleanup is a separate administrative operation outside normal simulator operation.

----

== What Happens to the Notecard Inside ==

The notecard was task inventory of the box (a primitems row). When the box is taken or deleted:

* The primitems row is deleted from the region DB.
* The notecard asset (text content) remains in the assets table -- it is referenced by assetID in the serialised object XML.
* When the box is later rezzed from inventory, the XML is deserialised and the notecard reappears as task inventory -- it is re-fetched from assets by assetID.

The notecard is not duplicated into the avatar's personal inventory (inventoryitems). It stays embedded in the object asset.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Garbage Collection]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Databases]]

OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box

2026-07-07T22:39:12Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box =

== Overview ==

Traces what happens in code, connectors, and database when an avatar rezzes a simple object (a box) from inventory into the world, then puts a notecard inside it. Uses live data from the osimdev T1 region database to illustrate the actual DB state.

This is a concrete instance of [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]. Read that page for the full code path. This page focuses on the DB state before and after.

----

== Setup: What Was in the Database Before ==

Before the box was rezzed, osimdev T1 contained 7 objects (471 prims). After rezzing the box and adding a notecard:

From live query (WHERE UUID = SceneGroupID to get root prim names):

SceneGroupID prim_count root_name
a4cbde76-... 193 CASA 3 (large house)
da990c49-... 181 Brown House
ed13b4e9-... 54 4 chair set
ef6cc0c0-... 36 Athena Bento BoM Mesh Body 6.5
d78b8ebf-... 5 Brown House Sculpts
1285d009-... 1 Sofa_1_N150911kompleet
746c1d97-... 1 Object (cube)
789a253a-... 1 Box

Note: the original query used MIN(Name) GROUP BY SceneGroupID which returned child prim names ("171800", "171801" etc.) for the Athena HUD instead of the root prim name. The correct query uses WHERE UUID = SceneGroupID. See WTF file.

----

== 1. Rezzing the Box ==

Avatar drags "Box" from inventory to the world.

Scene.RezObject() → BasicInventoryAccessModule.RezObject():
# InventoryService.GetItem() -- fetches the box's inventory record from inventoryitems table.
# AssetService.Get(assetID) -- fetches the serialised object XML from assets table.
# Scene.GetObjectsToRez() -- deserialises XML into SceneObjectGroup (1 prim).
# GetNewRezLocation() -- raycasts to ground surface for position.
# DoPreRezWhenFromItem() -- sets name/description, links FromUserInventoryItemID if copyable.
# Scene.AddNewSceneObject() -- adds to scene graph.
# SimulationDataService.StoreObject() called immediately on add -- writes prim to DB.
# CreateScriptInstances() -- no scripts in a plain box, so no-op.
# Schedules full update to all clients.

; DB reads:
* inventoryitems -- SELECT: box item record
* assets -- SELECT: object XML asset

; DB writes (immediate on AddNewSceneObject):
* prims -- INSERT: 1 row (UUID, SceneGroupID = same UUID for root, Name="Box", GroupPositionX/Y/Z, etc.)
* primshapes -- INSERT: 1 row (shape data: PCode=9 box, ProfileShape=0, etc.)

; DB writes (on next backup cycle, ~18s later):
* prims -- UPDATE: position/state confirmed
* primitems -- INSERT: empty (no task inventory yet)

----

== 2. Putting the Notecard in the Box ==

Avatar opens the box contents and drags a notecard from inventory into it.

This is a task inventory operation, not a world rez:

# Viewer sends UpdateTaskInventory packet.
# Scene.UpdateTaskInventory() validates permissions.
# Copies inventory item to object's task inventory (SceneObjectPart.Inventory).
# Sets HasGroupChanged = true on the SOG.
# On next backup cycle: SimulationDataService.StoreObject() writes primitems row.

; DB writes (on next backup cycle):
* primitems -- INSERT: 1 row (primID = box UUID, name="Notecard", assetID = notecard asset UUID, invType=7, assetType=7, etc.)

----

== 3. DB State After ==

prims table: 1 new row for the box root prim.
primshapes table: 1 new row.
primitems table: 1 new row for the notecard inside the box.

The notecard asset itself (the text content) lives in the assets table -- it was already there from when the notecard was written. The primitems row references it by assetID.

----

== 4. What the DB Rows Look Like ==

prims row (key fields):
* UUID -- unique prim UUID
* SceneGroupID -- same as UUID for root prim; child prims have root's UUID here
* RegionUUID -- T1 region UUID
* Name -- "Box"
* GroupPositionX/Y/Z -- world position
* OwnerID -- avatar UUID
* CreatorID -- avatar UUID
* BaseMask, OwnerMask, EveryoneMask, GroupMask, NextOwnerMask -- permissions
* ScriptAccessPin -- 0 (no scripts)
* RotationX/Y/Z/W -- orientation quaternion

primshapes row (key fields):
* UUID -- same as prim UUID
* PCode -- 9 (primitive)
* ProfileShape -- 0 (square/box)
* HollowShape -- 0
* ScaleX/Y/Z -- 0.5, 0.5, 0.5 (default half-metre cube)
* PathBegin/PathEnd -- 0/1 (full path)
* ProfileBegin/ProfileEnd -- 0/1 (full profile)

primitems row (key fields, after notecard added):
* itemID -- unique UUID for this task inventory entry
* primID -- box prim UUID
* assetID -- notecard asset UUID
* name -- notecard name
* description -- notecard description
* invType -- 7 (notecard)
* assetType -- 7 (notecard)
* creatorID -- avatar UUID
* ownerID -- avatar UUID
* BaseMask/CurrentMask/etc. -- permissions

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Databases]]

OpenSimulator Internals/Walkthroughs/Garbage Collection

2026-07-07T22:38:02Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Garbage Collection =

== Overview ==

Traces the two garbage collection mechanisms in OpenSimulator: temporary object cleanup (temp-on-rez objects expiring) and the periodic persistence/auto-return cycle (objects returned to owners for parcel violations). Also covers manual delete and the object persistence lifecycle.

----

== 1. Temporary Object Cleanup ==

OpenSim/Region/Framework/Scenes/Scene.cs -- CleanTempObjects()

Temporary objects are those with PrimFlags.TemporaryOnRez set. They expire based on a per-object Expires timestamp.

=== Trigger ===

CleanTempObjects() is called from the main heartbeat loop every m_update_temp_cleaning frames (default 180 frames, approximately every 16 seconds at ~11fps).

Runs asynchronously via WorkManager.RunInThreadPool to avoid blocking the heartbeat.

=== Process ===

# Gets all entities from scene graph.
# For each SceneObjectGroup:
#* Checks IsDeleted.
#* Checks RootPart.Flags has PrimFlags.TemporaryOnRez.
#* Checks GetSittingAvatarsCount() == 0 -- does not expire objects with seated avatars.
#* Checks RootPart.Expires <= DateTime.UtcNow.
# If all conditions met: calls DeleteSceneObject(grp, false).

DeleteSceneObject():
* Removes script instances.
* Removes physics actors.
* Unlinks from scene graph.
* Fires EventManager.TriggerObjectBeingRemovedFromScene().
* Calls SimulationDataService.RemoveObject() -- removes from prims/primshapes/primitems tables.

; DB writes:
* prims -- DELETE
* primshapes -- DELETE
* primitems -- DELETE (task inventory)

Temporary objects are not saved to inventory. They simply disappear.

----

== 2. Periodic Object Persistence ==

OpenSim/Region/Framework/Scenes/Scene.cs -- UpdateStorageBackup() → Backup()

The region periodically persists changed objects to the database.

=== Trigger ===

UpdateStorageBackup() called every m_update_backup frames (default 200 frames, approximately every 18 seconds). Runs async via WorkManager.RunInThreadPool. Protected by m_backingup flag -- skips if previous backup still running.

=== Process ===

Backup() fires EventManager.TriggerOnBackup(SimulationDataService, forced).

The SimulationDataService handler iterates all SceneObjectGroups. For each group with HasGroupChanged = true:

Persistence timing check (unless forced=true):
* Must have been changed for at least MinimumTimeBeforePersistenceConsidered (default 60 seconds).
* Must not have been unchanged for longer than MaximumTimeBeforePersistenceConsidered (default 600 seconds) -- forces persistence of long-unchanged objects.

If conditions met: calls group.ProcessBackup(SimulationDataService, forced).

ProcessBackup() calls SimulationDataService.StoreObject():
* For each part in the group: writes to prims and primshapes tables (INSERT or UPDATE).
* Writes task inventory to primitems table.
* Clears HasGroupChanged.

; DB writes:
* prims -- INSERT or UPDATE per changed prim
* primshapes -- INSERT or UPDATE
* primitems -- INSERT or UPDATE (task inventory)

=== Auto-Return Messages ===

Backup() also drains m_returns dictionary. For each returned object:
* Sends GridInstantMessage to the owner via IMessageTransferModule.
* Message: "Your object X was returned from parcel Y in region Z due to [reason]."

----

== 3. Parcel Auto-Return ==

Objects left on parcels they don't belong to are returned automatically based on parcel OtherCleanTime setting.

=== Trigger ===

ILandObject.ReturnLandObjects() is called periodically by the land module. Objects exceeding the parcel's OtherCleanTime are queued for return.

=== Process ===

# LandModule identifies objects that have exceeded their allowed time on the parcel.
# Calls Scene.returnObjects() with the list.
# returnObjects() calls IInventoryAccessModule.CopyToInventory(DeRezAction.Return) for each owner group.
# CopyBundleToInventory() serialises objects, creates assets, inserts inventory items into owner's Lost and Found folder.
# Scene.AddReturn() queues the return notification.
# Scene.DeleteSceneObject() removes objects from scene and database.

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: item in Lost and Found
* prims/primshapes/primitems -- DELETE

----

== 4. Object Persistence Lifecycle Summary ==

{| class="wikitable"
! State !! HasGroupChanged !! In DB !! Notes
|-
| Just rezzed || true || yes (immediately on AddNewSceneObject) || Immediately persisted on rez
|-
| Modified || true || stale || Queued for next backup cycle
|-
| Persisted || false || current || Written by Backup()
|-
| Temp-on-rez expired || -- || deleted || CleanTempObjects() removes
|-
| Deleted by avatar || -- || deleted || DeleteSceneObject() removes immediately
|-
| Returned || -- || deleted || CopyToInventory + DeleteSceneObject
|}

----

== 5. Shutdown Persistence ==

On Scene.Close():
* Calls Backup(true) with forced=true.
* All objects with HasGroupChanged = true are persisted regardless of timing.
* Ensures no changes are lost on clean shutdown.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]

OpenSimulator Internals/Code Map

2026-07-07T14:01:35Z

Jwbshaw: more

= OpenSimulator Internals/Code Map =

== Overview ==

This page maps the OpenSimulator codebase from the top down. Each section links to a drill-down page covering that component in detail.

Both ROBUST and OpenSim.exe are built from the same source tree and share the same DLL output. The difference is which entry point is called and which config file is loaded.

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

----

* [[OpenSimulator Internals/Code Map/ROBUST]] -- Grid services process
* [[OpenSimulator Internals/Code Map/OpenSim]] -- Region simulator process
** [[OpenSimulator Internals/Code Map/Scene]] -- Central region object
** [[OpenSimulator Internals/Code Map/ScenePresence]] -- Per-avatar state and lifecycle
** [[OpenSimulator Internals/Code Map/LLUDP]] -- Viewer network transport layer
** [[OpenSimulator Internals/Code Map/LLClientView]] -- IClientAPI implementation, packet dispatch and entity update encoding
** [[OpenSimulator Internals/Code Map/EntityTransferModule]] -- Teleport and region crossing
** [[OpenSimulator Internals/Code Map/HGEntityTransferModule]] -- HyperGrid teleport extensions
** [[OpenSimulator Internals/Code Map/AttachmentsModule]] -- Attachment rez, save, transfer
** [[OpenSimulator Internals/Code Map/AvatarFactoryModule]] -- Appearance baking, save, send
** [[OpenSimulator Internals/Code Map/InventoryAccessModule]] -- Object rez/take, HG asset mirroring
* [[OpenSimulator Internals/Code Map/Shared]] -- Code used by both

----

== See Also ==

* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Architecture Overview]]
* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Walkthroughs]]

OpenSimulator Internals/Code Map/ROBUST

2026-07-07T13:57:14Z

Jwbshaw: updates

= OpenSimulator Internals/Code Map/ROBUST =

== Overview ==

ROBUST is the grid services process. It reads configuration, starts HTTP listeners, loads service connector plugins, then sits waiting for incoming HTTP requests from simulators.

----

=== Entry Point ===

OpenSim/Server/ServerMain.cs -- class OpenSimServer, Main()

Sequence:

# Sets culture and .NET HTTP client defaults:
#* ServicePointManager.DefaultConnectionLimit = 64
#* ServicePointManager.MaxServicePointIdleTime = 30000
#* Expect100Continue = false
#* UseNagleAlgorithm = false
#* ServerCertificateValidationCallback = ValidateServerCertificate
# Creates HttpServerBase("R.O.B.U.S.T.", args) -- config is loaded here (see Config Loading below)
# Reads [Startup] section -- throws if missing
# Reads DnsTimeout (default 30000ms), NoVerifyCertChain, NoVerifyCertHostname from [Startup]
# Calls WebUtil.SetupHTTPClients() with cert settings and max 32 connections
# Reads connector list -- merges ServiceConnectors from [Startup] with all keys from [ServiceList]
# Copies System.Drawing.Common.dll for current platform (Windows vs Linux)
# Loops through connectors -- parses configName@port/dll:class format, loads each (see Service Connector Loading below)
# Special case: LLLoginServiceInConnector gets an IndexPHPHandler added to its HTTP server before loading
# Prints robuststartuplogo.txt to console if present
# Creates PluginLoader
# Calls m_Server.Run() -- enters main loop
# On exit: m_Server.Shutdown(), Util.StopThreadPool(), Environment.Exit()

----

=== Config Loading ===

OpenSim/Server/Base/HttpServerBase.cs
OpenSim/Server/Base/ServicesServerBase.cs

HttpServerBase constructor handles config loading. Layers are applied in order, each overriding the previous:

# Command line args parsed (-i ini file, -c console, -l logfile, -p prompt, -g logconfig)
# Ini file loaded -- defaults to Robust.ini, derived from executable name. Can be a local file or remote HTTP/HTTPS URL.
# Include-* keys scanned -- additional ini files merged in. Supports wildcards and URLs. Loop repeats until no new includes found.
# Environment variables merged in
# Command line args merged on top -- command line always wins
# Variable substitution run (ReplaceKeyValues) -- expands ${Section|Key} references
# ReadConfig() called -- reads [Network] section for port and SSL settings

[Network] minimum requirements:
* port -- required, no default, ROBUST will not start without it
* https_main, https_listener, https_external -- optional SSL flags
* cert_path, cert_pass -- required if SSL enabled
* ConsolePort -- optional remote console port

----

=== HTTP Servers ===

OpenSim/Server/Base/HttpServerBase.cs

* Main HTTP server created on port from [Network]
* Optional second SSL listener if https_listener = true
* All servers started before connectors are loaded
* Additional ports are created on demand via MainServer.GetHttpServer(port) during connector loading
* Handlers register into a running server during connector construction

----

=== Service Connector Loading ===

OpenSim/Server/Base/ServerUtils.cs -- LoadPlugin()

Connector string format:

configName@port/OpenSim.Server.Handlers.dll:ClassName

Parsing:
* Split on / -- left side is optional configName@port, right side is dll:class
* Split left side on @ -- if two parts, first is configName, second is port
* If port specified: get or create HTTP server for that port via MainServer.GetHttpServer()
* If no port: use MainServer.Instance (main port)

Loading:
* LoadPlugin() tries constructor with (IConfigSource, IHttpServer, configName) first
* Falls back to (IConfigSource, IHttpServer) if that fails
* Loaded connectors added to m_ServiceConnectors list
* Failed loads logged as errors but do not stop startup

See [[OpenSimulator Internals/Connector Architecture]] for the full connector pattern.

----

=== Main Loop ===

OpenSim/Server/Base/ServicesServerBase.cs -- Run()

* Watchdog and MemoryWatchdog threads enabled
* Sits in a console prompt loop
* Shutdown signal (quit/shutdown command or SIGTERM) triggers:
** m_Server.Shutdown()
** Util.StopThreadPool()
** Environment.Exit()

----

=== Service Implementations ===

Each service connector loaded from [ServiceList] handles one service domain.

{| class="wikitable"
! Service !! Implementation !! Handler
|-
| AssetService || OpenSim/Services/AssetService/AssetService.cs || OpenSim/Server/Handlers/Asset/
|-
| GridService || OpenSim/Services/GridService/GridService.cs || OpenSim/Server/Handlers/Grid/
|-
| UserAccountService || OpenSim/Services/UserAccountService/UserAccountService.cs || OpenSim/Server/Handlers/UserAccounts/
|-
| PresenceService || OpenSim/Services/PresenceService/PresenceService.cs || OpenSim/Server/Handlers/Presence/
|-
| InventoryService || OpenSim/Services/InventoryService/XInventoryService.cs || OpenSim/Server/Handlers/Inventory/
|-
| AuthenticationService || OpenSim/Services/AuthenticationService/PasswordAuthenticationService.cs || OpenSim/Server/Handlers/Authentication/
|-
| AvatarService || OpenSim/Services/AvatarService/AvatarService.cs || OpenSim/Server/Handlers/Avatar/
|-
| GridUserService || OpenSim/Services/UserAccountService/GridUserService.cs || OpenSim/Server/Handlers/GridUser/
|-
| AgentPreferencesService || OpenSim/Services/UserAccountService/AgentPreferencesService.cs || OpenSim/Server/Handlers/AgentPreferences/
|-
| LoginService || OpenSim/Services/LLLoginService/LLLoginService.cs || OpenSim/Server/Handlers/Login/
|-
| GatekeeperService || OpenSim/Services/HypergridService/GatekeeperService.cs || OpenSim/Server/Handlers/Hypergrid/
|-
| UserAgentService || OpenSim/Services/HypergridService/UserAgentService.cs || OpenSim/Server/Handlers/Hypergrid/
|}

Note: GridUserService and AgentPreferencesService source files live in the UserAccountService directory, not separate directories.

See [[OpenSimulator Internals/Code Map/ROBUST/GridService RegisterRegion]] for a detailed trace of GridService.RegisterRegion() and DeregisterRegion().

See [[OpenSimulator Internals/Code Map/ROBUST/PresenceService]] for a detailed trace of PresenceService.

See [[OpenSimulator Internals/Code Map/ROBUST/UserAccountService]] for a detailed trace of UserAccountService.

See [[OpenSimulator Internals/Code Map/ROBUST/InventoryService]] for a detailed trace of InventoryService.

See [[OpenSimulator Internals/Code Map/ROBUST/AuthenticationService]] for a detailed trace of AuthenticationService, including the impersonation mechanism.

See [[OpenSimulator Internals/Code Map/ROBUST/AvatarService]] for a detailed trace of AvatarService.

See [[OpenSimulator Internals/Code Map/ROBUST/GridUserService]] for a detailed trace of GridUserService.

See [[OpenSimulator Internals/Code Map/ROBUST/AgentPreferencesService]] for a detailed trace of AgentPreferencesService.

See [[OpenSimulator Internals/Code Map/ROBUST/LoginService]] for a detailed trace of LLLoginService.

See [[OpenSimulator Internals/Code Map/ROBUST/GatekeeperService]] for a detailed trace of GatekeeperService.

See [[OpenSimulator Internals/Code Map/ROBUST/UserAgentService]] for a detailed trace of UserAgentService.

----

== See Also ==

* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/AvatarFactoryModule]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Code Map/EntityTransferModule]]
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Connector Architecture]]

OpenSimulator Internals/Code Map/Scene

2026-07-07T13:55:59Z

Jwbshaw: updates

= 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).

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

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

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

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

----

== See Also ==

* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Code Map/OpenSim]]
* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/EntityTransferModule]]
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Code Map/AvatarFactoryModule]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Code Map/Shared]]
* [[OpenSimulator Internals/Architecture Overview]]
* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Logs Out]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]

OpenSimulator Internals/Code Map/Scene

2026-07-07T13:52:01Z

Jwbshaw: wrong paste

= 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).

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

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

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

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

----

== See Also ==

* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Code Map/OpenSim]]
* [[OpenSimulator Internals/Code Map/Shared]]
* [[OpenSimulator Internals/Architecture Overview]]
* [[OpenSimulator Internals/Connector Architecture]]

OpenSimulator Internals/Walkthroughs

2026-07-07T13:27:55Z

Jwbshaw: update

= OpenSimulator Internals/Walkthroughs =

== Overview ==
Each walkthrough traces a single user-facing action through code, connectors, and database writes. Where the Code Map and Databases pages describe components in isolation, these pages follow one operation end to end.

----

* [[OpenSimulator Internals/Walkthroughs/Bring Up Grid]]
* [[OpenSimulator Internals/Walkthroughs/Bring Up Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Change Outfit]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Logs Out]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Garbage Collection]] (stub)

----

== See Also ==

* [[OpenSimulator Internals/Code Map]]
* [[OpenSimulator Internals/Databases]]
* [[OpenSimulator Internals/Architecture Overview]]

OpenSimulator Internals/Connector Architecture

2026-07-07T13:23:00Z

Jwbshaw: update

= OpenSimulator Internals/Connector Architecture =

== Overview ==

Connectors are the HTTP client layer that sits between region simulators and ROBUST grid services. Each connector implements a service interface (e.g. IAssetService, IPresenceService) using HTTP calls to the corresponding ROBUST handler.

The same interface may be implemented by:
* A local connector -- calls the service directly in-process (standalone mode or co-located services).
* A remote connector -- makes HTTP calls to a ROBUST server.
* An HG connector -- wraps the remote connector with hypergrid-specific logic.

Region code calls only the interface. Which implementation is loaded depends on configuration ([Architecture] section of the ini files).

See [[OpenSimulator Internals/ROBUST Services]] for the server-side service implementations.

----

== Connector Pattern ==

All remote connectors follow the same pattern:

# Constructor receives IConfigSource and reads the service URL from config.
# Each method serialises parameters to a REST or XMLRPC request.
# Sends HTTP POST/GET/DELETE to the ROBUST handler endpoint.
# Deserialises the response and returns the result.

The HTTP client layer is WebUtil (OpenSim/Framework/WebUtil.cs), which handles serialisation, connection pooling, and error logging.

See [[OpenSimulator Internals/Connector Architecture/Asset Connector]] for a fully worked example of the pattern including both client and server-side handler code.

----

== Individual Connector Pages ==

{| class="wikitable"
! Connector !! Service Interface !! Notes
|-
| [[OpenSimulator Internals/Connector Architecture/Asset Connector]] || IAssetService || Includes server-side handler detail. HG variant wraps with foreign asset server logic.
|-
| [[OpenSimulator Internals/Connector Architecture/GridUser Connector]] || IGridUserService || Tracks last position, login/logout timestamps, home region.
|-
| [[OpenSimulator Internals/Connector Architecture/Presence Connector]] || IPresenceService || Online status, session tracking, region assignment.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAccount Connector]] || IUserAccountService || User account CRUD. Known bug: CreateUser() sends first name as email value.
|-
| [[OpenSimulator Internals/Connector Architecture/Inventory Connector]] || IInventoryService || XInventory protocol. UpdateFolder() URL-encodes Name; AddFolder() does not.
|-
| [[OpenSimulator Internals/Connector Architecture/Authentication Connector]] || IAuthenticationService || Password and token authentication, impersonation mechanism.
|-
| [[OpenSimulator Internals/Connector Architecture/Avatar Connector]] || IAvatarService || Appearance storage. ResetAvatar() log erroneously says "SetItems reply".
|-
| [[OpenSimulator Internals/Connector Architecture/Friends Connector]] || IFriendsService || Friend list, online notifications.
|-
| [[OpenSimulator Internals/Connector Architecture/Grid Connector]] || IGridService || Region registration, lookup, neighbour queries.
|-
| [[OpenSimulator Internals/Connector Architecture/Simulation Connector]] || ISimulationService || Inter-simulator agent and object transfer. QueryAccess, CreateAgent, UpdateAgent, CloseAgent, CreateObject.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAgent Connector]] || IUserAgentService || HG-only. Home region lookup, login to foreign grid, session verification.
|-
| [[OpenSimulator Internals/Connector Architecture/Gatekeeper Connector]] || IGatekeeperService || HG-only. Foreign grid entry point. GetHyperlinkRegion, LoginAgentToGrid.
|}

----

== HG Connectors ==

HyperGrid introduces additional connectors that wrap or replace the standard ones:

* UserAgent Connector -- used by the source grid to contact the avatar's home grid UserAgent service during HG teleport.
* Gatekeeper Connector -- used to contact a foreign grid's Gatekeeper during HG destination resolution.
* HGAsset Connector -- used by HGInventoryAccessModule to fetch/push assets between grids (via HGAssetMapper).

These are documented in the individual connector pages above and in:
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]

----

== Configuration ==

Connectors are selected in the [Architecture] ini include files:

* config-include/StandaloneCommon.ini -- standalone mode, services loaded in-process.
* config-include/GridCommon.ini -- grid mode, remote connectors used.
* config-include/HGCommon.ini -- hypergrid additions.

The [ServiceList] section of Robust.ini selects which ROBUST handlers are loaded. The [Modules] section of OpenSim.ini selects which connectors the simulator loads.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Code Map]]

OpenSimulator Internals/Code Map/InventoryAccessModule

2026-07-07T13:21:52Z

Jwbshaw: first

= OpenSimulator Internals/Code Map/InventoryAccessModule =

== Overview ==

OpenSim/Region/CoreModules/Framework/InventoryAccess/BasicInventoryAccessModule.cs
OpenSim/Region/CoreModules/Framework/InventoryAccess/HGInventoryAccessModule.cs

Two modules, one extends the other. BasicInventoryAccessModule handles all local inventory operations. HGInventoryAccessModule extends it for HyperGrid asset mirroring and suitcase management.

Registered as IInventoryAccessModule. Selected via [Modules] InventoryAccessModule = BasicInventoryAccessModule or HGInventoryAccessModule.

----

== BasicInventoryAccessModule ==

=== Configuration ===

[Inventory] section

{| class="wikitable"
! Key !! Default !! Purpose
|-
| CoalesceMultipleObjectsToInventory || true || Group multiple selected objects into one coalesced inventory item
|}

=== Event Wiring ===

OnNewClient() hooks per client:
* OnCreateNewInventoryItem → CreateNewInventoryItem()

=== CreateNewInventoryItem() ===

Called when avatar creates a new item directly in inventory (new script, notecard, landmark, etc.).

# Checks CanCreateUserInventory permission.
# Resolves target folder by ID, or by type if folder not found.
# If transactionID set (asset upload in progress): delegates to IAgentAssetTransactions.HandleItemCreationFromTransaction().
# Otherwise creates inline based on asset type:
#* Landmark: generates landmark asset data (region_id, local_pos, region_handle), stores asset, creates inventory item.
#* LSLText: uses Constants.DefaultScriptID as asset.
#* Notecard: uses Constants.EmptyNotecardID.
#* Settings/Material: uses environment/material defaults.
#* Clothing/Bodypart: sets flags = subType.
# Calls Scene.CreateNewInventoryItem() -- writes to inventoryitems table via InventoryService.

; DB writes:
* assets -- INSERT: new asset (landmark, notecard, etc.)
* inventoryitems -- INSERT: new inventory item

=== CopyToInventory() ===

Main path for taking objects from world to inventory (Take, TakeCopy, Delete, Return).

# Groups SOGs by owner (for coalesced objects, only same-owner SOGs merge).
# For each bundle: calls CopyBundleToInventory().

CopyBundleToInventory():
# Suspends keyframe motion on all SOGs.
# Records and stores positions/rotations (attachment stored pos used for attachments).
# Applies NextOwnerMask cleanup.
# Serialises: single SOG → SceneObjectSerializer.ToOriginalXmlFormat(); multiple → CoalescedSceneObjectsSerializer.ToXml().
# Restores positions.
# Calls CreateItemForObject() -- determines destination folder and creates InventoryItemBase shell.
# Calls AddPermissions() -- computes effective permissions from SOG current+folded perms; applies NextOwner if ownership changes.
# Creates asset: CreateAsset() → UUID.Random(), stores via AssetService.Store().
# If SaveToExistingUserInventoryItem: InventoryService.UpdateItem().
# Otherwise: Scene.AddInventoryItem() → InventoryService.AddItem(). Sends SendInventoryItemCreateUpdate() to client or owner's client.

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT or UPDATE

=== CreateItemForObject() ===

Determines destination folder and owner:

* Take / TakeCopy: remoteClient's agent ID, Object folder (or original folder if owner taking back own item).
* Delete (own item): Trash folder.
* Delete (other's item) / Return: Lost and Found folder of object owner.
* Group-owned: Last owner's inventory.

=== AddPermissions() ===

* If new owner (remoteClient != object owner) and PropagatePermissions: applies NextOwnerMask, sets ObjectSlamPerm flag.
* If same owner: copies current perms preserving folded bits.

=== RezObject() ===

Rezzes an inventory item into the scene.

# Gets InventoryItemBase from InventoryService.
# Gets asset from AssetService.
# Calls Scene.GetObjectsToRez() -- deserialises XML into List<SceneObjectGroup>.
# Calls Scene.GetNewRezLocation() -- raycasts to find rez position.
# Calls DoPreRezWhenFromItem():
#* Checks CanRezObject permission for each SOG.
#* Sets name/description from inventory item.
#* Applies ownership change and permission slam if new owner or Slam flag set.
#* Calls ApplyNextOwnerPermissions() if ownership changed.
#* Sets FromUserInventoryItemID if item is copyable.
# For each SOG: Scene.AddNewSceneObject(), CreateScriptInstances(), ResumeScripts().
# Calls DoPostRezWhenFromItem():
#* If item is no-copy: InventoryService.DeleteItems() -- removes item from inventory.

; DB reads:
* inventoryitems -- SELECT by item UUID
* assets -- SELECT by asset UUID

; DB writes (conditional):
* inventoryitems -- DELETE: if no-copy item consumed on rez

=== CapsUpdateInventoryItemAsset() ===

Called via capability when avatar edits a notecard, script, gesture, etc. in-world.

# Gets item, checks ownership and permissions.
# Creates new asset from uploaded data.
# Calls AssetService.Store() + InventoryService.UpdateItem().
# Returns new asset UUID.

; DB writes:
* assets -- INSERT: updated asset
* inventoryitems -- UPDATE: new assetID

----

== HGInventoryAccessModule ==

Extends BasicInventoryAccessModule. Active when HyperGrid is enabled.

=== Additional Configuration ===

[HGInventoryAccessModule] section

{| class="wikitable"
! Key !! Default !! Purpose
|-
| OutboundPermission || true || Allow assets to be posted to foreign user's asset server
|-
| RestrictInventoryAccessAbroad || true || Hide non-suitcase inventory when going HG
|-
| CheckSeparateAssets || false || Support grids where world and inventory use different asset servers
|-
| RegionHGAssetServerURI || (empty) || Local asset server URL when CheckSeparateAssets=true
|}

=== HGAssetMapper ===

Static singleton. Handles Get() and Post() -- HTTP calls to foreign asset servers to fetch or push assets.

* Get(assetID, agentID, foreignAssetServerURL): fetches asset from foreign server if not in local cache.
* Post(assetID, agentID, foreignAssetServerURL): pushes local asset to foreign server (subject to OutboundPermission).

=== IsForeignUser() ===

Returns true if the user's asset server differs from local. Gets AssetServerURI from AgentCircuitData.ServiceURLs or UserManagementModule. If CheckSeparateAssets=true, compares against m_LocalAssetsURL.

=== RezObject() Override ===

Before calling base.RezObject():
* If IsForeignUser: calls m_assMapper.Get(item.AssetID, agentID, foreignAssetServer) -- fetches object asset from foreign grid if not cached locally.

=== ExportAsset() Override ===

Called from CopyBundleToInventory() after asset is stored:
* If IsForeignUser and OutboundPermission: calls m_assMapper.Post() -- pushes newly created asset to foreign user's asset server.

=== Suitcase Management ===

On TeleportStart (HG departure, local user):
* ProcessInventoryForHypergriding(): fetches root folder content, renames all non-Suitcase folders to "FolderName (Unavailable)", sends BulkUpdateInventory to client. Avatar sees only My Suitcase contents while abroad.

On TeleportFail (HG departure failed, local user):
* ProcessInventoryForComingHome(): fetches root folder, sends full inventory back without "(Unavailable)" suffix.

On CompleteMovement (HG arrival, local user returning home):
* ProcessInventoryForComingHome(): same as TeleportFail -- restores full inventory view.

ProcessInventoryForArriving() and ProcessInventoryForLeaving() are currently no-ops.

=== GenerateLandmark() Override ===

Appends "gatekeeper {URL}" line to landmark data so HG landmarks carry grid identity.

=== Permissions ===

CanTakeObject(): if OutboundPermission=false and user is foreign, only allow taking own objects.
OnTransferUserInventory(): if OutboundPermission=false, block inventory transfer to foreign users.

=== PostInventoryAsset() ===

Hooked to OnNewInventoryItemUploadComplete event. After any inventory asset upload:
* If IsForeignUser and OutboundPermission (or asset is a landmark): posts asset to foreign user's asset server.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]

OpenSimulator Internals/Code Map/HGEntityTransferModule

2026-07-07T13:20:58Z

Jwbshaw: first

= OpenSimulator Internals/Code Map/HGEntityTransferModule =

== Overview ==

OpenSim/Region/CoreModules/Framework/EntityTransfer/HGEntityTransferModule.cs

Extends EntityTransferModule. Replaces it when HyperGrid is enabled ([Modules] EntityTransferModule = HGEntityTransferModule). Overrides the key virtual methods to handle cross-grid agent transfer, foreign user logout, appearance restriction, and incoming attachment asset fetching.

Also registers as IUserAgentVerificationModule -- verifies HG client tokens on connection.

----

== Configuration ==

[EntityTransfer] section

{| class="wikitable"
! Key !! Default !! Purpose
|-
| LevelHGTeleport || 0 || Minimum user level required to HG teleport (local users only)
|-
| RestrictAppearanceAbroad || false || If true, enforce exported appearance before HG TP
|-
| AccountForAppearance || (empty) || Comma-separated "First Last" account names whose appearance is the allowed export set
|}

----

== GetFinalDestination() Override ==

Called during DoTeleportInternal() to resolve the true destination.

# Calls GridService.GetRegionFlags() to check if the destination region has the Hyperlink flag.
# If Hyperlink: calls GatekeeperServiceConnector.GetHyperlinkRegion() -- HTTP request to the foreign grid's Gatekeeper service.
#* Gatekeeper returns the actual destination GridRegion on the foreign grid.
# If not Hyperlink: returns the region unchanged (same as base class).

This is the step that resolves a local hyperlink stub into a real foreign region descriptor.

----

== NeedsClosing() Override ==

Returns true (source agent should be fully closed after transfer) if:
* OutViewRange is true, OR
* The destination region has the Hyperlink flag or is unknown (flags == -1).

HG teleports always close the source agent regardless of view distance.

----

== CreateAgent() Override ==

Called during DoTeleportInternal() to create the agent at the destination.

# Calls GridService.GetRegionFlags() to check if destination is a Hyperlink region.
# If Hyperlink (HG teleport):
#* Checks if local user has sufficient UserLevel (>= LevelHGTeleport). Refuses if not.
#* Reads HomeURI from agentCircuit.ServiceURLs.
#* Gets or creates a UserAgentServiceConnector for the home grid.
#* Calls UserAgentService.LoginAgentToGrid() -- HTTP POST to home grid's UserAgent service.
#*: Home grid's UserAgent service calls the foreign Gatekeeper to create the agent there.
#* Sets logout = true -- flags that this agent should be logged out of the source grid after transfer.
#* Fires TriggerTeleportStart on success.
# If not Hyperlink: calls base.CreateAgent() -- normal SimulationService.CreateAgent().

----

== AgentHasMovedAway() Override ==

Called after the agent has successfully moved to destination.

# Calls base.AgentHasMovedAway() (currently a no-op in base).
# If logout == true (HG teleport):
#* Calls PresenceService.LogoutAgent() -- marks agent offline in source grid's presence table.
#* Calls GridUserService.LoggedOut() -- updates source grid's griduser table with last position.

This is the HG-specific grid logout. The agent is now on the foreign grid and is no longer a presence on the source grid.

; DB writes (source grid, HG teleport only):
* presence -- UPDATE: Online=0, session cleared
* griduser -- UPDATE: LastPosition, Logout timestamp

----

== ValidateGenericConditions() Override ==

Called before teleport proceeds. For HG teleports with RestrictAppearanceAbroad=true:

# Checks if destination is a Hyperlink region.
# For local grid users going HG:
#* Checks each wearable slot against the exported appearance (ExportedAppearance property).
#* Checks each attachment against the exported attachment list.
#* Returns false (rejects teleport) if any item is not in the allowed set.

ExportedAppearance: lazy-loaded on first access. Loads appearance for each account in AccountForAppearance from AvatarService, resolves attachment ItemIDs to AssetIDs via InventoryService.

----

== OnConnectionClosed() Override ==

Called when viewer disconnects.

For local grid users: calls IUserAgentService.LogoutAgent() -- notifies home UserAgent service.

For foreign (HG) users:
# Gets HomeURI from AgentCircuitData.ServiceURLs.
# Creates UserAgentServiceConnector for the home grid.
# Calls security.LogoutAgent() -- HTTP POST to foreign home grid's UserAgent service.
# Calls base.OnConnectionClosed() -- handles abort-in-transit case.

----

== TeleportHome() Override ==

For local grid users: delegates to base.TeleportHome() which uses GridUserService to find home region.

For foreign (HG) users:
# Gets HomeURI from AgentCircuitData.ServiceURLs.
# Calls UserAgentService.GetHomeRegion() -- HTTP request to foreign home grid.
# Constructs a Gatekeeper GridRegion from the HomeURI.
# Calls DoTeleport() with ViaHome flag.

----

== HandleIncomingSceneObject() Override ==

Called when an object crosses into this region from another.

For foreign-user attachments arriving via HGLogin (ViaHGLogin flag set):
# Adds object to scene immediately.
# Queues an async job on m_incomingSceneObjectEngine (JobEngine, 30s timeout).
# Job: creates HGUuidGatherer with the foreign AssetServerURI from AgentCircuitData.
#* Gathers all referenced asset UUIDs from the SOG recursively.
#* Fetches each asset from the foreign grid's asset server.
#* 30-second timeout per gather/fetch step -- removes all jobs for that owner on timeout.
# After fetch: calls base.HandleIncomingSceneObject().

For non-HGLogin foreign user attachments (already fetched by first local grid region): calls base directly.

For local user attachments: calls base directly.

----

== HandleIncomingAttachments() Override ==

Same pattern as HandleIncomingSceneObject() but for the attachment list transferred in AgentData during crossing/teleport.

For foreign HGLogin users:
# Queues async job.
# HGUuidGatherer fetches all attachment assets from foreign AssetServerURI.
# On completion: calls base.HandleIncomingAttachments().

Includes sp.IsDeleted check in fetch loop -- aborts if avatar departed during the fetch.

----

== VerifyClient() ==

IUserAgentVerificationModule implementation. Called by Scene.CheckClient() for HG arrivals.

# Gets HomeURI from AgentCircuitData.
# Creates UserAgentServiceConnector.
# Calls security.VerifyClient(SessionID, token) -- HTTP POST to foreign home grid.
# Returns true/false.

----

== Incoming Attachment Processing ==

m_incomingSceneObjectEngine: JobEngine with 30-second stall timeout. One engine per region. Processes HG attachment asset fetches serially per owner (CommonId = OwnerID).

RemoveIncomingSceneObjectJobs(commonId): drains the queue and reinserts all jobs except those matching the given owner UUID. Used on timeout to cancel stuck fetches.

Stat registered: "HGIncomingAttachmentsWaiting" -- pull stat showing queue depth.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/EntityTransferModule]]
* [[OpenSimulator Internals/Code Map/ROBUST/GatekeeperService]]
* [[OpenSimulator Internals/Code Map/ROBUST/UserAgentService]]
* [[OpenSimulator Internals/Connector Architecture/Gatekeeper Connector]]
* [[OpenSimulator Internals/Connector Architecture/UserAgent Connector]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]]

OpenSimulator Internals/Code Map/EntityTransferModule

2026-07-07T13:19:54Z

Jwbshaw: first

= OpenSimulator Internals/Code Map/EntityTransferModule =

== Overview ==

OpenSim/Region/CoreModules/Framework/EntityTransfer/EntityTransferModule.cs

INonSharedRegionModule. Handles all agent movement between regions: teleport (within region and to other regions), region crossing, child agent management, and object crossing. One instance per region.

Registered as IEntityTransferModule. Extended by HGEntityTransferModule for HyperGrid.

----

== Configuration ==

[EntityTransfer] section

{| class="wikitable"
! Key !! Default !! Purpose
|-
| wait_for_callback || true || Source region waits for destination to confirm arrival before closing agent
|-
| DisableInterRegionTeleportCancellation || false || If true, tells viewer to disable cancel button
|}

----

== Event Wiring ==

OnNewClient() hooks per client:

{| class="wikitable"
! Event !! Handler
|-
| OnTeleportHomeRequest || TriggerTeleportHome()
|-
| OnTeleportLandmarkRequest || RequestTeleportLandmark()
|-
| OnTeleportCancel || OnClientCancelTeleport() (if cancellation enabled)
|-
| OnConnectionClosed || OnConnectionClosed()
|}

OnConnectionClosed(): if client IsLoggingOut while in transit, updates transfer state to Aborting.

----

== Transfer State Machine ==

EntityTransferStateMachine tracks per-agent transfer state:

{| class="wikitable"
! State !! Meaning
|-
| (none) || Not in transit
|-
| Transferring || Transfer initiated, past point of no clean abort
|-
| ReceivedAtDestination || Destination confirmed arrival
|-
| CleaningUp || Closing child agents and source agent
|-
| Cancelling || Client requested cancel
|-
| Aborting || Client disconnected during transfer
|}

SetInTransit() / ResetFromTransit() bracket the full operation. UpdateInTransit() moves through states. Failed transitions are logged and abort the operation.

----

== Teleport Entry Point ==

Teleport(ScenePresence sp, ulong regionHandle, Vector3 position, Vector3 lookAt, uint teleportFlags)

# Checks permissions (CanTeleport). Adds Godlike flag if grid god.
# Calls SetInTransit() -- rejects if already in transit.
# If destination handle matches current region after offset check: calls TeleportAgentWithinRegion().
# Otherwise: calls TeleportAgentToDifferentRegion().
# ResetFromTransit() in finally block.

----

== TeleportAgentWithinRegion() ==

Local teleport within the same region.

# Validates position is within region bounds; substitutes emergency pos (128,128,128) if not.
# Raises Z to ground height + avatar half-height.
# Sends TeleportStart to viewer.
# Sends SendLocalTeleport to viewer.
# Sets sp.TeleportFlags, rotates avatar, zeros velocity.
# Calls sp.Teleport(position) -- moves physics actor.
# Fires CHANGED_TELEPORT script event on all attachment SOGs.

----

== TeleportAgentToDifferentRegion() ==

# Calls GetTeleportDestinationRegion() -- GridService.GetRegionByPosition() accounting for varregion offsets.
# Calls GetFinalDestination() (HG hook -- returns same region for normal grid).
# Calls ValidateGenericConditions() (override point).
# Calls DoTeleportInternal().

----

== DoTeleportInternal() ==

Core cross-simulator teleport sequence.

# DNS resolution: finalDestination.ExternalEndPoint.
# Calls SimulationService.QueryAccess() -- destination region confirms it will accept the agent. Returns reason string on refusal.
# Checks sp.Appearance.CanTeleport(ctx.OutboundVersion) -- rejects if outfit incompatible with destination protocol version.
# If avatar sitting: calls sp.StandUp().
# Sets sp.IsInTransit = true.
# Sends TeleportStart to viewer.
# Builds AgentCircuitData for the destination.
# Determines OutSideViewRange -- whether destination already has a child agent or needs a new one.
# Selects protocol version: V2 (>= 0.2) or V1 fallback.

----

== TransferAgent_V2() ==

Current protocol path.

# If OutSideViewRange: removes current region handle from ChildrenCapSeeds.
# Calls CreateAgent() -- SimulationService.CreateAgent() to destination. Fires TeleportStart event.
# Checks cancel/abort state.
# Sets sp.IsChildAgent = true.
# Sends TeleportFinishEvent to viewer immediately (V2 difference from V1: no prior EnableSimulator/EstablishAgentCommunication).
# Builds full AgentData via sp.CopyTo() including appearance, animations, attachments, script states.
# Sets SenderWantsToWaitForRoot = true in AgentData.
# Calls UpdateAgent() -- SimulationService.UpdateAgent() sends full agent state to destination. Blocks until destination's CompleteMovement() fires and returns.
# On UpdateAgent success: calls sp.HasMovedAway(), sp.MakeChildAgent(), CloseChildAgents().
# If NeedsClosing (OutSideViewRange): waits up to 15 seconds for sp.IsInTransit to clear, then calls m_scene.CloseAgent().

----

== TransferAgent_V1() ==

Legacy protocol path (destination protocol < 0.2).

# Calls CreateAgent().
# If OutSideViewRange: sends EnableSimulator + EstablishAgentCommunication via event queue, then sleeps 200ms.
# Sends full AgentData via UpdateAgent().
# Sends TeleportFinishEvent.
# Waits for WaitForAgentArrivedAtDestination() callback -- blocks up to 10 seconds.
# On success: CloseChildAgents(), MakeChildAgent(), CloseAgent() after 2-second sleep (viewer compatibility).

----

== Region Crossing ==

Cross(ScenePresence, isFlying):
* Fires async via WorkManager.RunInThreadPool.
* Calls CrossAsync() → CrossAgentToNewRegionAsync() → CrossAgentIntoNewRegionMain().

CrossAgentIntoNewRegionMain():
# Calls sp.CopyTo(cAgent, isCrossUpdate=true) -- full agent state including cross flags.
# Sets position to projected crossing position.
# Calls SimulationService.UpdateAgent() -- sends state to destination. Destination's IncomingUpdateChildAgent() fires, sets m_originRegionID.
# On success: sets sp.IsChildAgent = true, sends CrossRegion event queue message to viewer.
# CloseChildAgents() for out-of-range neighbours.
# Calls sp.HasMovedAway(), sp.MakeChildAgent().

CrossAsync() detects crossing by projecting position + velocity * 0.2s and calling GetDestination() → GridService.GetRegionByPosition().

----

== Child Agent Management ==

EnableChildAgents(ScenePresence sp):
* Computes neighbours within RegionViewDistance via RegionsInSPView().
* For new neighbours: builds AgentCircuitData, calls CreateAgent() + EnableSimulator + EstablishAgentCommunication.
* For regions no longer in view: calls sp.CloseChildAgents().
* Updates KnownRegions and cap seeds.
* Sends AgentPosition updates to existing known neighbours.
* Neighbour list cached for 30 seconds.

EnableChildAgent(sp, region): single-region version, used when a new neighbour comes online.

CloseOldChildAgents(sp): called from SendInitialData() on login. Closes any child agents not in current view range.

----

== Failure Handling ==

Fail():
* Calls CleanupFailedInterRegionTeleport() -- sets IsChildAgent=false, ReInstantiateScripts(), calls SimulationService.CloseAgent() on destination.
* Sends TeleportFailed to viewer.
* Fires TriggerTeleportFail event.

BannedRegionCache: ExpiringCacheOS keyed by region handle → Dictionary<UUID, expiry>. Regions that refuse QueryAccess are cached for 60 seconds to avoid hammering.

NotFoundLocationCache: Caches region handle positions that returned null from GridService for 30 seconds.

----

== Key Virtual Methods (HG Override Points) ==

{| class="wikitable"
! Method !! Purpose
|-
| GetFinalDestination() || Returns destination region (HG overrides to resolve HG address)
|-
| CreateAgent() || Calls SimulationService.CreateAgent() (HG overrides to set logout flag)
|-
| UpdateAgent() || Calls SimulationService.UpdateAgent()
|-
| AgentHasMovedAway() || Hook after agent departs (HG deletes attachments from scene)
|-
| NeedsClosing() || Whether to close source agent (HG uses different logic)
|-
| ValidateGenericConditions() || Additional pre-flight checks (base returns true)
|}

----

== Object Crossing ==

CrossPrimGroupIntoNewRegion():
* Calls SimulationService.CreateObject() on destination.
* On success: calls scene.DeleteSceneObject() on source.

GetObjectDestination(): projects object position into world coordinates, calls GridService.GetRegionByPosition().

----

== Statistics ==

Four stats registered per region under "entitytransfer" category:
* InterRegionTeleportAttempts
* InterRegionTeleportAborts (simultaneous logout)
* InterRegionTeleportCancels (client cancel)
* InterRegionTeleportFailures (network/server problems)

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Connector Architecture/Simulation Connector]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Logs Out]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]]

OpenSimulator Internals/Code Map/AttachmentsModule

2026-07-07T13:19:05Z

Jwbshaw: first

= OpenSimulator Internals/Code Map/AttachmentsModule =

== Overview ==

OpenSim/Region/CoreModules/Avatar/Attachments/AttachmentsModule.cs

INonSharedRegionModule. Handles all attachment operations: rezzing attachments on login, attaching/detaching objects, saving attachment state to inventory, and transferring attachments between regions. One instance per region.

Registered as IAttachmentsModule. Can be disabled via [Attachments] Enabled=false.

Requires IInventoryAccessModule -- disables itself if unavailable.

----

== Configuration ==

[Attachments] section

{| class="wikitable"
! Key !! Default !! Purpose
|-
| Enabled || true || Enable/disable the module
|-
| WearReplacesAll || true || When attaching to a point, remove all existing attachments at that point
|}

----

== Event Wiring ==

SubscribeToClientEvents() hooks per client:

{| class="wikitable"
! Event !! Handler
|-
| OnRezSingleAttachmentFromInv || Client_OnRezSingleAttachmentFromInv()
|-
| OnRezMultipleAttachmentsFromInv || Client_OnRezMultipleAttachmentsFromInv()
|-
| OnObjectAttach || Client_OnObjectAttach()
|-
| OnObjectDetach || Client_OnObjectDetach()
|-
| OnDetachAttachmentIntoInv || Client_OnDetachAttachmentIntoInv()
|-
| OnObjectDrop || Client_OnObjectDrop()
|}

Scene events:
* OnStartScript / OnStopScript -- sets HasGroupChanged on attachment SOGs when scripts start/stop.

----

== RezAttachments() ==

Called from ScenePresence.CompleteMovement() on real login (IsRealLogin true). Not called for teleports or crossings -- those carry attachments in AgentData.

# Returns immediately if sp.GetAttachmentsCount() > 0 (viewer already rezzed them).
# Fetches all attachment item UUIDs in a single batch: InventoryService.GetMultipleItems().
# For each attachment in sp.Appearance.GetAttachments():
#* Validates item exists and owner matches sp.UUID. If not: removes from appearance.
#* Calls RezSingleAttachmentFromInventoryInternal().
# For NPCs: uses AssetID directly, skips inventory item checks.

; DB reads:
* inventoryitems -- SELECT batch by item UUID array

----

== RezSingleAttachmentFromInventoryInternal() ==

Core rez path for a single attachment.

# Calls IInventoryAccessModule.RezObject() -- fetches asset, deserialises SOG, adds to scene.
# Calls AttachObjectInternal() -- attaches SOG to avatar.
# If doc (saved script state) provided: LoadScriptState() before attach.
# If attach fails: removes SOG from scene and returns null.

----

== AttachObjectInternal() ==

Attaches a SOG already in the scene to an avatar.

# Rejects if any avatars are sitting on the object.
# Resolves attachment point: uses explicit point, or stored LastAttachPoint, or left hand as fallback.
# Rejects if > Constants.MaxAgentAttachments already attached.
# If not appending (WearReplacesAll): collects existing SOGs at same attach point for removal.
# Calls DetachSingleAttachmentToInv() for each displaced attachment.
# Calls UpdateUserInventoryWithAttachment() -- updates inventory item to reflect new attach point.
# Calls AttachToAgent() -- physically attaches SOG to avatar in scene.
# If resumeScripts: CreateScriptInstances() + ResumeScripts().
# Fires EventManager.TriggerOnAttach().

----

== AttachToAgent() ==

Low-level scene attachment.

# Calls m_scene.DeleteFromStorage() -- removes object from region storage.
# Removes physics actors from all parts.
# Sets so.AttachedAvatar, so.AttachmentPoint, so.IsAttachment = true.
# Calls sp.AddAttachment(so).
# For HUD attachments (HasPrivateAttachmentPoint): sends kill packets to all other clients.
# Schedules full update for the SOG.

----

== DetachSingleAttachmentToInv() ==

Detach and save to inventory.

# Calls PrepareScriptInstanceForSave() -- fires detach event, waits 30ms, snapshots script state. Must be done OUTSIDE AttachmentsSyncLock to avoid deadlock.
# Under AttachmentsSyncLock:
#* Calls sp.Appearance.DetachAttachment() -- updates appearance wearables.
#* Calls AvatarFactory.QueueAppearanceSave().
#* Calls sp.RemoveAttachment().
#* Calls UpdateDetachedObject().

UpdateDetachedObject():
* Calls m_scene.DeleteSceneObject() -- removes from scene.
* Clears attachment fields (AttachedAvatar, ParentLocalId, IsAttachment).
* For local grid users (not HG visitors): calls UpdateKnownItem() -- serialises SOG to XML, updates asset and inventory item.
* Calls so.RemoveScriptInstances() + so.Dispose().

UpdateKnownItem():
* Serialises SOG to XML via SceneObjectSerializer.ToOriginalXmlFormat() including script state.
* Recalculates permissions from current prim permissions.
* Creates new asset via m_scene.CreateAsset().
* Calls IInventoryAccessModule.UpdateInventoryItemAsset().
* Sends SendInventoryItemCreateUpdate() to client.

; DB writes (on detach):
* assets -- INSERT: new serialised object asset
* inventoryitems -- UPDATE: new assetID, permissions

----

== DetachSingleAttachmentToGround() ==

Drops attachment to world at position 2.5m in front of avatar.

# Removes from inventory (DeleteItems).
# Clears attachment fields, sets AbsolutePosition.
# Calls so.ApplyPhysics(), so.AttachToBackup().
# Sends SendRemoveInventoryItem() to client.
# Fires TriggerOnAttach(localId, UUID.Zero) -- signals scripts.
# Removes script permissions (take controls, camera).
# Resumes scripts, schedules updates.

; DB writes:
* inventoryitems -- DELETE: removes item from user inventory

----

== CopyAttachments() (for region transfer) ==

CopyAttachments(IScenePresence, AgentData) -- called by ScenePresence.CopyTo() on departure:
* Clones each attachment SOG for transfer.
* Snapshots script state via GetStateSnapshot().
* Stores clones and states in ad.AttachmentObjects / ad.AttachmentObjectStates.

CopyAttachments(AgentData, IScenePresence) -- called by ScenePresence.CopyFrom() on arrival:
* Calls DeleteAttachmentsFromScene() to clear any existing attachments.
* Calls m_scene.IncomingAttechments() [sic -- typo in source] to add transferred SOGs.
* Note: typo IncomingAttechments() in Scene.cs line 2976 and AttachmentsModule.cs (Mantis pending).

----

== DeRezAttachments() ==

Called on avatar departure (not crossing -- crossing uses CopyAttachments).

* For each attachment: PrepareScriptInstanceForSave() then UpdateDetachedObject().
* For NPCs: UpdateDetachedObject() with empty script state.

----

== Known Issues ==

* IncomingAttechments() typo in Scene.cs line 2976 and AttachmentsModule.cs (Mantis pending).
* Comment in source notes that RegionCombiner module accesses SubscribeToClientEvents() and UnsubscribeFromClientEvents() directly, breaking module encapsulation. Marked as needing a fix.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/AvatarFactoryModule]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Change Outfit]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]

OpenSimulator Internals/Code Map/AvatarFactoryModule

2026-07-07T13:18:13Z

Jwbshaw: first

= OpenSimulator Internals/Code Map/AvatarFactoryModule =

== Overview ==

OpenSim/Region/CoreModules/Avatar/AvatarFactory/AvatarFactoryModule.cs

INonSharedRegionModule. Manages avatar appearance: receives baked texture updates from the viewer, validates the baked texture cache on login, queues appearance saves to AvatarService, and sends appearance to other clients. One instance per region.

Registered as IAvatarFactoryModule. Accessed by other modules via m_scene.AvatarFactory.

----

== Configuration ==

[Appearance] section in OpenSim.ini

{| class="wikitable"
! Key !! Default !! Purpose
|-
| DelayBeforeAppearanceSave || 5s || How long to wait after a change before saving to AvatarService
|-
| DelayBeforeAppearanceSend || 2s || How long to wait after a change before sending to other clients
|}

Timer fires every 500ms (m_checkTime) to drain the send and save queues.

----

== Event Wiring ==

SubscribeToClientEvents() hooks per client:

{| class="wikitable"
! Event !! Handler
|-
| OnRequestWearables || Client_OnRequestWearables()
|-
| OnSetAppearance || Client_OnSetAppearance()
|-
| OnAvatarNowWearing || Client_OnAvatarNowWearing()
|}

OnCachedTextureRequest is commented out.

----

== SetAppearance() ==

Main entry point for appearance changes. Called from Client_OnSetAppearance() and from other modules.

# Acquires m_setAppearanceLock (serialises concurrent updates).
# Calls sp.Appearance.SetVisualParams() if visualParams provided -- updates slider values, may change height.
# Calls sp.Appearance.SetTextureEntries() if textureEntry provided -- updates baked texture UUIDs.
# Calls UpdateBakedTextureCache() -- validates and stores baked textures in local asset cache and IBakedTextureModule.
# For NPCs: calls SendAppearance() immediately and returns.
# If appearance changed: calls QueueAppearanceSave().
# Always calls QueueAppearanceSend().

----

== UpdateBakedTextureCache() ==

Called on each texture update from viewer.

# Iterates cacheItems from viewer -- each maps a BakeType index to a CacheId and TextureID.
# For each entry: checks local IAssetCache for the baked texture asset.
# If found: updates WearableCacheItems[idx] with new TextureID and CacheId. Counts as a hit.
# If not found: sends SendRebakeAvatarTextures() to viewer for the missing texture. Throttled via ExpiringKey -- one rebake request per texture per 30 seconds.
# Clears PBR bake indices (>= BAKES_COUNT_PV7) that were not in the update set.
# If all items hit and validDirtyBakes > 0: stores full set to IBakedTextureModule (bake server).

----

== ValidateBakedTextureCache() ==

Called from CompleteMovement() on new root agent arrival (non-HG). Returns true if cache is valid.

# NPCs always return true.
# Checks each bake index: if WearableCacheItems matches face texture and asset is in local cache: hit.
# If local cache invalid and IBakedTextureModule available: fetches from bake server, populates local cache and WearableCacheItems.
# Returns true if hits >= BAKE_INDICES.Length (skirt index 19 is optional).

If ValidateBakedTextureCache returns false: CompleteMovement() calls QueueAppearanceSave() to trigger a rebake cycle.

----

== Queue / Timer Mechanism ==

QueueAppearanceSend(agentId):
* Adds agentId to m_sendqueue with timestamp = now + m_sendtime.
* Starts m_updateTimer.

QueueAppearanceSave(agentId):
* Adds agentId to m_savequeue with timestamp = now + m_savetime.
* Starts m_updateTimer.

HandleAppearanceUpdateTimer() (fires every 500ms):
* Drains m_sendqueue: for each expired entry calls SendAppearance(agentId) -- sp.SendAppearanceToAllOtherAgents() + Animator.SendAnimPack().
* Drains m_savequeue: batches expired entries, runs SaveAppearance() on thread pool.
* Stops timer when both queues empty.

SaveAppearance():
* Calls SetAppearanceAssets() -- resolves each wearable ItemID to AssetID via InventoryService.GetItem().
* Calls m_scene.AvatarService.SetAppearance() -- writes to ROBUST AvatarService → avatarappearance table.

; DB writes (async, via SaveAppearance):
* avatarappearance -- UPDATE: full appearance for avatar UUID

----

== Client_OnAvatarNowWearing() ==

Triggered when viewer sends AvatarIsWearing packet (outfit change initiated).

# Makes a copy of current AvatarAppearance (no lock needed on copy).
# Updates Wearables array from the wearing list -- sets ItemID, AssetID initially UUID.Zero.
# Calls avatAppearance.GetAssetsFrom(sp.Appearance) -- copies known asset IDs from current appearance.
# Under m_setAppearanceLock: updates sp.Appearance.Wearables only (does not overwrite textures or visual params).
# Calls QueueAppearanceSave() -- schedules async inventory lookup and save.

Note: Does NOT call QueueAppearanceSend(). The viewer will follow with OnSetAppearance once baking is done; that triggers the send.

----

== Client_OnRequestWearables() ==

Viewer requests wearable list (e.g. on login or reconnect). Fires async with a 4-second sleep before sending. Calls client.SendWearables(sp.Appearance.Wearables, sp.Appearance.Serial).

----

== SaveBakedTextures() ==

Saves baked textures from local asset cache to permanent AssetService storage. Used for NPCs. Marks assets as non-local, non-temporary, stores via m_scene.AssetService.Store().

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Code Map/ROBUST/AvatarService]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Change Outfit]]

OpenSimulator Internals/Code Map/ScenePresence

2026-07-07T13:17:18Z

Jwbshaw: first

= OpenSimulator Internals/Code Map/ScenePresence =

== Overview ==

OpenSim/Region/Framework/Scenes/ScenePresence.cs

One ScenePresence instance exists per agent per region. It represents the avatar -- whether root (avatar is here) or child (avatar is elsewhere, this is a listening post for interest management). ScenePresence implements IScenePresence and EntityBase.

----

== Lifecycle States ==

Governed by ScenePresenceStateMachine. The critical flag for most code paths is IsChildAgent (bool).

{| class="wikitable"
! State !! IsChildAgent !! Description
|-
| Child || true || Pre-seeded in neighbouring region. Tracks position updates, no physics, no full scene state.
|-
| Root || false || Avatar is present in this region. Full physics, full scene state, heartbeat participation.
|-
| Deleted || -- || IsDeleted set. Dispose() called.
|}

Transition from child to root happens in MakeRootAgent(), called from CompleteMovement(). Transition from root to child happens in MakeChildAgent(), called by EntityTransferModule on departure.

See [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]] for the full transition sequence on login.

----

== Constructor ==

ScenePresence(IClientAPI client, Scene world, AvatarAppearance appearance, PresenceType type)

# Sets IsChildAgent = true.
# Sets draw distance from client.StartFar, clamped to region MaxDrawDistance / DefaultDrawDistance.
# Sets RegionHandle, ControllingClient, name fields, UUID, LocalId.
# Fetches UserAccount -- sets m_userFlags and GodController god level. If no account found, god level 0.
# Initialises ScenePresenceAnimator and MovementAnimationOverrides.
# Sets AbsolutePosition from ControllingClient.StartPos.
# Disables child updates and reprioritization (m_childUpdatesBusy = true, m_reprioritizationBusy = true) -- re-enabled after CompleteMovement.
# Calls AdjustKnownSeeds() -- initialises m_knownChildRegions from CapsModule.
# Calls RegisterToClientEvents() -- see Event Wiring below.
# Sets Appearance from passed AvatarAppearance.
# Constructs ScenePresenceStateMachine.
# Calls ControllingClient.RefreshGroupMembership().

----

== Event Wiring ==

RegisterToClientEvents() hooks the following on ControllingClient:

{| class="wikitable"
! Event !! Handler
|-
| OnCompleteMovementToRegion || CompleteMovement()
|-
| OnAgentUpdate || HandleAgentUpdate()
|-
| OnAgentCameraUpdate || HandleAgentCamerasUpdate()
|-
| OnAgentRequestSit || HandleAgentRequestSit()
|-
| OnAgentSit || HandleAgentSit()
|-
| OnSetAlwaysRun || HandleSetAlwaysRun()
|-
| OnStartAnim || HandleStartAnim()
|-
| OnStopAnim || HandleStopAnim()
|-
| OnChangeAnim || avnHandleChangeAnim()
|-
| OnForceReleaseControls || HandleForceReleaseControls()
|-
| OnAutoPilotGo || MoveToTargetHandle()
|-
| OnRegionHandShakeReply || RegionHandShakeReply()
|}

All removed in RemoveClientEvents() on disposal.

----

== MakeRootAgent() ==

private bool MakeRootAgent(Vector3 pos, bool isFlying, ref Vector3 lookat)

Called only from CompleteMovement(). Returns false if already root.

# Acquires m_completeMovementLock.
# Handles pending sit (ParentUUID set): resolves prim, re-seats avatar.
# Sets IsChildAgent = false.
# Updates RegionHandle.
# Fires EventManager.TriggerSetRootAgentScene().
# If not sitting:
#* Calls CheckAndAdjustLandingPoint_OS() or _SL() -- adjusts position for telehubs, parcel landing points, ban lines.
#* Clamps position to region bounds.
#* Raises Z to ground height + avatar half-height.
#* If ViaLogin or ViaLocation flags: raycasts downward from PhysSearchHeight (300f) using RayFilterFlags.PrimsNonPhantomAgents to find surface, avoids placing avatar inside objects.
#* Sets AbsolutePosition.
#* Calls AddToPhysicalScene(isFlying).
# Calls m_scene.SwapRootAgentCount(false, IsNPC).
# Resets MovementFlags = 0.
# Updates circuit: AuthenticateHandler.UpdateAgentChildStatus(circuitCode, false).
# Fires EventManager.TriggerOnMakeRootAgent(this).

Physics position search constants:
* PhysSearchHeight = 300f
* PhysMinSkipGap = 20f
* PhysSkipGapDelta = 30f
* PhysNumberCollisions = 30

----

== MakeChildAgent() ==

public void MakeChildAgent(ulong newRegionHandle)

Called by EntityTransferModule when avatar departs.

# Resets m_updateAgentReceivedAfterTransferEvent.
# Clears group information and cross-update flags.
# Unhooks RegionHeartbeatEnd.
# Sets IsChildAgent = true.
# Calls m_scene.SwapRootAgentCount(true, IsNPC).
# Calls RemoveFromPhysicalScene().
# Clears parcel tracking.
# Sends kill packets to root presences that don't know the new region (won't receive the avatar as child).
# Updates circuit: AuthenticateHandler.UpdateAgentChildStatus(circuitCode, true).
# Fires EventManager.TriggerOnMakeChildAgent(this).

----

== CompleteMovement() ==

public void CompleteMovement(IClientAPI client, bool openChildAgents)

Triggered by OnCompleteMovementToRegion event from viewer.

* For teleports/crossings: calls WaitForUpdateAgent() -- waits up to 10 seconds for source region's UpdateAgent to arrive (sets m_originRegionID via CopyFrom()).
* For real login (IsRealLogin() true): skips WaitForUpdateAgent().
* Calls MakeRootAgent().
* Sends RegionHandshake if not a crossing.
* Calls ControllingClient.MoveAgentIntoRegion().
* Validates baked texture cache (AvatarFactory.ValidateBakedTextureCache()); queues appearance save if invalid.
* Sends initial avatar data to all presences.
* Sends appearance and animations to self and others.
* For real login: calls Scene.AttachmentsModule.RezAttachments(this).
* For crossing with carried attachments: restarts scripts, sends attachment updates.
* For login: calls IFriendsModule.SendFriendsOnlineIfNeeded().
* Hooks RegionHeartbeatEnd for per-frame processing.

IsRealLogin() check:

(teleportFlags & (ViaLogin | ViaHGLogin)) == ViaLogin

----

== RegionHandShakeReply() / SendInitialData() ==

public void RegionHandShakeReply(IClientAPI client)
private void SendInitialData()

RegionHandShakeReply() sets NeedInitialData = 2 on receipt of viewer handshake reply.

SendInitialData() is called from Update() when NeedInitialData > 0. It waits for:
* ViewerFlags.SentSeeds to be set (caps seeds sent to viewer).
* NeedInitialData incremented to 6 (several heartbeat frames for viewer to process seeds).

Then fires async (Util.FireAndForget):
* Releases source region via SimulationService.ReleaseAgent() if callback URI present.
* Calls IEntityTransferModule.CloseOldChildAgents().
* Sends terrain layer data if not a teleport.
* Sends parcel info.
* Sends full avatar updates for all other root presences (SendOtherAgentsAvatarFullToMe()).
* Sends ObjectUpdate packets for all scene objects -- full updates or cache probes depending on ViewerFlags.
* Calls IEntityTransferModule.EnableChildAgents() -- seeds neighbouring regions.
* Sets m_childUpdatesBusy = false.

----

== Update() ==

Called each heartbeat frame from Scene.Update() for every ScenePresence.

* If NeedInitialData > 0: calls SendInitialData() and returns.
* If IsChildAgent or IsInTransit: returns.
* Calls CheckForBorderCrossing().
* Handles MoveToTarget autopilot updates.
* Handles delayed stop.
* If avatar size changed: sends avatar data to all agents.
* If position, velocity, rotation, or collision plane changed beyond tolerance: calls SendTerseUpdateToAllClients().
* Calls CheckForSignificantMovement().

----

== Physical Scene ==

AddToPhysicalScene(bool isFlying):
* Calls PhysicsScene.AddAvatar() -- creates PhysicsActor.
* Wires pa.OnCollisionUpdate → PhysicsCollisionUpdate().
* Wires pa.OnOutOfBounds → OutOfBoundsCall().
* Sets PhysicsActor = pa.

RemoveFromPhysicalScene():
* Interlocked.Exchange to null (thread-safe).
* Unwires collision and OOB events.
* Calls PhysicsScene.RemoveAvatar().

----

== Neighbour Region Tracking ==

m_knownChildRegions: Dictionary<ulong, string> -- regionHandle → seed cap URL.
m_knownChildRegionsSizeInfo: Dictionary<ulong, spRegionSizeInfo> -- regionHandle → (sizeX, sizeY).

Key methods:
* AddNeighbourRegion() / RemoveNeighbourRegion()
* GetChildAgentsToClose() -- computes which neighbours to close on departure, based on IsOutsideView() distance check (currently hardcoded 255 rather than RegionViewDistance).
* CloseChildAgents() -- sends CloseChildAgentConnections to computed list, drops cap seeds.

----

== Sitting ==

HandleAgentRequestSit() → SendSitResponse() → HandleAgentSit() / PhysicsSit().

PhysicsSit() delegates to PhysicsScene.SitAvatar() with callback PhysicsSitResponse(). Falls back to legacy sit if physics engine doesn't support it.

On sit:
* RemoveFromPhysicalScene().
* ParentID = part.LocalId, ParentPart = part.
* part.AddSittingAvatar(this).
* Animator.SetMovementAnimations("SIT").

StandUp():
* Computes world position from sit offset and prim rotation.
* Clears ParentID, ParentPart.
* Calls AddToPhysicalScene() if addPhys true.
* part.RemoveSittingAvatar(this).
* Animator.SetMovementAnimations("STAND").

SIT_TARGET_ADJUSTMENT = (0, 0, 0.4f) -- empirically derived fudge factor matching SL behaviour (Mantis 1716).

----

== Parcel Visibility ==

ParcelHideThisAvatar: true if current parcel has SeeAVs = false.

On parcel crossing (currentParcelUUID setter → ParcelCrossCheck()):
* Computes which presences need kill packets (now hidden from them or they from us).
* Computes which presences need view packets (now visible).
* Sends kills and views accordingly.

----

== Child Agent Data Transfer ==

CopyTo(AgentData, isCrossUpdate): serialises full avatar state for transfer to destination region -- position, velocity, camera, appearance, animations, attachments, script controls, group info, friends online cache.

CopyFrom(AgentData): deserialises on destination side. Sets m_originRegionID, which signals WaitForUpdateAgent() to unblock CompleteMovement().

UpdateChildAgent(AgentData): called on destination when source fires UpdateAgent. Calls CopyFrom() then sets m_updateAgentReceivedAfterTransferEvent.

UpdateChildAgent(AgentPosition): lightweight position-only update for child agent interest management. Adjusts position by region offset, updates throttles with distance-based scaling factor.

----

== Movement ==

HandleAgentUpdate(): main movement handler. Processes AgentUpdateArgs from viewer each packet.
* Drops updates where IsChildAgent or IsInTransit.
* Updates DrawDistance, HideTitle, MuteCollisions, mouse state, State byte.
* Computes movement vector from control flags.
* Calls AddNewMovement() → sets PhysicsActor.TargetVelocity.
* Calls Animator.UpdateMovementAnimations().
* Calls SendControlsToScripts() -- fires EventManager.TriggerControlEvent for scripted control listeners.

Autopilot: MoveToTarget() / HandleMoveToTargetUpdate() -- PID-style movement toward a target position, used by llMoveToTarget() and parcel enforcement.

Border crossing detection: CheckForBorderCrossing() -- projects position by velocity * FrameTime, if outside region bounds calls CrossToNewRegion() → Scene.CrossAgentToNewRegion().

----

== Attachment Management ==

m_attachments: List<SceneObjectGroup>, locked on AttachmentsSyncLock.

AddAttachment() / RemoveAttachment() / GetAttachments() / ClearAttachments().

SendAttachmentsToAgentNF(): sends terse update then full updates for all attachments to a specific presence.
SendAttachmentScheduleUpdate(): sends pending flagged updates to self and all visible presences.

----

== Animation ==

Animator: ScenePresenceAnimator -- manages animation state machine.
Overrides: MovementAnimationOverrides -- server-side animation override pairs.

HandleStartAnim() / HandleStopAnim() / avnHandleChangeAnim(): viewer-initiated animation control.
RegionHeartbeatEnd hook: calls Animator.UpdateMovementAnimations() every 2 frames when root and not sitting.

----

== Significant Movement ==

CheckForSignificantMovement():
* MOVEMENT (0.25f sq) threshold: fires EventManager.TriggerOnClientMovement().
* SIGNIFICANT_MOVEMENT (16.0f sq) threshold: fires EventManager.TriggerSignificantClientMovement().
* CHILDAGENTSCHECK_MOVEMENT (1024f sq / 32m) threshold: calls IEntityTransferModule.EnableChildAgents() to update neighbour seeds.
* CHILDUPDATES_MOVEMENT (100f sq): sends AgentPosition updates to known child regions.

----

== Key Constants ==

{| class="wikitable"
! Constant !! Value !! Purpose
|-
| MOVEMENT || 0.25f || Minimum movement to trigger client movement event (sq distance)
|-
| SIGNIFICANT_MOVEMENT || 16.0f || Minimum movement to trigger significant movement event (sq distance)
|-
| CHILDUPDATES_MOVEMENT || 100.0f || Minimum movement to send child agent position update (sq distance)
|-
| CHILDAGENTSCHECK_MOVEMENT || 1024.0f || Minimum movement to recheck neighbour child agents (sq distance, ~32m)
|-
| CHILDUPDATES_TIME || 2000f || Minimum ms between child agent updates
|-
| SIT_TARGET_ADJUSTMENT || (0,0,0.4f) || Sit target fudge factor matching SL (Mantis 1716)
|-
| PhysSearchHeight || 300f || Ray cast start height for spawn position search
|-
| PhysMinSkipGap || 20f || Minimum gap between surfaces in spawn position search
|-
| AgentControlNormalVel || 4.096f || Normal walk speed multiplier
|-
| AgentControlMidVel || 0.6 * 4.096f || Slow walk speed multiplier
|}

----

== Known Issues ==

* IncomingAttechments() typo in Scene.cs line 2976 and AttachmentsModule.cs line 384 (Mantis pending).
* GetChildAgentsToClose() uses hardcoded 255 for view distance rather than RegionViewDistance -- comment in source acknowledges this.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Code Map/LLClientView]]
* [[OpenSimulator Internals/Code Map/LLUDP]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Logs Out]]

OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory

2026-07-07T13:15:48Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory =

== Overview ==

Traces what happens when an avatar deletes an item from inventory, moves it to trash, or purges the trash folder. Also covers the Return Object path (estate/parcel manager returning an object to owner's Lost and Found).

----

== Case 1: Delete Item (Move to Trash) ==

Avatar selects an item and deletes it (moves to Trash folder).

=== 1. Client Sends RemoveInventoryItem ===

OpenSim/Region/Framework/Scenes/Scene.cs -- RemoveInventoryItem()

# Viewer sends RemoveInventoryItem packet.
# Scene.RemoveInventoryItem() calls InventoryService.DeleteItems(agentID, [itemID]) if permitted.

Wait -- DeleteItems moves to trash in v2 protocol or deletes directly depending on implementation. In OpenSim's XInventoryService, DeleteItems() marks the item deleted (moves to system trash folder or removes depending on config).

; DB writes:
* inventoryitems -- UPDATE or DELETE depending on server config

----

== Case 2: Purge Folder (Empty Trash) ==

Avatar right-clicks Trash folder and selects Empty Trash.

=== 1. Client Sends PurgeInventoryDescendents ===

# Viewer sends PurgeInventoryDescendents packet with folderID = Trash folder UUID.
# Scene.HandlePurgeInventoryDescendents() calls InventoryService.PurgeFolder(folder).
# ROBUST XInventoryService: deletes all items and subfolders recursively from inventoryitems and inventoryfolders tables.

; DB writes:
* inventoryitems -- DELETE: all items in folder and subfolders
* inventoryfolders -- DELETE: all subfolders (not the trash folder itself)

----

== Case 3: Delete Object from World (DeRez to Trash) ==

Avatar right-clicks object in world and selects Delete (not Take).

=== 1. Client Sends DeRezObject with action=Delete ===

BasicInventoryAccessModule -- CopyToInventory(DeRezAction.Delete)

# If deleting own object: destination folder = Trash (FolderType.Trash).
# If deleting another's object (estate manager): destination = owner's Lost and Found (FolderType.LostAndFound).
# CopyBundleToInventory() runs: serialises object, creates asset, inserts inventory item in appropriate folder.
# Scene.DeleteSceneObject() removes object from scene and region storage.

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: item in Trash or LostAndFound
* prims/primshapes/primitems -- DELETE: object removed from region

----

== Case 4: Return Object (Parcel/Estate Manager) ==

Estate manager or parcel owner returns an object to its owner's inventory.

=== 1. Return Triggered ===

OpenSim/Region/Framework/Scenes/Scene.cs -- returnObjects()

# Parcel manager calls returnObjects() for objects on the parcel.
# Calls IInventoryAccessModule.CopyToInventory(DeRezAction.Return, UUID.Zero, objlist, null, false).
#* remoteClient is null -- return is server-initiated.
#* Destination folder: owner's Lost and Found (FolderType.LostAndFound).
# AddPermissions() with null remoteClient: same-owner path, perms preserved.
# Asset created, item inserted.
# Scene.AddReturn() queues a notification message to the owner.
# Scene.DeleteSceneObject() removes from scene.

On next backup cycle, Scene.Backup() processes m_returns:
* Sends GridInstantMessage to the owner: "Your object X was returned from parcel Y in region Z due to [reason]."

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: item in Lost and Found
* prims/primshapes/primitems -- DELETE

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Case !! Table !! Operation
|-
| Delete item || inventoryitems || UPDATE/DELETE
|-
| Purge folder || inventoryitems, inventoryfolders || DELETE recursive
|-
| Delete object || assets, inventoryitems || INSERT; prims DELETE
|-
| Return object || assets, inventoryitems || INSERT; prims DELETE
|}

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]

OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory

2026-07-07T13:14:30Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory =

== Overview ==

Traces what happens in code, connectors, and database when an avatar rezzes an object from inventory into the world.

----

== 1. Client Sends RezObject ==

OpenSim/Region/Framework/Scenes/Scene.cs -- RezObject()

# Viewer sends RezObject packet with itemID, ray start/end, and rez flags.
# Scene.RezObject() calls IInventoryAccessModule.RezObject().

----

== 2. Item and Asset Fetched ==

BasicInventoryAccessModule -- RezObject()

# Calls InventoryService.GetItem(agentID, itemID) -- reads inventoryitems table.
# Validates item exists and is owned by agent.
# Calls AssetService.Get(assetID) -- fetches object XML asset.
# If asset null or empty: sends alert to client, returns null.

For HG foreign users (HGInventoryAccessModule):
* If IsForeignUser: calls m_assMapper.Get(item.AssetID, agentID, foreignAssetServer) before asset fetch -- pulls asset from foreign grid if not cached locally.

; DB reads:
* inventoryitems -- SELECT by item UUID
* assets -- SELECT by asset UUID

----

== 3. Deserialise and Position ==

BasicInventoryAccessModule -- RezObject() continued

# Calls Scene.GetObjectsToRez() -- deserialises XML into List<SceneObjectGroup> and position offsets.
#* Single object: SceneObjectSerializer.FromOriginalXmlFormat().
#* Coalesced: CoalescedSceneObjectsSerializer.FromXml().
# Calls Scene.GetNewRezLocation() -- raycasts from RayStart to RayEnd against physics scene to find surface position.
# Checks CanRezObject permission at target position.
# If no-copy item fails perm check: sends SendBulkUpdateInventory to restore item to client display.

----

== 4. Ownership and Permissions Applied ==

BasicInventoryAccessModule -- DoPreRezWhenFromItem()

# Sets rootPart.Name and Description from inventory item (single object only).
# Applies ObjectSlamSale if flagged.
# Sets FromFolderID on SOG.
# If ownership change (new owner or Slam flag):
#* Changes OwnerID on all parts, sets LastOwnerID, calls Inventory.ChangeInventoryOwner().
#* Calls ApplyNextOwnerPermissions() -- applies NextOwnerMask to BasePermissions.
#* Applies any ObjectOverwrite flags from item.
# If same owner: sets FromUserInventoryItemID if item is copyable (links rezzed object back to inventory item for "save changes" support).
# Calls TrimPermissions() and InvalidateDeepEffectivePerms().

----

== 5. Object Added to Scene ==

BasicInventoryAccessModule -- RezObject() continued

# group.ResetIDs() -- assigns new UUIDs to all parts.
# Clears attachment data (ClearPartAttachmentData()).
# Sets IsSelected if RezSelected flag.
# Sets AbsolutePosition from ray result.
# Calls Scene.AddNewSceneObject(group, true, false) -- adds to scene graph, schedules persistence.
# Calls CreateScriptInstances(0, true, DefaultScriptEngine, 1) -- starts scripts with on_rez state source.
# Calls ResumeScripts().
# Schedules full update to clients.

; DB writes:
* prims -- INSERT: new prim rows for each part
* primshapes -- INSERT: shape data for each part
* primitems -- INSERT: task inventory for each part

----

== 6. No-Copy Item Removed from Inventory ==

BasicInventoryAccessModule -- DoPostRezWhenFromItem()

# If item.CurrentPermissions has no Copy bit: calls InventoryService.DeleteItems(owner, [itemID]).
# Item is consumed on rez.

; DB writes (no-copy only):
* inventoryitems -- DELETE: item removed

----

== 7. HG Asset Push (HG users only) ==

Not applicable on standard rez. HG asset push (ExportAsset) is triggered on CopyToInventory, not on rez.

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Operation !! Notes
|-
| inventoryitems || SELECT || Fetch item record
|-
| assets || SELECT || Fetch object XML
|-
| prims || INSERT || New object in region
|-
| primshapes || INSERT || Shape data
|-
| primitems || INSERT || Task inventory per part
|-
| inventoryitems || DELETE || No-copy items only
|}

----

== Edge Cases ==

Attachment rez (from RezAttachments or RezSingleAttachmentFromInventory): uses same RezObject() path but attachment=true. AddNewSceneObject() is called without script start (scripts start later in AttachToAgent). See [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]].

Coalesced object: multiple SOGs deserialised from one asset, each positioned using the stored offsets from CoalescedSceneObjectsSerializer. Each gets its own DB rows.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]

OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory

2026-07-07T13:13:00Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory =

== Overview ==

Traces what happens in code, connectors, and database when an avatar acquires an object into inventory. Covers three cases:

# Taking a copyable object from the world (Take Copy).
# Taking a no-copy object from the world (Take / derez).
# Buying an object from another avatar or vendor (buy object).

Avatar-to-avatar direct inventory transfer (Give Inventory) is a separate flow not covered here.

----

== Case 1: Take Copy (copyable object) ==

Avatar right-clicks an object they have copy permission on and selects Take Copy.

=== 1. Client Sends DeRezObject ===

OpenSim/Region/Framework/Scenes/Scene.cs -- DeRezObjects()

# Viewer sends DeRezObject packet with action = TakeCopy.
# Scene.DeRezObjects() fires.
# Permission check: CanTakeObject() for the SOG.
# If passing: calls IInventoryAccessModule.CopyToInventory(DeRezAction.TakeCopy, folderID, objlist, remoteClient, false).
# Object remains in scene -- Take Copy does not delete it.

=== 2. Object Serialised to Asset ===

BasicInventoryAccessModule -- CopyBundleToInventory()

# Suspends keyframe motion.
# Records current world position/rotation.
# Serialises SOG to XML via SceneObjectSerializer.ToOriginalXmlFormat() (single object) or CoalescedSceneObjectsSerializer (multiple selected).
# Restores position.
# Calls CreateItemForObject(TakeCopy):
#* Destination folder: Object folder (FolderType.Object).
#* Owner: remoteClient.AgentId.
# Calls AddPermissions() -- same-owner path: copies current perms, preserves folded bits, applies NextOwnerMask to NextPermissions.
# Creates asset: UUID.Random(), AssetType.Object, stores via AssetService.Store().
# Calls Scene.AddInventoryItem() → InventoryService.AddItem().
# Sends SendInventoryItemCreateUpdate() to client.

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: new item in Object folder

=== 3. HG Asset Post (HG users only) ===

HGInventoryAccessModule -- ExportAsset()

If avatar is a foreign HG user and OutboundPermission=true:
* m_assMapper.Post(assetID, agentID, foreignAssetServer) -- HTTP POST to push asset to foreign grid.

----

== Case 2: Take (no-copy object, or owner taking back own object) ==

Avatar takes a no-copy object, or picks up their own placed object.

=== 1. Client Sends DeRezObject ===

# Viewer sends DeRezObject packet with action = Take.
# Same permission check path.
# Calls IInventoryAccessModule.CopyToInventory(DeRezAction.Take, folderID, objlist, remoteClient, false).

=== 2. Object Serialised (same as Take Copy) ===

CopyBundleToInventory() with Take:
* Destination folder: original FromFolderID if owner taking back own item and folder still valid; otherwise Object folder.
* Asset created and stored, inventory item inserted.

=== 3. Object Removed from Scene ===

DoPostRezWhenFromItem():
* If item is no-copy (CurrentPermissions & Copy == 0): InventoryService.DeleteItems() removes item from inventory first (item was previously there for the no-copy object).

Scene.DeRezObjects() also:
* Calls DeleteSceneObject() -- removes SOG from scene graph, removes from SimulationDataService (prims table).

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: new item (or UPDATE if SaveToExisting)
* inventoryitems -- DELETE: original no-copy item if applicable
* prims/primshapes -- DELETE: object removed from region storage

----

== Case 3: Buy Object ==

Avatar buys an object set for sale (right-click → Buy).

=== 1. Client Sends ObjectBuy ===

OpenSim/Region/Framework/Scenes/Scene.cs -- ProcessObjectBuy() (via IBuySellModule)

# Viewer sends ObjectBuy packet with price.
# IBuySellModule.BuyObject() called.
# Checks sale type and price.
# If sale type is Copy: calls IInventoryAccessModule.CopyToInventory(DeRezAction.TakeCopy) -- same as Take Copy path above. Object stays in scene.
# If sale type is Original: calls IInventoryAccessModule.CopyToInventory(DeRezAction.Take). Object leaves scene.
# If sale type is Contents: copies contents of the object's inventory to buyer's inventory, not the object itself (separate path via task inventory).

Money transfer (if price > 0):
* IBuySellModule calls IMoneyModule.ObjectBuy() -- money transfer between accounts. This is grid-specific; base OpenSim has no money module by default.

; DB writes (object sale):
* Same as Take or Take Copy depending on sale type.

----

== Permissions Applied on Acquire ==

AddPermissions() is the key method. Two paths:

New owner (buyer or taker who is not the original owner) and PropagatePermissions=true:
* effectivePerms = intersection of all parts' CurrentAndFoldedNextPermissions().
* Applies PermissionsUtil.ApplyNoModFoldedPermissions().
* basePerms = effectivePerms & RootPart.NextOwnerMask.
* Fixes and folds: PermissionsUtil.FixAndFoldPermissions().
* Sets ObjectSlamPerm flag -- permissions applied again on rez.

Same owner (taking back own object):
* effectivePerms = intersection of current perms.
* NextPermissions = RootPart.NextOwnerMask & effectivePerms.
* No slam flag.

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Operation !! Case
|-
| assets || INSERT || All cases: new serialised object asset
|-
| inventoryitems || INSERT || All cases: new inventory item
|-
| inventoryitems || DELETE || No-copy Take: removes existing item
|-
| prims/primshapes/primitems || DELETE || Take (no-copy) or Take (own object): removes from region
|}

----

== HG Suitcase Note ==

When a local user is abroad (HG), ProcessInventoryForHypergriding() has renamed their non-suitcase folders to "(Unavailable)". Items they acquire while abroad go into My Suitcase (the only accessible folder). On return home, ProcessInventoryForComingHome() restores the full inventory view.

Foreign users acquiring objects: ExportAsset() posts the asset to their home grid's asset server if OutboundPermission=true.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]

OpenSimulator Internals/Walkthroughs/Avatar Goes HG

2026-07-07T13:11:03Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Goes HG =

== Overview ==

Traces what happens in code, connectors, and database when an avatar HyperGrid teleports from their home grid to a foreign grid, and when they return.

Assumes the home grid runs ROBUST + OpenSim with HGEntityTransferModule enabled.

----

== Part 1: Departing the Home Grid ==

=== 1. HG Destination Resolved ===

OpenSim/Region/CoreModules/Framework/EntityTransfer/HGEntityTransferModule.cs -- GetFinalDestination()
OpenSim/Services/Connectors/Hypergrid/GatekeeperServiceConnector.cs

# Avatar clicks a HG link or enters a HG URI (e.g. hg.example.com:8002:RegionName).
# GridService on source region looks up the destination -- finds a region with RegionFlags.Hyperlink set. This is a local stub entry, not a real region.
# GetFinalDestination() detects the Hyperlink flag.
# Calls GatekeeperServiceConnector.GetHyperlinkRegion() -- HTTP POST to the foreign grid's Gatekeeper service (hg.example.com:8002).
#* Gatekeeper validates the request and returns a real GridRegion descriptor for the destination on the foreign grid.
# ValidateGenericConditions() checks appearance restrictions if RestrictAppearanceAbroad=true.

=== 2. Pre-flight at Foreign Gatekeeper ===

EntityTransferModule -- DoTeleportInternal()

# SimulationService.QueryAccess() -- HTTP POST to destination simulator on foreign grid.
#* Destination checks ban list, parcel access, agent limit.
# sp.Appearance.CanTeleport() -- checks outfit compatibility with destination protocol version.

=== 3. Agent Created at Foreign Grid ===

HGEntityTransferModule -- CreateAgent() override

# Detects Hyperlink destination.
# Checks local user's UserLevel >= LevelHGTeleport. Refuses if insufficient.
# Gets HomeURI from agentCircuit.ServiceURLs.
# Creates UserAgentServiceConnector for home grid's UserAgent service.
# Calls UserAgentService.LoginAgentToGrid(source, agentCircuit, gatekeeperRegion, finalDestination, false) -- HTTP POST to home grid's UserAgent service.
#* Home UserAgent service validates the request.
#* Home UserAgent service calls foreign Gatekeeper.CreateAgent() -- HTTP POST to foreign gatekeeper.
#* Foreign Gatekeeper validates, calls foreign destination simulator's NewUserConnection.
#* Returns success.
# Sets logout = true -- this agent will be logged out of home grid.
# Fires TriggerTeleportStart.

=== 4. Agent State Sent ===

Same as standard teleport (see [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]] steps 5-6):

# sp.IsChildAgent = true set on source.
# TeleportFinishEvent sent to viewer with foreign destination endpoint and caps URL.
# AgentData built via sp.CopyTo() -- includes appearance, attachments with script states.
# SimulationService.UpdateAgent() -- HTTP POST to foreign destination simulator.
#* Foreign destination's IncomingUpdateChildAgent() → CopyFrom() fires.
# UpdateAgent() waits for avatar to become root at destination.

=== 5. Source Grid Logs Out Agent ===

HGEntityTransferModule -- AgentHasMovedAway() override

Called after UpdateAgent() returns successfully:

# sp.HasMovedAway() -- sends kill packets for non-HUD attachments, handles parcel visibility.
# sp.MakeChildAgent() -- source becomes child.
# sp.closeAllChildAgents() -- closes all neighbour child agents (logout=true path).
# AgentHasMovedAway() fires:
#* PresenceService.LogoutAgent(sessionID) -- marks agent offline on home grid.
#* GridUserService.LoggedOut(userID, ...) -- updates home grid's griduser with last position.
# NeedsClosing() returns true for HG (always) -- CloseAgent() called on source after delay.

; DB writes (home grid):
* presence -- UPDATE: Online=0
* griduser -- UPDATE: LastPosition, Logout timestamp

=== 6. Avatar Arrives at Foreign Grid ===

Foreign destination's CompleteMovement() fires when viewer sends CompleteMovementToRegion.

Standard arrival sequence (see [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]) with HG differences:

* TeleportFlags.ViaHGLogin is set -- baked texture validation skipped (AvatarFactory.ValidateBakedTextureCache() not called for HG).
* Attachments carried in AgentData. HandleIncomingAttachments() called.
* For HGLogin: HGEntityTransferModule.HandleIncomingAttachments() queues async asset fetch:
#* HGUuidGatherer walks each attachment SOG, collects all referenced asset UUIDs.
#* Fetches each asset from home grid's AssetServerURI (from AgentCircuitData.ServiceURLs).
#* 30-second timeout per asset fetch. On timeout: cancels all pending jobs for this avatar.
#* On completion: base.HandleIncomingAttachments() adds SOGs to scene.
* Foreign grid does NOT write to home grid's databases. Avatar's home presence/griduser records are already marked offline (step 5).

; DB writes (foreign grid):
* None for standard avatar data. Foreign grid may cache fetched assets locally.

----

== Part 2: Returning Home ==

=== 1. TeleportHome Initiated ===

HGEntityTransferModule -- TeleportHome()

# Avatar clicks "Teleport Home" or script calls llTeleportAgentHome().
# HGEntityTransferModule.TeleportHome() detects foreign user (IsLocalGridUser returns false).
# Gets HomeURI from AgentCircuitData.ServiceURLs.
# Creates UserAgentServiceConnector for home grid.
# Calls UserAgentService.GetHomeRegion(agentID) -- HTTP GET to home grid's UserAgent service.
#* Home UserAgent reads griduser table for HomeRegionID, HomePosition, HomeLookAt.
#* Returns GridRegion descriptor for home region.
# Constructs Gatekeeper GridRegion from HomeURI.
# Calls DoTeleport() with ViaHome flag.

=== 2. Home Grid Re-entry ===

Same protocol as any HG teleport but in reverse -- foreign grid is now source, home grid is destination.

Home grid's Gatekeeper receives CreateAgent request. Home grid validates. Home grid's NewUserConnection() fires. Standard arrival sequence.

On home grid arrival:
* TeleportFlags.ViaHGLogin is set.
* Home grid does NOT call PresenceService.LoginAgent() again -- the session was already established on initial login. A new session is established via the Gatekeeper flow.
* Baked texture validation skipped.
* Appearance data arrived via AgentData -- if RestrictAppearanceAbroad was enforced, avatar may arrive in restricted appearance.

=== 3. Foreign Grid Logs Out ===

HGEntityTransferModule -- AgentHasMovedAway() (foreign grid side)
HGEntityTransferModule -- OnConnectionClosed()

# AgentHasMovedAway() with logout=true:
#* PresenceService.LogoutAgent() on foreign grid (clears foreign presence record if any).
#* GridUserService.LoggedOut() on foreign grid.
# OnConnectionClosed() fires when viewer disconnects from foreign grid:
#* For foreign user: calls UserAgentServiceConnector(homeURI).LogoutAgent() -- HTTP POST to home grid's UserAgent service notifying of departure.

----

== Part 3: HG Landmark Teleport ==

HGEntityTransferModule -- RequestTeleportLandmark()

# Landmark contains Gatekeeper URI + RegionID + position.
# If gatekeeper is local grid: falls back to normal landmark teleport.
# If foreign gatekeeper:
#* DNS-resolves the gatekeeper host.
#* Calls GatekeeperServiceConnector.GetHyperlinkRegion() -- resolves RegionID to GridRegion on foreign grid.
#* Calls ValidateGenericConditions() (appearance check).
#* Calls DoTeleport() -- standard HG teleport from here.

----

== Client Verification ==

HGEntityTransferModule -- VerifyClient()

Called by Scene.CheckClient() on first HTTP contact from a foreign avatar's viewer.

# Gets HomeURI.
# Calls UserAgentServiceConnector(homeURI).VerifyClient(SessionID, token).
#* Home grid's UserAgent service confirms the session is valid.
# Returns false → scene removes circuit and closes agent.

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Grid !! Operation !! Step
|-
| presence || Home || UPDATE: Online=0 || Source logs out (step 5)
|-
| griduser || Home || UPDATE: LastPosition, Logout || Source logs out (step 5)
|-
| assets || Foreign || INSERT: fetched attachment assets || Incoming asset fetch (step 6)
|-
| presence || Foreign || UPDATE: session cleanup || Return/logout (part 2 step 3)
|-
| griduser || Foreign || UPDATE: LastPosition || Return/logout (part 2 step 3)
|}

----

== Key HG-specific Differences from Standard Teleport ==

{| class="wikitable"
! Aspect !! Standard Teleport !! HG Teleport
|-
| CreateAgent || SimulationService.CreateAgent() direct || UserAgentService.LoginAgentToGrid() via home grid
|-
| logout flag || false || true
|-
| Source logs out || No || Yes (PresenceService + GridUserService)
|-
| NeedsClosing || Only if OutViewRange || Always
|-
| Attachment fetch || Carried in AgentData || Async HGUuidGatherer from foreign AssetServer
|-
| Baked texture validation || Yes || No (ViaHGLogin)
|-
| OnConnectionClosed || Base handler || Also notifies home UserAgent service
|-
| TeleportHome || GridUserService.GetHomeRegion || UserAgentService.GetHomeRegion
|}

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/EntityTransferModule]]
* [[OpenSimulator Internals/Code Map/ROBUST/GatekeeperService]]
* [[OpenSimulator Internals/Code Map/ROBUST/UserAgentService]]
* [[OpenSimulator Internals/Connector Architecture/Gatekeeper Connector]]
* [[OpenSimulator Internals/Connector Architecture/UserAgent Connector]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]

OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions

2026-07-07T13:09:43Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions =

== Overview ==

Traces what happens in code, connectors, and database when an avatar teleports from one region to another on the same grid. Covers the V2 protocol path (protocol version >= 0.2), which is the current standard.

For region border crossing (walking/flying across a boundary), see the Crossing section below. For HG teleport, see [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]].

----

== Part 1: Teleport ==

=== 1. Teleport Requested ===

OpenSim/Region/Framework/Scenes/Scene.cs -- RequestTeleportLocation()
OpenSim/Region/CoreModules/Framework/EntityTransfer/EntityTransferModule.cs -- Teleport()

# Viewer sends TeleportLocationRequest packet (or map click, lure, landmark).
# Scene.RequestTeleportLocation() gets ScenePresence, checks not deleted/in transit, calls EntityTransferModule.Teleport().
# EntityTransferModule.Teleport():
#* Checks CanTeleport permissions.
#* Calls SetInTransit() -- rejects if already in transit.
#* Calls Util.CompareRegionHandles() to determine if destination is within current region bounds.
#* If same region: calls TeleportAgentWithinRegion() -- local move, no inter-region protocol.
#* If different region: calls TeleportAgentToDifferentRegion().

=== 2. Destination Lookup ===

EntityTransferModule -- TeleportAgentToDifferentRegion() → GetTeleportDestinationRegion()

# Calls GridService.GetRegionByPosition() -- HTTP GET to ROBUST GridService.
#* ROBUST reads regions table, returns GridRegion for the destination.
# Calls GetFinalDestination() -- on base class returns same region (HG override resolves foreign address).
# Calls ValidateGenericConditions() -- base class returns true (override point).

; DB reads (on ROBUST side):
* regions -- SELECT by world position

=== 3. Pre-flight Checks ===

EntityTransferModule -- DoTeleportInternal()

# DNS resolution: finalDestination.ExternalEndPoint.
# Calls SimulationService.QueryAccess() -- HTTP POST to destination simulator's QueryAccess endpoint.
#* Destination calls Scene.QueryAccess(): checks ban list, parcel access, agent limit, AllowAvatarCrossing.
#* Returns true/false + reason string.
# Checks sp.Appearance.CanTeleport(ctx.OutboundVersion) -- rejects if outfit incompatible with destination protocol version.
# If avatar sitting: calls sp.StandUp().
# Sets sp.IsInLocalTransit, sp.IsInTransit = true.
# Sends TeleportStart to viewer.

=== 4. Create Agent at Destination (V2) ===

EntityTransferModule -- TransferAgent_V2() → CreateAgent()

# Builds AgentCircuitData for the destination -- includes caps path, start position, appearance height.
# Determines OutSideViewRange: whether destination is outside current draw distance (needs new child agent vs reusing existing one).
# Calls SimulationService.CreateAgent() -- HTTP POST to destination simulator's NewAgentIn endpoint.
#* Destination calls Scene.NewUserConnection() with the AgentCircuitData.
#* NewUserConnection() validates presence, authorises user, sets up caps, adds circuit.
#* Returns success/failure + reason.
# If failed: sends TeleportFailed to viewer, clears transit state.
# Fires EventManager.TriggerTeleportStart on source.

=== 5. Send TeleportFinish to Viewer ===

EntityTransferModule -- TransferAgent_V2()

# Sets sp.IsChildAgent = true on source (before UpdateAgent, to prevent race with destination requesting a child close).
# Sends TeleportFinishEvent via IEventQueue -- gives viewer: destination handle, endpoint, caps seed URL, teleport flags.
# Viewer receives TeleportFinish and begins connecting to destination simulator.

=== 6. Send Full Agent State to Destination ===

EntityTransferModule -- TransferAgent_V2() → UpdateAgent()
ScenePresence -- CopyTo()

# Builds AgentData via sp.CopyTo(agent, isCrossUpdate=false):
#* Position, velocity, camera axes.
#* Appearance (full AvatarAppearance copy).
#* Animations, animation overrides, motion state.
#* Attachment SOGs (cloned via AttachmentsModule.CopyAttachments()) with script states.
#* Script controls, god data, group info, friends online cache.
#* Sets SenderWantsToWaitForRoot = true.
# Calls SimulationService.UpdateAgent() -- HTTP POST to destination simulator.
#* Destination calls Scene.IncomingUpdateChildAgent(AgentData).
#* Destination's ScenePresence.UpdateChildAgent() calls CopyFrom() which sets m_originRegionID.
#* If SenderWantsToWaitForRoot: destination waits (up to 25s polling) for sp.IsChildAgent to become false (CompleteMovement fires when viewer sends CompleteMovementToRegion).
#* Returns true when avatar is root at destination.
# UpdateAgent() blocks on source until destination returns.

=== 7. Avatar Becomes Root at Destination ===

ScenePresence -- CompleteMovement() (destination side)

# Viewer sends CompleteMovementToRegion to destination simulator.
# Destination CompleteMovement() fires (see [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]] steps 3-5 for detail).
# Key difference from login: WaitForUpdateAgent() waits up to 10s for m_originRegionID to be set (set by UpdateAgent arriving). For teleport this is not skipped.
# MakeRootAgent() called -- physics actor created, position adjusted.
# Avatar data sent to all presences at destination.
# Attachments: for teleport (not IsRealLogin), attachments were carried in AgentData. Scripts restarted via RestartAttachmentScripts() rather than RezAttachments().

=== 8. Source Cleans Up ===

EntityTransferModule -- TransferAgent_V2() (source, after UpdateAgent returns)

# Calls sp.HasMovedAway(nearRegion) -- if nearRegion (within view range and not logout): calls AttachmentsModule.DeleteAttachmentsFromScene() for non-HUD attachments; sends kill packets to presences that won't see the avatar in the new region.
# Calls sp.MakeChildAgent(destinationHandle) -- source presence becomes child. Physics removed. OnMakeChildAgent fires.
# Closes child agents: sp.CloseChildAgents(childRegionsToClose) or sp.closeAllChildAgents() for logout=true.
# If NeedsClosing (OutSideViewRange): waits up to 15s for sp.IsInTransit to clear, then calls m_scene.CloseAgent() -- fully removes source presence.
# If within view range (not NeedsClosing): source keeps a child agent. sp.IsInTransit = false.

; No DB writes at source during teleport. Attachment saves happen at logout/detach, not on teleport.

=== 9. GridUser Updated at Destination ===

After CompleteMovement() completes at destination, the region updates position:

# GridUserService.SetLastPosition() -- updates griduser table with new RegionID, position, look.

; DB writes:
* griduser -- UPDATE: LastRegionID, LastPosition, LastLookAt

=== 10. PresenceService Updated ===

# PresenceService.ReportAgent() (or equivalent) -- updates presence table with new RegionID.

; DB writes:
* presence -- UPDATE: RegionID to destination region

----

== Part 2: Region Border Crossing ==

Border crossing is initiated by the source region's physics simulation, not the viewer.

=== 1. Border Detected ===

ScenePresence -- CheckForBorderCrossing() (called each heartbeat frame from Update())

# Checks not IsChildAgent, not IsInTransit, not sitting, PhysicsActor != null.
# Projects position: pos + velocity * FrameTime.
# If projected position is outside region bounds: calls Scene.CrossAgentToNewRegion().
# Scene.CrossAgentToNewRegion() checks AllowAvatarCrossing flag, then calls EntityTransferModule.Cross().

=== 2. Destination Found ===

EntityTransferModule -- Cross() → CrossAsync() → CrossAgentToNewRegionAsync()

# Cross() fires async via WorkManager.RunInThreadPool.
# CrossAsync():
#* Projects pos + velocity * 0.2s.
#* Calls GetDestination() -- GridService.GetRegionByPosition() for the projected world position.
#* Calls SimulationService.QueryAccess() -- checks destination will accept avatar.
#* Removes avatar from physics: sp.RemoveFromPhysicalScene().
# Calls CrossAgentIntoNewRegionMain().

=== 3. Agent State Sent to Destination ===

EntityTransferModule -- CrossAgentIntoNewRegionMain()

# Builds AgentData via sp.CopyTo(cAgent, isCrossUpdate=true):
#* Sets CrossingFlags |= 1.
#* Includes CrossExtraFlags for mouse button state.
#* Attachments copied with script states.
# Calls SimulationService.UpdateAgent() -- HTTP POST to destination.
#* Note: for crossing, CreateAgent() is NOT called first if destination already has a child agent. UpdateAgent() is called directly.
#* Destination IncomingUpdateChildAgent() fires, sp.UpdateChildAgent() → CopyFrom() sets m_gotCrossUpdate=true.
# Sets sp.IsChildAgent = true.
# Sends CrossRegion event queue message to viewer -- gives destination handle, position, velocity, endpoint, caps path.
# Calls sp.HasMovedAway() and sp.MakeChildAgent().
# ResetFromTransit() called -- clears transit state.

If UpdateAgent fails (region refused):
# Calls ReInstantiateScripts() -- restores attachment scripts from InTransitScriptStates.
# Calls sp.AddToPhysicalScene() -- puts avatar back in physics.
# Returns false -- CheckForBorderCrossing() calls sp.CrossToNewRegionFail() which repositions avatar inside the region.

=== 4. Avatar Becomes Root at Destination ===

Destination side CompleteMovement() fires when viewer sends CompleteMovementToRegion:

# m_gotCrossUpdate = true (set by CopyFrom).
# WaitForUpdateAgent() skipped for crossing (not teleport -- no SenderWantsToWaitForRoot set for crossing path).
# MakeRootAgent() called. Physics created. Position from AgentData.
# SendRegionHandshake() skipped (not a crossing -- m_gotCrossUpdate suppresses it).
# MoveAgentIntoRegion() sends viewer its new position.
# Attachments: scripts restarted via RestartAttachmentScripts() (not RezAttachments).
# EnableChildAgents() seeds new neighbours.

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Operation !! Step !! Notes
|-
| regions || SELECT || Destination lookup (step 2) || ROBUST GridService
|-
| griduser || UPDATE || Post-arrival at destination (step 9) || LastRegionID, LastPosition
|-
| presence || UPDATE || Post-arrival at destination (step 10) || RegionID
|}

No asset or inventory writes occur during a normal teleport or crossing. Attachments are carried in AgentData in memory; they are only written to assets/inventory on detach or logout.

----

== Key Differences: Teleport vs Crossing ==

{| class="wikitable"
! Aspect !! Teleport !! Crossing
|-
| Initiator || Viewer request || Physics / heartbeat frame
|-
| Protocol || CreateAgent then UpdateAgent || UpdateAgent only (if child exists)
|-
| Viewer notification || TeleportFinish event queue || CrossRegion event queue
|-
| Script state || Snapshotted in CopyTo, restored via RestartAttachmentScripts || Same
|-
| isCrossUpdate flag || false || true
|-
| WaitForUpdateAgent || Yes (up to 10s) || No
|-
| m_gotCrossUpdate || false || true
|-
| RegionHandshake sent || Yes (if not crossing) || No
|-
| Source closes || If OutSideViewRange, after 15s || Immediately (MakeChildAgent)
|}

----

== Failure Modes ==

Teleport failure after CreateAgent (destination created but viewer can't connect):
* UpdateAgent() times out after ~10s.
* Fail() called: CleanupFailedInterRegionTeleport() -- SimulationService.CloseAgent() to destination, sp.IsChildAgent=false, scripts re-instantiated.
* TeleportFailed sent to viewer.

Crossing failure (UpdateAgent to destination fails):
* ReInstantiateScripts() restores attachment scripts.
* sp.AddToPhysicalScene() restores physics.
* sp.CrossToNewRegionFail() repositions avatar inside region bounds.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/EntityTransferModule]]
* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Connector Architecture/Simulation Connector]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Logs Out]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]]

OpenSimulator Internals/Walkthroughs/Avatar Logs Out

2026-07-07T13:06:06Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Logs Out =

== Overview ==

Traces what happens in code, connectors, and database when an avatar logs out normally. Covers both viewer-initiated logout and region-initiated close.

This does not cover region crossing or teleport departure -- see [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]].

----

== 1. Logout Initiated ==

=== Viewer-initiated ===

OpenSim/Region/ClientStack/Linden/UDP/LLClientView.cs

# Avatar clicks Logout in viewer.
# Viewer sends LogoutRequest UDP packet.
# LLClientView.HandleLogout() fires. Sets IsLoggingOut = true on the client.
# Calls Scene.CloseAgent(agentID, force=false).

=== Region-initiated (admin kick or simulator shutdown) ===

# Console command or admin API calls Scene.CloseAgent(agentID, force=true).
# Or: LLClientView.OnConnectionClosed fires when viewer connection drops; EntityTransferModule.OnConnectionClosed() sets transfer state to Aborting if in transit.

----

== 2. Scene.CloseAgent() ==

OpenSim/Region/Framework/Scenes/Scene.cs -- CloseAgent()

Under m_removeClientLock:

# Gets ScenePresence. If null or IsDeleted: removes from clientManager, authenticateHandler, capsModule directly and returns.
# Checks LifecycleState -- must be Running or PreRemove to proceed.
# Checks DoNotCloseAfterTeleport -- if true (another region renewed the child connection), resets flag and returns false without closing.
# Sets sp.LifecycleState = Removing.

Then outside the lock:

# Calls sp.ControllingClient.Close(force, force) -- this triggers RemoveClient() via the client stack.
# For NPCs: calls UserManagementModule.RemoveUser().

----

== 3. RemoveClient() ==

OpenSim/Region/Framework/Scenes/Scene.cs -- RemoveClient()

Under m_removeClientPrivLock:

# Gets AgentCircuitData -- if null, aborts.
# Gets ScenePresence -- if null, removes circuit and returns.
# If child agent and closeChildAgents: sends SendShutdownConnectionNotice() to viewer.
# If avatar is sitting: calls avatar.StandUp().
# Calls m_sceneGraph.removeUserCount(!isChildAgent).
# If root agent and closeChildAgents:
#* Gets KnownRegionHandles (all known neighbour regions).
#* Calls m_sceneGridService.SendCloseChildAgentConnections() -- async HTTP DELETE to each neighbour simulator's agent endpoint.
# Fires EventManager.TriggerClientClosed().
# Fires EventManager.TriggerOnRemovePresence().
# If root agent:
#* Calls AttachmentsModule.DeRezAttachments() -- saves all attachments to inventory (see step 4).
#* Calls ForEachClient() sending SendKillObject for this avatar's LocalId to all connected clients.
# Calls AgentTransactionsModule.RemoveAgentAssetTransactions() if present.

Finally (in finally block, always runs):
# m_authenticateHandler.RemoveCircuit(acd).
# m_sceneGraph.RemoveScenePresence(agentID).
# m_clientManager.Remove(agentID).
# m_capsModule.RemoveCaps(agentID, circuitcode).
# avatar.Dispose().

Note: PresenceService.LogoutAgent() and GridUserService.LoggedOut() are NOT called from RemoveClient(). These are called from LLClientView.Close() or from the login service cleanup path. See step 5.

----

== 4. Attachments Saved ==

OpenSim/Region/CoreModules/Avatar/Attachments/AttachmentsModule.cs -- DeRezAttachments()

For each attachment SOG:

# Calls PrepareScriptInstanceForSave() -- fires detach script event, waits 30ms, snapshots script state XML. Must run outside AttachmentsSyncLock.
# Calls UpdateDetachedObject():
#* Calls m_scene.DeleteSceneObject() -- removes from scene.
#* Clears attachment fields (AttachedAvatar, ParentLocalId, IsAttachment).
#* For local grid users only (not HG visitors): calls UpdateKnownItem() -- serialises SOG to XML, creates new asset, updates inventory item assetID and permissions.
#* Calls so.RemoveScriptInstances() + so.Dispose().
# Calls sp.ClearAttachments().

HG visitors: UpdateKnownItem() skipped. Their attachments are not saved to the foreign grid. When they log back in on their home grid, attachments reload from home grid state.

; DB writes:
* assets -- INSERT: updated serialised object XML per attachment (local users only)
* inventoryitems -- UPDATE: new assetID per attachment (local users only)

----

== 5. Presence and GridUser Updated ==

OpenSim/Region/ClientStack/Linden/UDP/LLClientView.cs -- Close()
OpenSim/Services/Connectors/Presence/PresenceServicesConnector.cs
OpenSim/Services/Connectors/GridUser/GridUserServicesConnector.cs

On client close (called from CloseAgent step 2):

# PresenceService.LogoutAgent(sessionID) called -- HTTP POST to ROBUST PresenceService.
#* ROBUST sets presence Online=0, clears RegionID for this session.
# GridUserService.LoggedOut(agentID, sessionID, regionID, position, lookAt) called -- HTTP POST to ROBUST GridUserService.
#* ROBUST updates griduser: LastRegionID, LastPosition, LastLookAt, Logout timestamp.

; DB writes:
* presence -- UPDATE: Online=0, RegionID cleared
* griduser -- UPDATE: LastPosition, LastLookAt, LastRegionID, Logout timestamp

----

== 6. Child Agents Closed ==

Called asynchronously from RemoveClient() step 3 via m_sceneGridService.SendCloseChildAgentConnections().

For each neighbour handle in KnownRegionHandles:

# HTTP DELETE to neighbour simulator's agent endpoint (SimulationService).
# Neighbour simulator receives request, validates auth token (SessionID).
# Calls Scene.CloseAgent() on the child ScenePresence.
# Child path: no attachment save, no presence update, just removes from scene graph.

----

== 7. Appearance Save (if queued) ==

If an appearance save was queued via AvatarFactoryModule and the 5-second delay has not yet elapsed:

* AvatarFactoryModule timer fires SaveAppearance().
* Calls AvatarService.SetAppearance() -- writes final appearance to ROBUST.

Whether this completes before or after the logout depends on timing. A logout immediately after an outfit change may race with or skip the final save.

; DB writes (conditional):
* avatarappearance -- UPDATE: final wearable list, textures, visual params

----

== Shutdown vs Normal Logout ==

Scene.Close() (simulator shutdown):

# Fires EventManager.TriggerSceneShuttingDown().
# Calls GridService.DeregisterRegion() -- removes region from regions table. Sets RegionOnline=0.
# Sends Kick message to all root avatars via ControllingClient.Kick().
# Sends SendShutdownConnectionNotice() to all.
# Sleeps 500ms for messages to deliver.
# Calls CloseAgent() for every ScenePresence.
# Calls Backup(true) -- forces persistence of all changed scene objects.
# Closes SceneGraph and disposes PhysicsScene.

; DB writes (on shutdown):
* regions -- UPDATE: RegionOnline=0 (via GridService.DeregisterRegion())
* prims/primshapes/primitems -- UPDATE: all changed objects persisted via Backup(true)
* presence/griduser -- UPDATE: as per normal logout for each agent

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Operation !! Step
|-
| assets || INSERT || Attachment object assets saved (step 4, local users)
|-
| inventoryitems || UPDATE || Attachment inventory items updated (step 4, local users)
|-
| presence || UPDATE || Online=0, session cleared (step 5)
|-
| griduser || UPDATE || LastPosition, Logout timestamp (step 5)
|-
| avatarappearance || UPDATE || Final appearance if save queued (step 7, conditional)
|-
| regions || UPDATE || RegionOnline=0 on shutdown only
|-
| prims/primshapes || UPDATE || Changed objects on shutdown only
|}

----

== Simultaneous Logout During Teleport ==

If the client sends LogoutRequest while a teleport is in progress:

# EntityTransferModule.OnConnectionClosed() fires.
# If agent is in transit: sets transfer state to Aborting.
# The in-progress teleport path checks Aborting state at each stage and aborts.
# Source region calls CleanupFailedInterRegionTeleport() -- calls SimulationService.CloseAgent() on destination to remove the half-created agent there.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/EntityTransferModule]]
* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Code Map/ROBUST/PresenceService]]
* [[OpenSimulator Internals/Connector Architecture/Presence Connector]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]

OpenSimulator Internals/Walkthroughs/Avatar Change Outfit

2026-07-07T13:04:31Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Change Outfit =

== Overview ==

Traces what happens in code, connectors, and database when an avatar changes outfit -- replacing wearables and rebaking appearance textures.

This covers the standard viewer-initiated outfit change. The sequence differs slightly between V1-style viewers (AvatarIsWearing only) and V2/3 viewers (AvatarIsWearing followed by AgentSetAppearance with baked textures).

----

== 1. Viewer Sends AvatarIsWearing ==

OpenSim/Region/CoreModules/Avatar/AvatarFactory/AvatarFactoryModule.cs -- Client_OnAvatarNowWearing()

# Avatar selects new outfit or drags wearable items onto avatar in viewer.
# Viewer sends AvatarIsWearing packet listing new wearable ItemIDs by WearableType slot.
# AvatarFactoryModule.Client_OnAvatarNowWearing() fires.
# Makes a copy of current AvatarAppearance (without textures).
# Updates Wearables array on the copy: sets ItemID for each type, AssetID = UUID.Zero initially.
# Calls avatAppearance.GetAssetsFrom(sp.Appearance) -- fills in known AssetIDs from current appearance where ItemID matches.
# Under m_setAppearanceLock: writes sp.Appearance.Wearables only. Does NOT overwrite baked textures or visual params.
# Calls QueueAppearanceSave() -- schedules async save after m_savetime (default 5s).

Note: No appearance send at this step. The viewer will bake and send new textures next.

; No DB writes yet (save is queued, not executed).

----

== 2. Viewer Bakes New Textures Locally ==

This step happens entirely on the viewer side. No server involvement.

* Viewer composites the new wearable assets (clothing layers, skin, etc.) into baked texture images for each BakeType (Head, UpperBody, LowerBody, Eyes, Skirt, Hair, and PBR variants).
* Viewer uploads baked texture assets to the region's asset upload cap.
* Assets arrive at AssetService and are stored (temporary=true, local=true initially).

; DB writes (via AssetService):
* assets -- INSERT: each new baked texture asset (temporary, local)

----

== 3. Viewer Sends AgentSetAppearance ==

OpenSim/Region/CoreModules/Avatar/AvatarFactory/AvatarFactoryModule.cs -- Client_OnSetAppearance() → SetAppearance()

# Viewer sends AgentSetAppearance packet containing:
#* New TextureEntry -- baked texture UUIDs for each face index.
#* New VisualParams -- slider values (height, body shape, etc.).
#* WearableCacheItems -- CacheId/TextureID pairs for each bake index.
#* AvatarSize vector.
# AvatarFactoryModule.SetAppearance() called under m_setAppearanceLock.
# Calls sp.Appearance.SetVisualParams() -- updates slider bytes, recalculates avatar height if changed.
# Calls sp.Appearance.SetTextureEntries() -- updates baked texture UUIDs in appearance.
# Calls UpdateBakedTextureCache():
#* Checks local IAssetCache for each baked texture asset.
#* Updates WearableCacheItems with confirmed TextureID and CacheId.
#* If any textures missing from cache: sends SendRebakeAvatarTextures() -- viewer must re-upload. Throttled to one request per texture per 30 seconds.
#* If full set valid and changed: stores to IBakedTextureModule (bake server cache).
# Calls QueueAppearanceSave() (appearance changed).
# Calls QueueAppearanceSend().

; No immediate DB writes -- both saves are queued.

----

== 4. Appearance Sent to Other Clients (Deferred) ==

AvatarFactoryModule.HandleAppearanceUpdateTimer() → SendAppearance()

After m_sendtime (default 2s), timer drains m_sendqueue:

# Calls sp.SendAppearanceToAllOtherAgents():
#* Iterates all root ScenePresences.
#* Calls ControllingClient.SendAppearance() for each -- sends AvatarAppearance packet with new VisualParams and baked texture bytes.
#* Respects parcel visibility (ParcelHideThisAvatar).
# Calls Animator.SendAnimPack() -- sends current animation state.

Other clients now render the avatar with the new appearance.

----

== 5. Appearance Saved to AvatarService (Deferred) ==

AvatarFactoryModule.HandleAppearanceUpdateTimer() → SaveAppearance()

After m_savetime (default 5s), timer drains m_savequeue. Runs on thread pool.

# Calls SetAppearanceAssets():
#* For each wearable slot: calls InventoryService.GetItem(userID, itemID) -- resolves ItemID to AssetID.
#* If item not found: removes wearable from appearance, logs warning.
#* Ignores Ruth default wearables.
# Calls m_scene.AvatarService.SetAppearance(agentID, sp.Appearance):
#* Connector: HTTP PUT to ROBUST AvatarService.
#* ROBUST writes avatarappearance table (wearable list, texture entry, visual params) and avatarattachments table.

; DB writes:
* inventoryitems -- SELECT: resolve each wearable ItemID to AssetID
* avatarappearance -- UPDATE: new wearable list, texture entry, visual params
* avatarattachments -- UPDATE: current attachment list

----

== 6. Attachments Changed (if outfit includes attachment changes) ==

OpenSim/Region/CoreModules/Avatar/Attachments/AttachmentsModule.cs

If the outfit change includes adding or removing attachments, the viewer sends separate RezSingleAttachmentFromInv / DetachAttachmentIntoInv packets independently of the appearance packets above.

Adding an attachment:
# Client_OnRezSingleAttachmentFromInv() fires.
# RezSingleAttachmentFromInventory() checks not already worn.
# RezSingleAttachmentFromInventoryInternal() calls IInventoryAccessModule.RezObject() -- fetches asset, deserialises SOG, adds to scene.
# AttachObjectInternal() attaches to avatar, displaces any existing attachment at same point (if WearReplacesAll=true).
# UpdateUserInventoryWithAttachment() updates inventory item to reflect attachment point.
# ShowAttachInUserInventory() calls sp.Appearance.SetAttachment() and QueueAppearanceSave().
# Scripts created and started (CreateScriptInstances, ResumeScripts).
# TriggerOnAttach() fires.

Removing an attachment:
# Client_OnDetachAttachmentIntoInv() fires.
# DetachSingleAttachmentToInv() called -- see [[OpenSimulator Internals/Code Map/AttachmentsModule]].
# Script state snapshotted, object removed from scene, asset and inventory item updated.

; DB writes (per attachment change):
* assets -- INSERT: updated attachment object asset (serialised XML)
* inventoryitems -- UPDATE: new assetID, attach point

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Operation !! Step
|-
| assets || INSERT || Viewer uploads baked textures (step 2)
|-
| inventoryitems || SELECT || SetAppearanceAssets() resolves wearable AssetIDs (step 5)
|-
| avatarappearance || UPDATE || AvatarService.SetAppearance() (step 5)
|-
| avatarattachments || UPDATE || AvatarService.SetAppearance() (step 5)
|-
| assets || INSERT || Attachment object re-saved (step 6, if attachments changed)
|-
| inventoryitems || UPDATE || Attachment inventory item updated (step 6, if attachments changed)
|}

----

== Timing Notes ==

* Appearance send is deferred 2s (m_sendtime) -- prevents flooding if multiple rapid changes.
* Appearance save is deferred 5s (m_savetime) -- ensures all wearable asset uploads complete before inventory lookup.
* Both delays are configurable in [Appearance] section of OpenSim.ini.
* The AvatarIsWearing and AgentSetAppearance packets often arrive nearly simultaneously. m_setAppearanceLock ensures AvatarIsWearing does not overwrite SetAppearance texture changes.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/AvatarFactoryModule]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/ROBUST/AvatarService]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Logs Out]]

OpenSimulator Internals/Walkthroughs/Avatar Rez In Region

2026-07-07T12:58:51Z

Jwbshaw: first

= OpenSimulator Internals/Walkthroughs/Avatar Rez In Region =

== Overview ==

Traces what happens in code, connectors, and database from the moment a viewer completes login and connects to a region, through to the avatar standing in-world with appearance applied and scene state sent.

This covers the normal login case (not HG, not region transfer). See [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]] and [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]] for those paths.

----

== 1. Login Service Issues Seed Capability ==

OpenSim/Services/LLLoginService/LLLoginService.cs
OpenSim/Server/Handlers/Login/LLLoginHandlers.cs

# Viewer POSTs login credentials to ROBUST LoginService (port 8002 by default) via XMLRPC.
# LLLoginService authenticates via AuthenticationService, loads UserAccount, fetches appearance via AvatarService.
# LoginService calls PresenceService.LoginAgent() -- writes presence row: UserID, RegionID, SessionID, SecureSessionID, Online=1.
# LoginService calls GridUserService.SetLastPosition() -- updates griduser: LastRegionID, LastPosition, Login timestamp.
# LoginService selects destination region via GridService -- reads from regions table.
# LoginService calls the destination region's NewUserConnection capability -- passes AgentCircuitData (agent UUID, session UUID, circuit code, appearance, teleport flags). This pre-populates AgentCircuitManager in the region before the viewer connects.
# LoginService returns login response to viewer: SimIP, SimPort, RegionX/Y, SeedCapability URL, circuit code, session UUIDs.

; DB writes:
* presence -- INSERT or UPDATE: UserID, RegionID, SessionID, SecureSessionID, Online=1
* griduser -- UPDATE: LastRegionID, LastPosition, Login timestamp

----

== 2. Viewer Establishes UDP Circuit ==

OpenSim/Region/ClientStack/Linden/UDP/LLUDPServer.cs

# Viewer sends UseCircuitCode packet to region UDP port.
# LLUDPServer.HandleUseCircuitCode() validates circuit code against AgentCircuitManager (pre-populated in step 1).
# On match: LLUDPClient created. LLClientView constructed and associated with the circuit.
# ScenePresence constructed:
#* IsChildAgent = true initially (set in constructor)
#* Constructor fetches UserAccount for god level and user flags
#* Constructor calls RegisterToClientEvents() -- wires OnCompleteMovementToRegion → CompleteMovement, OnAgentUpdate → HandleAgentUpdate, OnRegionHandShakeReply → RegionHandShakeReply, and others
#* Appearance set from AgentCircuitData appearance passed by LoginService
#* AdjustKnownSeeds() called -- initialises known neighbour region cap seeds

; No DB writes at this step.

----

== 3. Viewer Sends CompleteMovementToRegion ==

OpenSim/Region/Framework/Scenes/ScenePresence.cs -- CompleteMovement()

The viewer fires CompleteMovementToRegion after receiving the circuit acknowledgement. This triggers ScenePresence.CompleteMovement() on the region side.

# For login (IsRealLogin true): does NOT wait for UpdateAgent -- skips WaitForUpdateAgent(). For teleports and crossings: waits up to 10 seconds for the source region's UpdateAgent call to arrive before proceeding.
# Checks flying state from AgentControlFlags.
# Calls MakeRootAgent() (see step 4).
# If not a cross-update: fetches group title via IGroupsModule.
# Rotates avatar to look direction.
# Initialises parcel tracking (m_currentParcelUUID, m_currentParcelHide).
# Sets m_inTransit = false.
# Sends RegionHandshake to viewer (ControllingClient.SendRegionHandshake()) if not a crossing.
# Calls ControllingClient.MoveAgentIntoRegion() -- sends the viewer its position and look.
# Validates baked texture cache via AvatarFactory. Queues appearance save if invalid.
# Sends initial avatar data to all presences (SendInitialAvatarDataToAllAgents()).
# Sends this avatar's appearance to self (SendAppearanceToAgent(this)).
# Sends current animation pack to self.
# Sends appearance and animations to all other presences (parcel visibility respected).
# Rezzes attachments: for real login, calls Scene.AttachmentsModule.RezAttachments(this).
# For login (not cross-update): calls IFriendsModule.SendFriendsOnlineIfNeeded().
# Hooks RegionHeartbeatEnd event for per-frame health regen and movement animation updates.

; No DB writes at this step (appearance save is queued async if needed).

----

== 4. MakeRootAgent() ==

OpenSim/Region/Framework/Scenes/ScenePresence.cs -- MakeRootAgent()

Called from CompleteMovement(). This is the critical path; delay here delays the crossing.

# Acquires m_completeMovementLock. Returns false immediately if already root agent (IsChildAgent == false).
# Handles pending sit: if ParentUUID is set, resolves the sit target prim and re-seats the avatar.
# Sets IsChildAgent = false.
# Updates RegionHandle to this region.
# Fires EventManager.TriggerSetRootAgentScene().
# Position adjustment (if not sitting):
#* Checks and adjusts landing point (telehub, parcel landing point, ban lines) via CheckAndAdjustLandingPoint_OS() or _SL().
#* Clamps position to region bounds.
#* Raises position to ground height + avatar half-height.
#* If ViaLogin or ViaLocation flags set: raycasts downward from PhysSearchHeight (300m) to find surface, adjusts Z to avoid being inside objects.
#* Sets AbsolutePosition.
#* Calls AddToPhysicalScene(isFlying) -- creates PhysicsActor, enters physics simulation.
# Calls m_scene.SwapRootAgentCount(false, IsNPC) -- increments root agent count.
# Resets MovementFlags to 0.
# Updates circuit child status: AuthenticateHandler.UpdateAgentChildStatus(circuitCode, false).
# Fires EventManager.TriggerOnMakeRootAgent(this) -- modules hook here.

; No DB writes at this step.

----

== 5. RegionHandshake / SendInitialData ==

OpenSim/Region/Framework/Scenes/ScenePresence.cs -- RegionHandShakeReply(), SendInitialData()

# Viewer sends RegionHandshakeReply in response to the handshake sent in step 3.
# RegionHandShakeReply() sets m_gotRegionHandShake = true and NeedInitialData = 2.
# On subsequent heartbeat frames, Update() checks NeedInitialData > 0 and calls SendInitialData().
# SendInitialData() waits for viewer caps seeds to be sent (ViewerFlags.SentSeeds), then waits a few more frames for the viewer to process them (NeedInitialData incremented to 6 before proceeding).
# When ready, fires async via Util.FireAndForget:
#* Releases source region if callback URI present (v1 or v0.7 HG path).
#* Closes old child agents via IEntityTransferModule.CloseOldChildAgents().
#* Sends terrain layer data (Scene.SendLayerData()) if not a teleport.
#* Sends parcel info (LandChannel.sendClientInitialLandInfo()).
#* Sends full updates for all other root presences' avatars (SendOtherAgentsAvatarFullToMe()).
#* Sends ObjectUpdate packets for all scene objects within draw distance -- either full updates or cache probes depending on viewer cache state.
#* Creates child agents in neighbouring regions via IEntityTransferModule.EnableChildAgents(this).
#* Enables child update processing (m_childUpdatesBusy = false).

; No DB writes at this step.

----

== 6. Attachments Rezzed ==

OpenSim/Region/CoreModules/Avatar/Attachments/AttachmentsModule.cs -- RezAttachments()

Called from CompleteMovement() for real logins (IsRealLogin true). For teleports/crossings, attachments are carried in AgentData and scripts restarted via RestartAttachmentScripts() instead.

# For each attachment in appearance data: fetches inventory item from InventoryService.
# Fetches asset from AssetService.
# Rezzes SceneObjectGroup in world at attachment point.
# Note: method name typo IncomingAttechments() exists at Scene.cs line 2976 and AttachmentsModule.cs line 384 (Mantis pending).

; DB reads:
* inventoryitems -- SELECT by item UUID for each attachment

----

== 7. Presence and GridUser Updated ==

OpenSim/Services/Connectors/Presence/PresenceServicesConnector.cs
OpenSim/Services/Connectors/GridUser/GridUserServicesConnector.cs

After MakeRootAgent and CompleteMovement complete, the region confirms the avatar's position:

# PresenceService.ReportAgent() -- updates presence table, confirms RegionID.
# GridUserService.SetLastPosition() -- updates griduser with confirmed in-region position and look.

; DB writes:
* presence -- UPDATE: RegionID confirmed for this session
* griduser -- UPDATE: LastPosition, LastLookAt, LastRegionID

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Operation !! Step
|-
| presence || INSERT/UPDATE || LoginService (step 1)
|-
| griduser || UPDATE || LoginService (step 1), post-rez (step 7)
|-
| regions || SELECT || LoginService destination lookup (step 1)
|-
| avatarappearance || SELECT || LoginService via AvatarService (step 1)
|-
| avatarattachments || SELECT || LoginService via AvatarService (step 1)
|-
| inventoryitems || SELECT || AttachmentsModule.RezAttachments() (step 6)
|}

Note: avatarappearance and avatarattachments are read by LoginService, not by the region directly -- the appearance data travels to the region inside AgentCircuitData.

----

== Key Flags ==

* TeleportFlags.ViaLogin | TeleportFlags.ViaRegionID -- set for normal login. Controls landing point behavior, telehub routing, and whether WaitForUpdateAgent() is skipped.
* TeleportFlags.ViaHGLogin -- HG login path; triggers different appearance handling and skips baked texture validation.
* IsRealLogin() -- returns true only for ViaLogin without ViaHGLogin. Determines whether attachments are freshly rezzed vs carried from source region.
* m_gotCrossUpdate -- false for login, true for region crossings. Controls whether SendLayerData and child agent setup are deferred.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/ROBUST/LoginService]]
* [[OpenSimulator Internals/Code Map/ROBUST/PresenceService]]
* [[OpenSimulator Internals/Code Map/ROBUST/AvatarService]]
* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Code Map/LLClientView]]
* [[OpenSimulator Internals/Connector Architecture/Presence Connector]]
* [[OpenSimulator Internals/Connector Architecture/Avatar Connector]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Goes HG]]

OpenSimulator Internals/Connector Architecture

2026-07-07T12:31:57Z

Jwbshaw: more stuff

= OpenSimulator Internals/Connector Architecture =

== Overview ==

Connectors are the HTTP client layer that sits between region simulators and ROBUST grid services. Each connector implements a service interface (e.g. IAssetService, IPresenceService) using HTTP calls to the corresponding ROBUST handler.

The same interface may be implemented by:
* A local connector -- calls the service directly in-process (standalone mode or co-located services).
* A remote connector -- makes HTTP calls to a ROBUST server.
* An HG connector -- wraps the remote connector with hypergrid-specific logic.

Region code calls only the interface. Which implementation is loaded depends on configuration ([Architecture] section of the ini files).

See [[OpenSimulator Internals/ROBUST Services]] for the server-side service implementations.

----

== Connector Pattern ==

All remote connectors follow the same pattern:

# Constructor receives IConfigSource and reads the service URL from config.
# Each method serialises parameters to a REST or XMLRPC request.
# Sends HTTP POST/GET/DELETE to the ROBUST handler endpoint.
# Deserialises the response and returns the result.

The HTTP client layer is WebUtil (OpenSim/Framework/WebUtil.cs), which handles serialisation, connection pooling, and error logging.

See [[OpenSimulator Internals/Connector Architecture/Asset Connector]] for a fully worked example of the pattern including both client and server-side handler code.

----

== Individual Connector Pages ==

{| class="wikitable"
! Connector !! Service Interface !! Notes
|-
| [[OpenSimulator Internals/Connector Architecture/Asset Connector]] || IAssetService || Includes server-side handler detail. HG variant wraps with foreign asset server logic.
|-
| [[OpenSimulator Internals/Connector Architecture/GridUser Connector]] || IGridUserService || Tracks last position, login/logout timestamps, home region.
|-
| [[OpenSimulator Internals/Connector Architecture/Presence Connector]] || IPresenceService || Online status, session tracking, region assignment.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAccount Connector]] || IUserAccountService || User account CRUD. Known bug: CreateUser() sends first name as email value.
|-
| [[OpenSimulator Internals/Connector Architecture/Inventory Connector]] || IInventoryService || XInventory protocol. UpdateFolder() URL-encodes Name; AddFolder() does not.
|-
| [[OpenSimulator Internals/Connector Architecture/Authentication Connector]] || IAuthenticationService || Password and token authentication, impersonation mechanism.
|-
| [[OpenSimulator Internals/Connector Architecture/Avatar Connector]] || IAvatarService || Appearance storage. ResetAvatar() log erroneously says "SetItems reply".
|-
| [[OpenSimulator Internals/Connector Architecture/Friends Connector]] || IFriendsService || Friend list, online notifications.
|-
| [[OpenSimulator Internals/Connector Architecture/Grid Connector]] || IGridService || Region registration, lookup, neighbour queries.
|-
| [[OpenSimulator Internals/Connector Architecture/Simulation Connector]] || ISimulationService || Inter-simulator agent and object transfer. QueryAccess, CreateAgent, UpdateAgent, CloseAgent, CreateObject.
|-
| [[OpenSimulator Internals/Connector Architecture/UserAgent Connector]] || IUserAgentService || HG-only. Home region lookup, login to foreign grid, session verification.
|-
| [[OpenSimulator Internals/Connector Architecture/Gatekeeper Connector]] || IGatekeeperService || HG-only. Foreign grid entry point. GetHyperlinkRegion, LoginAgentToGrid.
|}

----

== HG Connectors ==

HyperGrid introduces additional connectors that wrap or replace the standard ones:

* UserAgent Connector -- used by the source grid to contact the avatar's home grid UserAgent service during HG teleport.
* Gatekeeper Connector -- used to contact a foreign grid's Gatekeeper during HG destination resolution.
* HGAsset Connector -- used by HGInventoryAccessModule to fetch/push assets between grids (via HGAssetMapper).

These are documented in the individual connector pages above and in:
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]

----

== Configuration ==

Connectors are selected in the [Architecture] ini include files:

* config-include/StandaloneCommon.ini -- standalone mode, services loaded in-process.
* config-include/GridCommon.ini -- grid mode, remote connectors used.
* config-include/HGCommon.ini -- hypergrid additions.

The [ServiceList] section of Robust.ini selects which ROBUST handlers are loaded. The [Modules] section of OpenSim.ini selects which connectors the simulator loads.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Code Map]]

OpenSimulator Internals/Connector Architecture/Gatekeeper Connector

2026-07-07T12:24:34Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/Gatekeeper Connector =

== Overview ==

GatekeeperServiceConnector is the client-side connector used to talk to a foreign grid's GatekeeperService. It handles HG region linking, map tile retrieval, and region lookup. It extends SimulationServiceConnector, inheriting the agent and object transfer paths with overridden URL prefixes.

Source file:

OpenSim/Services/Connectors/Hypergrid/GatekeeperServiceConnector.cs

----

=== Inheritance ===

Extends SimulationServiceConnector. Overrides:
* AgentPath() -- returns "foreignagent/" instead of "agent/"
* ObjectPath() -- returns "foreignobject/" instead of "object/"

This means CreateAgent() from the parent sends to destination.ServerURI + "foreignagent/" + agentID + "/" when called through this connector.

----

=== Initialisation ===

Two constructors:
* Default (no args) -- no asset service; GetMapImage() will return the default HG map tile UUID
* IAssetService argument -- asset service used by GetMapImage() to store downloaded map tiles

No config file reading. The destination URI comes from GridRegion.ServerURI per call.

----

=== Transport ===

All non-inherited methods use XML-RPC via Nwc.XmlRpc over HTTP POST to the gatekeeper's ServerURI. 10-second timeout on all XML-RPC calls.

Agent and object transfer methods are inherited from SimulationServiceConnector and use WebUtil OSD/REST.

----

=== LinkRegion() ===

public bool LinkRegion(GridRegion info, out UUID regionID, out ulong realHandle,
out string externalName, out string imageURL, out string reason, out int sizeX, out int sizeY)

XML-RPC method: "link_region"

Sends: region_name

On success parses: uuid, handle (as ulong), region_image, external_name, size_x, size_y. All fields checked for null before parsing. Default sizeX/sizeY is Constants.RegionSize if not provided.

Returns false on connection error, XML-RPC fault, or parse exception.

----

=== GetMapImage() ===

public UUID GetMapImage(UUID regionID, string imageURL, string storagePath)

Downloads and stores a foreign region's map tile as an asset.

Sequence:
# If no AssetService: returns m_HGMapImage (00000000-0000-1111-9999-000000000013) immediately
# Builds filename: storagePath + regionID + ".jpg"
# If file not on disk: downloads from imageURL via WebClient.DownloadFile()
# Opens as Bitmap, encodes to JPEG2000 via OpenJPEG.EncodeFromImage()
# Stores as AssetType.Texture with random UUID, name "region {regionID}", creator = regionID
# Returns the stored asset UUID

Exception handling: entire sequence wrapped in bare catch -- logs "probably already in the cache" and returns m_HGMapImage. This catches OpenJPEG p/invoke failures specifically (comment says "LEGIT").

m_HGMapImage (00000000-0000-1111-9999-000000000013) is the fallback UUID returned on any failure.

----

=== GetHyperlinkRegion() ===

public GridRegion GetHyperlinkRegion(GridRegion gatekeeper, UUID regionID, UUID agentID,
string agentHomeURI, out string message)

XML-RPC method: "get_region"

Sends: region_uuid; optionally agent_id and agent_home_uri if agentID is non-zero.

On success parses full GridRegion: uuid, x, y, size_x, size_y, region_name, hostname, http_port, internal_port, server_uri. All fields null-checked before parsing.

message handling:
* If hash["message"] present: use it
* If success and no message: set message = null
* If failure and no message: set message = "The teleport destination could not be found." (comment notes this is for old grids that don't send message)

Returns null on connection error, XML-RPC fault, parse exception, or result == false.

----

=== Notes ===

* GetMapImage() uses the deprecated WebClient class for download. The comment "LEGIT" on the bare catch is the only documentation for why all exceptions are swallowed there.
* The fallback map tile UUID (00000000-0000-1111-9999-000000000013) is a static field -- the same UUID is returned for all failed map tile fetches regardless of region.
* Agent transfer uses "foreignagent/" path rather than "agent/" -- this is what distinguishes inbound HG agent traffic from local teleport traffic on the receiving simulator.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Connector Architecture/Simulation Connector]]
* [[OpenSimulator Internals/Connector Architecture/UserAgent Connector]]
* [[OpenSimulator Internals/Code Map/ROBUST/GatekeeperService]]

OpenSimulator Internals/Connector Architecture/UserAgent Connector

2026-07-07T12:23:52Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/UserAgent Connector =

== Overview ==

UserAgentServiceConnector is the remote connector for IUserAgentService. It is used by foreign grids to talk to a home grid's UserAgentService -- verifying agents, getting home region info, and checking online friends. It extends SimulationServiceConnector, inheriting the agent transfer path and overriding the agent URL path.

Source file:

OpenSim/Services/Connectors/Hypergrid/UserAgentServiceConnector.cs

----

=== Inheritance ===

Extends SimulationServiceConnector. Overrides:
* AgentPath() -- returns "homeagent/" instead of "agent/"
* PackData() -- adds gatekeeper_serveruri, gatekeeper_host, gatekeeper_port, destination_serveruri to the OSD payload

This means CreateAgent() from the parent class sends to destination.ServerURI + "homeagent/" + agentID + "/" when called through this connector.

----

=== Initialisation ===

Two constructors:
* String URL -- validates URI, normalizes to lowercase with trailing slash
* IConfigSource -- reads HomeURL from GridInfo; throws if missing or invalid

No config section key -- the URL is taken from GridInfo.HomeURL, which reads from [Const], [Startup], or [Hypergrid] sections.

----

=== Transport -- Two Protocols ===

This connector uses two different transports depending on the method:

Agent transfer (inherited from SimulationServiceConnector):
* LoginAgentToGrid() calls CreateAgent() -- uses WebUtil OSD/LLSD over HTTP POST/PUT to "homeagent/" path

All other methods:
* Use XML-RPC via Nwc.XmlRpc over HTTP POST to m_ServerURL
* CallServer() is the shared helper for XML-RPC calls that return a Hashtable
* GetBoolResponse() is the shared helper for XML-RPC calls that return a bool via a "result" key

----

=== LoginAgentToGrid() ===

Two overloads:

public bool LoginAgentToGrid(GridRegion source, AgentCircuitData aCircuit, GridRegion gatekeeper,
GridRegion destination, bool fromLogin, out string reason)

Constructs a synthetic home GridRegion using m_ServerURL as ServerURI, then calls the parent CreateAgent(). Teleport flag is ViaLogin if fromLogin, ViaHome otherwise. Stores gatekeeper in m_Gatekeeper for use by PackData().

public bool LoginAgentToGrid(GridRegion source, AgentCircuitData aCircuit, GridRegion gatekeeper,
GridRegion destination, out string reason)

Always passes fromLogin = false. Used by simulators.

----

=== XML-RPC Methods ===

{| class="wikitable"
! Method !! XmlRpc method !! Returns !! Notes
|-
| GetHomeRegion(userID, out position, out lookAt) || "get_home_region" || GridRegion || Parses full GridRegion from Hashtable; returns null on failure
|-
| IsAgentComingHome(sessionID, thisGridExternalName) || "agent_is_coming_home" || bool || Via GetBoolResponse()
|-
| VerifyAgent(sessionID, token) || "verify_agent" || bool || Via GetBoolResponse()
|-
| VerifyClient(sessionID, token) || "verify_client" || bool || Via GetBoolResponse()
|-
| LogoutAgent(userID, sessionID) || "logout_agent" || void || Calls GetBoolResponse() but discards result
|-
| GetUserInfo(userID) || "get_user_info" || Dictionary<string,object> || All non-null Hashtable entries returned
|-
| GetServerURLs(userID) || "get_server_urls" || Dictionary<string,object> || Only SRV_-prefixed keys returned; "SRV_" prefix stripped
|-
| LocateUser(userID) || "locate_user" || string || Returns hash["URL"] or empty string
|-
| GetUUI(userID, targetUserID) || "get_uui" || string || Returns hash["UUI"] or empty string
|-
| GetUUID(first, last) || "get_uuid" || UUID || Throws on missing or unparseable UUID response
|-
| StatusNotification(friends, userID, online) || "status_notification" || List<UUID> || [Obsolete]; friends sent as friend_0, friend_1...; returns online UUIDs
|-
| GetOnlineFriends(userID, friends) || "get_online_friends" || List<UUID> || [Obsolete]; same encoding as StatusNotification
|}

GetHomeRegion() field parsing: uuid, x, y, size_x, size_y, region_name, hostname, http_port, server_uri, internal_port, position, lookAt. All fields checked for null before parsing. Missing fields silently use zero/default values.

GetServerURLs() strips the "SRV_" prefix from keys, returning just the service type name.

GetUUID() throws on failure -- the only method in this connector that throws instead of returning a sentinel value.

----

=== SetClientToken() ===

No-op. Accepted but does nothing.

----

=== Notes ===

* This connector uses XML-RPC for most operations and OSD/REST for agent transfer -- two different protocols in the same class.
* StatusNotification() and GetOnlineFriends() are both marked [Obsolete]. Exception catch blocks in both methods silently swallow all exceptions with no logging.
* LogoutAgent() discards the bool result from GetBoolResponse() -- callers cannot detect failure.
* GetUUID() is the only method that throws on error rather than returning null/empty/false.
* The error message in GetBoolResponse() for "THIS IS BAAAAD" is verbatim from the source.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Connector Architecture/Simulation Connector]]
* [[OpenSimulator Internals/Code Map/ROBUST/UserAgentService]]
* [[OpenSimulator Internals/Code Map/ROBUST/GatekeeperService]]

OpenSimulator Internals/Connector Architecture/Simulation Connector

2026-07-07T12:23:08Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/Simulation Connector =

== Overview ==

SimulationServiceConnector is the remote connector for ISimulationService. It handles inter-simulator communication: creating and updating agents during teleport and region crossing, and transferring objects between regions. Unlike the other connectors, it talks directly to region simulators, not to ROBUST.

Source file:

OpenSim/Services/Connectors/Simulation/SimulationServiceConnector.cs

----

=== Initialisation ===

No config file reading. No service URI -- the destination URI comes from GridRegion.ServerURI on each call.

Two constructors:
* Default (no args)
* IConfigSource -- no-op, config argument unused

GetScene() and GetInnerService() always return null.

----

=== Transport ===

Unlike all other connectors, SimulationServiceConnector does not use SynchronousRestFormsRequester. It uses WebUtil methods with OSDMap (LLSD) payloads:

* WebUtil.PostToServiceCompressed() -- compressed POST, used for CreateAgent first attempt
* WebUtil.PostToService() -- uncompressed POST, used as fallback
* WebUtil.PutToServiceCompressed() / PutToService() -- PUT, used for UpdateAgent
* WebUtil.ServiceOSDRequest() -- used for QueryAccess (QUERYACCESS method), ReleaseAgent and CloseAgent (DELETE)

URL pattern: destination.ServerURI + "agent/" + agentID + "/"

AgentPath() and ObjectPath() are virtual -- subclasses can override the path segments.

----

=== Agent Methods ===

==== CreateAgent() ====

public bool CreateAgent(GridRegion source, GridRegion destination, AgentCircuitData aCircuit, uint flags, EntityTransferContext ctx, out string reason)

# Packs AgentCircuitData via aCircuit.PackAgentCircuitData(ctx)
# Adds context, source region info, destination region info, and teleport flags via PackData()
# Attempts compressed POST first (WebUtil.PostToServiceCompressed)
# On success: reads _Result map for actual success/reason
# On failure: falls back to uncompressed POST (WebUtil.PostToService) with warning that destination should be updated
# Returns false with reason on all failure paths

==== UpdateAgent(destination, AgentData, ctx) ====

Full agent data update (region crossing). Timeout 200 seconds.

==== UpdateAgent(destination, AgentPosition) ====

Position-only update. Called frequently during avatar movement.

Deduplication via m_updateAgentQueue dictionary keyed by URI:
* First thread for a URI becomes the worker; subsequent threads update the map and return
* Worker loops, sending the most recent position until no new update arrives
* On send failure: blacklists the destination URI for 120 seconds via _failedSims ExpiringCache
* Blacklisted destinations return false immediately without attempting contact

Private UpdateAgent(destination, IAgentData, ctx, timeout) handles the actual PUT:
* Uses PutToServiceCompressed
* If OutboundVersion >= 0.3: returns immediately on success
* If OutboundVersion < 0.2: falls back to uncompressed PutToService on failure

==== QueryAccess() ====

public bool QueryAccess(GridRegion destination, UUID agentID, string agentHomeURI, bool viaTeleport, Vector3 position, List<UUID> featuresAvailable, EntityTransferContext ctx, out string reason)

URL: destination.ServerURI + "agent/" + agentID + "/" + destination.RegionID + "/"

Sends simulation service version negotiation fields:
* simulation_service_supported_min/max
* simulation_service_accepted_min/max
* my_version (legacy field, set to minimum for safety)
* features (List of UUID capabilities)
* context

Response handling:
* Reads _Result map for success, reason, negotiated_inbound_version, negotiated_outbound_version
* Falls back to legacy "version" field (SIMULATION/N.N format) if negotiated fields absent
* Sets ctx.InboundVersion and ctx.OutboundVersion from response
* If MethodNotAllowed error received: logs it and returns true (legacy simulator compatibility)
* Sets ctx.WearablesCount based on OutboundVersion:
** < 0.5: LEGACY_VERSION_MAX_WEARABLES
** < 0.6: LEGACY_VERSION_MAX_WEARABLES + 1
** >= 0.6: -1 (send all)
* Clears featuresAvailable and repopulates from response

Comment in source notes the _Result success/failure is the authoritative one, not the sibling result node -- legacy issue from 0.7.3.1 era labelled "nte4.8 crap".

==== ReleaseAgent() ====

Sends DELETE to a provided URI (not constructed from destination). Always returns true regardless of result.

==== CloseAgent() ====

URL: destination.ServerURI + "agent/" + id + "/" + destination.RegionID + "/?auth=" + auth_code

Sends DELETE. Always returns true regardless of result.

----

=== Object Methods ===

==== CreateObject(destination, newPosition, sog, isLocalCall) ====

URL: destination.ServerURI + "object/" + sog.UUID + "/"

Packs scene object as XML2 via sog.ToXml2(), extra state via ExtraToXmlString() and GetStateSnapshot(). Sends uncompressed POST. Returns false if result is null or success is false.

==== CreateObject(destination, userID, itemID) ====

Not implemented. Always returns false with a TODO comment.

----

=== Notes ===

* This connector talks to region simulators, not ROBUST. The destination URI comes from GridRegion.ServerURI per call.
* The compressed/uncompressed fallback in CreateAgent() exists for backward compatibility with older simulators. A warning is logged when the fallback is needed.
* UpdateAgent position deduplication means only the most recent position is ever sent -- intermediate positions are silently dropped. This is intentional.
* The 200-second timeout on full AgentData UpdateAgent is notably long -- comment "yes, 200 seconds" is in the source.
* ReleaseAgent and CloseAgent always return true -- callers cannot detect failure from return value.
* CreateObject by userID+itemID is explicitly unimplemented with a "TODO, not that urgent" comment.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST/GatekeeperService]]
* [[OpenSimulator Internals/Code Map/Scene]]

OpenSimulator Internals/Connector Architecture/Grid Connector

2026-07-07T12:22:18Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/Grid Connector =

== Overview ==

GridServicesConnector is the simulator-side remote connector for IGridService. It translates IGridService calls into HTTP POST requests to the ROBUST Grid handler at /grid.

Source file:

OpenSim/Services/Connectors/Grid/GridServicesConnector.cs

----

=== Initialisation ===

Config section: [GridService]

Required key:
* GridServerURI -- URL of the ROBUST grid endpoint; throws if missing

Two URIs are constructed:
* m_ServerURI -- base URI (trailing slash trimmed)
* m_ServerGridURI -- m_ServerURI + "/grid" -- used for all requests

Base class BaseServiceConnector.Initialise() called for auth setup.

Three constructors:
* Default (no args) -- URIs must be set externally
* String URI -- sets both m_ServerURI and m_ServerGridURI directly
* IConfigSource -- calls Initialise(), normal grid mode

----

=== Transport ===

All methods POST to m_ServerGridURI using SynchronousRestFormsRequester.MakePostRequest(). All requests include a METHOD field. Most also include SCOPEID.

List-returning methods iterate all values in the reply dictionary and construct GridRegion from each dictionary entry. Empty list returned on empty reply or exception.

Single-region methods check for a "result" key containing a dictionary and construct GridRegion from it. Null returned if not found.

----

=== Methods ===

{| class="wikitable"
! Method !! METHOD field !! Returns !! Notes
|-
| RegisterRegion(scopeID, regionInfo) || "register" || string || Empty string on success; error message on failure. Sends full GridRegion via ToKeyValuePairs(). Checks Result field for "success"/"failure".
|-
| DeregisterRegion(regionID) || "deregister" || bool || Checks Result == "success"
|-
| GetNeighbours(scopeID, regionID) || "get_neighbours" || List<GridRegion> || Returns empty list on failure
|-
| GetRegionByUUID(scopeID, regionID) || "get_region_by_uuid" || GridRegion || Null on not found
|-
| GetRegionByHandle(scopeID, handle) || (none) || GridRegion || Converts handle to x,y coords; delegates to GetRegionByPosition()
|-
| GetRegionByPosition(scopeID, x, y) || "get_region_by_position" || GridRegion || Null on not found
|-
| GetRegionByName(scopeID, name) || "get_region_by_name" || GridRegion || Null on not found
|-
| GetLocalRegionByName(scopeID, name) || "get_localregion_by_name" || GridRegion || Null on not found; used by GatekeeperService
|-
| GetRegionByURI(scopeID, uri) || (none) || GridRegion || Always returns null -- not implemented
|-
| GetLocalRegionByURI(scopeID, uri) || (none) || GridRegion || Always returns null -- not implemented
|-
| GetRegionsByName(scopeID, name, max) || "get_regions_by_name" || List<GridRegion> || Name prefix search; max limits results
|-
| GetRegionsByURI(scopeID, uri, max) || (none) || List<GridRegion> || Always returns null -- not implemented
|-
| GetRegionRange(scopeID, xmin, xmax, ymin, ymax) || "get_region_range" || List<GridRegion> || Bounding box query
|-
| GetDefaultRegions(scopeID) || "get_default_regions" || List<GridRegion> || Returns empty list on failure
|-
| GetDefaultHypergridRegions(scopeID) || "get_default_hypergrid_regions" || List<GridRegion> || Returns empty list on failure
|-
| GetFallbackRegions(scopeID, x, y) || "get_fallback_regions" || List<GridRegion> || Returns empty list on failure
|-
| GetOnlineRegions(scopeID, x, y, max) || "get_online_regions" || List<GridRegion> || Sends MC for max count; returns empty list on failure
|-
| GetHyperlinks(scopeID) || "get_hyperlinks" || List<GridRegion> || Returns empty list on failure
|-
| GetRegionFlags(scopeID, regionID) || "get_region_flags" || int || Returns -1 on failure; parses result as int
|-
| GetExtraFeatures() || "get_grid_extra_features" || Dictionary<string,object> || Returns all key-value pairs from reply; empty dict on failure
|}

RegisterRegion() result handling:
* "success" (case-insensitive) -- returns empty string
* "failure" (case-insensitive) -- logs Message field and returns it
* Anything else -- logs "unexpected result" and returns it
* All errors return a non-empty string; callers check for empty string to detect success

----

=== Notes ===

* GetRegionByURI(), GetLocalRegionByURI(), and GetRegionsByURI() always return null -- RegionURI queries are not implemented in this connector.
* GetRegionByHandle() is a local conversion wrapper -- it does not make a separate HTTP call with the handle value.
* List methods return empty list (not null) on all failure paths.
* Single-region methods return null on failure.
* GetRegionFlags() returns -1 on failure, not 0 -- callers should check for negative values.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST/GridService RegisterRegion]]
* [[OpenSimulator Internals/Code Map/Shared]]

OpenSimulator Internals/Connector Architecture/Friends Connector

2026-07-07T12:21:31Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/Friends Connector =

== Overview ==

FriendsServicesConnector is the simulator-side remote connector for IFriendsService. It translates IFriendsService calls into HTTP POST requests to the ROBUST Friends handler at /friends.

Source file:

OpenSim/Services/Connectors/Friends/FriendsServicesConnector.cs

----

=== Initialisation ===

Config section: [FriendsService]

Required key:
* FriendsServerURI -- URL of the ROBUST friends endpoint; throws if missing

Base class BaseServiceConnector.Initialise() called for auth setup.

Three constructors:
* Default (no args) -- URI must be set externally
* String URI -- used by callers that pass the URI directly
* IConfigSource -- calls Initialise(), normal grid mode

----

=== Transport ===

All methods POST to m_ServerURI + "/friends" using SynchronousRestFormsRequester.

Unlike most other connectors, requests do not include VERSIONMIN / VERSIONMAX fields.

----

=== Methods ===

{| class="wikitable"
! Method !! METHOD field !! Notes
|-
| GetFriends(UUID principalID) || "getfriends" || UUID overload
|-
| GetFriends(string principalID) || "getfriends_string" || String overload -- used for HG UUI identifiers
|-
| StoreFriend(principalID, friend, flags) || "storefriend" || Sends PrincipalID, Friend, MyFlags; returns bool from Result field
|-
| Delete(UUID principalID, string friend) || "deletefriend" || UUID overload
|-
| Delete(string principalID, string friend) || "deletefriend_string" || String overload -- used for HG UUI identifiers
|}

GetFriends() (both overloads) delegate to a protected GetFriends(Dictionary, string) helper:
* Returns empty FriendInfo[] if result == "null"
* Iterates all values in reply dictionary, constructs FriendInfo for each dictionary entry
* Returns empty FriendInfo[] on empty reply or exception (never returns null)

StoreFriend() and Delete():
* Check replyData["Result"] (capital R -- different from most other connectors which use lowercase "result")
* Parse as bool via Boolean.TryParse()
* Return false on empty reply, null response, or exception

----

=== Notes ===

* Two string overloads exist (GetFriends, Delete) to support HyperGrid UUI identifiers which are not valid UUIDs.
* Result field key is "Result" (capital R) -- inconsistent with most other ROBUST service connectors which use lowercase "result".
* No VERSIONMIN/VERSIONMAX sent -- unlike GridUser, Presence, Avatar, and UserAccount connectors.
* GetFriends() returns empty array (not null) on all failure paths.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/Code Map/Shared]]

OpenSimulator Internals/Connector Architecture/Avatar Connector

2026-07-07T12:20:47Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/Avatar Connector =

== Overview ==

AvatarServicesConnector is the simulator-side remote connector for IAvatarService. It translates IAvatarService calls into HTTP POST requests to the ROBUST Avatar handler at /avatar.

Source file:

OpenSim/Services/Connectors/Avatar/AvatarServicesConnector.cs

----

=== Initialisation ===

Config section: [AvatarService]

Required key:
* AvatarServerURI -- URL of the ROBUST avatar endpoint; throws if missing

Base class BaseServiceConnector.Initialise() called for auth setup.

Three constructors:
* Default (no args) -- URI must be set externally
* String URI -- used by callers that pass the URI directly
* IConfigSource -- calls Initialise(), normal grid mode

----

=== Transport ===

All methods POST to m_ServerURI + "/avatar" using SynchronousRestFormsRequester.

All requests include:
* VERSIONMIN / VERSIONMAX -- protocol version negotiation
* METHOD -- identifies the operation

----

=== Methods ===

{| class="wikitable"
! Method !! METHOD field !! Notes
|-
| GetAvatar(userID) || "getavatar" || Returns AvatarData constructed from result dictionary; null on empty reply or missing result
|-
| GetAppearance(userID) || (none) || Calls GetAvatar(), then avatar.ToAvatarAppearance()
|-
| SetAvatar(userID, avatar) || "setavatar" || Serializes avatar via ToKeyValuePairs(); returns bool from result field
|-
| SetAppearance(userID, appearance) || (none) || Constructs AvatarData from AvatarAppearance, calls SetAvatar()
|-
| ResetAvatar(userID) || "resetavatar" || Returns bool from result field
|-
| SetItems(userID, names[], values[]) || "setitems" || Sends Names and Values as parallel List<string>; returns bool
|-
| RemoveItems(userID, names[]) || "removeitems" || Sends Names as List<string>; returns bool
|}

All write methods (SetAvatar, ResetAvatar, SetItems, RemoveItems) check replyData["result"].ToLower() == "success" and return false on empty reply, missing result field, or exception.

----

=== Notes ===

* The log message in ResetAvatar() says "SetItems reply" in both the missing-result and empty-reply branches -- copy-paste error from SetItems(). The method itself is correct; only the log text is wrong.
* ScopeID fields are present in the code but commented out throughout.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST/AvatarService]]
* [[OpenSimulator Internals/Code Map/Shared]]

OpenSimulator Internals/Connector Architecture/Authentication Connector

2026-07-07T12:20:00Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/Authentication Connector =

== Overview ==

AuthenticationServicesConnector is the simulator-side remote connector for IAuthenticationService. It translates authentication calls into HTTP POST requests to the ROBUST Authentication handler at /auth/plain.

Source file:

OpenSim/Services/Connectors/Authentication/AuthenticationServicesConnector.cs

----

=== Initialisation ===

Config section: [AuthenticationService]

Required key:
* AuthenticationServerURI -- URL of the ROBUST authentication endpoint; throws if missing

Base class BaseServiceConnector.Initialise() called for auth setup.

Three constructors:
* Default (no args) -- URI must be set externally
* String URI -- used by callers that pass the URI directly
* IConfigSource -- calls Initialise(), normal grid mode

----

=== Transport ===

All methods POST to m_ServerURI + "/auth/plain" using SynchronousRestFormsRequester. All requests include a METHOD field.

----

=== Methods ===

{| class="wikitable"
! Method !! METHOD field !! Notes
|-
| Authenticate(principalID, password, lifetime) || "authenticate" || Returns token string on success, empty string on failure
|-
| Authenticate(principalID, password, lifetime, out realID) || "authenticate" || realID always returns UUID.Zero; delegates to the 3-arg overload
|-
| Verify(principalID, token, lifetime) || "verify" || Returns bool
|-
| Release(principalID, token) || "release" || Returns bool
|-
| SetPassword(principalID, passwd) || (none) || Always returns false -- not done from remote simulators
|-
| GetAuthInfo(principalID) || (none) || Always returns null -- not done from remote simulators
|-
| SetAuthInfo(info) || (none) || Always returns false -- not done from remote simulators
|}

Authenticate() sends: PRINCIPAL, PASSWORD, LIFETIME. Returns Token from reply on Success, empty string otherwise.

Verify() sends: PRINCIPAL, TOKEN, LIFETIME. Returns true on Success.

Release() sends: PRINCIPAL, TOKEN. Returns true on Success.

All three parse XML response and check replyData["Result"] == "Success".

----

=== Notes ===

* The out realID overload of Authenticate() always sets realID to UUID.Zero and delegates to the 3-arg version. The realID concept exists in the service interface but is not implemented at the connector level.
* SetPassword(), GetAuthInfo(), and SetAuthInfo() are explicitly documented in comments as not done from remote simulators.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST/AuthenticationService]]
* [[OpenSimulator Internals/Code Map/Shared]]

OpenSimulator Internals/Connector Architecture/Inventory Connector

2026-07-07T12:19:13Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/Inventory Connector =

== Overview ==

XInventoryServicesConnector is the simulator-side remote connector for IInventoryService. It translates IInventoryService calls into HTTP POST requests to the ROBUST XInventory handler at /xinventory.

Source file:

OpenSim/Services/Connectors/Inventory/XInventoryServicesConnector.cs

----

=== Initialisation ===

Config section: [InventoryService] (or configName argument if provided)

Required key:
* InventoryServerURI -- URL of the ROBUST inventory endpoint; throws if missing

The endpoint URL is always InventoryServerURI + "/xinventory" (trailing slash normalized).

Optional key:
* RemoteRequestTimeout -- timeout in seconds for HTTP requests; default -1 (100 seconds, not infinite)

A stats counter (RequestsMade) is registered with StatsManager on initialisation.

Four constructors:
* Default (no args) -- URI must be set externally
* String URI -- used by callers that pass the URI directly; appends /xinventory
* IConfigSource -- calls Initialise(), normal grid mode
* IConfigSource + configName -- used for non-default section names

----

=== Transport ===

Unlike other connectors, XInventoryServicesConnector does not use SynchronousRestFormsRequester. It has its own MakePostDicRequest() method using HttpClient directly.

MakePostDicRequest() features:
* Uses WebUtil.GetNewGlobalHttpClient() with configured timeout
* Sends Keep-Alive headers (timeout=30, max=10)
* Sends Content-Type: application/x-www-form-urlencoded
* Uses HttpCompletionOption.ResponseHeadersRead -- reads headers first, then streams body
* Body receive has its own CancellationTokenSource timeout via WebUtil.EstimatedReceiveTimeout()
* Logs requests taking longer than WebUtil.LongCallTime
* Logs body timeouts separately from other errors
* Always disposes request, response, and client in finally block
* Returns empty Dictionary on null response (never returns null)

All requests are POST to m_InventoryURL. The METHOD and parameters are encoded as URL query string in the POST body.

MakeRequest() increments RequestsMade counter on every call.

----

=== Item Cache ===

Static ExpiringCacheOS<UUID, InventoryItemBase> shared across all instances. TTL is 30 seconds.

Cache is checked in GetItem() and GetMultipleItems() before making remote requests. Cache is updated on successful GetItem(), UpdateItem(), and GetMultipleItems(). Cache entries are removed on MoveItems() and DeleteItems().

----

=== CheckReturn() ===

Helper used by most methods. Returns false if the reply dictionary is null or empty. If RESULT key exists and its value parses as bool, returns that bool. If RESULT key exists but is not parseable as bool, returns false. If RESULT key is absent, returns true (assumes success if the server returned any data).

GetAssetPermissions() cannot use CheckReturn() because its RESULT is an int, not a bool -- it has its own inline parse.

----

=== Methods ===

{| class="wikitable"
! Method !! METHOD field !! Notes
|-
| CreateUserInventory(principalID) || CREATEUSERINVENTORY || Returns bool
|-
| GetInventorySkeleton(principalID) || GETINVENTORYSKELETON || Returns List<InventoryFolderBase> from FOLDERS dict
|-
| GetRootFolder(principalID) || GETROOTFOLDER || Returns single InventoryFolderBase from "folder" key
|-
| GetFolderForType(principalID, type) || GETFOLDERFORTYPE || TYPE sent as int
|-
| GetFolderContent(principalID, folderID) || GETFOLDERCONTENT || Returns InventoryCollection with Folders and Items lists
|-
| GetMultipleFoldersContent(principalID, folderIDs[]) || GETMULTIPLEFOLDERSCONTENT || Batch; results keyed as F_{uuid}; null entry per missing folder
|-
| GetFolderItems(principalID, folderID) || GETFOLDERITEMS || Returns List<InventoryItemBase> from ITEMS dict
|-
| AddFolder(folder) || ADDFOLDER || Sends full folder fields as dictionary
|-
| UpdateFolder(folder) || UPDATEFOLDER || Sends fields as query string; URL-encodes Name
|-
| MoveFolder(folder) || MOVEFOLDER || Sends ParentID, ID, PRINCIPAL only
|-
| DeleteFolders(principalID, folderIDs) || DELETEFOLDERS || Sends FOLDERS as List<string>
|-
| PurgeFolder(folder) || PURGEFOLDER || Sends ID only
|-
| AddItem(item) || ADDITEM || Sends full item fields; null-coalesces Description, CreatorData, CreatorId
|-
| UpdateItem(item) || UPDATEITEM || Updates cache on success
|-
| MoveItems(principalID, items) || MOVEITEMS || Sends parallel IDLIST and DESTLIST; removes from cache
|-
| DeleteItems(principalID, itemIDs) || DELETEITEMS || Removes from cache
|-
| GetItem(principalID, itemID) || GETITEM || Cache-first; updates cache on fetch
|-
| GetMultipleItems(principalID, itemIDs[]) || GETMULTIPLEITEMS || Cache-first per item; only fetches uncached IDs; results keyed as item_N
|-
| GetFolder(principalID, folderID) || GETFOLDER || Returns single InventoryFolderBase
|-
| GetActiveGestures(principalID) || GETACTIVEGESTURES || Returns List<InventoryItemBase> from ITEMS dict
|-
| GetAssetPermissions(principalID, assetID) || GETASSETPERMISSIONS || Returns int from RESULT field; 0 on failure
|-
| HasInventoryForUser(principalID) || (none) || Always returns false -- not implemented for remote connector
|}

----

=== BuildFolder() / BuildItem() ===

Static helpers that construct InventoryFolderBase and InventoryItemBase from reply dictionaries. Both catch exceptions and return an empty object on parse failure rather than throwing. CreatorData is optional in BuildItem() -- fetched via TryGetValue.

----

=== Notes ===

* This is the only connector in the set that uses HttpClient directly rather than SynchronousRestFormsRequester.
* HasInventoryForUser() always returns false -- not implemented.
* GetMultipleItems() builds the request body with a StringBuilder, skipping items already in cache. The result index tracking (variable i) carries over between the cache-hit loop and the network-result loop -- order of itemArr entries may not match order of itemIDs if some were cached and some were not.
* GetMultipleFoldersContent() returns null entries (not omits) for folders not found in the reply, preserving index alignment with the input folderIDs array.
* UpdateFolder() URL-encodes Name via HttpUtility.UrlEncode() but AddFolder() does not -- inconsistency within the same file.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST/InventoryService]]
* [[OpenSimulator Internals/Code Map/Shared]]

OpenSimulator Internals/Connector Architecture/UserAccount Connector

2026-07-07T12:18:02Z

Jwbshaw: first

= OpenSimulator Internals/Connector Architecture/UserAccount Connector =

== Overview ==

UserAccountServicesConnector is the simulator-side remote connector for IUserAccountService. It translates IUserAccountService calls into HTTP POST requests to the ROBUST UserAccount handler at /accounts.

Source file:

OpenSim/Services/Connectors/UserAccountServicesConnector.cs

----

=== Initialisation ===

Config section: [UserAccountService]

Required key:
* UserAccountServerURI -- URL of the ROBUST UserAccount endpoint; throws if missing or unresolvable

Base class BaseServiceConnector.Initialise() called for auth setup.

Three constructors:
* Default (no args) -- URI must be set externally
* String URI -- used by callers that pass the URI directly
* IConfigSource -- calls Initialise(), normal grid mode

----

=== Transport ===

All methods POST to m_ServerURI + "/accounts" using SynchronousRestFormsRequester.

All requests include:
* VERSIONMIN / VERSIONMAX -- protocol version negotiation
* METHOD -- identifies the operation

Two internal helpers:

SendAndGetReply() -- used by single-account GET methods and StoreUserAccount():
* POSTs, parses XML response
* Returns UserAccount constructed from result dictionary, or null

SendAndGetBoolReply() -- defined but not called by any method in this file. Dead code.

----

=== Methods ===

{| class="wikitable"
! Method !! METHOD field !! Notes
|-
| GetUserAccount(scopeID, firstName, lastName) || "getaccount" || Lookup by name
|-
| GetUserAccount(scopeID, email) || "getaccount" || Lookup by email
|-
| GetUserAccount(scopeID, userID) || "getaccount" || Lookup by UUID
|-
| GetUserAccounts(scopeID, query) || "getaccounts" || Search by name fragment; returns List<UserAccount>
|-
| GetUserAccounts(scopeID, List<string> IDs) || "getmultiaccounts" || Batch lookup by UUID list; falls back to one-by-one if server returns "Failure"
|-
| StoreUserAccount(data) || "setaccount" || Serializes UserAccount via ToKeyValuePairs(); returns true if result is non-null
|-
| CreateUser(first, last, password, email, scopeID) || "createuser" || Remote user creation; not part of IUserAccountService interface
|-
| InvalidateCache(userID) || (none) || No-op -- cache invalidation not implemented for remote connector
|-
| GetUserAccountsWhere(scopeID, where) || (none) || Always returns null -- not implemented for regions
|}

GetUserAccounts(List<string> IDs) fallback:
* Tries "getmultiaccounts" first
* If result == "Failure": sets suported = false, falls back to calling GetUserAccount(scopeID, uuid) one by one
* Skips IDs that are not valid non-zero UUIDs in the fallback path

----

=== Notes ===

* CreateUser() has a bug: the email field sends first name instead of the email value. The line reads sendData["Email"] = first rather than sendData["Email"] = email.
* SendAndGetBoolReply() is defined but never called -- dead code.
* InvalidateCache() is a no-op -- the remote connector has no local cache to invalidate.
* GetUserAccountsWhere() returns null unconditionally -- SQL WHERE clause queries are not supported over HTTP.
* ScopeID fields are present in the code but some are commented out.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST/UserAccountService]]
* [[OpenSimulator Internals/Code Map/Shared]]