The Ubiquitous Teleporter

In Second Life and OpenSim all of us very quickly learn how to teleport across sims or from sim to sim using Landmarks, or by double-clicking on the Map. This is a built-in function of these worlds. However one often comes across in-sim teleporters that will move you a distance across a sim using a method that requires you to sit on a prim. It is this type of teleportation that I will begin to look at in this post.

A good example of this method is the part of the Stairway of Learning where the user must pass across a gap from one side of the hyperdome to the other, as shown below.

Jumping the Gap

When the user steps on the sixth stair not only does the information board appear but an arrow with floating text also displays over the next step. The user clicks (sits) on this arrow to teleport across the gap to the descending set of steps on the other side of the hyperdome.

The Stairway of Learning Teleporter

The script that performs the teleportation uses functions that are associated with sitting or posing. When a user sits on a scripted prim the positioning of the user is determined using the function llSitTarget. This function describes an offset position (in metres) and a rotation relative to the prim’s position and rotation, using the syntax llSitTarget(vector offset, rotation rot). The following examples show two different sit targets using different offsets, i.e. X, Y and Z amounts, and zero rotation.

llSitTarget(<1.0, 0.0, 0.0>, ZERO_ROTATION)
Offset Forward on the X Axis

llSitTarget(<0.0, 2.0, 1.0>, ZERO_ROTATION)
Offset to the Side on the Y Axis
and Up on the Z Axis

Note: The sit target is a property of the prim so once it is set it will remain with the prim even if the script is removed. To remove a sit target the offset must be set to <0.0, 0.0, 0.0> or ZERO_VECTOR, i.e. llSitTarget(ZERO_VECTOR, ZERO_ROTATION). To sit “behind” the prim one would use a negative X amount, to sit below a negative Z amount and of course to the right of the prim (set as that shown above) a negative Y amount.

The most basic of sits would look like the following where a sit target is described in the state_entry event.

default
{
state_entry()
{
llSitTarget(<0.0, 0.0, 0.1>, ZERO_ROTATION);
}
}

So how does this translate to a teleporter. First of all it relies on the fact that the maximum offset on any axis in llSitTarget is 300 m. Having such a large offset allows it to be set so that the user can be sat away from the prim at most points across a sim that would be a destination required by a teleporter. The script can then be used to unsit the user leaving them with the illusion of having been teleported. To do this of course we must first expand the script above to find out when the prim has been sat upon and then script it further to unsit the avatar.

When an avatar sits on a prim they are considered to be linked to that prim, in much the same way that we use Ctrl L to link prims together as a grouped object. Therefore an avatar sitting on a prim, or an object made up of linked prims, increases the linked prim count by one (the avatar is considered to be only one prim even with attachments). Increasing (or decreasing) the number of links triggers an event called the changed event which can be used to tell if an avatar has sat on the prim and it is this event that is used in the next step of the teleporter.

changed(integer change)
{
if(change & CHANGED_LINK)
{
if(llAvatarOnSitTarget() != NULL_KEY)
{
//We know an avatar is linked
//and can now work with that here
}
}
}

Within the event is the first IF statement that checks what sort of change has occurred. The changed event can be used to detect a number of changes such as prim colour, scale or owner for example, but in this case it is checking whether the number of links has changed. Given that an avatar sitting on a prim is considered a link the first IF statement is true and the next IF statement runs. This second statement uses the llAvatarOnSitTarget function to determine if an avatar is using the sit target, i.e. sitting on the prim, by returning a key that is the UUID of the avatar. If the result is NULL_KEY then there is no avatar seated. Why is this done? Because the changed event will also run when the avatar unsits from the prim as the number of links has been reduced and there will be no need to run the second block of code if an avatar isn’t seated.

Once it is determined that an avatar has sat on the prim the script can then proceed to unsit them using the llUnSit function. This requires the UUID of the seated avatar to allow the llUnSit function to target them, so the llAvatarOnSitTarget function is used as the llUnsit parameter. The code below shows the script in its entirety with a sit target that places the avatar 10 m away from the initiating prim on the X axis (relative to the local prim coordinates).

default
{
state_entry()
{
llSitTarget(<10.0, 0.0, 0.0>, ZERO_ROTATION);
}

changed(integer change)
{
if(change & CHANGED_LINK)
{
if(llAvatarOnSitTarget() != NULL_KEY)
{
llUnSit(llAvatarOnSitTarget());
}
}
}
}

Note: Although an avatar can sit on a prim without a sit target, the sit target MUST be present for this script to work as it uses the llAvatarOnSitTarget function to check whether an avatar is seated.

This is the most basic of teleporter scripts and hopefully this post has given an insight into how it works. Varying levels of complexity can be added to the script that deal with specifying the destination, dealing with rotation issues of the prim, facing the avatar in a certain direction etc. For now I’ll leave it at the simple stage but in the future will add further posts that investigate these options.

Next in this Series: Teleporter Tweaks