Handy's candle system - instructions

Designed for builders and content creators, Handy's candle system lets you add candle-type particle flames to your products easily without having to write scripts - setup is through simple menus. It's suitable for anything from a simple candle or tea-light to a multiple-candle chandelier or a complex lantern; for convenience, we'll just use "candle" to describe the objects here.

The scripts use particles to create the flame. These are more lifelike than flames made by using animated textures.

Click here for a list of features.

This document describes how to use the candle system.

What you get

You should have the following scripts:

Handy's candle control*

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

Handy's candle setup*

This script is the one you use to set up the candle, and lets you define such things as the flame 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 candle on or off (see this section).

Creating a simple candle

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

Adding the scripts

When you're ready for your candle to have a flame, drop the Handy's candle control and Handy's candle setup scripts into the contents of the prim that will have the flame. The picture below shows both scripts in the prim contents. (Note that the version number v1.0 may be different in your scripts.)

Prim contents

You should now have a candle flame coming out of the centre of your prim. If you cannot see anything, the flame may be buried inside the prim - we will rememdy this in the section on flame positioning below.

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 POSITION, TEXTURE, COLOUR, SIZE, WIDTH, CAST LIGHT, SMOKE and DENSITY all take you to other menus, 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 candle flame 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.

POSITION menu

Flame position

A common problem with candle flames is that they are either too high up, and appear to float in the air, or too low down and seem to be buried inside the prim.

With this menu, you can adjust the height the flame appears above the prim.

Position menu

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

Note that this might not work as expected if the prim is not vertical - the flame might move in a different direction; it is not possible to move the flame in any other direction due to restrictions of the Second Life particle system.

Although the height cannot go below 0.0m, it's possible to switch into a "low setting" if necessary by selecting Set LOW. This is intended for use with sculpted candles s whose centre points have been set high up into the wick. To go back to a normal height range, select Set NORMAL. See the section Flame height issues for more details.

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

TEXTURE menu

Flame texture

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

Flame texture menu

The buttons are a list of the available textures, and "Current texture" tells us which one is currently selected. The first texture - "Abune 1" - 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.

Click here to see the available textures.

The 24 textures were all specially created for Handy's Tools. The "Melino" textures are by Tara Tagore of Melino Style, and the "Abune" textures are by Abune Audebarn of Abune Clocks and Lamps.

As with all the menus, the changes you make are immediately visible in the candle. 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.

COLOUR menu

Flame colour

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

Flame colour menu

Use the appropriate buttons to increase or decrease the (R)ed, (G)reen and (B)lue components of the light. Note that most of the supplied candle flames already have some colour, and you're adding to that colour. It's rather like adding colour to a prim that already has a texture.

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.

SIZE menu

Flame size

The SIZE menu lets you make the flame bigger or smaller.

Flame size menu

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

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

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

WIDTH menu

Flame width

This menu lets you make the flame wider or narrower

Flame width menu

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

CAST LIGHT menu

Cast light

"Cast light", sometimes called "point light" or "local light", refers to the light that your candle 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 candle 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 candle will always show your changes.

See below for the COLOUR and FLICKER options.

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

Cast light colour menu

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

Cast light FLICKER menu

Cast light flicker

Using this menu, you can make the candle appear to flicker, as if there's a breeze or the candle is burning low.

Cast light flicker menu

The Low, Medium and High settings give different amounts of flicker, and None turns the feature off altogether.

SMOKE menu

Smoke

The candle system gives you the option of your candle emitting realistic smoke for a few seconds when it's extinguished.

Smoke menu

There are three choices of smoke texture. By default, there is no smoke, but you can select any of the three textures. When you do, the menu looks like this:

Smoke menu 2

The Test button switches the candle off for a few seconds so you can see the smoke you have selected.

Use Smoke off if you don't want smoke.

If you'd like to get rid of the grey rectangles you sometimes see when smoke and flame textures are still rezzing, see the section on Pre-rezzing below.

The smoke textures were specially created for Handy's Tools by Tara Tagore of Melino Style. You can also use your own texture if you wish

DENSITY menu

Density

You can adjust how solid the candle flame appears.

Density menu

Select Low, Medium or High to get the appearance you want. The default is Medium.

Finishing off your candle

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

Using the candle

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

However, the owner of the object 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 candle. It cycles through three settings: Anyone (any user can control the candle), Group (only someone in the same group can control the candle), 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 candle. The owner, however, can use the candle without wearing the tag.

The Day/night button toggles a feature whereby the candle 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 candles, lanterns, etc. However, the candle 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 flame prims

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

To do this, simply edit the prims you want to generate flames and add *candle* (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 flames 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 flame to be from a prim other than the script prim, and there is no limit to how many candles 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 flame must be linked to the prim with the control script.

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.

In the case of your candles, people may see this happening when the candle is first lit and the flame texture is still loading on their viewer. Also, if you have smoke enabled, they may see an unrezzed smoke texture when the candle is turned off.

The candle system gives you the option of preventing this from happening by pre-rezzing the flame and (if applicable) smoke textures.

It does this by using a prim of your choosing as a pre-rezzer; that prim will invisibly force the viewers to keep the textures downloaded.

Because this uses the particle system, the pre-rezzer prim cannot be used for any other particles, including the candle flame.

To use a prim in your object as a pre-rezzer, just add *prerez* to the name or description (case is not important).

As with *candle*-type prims, the pre-rezzer prim must be linked, and you don't need the setup script.

You only need one pre-rezzer prim per object, regardless of how many candles it has.

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 candles, 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 as a light prim, use the tag *light* 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.

Using your own flame and smoke textures

If you have a flame or smoke texture you'd rather use instead of one of the textures included in the candle 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 candle flame or, if the texture name contains the word "smoke" (case doesn't matter), the candle smoke. This overrides the selection that you have made in the menu.

It's possible to have your own flame and your own smoke textures in this way.

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

A scriptless candle

If you want your candle to be on all the time, and you don't want to use the flicker feature, you can remove the control script ("Handy's candle 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 candles.

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

If that's not possible, you can copy/paste the data from the description into a notecard called Handy's candle 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 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 candle 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 Candle System makes it easier to incorporate your candle flames 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 candle on or off (SEND) and/or detect when the candle is switched on or off (RECV):

integer CANDLE_SEND_ON  = -8022100 ; // send to candle system to switch candle on
integer CANDLE_SEND_OFF = -8022101 ; // send to candle system to switch candle off
integer CANDLE_RECV_ON  = -8022105 ; // candle system sends this when switched on
integer CANDLE_RECV_OFF = -8022106 ; // candle 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 candle 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, CANDLE_SEND_ON, "", NULL_KEY) ;
}
no_sensor()
{
    llMessageLinked(LINK_SET, CANDLE_SEND_OFF, "", NULL_KEY) ;
}

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

link_message(integer Sender, integer Number, string Str, key ID)
{
    if (Number == CANDLE_RECV_ON)
        llOwnerSay("on") ;
    else if (Number == CANDLE_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 CANDLE_CHAT = -447390 ;

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

state_entry()
{
    llListen(CANDLE_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) ;
}

Flame height issues

As mentioned in the section on the POSITION menu, some sculpted candles have their centre points offset high up into the wick part of the candle. In order to accomodate sculpts like this, there is a "low setting" feature, described in that section. This uses an alternative set of flame textures, identical to the normal ones but moved downwards to compensate for the extra height.

Because of this, and the way in which particles are configured in Handy's candle system, the flame may not be quite so lifelike in the "low setting", so it's probably best to use the "normal setting" where possible. You be the judge, however, and the difference in appearance is only slight.

It's Handy's opinion that setting the centre point of sculpts so high creates more problems than it solves, because it's easy for a script to move a flame upwards, higher on the Z axis, but it's not possible to move it in the other direction. But then again, Handy doesn't make sculpts ...

Following the object

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

However, if you adjust the flame upwards with the POSITION menu, this will no longer happen and the candle will leave an unrealistic trail of flames 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 Candle System.