Region crossing

==Introduction==
The Second Life world is divided into square regions 256 meters on a side. Each region is managed by a separate simulator program. Viewers present the illusion of a large, seamless world by communicating with several region simulators simultaneously. Avatars cross between regions via a complex process which requires cooperation between multiple simulators and viewers.
==Overview of a region crossing==
A region crossing is initiated by a simulator when an avatar goes outside the region boundary. The center of the root prim of the linkset must be one meter past the boundary for crossing to trigger. This prevents toggling back and forth for avatars on the edge of the region. For avatars on vehicles, the center point of the root prim of the vehicle triggers the crossing, so that all avatars and the vehicle remain together. 
When an avatar or an object crosses a region boundary, its information is sent from one simulator to the next. From the viewpoint of a viewer, it is re-created in the gaining region. When the viewer receives an ObjectUpdate message for the avatar or object in the gaining region, the viewer will re-create the object. ObjectUpdate messages (either full or compressed) are sent for each prim in the linkset. 
The viewer then detects that it has a duplicate of an existing object that was in the losing region. Each object in the world has a unique UUID, and the viewer checks for duplicates. Creation of a duplicate causes the viewer to delete the old object. This is almost seamless to the user, although some object flicker can often be seen.
The viewer is informed of an avatar region crossing via the CrossedRegion event, which travels over the event poller channel. This is no longer a UDP message, although it was in earlier versions of the SL system. This message indicates the beginning of the region crossing process. An AgentMovementComplete message from the gaining region indicates completion. It is not guaranteed that those messages arrive in order. This tells the viewer which simulator has control and should receive AgentUpdate messages with mouse and keyboard inputs.
During the movement process, there are some out-of-sync conditions. The avatar object does not cross at the same time that control is handed off. This causes some difficulties if the out of sync condition persists. If it persists for more than a few seconds, the region crossing has failed. 
=Event sequence diagram for region crossings=
To change the diagram, change this source code, then paste it into this free online chart generator to generate a new .png image.
Then replace the version of the image above with a new image.
title Region crossing
participant "Viewer" as V
participant "Losing Sim" as H
participant "Gaining Sim" as N
activate H
activate N
V-->>H: AgentUpdate
V-->>H: AgentUpdate
rbox left of V: Avatar crosses region boundary
H->N: ServerSide ChitChat
N->H:
V->H: EventQueueGet
H->V: CrossedRegion
rbox left of V: Control of avatar transferred to gaining region
rbox left of V: Sim waits for CompleteAgentMovement
V-->>N: CompleteAgentMovement
N-->>V: AgentMovementComplete
V-->>N: AgentUpdate
rbox left of V: Out of sync until object update from ganing region
N-->>V: ObjectUpdate
rbox left of V: Viewer creates avatar object in gaining region
rbox left of V: Viewer detects duplicate object in losing region and kills it.
V-->>N: AgentUpdate
rbox left of V: Normal avatar operation in gaining region
N-->>V: TerseImprovedObjectUpdate
V-->>N: AgentUpdate
N-->>V: ObjectUpdate
==Discussion==
This is an event sequence diagram of the essential events that take place as an avatar crosses from one region to another.
It shows the normal case for a simple region crossing.
This is a rather brittle operation. Many things can and do go wrong.
===Double region crossings===
If a second region crossing starts before the first one is completed, results are generally unsatisfactory. 
This usually happens at region corners where four regions meet, but can also be caused by very fast movement.
The simulators are not properly interlocked to prevent this.
===Gaining region not yet fully live===
It's possible to cross into a neighbor region which is still in the process of connecting to the viewer. See Adding neighbor region sequence. This usually works, and will force the neighbor region to become fully live.
===Multiple avatars on a vehicle===
This is not well understood at this time, and tends to be unreliable.
==Notes==
Dashed lines are UDP messages. Solid lines are events received via EventQueueGet.
This documents the successful "happy path". Error conditions are not yet covered.
This information reflects what has been discovered by third part viewer developers. It is not official and may contain errors.