Difference between revisions of "LlTeleportAgent"

From Second Life Wiki
Jump to navigation Jump to search
(Added the example of how to use this function in an Experience)
({{Jira|SVC-7987}})
Line 1: Line 1:
{{LSL_Function
{{LSL_Function
|inject-2={{LSL Function/avatar|avatar|region=*}}{{LSL Function/inventory|landmark|type=landmark|uuid=false|empty=(for teleporting within the same region)}}{{Issues/BUG-4062}}
|inject-2={{LSL Function/avatar|avatar|region=*}}{{LSL Function/inventory|landmark|type=landmark|uuid=false|empty=(for teleporting within the same region)}}{{Issues/BUG-4062}}{{Issues/SVC-7987}}
|inject-3={{LSL_Function/permission|PERMISSION_TELEPORT|grant={{LSLP|avatar}}}}
|inject-3={{LSL_Function/permission|PERMISSION_TELEPORT|grant={{LSLP|avatar}}}}
|func=llTeleportAgent
|func=llTeleportAgent
Line 7: Line 7:
|p2_type=string|p2_name=landmark|p2_desc
|p2_type=string|p2_name=landmark|p2_desc
|p3_type=vector|p3_name=position|p3_desc=The position within the local region to teleport the avatar to if no landmark was provided.
|p3_type=vector|p3_name=position|p3_desc=The position within the local region to teleport the avatar to if no landmark was provided.
|p4_type=vector|p4_name=look_at|p4_desc=The position within the target region that the avatar should be turned to face upon arrival.
|p4_type=vector|p4_name=look_at|p4_desc=The direction the avatar should be turned to face upon arrival.
|func_desc=Requests a teleport of {{LSLP|avatar}} to a {{LSLP|landmark}} stored in the object's inventory.  If no landmark is provided (an empty string), the avatar is teleported to the location {{LSLP|position}} in the current region. In either case, the avatar is turned to face the position given by {{LSLP|look_at}} in local coordinates.
|func_desc=Requests a teleport of {{LSLP|avatar}} to a {{LSLP|landmark}} stored in the object's inventory.  If no landmark is provided (an empty string), the avatar is teleported to the location {{LSLP|position}} in the current region. In either case, the avatar is turned to face the position given by {{LSLP|look_at}} in local coordinates.
|func_footnote
|func_footnote

Revision as of 18:55, 12 March 2016

Summary

Function: llTeleportAgent( key avatar, string landmark, vector position, vector look_at );

Requests a teleport of avatar to a landmark stored in the object's inventory. If no landmark is provided (an empty string), the avatar is teleported to the location position in the current region. In either case, the avatar is turned to face the position given by look_at in local coordinates.

• key avatar avatar UUID that is in the same region (the avatar to teleport, must be the owner)
• string landmark a landmark in the inventory of the prim this script is in or an empty string (for teleporting within the same region)
• vector position The position within the local region to teleport the avatar to if no landmark was provided.
• vector look_at The direction the avatar should be turned to face upon arrival.

To run this function the script must request the PERMISSION_TELEPORT permission with llRequestPermissions and it must be granted by avatar.

Caveats

  • If landmark is not an empty string and...
    • landmark is missing from the prim's inventory or it is not a landmark then an error is shouted on DEBUG_CHANNEL.
Permissions
  • Once the PERMISSION_TELEPORT permission is granted there is no way to revoke it except from inside the script (for example, with a new llRequestPermissions call) or the script is reset or deleted.
  • This function can only teleport the owner of the object (unless part of an Experience).
  • Teleports are throttled
  • This function cannot be used in a script in an object attached using llAttachToAvatarTemp.
  • Sitting avatars cannot be teleported using this function. You must llUnSit them first.
  • This function does not override a parcel's teleport settings, i.e. if the parcel has a landing zone enabled the agent will be teleported there.
  • If the script is part of an experience that the avatar has granted permission, then this function may teleport them without being the owner and it will override parcel teleport routing. See the example below.
All Issues ~ Search JIRA for related Bugs

Examples

Without a landmark in the object's inventory

key  teleportee;

default
{
    state_entry()
    {
        llSay(0, "Touch to teleport");
    }

    touch_start(integer total_num)
    {
        teleportee = llDetectedKey(0);
        llRequestPermissions(teleportee, PERMISSION_TELEPORT);
    }
    
    run_time_permissions(integer perm)
    {
        if(PERMISSION_TELEPORT & perm)
        {
            llTeleportAgent(teleportee, "", <13.0, 38.0, 23.5>, <13.0, 12.0, 23.5>);
        }
    }
}

With a landmark in the objects inventory

key  teleportee;

default
{
    state_entry()
    {
        llSay(0, "Touch to teleport");
    }

    touch_start(integer total_num)
    {
        teleportee = llDetectedKey(0);
        llRequestPermissions(teleportee, PERMISSION_TELEPORT);
    }
    
    run_time_permissions(integer perm)
    {
        if(PERMISSION_TELEPORT & perm)
        {
            llTeleportAgent(teleportee, "Experience Tools 1", <0.0, 0.0, 0.0>, <0.0, 0.0, 0.0>);
        }
    }
}

How to use this function in an Experience

// A SIMPLE SCRIPT that implements an Experience based teleport.
// Compile with the "Use Experience" box cnecked and an experience key you own selected.
// The prim containing this script must contain a landmark named "Landmark" in its contents
//
// If the person touching this box has not previously accepted an invitation to your experience,
// that person will be offered that opportunity when this prim is touched, and if the invitations
// is accepted, will be immediately teleported to the target of the landmark.
//
// If the toucher has previously accepted an invitation, the person will be immediately teleported
// with no interruption.
//
// The script has no safety features, e.g., will simply fail if the prim contains no landmark.
//
// Thanks to Rolig Loon for her help in figuring out how to do this
// See https://community.secondlife.com/t5/English-Knowledge-Base/Experiences-in-Second-Life/ta-p/2744686
// to read what the Lindens think is an adequate explanation of all this.


default
{
    touch_start(integer n)
    {
        llRequestExperiencePermissions(llDetectedKey(0), "");
    }
    
    experience_permissions(key av)
    {
        llTeleportAgent(av, "Landmark", ZERO_VECTOR, ZERO_VECTOR);
    }
 
}

See Also

Events

•  run_time_permissions Permission receiving event

Functions

•  llGetPermissions Get the permissions granted
•  llGetPermissionsKey Get the agent who granted permissions
•  llRequestPermissions Request permissions
•  llTeleportAgentGlobalCoords Teleports an agent to a global position.

Articles

•  Script permissions

Deep Notes

History

Date of Release 24/07/2012

All Issues

~ Search JIRA for related Issues
   llTeleportAgent() and llTeleportAgentGlobalCoords() can break any script in any attached object that contains a changed event.
   llTeleportAgent always points in the positive Y direction on teleport

Signature

function void llTeleportAgent( key avatar, string landmark, vector position, vector look_at );