lookat vector with OsTeleportAgent & OsTeleportOwner

I’ve noticed various advice about how to point the agent (i.e. your avatar) after teleporting using a script in OpenSim. This is done with OsTeleportAgent and OsTeleportOwner. Unlike llMapDestination, the lookat vector is actually implemented, which is rather pleasing. However, there is no documentation on how to use it, at the time of writing.

There are no clear instructions anywhere on the Web, and some of the advice I have seen appears to be wrong. For instance, one person suggested putting a prim on the ground in the direction you want your avatar to look and then using its coordinates. I can confirm that this does not work except for in one case (rather like the stopped clock being correct once a day). It is not a Euler vector in radians corresponding to a rotation, so please don’t waste your time trying stuff like llRot2Euler(rot) and so on. This will simply confuse you for longer than is necessary.

It appears that these work if you are teleporting within a region, but the lookat vector simply fails if you are teleporting between regions. In inter-region teleports, I am always pointing due East, or slightly turned to the SE if I am too near to non-phantom objects. It just doesn’t work, whatever the numbers are. However, intra-region teleports appear to work as follows:

Teleporting within the same region

In fact, the actual numbers in the vector don’t seem to matter if they are high enough, and only X & Y work at all because your avatar will not be pointing upwards. Quite simply, due North is <0,10,0>, due South is <0,-10,0>, due East is <10,0,0>, due West is <-10,0,0> and so on. The figure 10 is arbitrary. I’ve found it works with any positive number. Provided that X and Y are equal, this would mean that NE is <10,10,0>, SE is <10,-10,0>, SW is <-10,-10,0> and NW is <-10,10,0>. You can work out the minor points of the compass yourself from those, I hope.

So, to summarise, the agent is pointing in the direction of the relative axes, not rotated around them as with other vectors.

Another very weird aspect of OsTeleportAgent and OsTeleportOwner is that, after saving the script and teleporting, you will notice that it always fails the first time but succeeds on every subsequent attempt. This seems to be a very minor, completely reproducible bug. This confused me for a long time, leading me to much unnecessary extra fiddling with my scripts before I realised how it actually works.

Teleporting to other regions

Apparently, any lookat vector will currently give the same result. I am currently using the OpenSim 0.7.5 release version.

Further notes

I used the following syntax (the second variant in the documentation):

void osTeleportAgent(string agent, string regionName, vector position, vector lookat)

void osTeleportOwner(string regionName, vector position, vector lookat)

I have not tested the other two variants:

void osTeleportAgent(string agent, integer regionX, integer regionY, vector position, vector lookat)

void osTeleportOwner(integer regionX, integer regionY, vector position, vector lookat)

void osTeleportAgent(string agent, vector position, vector lookat)

void osTeleportOwner(vector position, vector lookat)

The former pair just show an alternative way of describing a region, using its coordinates rather than its name. The variant that I have used is the best for hypergrid even though the documentation wrongly says it can only be used for a local grid. The code examples prove otherwise. Obviously, the last variant is only useful within the current region. There is no reason to think – although I have not tested this – that the lookat vector behaves any differently in inter-region teleports based on how you specify which region is your destination. However, just as a last caveat, I should add that I did this testing within a local grid, as I have not yet had time to wait for the often slow hypergrid teleports in order to test it on hypergrid fully.

Please let me know if you’ve found any relevant bug reports or documentation that I’ve missed 🙂

It’s a real shame that the lookat vectors only work within the current region, as they are very useful.