Handy's door & drawer system - instructions
Designed for builders and content creators, Handy's door & drawer system lets you add working doors, drawers, etc on to your products easily without having to write scripts - setup is through simple menus. It's suitable for anything where prims move together in an open/closed manner - apart from doors and drawers, you can use it for objects with lids, opening windows, bridges that open and close, and so on..
Click here for a list of features.
This document describes how to use Handy's door & drawer system.
NOTE: Throughout this guide, we'll be talking about 'doors', but the same applies to drawers, lids, windows and so on.
What you get
You should have the following scripts:Handy's door control*
This is the script that controls the door/drawer. You have copy/transfer permission on this script, so you can include it in the products you sell or give away.Handy's door setup*
This script is the one you use to set up the door, and lets you define how the doors open and close, the sounds they make, and so on. The script is copy only, and you would remove the script when you're ready to sell or give away your product.Handy's doors plugin - Auto Close* Handy's doors plugin - Auto Open* Handy's doors plugin - Greeter* Handy's doors plugin - Security*
These scripts are optional plugins that extend the capabilities of Handy's Door & Drawer scripts. See the Plugins section for details.
This guide goes through the process of make the doors, drawers, etc in your objects work.
We will work through an example, which is to make the doors on this cabinet open and close:
Our example cabinet
This cabinet has two separate prims for the two doors, and another pair of prims for the door handles.
Prims coloured for clarity
It's best where possible to use the scripts late on in the process of building your creation, when the doors, drawers, etc are built and linked in to the rest of the object. Our example is assembled and linked as in the picture.
For the door scripts to work, the doors, and any handles, etc must be linked. The root prim must not form any part of a door/drawer.
Drop the Handy's door control and Handy's door setup scripts into the contents of the root prim, and you will see the MAIN MENU appear.
When both scripts are in place, if all is well, you will get the MAIN MENU:
If for any reason you lose the menu, just click the object to get it back again.
Because we haven't told the scripts about any doors yet (so the description reads "Doors: None"), the menu is simple.
The optioncloses the menu, and asks you if you want to delete the setup script (say "No" for now). Click the object if necessary to get the menu back.
Theoption gives you the link to these instructions.
The optionlets us specify a prim as a door.
Remember, we're calling them 'doors' here, and in this cabinet they are doors, but they could be drawers or windows or anything - the principle is the same.
Adding the doors
So, at the MAIN MENU, clickand you will see this dialog:
If you clicked the option by mistake,will take you back to the MAIN MENU. Otherwise, click the prim that you want to be the main prim of the door, drawer or whatever.
In this case, we'll start with the left-hand door, and we'll click the door prim itself, not the handle. This is because it's easier to move the door prim and then have the handle follow it.
Note that when you click the door, it briefly flashes yellow like this:
The door flashes yellow to confirm your selection
Note that when prims flash colours like this, the colours may appear slightly different to you, depending on what textures, etc your object has.
That's all we need to do to tell the scripts that this prim is a door. You'll be taken back to the MAIN MENU, but with more options this time:
The, , , and options only appear once you've specified at least one door. We'll come to these options in a minute.
Our cabinet has two doors, so we'll add the second one now by clickingfollowed by the right-hand door:
Again, the door flashes yellow
and now our MAIN MENU shows "Doors: 2", but is otherwise the same:
Obviously, if your creation only has one door, drawer, or whatever, you only need to useonce.
If you now click theoption on the MAIN MENU, you'll see each of the doors flash yellow in turn. This is a quick visual check you can do to make sure that you've set the doors up the way you want them.
You can specify as many doors as you like.
If you've added a door by mistake, you can undo this by using theoption.
Making a door move
Next, we can tell the script how the door should move when it opens. To do this, we need to use theoption on the MAIN MENU.
Editing a door
When you click, if you have more than one door you'll see this dialog:
and you can just click the door you want to work with. If you only have one door, this part is skipped and you go straight into the next menu:
Because our door is already closed, we only need to show the script how it needs to be positioned when it's open. To do this, simply edit the door (using "Edit linked" on the Second Life build floater) and move the prim into its open position, then clickto record that position:
This door pivots around the edge, but that's not essential.
If you started out with the door open, you can set the closed position instead by moving it and clicking. Either way works.
You can now close the Second Life build floater and test your positions by clickingand on the EDIT DOOR menu:
... and close
If you're not happy with your positions, you can change them. Remember to open or close the door first to select the position you want to change, then edit the position, then select the appropriate "Set" option.
Thebutton on the EDIT DOOR menu takes you back to the MAIN MENU. While you're in the EDIT DOOR menu, the door you selected (or the only door if you only have one) remains the currently selected door, and all options in the EDIT DOOR menu act upon that one door.
You may notice that now, if you selectfrom the MAIN MENU, the door(s) you have set the positions for will show as green instead of yellow:
This lets you know that the door is capable of opening and closing. The colours are designed to be like traffic lights in this way - green means everything is OK.
Of course, our doorknobs are staying in the same place when we open and close the doors, so let's do something about that.
Attaching prims to the door
A major feature of Handy's door & drawer system is that you can attach other prims to your doors, etc. In this case, our doors have knobs which need to move with the doors, but you can attach anything - handles, windows, trimmings - anything that moves the same way as the door itself.
If you just have one prim for each door/drawer, without any handles or other additional prims on the doors/drawers, you can skip this section.
To attach a prim to a door, we need to edit that door first by selectingfrom the MAIN MENU (and clicking the door if necessary to select it).
On the EDIT DOOR menu for the left-hand door, we select theoption, and we get this dialog:
Clicking on the handle as shown is all that's needed to associate that prim with the current door.
Now we can test it with theand buttons:
and we see that the handle moves with the door as it opens and closes.
You can attach as many prims as you like to a door. They don't have to match, either - one door could have five attached prims and another none, for example.
Thebutton shows the prims attached to the current door/drawer by flashing each one blue. The button can be used to reverse the attaching process, so that a prim is no longer attached to the door/drawer.
Then we go back to the MAIN MENU and load the EDIT DOOR menu for the right-hand door, and do the same thing for that handle:
It's as simple as that.
If you wish to move an attached prim - for example, a handle is in the wrong place on the door - just detach it, move it to where you want it and attach it again.
Handy's Door & Drawer system comes with 34 different pairs of opening and closing sounds, for all kinds of doors and drawers. You can also use your own sounds if you wish.
By default, there are no sounds, but you can chose one by using thebutton of the MAIN MENU to get the OPTIONS menu:
This tells us that currently there is no sound; the numbers 1-6 refer to the first six of the 34 open/close pairs of sounds. You can page through the available sounds using theand buttons where appropriate.
To hear a pair of sounds, click on the number, and the doors will open and close so you can hear the sounds you've selected. Selecting a sound gives you more options:
You can control the volume using theand buttons - each time, the doors will open and close so you can hear the results of your change. The current volume is shown as a percentage, below the current sound selection.
If you decide you don't want any sound, select theoption.
When you're finished with sounds, click thebutton to return to the OPTIONS menu.
Another option on the OPTIONS menu is. This is a toggle option, which switches between ON and OFF states, by default OFF:
and toggling to ON:
The difference between them is as follows:
OFF: Each door/drawer is separate, and to open or close one the user must click on the door/drawer itself (including prim(s) attached to that door/drawer).
ON: All doors/drawers work together, and clicking anywhere on the object opens and closes them all.
Which you choose depends on how you expect your object to be used.
When you're happy with the doors/drawers, it's time to get the object ready for normal use.
Removing the setup script
If you're going to sell or give away your creation, you will need to remove the setup script, partly because it's no-transfer. Even if you're keeping it for your own use, it's a good idea to take the setup script out when you're finished working on it.
It won't be possible to change any of the settings without putting the setup script back in. However, if you do decide you want to change something, and add the setup script again to the prim, it will pick up the settings you've already adjusted and you'll be able to carry on from where you left off.
To remove the script, you can select Main menu, and answer Yes to this prompt:from the
Alternatively, you could just delete the script Handy's door setup from the prim contents by hand.
Using the door/drawer object
With the setup script removed, operating the door is simply a case of clicking on them (depending on the Together setting).
However, if there are plugins installed which have menus, the owner of the object can also long-click (press and hold down the left mouse button) to access the plugins menu. See the Plugins section for more information.
Plugins are additional, optional scripts that you can drop in to your objects to extend the capabilities of Handy's Door & Drawer system.
Four plugins are provided, and anyone with scripting knowledge can add their own.
Plugins cannot be used in conjunction with the Setup script, and should be added once the object has been configured with the Door & Drawer system.
To access the menu for plugins that have menus, long-click (click and hold) the object. This will load the CONTROL menu (in this example, the Auto Close plugin is installed):
Only the owner of the object can do this. So if you're selling the object, your customers will be able to set up the plugins themselves. If you wish to use parts of this document in your own documentation for your customers, please feel free to do so.
Additionally, if you sell your objects with modify permssions for next owner, they will be able to add plugins themselves.
Some plugins will work together. For example, if you install both the Security plugin and the Auto Open plugin, the doors will open automatically, but only for people permitted by the Security system.
In this section, we look at each of the provided plugins. If you'd like to write your own plugins, see the section on Creating your own plugins.
Auto Close plugin
If this plugin is installed, the doors (or drawers, etc) will automatically close after a predetermined period, by default 30 seconds.
Selecting the Auto Close menu gives you these options:
From here, you can adjust the time before the doors auto-close.
Auto Open plugin
The Auto Open plugin will open the doors automatically when an avatar approaches, and close them again when nobody is nearby. Because their functionalities overlap, the Auto Open and Auto Close plugins don't work very well together, but Auto Open will work fine with the other current plugins.
There is a menu, which lets the owner set the distance for an avatar to trigger the open/close action:
This plugin simply announces in chat when someone opens the door.
By default, the message is (for example) "Handy Low is at the door", but this can be changed through the plugin menu:
The Security plugin is for users who wish to restrict who can use the door.
The menu for the plugin looks like this:
As in this example, by default security is set to, and there is no restriction on who can use it.
Setting it tomeans that only the owner can use the door(s)/drawer(s)/etc.
Selectingmeans that only specified avatars can use the product, and a new option appears:
Thebutton takes you to another menu:
Because there are no avatars in the list, only thebutton is available. Clicking that will bring up this window, where you can type the name of an avatar:
As the dialog explains, you can only use user and legacy names because display names can easily be faked. So, in this example, Daedric Artifact and daedric.artifact would be fine, but if that avatar had later set their SL name to Dae, for example, that could not be used.
Click, and the system confirms that the name as been added:
As you add avatars to the list, the count of entries shows how many there are:
Of course, the thebutton deletes an entry from the list.
Theoption lists the avatars in Nearby Chat:
As chat text says, you can copy the list of avatars and paste them into a notecard called Allowed, and drop that notecard into the prim contents:
From then on, the Security plugin will use that notecard for its avatar list. The user can edit the notecard directly in the prim contents to make changes to the list. Meanwhile, the script will not show the list-editing options, but will instead show that the notecard is being used:
The information above should be all you need to know to set up simple doors or drawers in an object. However, Handy's Door & Drawer System is capable of much more than that, and in this section we'll look at some more advanced features, as well as look in more detail into some features we've already covered.
Using your own sounds
If you'd like to use your own sounds, you can simply drop them into the object contents and make sure that their names contain "open" and "close" (case is not important) for the opening and closing sound respectively. From then on, the control script will use your sounds instead of whatever is set up. If you want to use the same sound for both opening and closing, just rename it so its name contains both "open" and "close".
Creating your own plugins
If you're comfortable writing fairly simple scripts, you can quite easily write your own plugins. This section tells you all you need to know to do that.
Also, if you need a plugin that might be useful to other customers, which could be added to the collection provided by Handy's Tools, contact Handy Low. Maybe it will be written and provided free of charge to you and anyone else who wants it.
If you don't know anything about scripting, you can just skip this section.
Central to any plugin is Link Messaging, through the LSL command llMessageLinked() [SL Wiki] and the LSL event link_message() [SL Wiki]. Plugins can send link messages to the control script to tell it to do things (open a door, for example), and they can receive link messages when the control script does things, such as when someone clicks on a door.
The type of message is dictated by the value of the integer within the link message, and additional information is carried in the string and key parts.
It's recommended that you use the following variables as necessary, rather than the actual number values. SEND variables denote commands that are sent from the plugin to the controller (you'll use llMessageLinked() for these), and RECV commands are those you'll receive in your link_message() events.
integer PLUGIN_DOOR_SEND_OPEN_ALL = 715001 ; // Open all doors integer PLUGIN_DOOR_SEND_CLOSE_ALL = 715002 ; // Close all doors integer PLUGIN_DOOR_SEND_OPEN_ONE = 715003 ; // Open one door (ID of door is in string) integer PLUGIN_DOOR_SEND_CLOSE_ONE = 715004 ; // Close one door (ID of door is in string) integer PLUGIN_DOOR_RECV_OPEN = 715005 ; // Door has opened (ID in string) integer PLUGIN_DOOR_RECV_CLOSE = 715006 ; // Door has closed (ID in string) integer PLUGIN_DOOR_RECV_TRYING_OPEN = 715007 ; // Someone is trying to open a door (Door ID in string, avatar UUID in key) integer PLUGIN_DOOR_RECV_TRYING_CLOSE = 715008 ; // Someone is trying to open a door (Door ID in string, avatar UUID in key) integer PLUGIN_DOOR_SEND_LOCK = 715010 ; // Lock the doors (so they can only be opened/closed by plugin) integer PLUGIN_DOOR_SEND_UNLOCK = 715011 ; // Unlock the doors integer PLUGIN_DOOR_SEND_TRY_OPEN_ALL = 715014 ; // Try to open all doors integer PLUGIN_DOOR_SEND_TRY_CLOSE_ALL = 715015 ; // Try to close all doors integer PLUGIN_DOOR_SEND_LIST_DOORS = 715020 ; // Request for a list of door IDs integer PLUGIN_DOOR_RECV_LIST_DOORS = 715021 ; // List of door IDs received, comma-separated integer PLUGIN_DOOR_SEND_MENU_BUTTON = 715100 ; // Add a menu button to the plugins control menu integer PLUGIN_DOOR_RECV_MENU_BUTTON = 715101 ; // A menu button on the plugins menu has been clicked (button value in string, user UUID in key) integer PLUGIN_DOOR_SEND_MENU_FINISH = 715102 ; // Sent when menu interaction finished, to return to plugin menu integer PLUGIN_DOOR_BOOTING = 715200 ; // Door controller is booting up integer PLUGIN_DOOR_BOOTED = 715201 ; // Door controller has booted up integer PLUGIN_DOOR_SOUND = 715220 ; // Play door sound (open if string non-null; close if null)
Note that doors each have an ID number, an integer that's typically 1, 2, 3, etc, but may not be consecutive
This part of the documentation is a work in progress. Please contact Handy Low if you need more information here.
External chat channel
When opening or closing, the control script will say the words "open" and "close" (as appropriate) on chat channel 166214. External scripts can use this to detect the doors opening and closing.
How the system stores data
Handy's door & drawer system stores its data - the open and closed positions, sounds selections and so on - in the descriptions of the prims. If these descriptions are overwritten, the doors, etc will no longer work.
To upgrade the control script in an object with a later version, simply drop the new version into the object's contents and the previous version will be automatically deleted. This does not apply to the setup script or to plugins, which must be manually upgraded.
If you have any questions or problems, see the Contact page for details of how to get help.
Thank you for buying Handy's Door & Drawer System.