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).

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

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

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

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

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:

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

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

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

However there is no implicit conversion with llListFindList. llListFindList requires not only the values to match but also the types.

llListFindList(["01234567-89ab-cdef-0123-456789abcdef"], [(key)"01234567-89ab-cdef-0123-456789abcdef"]) == -1;


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:

llOwnerSay("secondlife:///app/agent/" + (string)owner_key + "/about");

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:

llOwnerSay("secondlife:///app/group/" + (string)group_key + "/about");

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:

llOwnerSay("secondlife:///app/parcel/" + (string)parcel_key + "/about");

Testing for a valid key:

To test for a valid key, just do this:

if(uuid){
     //do something
}

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:

// 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);
}

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) { /* wont work */ }
    
    then you can use a simple workaround like so:
    if (uuid) { } else { /* will work */ }
    
    This is particularly useful if we wish to discard invalid string content (i.e - ensure that a key is actually a key) like so:
    if (uuid) ; else uuid = NULL_KEY;
    
  • 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.
  • Furthermore, LSO and Mono do not work the same when it comes to typecasting strings to keys.
    • There is a bug in LSO that LL has declined to fix, the reason given is that fixing it would break existing content.