Handy's fire system - instructions

Designed for builders and content creators, Handy's fire system lets you add fire to your products easily without having to write scripts - setup is through simple menus. It's suitable for fireplaces, campfires, braziers, or any other burning objects.

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

Click here for a list of features.

This document describes how to use Handy's fire system.

What you get

You should have the following scripts:

Handy's fire control*

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

Handy's fire setup*

This script is the one you use to set up the fire, 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 fire on or off (see this section).

Creating a fire

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

Adding the scripts

When you're ready for your object to have fire, drop the Handy's fire control and Handy's fire setup scripts into the contents of the prim that will generate the flames. 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 flames coming out of the centre of your prim. Don't worry if it doesn't look right yet,

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, SMOKE, CAST LIGHT, SOUND and TWEAKS 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 fire 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

A common problem with particle 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.

Flame position

With this menu, you can adjust the height the fire appears above the prim, as shown above.

Position menu

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

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

It is not possible to move the fire sideways due to restrictions of the Second Life particle system. Nor is it possible to move it downwards below the 0.0m mark - 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 fire is the image that is used to make the flames. No less than 25 different textures are included with the fire 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.

The 25 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 fire. 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 fire texture.

Flame colour menu

Use the appropriate buttons to increase or decrease the (R)ed, (G)reen and (B)lue components of the colour. Note that most of the supplied 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. However, the texture "Abune 5" is a copy of "Abune 1" which has had all colour removed, to give you greater flexibility for unusual colours.

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 fire bigger or smaller.

Flame size menu

The current size of the fire is given in metres. The actual size of the flame is a little 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 fire and smoke by different amounts. You can see them change size when you do this.

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

SMOKE menu

Smoke

This menu lets you select the texture you'd like to use for the smoke, as well as to change the darkness and density of the smoke - or even turn it off altogether and just have flames.

Smoke menu

The options TEXTURE 1 to TEXTURE 6 give a selection of different textures for the smoke. Smoke offstops the script from generating smoke.

Note that, unlike normal fire scripts, Handy's Fire System uses the same prim for both flames and smoke.

The Darkness + and Darkness - buttons control the greyness of the smoke - 0% (the default) is the natural texture, whereas 100% is almost completely black.

Below them, the Density + and Density - buttons control how much smoke is generated. This is on a scale of 1 to 4, 2 being the default.

The < MAIN MENU option returns to the main menu.

You can also use your own smoke texture if you wish.

See also the section about Handy's Smoke System for more advanced smoke capabilities.

CAST LIGHT menu

Cast light

"Cast light", sometimes called "point light" or "local light", refers to the light that your fire 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 fire 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 fire 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 fire appear to flicker, as if there's a breeze or the fire is fuelled with damp wood.

Cast light flicker menu

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

SOUND menu

This menu controls the sound the fire produces.

Sound menu

Select the sound you like from 1 to 9 (the sound will change when you click each one), and adjust the volume of the sound with the Volume + and Volume - buttons. If you prefer no sound at all, simply reduce the volume to 0%.

Note that it can take several seconds for sounds to load in Second Life.

If you have a sound file of your own that you'd rather use, just drop it into the prim contents and the control script will use that instead.

Select < MAIN MENU to return to the main menu when you're happy with the sound.

TWEAKS menu

The TWEAKS menu brings together four different values you can tweak (change) which affect the appearance of your fire.

Tweaks menu

A brief explanation of each of the tweaks:

Density controls how many flames the script generates. In technical terms, this is the number of particles generated.

Scatter controls the how widely the flame particles are spread out - this is different from SIZE above because the flames themselves don't change size, only the area they appear in.

Speed controls the rate at which the flames travel upward - higher values will cause the flames to shoot up more rapidly.

Linger controls how much time it takes before the flames disappear as they travel upwards.

The Reset all button resets all of the tweaks to their normal values.

You could use 'Reset all' if tweak things until your flames look weird and you don't know how to change them back.

When you select any of these four tweaks, a sub-menu will appear which you can use to change them. This is basically the same menu for each of the tweaks. Here, for example, is the menu you would get if you clicked the Density option:

Density tweak menu

All the tweaks have a value which can go from 1 to 5, and the normal value of each is 3. Use More + and More - to adjust the value, or Reset to set it back to 3, the normal (default) value.

As you change the values, the flames will change accordingly. Some changes may be quite subtle and hard to detect, and others can be quite dramatic, especially in combination.

Finishing off your fire

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

Using the fire

With the setup script removed, operating the fire 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 fire. It cycles through three settings: Anyone (any user can control the fire), Group (only someone in the same group can control the fire), 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 fire. The owner, however, can use it without wearing the tag.

Advanced topics

The information above should be all you need to know to set up simple fires. However, Handy's Fire 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 a different prim

Normally, the fire control script will create flames, smoke and light in the prim where the script resides. However, you may want to use a different prim for various reasons.

To move the fire and smoke to another prim, simply edit that prim change the name - or description- to *flame* (case is not important). From then on, the control script will use that prim to generate flames instead of the one it's in.

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

Remember that the setup script must be in the same prim as the control script; the prim 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.

To prevent this from happening, Handy's Fire System continues to generate smoke and fire particles - invisible ones - when switched off.

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

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 fire 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 flames or, if the texture name contains the word "smoke" (case doesn't matter), the 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.

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

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, so that the description is visible to everyone.

One way to avoid this is to use a non-root prim to store the control script. See the section Using a different prim for more details.

If that's not possible, you can copy/paste the data from the description into a notecard called Handy's fire 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 fire 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, candle, etc. Therefore, you can use the trigger to control multiple products with one click.

Integration with other scripts

Handy's Fire 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 fire on or off (SEND) and/or detect when the fire is switched on or off (RECV):

integer FIRE_SEND_ON  = -8022200 ; // send to switch fire on
integer FIRE_SEND_OFF = -8022201 ; // send to switch fire off
integer FIRE_RECV_ON  = -8022205 ; // sent when switched on
integer FIRE_RECV_OFF = -8022206 ; // sent 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 fire 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, FIRE_SEND_ON, "", NULL_KEY) ;
}
no_sensor()
{
    llMessageLinked(LINK_SET, FIRE_SEND_OFF, "", NULL_KEY) ;
}

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

link_message(integer Sender, integer Number, string Str, key ID)
{
    if (Number == FIRE_RECV_ON)
        llOwnerSay("on") ;
    else if (Number == FIRE_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 FIRE_CHAT = -447391 ;

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

state_entry()
{
    llListen(FIRE_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, it is not possible to position the flame below 0.0m. This is a Second Life restriction.

If this is a problem, it's best to use a separate, invisible prim for the flame, with the name or description containing *flame*, as described in the section on Using a different prim.

Following the object

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

However, if you adjust the flame upwards with the POSITION menu, this will no longer happen and the fire 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.

More advanced smoke

Because Handy's Fire System uses the same prim generate fire and smoke, the options for controlling the appearance of the smoke are somewhat limited. If you prefer more capabilities - or even just more smoke - you could consider purchasing Handy's Smoke & Steam System, which can be used alongside Handy's Fire System to provide the best of both worlds.

Note that the Smoke & Steam System must be installed in a separate prim from the Fire System.

In this case, you may want to stop the Fire System itself from generating smoke - simply turn it off on the SMOKE menu and use the Smoke & Steam System to provide the smoke you need.

The Smoke & Steam system can be synchronised with the Fire System so that the smoke turns on and off with the fire. See the documentation for the Smoke & Steam System for more details.

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