Developer's Guide - OpenCollarTeam/OpenCollar GitHub Wiki

Introduction

Welcome to the OpenCollar Developer's Guide. This page is for OpenCollar (Plugin) Developers, mostly to give some insight in the message protocols. And as a reference.

Child prim scripts

Certain functions (scripts) reside in child prims. Those scripts identify themselves, using a LINK_ALL_OTHERS target, upon LINK_UPDATE "LINK_REQUEST" message, which will be triggered by the root prim upon every rez and CHANGED_LINK event. Child prim scripts are not to be merged together in a prim. Prim numbers below are defaults.
child prim 2: scripts: oc_anim, oc_couples (*) (also: all animations and notecard: .couples)
child prim 3: script: oc_dialog
child prim 4: script: oc_rlvsys
child prim 5: script: oc_settings
child prim 6: script: oc_auth
(*) oc_couples does not respond to LINK_UPDATE "LINK_REQUEST" messages.

The scripts will identify themselves with a LINK_UPDATE message containing respectively "LINK_ANIM", "LINK_DIALOG", "LINK_RLV", "LINK_SAVE" or "LINK_AUTH". Every script that needs one of these functions, should record the sender_num of those responses, usually in global integers LINK_ANIM, LINK_DIALOG, LINK_RLV, LINK_SAVE and LINK_AUTH

Message Map

Number of Internal Linked Messages (llMessageLinked()) are named by global integers. If a function is used that is served by a script in one of the child prims, their corresponding LINK_* global integer should be used, otherwise LINK_THIS, keeping the message within the root prim.

If sending a key (for id) is not relevant, use an empty string rather than NULL_KEY.

Most message numbers are being used in a protocol that can be categorized as Half Duplex; a response message will be sent back via a different message number. In case of a Full Duplex protocol, results will be sent back using the same message number. In some cases a child prim will relay a message back to all other prims. (For example: LM_SETTING_DELETE.)

REBOOT (-1000)

Instructs scripts to reboot themselves. Text MUST be "reboot" in order to comply.

LOADPIN (-1904)

Full duplex
LinkNumber: LINK_*
Request message: 'script name', Response message: 'pin'@'script name'
Key: child prim key (in response msg)

Used for letting child prims having their Remote Load Script Pin set, for updating purposes. Typical conversation:

  • Root prim sends LOADPIN "oc_dialog" to LinkNumber LINK_DIALOG
  • oc_dialog sends back to 'sender': LOADPIN "'pin'@oc_dialog", along with its child prim key
  • Root prim receives LOADPIN with sender_num of that of oc_dialog prim and the key of that prim, so the root prim can now load a script into this child prim, using llRemoteLoadScritPin().

LINK_UPDATE (-10)

Full Duplex

Used for requesting and reporting back child prim numbers. Typical conversation:

  • Upon CHANGED_LINK event or new rez, oc_sys broadcasts LINK_UPDATE "LINK_REQUEST" to LINK_ALL_OTHERS.
  • All child prim scripts (except oc_couples; which allows its sibling script oc_anim this responsibility) report their LinkNumber by replying to LINK_ALL_OTHERS and their specific child prim tag in the text parameter ("LINK_DIALOG", "LINK_AUTH", etc.)

Commands:

CMD_ZERO (0)

Used internally

CMD_OWNER (500)

CMD_TRUSTED (501)

CMD_GROUP (502)

CMD_WEARER (503)

CMD_EVERYONE (504)

CMD_RLV_RELAY (507)

CMD_SAFEWORD (510)

CMD_RELAY_SAFEWORD (511)

CMD_BLOCKED (520)

Messages & Dialogs:

POPUP_HELP (1001)

deprecated(?)

NOTIFY (1002)

LinkNumber: LINK_DIALOG Key: avatar

Sends a message to avatar specified with 'avatar'. The first character of the message MUST be a 0 or 1, stating whether this message must also be sent to the wearer of the OC device, (0 = FALSE, 1 = TRUE). Examples:

  • llMessageLinked(LINK_DIALOG, NOTIFY, "0Private message for 'avatar' only.", avatar);
  • llMessageLinked(LINK_DIALOG, NOTIFY, "1Very special feature now enabled.", avatar);
  • llMessageLinked(LINK_DIALOG, NOTIFY, "1This message will only be sent once", g_kWearer);

The message in last example will only be sent once, despite the '1' as its first character, because it already will be sent to the wearer (g_kWearer). If avatar is in the same region, llRegionSayTo() will be used, otherwise llInstantMessage(), which will result in a 1 second penalty delay for the oc_dialog script. Note: The message will be sent by the child prim, so its name, not the name of the root prim, will be used. See also: Substitution tokens

NOTIFY_OWNERS (1003)

LinkNumber: LINK_DIALOG
key: "ignoreNearby" or empty

Sends a message to all owners. If key id == "ignoreNearby" (yes, a string), the message will not be sent to owners that are within 20 meters range. The same substitution tokens as with NOTIFY apply as the same mechanism is used. This also means that if there are, for example, 20 owners defined, who are not in the same region, this function needs 20 seconds to complete, before it can do any other things, like presenting and processing dialogs.

SAY (1004)

LinkNumber: LINK_DIALOG

'Says' something in local chat. The first character of the message MUST be a 0 or 1, stating whether the message must be said (range 20 m) or whispered (range 10 m). In case of whispering, prefix "/me" will be used, so viewers can distinguish its text from regular chat, usually using italics. The same substitution tokens as with NOTIFY apply.

DIALOG (-9000)

LinkNumber: LINK_DIALOG

Starts a dialog. The text field contains avatar id, description prompt, page number, buttons, util buttons and auth level. The key id of this message must be a unique key (like generated with llGenerateKey() and will be used with response messages. Any new instantiations of dialogs by the same avatar will silently invalidate any old one. When no buttons are given (not even util buttons), a text box is presented, where the avatar can enter custom text.

[See OC Plugin template for an example on how to use the dialog.]

DIALOG_RESPONSE (-9001)

If an avatar presses a dialog button, this message will be broadcasted, containing the avatar's key, button text, page number and auth level. The key of the message will be that of the uniquely generated key, passed with the DIALOG message.

DIALOG_TIMEOUT (-9002)

If the avatar fails to press any button of a dialog created with DIALOG, within a specific period of time (300 seconds(?)), the dialog will invalidate itself and broadcast this DIALOG_TIMEOUT message, containing an empty message and the uniquely generated key as the message key.

SENSORDIALOG (-9003)

LinkNumber: LINK_DIALOG

FIND_AGENT (-9005)

deprecated(?)

Settings:

LM_SETTING_SAVE (2000)

LinkNumber: LINK_SAVE

Scripts can save settings with this message. The message must be of format "token=value" or "group_token=value". The use of underscores or equal signs in 'value' is discouraged. Once the setting has been saved, a confirmation message LM_SETTING_RESPONSE will be broadcasted back (to all prims, except that of LINK_SAVE itself). If a setting with the same token (or group_token) exists, it will be silently overwritten.

LM_SETTING_REQUEST (2001)

LinkNumber: LINK_SAVE

Request a setting from the settings storage. The token can either be "token" or "group_token". If the setting is found, it will be sent in a LM_SETTING_RESPONSE message, broadcasted to all prims (except that of LINK_SAVE itself) in form "token=value", or "group_token=value". If the setting is not found, a message LM_SETTING_EMPTY will be broadcasted instead, repeating the requested "token" or "group_token".
If token == "ALL" (all upper case), all settings will be sent back, each in a message of its own. An extra 'setting' "settings=sent" will be added as the last response message.
Note: When requesting ALL settings, there will be a deliberate delay of 2.0 seconds.

LM_SETTING_RESPONSE (2002)

Broadcast message in response to LM_SETTING_SAVE or LM_SETTING_REQUEST, in form "token=value" or "group_token=value", in case of LM_SETTING_REQUEST only if the setting was found.

LM_SETTING_DELETE (2003)

LinkNumber: LINK_SAVE Relay Duplex

Instructs the settings script to remove a setting, with form "token" or "group_token". oc_setting will relay this message to LINK_ALL_OTHERS, no matter what. If 'token' = "all" (lower case) when using form 'group_token' (for example: "myplugin_all"), all settings in the same 'group' ("myplugin") will be removed. There will be no response to this message, whether a setting(s) is found or not.

LM_SETTING_EMPTY (2004)

Broadcast message in response to LM_SETTING_REQUEST, returning requested "token" or "group_token", stating the setting was not found.

Menu injection/removal:

MENUNAME_REQUEST (3000)

MENUNAME_RESPONSE (3001)

MENUNAME_REMOVE (3003)

RLV:

RLV_CMD (6000)

LinkNumber: LINK_RLV

RLV_REFRESH (6001)

RLV plugins should reinstate their restrictions upon receiving this message.

RLV_CLEAR (6002)

RLV plugins should clear their restriction lists upon receiving this message.

RLV_VERSION (6003)

RLV Plugins can recieve the used RLV viewer version upon receiving this message.

RLVA_VERSION (6004)

RLV Plugins can recieve the used RLVa viewer version upon receiving this message.

RLV_OFF (6100)

Send to inform plugins that RLV is disabled now, no message or key needed

RLV_ON (6101)

Send to inform plugins that RLV is enabled now, no message or key needed

Animations:

ANIM_START (7000)

ANIM_STOP (7001)

ANIM_LIST_REQUEST (7002)

ANIM_LIST_RESPONSE (7003)

MVANIM_INIT (13000)

MVANIM_ANNOUNCE (13001)

MVANIM_SKIP (13002)

MVANIM_GIVE (13003)

Particles / Leash:

CMD_PARTICLE (20000)

CMD_LEASH_SENSOR (20001)

Substitution Tokens

The following tokens will be substituted in output functions like NOTIFY, SAY, DIALOG, etc.:

  • %PREFIX%
  • %CHANNEL%
  • %DEVICETYPE%
  • %WEARERNAME%
  • %NOACCESS% (will be replaced with "Access denied")