Saturday, November 1, 2014

Tool: Messenger/Sender Tool

[Black Tulip] Messenger/Sender Tool

(c) 2012 Auryn Beorn

Messenger/Sender Tool in Marketplace.

TABLE OF CONTENTS



FEATURES

The [Black Tulip] Messenger/Sender Tool (Messenger) is a HUD (Heads Up Display) that allows you to perform the following functions for all the avatars listed in the configuration notecard:

  • Send all the notecards contained in the HUD, plus a message
  • Send all the landmarks contained in the HUD, plus a message
  • Send all the objects contained in the HUD, plus a message
  • Send all the items (no matter the asset type) contained in the HUD, plus a message
  • Send only a message
  • Get a list of the UUIDs and avatar names of all the avatars on the sim to copy/paste in your configuration notecard

NOTE: The script itself and the configuration notecard will NOT be sent to the avatars listed in your notecard.



INSTALLATION AND USE OF YOUR MESSENGER TOOL


Wear the object [Black Tulip] Messenger/Sender Tool (wear/center). It will attach to the center attachment point of your avatar. It consists of a panel (touch area) showing all the options. Clicking the various areas of the HUD will activate the indicated function.

To use the HUD, simply Edit it, and drag the notecards/landmarks/objects/etc that you want to send into the Contents of the HUD. There are no restrictions over the number of items you can send. Check the IMPORTANT NOTES ABOUT THE ASSETS YOU WISH TO SEND section of this document for in depth notes.

Edit the configuration notecard [Black Tulip] Messenger/Sender Tool - CONFIG according to the rules of the THE CONFIGURATION NOTECARD section below.

Your HUD is ready to use.

This first version of the tool has the following options, in order from top to bottom, left to right:

Send notecard/s and message
This will ask you to type a message in a certain channel. This channel is set in the configuration notecard. You have five minutes to complete writing your message.

After writing the message and pressing ENTER, the Messenger will send all the notecards contained in the Contents of the HUD (with the exception of the configuration notecard [Black Tulip] Messenger/Sender Tool - CONFIG) together with the message, to all the avatars you have listed in the configuration notecard.

Send landmarks/s and message
This will ask you to type a message in a certain channel. This channel is set in the configuration notecard. You have five minutes to complete writing your message.

After writing the message and pressing ENTER, the Messenger will send all the landmarks contained in the Contents of the HUD together with the message, to all the avatars you have listed in the configuration notecard.

Send object/s and message
This will ask you to type a message in a certain channel. This channel is set in the configuration notecard. You have five minutes to complete writing your message.

After writing the message and pressing ENTER, the Messenger will send all the objects contained in the Contents of the HUD together with the message, to all the avatars in your list in the configuration notecard to all the avatars you have listed in the configuration notecard.

Send all and message
This will ask you to type a message in a certain channel. This channel is set in the configuration notecard. You have five minutes to complete writing your message.

After writing the message and pressing ENTER, it will send all the assets contained in the Contents of the HUD (with the exception of the configuration notecard [Black Tulip] Messenger/Sender Tool - CONFIG and the main script [Black Tulip] Messenger/Sender Tool) together with the message, to all the avatars you have listed in the configuration notecard.

Get avatars' data as list
This will output in local chat, in an owner-say message (that is, only you can see it) a list of all the UUIDs and avatar names from the avatars in the sim where you are, in a suitable format to directly copy/paste them in your configuration notecard.

Scripts can't write notecards, so this option will help you in adding UUIDs and names to your list.

Send message
This will ask you to type a message in a certain channel. This channel is set in the configuration notecard. You have five minutes to complete writing your message.

After writing the message and pressing ENTER, it will send this message to all the avatars you have listed in the configuration notecard.


THE CONFIGURATION NOTECARD


The configuration notecard must be placed in the Contents of the HUD together with the [Black Tulip] Messenger/Sender Tool script, and it has to be named [Black Tulip] Messenger/Sender Tool – CONFIG.

As we can see in the sample notecard, its format is very simple:

# [Black Tulip] Messenger/Sender Tool - CONFIG
# Lines beginning by # are ignored

channel = 5

766f3817-2f2a-469d-acfa-9789080ecc85|Auryn Beorn
c1502900-1696-45e8-904f-c58a1995c33d|Auryn (Resident)

It supports a single parameter, which must be named channel, assigned a number, as in the sample:

channel = 5

This means that the HUD will ask you to input your messages in channel #5. If you wish to use a different chat channel, simply edit the notecard in the object and change 5 to the channel number of your preference.

Then, following the channel parameter, you simply type a list indicating the avatars to whom you want to send notecards, landmarks, etc. Use one line per avatar, having this format:

UUID|Avatar Name

The | is a separator character (often called a "pipe"). You can specify whatever avatar name you prefer. This is simply informative for you; the HUD will always inform you of the progress of the task it is performing, by saying to which avatar it has sent the information, and this will be the name the HUD will use.

Check the HOW DO WE GET THE AVATAR KEY? section to learn about retrieving the UUID of an avatar.


IMPORTANT NOTES ABOUT THE ASSETS YOU WISH TO SEND


Because of a Second Life scripting limitation, the items have to be sent one at a time, per avatar. Each item sent adds a delay of 2 seconds, so if you have a long collection of items to be sent to a long list of avatars, expect the script to take some time. It will inform you of its progress, but it will require the time.

Unless stated otherwise, the references to permissions explained now are permissions for the owner of the object. That is, you.

To make sure that there won't be issues in using this tool, your assets should have one of the following permissions for you:
    Copy - Modify - Transfer (that is, FULL PERMS)
    Copy - No Modify - Transfer

If the items you want to send are not full permissions, but copy/no modify/transfer, you will have to rez the HUD, drag the desired items into its Contents, and then take the HUD back into your inventory before attaching it.

If you attempt to send a no copy asset (for you), or a no transfer asset (for you), the HUD will output an error message.

You may set permissions for NEXT OWNER as you deem necessary! It's permissions for you that need to be copy and transfer. If you're unclear about the difference between permissions for owner, and permissions for next owner, check this tutorial about the basics on permissions in SL.


HOW DO WE GET THE AVATAR KEY?


Some viewers, like Firestorm, show you the avatar key as you open a profile, over the name. But in case you don't have a viewer that allows you to obtain the key of an avatar from the avatar name, this box also contains an object that will allow you to get the key of an avatar.

Rez the object [Black Tulip] Request UUID avatar. You'll see appear a black sphere with white text over it: Click here to request an avatar UUID.

When you click the sphere, it will turn to green and the text over it will change to: Type in chat /1 FirstName LastName (New avatars, LastName = Resident)

For example, to find the key for the avatar Auryn Beorn, we have to do the following:

  • Click the sphere.
  • Type in chat:
    /1 Auryn Beorn

Then the sphere will return us text like the following:

[22:34:44]  [Black Tulip] Request UUID avatar: 0 => 4454> Auryn Beorn: Name2Key.Lookup
[22:34:45]  [Black Tulip] Request UUID avatar: 0 => 4454> Found: 766f3817-2f2a-469d-acfa-9789080ecc85

and will go back to black.

If we want to find the key of an avatar without surname, we have to add Resident, as follows (don't confuse the name with the display name!):

  • Click the sphere.
  • Type in chat:
    /1 Auryn Resident

The sphere, again, will return us text like the following:

[22:12:24]  [Black Tulip] Request UUID avatar: 0 => 214> Auryn Resident: Name2Key.Lookup
[22:12:25]  [Black Tulip] Request UUID avatar: 0 => 214> Found: c1502900-1696-45e8-904f-c58a1995c33d

and will go back to black.

To minimize lag, the sphere will wait for our request a maximum of 2 minutes. If no request has been done during two minutes, the sphere will go back to black and we'll have to click it again if we want to get an avatar key from a name.


If you have any problem with this script, please give a complete description of your issue in the following 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