|
|
| (54 intermediate revisions by one user not shown) |
| Line 3: |
Line 3: |
| | =Introduction= | | =Introduction= |
| | | | |
| − | '''Work in progress''' | + | A teleport is the transfer of a user's connection (represented in-world by their avatar) from one location to another. These locations can be |
| | | | |
| − | Teleports in OpenSimulator involve a complex exchange of messages between the simulator hosting the source region, the simulator hosting the destination region (which may be the same simulator that is hosting the source region) and the viewer. This page documents that message exchange.
| + | * Within the same region. |
| | + | * Between different regions on the same simulator. |
| | + | * Between different simulators on the same network within the same grid (e.g. a grid hosted on a single network). |
| | + | * Between different networks within the same grid (e.g. between simulators hosted on OSGrid). |
| | + | * Between different networks on different grids (i.e. Hypergrid teleport). |
| | | | |
| − | In terms of basic grid teleports (where all simulators are hosted on the same grid), there are five different scenarios. | + | In OpenSimulator 0.7.5 and for many releases previously, a teleport protocol called SIMULATION/0.1 was used. In OpenSimulator 0.7.6 and after, a teleport protocol called SIMULATION/0.2 is used by default. However, OpenSimulator can still use the SIMULATION/0.1 protocol required by older versions and will automatically inter-operate with them. |
| | | | |
| − | * Teleport within the same region (intra-region).
| + | If you want to know an eye-watering amount of nitty-gritty about how this works, then please see the [[Teleport Protocol]] page. |
| − | * Teleport to an out-of-sight region hosted on the same simulator (same simulator, out-of-sight).
| + | |
| − | * Teleport to an in-sight region hosted on the same simulator (same simulator, in-sight).
| + | |
| − | * Teleport to an out-of-sight region hosted on a different simulator (different simulator, out-of-sight).
| + | |
| − | * Teleport to an in-sight region hosted on a different simulators (different simulator, in-sight).
| + | |
| | | | |
| − | These are listed in terms of complexity and hence reliability. Intra-region teleport is the simplest at all since the avatar just needs to be moved within the region - connections do not need to be torn down and established.
| + | =Configuration= |
| | | | |
| − | Same simulator, out-of-sight teleport is the next simplest. Though the avatar needs to be removed from one scene and placed in another, a second simulator is not involved. As the regions are out of sight of one another for the client's draw distance, no management of root and child agents is required (see [[Glossary]] for more information on agents).
| + | Normally, no configuration is required. However, from OpenSimulator 0.7.6 onwards, one can force the simulator to always use the older SIMULATION/0.1 protocol to send an avatar to another simulator, receive an avatar from another simulator or both. |
| | | | |
| − | Same simulator, in-sight teleport is similar to out-of-sight teleport except that some management of agents (e.g. downgrade root agent to child on the source region) needs to be done.
| + | ==Using SIMULATION/0.1 to send an avatar to another region== |
| | | | |
| − | Different simulator, out-of-sight teleport is similar to same simulator, out-of-sight teleport except that the need to communicate between different simulator processes increases the complexity of the teleport and often introduces a network dependency (unless the simulators are hosted on the same machine).
| + | The protocol version used for outgoing teleports is controlled by the MaxOutgoingTransferVersion attribute in the [EntityTransfer] section of OpenSim.ini. Specifying |
| | | | |
| − | Different simulator, in-sight teleport is the more complex normal grid teleport, since not only is there an interaction between source simulator, destination simulator and viewer, but upgrade and downgrades between child and root agents need to be managed as well.
| + | [EntityTransfer] |
| | + | MaxOutgoingTransferVersion = "SIMULATION/0.1" |
| | | | |
| − | =Same simulator, Out-of-sight=
| + | here will make the simulator use this earlier protocol for outgoing teleports even if the destination has SIMULATION/0.2 available (all such simulators should also have SIMULATION/0.1 available). See OpenSimDefaults.ini for more details. |
| | | | |
| − | This is a detailed description of the steps performed for a same simulator, out-of-sight region teleport.
| + | ==Using SIMULATION/0.1 to receive an avatar from another region== |
| | | | |
| − | Key: V = viewer, S = source region, D = destination region, SCh = source region with child agent, DCh = destination region which should have child agent, G = grid service.
| + | In this case, one needs to use the ConnectorProtocolVersion in the [SimulationService] section of StandaloneCommon.ini or GridCommon.ini as appropriate. For example |
| | | | |
| − | Steps:
| + | [SimulationService] |
| | + | ConnectorProtocolVersion = "SIMULATION/0.1" |
| | | | |
| − | * V->S, Viewer sends TeleportLocationRequest UDP packet to its current simulator. This holds the desired destination region co-ordinates.
| + | =References= |
| − | * Source simulator checks the user is allowed to teleport in principle.
| + | |
| − | * V->G, Source tries to retrieve information about the destination region from the grid service.
| + | |
| − | * Source checks destination is within max teleport distance. This is because most Second Life compatible viewers cannot teleport further than 4096 regions due to implementation and possibly protocol limitations.
| + | |
| − | * S->D, Source contacts the destination simulator to check whether the agent is allowed to teleport to the destination region. Failure may occur here because the destination simulator is unavailable, the region is not letting any users in, etc.
| + | |
| − | * S->V, If everything is okay, the viewer is sent a TeleportStart UDP packet. This is a very simple packet that just tells the viewer that the teleport is in progress. At this point on the viewer, the 3D scene will be replaced by a teleport progress screen (classically black with a progress bar in the middle).
| + | |
| − | * Source calculates whether the destination region is in-sight. In this case, it is out-of-sight.
| + | |
| − | * S->D, Therefore, source asks destination to create an agent in anticipation of a connection from the viewer. The agent starts as a child agent - it will be upgraded to a root agent on a successful connection. The session circuit code is passed on so that the destination simulator can recognize a new connection from the viewer.
| + | |
| − | * S->SCh*, If create agent request is successful, source requests closure of existing child agents which were allowing the user to see events in neighbouring and other in-sight regions at the source location.
| + | |
| − | ** These close requests go from the source simulator to in-sight regions which may be on the same simulator or different simulators.
| + | |
| − | ** SCh*->V, Each close requests triggers a client connection close. This tears down the client circuit, removes the scene presence (the primary code representation of the agent in the scene) and sends the client a DisableSimulator event via the Event Queue HTTP capability.
| + | |
| − | * S->V, Source simulator sends an EnableSimulator Event Queue message for the destination region to the viewer. This triggers the viewer to send the initial UseCircuitCode UDP packet to the destination simulator to establish a new connection.
| + | |
| − | * S->V, Very shortly afterwards, the source simulator sends an EstablishAgentCommunication Event Queue message to the viewer. This contains the destination simulators HTTP capability root URL. This triggers the viewer to send a SEED capability request to the destination simulator. The destination replies with all the capabilities that are available on that simulator.
| + | |
| − | * S->D, Source sends the destination simulator is sent more information about the incoming connection via the UpdateAgent inter-region communication message.
| + | |
| − | * S->V, The source sends the viewer a TeleportProgress UDP packet. This is just a status update and advances the viewer's waiting bar for the teleport.
| + | |
| − | * S->V, The source sends the viewer a TeleportFinish Event Queue message.
| + | |
| − | * The source now waits 10 seconds for a ReleaseAgent inter-region message from the destination simulator that the new connection is operational.
| + | |
| − | * V->D, The TeleportFinish message sent to the viewer triggers it to send a CompleteAgentMovement UDP packet to the destination simulator on the newly established UDP connection.
| + | |
| − | ** This triggers the destination simulator to upgrade the previously established child agent to a full root agent.
| + | |
| − | ** D->S, The destination simulator calls back the source simulator with a ReleaseAgent inter-region message to tell it that the new connection was successfully established.
| + | |
| − | ** D->DCh*, The destination simulator asks neighbouring regions to initiate child agent connections if appropriate.
| + | |
| − | ** DCh*->V, Each new child agent requests triggers an EnableSimulator EQ message from the destination child agent region to the viewer.
| + | |
| − | * Once the source receives the ReleaseAgent message, it cleans up the old presence by removing the avatar and its attachments from the source scene. The agent is downgraded from a root agent to a child agent.
| + | |
| − | * S->V, Since the source region is no longer in sight, this child agent is closed completely. This triggers a DisableSimulator Event Queue message from the source simulator to the viewer for the old connection.
| + | |
| | | | |
| − | For reference, these are the relevant log entries taken from a successful teleport of Justin Clark-Casey from a region called "test two" to a region called "test one". This was taken with non-constant packets logged (via the "debug packet 1" command on the console) and high level of inbound and outbound non-poll events logged (via the "debug http all 6" console command). The OpenSimulator commit was dc460579 (post 0.7.4). The exact messages displayed will almost certainly change in the future.
| + | * [[Teleport Protocol]] - an extremely in depth look at the teleport protocol. |
| − | | + | |
| − | <pre style="white-space: pre-wrap;
| + | |
| − | white-space: -moz-pre-wrap;
| + | |
| − | white-space: -pre-wrap;
| + | |
| − | white-space: -o-pre-wrap;
| + | |
| − | word-wrap: break-word">
| + | |
| − | 22:55:07 - [CLIENT]: PACKET IN from Justin Clark-Casey (root ) in test two - TeleportLocationRequest
| + | |
| − | 22:55:07 - [ENTITY TRANSFER MODULE]: Teleporting Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from test two to http://192.168.1.2:9000/ (http://192.168.1.2:9000/) test one/<136.5267, 124.713, 24.37189>
| + | |
| − | 22:55:07 - [ENTITY TRANSFER MODULE]: Destination is running version SIMULATION/0.1
| + | |
| − | 22:55:07 - [CLIENT]: PACKET OUT to Justin Clark-Casey (root ) in test two - TeleportStart
| + | |
| − | 22:55:07 - [SCENE]: Region test one told of incoming child agent Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 (circuit code 364119402, IP 192.168.1.2, viewer Second Life Release 3.3.4.262321, teleportflags (ViaLocation), position <136.5267, 124.713, 24.37189>)
| + | |
| − | 22:55:07 - [WEB UTIL]: HTTP OUT 37 SynchronousRestForms POST http://localhost:8003/presence
| + | |
| − | 22:55:07 - [WEB UTIL]: HTTP OUT 37 took 5ms, 2ms writing
| + | |
| − | 22:55:07 - [SCENE]: Region test one authenticated and authorized incoming child agent Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 (circuit code 364119402)
| + | |
| − | 22:55:07 - [CAPS]: Registered seed capability /CAPS/a39ede5d-c895-43c0-8936-ff1e9e6eb9fb0000/ for e4f3924a-5a7c-4e1a-bee7-aa96580f2515
| + | |
| − | 22:55:07 - [REGION CONSOLE]: /CAPS/47e88d6a-8f9a-4457-95e0-a51fdb4c1b90 in region test one
| + | |
| − | 22:55:07 - [SCENE PRESENCE]: Closing child agents. Checking 1 regions in test two
| + | |
| − | 22:55:07 - [ENTITY TRANSFER MODULE]: Set release callback URL to http://192.168.1.2:9000/agent/e4f3924a-5a7c-4e1a-bee7-aa96580f2515/dd5b77f8-bf88-45ac-aace-35bd76426c82/release/ in test two
| + | |
| − | 22:55:07 - [SCENE]: Incoming child agent update for e4f3924a-5a7c-4e1a-bee7-aa96580f2515 in test one
| + | |
| − | 22:55:07 - [LLUDPSERVER]: Handling UseCircuitCode request for circuit 364119402 to test one from IP 192.168.1.2:49350
| + | |
| − | 22:55:07 - [SCENE]: Adding new child scene presence Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 to scene test one at pos <136.5267, 124.713, 24.37189>
| + | |
| − | 22:55:07 - [BASE HTTP SERVER]: HTTP IN 185 :9000 stream handler POST /CAPS/a39ede5d-c895-43c0-8936-ff1e9e6eb9fb0000/ SEED from 192.168.1.2:45311
| + | |
| − | 22:55:07 - [BASE HTTP SERVER]: <llsd><array><string>AttachmentResources</string><string>AvatarPickerSearch</string><string>ChatSessionRequest</string><string>CopyInventoryFromNotecard</string><string>CreateInventoryCategory</string><string>DispatchRegionInfo</string><string>EstateChangeInfo</string><string>EventQueueGet</string><string>EnvironmentSettings</string><string>ObjectMedia</string><string>ObjectMediaNavigate</string><string>FetchLib2</string><string>FetchLibDescendents2</string><string>FetchInventory2</string><string>FetchInventoryDescendents2</string><string>GetDisplayNames</string><string>GetTexture</string><string>GetMesh</string><string>GetObjectCost</string><string>GetObjectPhysicsData</string><string>GroupProposalBallot</string><string>HomeLocation</string><string>LandResources</string><string>MapLayer</string><string>MapLayerGod</string><string>MeshUploadFlag</string><string>NewFileAgentInventory</string><string>ParcelPropertiesUpdate</string><string>ParcelMediaURLFilterList</string><string>ParcelNavigateMedia</string><string>ParcelVoiceInfoRequest</string><string>ProductInfoRequest</string><string>ProvisionVoiceAccountRequest</string><string>RemoteParcelRequest</string><string>RequestTextureDownload</string><string>ResourceCostSelected</string><string>SearchStatRequest</string><string>SearchStatTracking</string><string>SendPostcard</string><string>SendUserReport</string><string>SendUserReportWithScreenshot</string><string>ServerReleaseNotes</string><string>SimConsole</string><string>SimulatorFeatures</string><string>SetDisplayName</string><string>SimConsoleAsync</string><string>StartGroupProposal</string><string>TextureStats</string><string>UntrustedSimulatorMessage</string><string>UpdateAgentInformation</string><string>UpdateAgentLanguage</string><string>UpdateGestureAgentInventory</string><string>UpdateNotecardAgentInventory</string><string>UpdateScriptAgent</string><string>UpdateGestureTaskInventory</string><string>UpdateNotecardTaskInventory</string><string>UpdateScriptTask</string><string>UploadBakedTexture</string><string>ViewerMetrics</string><string>ViewerStartAuction</string><string>ViewerStats</string></array></llsd>\n...
| + | |
| − | 22:55:07 - [BASE HTTP SERVER]: HTTP IN 185 :9000 took 6ms
| + | |
| − | 22:55:07 - [BASE HTTP SERVER]: HTTP IN 186 :9000 stream handler GET /CAPS/92a66f2a-fff7-4fac-9044-49de791fc8af SimulatorFeatures e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from 192.168.1.2:45313
| + | |
| − | 22:55:07 - [BASE HTTP SERVER]: ...
| + | |
| − | 22:55:07 - [BASE HTTP SERVER]: HTTP IN 186 :9000 took 3ms
| + | |
| − | 22:55:08 - [CLIENT]: PACKET OUT to Justin Clark-Casey (root ) in test two - TeleportProgress
| + | |
| − | 22:55:08 - [ENTITY TRANSFER MODULE]: Sending new CAPS seed url http://192.168.1.2:9000/CAPS/a39ede5d-c895-43c0-8936-ff1e9e6eb9fb0000/ from test two to Justin Clark-Casey
| + | |
| − | 22:55:08 - [LLUDPSERVER]: Handling UseCircuitCode request for circuit 364119402 to test one from IP 192.168.1.2:49350
| + | |
| − | 22:55:08 - [SCENE PRESENCE]: Completing movement of Justin Clark-Casey into region test one in position <136.5267, 124.713, 24.37189>
| + | |
| − | 22:55:08 - [SCENE]: Upgrading child to root agent for Justin Clark-Casey in test one
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 38 SynchronousRestForms POST http://localhost:8003/friends
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 38 took 5ms, 1ms writing
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 39 SynchronousRestForms POST http://localhost:8003/presence
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 39 took 106ms, 1ms writing
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 40 SynchronousRestForms POST http://localhost:8003/griduser
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 40 took 40ms, 1ms writing
| + | |
| − | 22:55:08 - [SCENE PRESENCE]: Releasing Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 with callback to http://192.168.1.2:9000/agent/e4f3924a-5a7c-4e1a-bee7-aa96580f2515/dd5b77f8-bf88-45ac-aace-35bd76426c82/release/
| + | |
| − | 22:55:08 - [SCENE PRESENCE]: baked textures are in the cache for Justin Clark-Casey
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 41 SynchronousRestForms POST http://localhost:8003/grid
| + | |
| − | 22:55:08 - [WEB UTIL]: HTTP OUT 41 took 2ms, 0ms writing
| + | |
| − | 22:55:08 - [BASE HTTP SERVER]: HTTP IN 190 :9000 stream handler GET /CAPS/0020/74679c6b-bb43-41a6-8282-37676a85d005 EnvironmentSettings e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from 192.168.1.2:45320
| + | |
| − | 22:55:08 - [BASE HTTP SERVER]: ...
| + | |
| − | 22:55:08 - [CLIENT]: PACKET OUT to Justin Clark-Casey (child) in test two - KillObject
| + | |
| − | 22:55:08 - [SCENE PRESENCE]: Making Justin Clark-Casey a child agent in test two
| + | |
| − | 22:55:08 - [BASE HTTP SERVER]: HTTP IN 190 :9000 took 12ms
| + | |
| − | 22:55:10 - [CLIENT]: Close has been called for Justin Clark-Casey attached to scene test two
| + | |
| − | 22:55:10 - [SCENE]: Removing child agent Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from test two
| + | |
| − | 22:55:11 - [ENTITY TRANSFER STATE MACHINE]: Agent e4f3924a-5a7c-4e1a-bee7-aa96580f2515 cleared from transit in test two
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | = Legacy documentation =
| + | |
| − | | + | |
| − | This documentation is legacy because in part it refers to components and mechanisms that have since been changed. Chiefly, grid services are now discrete services hosted by a standalone or in one or more ROBUST instances - the discrete user, inventory, etc. servers no longer exist. Also inventory is no longer fully loaded onto a simulator when a root agent arrives there - instead it is pulled from the grid inventory service on-demand.
| + | |
| − | | + | |
| − | == Grid Teleport Procedure ==
| + | |
| − | | + | |
| − | [[Image:GridTeleports.jpg|500px]]
| + | |
| − | | + | |
| − | == Hypergrid Teleport Procedure ==
| + | |
| − | | + | |
| − | [[Image:HypergridTeleports.jpg|500px]]
| + | |
| − | | + | |
| − | == Open Grid Protocol Teleport Procedure ==
| + | |
| − | | + | |
| − | See [http://wiki.secondlife.com/wiki/OGP_Explained#Teleport OGP Explained "Teleport"]
| + | |
| − | | + | |
| − | == Related ==
| + | |
| − | | + | |
| − | [[Image:Child-event-queue.png|500px]]
| + | |
| − | | + | |
| − | == Teleports in OpenSimulator as of 2009-02-06 ==
| + | |
| − | | + | |
| − | [[Image:Teleport.jpg]]
| + | |
| − | | + | |
| − | == Teleport Study (2009-03-05) ==
| + | |
| − | | + | |
| − | The following four pictures compare the current agent transfer scheme with 3 possible agent transfer schemes. The different schemes have slightly different requirements with respect to authentication.
| + | |
| − | | + | |
| − | [[Image:TPCurrent.JPG]]
| + | |
| − | | + | |
| − | [[Image:TPScenarioA.JPG]]
| + | |
| − | | + | |
| − | [[Image:TPScenarioB.JPG]]
| + | |
| − | | + | |
| − | [[Image:TPScenarioC.JPG]]
| + | |
A teleport is the transfer of a user's connection (represented in-world by their avatar) from one location to another. These locations can be
In OpenSimulator 0.7.5 and for many releases previously, a teleport protocol called SIMULATION/0.1 was used. In OpenSimulator 0.7.6 and after, a teleport protocol called SIMULATION/0.2 is used by default. However, OpenSimulator can still use the SIMULATION/0.1 protocol required by older versions and will automatically inter-operate with them.
If you want to know an eye-watering amount of nitty-gritty about how this works, then please see the Teleport Protocol page.
Normally, no configuration is required. However, from OpenSimulator 0.7.6 onwards, one can force the simulator to always use the older SIMULATION/0.1 protocol to send an avatar to another simulator, receive an avatar from another simulator or both.
The protocol version used for outgoing teleports is controlled by the MaxOutgoingTransferVersion attribute in the [EntityTransfer] section of OpenSim.ini. Specifying
here will make the simulator use this earlier protocol for outgoing teleports even if the destination has SIMULATION/0.2 available (all such simulators should also have SIMULATION/0.1 available). See OpenSimDefaults.ini for more details.
In this case, one needs to use the ConnectorProtocolVersion in the [SimulationService] section of StandaloneCommon.ini or GridCommon.ini as appropriate. For example
