THE "[Black Tulip] Door Controller v2 ~CFG~" NOTECARD FORMAT, IN DETAIL
As we know, the controller "[Black Tulip] Door Controller v2" script is capable of performing quite a number of operations over the prim designated as "doors," and all this functionality is described in the "[Black Tulip] Door Controller v2 ~CFG~" notecard, which is mostly generated by the configuration tool.
However, the configuration tool outputs some generic data at some places that we can later manually change, and indeed we will want to change, in order to activate several special features. For that reason, we're going to study now the "[Black Tulip] Door Controller v2 ~CFG~" notecard format in detail. This study is broken down into three sections, to allow us go from a general perspective of what the script would perform with the build "as a whole," to the details that each separate door prim can control.
GENERAL PARAMETERS TO THE BUILD
This holds true for all the notecard: A line beginning with # is taken as a comment line. Thus, everything written after it will be *ignored*.
There are three general parameters that affect the whole build.
They are written in the notecard with the following format:
parameter | value
We find them at the top section of the notecard. Together with some default values, they read as follows:
autoCloseTime | 30 doorTalksInChat | 0 memoryReport | 1
autoCloseTime
This is a float value (a number with decimals). When the door is opened, it will close automatically after autoCloseTime seconds. If we set it to 0.0, the auto-close function is disabled - when we click a door and it opens, we'll need to click the door again to close it.
doorTalksInChat
Set this to 1 if you want the doors saying that they're open or closed in local chat, like the following:
[05:13] Test Door Model: Kitchen Door is open. [05:13] Test Door Model: Main Door is open. [05:13] Test Door Model: Main Door is closed. [05:13] Test Door Model: Kitchen Door is closed.
If you don't want those messages appearing, then set this to 0. Note that each group of doors uses its own name (e.g. "Main Door" and "Kitchen Door").
memoryReport
If we want to be informed about the free available memory after reading the notecard, set this to 1, and a message like the following will show in chat after reading the "[Black Tulip] Door Controller v2 ~CFG~" configuration notecard:
[05:06] Test Door Model: Free memory for the script: 40948 bytes
But if we don't want this appearing in the chat, then simply set memoryReport to 0.
So the values supplied in the sample "[Black Tulip] Door Controller v2 ~CFG~" notecard from your package:
autoCloseTime | 30 doorTalksInChat | 0 memoryReport | 1
mean:
autoCloseTime | 30.0
Each door will close automatically after 30 seconds if we don't close them manually
doorTalksInChat | 0
The doors *won't* say anything in chat when open or closed (they will be silent)
memoryReport | 1
After the "[Black Tulip] Door Controller v2 ~CFG~" notecard is read, we'll be notified with an owner say message about the free memory for the script
PER-GROUP DOOR PARAMETERS
The format of a GROUP configuration line, understanding here "GROUP = ONE COMPLETE DOOR", is as follows:
GroupSettings | DoorName # AccessMode # SoundOpen # SoundClosed # OpenMode
The keyword "GroupSettings" is written exactly like that. We'll notice this also from the output of the configuration tool. Then a | separates the keyword from its value. This value is actually composed of several parameters that affect to the whole group (door), separated by the # character.
***(VERY) IMPORTANT: The group configuration line should be ALWAYS before ANY of the configuration lines for each specific prim being a part of that door.
***Lag could delay the configuration tool when it is outputting the data, and swap the group configuration line to a wrong place.
***The controller script ALWAYS needs the group configuration line before any prim configuration line. If you see this mishap, change the order of the lines manually. Although the configuration tool introduces a forced delay to minimize this, it's not possible to avoid it always, so please be aware!
The values are expected in a specific order. What the values mean, in their expected order, is:
DoorName
This is the name of the door as a group. This is the prim name we wrote in the first place before starting with the configuration tool, and that we also provided in the "[Black Tulip] Configure Doors v2 ~CFG~" notecard. DO NOT CHANGE IT! The script will be using this value to know exactly which the prims comprise the door.
AccessMode
This is an integer value, which indicates *who* can open this specific door.
The allowed values are 0, 1, 2 and 3, and they mean:
| 0 | Everybody can open the doors |
| 1 | Only the owner can open the doors |
| 2 | Avatars having the same group ACTIVE that the doors belong to, will be able to open the doors |
| 3 | Only avatars listed in the white list will be able to open the doors |
(Obviously, the owner can ALWAYS open the doors)
Although we can decide, per door, whether to use the white list or not, the white list itself is common to each door that wants to use this access mode. We find where to write the white list under the following comment lines in the "[Black Tulip] Door Controller v2 ~CFG~" notecard:
# White list here: Add names of the avatars that will be able to open the door. One name per line. # Do NOT use display names. LEGACY NAMES only - http://wiki.secondlife.com/wiki/Category:LSL_Legacy_Name
The notecard supplies a couple of names as an example:
Auryn Beorn Auryn Resident
Check again the "ACCESS MODE" subsection under the "THE CONFIGURATION TOOL, IN DETAIL" for a detailed explanation about how legacy names are written, if you need a reminder on this.
SoundOpen
This is a sound to play when the door is opened, and can be one of these options:
- A sound UUID
- A sound clip name, coinciding with a sound clip existing in the ROOT PRIM together with the controller script and notecard
- No text, if you don't want a sound playing when the door opens
IMPORTANT: Remember that the sound clips you purchase are subject to Terms of Use, and they normally FORBID distributing them in full permissions state. In this case, DO NOT TYPE AN UUID, because this is the same, technically, as distributing the sound with full permissions. If you're using sound clips you've purchased, then type the name of the sound clip name, and set their permissions for next owner correctly.
Please read this section of the "Permissions (Basics)" class if you don't understand why it's not acceptable to deliver an UUID of a licensed asset.
IMPORTANT: All the sound clips have to be contained in the root prim.
SoundClosed
This is a sound to play when the door is closed, and can be one of these options:
- A sound UUID
- A sound clip name, coinciding with a sound clip existing in the ROOT PRIM together with the controller script and notecard
- No text, if you don't want a sound playing when the door closes
OpenMode
This is an integer value, which indicates what circumstance may trigger the opening of this specific door. The allowed values are 0, 1 and 100, and they mean:
0 The door will open only on touch
1 The door will open only on collision
100 The door will open either by touch or by collision
IMPORTANT! If the door should open by collision, because of a serious limitation of the scripting language, no floor prim should be linked to the build. The floor prims should be linked apart. We've been testing for possible solutions, but none of them was low-lag enough as to feel it was a good idea to incorporate it into this script. So yes: you can use linked doors that open by collision, all of them controlled by one script, but the floors have to be linked apart. It's the best compromise to ensure your build will be the lowest lag possible.
No Sounds: When you don't want sounds being played by the door when it opens/closes, the format of the line is:
No Sound when opening
GroupSettings | DoorName # AccessMode ## SoundClosed # OpenMode
No Sound when closing
GroupSettings | DoorName # AccessMode # SoundOpen ## OpenMode
No Sound when both opening and closing
GroupSettings | DoorName # AccessMode ### OpenMode
INDIVIDUAL PRIM PARAMETERS
Every prim that is part of a door has THREE LINES with information about:
- What to do with this prim when the door has to be open
- What to do with this prim when the door has to be closed
- Is this prim reacting to the trigger (touch/collision/both) that will open the whole door?
DoorName#orderNumber | PARAMETER = value
DoorName is the same DoorName that shows in the corresponding GroupSettings line, so all the prims having this DoorName should have their data always BELOW the GroupSettings line.
orderNumber is assigned by the configuration tool
The whole:
DoorName#orderNumber
is the complete name that the configuration tool uses to rename the prim. DO NOT CHANGE THIS! This information is essential for the script, and thanks to it you do not have to worry about unlinking/relinking a finished build, unlike the previous version of the tool.
PARAMETER may be one of the three following options:
OPEN
CLOSED
REACTS_TO_TRIGGER
OPEN and CLOSED expect exactly the same kind of value. The value showing in the OPEN line refers to the position/rotation/size/slice/sculpt prim values when that prim in the door has to enter into open state, and the value showing in the CLOSED line, refers to the same but in the closed state.
The exact value is written as follows:
position_vector # rotation # size_vector # sculptprimUUID,stitchingType
For example, we may find a line such as:
d1#1 | OPEN = <-2.8125,0.0,0.9958>#<-0.3827,0.0,0.0,0.9239>#<0.5,0.5,0.882>#
And this means:
The prim d1#1 belonging to a door named d1, for the open state, should change to:
Position <-2.8125,0.0,0.9958>
Rotation <-0.3827,0.0,0.0,0.9239>
Size <0.5,0.5,0.882>
Sculpt Not defined
REACTS_TO_TRIGGER may have one of two values:
| 1 | This specific prim in the door will react when touched/collided upon, and so the whole door will open/close |
| 0 | This specific prim in the door WILL NOT REACT when touched/collided upon |
By default, the value is 1. The configuration tool ALWAYS outputs a 1 for this, so when we want to make the prim to NOT react to touch/collision, we have to manually change that 1 to 0, for example (if our door prim is d1#1):
d1#1 | REACTS_TO_TRIGGER = 0
When is this useful? Why have this feature?
When and why can be quickly understood by thinking of a "Murphy bed" (check the link if you don't know what is this.)
A Murphy bed is a bed that can be opened and closed, and when opened, you have pillows, the mattress, a cover...
Now, if you're designing this kind of build, chances are high that you also want to include, at least, a multipose engine such as MLPv2 or AVsitter. If the animation menus are to show when you click on the pillows, or the mattress (for example), you're going to have the following ugly situation happening:
The bed will close when the animation menu is invoked, because you're clicking prims that are part of a "door", and so they activate the open/close functionality.
Well, REACTS_TO_TRIGGER = 0 is set in place to AVOID IT, so you CAN have animation menus on the pillows, mattress... and when those prims are clicked, the bed, as a "door," will not react, staying open and allowing the animation menus to be used in a logical way. You just have to change the default 1 value that the configuration tool outputs, to 0, in all the prims that SHOULD NOT close our Murphy bed, or any other build of similar characteristics.
