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.

Tutorial

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:

Cabinet

Our example cabinet

This cabinet has two separate prims for the two doors, and another pair of prims for the door handles.

Cabinet

Prims coloured for clarity

Getting started

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:

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 option Finish closes 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.

The Help option gives you the link to these instructions.

The option Add door lets 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, click Add door and you will see this dialog:

Add door menu

If you clicked the option by mistake, Cancel 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:

Main menu

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:

Main menu

The Open doors, Close doors , OPTIONS , Edit door and See doors 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 clicking Add door followed by the right-hand door:

Main menu

Again, the door flashes yellow

and now our MAIN MENU shows "Doors: 2", but is otherwise the same:

Main menu

Obviously, if your creation only has one door, drawer, or whatever, you only need to use Add door once.

If you now click the See doors option 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 the Unset door option.

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 the Edit door option on the MAIN MENU.

Editing a door

When you click Edit door, if you have more than one door you'll see this dialog:

Select door to be edited

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:

EDIT DOOR

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 click Set open to record that position:

Setting open position

This door pivots around the edge, but that's not essential.

Note:

  • The door (or drawer, etc) can change position, rotation or both
  • You can spend as much time as you like moving the door into the right position - there is no time-out, and only the final position is recorded
  • You can always go back and set a new open and/or closed position later. Just edit it the way you want, and click the appropriate button
  • Don't move the handles (or other attached prims) at this stage. They'll move themselves automatically when the time comes.

If you started out with the door open, you can set the closed position instead by moving it and clicking Set closed. Either way works.

You can now close the Second Life build floater and test your positions by clicking Open and Close on the EDIT DOOR menu:

Door prim open

Open ...

Door prim closed

... 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.

The << MAIN button 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 select See doors from the MAIN MENU, the door(s) you have set the positions for will show as green instead of yellow:

Green door

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 selecting Edit door from the MAIN MENU (and clicking the door if necessary to select it).

Edit Menu

On the EDIT DOOR menu for the left-hand door, we select the Attach prim option, and we get this dialog:

Attaching a prim

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 the Open and Close buttons:

Door open
Door closed

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.

The See attached button shows the prims attached to the current door/drawer by flashing each one blue. The Detach prim 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:

Attaching a prim

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.

Adding sounds

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 the OPTIONS button of the MAIN MENU to get the OPTIONS menu:

Options

and selecting SOUNDS:

Sounds

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 the NEXT > and < PREV 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:

Sounds

You can control the volume using the Volume + and Volume - 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 the No sound option.

When you're finished with sounds, click the < OPTIONS button to return to the OPTIONS menu.

Together

Another option on the OPTIONS menu is Together. This is a toggle option, which switches between ON and OFF states, by default OFF:

Sounds

and toggling to ON:

Sounds

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.

Finishing off

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 Finish from the Main menu, and answer Yes to this prompt:

Remove setup script? Yes No

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

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):

Control menu

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:

Auto Close menu

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:

Auto Open menu

Greeter plugin

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:

Greeting menu

Security plugin

The Security plugin is for users who wish to restrict who can use the door.

The menu for the plugin looks like this:

Security menu

As in this example, by default security is set to Anyone, and there is no restriction on who can use it.

Setting it to Only you means that only the owner can use the door(s)/drawer(s)/etc.

Selecting Avatar list means that only specified avatars can use the product, and a new option appears:

Security menu

The Edit list ... button takes you to another menu:

Approved avatars

Because there are no avatars in the list, only the Add avatar button is available. Clicking that will bring up this window, where you can type the name of an avatar:

Add avatar to security

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 Submit, and the system confirms that the name as been added:

Avatar added

As you add avatars to the list, the count of entries shows how many there are:

Approved avatars

Of course, the the Delete avatar button deletes an entry from the list.

The List option lists the avatars in Nearby Chat:

List avatars

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:

Notecard in 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:

Security using notecard

Advanced topics

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.

Upgrading scripts

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.

Support

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.