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

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:

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:

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)

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)