Difference between revisions of "LlTeleportAgentGlobalCoords"

From Second Life Wiki
Jump to navigation Jump to search
m (changed example script)
m
(14 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{LSL_Function
{{LSL_Function
|inject-1={{LSL Generic/pre-release|3=RC LeTigre channel}}
|inject-2={{LSL Function/avatar|agent|region=*}}{{Issues/BUG-4062}}{{Issues/SVC-7987}}
|inject-2={{LSL Function/avatar|agent|region=*}}
{{LSL Function/position|region_coordinates|region=*}}
|inject-3={{LSL_Function/permission|PERMISSION_TELEPORT|grant={{LSLP|agent}}}}
|inject-3={{LSL_Function/permission|PERMISSION_TELEPORT|grant={{LSLP|agent}}}}
|func=llTeleportAgentGlobalCoords
|func=llTeleportAgentGlobalCoords
|func_desc=Teleports an {{LSLP|agent}} to set of a {{LSLP|region_coordinates}} within a region at the specified {{LSLP|global_coordinates}}.  The agent lands facing the position defined by {{LSLP|look_at}} local coordinates.  A region's global coordinates can be retrieved using <code>[[llRequestSimulatorData]](region_name, DATA_SIM_POS)</code>
|func_desc=Teleports an {{LSLP|agent}} to set of a {{LSLP|region_coordinates}} within a region at the specified {{LSLP|global_coordinates}}.  The agent lands facing the direction defined by {{LSLP|look_at}}.  A region's global coordinates can be retrieved using <code>[[llRequestSimulatorData]](region_name, DATA_SIM_POS)</code>
|func_footnote=The combination of [[llRequestSimulatorData]] and [[llTeleportAgentGlobalCoords]] allows agents to be teleported to regions by region name.
|func_footnote=The combination of [[llRequestSimulatorData]] and [[llTeleportAgentGlobalCoords]] allows agents to be teleported to regions by region name.
|p1_type=key|p1_name=agent|p1_desc=&#32;(avatar to be teleported)
|p1_type=key|p1_name=agent|p1_desc=&#32;(avatar to be teleported)
|p2_type=vector|p2_name=global_coordinates|p2_desc=Global coordinates of the destination region. Can be retrieved by using [[llRequestSimulatorData]](region_name, DATA_SIM_POS).
|p2_type=vector|p2_name=global_coordinates|p2_desc=Global coordinates of the destination region. Can be retrieved by using [[llRequestSimulatorData]](region_name, DATA_SIM_POS).
|p3_type=vector|p3_name=region_coordinates|p3_desc=Destination position inside the target region, given in local coordinates.
|p3_type=vector|p3_name=region_coordinates|p3_desc=&#32;where the avatar should land.
|p4_type=vector|p4_name=look_at|p4_desc=Location avatar will face after completing the teleport, given in local coordinates.
|p4_type=vector|p4_subtype=direction|p4_name=look_at|p4_desc=direction the avatar should be facing on landing (east, west, etc).
|caveats=
|caveats=
* '''This function can only teleport the owner of the object''' (unless part of an [[:Category:Experience Tools|Experience]]).
* Teleports are throttled
* This function cannot be used in a script in an object attached using [[llAttachToAvatarTemp]].
* 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.
* Sitting avatars cannot be teleported using this function. You must [[llUnSit]] them first.
|examples=<lsl>
* 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.
* {{LSLPT|look_at}} is ''not'' the coordinates of a point in the region. The {{LSLPT|look_at}} vector is <code><llCos(facing), llSin(facing), 0.0></code> where '''facing''' is the angle towards which the arriving avatar is to look.
** To look at a specific point in the region: <code>look_at = point - region_coordinates</code>
|examples=<source lang="lsl2">
string simName = "Help Island Public";
string simName = "Help Island Public";
vector simGlobalCoords;
vector landingPoint = <128.0, 128.0, 24.0>;
vector landingPoint = <128.0, 128.0, 24.0>;


key avatarToBeTeleported;
key owner;
vector globalSimCoordinates;
 


default
default
Line 25: Line 33:
     {
     {
         llResetScript();
         llResetScript();
    }
    changed(integer change)
    {
        if (change & CHANGED_OWNER)
            llResetScript();
     }
     }


     state_entry()
     state_entry()
     {
     {
        owner = llGetOwner();
        llRequestPermissions(owner, PERMISSION_TELEPORT);
         llRequestSimulatorData(simName, DATA_SIM_POS);
         llRequestSimulatorData(simName, DATA_SIM_POS);
     }
     }
Line 34: Line 51:
     touch_start(integer total_number)
     touch_start(integer total_number)
     {
     {
         avatarToBeTeleported = llDetectedKey(0);
         key id = llDetectedKey(0);


         if (globalSimCoordinates == ZERO_VECTOR)
         if (id == owner)
         {
         {
             llRegionSayTo(avatarToBeTeleported, PUBLIC_CHANNEL, "Configuration error, teleport request has been denied. Please try again!");
             if (simGlobalCoords == ZERO_VECTOR)
             llResetScript();
            {
                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
         else
         {
         {
             llRegionSayTo(avatarToBeTeleported, PUBLIC_CHANNEL, "Teleporting you to: http://maps.secondlife.com/secondlife/" + llEscapeURL(simName) + "/" + (string)llRound(landingPoint.x) + "/" + (string)llRound(landingPoint.y) + "/" + (string)llRound(landingPoint.z) + "/");
            // llRegionSayTo is faster than llInstantMessage and we can assume
            llRequestPermissions(avatarToBeTeleported, PERMISSION_TELEPORT);
            // 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 perms)
     run_time_permissions(integer perm)
     {
     {
         if (perms & PERMISSION_TELEPORT)
         // if permission request has been denied (read ! as not)
            llTeleportAgentGlobalCoords(avatarToBeTeleported, globalSimCoordinates, landingPoint, ZERO_VECTOR);
        if (!(perm & PERMISSION_TELEPORT))
         else
         {
             llRegionSayTo(avatarToBeTeleported, PUBLIC_CHANNEL, "Teleport failed, you didn't grant permissions. Please try again!");
             llOwnerSay("I need permissions to teleport you!");
            llRequestPermissions(owner, PERMISSION_TELEPORT);
        }
    }


        llResetScript();
//  dataserver event only called if data is returned
    }
//  or in other words, if you request data for a sim that does
//  not exist this event will NOT be called


     dataserver(key query_id, string data)
     dataserver(key query_id, string data)
     {
     {
         globalSimCoordinates = (vector)data;
         simGlobalCoords = (vector)data;
        // llOwnerSay("Sim global coords: " + (string)simGlobalCoords);
     }
     }
}
}
</lsl>
</source>
|also_functions=
|also_functions=
{{LSL DefineRow||[[llRequestSimulatorData]]|Useful for requesting simulator position}}
{{LSL DefineRow||[[llRequestSimulatorData]]|Useful for requesting simulator position}}
Line 71: Line 107:
|cat3
|cat3
|cat4
|cat4
|history = Date of Release  [[ Release_Notes/Second_Life_Server/12#12.07.24.262437 | 24/07/2012 ]]
}}
}}

Revision as of 19:09, 12 March 2016

Summary

Function: llTeleportAgentGlobalCoords( key agent, vector global_coordinates, vector region_coordinates, vector look_at );

Teleports an agent to set of a region_coordinates within a region at the specified global_coordinates. The agent lands facing the direction defined by look_at. A region's global coordinates can be retrieved using llRequestSimulatorData(region_name, DATA_SIM_POS)

• key agent avatar UUID that is in the same region (avatar to be teleported)
• vector global_coordinates Global coordinates of the destination region. Can be retrieved by using llRequestSimulatorData(region_name, DATA_SIM_POS).
• vector region_coordinates position in region coordinates where the avatar should land.
• vector look_at direction the avatar should be facing on landing (east, west, etc).

To run this function the script must request the PERMISSION_TELEPORT permission with llRequestPermissions and it must be granted by agent. The combination of llRequestSimulatorData and llTeleportAgentGlobalCoords allows agents to be teleported to regions by region name.

Caveats

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.
  • look_at is not the coordinates of a point in the region. The look_at vector is <llCos(facing), llSin(facing), 0.0> where facing is the angle towards which the arriving avatar is to look.
    • To look at a specific point in the region: look_at = point - region_coordinates
All Issues ~ Search JIRA for related Bugs

Examples

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 event only called if data is returned
//  or in other words, if you request data for a sim that does
//  not exist this event will NOT be called

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

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
•  llRequestSimulatorData Useful for requesting simulator position
•  llTeleportAgent Teleporting agents to a landmark or position in the region.

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 llTeleportAgentGlobalCoords( key agent, vector global_coordinates, vector region_coordinates, vector look_at );