Jump to content

OpenSimulator Internals/Walkthroughs/Avatar Goes HG

From Open Simulator Technical Help
Revision as of 13:11, 7 July 2026 by Jwbshaw (talk | contribs) (first)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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
  1. Avatar clicks a HG link or enters a HG URI (e.g. hg.example.com:8002:RegionName).
  2. 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.
  3. GetFinalDestination() detects the Hyperlink flag.
  4. 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.
  5. ValidateGenericConditions() checks appearance restrictions if RestrictAppearanceAbroad=true.

2. Pre-flight at Foreign Gatekeeper

EntityTransferModule -- DoTeleportInternal()
  1. SimulationService.QueryAccess() -- HTTP POST to destination simulator on foreign grid.
    • Destination checks ban list, parcel access, agent limit.
  2. sp.Appearance.CanTeleport() -- checks outfit compatibility with destination protocol version.

3. Agent Created at Foreign Grid

HGEntityTransferModule -- CreateAgent() override
  1. Detects Hyperlink destination.
  2. Checks local user's UserLevel >= LevelHGTeleport. Refuses if insufficient.
  3. Gets HomeURI from agentCircuit.ServiceURLs.
  4. Creates UserAgentServiceConnector for home grid's UserAgent service.
  5. 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.
  6. Sets logout = true -- this agent will be logged out of home grid.
  7. Fires TriggerTeleportStart.

4. Agent State Sent

Same as standard teleport (see OpenSimulator Internals/Walkthroughs/Avatar Transfer Between Regions steps 5-6):

  1. sp.IsChildAgent = true set on source.
  2. TeleportFinishEvent sent to viewer with foreign destination endpoint and caps URL.
  3. AgentData built via sp.CopyTo() -- includes appearance, attachments with script states.
  4. SimulationService.UpdateAgent() -- HTTP POST to foreign destination simulator.
    • Foreign destination's IncomingUpdateChildAgent() → CopyFrom() fires.
  5. UpdateAgent() waits for avatar to become root at destination.

5. Source Grid Logs Out Agent

HGEntityTransferModule -- AgentHasMovedAway() override

Called after UpdateAgent() returns successfully:

  1. sp.HasMovedAway() -- sends kill packets for non-HUD attachments, handles parcel visibility.
  2. sp.MakeChildAgent() -- source becomes child.
  3. sp.closeAllChildAgents() -- closes all neighbour child agents (logout=true path).
  4. AgentHasMovedAway() fires:
    • PresenceService.LogoutAgent(sessionID) -- marks agent offline on home grid.
    • GridUserService.LoggedOut(userID, ...) -- updates home grid's griduser with last position.
  5. 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()
  1. Avatar clicks "Teleport Home" or script calls llTeleportAgentHome().
  2. HGEntityTransferModule.TeleportHome() detects foreign user (IsLocalGridUser returns false).
  3. Gets HomeURI from AgentCircuitData.ServiceURLs.
  4. Creates UserAgentServiceConnector for home grid.
  5. 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.
  6. Constructs Gatekeeper GridRegion from HomeURI.
  7. 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()
  1. AgentHasMovedAway() with logout=true:
    • PresenceService.LogoutAgent() on foreign grid (clears foreign presence record if any).
    • GridUserService.LoggedOut() on foreign grid.
  2. 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()
  1. Landmark contains Gatekeeper URI + RegionID + position.
  2. If gatekeeper is local grid: falls back to normal landmark teleport.
  3. 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.

  1. Gets HomeURI.
  2. Calls UserAgentServiceConnector(homeURI).VerifyClient(SessionID, token).
    • Home grid's UserAgent service confirms the session is valid.
  3. Returns false → scene removes circuit and closes agent.

Summary: DB Tables Touched

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

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

Retrieved from "http://osimdev.org/wiki/index.php?title=OpenSimulator_Internals/Walkthroughs/Avatar_Goes_HG&oldid=86"