LSL Protocol/Restrained Love Relay/Reference Implementation
This particular example that anyone can distribute freely as open-source only (you are not allowed to sell this code) and including the header comments is just meant to give an idea of how a relay basically works. You can find the change history at Change History.
What it does
- Implements the specification described hereabove.
- Commented to facilitate reading and learning.
- Tested and working with test objects and with real cages.
What it doesn't do
- Error-checking.
- Access lists.
- Lock on the avatar.
- Handle more than one object.
- Reject some commands by nature.
- And so much more that makes good scripts stand out in the crowd.
How to use it
- Create a prim in which you put a script containing this code (don't forget to name it correctly by following the "RLVnnn" requirement).
- Wear the prim, it says its current on/off status
- Click on the prim to switch from "Off" to "On with permission" to "On without permission" and back to "Off"
- Find an object that implements this specification and test.
Special thanks
- Chorazin Allen for reviewing the code, giving ideas, coding and re-coding his own scripts to make sure everything works properly between the relay and the cage, and for not killing me every time I change my mind here and there on the spec.
- Azoth Amat and Nano Siemens for helping to find a solution to the "force sit on login" problem
- Gregor Mougin for discovering and fixing the not-pong reply on login.
Reference Implementation
<lsl>
//~ RestrainedLife Viewer Relay Script example code
//~ By Marine Kelley
//~ 2008-02-03
//~ 2008-02-03
//~ v1.1
//~ 2008-02-16 with fixes by Maike Short
//~ 2008-02-24 more fixes by Maike Short
//~ 2008-03-03 code cleanup by Maike Short
//~ 2008-03-05 silently ignore commands for removing restrictions if they are not active anyway
//~ 2008-06-24 fix of loophole in ask-mode by Felis Darwin
//~ 2008-09-01 changed llSay to llShout, increased distance check (MK)
//~ This code is provided AS-IS, OPEN-SOURCE and holds NO WARRANTY of accuracy, //~ completeness or performance. It may only be distributed in its full source code, //~ this header and disclaimer and is not to be sold.
//~ * Possible improvements //~ Do some error checking //~ Handle more than one object //~ Periodically check that the in-world objects are still around, when one is missing purge its restrictions //~ Manage an access list //~ Reject some commands if not on access list (force remove clothes, force remove attachments...) //~ and much more...
// ---------------------------------------------------
// Constants
// ---------------------------------------------------
integer RLVRS_PROTOCOL_VERSION = 1020; // version of the protocol, stated on the specification page
string PREFIX_RL_COMMAND = "@"; string PREFIX_METACOMMAND = "!";
integer RLVRS_CHANNEL = -1812221819; // RLVRS in numbers integer DIALOG_CHANNEL = -1812220409; // RLVDI in numbers
integer MAX_OBJECT_DISTANCE = 100; // 100m is llShout distance integer MAX_TIME_AUTOACCEPT_AFTER_FORCESIT = 300; // 300 is 5 minutes
integer PERMISSION_DIALOG_TIMEOUT = 30;
integer LOGIN_DELAY_WAIT_FOR_PONG = 10; integer LOGIN_DELAY_WAIT_FOR_FORCE_SIT = 60;
integer MODE_OFF = 0; integer MODE_ASK = 1; integer MODE_AUTO = 2;
// ---------------------------------------------------
// Variables
// ---------------------------------------------------
integer nMode;
list lRestrictions; // restrictions currently applied (without the "=n" part) key kSource; // UUID of the object I'm commanded by, always equal to NULL_KEY if lRestrictions is empty, always set if not
string sPendingName; // name of initiator of pending request (first request of a session in mode 1) key sPendingId; // UUID of initiator of pending request (first request of a session in mode 1) string sPendingMessage; // message of pending request (first request of a session in mode 1) integer sPendingTime;
// used on login integer timerTickCounter; // count the number of time events on login (forceSit has to be delayed a bit) integer loginWaitingForPong; integer loginPendingForceSit;
key lastForceSitDestination; integer lastForceSitTime;
// --------------------------------------------------- // Low Level Communication // ---------------------------------------------------
debug(string x)
{
// llOwnerSay("DEBUG: " + x);
}
// acknowledge or reject ack(string cmd_id, key id, string cmd, string ack) {
llShout(RLVRS_CHANNEL, cmd_id + "," + (string)id + "," + cmd + "," + ack);
}
// cmd begins with a '@' sendRLCmd(string cmd) {
llOwnerSay(cmd);
}
// get current mode as string string getModeDescription() {
if (nMode == 0) return "RLV Relay is OFF"; else if (nMode == 1) return "RLV Relay is ON (permission needed)"; else return "RLV Relay is ON (auto-accept)";
}
// check that this command is for us and not someone else integer verifyWeAreTarget(string message) {
list tokens = llParseString2List(message, [","], []);
if (llGetListLength(tokens) == 3) // this is a normal command
{
if (llList2String(tokens, 1) == llGetOwner()) // talking to me ?
{
return TRUE;
}
}
return FALSE;
}
// --------------------------------------------------- // Permission Handling // ---------------------------------------------------
// are we already under command by this object? integer isObjectKnow(key id) {
// first some error handling
if (id == NULL_KEY)
{
return FALSE;
}
// are we already under command by this object?
if (kSource == id)
{
return TRUE;
}
// are we not under command by any object but were we forced to sit on this object recently?
if ((kSource == NULL_KEY) && (id == lastForceSitDestination))
{
debug("on last force sit target");
if (lastForceSitTime + MAX_TIME_AUTOACCEPT_AFTER_FORCESIT > llGetUnixTime())
{
debug("and recent enough to auto accept");
return TRUE;
}
}
return FALSE;
}
// check whether the object is in llShout distance. It could have moved
// before the message is received (chatlag)
integer isObjectNear(key id)
{
vector myPosition = llGetRootPosition(); list temp = llGetObjectDetails(id, ([OBJECT_POS])); vector objPostition = llList2Vector(temp,0); float distance = llVecDist(objPostition, myPosition); return distance <= MAX_OBJECT_DISTANCE;
}
// do a basic check on the identity of the object trying to issue a command integer isObjectIdentityTrustworthy(key id) {
key parcel_owner=llList2Key (llGetParcelDetails (llGetPos (), [PARCEL_DETAILS_OWNER]), 0);
key parcel_group=llList2Key (llGetParcelDetails (llGetPos (), [PARCEL_DETAILS_GROUP]), 0);
key object_owner=llGetOwnerKey(id);
key object_group=llList2Key (llGetObjectDetails (id, [OBJECT_GROUP]), 0);
debug("owner= " + (string) parcel_owner + " / " + (string) object_owner);
debug("group= " + (string) parcel_group + " / " + (string) object_group);
if (object_owner==llGetOwner () // IF I am the owner of the object
|| object_owner==parcel_owner // OR its owner is the same as the parcel I'm on
|| object_group==parcel_group // OR its group is the same as the parcel I'm on
)
{
return TRUE;
}
return FALSE;
}
// Is this a simple request for information or a meta command like !release?
integer isSimpleRequest(list list_of_commands)
{
integer len = llGetListLength(list_of_commands);
integer i;
// now check every single atomic command
for (i=0; i < len; ++i)
{
string command = llList2String(list_of_commands, i);
if (!isSimpleAtomicCommand(command))
{
return FALSE;
}
}
// all atomic commands passed the test
return TRUE;
}
// is this a simple atmar command // (a command which only queries some information or releases restrictions) // (e. g.: cmd ends with "=" and a number (@version, @getoutfit, @getattach) or is a !-meta-command) integer isSimpleAtomicCommand(string cmd) {
// check right hand side of the "=" - sign
integer index = llSubStringIndex (cmd, "=");
if (index > -1) // there is a "="
{
// check for a number after the "="
string param = llGetSubString (cmd, index + 1, -1);
if ((integer)param!=0 || param=="0") // is it an integer (channel number)?
{
return TRUE;
}
// removing restriction
if ((param == "y") || (param == "rem"))
{
return TRUE;
}
}
// check for a leading ! (meta command)
if (llSubStringIndex(cmd, PREFIX_METACOMMAND) == 0)
{
return TRUE;
}
// check for @clear
// Note: @clear MUST NOT be used because the restrictions will be reapplied on next login
// (but we need this check here because "!release|@clear" is a BROKEN attempt to work around
// a bug in the first relay implementation. You should refuse to use relay versions < 1013
// instead.)
if (cmd == "@clear")
{
return TRUE;
}
// this one is not "simple".
return FALSE;
}
// If we already have commands from this object pending // because of a permission request dialog, just add the // new commands at the end. // Note: We use a timeout here because the player may // have "ignored" the dialog. integer tryToGluePendingCommands(key id, string commands) {
if ((sPendingId == id) && (sPendingTime + PERMISSION_DIALOG_TIMEOUT > llGetUnixTime()))
{
debug("Gluing " + sPendingMessage + " with " + commands);
sPendingMessage = sPendingMessage + "|" + commands;
return TRUE;
}
return FALSE;
}
// verifies the permission. This includes mode // (off, permission, auto) of the relay and the // identity of the object (owned by parcel people). integer verifyPermission(key id, string name, string message) {
// is it switched off?
if (nMode == MODE_OFF)
{
return FALSE;
}
// extract the commands-part
list tokens = llParseString2List (message, [","], []);
if (llGetListLength (tokens) < 3)
{
return FALSE;
}
string commands = llList2String(tokens, 2);
list list_of_commands = llParseString2List(commands, ["|"], []);
// accept harmless commands silently
if (isSimpleRequest(list_of_commands))
{
return TRUE;
}
// if we are already having a pending permission-dialog request for THIS object,
// just add the new commands at the end of the pending command list.
if (tryToGluePendingCommands(id, commands))
{
return FALSE;
}
// check whether this object belongs here
integer trustworthy = isObjectIdentityTrustworthy(id);
string warning = "";
if (!trustworthy)
{
warning = "\n\nWARNING: This object is not owned by the people owning this parcel. Unless you know the owner, you should deny this request.";
}
// ask in permission-request-mode and/OR in case the object identity is suspisous.
if (nMode == MODE_ASK || !trustworthy)
{
sPendingId=id;
sPendingName=name;
sPendingMessage=message;
sPendingTime = llGetUnixTime();
llDialog (llGetOwner(), name + " would like control your viewer." + warning + ".\n\nDo you accept ?", ["Yes", "No"], DIALOG_CHANNEL);
debug("Asking for permission");
return FALSE;
}
return TRUE;
}
// ---------------------------------------------------
// Executing of commands
// ---------------------------------------------------
// execute a non-parsed message // this command could be denied here for policy reasons, (if it were implemenetd) // but this time there will be an acknowledgement execute(string name, key id, string message) {
list tokens=llParseString2List (message, [","], []);
if (llGetListLength (tokens)==3) // this is a normal command
{
string cmd_id=llList2String (tokens, 0); // CheckAttach
key target=llList2Key (tokens, 1); // UUID
if (target==llGetOwner ()) // talking to me ?
{
list list_of_commands=llParseString2List (llList2String (tokens, 2), ["|"], []);
integer len=llGetListLength (list_of_commands);
integer i;
string command;
string prefix;
for (i=0; i<len; ++i) // execute every command one by one
{
// a command is a RL command if it starts with '@' or a metacommand if it starts with '!'
command=llList2String (list_of_commands, i);
prefix=llGetSubString (command, 0, 0);
if (prefix==PREFIX_RL_COMMAND) // this is a RL command
{
executeRLVCommand(cmd_id, id, command);
}
else if (prefix==PREFIX_METACOMMAND) // this is a metacommand, aimed at the relay itself
{
executeMetaCommand(cmd_id, id, command);
}
}
}
}
}
// executes a command for the restrained life viewer // with some additinal magic like book keeping executeRLVCommand(string cmd_id, string id, string command) {
// we need to know whether whether is a rule or a simple command
list tokens_command=llParseString2List (command, ["="], []);
string behav=llList2String (tokens_command, 0); // @getattach:skull
string param=llList2String (tokens_command, 1); // 2222
integer ind=llListFindList (lRestrictions, [behav]);
if (param=="n" || param=="add") // add to lRestrictions
{
if (ind<0) lRestrictions+=[behav];
kSource=id; // we know that kSource is either NULL_KEY or id already
}
else if (param=="y" || param=="rem") // remove from lRestrictions
{
if (ind > -1) lRestrictions=llDeleteSubList (lRestrictions, ind, ind);
if (llGetListLength (lRestrictions)==0) kSource=NULL_KEY;
}
workaroundForAtClear(command);
rememberForceSit(command);
sendRLCmd(command); // execute command
ack(cmd_id, id, command, "ok"); // acknowledge
}
// check for @clear // Note: @clear MUST NOT be used because the restrictions will be reapplied on next login // (but we need this check here because "!release|@clear" is a BROKEN attempt to work around // a bug in the first relay implementation. You should refuse to use relay versions < 1013 // instead.) workaroundForAtClear(string command) {
if (command == "@clear")
{
releaseRestrictions();
}
}
// remembers the time and object if this command is a force sit rememberForceSit(string command) {
list tokens_command=llParseString2List (command, ["="], []);
string behav=llList2String (tokens_command, 0); // @sit:<uuid>
string param=llList2String (tokens_command, 1); // force
if (param != "force")
{
return;
}
tokens_command=llParseString2List(behav, [":"], []);
behav=llList2String (tokens_command, 0); // @sit
param=llList2String (tokens_command, 1); // <uuid>
debug("'force'-command:" + behav + "/" + param);
if (behav != "@sit")
{
return;
}
lastForceSitDestination = (key) param;
lastForceSitTime = llGetUnixTime();
debug("remembered force sit");
}
// executes a meta command which is handled by the relay itself executeMetaCommand(string cmd_id, string id, string command) {
if (command==PREFIX_METACOMMAND+"version") // checking relay version
{
ack(cmd_id, id, command, (string)RLVRS_PROTOCOL_VERSION);
}
else if (command==PREFIX_METACOMMAND+"release") // release all the restrictions (end session)
{
releaseRestrictions();
ack(cmd_id, id, command, "ok");
}
}
// lift all the restrictions (called by !release and by turning the relay off) releaseRestrictions () {
kSource=NULL_KEY;
integer i;
integer len=llGetListLength (lRestrictions);
for (i=0; i<len; ++i)
{
sendRLCmd(llList2String (lRestrictions, i)+"=y");
}
lRestrictions = [];
loginPendingForceSit = FALSE;
}
// ---------------------------------------------------
// initialisation and login handling
// ---------------------------------------------------
init() {
nMode=1; kSource=NULL_KEY; lRestrictions=[]; sPendingId=NULL_KEY; sPendingName=""; sPendingMessage=""; llListen (RLVRS_CHANNEL, "", "", ""); llListen (DIALOG_CHANNEL, "", llGetOwner(), ""); llOwnerSay (getModeDescription());
}
// sends the known restrictions (again) to the RL-viewer // (call this functions on login) reinforceKnownRestrictions() {
integer i;
integer len=llGetListLength(lRestrictions);
string restr;
debug("kSource=" + (string) kSource);
for (i=0; i<len; ++i)
{
restr=llList2String(lRestrictions, i);
debug("restr=" + restr);
sendRLCmd(restr+"=n");
if (restr=="@unsit")
{
loginPendingForceSit = TRUE;
}
}
}
// send a ping request and start a timer pingWorldObjectIfUnderRestrictions() {
loginWaitingForPong = FALSE;
if (kSource != NULL_KEY)
{
ack("ping", kSource, "ping", "ping");
timerTickCounter = 0;
llSetTimerEvent(1.0);
loginWaitingForPong = TRUE;
}
}
default {
state_entry()
{
init();
}
on_rez(integer start_param)
{
// relogging, we must refresh the viewer and ping the object if any
// if mode is not OFF, fire all the stored restrictions
if (nMode)
{
reinforceKnownRestrictions();
pingWorldObjectIfUnderRestrictions();
}
// remind the current mode to the user
llOwnerSay(getModeDescription());
}
timer()
{
timerTickCounter++;
debug("timer (" + (string) timerTickCounter + "): waiting for pong: " + (string) loginWaitingForPong + " pendingForceSit: " + (string) loginPendingForceSit);
if (loginWaitingForPong && (timerTickCounter == LOGIN_DELAY_WAIT_FOR_PONG))
{
llWhisper(0, "Lucky Day: " + llKey2Name(llGetOwner()) + " is freed because the device is not available.");
loginWaitingForPong = FALSE;
loginPendingForceSit = FALSE;
releaseRestrictions();
}
if (loginPendingForceSit)
{
integer agentInfo = llGetAgentInfo(llGetOwner());
if (agentInfo & AGENT_SITTING)
{
loginPendingForceSit = FALSE;
debug("is sitting now");
}
else if (timerTickCounter == LOGIN_DELAY_WAIT_FOR_FORCE_SIT)
{
llWhisper(0, "Lucky Day: " + llKey2Name(llGetOwner()) + " is freed because sitting down again was not possible.");
loginPendingForceSit = FALSE;
releaseRestrictions();
}
else
{
sendRLCmd ("@sit:"+(string)lastForceSitDestination+"=force");
}
}
if (!loginPendingForceSit && !loginWaitingForPong)
{
llSetTimerEvent(0.0);
}
}
listen(integer channel, string name, key id, string message)
{
if (channel==RLVRS_CHANNEL)
{
if (!verifyWeAreTarget(message))
{
return;
}
if (nMode== MODE_OFF)
{
debug("deactivated - ignoring commands");
return; // mode is 0 (off) => reject
}
if (!isObjectNear(id)) return;
debug("Got message (active world object " + (string) kSource + "): name=" + name+ "id=" + (string) id + " message=" + message);
if (kSource != NULL_KEY && kSource != id)
{
debug("already used by another object => reject");
return;
}
loginWaitingForPong = FALSE; // whatever the message, it is for me => it satisfies the ping request
if (!isObjectKnow(id))
{
debug("asking for permission because kSource is NULL_KEY");
if (!verifyPermission(id, name, message))
{
return;
}
}
debug("Executing: " + (string) kSource);
execute(name, id, message);
}
else if (channel==DIALOG_CHANNEL)
{
if (id != llGetOwner())
{
return; // only accept dialog responses from the owner
}
if (sPendingId!=NULL_KEY)
{
if (message=="Yes") // pending request authorized => process it
{
execute(sPendingName, sPendingId, sPendingMessage);
}
// clear pending request
sPendingName="";
sPendingId=NULL_KEY;
sPendingMessage="";
}
}
}
touch_start(integer num_detected)
{
// touched by user => cycle through OFF/ON_PERMISSION/ON_ALWAYS modes
key toucher=llDetectedKey(0);
if (toucher==llGetOwner())
{
if (kSource != NULL_KEY)
{
llOwnerSay("Sorry, you cannot change the relay mode while it is locked.");
return;
}
++nMode;
if (nMode>2) nMode=0;
if (nMode==MODE_OFF) releaseRestrictions ();
llOwnerSay (getModeDescription());
}
}
changed(integer change)
{
if (change & CHANGED_OWNER)
{
llResetScript();
}
}
}
</lsl>