Monday, November 3, 2014

Tool: Simple Teleport System

[Black Tulip] Simple Teleport System

(c) 2014 Sei Lisa, Auryn Beorn

Simple Teleport System, in Marketplace.

If you're planning on setting up a teleport system, and all of your destination locations have Teleport Routing set to Anywhere, the simplest solution might be the most effective and user friendly for your customers, and that is what this script offers to you. Set up an object that will be the teleport panel via a notecard, and you can rez copies of this object, already set up, at all places where you need your teleport board.

Please read the following instructions carefully. There's a sample object included to guide you through an example set up, so you can then set up your own teleport board. If the script isn't working as it should, please read first the Troubleshooting section of this documentation. If your problem isn't described there, then fill the following form, explaining exactly what you did and what happened, and I'll get back to you.

TABLE OF CONTENTS




FEATURES


IMPORTANT: You need Teleport Routing set to Anywhere in all of your destination locations, in order for this script to work.

  • Configure several teleport points, anywhere (each destination location requires the Teleport Routing setting specified above)
  • Each teleport point has owner only/group/everybody (all) access
  • Menu shows allowing the user to click the location and so being teleported to it
  • Location shows in private chat too (the text will not be seen by others, only by the avatar clicking)


SET UP: WHAT ELEMENTS DO I NEED FOR THIS SYSTEM?


You need three items to set up the teleport system:

  • An object that you will use as teleport board
  • The [Black Tulip] Simple Teleport System script
  • The [Black Tulip] Simple Teleport System ~CFG~ configuration notecard

Included with this package, there's a teleport board ready for up to EIGHT destinations, the [Black Tulip] Simple Teleport SAMPLE OBJECT object. You can use that one if you prefer so.

We will have to:

  • Type an identifier we choose in the DESCRIPTION field of the prims that contain teleport panels
  • Use that identifier in the configuration notecard, to define the teleport points

There can be more than one prim containing teleport panels. Make sure that each prim has a DIFFERENT description than the rest.


SETUP: EXAMINING THE SAMPLE OBJECT


Rez the [Black Tulip] Simple Teleport SAMPLE OBJECT object. Inspect it, and pay attention to the DESCRIPTION field of the prims.

The root prim has no description.
The prim with the teleport panels has the following description:

tp

This description, tp, will be relevant to the configuration notecard.

If you were working with your own teleport panel object, and you have more prims that will contain teleport destinations, this is what you have to remember: give each teleport prim an UNIQUE description.

For example, the following descriptions would be okay in different prims:

tp
tp1
tp2
tpMainArea

while the following ones would not be okay:

tp
tp1
tp1
tp2

because tp1 shows twice. Make sure your descriptions are UNIQUE in the same object.


SETUP: THE CONFIGURATION NOTECARD


The configuration notecard is named [Black Tulip] Simple Teleport System ~CFG~, and it allows us to:

  • Write comment lines, for our own clarifications. Comment lines always begin with a # character.
  • Define the teleport points: what prim, face (showing one panel) correspond to a specific location, and the access type.
  • Define a default text other than Would you like to: showing on the menu.

With the exception of comment lines, all of the other lines have the structure:

parameter = value

The accepted parameter keywords are:

TP
In here, we relate prim+face with a specific location and access type for it

txtMenu
In here, we define a text other than the default Would you like to: that shows on the menu.

Now, let's explain how the values are written and what they mean.


TP = Prim-Desc|Face-Number|Region Name|X|Y|Z|Access

We specify the definition of a teleport destination after the = sign after the TP key word. We have to write down a series of values and separate them with the | character. What do all those Prim-Desc, Face-Number, etc. mean?

Prim-Desc
The description we have written for a teleport prim

Face-Number
The face number of a prim showing a teleport panel to be clicked upon

Region Name
The region name of the destination location

X
The X coordinate of the destination location

Y
The Y coordinate of the destination location

Z
The Z coordinate of the destination location

Access
A number identifying the type of access:
  • 0: Everyone will get the teleport menu when clicking on that panel
  • 1: Only those with the group tag activated will get the teleport menu when clicking on that panel
  • 2: Only the owner of the object will get the teleport menu when clicking on that panel

We write ONE of this lines PER teleport destination. If you don't know how to obtain Region Name, X, Y and Z, check the following section, How to obtain the region data. In a moment we analyze the meaning of the lines in the included [Black Tulip] Simple Teleport System ~CFG~ configuration notecard. Before that, let's complete the notecard specification, with the other possible value.

txtMenu = Text to show on the menu

By default, the menu shows the Would you like to: text, and then the teleport link. If you would like a different text before the teleport link, write it after the = sign, and do NOT write in separate lines! All the text should be together on the same line. If you're fine with the default text, then just leave the line commented, as it is in the supplied configuration notecard.

Let's examine now the TP = lines from the supplied [Black Tulip] Simple Teleport System ~CFG~ configuration notecard:

TP = tp|0|Casablanca Estates|193|112|25|0
TP = tp|1|Casablanca Estates|215|150|35|0
TP = tp|2|Casablanca Estates|185|170|26|0
TP = tp|3|Casablanca Estates|204|90|35|0
TP = tp|4|Casablanca Estates|225|148|25|0
TP = tp|5|Casablanca Estates|199|168|36|0
TP = tp|6|Casablanca Estates|124|126|22|0
TP = tp|7|Casablanca Estates|167|172|25|0

If we count the TP = lines, we see that we have EIGHT of them. This means that the panel object will hold eight different locations.

The first line says:

TP = tp|0|Casablanca Estates|193|112|25|0

This means: When we click on the prim with description tp, the face number 0, we will be offered to teleport to Casablanca Estates region, position X = 193, Y = 112, Z = 25, and everybody will get this menu, for the access is set to 0, in the last field.

The second line says:

TP = tp|1|Casablanca Estates|215|150|35|0

This means: When we click on the prim with description tp, the face number 1, we will be offered to teleport to Casablanca Estates region, position X = 215, Y = 150, Z = 35, and everybody will get this menu, for the access is set to 0, in the last field.

and similarly, we can now understand what the other lines mean.

If we had another prim with description, for example, tp1, we could add more lines like:

TP = tp1|0|Casablanca Estates|215|140|25|1

which would mean, when we click on the prim with description tp1, the face number 0, we will be offered to teleport to Casablanca Estates region, position X = 215, Y = 140, Z = 25, and only those with their group tag on would get this menu, for the access is set to 1, in the last field.

REMEMBER: *YOU* decide what description you want to give to your prims, and then you use those descriptions in the configuration notecard.

IMPORTANT: Do not use the = character in the description of the prim, and do not leave spaces around the | characters of the notecard. Be particularly careful with possible spaces at the end of the lines, for those are easily unnoticed.

If you ever lose your configuration notecard, your documentation has an embedded copy.


SETUP: THE CONFIGURATION NOTECARD - HOW TO OBTAIN THE REGION DATA


Let's take as an example the landmark included with your purchase.

In your inventory, right click on it and select the Show on Map option. This opens the world map, showing you a red circle highlighting the location. To the right, you have some information:


Highlighted, there's the name Casablanca Estates followed by a Find button. Casablanca Estates is the region name. We would write it exactly that way. Then, under Location, we see three numbers. They correspond, respectively, to the X, Y and Z position of the destination location. So 171 would be the number to write down for X, 128, the number for Y, and finally, 25, the number for Z.


SETUP: DROPPING THE SCRIPT AND NOTECARD


Now that the configuration notecard is ready, this is how we have to proceed:

  • Right click the LINKED panel object to Edit it.
  • Do NOT tick Edit Linked. This is to ensure that script and notecard will go to the root prim.
  • Click the Content tab of the Edit window.
  • Drag from your inventory and drop on said Content tab the [Black Tulip] Simple Teleport System ~CFG~ notecard.
  • Now, drag from your inventory and drop on the Content tab the [Black Tulip] Simple Teleport System script.
  • Close the Edit window.

You will see a message show up in your local/nearby chat window telling you when the script is ready.

If you need to change/add/remove locations, you can edit the notecard inside the object, or delete it, then edit the notecard in your inventory and drag and drop it again.


TROUBLESHOOTING


Q: The script does not recognize the name I have given to the teleport prims. What happens?

A: Make sure you have written the name in the DESCRIPTION field of the prims. If you use the Name field, the script will not know those are your teleport points.


Q: I have double-checked: I've written the names in the DESCRIPTION field of the prims, but the script does not work. What's wrong?

A: Make sure that name coincides exactly with the one you write in the notecard lines. Careful with spaces at the end of the description field, for those would go unnoticed.


Q: My customers say that they get the menu and click on the teleport link, but they're not teleported to the exact location. What's happening?

A: Make sure that the Teleport Routing setting of the land properties for that destination is set to ANYWHERE.


Q: I have a customer telling me that no link shows on the menu. What's wrong here?

A: It could be that your customer is using a way outdated viewer. They should update their viewer, but in any case, they also receive in local chat a link that they can click to teleport to the destination. Let them know about this.


For any other problem not described here, please give a complete description of your issue in the customer service online form. I'll get back to you after I have read your report and replicated your issue inworld, according to your description of it. Please, be detailed.

-- Auryn Beorn