Recommendation: GSI CLEP (v1)
Channel and message protocol for efficient and flexible LSL chat communication
The Global Scripting Institute (GSI) is an informal organization of Second Life® users that design and test standards for efficient, flexible, and readable scripts in Second Life. "Second Life®" and "Second Life Grid™" are trademarks of Linden Research, Inc., d/b/a Linden Lab. The Global Scripting Institute and its catalog are not affiliated with with or sponsored by Linden Research.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The Chat link_message Extension Protocol (CLEP) is a protocol for inter-script chat communication in Linden Scripting Language (LSL).
CLEP transmits link_message Extension Protocol (LEP) messages over chat to scripts in other linksets in the same region. LEP is a data format that allows scripts to rapidly route messages to individual scripts in a linkset. Combined, LEP and CLEP allow scripts to transmit LEP messages to any other script in the region that is listening for CLEP messages on the message's channel.
CLEP uses llRegionSay and llRegionSayTo to pass LEP messages as serialized data to other objects.
CLEP messages MUST be sent either to a specific prim or all prims in a region. CLEP does not provide any method to send messages to any other groupings of prims.
Messages sent to a specific prim listening to a channel MUST be constructed as follows:
llRegionSayTo( target_prim, channel, serialized_message );
Messages sent to all prims listening to a channel MUST be constructed as follows:
llRegionSay( channel, serialized_message );
The message will only be delivered if the recipient has called llListen with the same channel.
| Placeholder | Type | Description |
|---|---|---|
target_prim |
key | MUST be the UUID of the target prim, if sending a message to a specific prim. |
channel |
integer | MUST be the result of the CLEP Channel Hash Utility Function described below. |
serialized_message |
string | MUST be the result of the CLEP Message Serialization Function described below. |
The CLEP Channel Hash Utility Function (CHUF) generates an integer channel based on a CHUF domain.
The CHUF must be defined as follows:
integer channel = (integer)("0x" + llGetSubString(llSHA256String(domain), -8, -1));
if ( channel == PUBLIC_CHANNEL || channel == DEBUG_CHANNEL ) channel++; // filter out channels that can be seen in the viewer by default
| Placeholder | Type | Description |
|---|---|---|
service |
string | MUST be a string of any value. The value MUST NOT contain any newline ("\n") characters. This value SHOULD be shared among all scripts that use any single implementation of CLEP. This is to prevent crosstalk between different systems listening on the same domain. For example, if two script systems are in a single prim and both use the prim's UUID as a domain, this value lets both mutually exclude each others' CLEP traffic. |
domain |
string | MUST be a string of any value. The value MUST NOT contain any newline ("\n") characters. This value can be treated as an arbitrary "string channel". By separating CHUF traffic in each domain to a different integer channel, CLEP messages from other domains are filtered server-side - messages not sent to the same domain will not trigger a listen event in the first place.A domain SHOULD be a pre-shared string, the prim's UUID, another prim's UUID, or some combination of the three, as desired. |
The CLEP Message Serialization Function (MSF) serializes a list with any characters into a string with the ability to detect truncation in transit.
The MSF must be defined as follows:
TODO
TODO
CLEP was authored by Nelson Jenkins on behalf of GSI.