Editing OpenSimulator Internals/Code Map/EntityTransferModule

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