Jwbshaw: first

2026-07-07T13:20:58Z

first

New page

= 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/HGEntityTransferModule - Revision history

Jwbshaw: first