OGP Teleport Draft 5
Open Grid Protocol: Teleport
- Draft 5
- October 2008
- Notice: This draft is for public comment.
- Mark Lentczner (Zero Linden) Linden Lab zero.linden@secondlife.com
- Tess Chu (Tess Linden) Linden Lab tess@lindenlab.com
- Leyla Farazha (Leyla Linden) Linden Lab leyla@lindenlab.com
- Bill Humphries (Whump Linden) Linden Lab whump@lindenlab.com
- Copyright 2008, Linden Lab. All rights reserved.
- This work is licensed under the Creative Commons Attribution-Share Alike 3.0 license. See http://creativecommons.org/licenses/by-sa/3.0/for details.
- All contributions to this document must be contributed under the Second Life Project Contribution Agreement. See http://wiki.secondlife.com/wiki/Project:Contribution_Agreementfor details
- Abstract
- Teleport in Open Grid Protocol is the movement of an avatar into, among, and out of regions.
- Status
- As of Fall 2008, this protocol is a work in progress. While the major structural elements have been designed, the specific elements for many needed resources have not. This work is being undertaken by Linden Lab and its community based Architecture Working Group.
- This protocol is being defined in light of feature set of Second Life. For now, where this document is currently lacking details, familiarity with Second Life will be assumed. It is an express aim of this work to enable the live, gradual migration of Second Life to using this new protocol as the development proceeds. As development proceeds, notes will be made available indicating status of current protocol deployed on the Beta Grid.
Teleport Sequence
The Rez Avatar resources cover all forms of agent movement in and out of regions. In particular, it covers
- Initial placement in a region after logging in
- After logging in, most viewers will first invoke the Agent Information Resource which will find out this agent's home and last location.
- Crossing into an adjacent region
- ::Note: As currently deployed, Region Crossing does not yet use this protocol.
- Teleporting from one region to another
- Removing the agent from a region when logging out
- ::Note: This still needs to be hooked up in the deployed version.
On inital placement, Agent Domain acts as the "current region" as it holds the saved avatar data. On log out, Request Rez Avatar is implicit, and the Agent Domain acts as the "destination region", receiving and storing the saved avatar data. Derez Avatar is always granted upon Rez and stored away for the next placement.
In all cases, the sequence of resource invocations follows the same form. First, the Viewer invokes Place Avatar on the agent's Agent Domain. While processing Place Avatar, Agent Domain asks the destination region if the avatar can be placed by requesting and invoking the Request Rez Avatar resource. If the agent is already connected to a region, in the previous Teleport, the Agent Domain has already stored away the Derez Avatar capability for that agent. The Agent Domain passes the Rez Avatar capability to the (stored away) Derez Avatar capability, asking the current region to transfer the avatar to its destination. The current region in turn transfers the avatar to the destination by POST'ing to the Rez Avatar resource. The response to Rez Avatar is propagated all the way back to the Agent Domain, which passes the results overlayed with the response from Request Rez Avatar back to the Viewer. Finally, the Viewer establishes communication with destination region to begin simulation.
Avatar Data Vetted (Optional)
The client has the option to have the Agent Domain vet their avatar data when coming out of uncharted regions. In those cases, the Agent Domain will essentially log out of the previous region before entering untrusted region so that the Avatar Data can be compared to when the agent logs out of the untrusted region.
The sequence of resouce invocations are modified as follows: Upon entering the untrusted region, the Agent Domain calls its own Vetted Derez Avatar capability, saving away a the avatar state, before calling the untrusted region's Rez Avatar. Upon exiting the untrusted region, the Agent Domain passes its own Vetted Rez Avatar capability to Derez Avatar, which does a comparison check between the previously saved avatar state against the newly Derezed avatar state.
Informational Suite
- Note: These resource classes will probably move to other documents in the future as they contain information that is more broadly applicable than to just Teleport.
Agent Information (Resource Class)
Agent information capability is necessary for login as tells the client the agent_id for the authenticated avatar. This capabililty is normally attained from a global web service.
::Note: The deployed version combines this resource with agent/session, returning the agent_id and agent/session fields. See Agent Session resource. As currently deployed, home or last login location uses a legacy form of the Rez Avatar protocol which will be replaced by this resource.
GET Interface
%% agent/info -> undef
<- {
agent_id: uuid,
login_location: { home: uri, last: uri }
}
Agent Session (Resource Class)
An agent's session information is necessary for login and contains required information for connection to a region after Place Avatar. Presence indicates whether the agent is online and which region they are currently connected to. This capability is normally attained from the Agent Seed Capability.
::Note: Under development. See note in Agent Information resource.
GET Interface
&presence = {
status: "online",
; Note: As deployed, this field is named 'region_url'
; presence only specifies this field if the agent is online
public_region_seed_capability: uri
}
&presence = {
status: "pending_login"
}
&presence = {
status: "pending_logoff"
}
&presence = {
status: "offline"
}
%% agent/session -> undef
<- {
agent_id: uuid, ; the deployed version includes this, but will be moved to agent/info cap
circuit_code: int,
session_id: uuid,
secure_session_id: uuid,
presence, presence
}
Region Information (Resource Class)
A region's information is necessary for placing an avatar. The public region seed capability is public information.
GET Interface
%% public_region_seed_cap -> undef <- &resp
; success
&resp = {
capabilities: [ rez_avatar/request: uri ]
}
; error
&resp = {
message: string
}
- Note: In the future, the Public Region Seed Capability request may return capabilities other than rez_avatar/request.
Rez Avatar Suite
Place Avatar (Resource Class)
When this completes successfully, the avatar is now placed within the new region, and communications with the region can begin. This capability is normally attained from the Agent Seed Capability.
POST Interface
Many of the fields in the response body can also be retrieved via the Region Information resource.
%% rez_avatar/place -> {
; Note: As deployed, this field is named 'region_url'
public_region_seed_capability: uri,
position: [ real, real, real ] ; optional position in local coordinates
}
; response
<- {
connect: bool,
; Note: As deployed, this field is named 'seed_capability'
region_seed_capability: uri,
look_at: [ real, real, real ], ; x, y, z
position: [ real, real, real ], ; position in local coordinates
sim_host: string,
sim_port: int,
; Note: These fields are region information
region_id: uuid,
region_x: int,
region_y: int,
sim_access: 'PG' | 'Mature'
}
Request Rez Avatar (Resource Class)
Upon receiving a Place Avatar request, the Agent Domain makes a request to the region. If the request succeeds, the destination region has approved all agent information and is ready to receive avatar data for simulation. This capability is obtained by using the Public Region Seed Cap.
POST Interface
%% rez_avatar/request -> {
agent_id: uuid,
circuit_code: int,
secure_session_id: uuid,
session_id: uuid,
first_name: string,
last_name: string,
position: [ real, real, real ], ; optional
; Note: These fields are agent-domain specific and probably do not belong here.
age_verified: bool, ; optional
agent_access: 'PG' | 'Mature', ; optional
allow_redirect: bool, ; optional
god_level: int, ; optional
identified: bool, ; optional
transacted: bool, ; optional
limited_to_estate: int ; optional
; Note: The deployed version also includes some estate information about the previous region the agent is on. This is probably only relevant to the current Estate features of Second Life:
src_can_see_mainland: bool, ; optional
src_estate_id: int ; optional
}
; successful response
<- {
connect: true,
rez_avatar/rez: uri, ; this is a one-shot capability
rez_avatar/derez: uri, ; another one-shot capability
region_seed_capability: uri,
sim_host: string,
sim_port: int,
; Note: These fields are region information
region_id: uuid,
region_x: int,
region_y: int,
sim_access: 'PG' | 'Mature'
}
; general failure
<- {
connect: false,
message: string
}
Rez Avatar (Resource Class)
Rez the given avatar data onto a region. When this completes, the simulator should have everything it needs to begin simulation. This capability is normally attained from Request Rez Avatar Resource.
- Note: Many fields that should belong in the Request Rez Avatar response are also currently responded via Rez Avatar.
Vetted Rez Avatar (Resource Class)
The Agent Domain verifies that the Avatar Data being rezzed is consistent with the Avatar Data that has been stored away when the avatar first teleported into the region. Then it forwards the Avatar Data to the new region's Rez Avatar resource. This capability is normally granted by the Agent Domain during teleport out of a region that the client indicated needs to be vetted.
POST Interface
%% rez_avatar/rez -> {
avatar data: ? ; under construction
}
%% rez_avatar/vetted_rez
-> {
avatar_data: ? ; under construction
rez_avatar/rez: uri,
}
; successful response, including failure to grant seed capability
<- {
connect: true,
look_at: look_at,
position: position
}
; general failure
{
connect: false,
redirect: bool, ; Need to redirect.
resethome: bool, ; Need to Reset Home
message: string
}
Derez Avatar (Resource Class)
This resource serializes the avatar data and sends it off to another process via Rez Avatar.
The rez_avatar/derez capability for a region/agent pair is returned in the response to rez_avatar/request capability.
Vetted Derez Avatar (Resource Class)
The Agent Domain stores away the avatar data before the avatar is rezzed on an vetted region. This capability is normally granted by the Agent Domain during teleport into a region that the client indicated needs to be vetted.
POST Inferface
%% rez_avatar/derez -> {
rez_avatar/rez: uri, ; capability for the Rez Avatar resource
position: [ real, real, real ]
}
%% rez_avatar/vetted_derez
-> {
rez_avatar/rez: uri, ; capability for the Rez Avatar
position: [ real, real, real ]
}
; successful response, including failure to grant seed capability
<- {
connect: true,
look_at: look_at,
position: [ real, real, real ]
}
; general failure
<- {
connect: false,
reason: string ; human readable
}