Handy's light system - instructions

Designed for builders and content creators, Handy's light system lets you add lights to your products easily without having to write scripts - setup is through simple menus. It's suitable for anything from a simple electric light-bulb to a chandelier, a streetlight or a gas mantle; for convenience, we'll just use "light" to describe the objects here.

One of the prominent features of the light system is an optional and configurable particle aura, or halo, around the light.

Click here for a list of features.

This document describes how to use the light system.

What you get

You should have the following scripts:

Handy's light control*

This is the script that controls the light. You have copy/transfer permission on this script, so you can include it in the products you sell or give away.

Handy's light setup*

This script is the one you use to set up the light, and lets you define such things as the aura texture, its size, how much light it casts, 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 touch trigger*

For more advanced setups, this lets you control which prim you click to switch the light on or off (see this section).

Creating a simple light

Included with the light system is a simple example object to practice with if you wish to.

Adding the scripts

To make a prim light up, drop the Handy's light control and Handy's light setup scripts into the prim's contents. The picture below shows both scripts (note that the version number v1.0 may be different in your copies.)

Prim contents

When the scripts are in place, the prim should have light up and you will see a menu on your screen.

You may notice that the scripts set the prim description to what looks like random characters, but is in fact your setup data. For an explanation, see the sections Prim descriptions and data and Using a notecard to store data.

When both scripts are in place, if all is well, you will get the main menu:

Main menu

The options BRILLIANCE, CAST LIGHT, AURA and SOUND take you to other menus (see below), which is why they are in UPPER CASE (all upper-case options take you to menus).

Reset sets everything back the way it started, so any changes you made are undone. Also, it stops all prims from emitting particles and cast light, in case any have been accidentally left in that state. When the reset has finished, only the prims you specify will generate particles and light.

Finish closes the menu, and asks you if you want to delete the setup script (say "No" for now). Click the prim to get the menu back.

Help tells you the link to these instructions in chat.

On/Off turns the light on and off.

With all the menus, you can always come back if you change your mind later. Nothing is permanent.

The main work is done in these other menus, so let's go through them one by one.

If at any time you find you have no menu at all, just click the prim to get the menu back.

BRILLIANCE menu

"Brilliance" refers to how much (and how) the light appears to glow.

Brilliance menu

There are two sides to this:

  • Bright ("full-bright") means that the prim is fully lit at all times, although this maybe be hard to see around midday. Due to SL restrictions, this is either on or off, and cannot be varied any more than that.
  • Glow is a glowing effect that's used here as a percentage. It can be anything from a very subtle sheen to a harsh brightness.

It's best to experiment with both these values, checking with various sun positions - midday, midnight, sunrise and sunset and other times in-between.

CAST LIGHT menu

Cast light

"Cast light", sometimes called "point light" or "local light", refers to the light that can shine onto nearby objects, water, avatars, and so on.

Cast light menu

The top six buttons increase and decrease the following parameters:

Intensity is how bright the light is.

Radius is how far the light shines - for example, a light with a radius of 3 metres will illuminate objects below 3 metres away, but not any further than that.

Fall-off is how rapidly the light fades as you move away from the object. A light with a fall-off of 0% will illuminate everything within its radius more or less equally, but one with a fall-off of 90%, for example, will only faintly illuminate objects near its radius

Probably the best way to find the right values for those is to play with them until it looks right - the light cast by the light will always show your changes.

See below for the COLOUR option.

The None button will turn off cast light, and the Default button will reset the cast light parameters to their default values. When you're happy with the texture, select < MAIN MENU to go back to the main menu.

CAST LIGHT COLOUR menu

Cast light colour

This menu controls the colour of the light that is shone on other objects, which is independent of the colour of the aura.

Cast light colour menu

Use the appropriate buttons to increase or decrease the (R)ed, (G)reen and (B)lue components of the light.

By default, the values change by 15, but you can select different amounts of change using the Change by 5 and Change by 50 buttons.

See How changing colours works below if you'd like more information on exactly how these colour changes work.

The Reset button changes the colour back to the default. Select the < MAIN MENU option to return the that menu.

If you want a quick and easy way of setting the precise colour you want, the Exact RGB button will give you this dialog:

Exact RGB dialog

In the white box, just type in the RGB values you want, separated by commas (or space, "/" or "." characters) and click Submit.

So, typing "0, 255, 255" (without quotes) will give you a cyan colour, and "204 153 0" will make a mustard colour.

To cancel and return to the menu, click Submit without typing anything.

People with old viewers (1.23 and earlier) will not be able to use this feature for technical reasons.

Select < MAIN MENU to go back to the main menu.

AURA OPTIONS menu

Aura

The "aura" is an optional particle texture that forms a kind of halo around the light.

Cast light colour menu

When you add the light scripts, the aura is on by default. If you cannot see anything, the aura may be buried inside the prim (see the SIZE menu below) or it may be hard to see against the background. It might be helpful to put something dark behind the light so that you can see the aura more clearly.

The options POSITION, TEXTURE, COLOUR, SIZE, WIDTH, COLOUR and ALPHA all give sub-menus that we'll cover next. Aura off removes the aura entirely, giving an Aura on button to restore it.

Note that any changes you make to the aura may take several seconds to show. Also, when you switch the light off, the aura may linger for a little while. This is because of the way the particles are generated by Handy's Light System for maximum softness and smooth blending.

AURA POSITION menu

Aura position

With this menu, you can move the aura up and down (relative to the rotation of the prim) to place it where you like.

Position menu

Use +++ to move the aura up a lot, ++ to move it up a medium amount, and + for a small amount. Likewise, - - -, - - and - make the aura lower.

Note that this might not work as expected if the prim is not vertical - the aura might move in a different direction.

It is not possible to move the aura sideways due to restrictions of the Second Life particle system, nor is it possible to move it downwards below the 0.0m mark.

The Reset button sets the height back to 0.0m. Use the < MAIN MENU button to return to the top-level menu.

AURA TEXTURE menu

Aura texture

The texture of the aura is the image that is used to make the aura itself. Six different textures are included with the light system, and you can also use your own if you wish (although for now, let's use one of the supplied ones).

Aura texture menu

The buttons are a list of the available textures, and "Current texture" tells us which one is currently selected. "Abune 5" is the default texture, but you can select any of the listed textures for your products. Use the NEXT > and < PREV buttons to move through the list of textures.

The "Abune" textures were all specially created for Handy's Tools by Abune Audebarn of Abune Clocks and Lamps. The "Linden" texture is the default SL particle texture.

As with all the menus, the changes you make are immediately visible in the light. This makes it easy to find what you want.

When you're happy with the texture, select < MAIN MENU to go back to the main menu.

AURA SIZE menu

Aura size

This menu lets you make the aura bigger or smaller.

Aura size menu

The current size of the aura is given in metres. The actual size of the aura is smaller than that (for technical reasons), so it's just a guide.

As with the AURA POSITION menu, the +++ , ++ , + ,  - - - , - - and - buttons increase and decrease the size of the aura by different amounts. You can see the aura change size when you do this.

When you're happy with the size of your aura, select < MAIN MENU to return to the main menu.

AURA WIDTH menu

Aura width

This menu lets you make the aura wider or narrower

Aura width menu

Select Wider (+) or Thinner (-) as needed, or Reset to restore the aura to its original proportions. Select < MAIN MENU to go back to the main menu.

AURA COLOUR menu

Aura colour

This menu lets you make adjustments to the colour of the aura texture.

Aura colour menu

The cast light colour menu operates in an identical way to the CAST LIGHT COLOUR menu. See that section for more details on the various options on this menu.

AURA ALPHA menu

Aura alpha

This menu lets you make adjustments to the transparency of the aura texture.

Aura alpha menu

Use the appropriate buttons to increase or decrease alpha (transparency) of the aura.

SOUND menu

This menu lets you select a "switch" sound to be played when the light is switched on or off. Six sounds are provided.

Sound menu

Select one of the sounds from 1 to 6 - a preview of the sound will be played when you select it. Or, select Test to hear the preview again.

The None button turns sounds off, and Volume + and Volume - adjust how loud the sound is.

You can use your own sound if you like - see the section Using your own switch sound below.

Finishing off your light

When you're happy with the light, 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 light, you will need to remove the setup script, partly because it's no-transfer. Even if you're keeping the light 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 light setup from the prim contents by hand.

Using the light

With the setup script removed, operating the light is simple - click to turn on and again to turn off.

However, the owner of the light can also long-click (press and hold down the left mouse button) to bring up this menu:

User menu

The Access button specifies who can control the light. It cycles through three settings: Anyone (any user can control the light), Group (only someone in the same group can control the light), and Owner only (only the owner can control it).

For Group access, someone who is a member of the same group as the object and who is wearing that group's tag is permitted to control the light. The owner, however, can use the light without wearing the tag.

The Day/night button toggles a feature whereby the light turns on automatically at dusk and off again at dawn. This uses the SL estate sun position and, as with all objects that work this way, can not take into account changes made to the sun position in the viewer.

Advanced topics

The information above should be all you need to know to set up simple lights. However, the light 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.

Specifying light prims

If you want to make a linked object that has more than one light, you can set up and control all the lights from one set of scripts in one prim.

To do this, simply edit the prims you want to generate light and add *light* (including the * characters) to the name or description. Upper or lower case is not important.

From then on, the scripts will use those prims to generate light instead of the prim they're in.

You don't need to use the setup script to make this happen.

You can use this feature in any case where you want the light to be from a prim other than the script prim, and there is no limit to how many lights you can run from one script. Remember that the setup script must be in the same prim as the control script.

Of course, the prim(s) to be used for the light must be linked to the prim with the control script.

Specifying a prim for cast light

Cast lights in Second Life are actually something of a precious resource, since viewers can only show a limited number, in some cases as low as two or three. If there are more lights in an area than the viewer can handle, only the nearest lights are shown. This is why someone wearing multiple face-lights, for example, often appears to "suck out all the light" from a club.

To help conserve lights in objects with multiple lights, you can specify a single prim to cast the light for the whole set. In many cases, this is just as attractive as having multiple light sources.

To designate a single prim for cast light, use the tag *castlight* (including the * characters) in the prim name or description. You can combine this freely with other tags, because particles are not used to generate cast light.

Only one prim per linked object can be used in this way.

Pre-rezzing

Probably everyone who's spent any time in Second Life will have seen the way that particles, when first generated, often appear as grey rectangles, due to the particle texture not being rezzed yet.

To prevent this from happening, Handy's Light System continues to generate particles - small, invisible ones - when switched off.

You don't need to do anything to make this happen.

Using your own aura texture

If you have a aura texture you'd rather use instead of one of the textures included in the light system, it's very easy to do this.

Just drop your texture into the prim contents. The script will then use that texture for the light aura. This overrides the selection that you have made in the menu.

To revert to using the built-in textures on the menu, simply delete the texture(s) from the prim contents.

Using your own switch sound

You can also override the sound played when the light is switched on and off, replacing it with your own.

Just drop the sound file into the prim contents and the control script will play that sound whenever the light is switched on or off.

A scriptless light

If you want your light to be on all the time, you can remove the control script ("Handy's light control").

Prim descriptions and data

Normally, all setup data is stored in the prim description in an encoded format. This means you don't need to use notecards to set up your lights.

In fact, you can use this to copy the setup parameters from one prim to another by copy/pasting the description text, although note that this will only work for a prim with the same creator. If the prim you're copying to has a different creator, you'll need to use the setup script.

Using a notecard to store data

The disadvantage of using the description to store data is that you can't then use the description for your own purposes without preventing the light control script from working. This is especially a problem if you need to have the control script in the root prim, because the description is visible to everyone and you might want to use it yourself.

One way to avoid this is to use a non-root prim to store the control script - see the section on specifying light prims.

If that's not possible, you can copy/paste the data from the description into a notecard called Handy's light data(case is important) in the prim's contents. The control script will then read the notecard instead of the description to get its data. Only do this after the setup script has been removed. If you need to use the setup script again, first do the reverse: copy/paste from the notecard back into the description and remove the notecard.

How changing colours works

Two different menus - the Colour menu and the Cast Light Colour menu - give you options that increase or decrease the Red, Green and Blue components of a colour. Although these are simple in operation, and normally work as you'd expect, they have a slightly unusual way of working when you try to go beyond the 0-255 limits.

To put it technically: when one channel is at its upper or lower limit, attempts to change it beyond those limits will incur opposite changes on the complementary channels. Don't worry if that doesn't make sense to you.

In simpler terms, for example: if you try to increase Green beyond 255 (which is the maximum value), the script will push Red and Blue down instead. Likewise, if you try to decrease Blue below 0 (the minimum), Red and Green will increase instead.

This is deliberate behaviour, designed to make it more intuitive. For example, if you start with lime green at 128,180,0, and keep increasing Red, you will continue to make the colour redder until it becomes 255,0,0 (completely red).

Touch trigger script

The Handy's touch trigger script can be used to control which prim the user can click to turn the light on and off. If the script is present in one prim in a linkset, then that prim is the one that should be clicked. However, if the touch trigger script is in the root prim, the user can click any prim in the set. This overrides the way that the control script normally responds to clicks.

Note that if you remove this script, you should reset the control script before it will work normally.

This same script can act as a touch trigger for other Handy's Tools products, such as smoke, fire, etc. Therefore, you can use the trigger to control multiple products with one click.

Integration with other scripts

Handy's Light System makes it easier to incorporate your light into other scripted systems.

This section describes how, and will only make sense to someone who understand LSL (Linden Scripting Language). You can skip this section if you're not a scripter; you won't need any of the information in it anyway.

Link messages

The following pseudo-constants declare values used in the integer portion of linked messages, so another script can switch the light on or off (SEND) and/or detect when the light is switched on or off (RECV):

integer LIGHT_SEND_ON  = -8022400 ; // send to light system to switch light on
integer LIGHT_SEND_OFF = -8022401 ; // send to light system to switch light off
integer LIGHT_RECV_ON  = -8022405 ; // light system sends this when switched on
integer LIGHT_RECV_OFF = -8022406 ; // light system sends this when switched off

Here are a couple of examples to illustrate the use of these link messages:

a. Using the SEND link messages to turn a light on and off depending on whether the owner is within 10m of the object:

state_entry()
{
    llSensorRepeat("", llGetOwner(), AGENT, 10.0, PI, 2.0) ;
}
sensor(integer n)
{
    llMessageLinked(LINK_SET, LIGHT_SEND_ON, "", NULL_KEY) ;
}
no_sensor()
{
    llMessageLinked(LINK_SET, LIGHT_SEND_OFF, "", NULL_KEY) ;
}

b. Processing RECV link messages to tell the owner when the light is turned on or off:

link_message(integer Sender, integer Number, string Str, key ID)
{
    if (Number == LIGHT_RECV_ON)
        llOwnerSay("on") ;
    else if (Number == LIGHT_RECV_OFF)
        llOwnerSay("off") ;
}

Chat messages

This pseudo-constant declares a chat channel which the control script announces (via llRegionSay()) being switched on and off:

integer LIGHT_CHAT = -447390 ;

And this code uses that chat from the light system on that channel, to make a prim invisible when the light is not lit:

state_entry()
{
    llListen(LIGHT_CHAT, "", NULL_KEY, "") ;
}
listen(integer Channel, string Name, key ID, string Message)
{
    if (Message == "on")
        llSetAlpha(1.0, ALL_SIDES) ;
    else if (Message == "off")
        llSetAlpha(0.0, ALL_SIDES) ;
}

Following the object

If your light is moved around when it is lit, for example if it's carried by an avatar or attached to a vehicle, normally the aura will stay with the light.

However, if you adjust the aura upwards with the POSITION menu, this will no longer happen and the light will leave an unrealistic trail of auras as it moves. This is due to the way particles work in Second Life. It's not known why they work like that.

Upgrading scripts

To upgrade the script(s) in an object with a later version, simply drop the new script(s) into the object's contents and the previous version(s) will be automatically deleted. This does not apply to the setup script.

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