llTeleportAgent

From Second Life Wiki
Revision as of 10:45, 23 March 2023 by Dyna Mole (talk | contribs)
Jump to navigation Jump to search

Summary

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

Teleports an agent to a landmark stored in the object's inventory.

If landmark is an empty string, the avatar is teleported to the location position in the current region.

If the destination is in the current region, the avatar will land facing look_at as a position within that region. Otherwise, look_at is treated as a unit direction.

• key agent – 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 position within the region that 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 agent.

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 (no more than 10 teleports within 15 seconds)
  • 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 avatar 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.
  • When look_at is treated as a direction, a valid input should be <llCos(angle), llSin(angle), 0.0>.
    • In other words, it should be a unit vector corresponding to the avatar turning angle radians from north.

Examples

Basic example with a landmark called Destination in the object's inventory: 

default
{
    touch_start(integer num_detected)
    {
        llRequestPermissions(llGetOwner(), PERMISSION_TELEPORT);
    }

    run_time_permissions(integer perm)
    {
        if (PERMISSION_TELEPORT & perm)
        {
            llTeleportAgent(llGetPermissionsKey(), "Destination", ZERO_VECTOR, ZERO_VECTOR);
        }
    }
}

Basic example without a landmark in the object's inventory, while facing the avatar towards the center of the region: 

default
{
    touch_start(integer num_detected)
    {
        llRequestPermissions(llGetOwner(), PERMISSION_TELEPORT);
    }

    run_time_permissions(integer perm)
    {
        if (PERMISSION_TELEPORT & perm)
        {
            vector region_pos = <100, 130, 40>;
            vector look_at = <128,128,40>;
            llTeleportAgent(llGetPermissionsKey(), "", region_pos, look_at);
        }
    }
}

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 agent)
    {
        llTeleportAgent(agent, "Landmark", ZERO_VECTOR, ZERO_VECTOR);
    }
}

Below is an example of properly handling the look_at value based on whether the destination is the current region or a different one. This ensures that the avatar will always be facing the same direction regardless of whether they're teleporting within the region or to another one.

The script keeps track of the landmark's destination coordinate in the state_entry and changed events, which is later used to calculate the total distance of the teleport. 

string landmark;
vector destination;

default
{
    state_entry()
    {
        // Get data about the first landmark in object inventory when script starts.
        if (llGetInventoryNumber(INVENTORY_LANDMARK) > 0) {
            landmark = llGetInventoryName(INVENTORY_LANDMARK, 0);
            llRequestInventoryData(landmark);
        }
    }

    changed(integer change)
    {
        if (!(change & (CHANGED_INVENTORY|CHANGED_REGION))) return;

        // Get data about the first landmark in object inventory when inventory changes.
        if (llGetInventoryNumber(INVENTORY_LANDMARK) > 0) {
            landmark = llGetInventoryName(INVENTORY_LANDMARK, 0);
            llRequestInventoryData(landmark);
        }
    }

    dataserver(key query, string data)
    {
        // Save llRequestInventoryData response.
        destination = (vector)data;
    }

    touch_start(integer num_detected)
    {
        llRequestPermissions(llGetOwner(), PERMISSION_TELEPORT);
    }

    run_time_permissions(integer perm)
    {
        if (!(PERMISSION_TELEPORT & perm)) return;

        float angle = 45 * DEG_TO_RAD;

        // When teleporting to another region, we need a direction vector.
        vector look_at = <llCos(angle), llSin(angle), 0>;

        float sim_size = llVecMag(<1,1,1>);
        float distance = llVecDist(<1,1,1>, destination / 256);

        if (distance < sim_size) {
            // When teleporting within the current region, we should use a position within the region instead.
            look_at = destination + look AT;
        }

        llTeleportAgent(llGetPermissionsKey(), landmark, ZERO_VECTOR, look_at);
    }
}
Another example, submitted by Jesse Barnett, shows how to use a list of landmarks inside a HUD to allow teleporting, even inside a no-script area: Teleport HUD.

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

Signature

function void llTeleportAgent( key agent, string landmark, vector position, vector look_at );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlTeleportAgent&oldid=1213764"