llTeleportAgentGlobalCoords

void llTeleportAgentGlobalCoords(key AvatarID, vector GlobalPosition, vector RegionPosition, vector LookAtPoint)

Teleports an agent to the RegionPosition local coordinates within a region which is specified by the GlobalPosition global coordinates. The agent lands facing the position defined by LookAtPoint local coordinates.

Requires the PERMISSION_TELEPORT permission. This function can only teleport the owner of the object.

Parameters

AvatarID (key): UUID of avatar.
GlobalPosition (vector): Global coordinates of the destination region. Can be retrieved by using llRequestSimulatorData(region_name, DATA_SIM_POS).
RegionPosition (vector): The position within the target region to teleport the avatar to, if no landmark was provided.
LookAtPoint (vector): The position within the target region that the avatar should be turned to face upon arrival.

Technical Details

Return Type: void
Energy: 10

A region’s global coordinates can be retrieved using llRequestSimulatorData("region name", DATA_SIM_POS).

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

The combination of llRequestSimulatorData and llTeleportAgentGlobalCoords allows agents to be teleported to regions by region name.

Caveats

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; 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
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

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

    run_time_permissions(integer perm)
    {
        if (PERMISSION_TELEPORT & perm)
        {
            vector global_coord = <232704, 291072, 0>;
            vector region_pos = <122, 122, 40>;
            llTeleportAgentGlobalCoords(llGetPermissionsKey(), global_coord, region_pos, ZERO_VECTOR);
        }
    }
}

Handling Different Regions

This example keeps track of the current global coordinate and adjusts 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 current region’s global coordinate in state_entry and changed events, which is later used to check whether the destination has the same global coordinates.

vector current_region;

default
{
    state_entry()
    {
        // Get current global coordinate when the script starts.
        llRequestSimulatorData(llGetRegionName(), DATA_SIM_POS);
    }

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

        // Get current region coordinate when entering a new region.
        llRequestSimulatorData(llGetRegionName(), DATA_SIM_POS);
    }

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

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

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

        vector global_coord = <232704, 291072, 0>;
        vector region_pos = <122, 122, 40>;

        float angle = 45 * DEG_TO_RAD;
        vector look_at = <llCos(angle), llSin(angle), 0>;

        if (current_region == global_coord) {
            // When teleporting within the current region, we should use a position within the region instead.
            look_at = region_pos + look_at;
        }

        llTeleportAgentGlobalCoords(llGetPermissionsKey(), global_coord, region_pos, look_at);
    }
}

Teleporting by Region Name

This older example demonstrates how to use llRequestSimulatorData to get simulator coordinates by region name, then teleport an avatar to that region:

string simName = "Help Island Public";
vector simGlobalCoords;

vector landingPoint = <128.0, 128.0, 24.0>;

key owner;


default
{
    on_rez(integer start_param)
    {
        llResetScript();
    }

    changed(integer change)
    {
        if (change & CHANGED_OWNER)
            llResetScript();
    }

    state_entry()
    {
        owner = llGetOwner();

        llRequestPermissions(owner, PERMISSION_TELEPORT);
        llRequestSimulatorData(simName, DATA_SIM_POS);
    }

    touch_start(integer total_number)
    {
        key id = llDetectedKey(0);

        if (id == owner)
        {
            if (simGlobalCoords == ZERO_VECTOR)
            {
                llOwnerSay("Config error, tp request was denied. Please try again!");
                llResetScript();
            }
            else
            {
                llOwnerSay("Teleporting you to: http://maps.secondlife.com/secondlife/"
                    + llEscapeURL(simName) + "/" + (string)llRound(landingPoint.x)
                    + "/" + (string)llRound(landingPoint.y) + "/" + (string)llRound(landingPoint.z) + "/");

                llTeleportAgentGlobalCoords(owner, simGlobalCoords, landingPoint, ZERO_VECTOR);
            }
        }
        else
        {
            // llRegionSayTo is faster than llInstantMessage and we can assume
            // that the touching avatar is within the same sim

            llRegionSayTo(id, PUBLIC_CHANNEL,
                "Sorry, I can't tp you. You're NOT my owner!");
        }
    }

    run_time_permissions(integer perm)
    {
        // if permission request has been denied (read ! as not)
        if (!(perm & PERMISSION_TELEPORT))
        {
            llOwnerSay("I need permissions to teleport you!");
            llRequestPermissions(owner, PERMISSION_TELEPORT);
        }
    }

    dataserver(key query_id, string data)
    {
        simGlobalCoords = (vector)data;
        // llOwnerSay("Sim global coords: " + (string)simGlobalCoords);
    }
}