Handy's smoke & steam system - instructions

Designed for builders and content creators, Handy's smoke & steam system lets you add smoke or steam to your products easily without having to write scripts - setup is through simple menus. It's suitable for chimneys, fires, steam engines, cauldrons, pans - anywhere you might see smoke or steam.

Because smoke and steam are so similar in appearance, they are treated by the scripts as the same thing.

Click here for a list of features.

This document describes how to use Handy's smoke & steam System.

What you get

You should have the following scripts:

Handy's smoke control*

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

Handy's smoke setup*

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

Creating smoke or steam

Included with the 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 smoke, drop the Handy's smoke control and Handy's smoke setup scripts into the contents of the prim that will generate the smoke. 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 smoke (or steam, depending on your imagination) 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 TEXTURE, COLOUR, THICKNESS, SIZE, SPEED, SPREAD, HEIGHT and WIND 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, in case any have been accidentally left in that state. When the reset has finished, only the prims you specify will generate particles.

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 smoke or steam 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.

TEXTURE menu

Smoke texture

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

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

Smoke colour menu

This menu lets you make adjustments to the colour of the smoke/steam texture by selecting one of two sub-menus:

• The RGB sub-menu (see below) lets you change the colour itself

• The DARKNESS sub-menu (see below) lets you change how dark or light the smoke appears.

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

RGB menu

Smoke RGB
Smoke colour menu

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

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 < COLOUR to go back to the COLOUR menu.

DARKNESS menu

Smoke darkness

This menu lets you control how dark or light your smoke or steam appears - anything from pure white steam through light grey woodsmoke to the near-black smoke from burning tyres.

Smoke size menu

Simply use the Darker + and Lighter - buttons to adjust the darkness; Reset sets it back to completely light again.

Select < COLOUR to go back to the COLOUR menu.

THICKNESS menu

Smoke thickness

Use this menu to specify how thick the smoke will be - from the faint wisps or steam from a simmering cooking pot to the dense smoke from a bonfire.

Smoke size menu

Two different values affect the appearance in this way:

Alpha (transparency) - the greater the alpha, the less thick the smoke will appear

Density (number of particles) - the greater the density, the more smoke there will be

Use the Alpha ++ and Alpha - - buttons for large changes to alpha, and Alpha + and Alpha - for smaller changes. Use Density + and Density - to change the density value.

The Reset button sets the alpha and density back to their default values.

SIZE menu

Smoke size

The SIZE menu lets you make the smoke or steam bigger or smaller.

Smoke size menu

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

The +++ , ++ , + ,  - - - , - - and - buttons increase and decrease the size of the smoke/steam particles by different amounts. You can see it change size when you do this.

Reset sets it back to 0.5, which is the default size.

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

SPEED menu

This menu lets you control how fast the smoke travels upwards. In real life, this usually depends on the temperature of the source - steam from a simmering pan will rise more slowly than the smoke from a blazing fire.

Smoke speed menu

Use the Speed + and Speed - buttons to change the speed, or Reset speed to set it back to 10, the default.

The higher the speed, the taller the column of smoke or steam you'll see. Use this option in conjunction with the HEIGHT menu (see below) to get the total height you want.

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

SPREAD menu

Smoke spread

The smoke/steam particles form a kind of V shape in the air, and here you can control the width of that V at the top and bottom. This menu controls:

  • Start (the bottom of the V): How widely-spaced the particles are when they first appear.
  • End (the top of the V): How much the smoke or steam spreads as it travels upwards.

Smoke spread menu

Use the Start +, Start -, End + and End - buttons to change the spread, or any of the Reset buttons to restore the defaults.

When you're happy with the spread of your smoke or steam, select < MAIN MENU to return to the main menu.

HEIGHT menu

Smoke height

This menu lets you adjust the total height of the column of smoke or steam - that is, how high into the sky it goes.

Smoke height menu

The height is expressed as a percentage of the maximum height allowed by the Second Life particle system.

The +++ , ++ , + ,  - - - , - - and - buttons increase and decrease the height by different amounts. You can see it slowly change when you do this, as new particles conform to the new height.

Reset sets it back to 50%, which is the default.

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

WIND menu

Wind

Use this menu to tell the system whether or not the SL wind should affect your smoke or steam.

Smoke wind menu

Use the Wind on and Wind off buttons as necessary.

Due to Second Life limitations, it's not possible to control the amount that wind affects the smoke or steam. It's either on or off, with no intermediate settings.

The strength and direction of the wind depends on the Second Life weather system, and varies with time.

Note that the height of the object affects how much the smoke is blown by wind. The smoke from objects on a sky platform at 1000m, for example, will be blown more strongly than objects at ground level.

Select < MAIN MENU to return to the main menu when you're finished.

Finishing off your smoke / steam

When you're happy with the smoke, 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 smoke setup from the prim contents by hand.

Using the smoke/steam object

With the setup script removed, operating the smoke 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 smoke or steam. It cycles through three settings: Anyone (any user can control the smoke/steam), 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 smoke/steam. 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 smoke or steam. However, Handy's Smoke & Steam 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 smoke prims

Normally, the smoke will be emitted from the prim that contains the control script. However, you can specify one or more prims (in the same linkset) to use instead.

To have smoke come from another prim, simply edit that prim and change the name - or description - to include *smoke* (including asterisks; case is not important). From then on, the control script will use that prim to generate smoke 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, and the prim to be used for the smoke 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 Smoke & Steam System continues to generate particles - invisible ones - when switched off, so that the smoke texture is always in the viewer cache.

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

Using your own smoke texture

If you have a full-perm smoke texture you'd rather use instead of one of the textures included, it's very easy to do this.

Just drop your texture into the prim contents. The control script will then use that texture for the smoke smoke.

Note that the texture has to be full perm for any of this to work, due to Second Life restrictions.

A scriptless candle

If you want the smoke to be emitted all the time, you can remove the control script ("Handy's smoke 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 smoke.

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 smoke 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 Specifying smoke prims for more details.

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

Integration with other scripts

Handy's Smoke System makes it easier to incorporate your smoke 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 smoke on or off (SEND) and/or detect when the smoke is switched on or off (RECV):

integer SMOKE_SEND_ON  = -8022300 ; // send to switch smoke on
integer SMOKE_SEND_OFF = -8022301 ; // send to switch smoke off
integer SMOKE_RECV_ON  = -8022305 ; // sent when switched on
integer SMOKE_RECV_OFF = -8022306 ; // 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 the smoke 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, SMOKE_SEND_ON, "", NULL_KEY) ;
}
no_sensor()
{
    llMessageLinked(LINK_SET, SMOKE_SEND_OFF, "", NULL_KEY) ;
}

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

link_message(integer Sender, integer Number, string Str, key ID)
{
    if (Number == SMOKE_RECV_ON)
        llOwnerSay("on") ;
    else if (Number == SMOKE_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 SMOKE_CHAT = -447392 ;

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

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

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 Smoke & Steam System.