Handy's water system - instructions

Designed for builders and content creators, Handy's water system lets you add moving water to your products easily without having to write scripts - setup is through simple menus.

Click here for a list of features.

Handy's water system comprises three parts:

  • Spray: particles that give a cascade of water droplets
  • Flow: smoothly moving water surface textures
  • Sound: the sound of running/splashing water

You can use any combination of those three parts: any one alone, any two in combination or all three.

This document describes how to use the water system.

What you get

You should have the following scripts:

NameDescription
Handy's water control* This is the script that controls the water effects (spray, flow and sound). You have copy/transfer permission on this script, so you can include it in the products you sell or give away.
Handy's water setup (spray)*
Handy's water setup (flow)*
Handy's water setup (sound)*
You can use these scripts to set up the water spray, flow and sound, adjusting any of these to suit your product. These scripts are copy only, and you would remove them when you're ready to sell or give away your product.
Handy's water plugin - [...] Several (optional) example plugins - see the section on supplied plugins for more information on these. You don't need them for the water to work.

Creating your product

The following sections describe how to add water to your creations.

Adding the scripts

Simply drop the Handy's water control and the appropriate setup script(s) (spray, flow, and/or sound) into the prim's contents. If you're adding the scripts to a linked set, note:

  • If you're using the water sounds, these will come from the prim that contains the scripts
  • Spray and Flow can happen in any prim(s), but it's a little bit easier if it's the same prim as the script
  • Scripts in one prim can control Spray and Flow in multiple prims (but not Sound)
  • But if you want Sprays and/or Flows that look different, you can install the scripts into more than one prim

The picture below all three setup scripts and the control script in the prim contents. (Note that the version number v1.0 may be different in your scripts.)

Prim contents

You only need to use the relevant scripts - for example, if you're making a fountain that only has spray, you don't need to use the flow and sound setup scripts, although they won't do any harm being there.

When the scripts are in place, a menu will be displayed on your screen - we'll look at that shortly.

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.

The three setup scripts

Due to the memory restrictions imposed on Second Life scripts, the three parts (Spray, Flow and Sound) have been split into three different scripts, as described above.

However, it's very easy to switch between the three scripts.

If you have two or more of the setup scripts in the object, the main menu for each script will have row of buttons on top like this:

Parts menu line

You can switch between the parts by selecting these options - the current part will be highlighted with [ ] brackets.

If you only include two of the setup scripts, the missing one will have an empty button like this: --. If you only include one, these options serve no purpose and won't appear at all.

Now let's look at the menus for the three parts. Each part has its own section in this document:

  1. Spray menus - particle effects like a water spray
  2. Flow menus - sliding or rotating water surface textures
  3. Sound menus - running/splashing water sounds

3 - Spray menus

When you first select the Spray menus, the water spray is disabled, and you will see this menu:

Spray menu (disabled)

To start the spray (and get access to the options to change it), click Enable. The spray will start, and you will see the full spray menu:

Before we start, let's consider which prim(s) we want to use for the water spray. By default, the scripts will use the one containing the scripts. If that's not what you want, you can use another prim (or prims) in a linkset by changing the description of the prim(s) so they contains the text *waterspray* (including asterisks). See the section Specifying prims below for more information.

Spray menu (enabled)

The buttons [-SPRAY-], -FLOW- and -SOUND- give you the menus for the other scripts (see Switching between the scripts above).

The options SHAPE and DROPS take you to other menus which deal with Spray setup (see below). Upper-case options always take you to menus.

Disable removes the spray and returns you to the previous menu above.

Reset sets all Spray settings (but not Flow or Sound) back to defaults. 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 prim(s) you specify will generate particles.

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

Help tells you the link to these instructions in chat.

With all the menus, you can always come back if you change your mind later. Anything you want can be undone.

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.

3.1 - SHAPE menu (Spray)

The SHAPE menu of -Spray- brings together the options that affect the overall shape of the spray (options that change the spray texture itself are in the DROPS menu).

Shape menu

All the options here - HEIGHT, SIZE, SPREAD, WIND and LIFT - give you separate menus (see below; the options in this paragraph are links). Use < SPRAY if you want to return to the main SPRAY menu.

3.2 - DROPS menu (Spray)

The DROPS menu of -Spray- brings together the options that affect the appearance of the spray droplets (options that change the overall shape are in the SHAPE menu).

DROPS menu

Like the SHAPE menu, all the options here - TEXTURE, COLOUR, ALPHA and DENSITY - give you separate menus (see below; the options in this paragraph are links). Use < SPRAY if you want to return to the main SPRAY menu.

3.3 - HEIGHT menu (Spray)

Height examples

Available in the SHAPE menu of -Spray-, this controls the overall height of the spray.

HEIGHT menu

The +++, ++, + ,  - - - , - - and - buttons increase and decrease the height of the spray by different amounts. You can see the height change when you do this.

Note that this is not a precise measurement, because the actual height of the water depends on several different factors.

The Reset button sets the height back to the default (6.0).

Use the < SHAPE option to return to the SHAPE menu.

3.4 - SIZE menu (Spray)

Size examples

Available in the SHAPE menu of -Spray-, this controls the size of the water textures (particles).

SIZE menu

Use the +++, ++, + ,  - - - , - - and - buttons to make the particles larger and smaller by different amounts.

To avoid distorting the shapes of the water droplets, the particles are always kept square (ie, height and width are equal) to match the textures.

The maximum size of 4m for a particle is a Second Life restriction.

The Reset button sets the size back to the default (0.4m).

Use the < SHAPE option to return to the SHAPE menu.

3.5 - SPREAD menu (Spray)

Spread examples

Available in the SHAPE menu of -Spray-, this controls how wide the spray is - that is, how far the water spreads sideways as it shoots up and falls back down.

SPREAD menu

The ++++, ----, etc buttons increase and decrease the width of the spray by different amounts.

Note that this is not as precise as the numbers indicate. Unfortunately, due to the way SL rounds the numbers it uses for these angles, it might not be possible to get exactly the angle you want.

The Reset button sets the spread back to the default (3.5 degrees).

Use the < SHAPE option to return to the SHAPE menu.

3.6 - WIND menu (Spray)

Wind example

Available in the SHAPE menu of -Spray-, this controls whether the water is blown by the SL wind.

WIND menu

As you may know, the wind in Second Life is variable, so the effect it will have on the spray will vary too. Also, the wind is stronger at higher elevations than at ground level. If you're creating a product that will be used by other people, it's best to bear this in mind.

If you're not sure whether to have the wind effect on or off, it might be best to leave it switched off.

Use the < SHAPE option to return to the SHAPE menu.

3.7 - LIFT menu (Spray)

Lift example

Available in the SHAPE menu of -Spray-, this optionally raises the spray particles.

LIFT menu

This feature is designed for cases where the default (particles coming from the centre of the prim) causes the spray to be buried inside the object.

In such cases, use the +++, ++, + ,  - - - , - - and - buttons to raise and lower the spray by different amounts until it looks right.

Note that it's not possible to lower the spray below the default position. This is a Second Life restriction.

The Reset button sets the lift back to zero.

Use the < SHAPE option to return to the SHAPE menu.

3.8 - TEXTURE menu (Spray)

Texture examples

Available in the DROPS menu of -Spray-, this lets you select the texture of the water droplets.

LIFT menu

Just select the texture names until you see the one you want, or use the << and >> buttons to see the previous or next pages.

Some of the textures have variants labelled L for large, S for small, etc. This is the size of the individual droplets within the textures, not the textures themselves.

Use < DROPS to return to the DROPS menu.

3.9 - COLOUR menu (Spray)

Colour examples

Available in the DROPS menu of -Spray-, this controls the colour(s) of the water spray. Your can have up to two colours if you wish:

The illustration above shows how a spray might look with no colours, with one colour and with two colours.

Note that the water particles will begin with the first colour and then fade through the spectrum to the second colour as they travel - in that illustration, from yellow to orange to red to purple.

When you first select the COLOUR menu, it's in one-colour mode like this:

Colour menu

You can select the RGB option to set the colour (see below), or click the Mode button to switch to two-colour mode like this:

Colour menu

Note that there are now two options to change the colour: RGB 1 and RGB 2 for the start and end colours.

Here, you can click the Mode button to switch back to one-colour mode if you wish.

In either one-colour or two-colour mode, the < DROPS button takes you back to the DROPS menu and the Reset button changes the colour(s) back to white (no colour).

When you select one of the RGB options above, you'll be given this menu:

Colour menu

Use the appropriate buttons to increase or decrease the (R)ed, (G)reen and (B)lue components of the water 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 < COLOUR 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.

3.10 - ALPHA menu (Spray)

Alpha examples

Available in the DROPS menu of -Spray-, this controls the transparency of the water spray.

Alpha menu

Simply use the +++, ---, etc buttons to make the water more transparent (higher numbers) or more opaque (lower numbers).

The Reset button sets the alpha back to the default (40%).

The < DROPS button takes you back to the DROPS menu.

3.11 - DENSITY menu (Spray)

Density examples

Available in the DROPS menu of -Spray-, this affects how many particles are used to generate the spray.

Density menu

You can use the +++, ---, etc buttons to increase or decrease the density by different amounts.

The Reset button sets the density back to the default (40).

The < DROPS button takes you back to the DROPS menu.

4 - Flow menus

When you first select the Flow menus, the flowing water effect is disabled, and you will see this menu:

Flow menu (disabled)

Before we start, let's consider which texture(s) we want to flow. By default, the scripts will use the prim containing the scripts, and all sides of that prim. If that's not what you want, you can use other prim(s) in a linkset by changing the description of those prim(s) so they contains the text *waterflow* (including asterisks). You can also specify which side(s) of the prim(s) to animate; see the section Specifying prims below for more information.

To start the flowing motion (and get access to the options to change it), click Enable. The texture will start to move, and you will see the full texture menu:

Flow menu (enabled)

The buttons -SPRAY-, [-FLOW-] and -SOUND- give you the menus for the other scripts (see Switching between the scripts above).

The options TEXTURE, ALPHA, SIZE, DIRECTION and SPEED take you to other menus which deal with Flow setup; see below for details (buttons in this paragraph are links). Upper-case options always take you to menus.

Disable stops the texture movement and returns you to the previous menu above.

Reset sets everything all Flow settings (but not Spray or Sound) back to their default values. Also, it stops all texture animations, in case any have been accidentally left in that state. When the reset has finished, only the prim sides(s) you specify will be animated.

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

Help tells you the link to these instructions in chat.

With all the menus, you can always come back if you change your mind later. Anything you want can be undone.

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.

4.1 - TEXTURE menu (Flow)

The TEXTURE menu of -Flow- will texture the water surfaces with one of the 30 water textures available in Handy's water system. Each of those 30 textures is provided in 256x256, 512x512 and 1024x1024 variants.

Flow texture menu

Use the << and >> buttons to move back and forwards through the available textures Water 1 to Water 30.

The Resolution button cycles through the three available resolutions (256, 512 and 1024 square).

All this menu does is to apply the texture once, at the time you select the one you want. If you'd rather use your own texture, just set it as normal through the viewer's build menu (or drop the texture onto the object).

The < FLOW button takes you back to the FLOW menu.

4.2 - ALPHA menu (Flow)

The ALPHA menu of -Flow- will set the transparency of the water surfaces.

Flow alpha menu

This menu is purely for convenience, and does the same as setting the transparncy through the viewer's build floater.

The < FLOW button takes you back to the FLOW menu.

4.3 - SIZE menu (Flow)

The SIZE menu of -Flow- allows you to enlarge the texture.

Flow size menu

This doesn't change the texture itself (a 512x512 texture will remain 512x512, for example), but makes the existing texture larger, somewhat like zooming in.

You can enlarge and shrink the texture on the X and Y axes as necessary to suit your product.

The Reset button sets the size back to the default (1, 1).

The < FLOW button takes you back to the FLOW menu.

4.4 - DIRECTION menu (Flow)

The DIRECTION menu of -Flow- lets you specify which direction the water should flow, and whether or not the movement should be a rotation.

Flow direction menu

Click Sliding or Rotating buttons to switch between the types of movement. You can also click the Reverse button to make the water flow in the opposite direction. The currently active button(s) will have ( ) brackets.

The Reset button sets the direction back to the default (Sliding, no Reverse).

The < FLOW button takes you back to the FLOW menu.

If the flow is going sideways - at 90 or 270 degrees to the direction you need - edit the texture of the prim and set the Rotation to 90 or 270 as appopriate. For technical reasons, this cannot be done through the menus.

4.5 - SPEED menu (Flow)

The SPEED menu of -Flow- lets you control the speed of the flowing water.

Flow speed menu

Use the + and - buttons to increase or decrease the speed by the various amounts shown.

Use the + ... and - ... buttons to increase or decrease the speed by the various amounts shown.

The Reset button sets the flow speed back to the default (20).

The < FLOW button takes you back to the FLOW menu.

5 - Sound menus

When you first select the -SOUND- menu, the water sound is disabled, and you will see this menu:

Sound menu (disabled)

To start the sound (and get access to the options to change it), click Enable. A water sound will start playing, and you will see the full SOUND menu:

Sound menu (enabled)

The buttons -SPRAY-, -FLOW- and [-SOUND-] give you the menus for the other scripts (see Switching between the scripts above).

The options CHOOSE and VOLUME take you to other menus which deal with Sound setup (see below; the buttons in this paragraph are links). Upper-case options always take you to menus.

Disable stops the sound and returns you to the previous menu above.

Reset sets all the Sound settings (but not Spray or Flow) back to defaults.

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

Help tells you the link to these instructions in chat.

With all the menus, you can always come back if you change your mind later. Anything you want can be undone.

The main work is done in these other menus, so let's go through those now.

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

5.1 - CHOOSE menu (Sound)

Available from the -SOUND- menu, this lets you select a water sound.

Sound menu

17 unique water sounds are available, from Water 1 to Water 17. Use << and >> to move back and forwards. Click any sound, and it will start playing automatically.

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

5.2 - VOLUME menu (Sound)

Available from the -SOUND- menu, this lets you select how loud the water sound is.

Sound menu 2

The Volume + and Volume - buttons adjust the volume, from 10% to 100%.

Removing the setup scripts

If you're going to sell or give away your product, 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 Spray, Flow or Sound menu, and answer Yes to this prompt:

Would you like to remove setup script(s)? Yes No

Alternatively, you could just delete the setup scripts from the prim contents by hand.

Using the water

With the setup script(s) removed, there is nothing to interact with - the water spray, flow and/or sound just keeps working.

If you'd like the user to have interactive control, look at adding a plugin to your creation.

Advanced topics

The information above should be all you need to know to set up your water. 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 prims

If you want to make a linked object that has sprays and/or flow on more than one prim, you can do all this from one set of scripts.

To do this, you need to put a special sequence of characters into the descriptions of the spray/moving water prims.

  • For a prim that needs water spray, add *waterspray* (including the * characters) to the prim description. Upper or lower case is not important, and you can mix that with other characters in the description.
  • For a prim that needs flowing water, add *waterflow* as above.
  • You can even combine these with something like *waterspray*waterflow*, and mix these tags with any other information you might need

From then on, the scripts will use those prims instead of the prim they're in. There is no practical limit to how many prims can be used in this way.

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

You can even specify which side (face) of a prim are to be used for water flow by adding the side number - eg *waterflow3* to animate face number 3.

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, the Spray system continues to generate particles - very small, invisible ones - when switched off.

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

Using your own texture

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

Just drop your texture into the prim contents, and make sure that the name of the texture contains the sequence of letters spray (upper/lower case doesn't matter). The script will then use that texture for the spray. 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.

You can do this without the setup script.

Using your own sound

You can also override the sound, replacing it with your own.

Just set the water system to use one of the supplied sounds, then drop your sound file into the prim contents - the control script will then play that sound instead.

You can do this without the setup script.

A scriptless object

Particle effects (and looped sounds) don't need a script to keep them going. If you want your Spray, Flow and Sound to be on all the time, and the user doesn't need to turn the sound on and off, you can remove the control script ("Handy's water control").

NOTE: However, if someone makes a copy of such an object in-world (eg by holding shift and dragging the object), the water flow will NOT be copied. This is because of the way Second Life copies (or fails to copy) prim data.

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

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

If that's not possible, you can copy/paste the data from the description into a notecard called Handy's water 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

The COLOUR menu gives you options that increase or decrease the Red, Green and Blue components of a colour. Although this is easy to do, and normally works as you'd expect, it does 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).

Upgrading scripts

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

Plugins

Handy's water system supports plugin scripts, which can communicate with the control script. You can use plugins to add functionality, or to integrate the water with your own scripts.

Supplied plugins

Three plugins are included with Handy's water system. These are full-perm so you can modify them as you wish, but will also work as they are if you wish to include them in your products.

Volume control

This plugin adds a keypad-style volume control menu, which the owner can get by clicking the object. The menu looks like this:

Sound menu (enabled)

This plugin is called Handy's water plugin - volume control, although the name isn't important in practice.

On/off and volume control

This plugin also gives control of the volume (with + and - controls this time), but in addition lets the owner turn the water on and off:

Sound menu (enabled)

This plugin is called Handy's water plugin - on, off, volume, although again the name isn't important.

On when seated

This plugin has no menu. All it does is to turn the water on when someone sits on the object, and off again when nobody's sitting.

As supplied, this plugin is called Handy's water plugin - on when seated, although you can call it what you want.

Writing your own plugins

NOTE: this section will only make sense to someone who knows a little about the LSL scripting language. Otherwise, you can safely ignore it!

If you like, you can easily create your own plugins. It might be a good idea to look at the plugins supplied to get an idea, but essentially they're simple, just link messages sent to the control script, or received from it.

Plugins may communicate with the control script using the following link message integer values:

ValueMnemonicDescription
717000PLUGIN_WATER_SPRAY_SEND_STARTSend to ctrl script to start water spray
717001PLUGIN_WATER_SPRAY_SEND_STOPSend to ctrl script to stop water spray
717010PLUGIN_WATER_FLOW_SEND_STARTSend to ctrl script to start water flow
717011PLUGIN_WATER_FLOW_SEND_STOPSend to ctrl script to stop water flow
717020PLUGIN_WATER_SOUND_SEND_STARTSend to ctrl script to start water sound
717021PLUGIN_WATER_SOUND_SEND_STOPSend to ctrl script to stop water sound
717025PLUGIN_WATER_SOUND_SEND_VOLUMESend to ctrl script to set sound volume
717026PLUGIN_WATER_SOUND_RECV_VOLUMESent by ctrl script to give sound volume
717050PLUGIN_WATER_RECV_BOOTINGSent by ctrl script when bootup starts
717051PLUGIN_WATER_RECV_BOOTEDSent by ctrl script when bootup ends

For example, to stop the spray in an LSL script, you could declare the following variable:

integer PLUGIN_WATER_SPRAY_SEND_STOP = 717001 ;

and then, in the appropriate place in your code, include the command to stop the spray:

llMessageLinked(LINK_SET, PLUGIN_WATER_SPRAY_SEND_STOP, "", NULL_KEY) ;

When that command is issued, the water spray will stop.

For PLUGIN_WATER_SOUND_SEND_VOLUME, the desired volume level from 0 (muted) to 10 (full) should be sent in the string portion of the link message. The same format is sent by the control script for PLUGIN_WATER_SOUND_RECV_VOLUME.

This section is a work in progress. If you'd like to see more details here, or if you have any suggestions or questions about plugins, please contact Handy Low. Likewise, if you have any plugins you'd like to share, please get in touch.

Support

If you have any questions or problems, please see the Contact page for details of how to get help.

Thank you for buying Handy's water system.