Don't click here unless you want to be banned.

LSL Wiki : exchangeToolDiscovery

HomePage :: PageIndex :: RecentChanges :: RecentlyCommented :: UserSettings :: You are

Tool Discovery Protocol

This protocol is used by the TrustNet HUD Avatar Scanner (supported starting at version 0.50) to discover "tools", that is, various scripts that can target avatars to perform a function. The idea is to use the scanner to select an avatar from the list by clicking on it, and then pass the selection to an external tool. This is intended to integrate with tools like security orbs, weapons that target a specific avatar, etc.


The object that wishes to implement the protocol must listen on channel 0x44470001 (or 1145503745 in decimal).

The text sent on the channel to the object implementing the protocol has a base format of llList2CSV([version, target_key, command]). Additional data is arguments to the command.

Field Type Description
version integer Protocol version number. Currently always 1.
target_key key Object key the message is destined to. If NULL_KEY, then destined to all the objects that hear it.
command string Command (see list below)
If the object implementing this protocol supports some sort of access control (for example, can only be used by its owner) it should ignore completely commands coming from objects owned by avatars that won't be able to use it.


The first stage of the protocol is the discovery process. The scanner sends the "discover" command, and all the objects wishing to appear on the menu must reply as quickly as possible. The reply to this command must be sent to the specified channel, which is randomly generated.

Field Type Description
version integer Protocol version number. Currently always 1.
target_key key NULL_KEY
command string "discover"
reply_channel integer Channel where to send the reply. Will be randomly generated.

Discovery Reply

The reply must be in the format of llList2CSV([version, name, priority]) sent to the channel indicated in the "discover" command.

Field Type Description
version integer Protocol version number. Currently always 1.
name string Name of the function the object replying performs. Must 24 characters or less, or the reply will be ignored. Must be unique.
priority integer Number from 1 to 10, indicating the importance of this function. Higher numbers have higher priority. If there are enough objects replying that they can't fit in the llDialog list (more than 12), the lowest priority entry will be dropped to make room for a new one. The TrustNet Avatar Scanner internally gives a higher priority to objects owned by the scanner's owner.
The name sent must be unique, as it is what will be displayed on the llDialog button. Only one function per object will be accepted.

Command Execution Request

If the tool is chosen to perform its function, then an execute command will be sent to the channel, with this format:

Field Type Description
version integer Protocol version number. Currently always 1.
target_key key Object's key
command string "execute"
avatar_key key Key of the avatar that was selected
avatar_name string Name of the avatar that was selected
The object should respond to this by performing whatever action it does on the avatar. If multiple actions may be performed, it should present them to the scanner's owner (obtained with llGetOwnerKey in the listen event) using llDialog.


In order to make it easier to extend the protocol if needed, all commands are prefixed with a version number. An object implementing the protocol should check the version number it just received, and if it doesn't recognize the version, the preferred action is to ignore the command completely.

Protocol Example

This is the timeline of the events that would happen when the full protocol is played out.

1. Scanner sends llList2CSV([version, NULL_KEY, "discovery", channel_num]) to channel 0x44470001.
2. Object replies with llList2CSV([version, "Test Object", 5]) sent to channel channel_num.
3. If "Test Object" is selected on the dialog, scanner sends llList2CSV([version, objects_key, "execute", avatar_key, avatar_name]) to channel 0x44470001.
4. Object performs the action on avatar avatar_key.

Example Source

This is the source for a script that would be detected by the scanner, and be possible to use with it.

// Example of Tool Discovery protocol, by Dale Glass

// Channel where the announcement request will be sent
integer  g_announce_channel = 0x44470001;

// Name the object will have in the tools list. Must be unique
string   g_name             = "Test";

// Priority, 1-10. Larger number = higher priority
integer  g_priority         = 5;

// Protocol version we speak
integer  g_protocol_version = 1;

default {
    state_entry() {
        llListen(g_announce_channel, "", NULL_KEY, "");
    listen(integer channel, string obj_name, key id, string str) {
        list tmp = llCSV2List(str);
        integer version  = llList2Integer(tmp,0);
        key     dest_key = llList2Key(tmp,1);
        string  command  = llList2String(tmp,2);

        if ( version != g_protocol_version ) return;
        if ( (dest_key != llGetKey()) && (dest_key != NULL_KEY) ) return;

        if ( command == "discover" ) {
            integer reply_chan = llList2Integer(tmp,3);
            llSay(reply_chan, llList2CSV([g_protocol_version, g_name, g_priority]));
            llOwnerSay("Replied to announcement request from " + obj_name);
        } else if ( command == "execute" ) {
            key    av_key  = llList2Key(tmp,3);
            string av_name = llList2String(tmp,4);

            // Perform our action
            llInstantMessage(av_key, "Test!");
            llOwnerSay("Executed command on " + av_name + " (" + (string)av_key + ")");
        } else {
            llOwnerSay("Unknown command: " + command);

Protocol Exchange
There is no comment on this page. [Display comments/form]