Category:LSL Key

From Second Life Wiki
Jump to navigation Jump to search

Intro:

A key is a universal unique identifier in Second Life for anything mostly, be it a prim, avatar, texture, etc.

You may see key referred to as UUID, UID, "Asset UUID", or "asset-ID".

The key itself is formed of "Wikipedia logo"hexadecimal characters [0-9a-f] and each section of the key is broken up by dashes (for a total amount of 36 characters).

<lsl>

   key whatever = "01234567-89ab-cdef-0123-456789abcdef";

</lsl>

Some keys in Second Life are a UUID-4 as defined in RFC-4122.

<lsl>

   key uuid = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx";

// where: // 4 is 4 // x is [0-9a-f] // y is [8-9a-b] </lsl>

Receiving keys:

There are several ways to acquire the key of something:

  1. Having someone supply it to you;
  2. Using a built-in LSL function such as llGetKey, llGetLinkKey etc.
  3. In your inventory, right-clicking over something and choosing Copy Asset UUID. Note this will only work on items that you have full permissions to.

Generating keys:

Built-in LSL functions:

function purpose
llGenerateKey Generates a key using Version 5 (SHA-1 hash) UUID generation to create a unique key.

User-defined functions:

function purpose
GenerateKey Generates an MD5-based (version 3) type UUID. Useful for identifying link-messages and for other purposes.
GenUUID Generates a UUID based on PHP com_create_guid.

Converting Keys:

When a key is supplied to you as a text string, you convert it to the key data-type like this:

<lsl>key whatever = (key)"01234567-89ab-cdef-0123-456789abcdef";</lsl>

Implicit conversion will happen automatically when supplying a string where a key is required.

<lsl>key uuid = "01234567-89ab-cdef-0123-456789abcdef"; llKey2Name("01234567-89ab-cdef-0123-456789abcdef");</lsl>

However there is no implicit conversion with llListFindList. llListFindList requires not only the values to match but also the types. Tip: ERR_GENERIC has the integer value -1.

<lsl>llListFindList(["01234567-89ab-cdef-0123-456789abcdef"], [(key)"01234567-89ab-cdef-0123-456789abcdef"]) == ERR_GENERIC;</lsl>


Displaying avatar or group information:

If you know an avatar's key, you can display the avatar's name in the viewer window and chat history by using the following special URL: <lsl>llOwnerSay("secondlife:///app/agent/" + (string)owner_key + "/about");</lsl>

This displays both display name and username as a clickable link that brings up an avatar profile window when clicked. It is easier than using llRequestAgentData or llRequestUsername or llRequestDisplayName, since there is no need to use a dataserver event.

If you know a group key (as a result of calling llGetObjectDetails(key id, [OBJECT_GROUP]), or calling llGetParcelDetails(vector pos, [PARCEL_DETAILS_GROUP])), you can display the group's name with the following special URL: <lsl>llOwnerSay("secondlife:///app/group/" + (string)group_key + "/about");</lsl>

This displays the group name as a clickable link that brings up a group profile window when clicked. This is especially useful since there is no other way to do this; there is no LSL function to print out a group's name.

Finally, if you know a parcel key (as a result of calling llGetParcelDetails(vector pos, [PARCEL_DETAILS_ID])), you can create a clickable link that brings up a place profile window when clicked, using the following special URL: <lsl>llOwnerSay("secondlife:///app/parcel/" + (string)parcel_key + "/about");</lsl>

Testing for a valid key:

To test for a valid key, just do this:

<lsl>if(uuid){

    //do something

}</lsl>

if(uuid) will only return true if it is supplied a key that is both (A) valid, and (B) NOT a NULL_KEY.

Tip! In techy talk, this method is called "passing it as the parameter for a conditional"

Note! It is important for the above example that uuid be defined as a key. It can of course be typecast to be a key as well: if((key)uuid)

Here is an example of how to build a function around this:

<lsl> // 2: valid key, not NULL_KEY // 1 (TRUE): NULL_KEY // 0 (FALSE): not a key

integer isKey(key in) {

   if (in)
       return 2;
   return (in == NULL_KEY);

} </lsl>

Caveats:

  • if (uuid) is a special case. Keys cannot be converted to integers, so logical operators such as !, || and && cannot be used with keys. If you wish to do if (!uuid) // Some action then you can use a simple workaround like so: if (uuid) {} else // Some action. This is particularly useful if we wish to discard invalid string content (i.e - ensure that a key is actually a key) like so:<lsl>if (uuid) ; else uuid = NULL_KEY;</lsl>
  • Be careful when adding key literals to lists, no implicit typecasting will take place. Failing to ensure that key literals are keys will cause problems with llListFindList.