LSL Protocol/LockMeister System

LockMeister

The LockMeister System is a keyring of commands used for enhanced functions in bondage toys, its main function is to get the keys needed for particle chains, but as the protocol grow more and more commands are added. This protocol is maintained and designed by Kyrah Abattoir, IM her inworld if you have suggestions.

Return to protocol exchange

Features

• Simple to use
• Flexible
• Fully backward compatible
• Sensorless key grabbing (possible on child prims too) for particle chains (several mooring points)
• Boot/shoes animation overrider controlling (on/off)
• Color propagation in a lockmeister item set

Legacy Functions (LMV1)

Basically, all LockMeister items listen on channel -8888
Its strongly recommended to use only the llWhisper function for sending the commands

When someone sits, click (the interaction model is left to the imagination of the scripter) on a LockMeister compliant item, this one will sequentially send the ping messages to each of the mooring points it needs, for example for a St. Andree Cross we will ping the wrist and ankle cuffs, in our example we see we will have to send the messages lcuff,rcuff,llcuff,rlcuff (which are the ones for these points).
When a LockMeister attachment detects the message corresponding to itself in the channel -8888 it will answer by the same message completed by "ok"

'An item will send the message using this format:
message shape: <avatar key><command> example: "748bb591-0d9d-4907-8287-dc27b8267e24lcuff" (we ping the left wrist cuff attachment of the avatar whose key is positioned before the name of the attachment point, or command)
The concerned attachment will answer:
message shape: <avatar key><command>" ok" example: "748bb591-0d9d-4907-8287-dc27b8267e24lcuff ok" (the concerned object answer on the channel -8888)

In order to draw a chain of particles we need the key of the object. When we used the listener event to get the answer message, the listen event returned us the key of the object that answered in it's key id field. This is the key of the speaking prim, which should be the prim we need to attach the chain to.

The New Extension (LMV2)

The LockMeister protocol version 2 (LMV2) is built over the initial protocol (LMV1) and is designed to allow scripters to create furnitures and attachments without needing a slave script in every anchor prims. Linden Labs declared that they wouldn't be supporting any method for sending chat from a root prim and making it come from a child prim ( no "llLinkSay(integer link_number,integer channel,string message )" for example. ), the LMV2 protocol adds an extra set of commands to get around this problem.

'An item will send the message using this format (same as V1):
message shape: <avatar key><command>
example: "748bb591-0d9d-4907-8287-dc27b8267e24lcuff"
(we ping the left wrist cuff attachment of the avatar whose key is positioned before the name of the attachment point, or command)

The concerned attachment will answer (same as V1):
message shape: <avatar key><command>" ok"
example: "748bb591-0d9d-4907-8287-dc27b8267e24lcuff ok" (the concerned object answer on the channel -8888)

We now have in the listen event 'id' parameter a key, we should start using it as a particle target, if the object is only LMV1 it will be the proper target id, but if the object is LMV2, this will most likely be the root prim of the object. now we can use this id to send the lmv2 messages using llRegionSayTo()

LMV2 MESSAGES SHOULD ALWAYS USE llRegionSayTo() !!

'The item can now send an LMV2 message using this format:
message shape: <avatar key>|LMV2|RequestPoint|<anchor point>
example: "748bb591-0d9d-4907-8287-dc27b8267e24|LMV2|RequestPoint|lcuff"

The concerned attachment will answer (if it is LMV2 compatible):
message shape: <avatar key>|LMV2|ReplyPoint|<anchor point>|<anchor point key>
example: "748bb591-0d9d-4907-8287-dc27b8267e24|LMV2|ReplyPoint|lcuff|636bbccc-0d9d-4907-8287-dc27b8267e24"

If the target object doesn't support LMV2, we won't receive any answer, so it's important to start drawing the particles before the LMV2 reply comes. If the reply DOES arrive, we can grab the new target key and synchronise our particle system.

Complete List of Mooring Points

# name Description 1 rcuff right wrist cuff 2 rbiceps right upperarm cuff 3 lbiceps left upper arm cuff 4 lcuff left wrist cuff 5 lblade left shoulder blade 6 rblade right shoulder blade 7 rnipple right nipple point 8 lnipple left nipple point 9 rfbelt right front of the belt 10 lfbelt left front of the belt 11 rtigh right upper leg cuff 12 ltigh left upper leg cuff 13 rlcuff right ankle cuff 14 llcuff left ankle cuff 15 lbbelt left back of the belt 16 rbbelt right back of the belt 17 pelvis lower front of the pelvis 18 fbelt front of the belt 19 bbelt back of the belt 20 rcollar right of the collar 21 lcollar left of the collar 22 thead top of the head 23 collar front of the collar 24 lbit left corner of mouth/cheek (for pony bits) 25 rbit right corner of mouth/cheek (for pony bits) 26 nose nose 27 bcollar back of the collar 28 back middle of the back 29 lhand left hand (e.g. for mittens) 30 rhand right hand (e.g. for mittens) 31 rbelt right side of the belt 32 lbelt left side of the belt

NOTE: ltigh/rtigh were typos introduced during LM1 so for compatibility reasons we are keeping them as is.

Others

• handle - type "leash handle" , this is useful for leashing to a leash handle.
• tether - type "tether point" , this is useful for leashing to some fixed anchor.

Special Commands

<avatar key>col<vector> - order a color change (used in LockMeister collars to tint the cuffs like the collar) OPTIONAL
ex: "748bb591-0d9d-4907-8287-dc27b8267e24col<1.0,1.0,1.0>" will say to an item able to understand it (color yourself in white)

<avatar key>booton/bootoff = commands sent by collar objects, asking that the shoes animation overrider be started or stopped
ex: "748bb591-0d9d-4907-8287-dc27b8267e24booton" activate the animation overrider
ex: "748bb591-0d9d-4907-8287-dc27b8267e24bootoff" deactivate the animation overrider

Amethyst extension commands (LMV1)

The following commands are not part of the main lockmeister protocol, but additions Amethyst Rosencrans made in her sold and free cuff scripts. They are here to document the extensions so others can utilize them.

<avatar key>target|point1|point2 = Connect a chain from mooring point 1 to mooring point 2 ex: "748bb591-0d9d-4907-8287-dc27b8267e24target|lcuff|rcuff" will create a chain from the left cuff to the right cuff

<avatar key>target|point = Remove a chain from mooring point ex: "748bb591-0d9d-4907-8287-dc27b8267e24target|lcuff" will remove a chain from the left cuff

<avatar key>texture|<texture key> = Change the texture of the chains used by the target command ex: "748bb591-0d9d-4907-8287-dc27b8267e24texture|1ffb37fa-2fc1-dbec-d8ea-0607583a03c6" will change the chain texture

<avatar key>gravity|<downward acceleration float> = Change the rate at which the chain particles move down ex: "748bb591-0d9d-4907-8287-dc27b8267e24gravity|0.5" will change the chain texture to move down half a meter a second

<avatar key>age|<age float> = Change how fast the chain particles move from point 1 to point 2 ex: "748bb591-0d9d-4907-8287-dc27b8267e24age|2.0" will change the chain texture to move the distance in 2 seconds

Cool Products extension commands (LMV1)

The following commands are not part of the main lockmeister protocol, but additions Henri Beauchamp made for use by his Cool Products (such as the Cool Collar). They are here to document the extensions so others can utilize them.

<avatar key>point here = Signals that anchoring point "point" just appeared. ex: "748bb591-0d9d-4907-8287-dc27b8267e24handle here" could be emitted by the on_rez event of a leash handle to signal the collars connected to the owner of the leash handle that they should connect to it instead of staying connected to the center of the avatar.

<avatar key>point gone = Signals that anchoring point "point" just disappeared. ex: "748bb591-0d9d-4907-8287-dc27b8267e24handle gone" could be emitted by the a leash handle when it is detached to signal the collars connected to it that they should unleash.

(unknown) extension commands (LMV1)

<toucher key>post ok = Signals that <toucher key> has touched an object. The toy will then issue an "<object key>handle" command to the object, which will return "<object key>handle ok" to activate the leash.

Note about message sending

• It is recommended to send the LMV1 "ping" messages through llWhisper so only close proximity objects will receive them.
• Now that llRegionSayTo() is available, it is strongly recommended to send "pong" messages through llRegionSayTo(), because of this, it is NOT recommended to have objects rely on "message snooping", because they won't be able to see message replies with llRegionSayTo().
• LMV2 Messages should ALWAYS be send using llRegionSayTo().

Seal Of Approval (optional)

The seal of aproval program is currently discontinued.

Example Scripts

Example Attachment Script

<lsl>//KDC sample LockMeister attachment version 1.1a // //NOTE: This script must be in the root prim of the object for working properly // Please ensure that you named the anchor prim properly too, this is the prim the script will look for // when sending LMV2 replies. // ... // in a general way this script is here as an explanation to the LockMeister System so ... WRITE YOUR OWN CODE!! // //KDC, kyrah design concept

string mooring_point = "lcuff"; //write here the mooring point you want to use

string anchor_name = ""; //write here the name of the child prim that will act as the anchor point, leave blank to use the root.

default {

   attach(key id)
   {
       if(id != NULL_KEY)
           llResetScript();
   }
   state_entry()
   {
       llListen(-8888,"","","");//open the lockmeister channel
   }
   listen(integer channel,string name,key id,string message)
   {
       //This will ensure that we only answer to LockMeister messages when we are attached to an avatar.
       if( !llGetAttached() )
           return;

       if (message == (string)llGetOwner()+ mooring_point)
       {   //This part reply to Lockmeister v1 messages
           //message structure:   llGetOwner()+mooring_point ( without the '+' )

           llWhisper(-8888, (string)llGetOwner()+ mooring_point+" ok");//answering it
           //message structure:   llGetOwner()+mooring_point+" ok" ( without the '+' )
       }

       //we parse the message into a list and recover each element.
       list params = llParseString2List( message, ["|"], [] );

       if( llList2List(params,0,3) == [llGetOwner(), "LMV2", "RequestPoint", mooring_point] )
       {
           //this message is for us, it's claiming to be an LMV2 message, it's a "Request" message, and concerns the mooring_point we specified
           //message structure:   llGetOwner()|LMV2|RequestPoint|anchor_name

           //Now that we are certain that the message concerns us, we look for the prim key to insert in our reply.

           if(anchor_name   == "")
           {
               //If there is no anchor set, we assume root prim.
               llRegionSayTo( id, -8888, llDumpList2String( [llGetOwner(), "LMV2", "ReplyPoint", mooring_point, llGetKey()], "|" ) );
           }
           else
           {
               //Otherwise, we loop through the link set looking for a match.
               integer i;
               for( i = 1; i <= llGetNumberOfPrims(); i++)
               {
                   if( llGetLinkName(i) == anchor_name )
                   {   //If this is our anchor prim, we reply
                       //pattern sent:   llGetOwner()|LMV2|ReplyPoint|anchor_name|anchor_key
                       llRegionSayTo( id, -8888, llDumpList2String( [llGetOwner(), "LMV2", "ReplyPoint", mooring_point, llGetLinkKey(i)], "|" ) );
                       return;
                   }
               }
           }
       }
   }

}</lsl>

Example Furniture Script

<lsl> // Lockmeister V2 Bondage Cross Example. // by Innula Zenovka // // This script shows a typical usage for a Bondage Cross. // The script expects to be placed in the root of a linkset with // four chain points included. // The script scans the linkset and identifies the four chain points // by their description field: // "top left", "top right", "bottom left", "bottom right" (without quotes, specified below) // When someone sits on the cross, the animation found inside of the root prim // will be played and 4 chains corresponding to the chain points specified will be started. // The animation is removed and the chains turned off when the avatar unsits.

integer handle; integer lm_channel = -8888; integer i; integer max; integer n; integer number_of_prims;

key victim; list emitters; list particles;

string LM2_request = "|LMV2|RequestPoint|"; string anim;

string str_top_left ="top left"; //put in the description fields of the emitter prims string str_top_right ="top right"; string str_bottom_left ="bottom left"; string str_bottom_right="bottom right";

string left_wrist = "lcuff"; //lockmeister names string right_wrist = "rcuff"; string right_ankle = "rlcuff"; string left_ankle = "llcuff";

string request;

init(){

   number_of_prims = llGetObjectPrimCount(llGetKey());
   anim = llGetInventoryName(INVENTORY_ANIMATION,0);
   emitters = [str_top_left,left_wrist,str_top_right,right_wrist,str_bottom_left,left_ankle,str_bottom_right,right_ankle];
   //descriptions of our points, and the LM points we want to use as targets for our chains
   max = llGetNumberOfPrims()+1;
   while (max--){//loop through the linkset
       string s = llToLower(llStringTrim((string)llGetLinkPrimitiveParams(max,[PRIM_DESC]),STRING_TRIM));
       n = llListFindList(emitters,[s]); //check if it's an emitter prim
       if(~n){// if it is
           emitters = llListInsertList(emitters,[max],(n+2));
           //insert it into the list after the LM attachment point name
       }
   }
   max = llGetListLength(emitters);//now get rid of the link descriptions from the list, cos we're not using them again
   while (max>-1){
       emitters = llDeleteSubList(emitters,max,max);
       max-=3;
   }
   max = llGetListLength(emitters);
   // llOwnerSay(llList2CSV(emitters));

   particles = [  // start of particle settings
       // Texture Parameters:
       PSYS_SRC_TEXTURE, llGetInventoryKey(llGetInventoryName(INVENTORY_TEXTURE, 0)),//nb -- only works for full perms textures,
       // otherwise hard code the texture's uuid
       PSYS_PART_START_SCALE, <0.1, 0.1, FALSE>, PSYS_PART_END_SCALE, <0.1, 0.1, FALSE>,
       PSYS_PART_START_COLOR, <1.00,1.00,1.00>,    PSYS_PART_END_COLOR, <1.00,1.00,1.00>,
       PSYS_PART_START_ALPHA, (float) 1.0,         PSYS_PART_END_ALPHA, (float) 1.0,

       // Production Parameters:
       PSYS_SRC_BURST_PART_COUNT, (integer)  2,
       PSYS_SRC_BURST_RATE,         (float) 0.01,
       PSYS_PART_MAX_AGE,           (float)  2.0,
       // PSYS_SRC_MAX_AGE,            (float)  0.00,

       // Placement Parameters:
       PSYS_SRC_PATTERN, (integer) 1, // 1=DROP, 2=EXPLODE, 4=ANGLE, 8=CONE,

       // Placement Parameters (for any non-DROP pattern):
       //  PSYS_SRC_BURST_SPEED_MIN, (float) 00.0,   PSYS_SRC_BURST_SPEED_MAX, (float) 00.0,
       //  PSYS_SRC_BURST_RADIUS, (float) 00.0,

       // Placement Parameters (only for ANGLE & CONE patterns):
       //  PSYS_SRC_ANGLE_BEGIN, (float) 0.50 * PI,   PSYS_SRC_ANGLE_END, (float) 0.50 * PI,
       //  PSYS_SRC_OMEGA, <00.00, 00.00, 01.00>,

       // After-Effect & Influence Parameters:
       PSYS_SRC_ACCEL, < 00.00, 00.00, -00.1>,
       //  PSYS_SRC_TARGET_KEY, (key) llGetLinkKey(llGetLinkNum() + 1),

       PSYS_PART_FLAGS, (integer) ( 0                  // Texture Options:
           | PSYS_PART_INTERP_COLOR_MASK
       | PSYS_PART_INTERP_SCALE_MASK
       | PSYS_PART_EMISSIVE_MASK
       | PSYS_PART_FOLLOW_VELOCITY_MASK
       // After-effect & Influence Options:
       //   | PSYS_PART_WIND_MASK
       // | PSYS_PART_BOUNCE_MASK
       // | PSYS_PART_FOLLOW_SRC_MASK
       | PSYS_PART_TARGET_POS_MASK
       // | PSYS_PART_TARGET_LINEAR_MASK
       )
           //end of particle settings
           ];

}

default {

   state_entry()
   {
       init();
       llSitTarget(<-0.19225, 0.00489, -0.42793>, <-0.06705, -0.27499, 0.95891, 0.01923>);
   }

   on_rez(integer start_param)
   {
       init();
   }

   changed(integer change)
   {
       if(change & CHANGED_LINK){
           victim = llAvatarOnSitTarget();
           if(victim){
               llRequestPermissions(victim,PERMISSION_TRIGGER_ANIMATION);
           }
           else{
               llListenRemove(handle);
               llLinkParticleSystem(LINK_SET,[]);
               if(llGetObjectPrimCount(llGetKey())!=number_of_prims){
                   //some relinking has taken place, so read the link numbers again
                   init();
               }
           }
       }
       else if (change & CHANGED_INVENTORY){
           init();
       }
   }

   run_time_permissions(integer permissions)
   {
       if(permissions & PERMISSION_TRIGGER_ANIMATION){
           if(anim){
               llStopAnimation("sit");
               llStartAnimation(anim);
           }
           handle = llListen(lm_channel,"","","");
           n=0;
           while (n<max){//run though the list of emitters, asking for the uuids of the target points
               request = llList2String(emitters,n);
               llRegionSayTo(victim,lm_channel,(string)victim+request);//v1 style LM message
               n+=2;
           }
       }
   }

   listen(integer channel, string name, key id, string message){

       if(llGetSubString(message,0,35)==(string)victim){// it's for us
           if(llGetSubString(message,-2,-1)=="ok"){//it's an old style v1 LM reply
               string s = llGetSubString(message,36,-4);//strip out the victim's key and the " ok" tag
               i = llListFindList(emitters,[s]);

               if(~i){//check that it's a point on the list
                   i+=1;//the emitter number is the next item
                   //draw a chain, using the uuid of the sender as the target
                   llLinkParticleSystem(llList2Integer(emitters,i),particles+[PSYS_SRC_TARGET_KEY,id]);

                   //now send a v2 style LM message, because if the target attachment is using v2 style messages,
                   // then the chains will be better targetted
                   request = (string)victim+LM2_request+s;
                   llRegionSayTo(victim,lm_channel,request);
               }

           }
           else{//v2 style LM reply
               // is it a v2 style LM reply?
               list temp = llParseString2List(message,["|"],[""]);
               if(llList2String(temp,1)=="LMV2" && llList2String(temp,2)=="ReplyPoint"){    //looks like it is
                   temp = llDeleteSubList(temp,0,2);//get rid of the victim's key and the "LMV2", "ReplyPoint" bits
                   i=llListFindList(emitters,llList2List(temp,0,0));//check it's a point on the list
                   if(~i){
                       i+=1;//the emitter number is the next item
                       //draw a chain, this time using the uuid supplied in the message (cast as a key) as the target
                       llLinkParticleSystem(llList2Integer(emitters,i),particles+[PSYS_SRC_TARGET_KEY,(key)llList2String(temp,1)]);
                   }
               }
           }
       }
   }

} </lsl>