Script: Bathtub Controller

[Black Tulip] Bathtub Controller (Script for Designers)

(c) 2014 Auryn Beorn

Bathtub Controller script in Marketplace.

Thank you for having considered this script to enhance the quality of your products. Please read the following instructions carefully, especially the ones explaining which permissions to apply to the scripts for the next owner. Failure to complete this task INVALIDATES the license governing your use of this set of scripts. Should you have problems, please fill the scripts assistance form, explaining what you did and what happened, and I'll get back to you.

IMPORTANT!
The script contains a check to prevent accidental give-aways. If you haven't set permissions correctly in your inventory, then the script will self delete when you try to use it. The best way to ensure you set permissions correctly is by doing it NOW in your inventory.

FEATURES
SET UP
THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT
TROUBLESHOOTING

FEATURES

Define up to three particle effects for your bathtub (they may be steam, bubbles, falling water...)
Assign prims to each effect (for example, you may have two prims emitting bubbles - a jacuzzi)
Start/Stop those effects independently
Define up to two animated water groups (they may be the water in the tub, falling water from a faucet...)
Show/hide those animated water groups
Define a FAUCET (particles OR animated water):
- When ON, it will play an "open faucet sound" (if defined) and start the effect
- When OFF, it will play a "close faucet sound" (if defined) and stop the effect
Allow to select one from up to nine sounds to play as loop sound (different water/bubbles/etc sound effects)
Adjust the sound volume from the menu
Menu timeout to reduce lag - no open listeners after timeout (0.001 ms script time when idle)
Final user can change access to owner only/everybody/group
Menu can be integrated into tools such as MLPv2, AVsitter... (AVsitter version 2 works too!)
You can add up to THREE buttons to interact with (call) other scripts

SET UP: WHAT SCRIPT TO USE?

There are two scripts contained in your folder:

[Black Tulip] Bathtub Controller
[Black Tulip] Bathtub Controller [MODULE]

We need to use ONLY ONE of them in a given product.

Which one? How to choose?

The [MODULE] version, as explained in the THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT section, will allow you to use this script integrated with other scripts that allow sending linked messages, such as the Multi Love Pose (MLP) or AVSitter for multiavatar, multianimation devices.

So, depending on what we need, we'll use the following script as main one:

Normal use - We want the menu to show when the object is clicked:
[Black Tulip] Bathtub Controller

The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] Bathtub Controller [MODULE]

Once we've chosen the right main script, we have to set some descriptions in the primitives of the object, following the instructions below, and modify the parameters in the configuration notecard.

This configuration notecard is named "[Black Tulip] Bathtub Controller ~CFG~"
Embedded in the documentation notecard, you have a copy. Keep it in a safe place, should you need a fresh copy at any time.

SETUP: CHANGE PERMISSIONS FOR NEXT OWNER

Check the following section on this page, knowing that each [Black Tulip] ASSET refers to the following scripts:

[Black Tulip] Bathtub Controller
[Black Tulip] Bathtub Controller [MODULE]

SETUP: EXAMINING THE SAMPLE OBJECT

With this script, you may control the following:

Define up to three particle effects for your bathtub (they may be steam, bubbles, falling water...)
Assign prims to each effect (for example, you may have two prims emitting bubbles - a jacuzzi)
Start/Stop those effects independently
Define up to two animated water groups (they may be the water in the tub, falling water from a faucet...)
Show/hide those animated water groups
Define a FAUCET (particles OR animated water):
- When ON, it will play an "open faucet sound" (if defined) and start the effect
- When OFF, it will play a "close faucet sound" (if defined) and stop the effect
Allow to select one from up to nine sounds to play as loop sound (different water/bubbles/etc sound effects)
Adjust the sound volume from the menu
Add up to THREE buttons to interact with (call) other scripts

We'll understand better what this means by examining the [Black Tulip] Bathtub - SAMPLE OBJECT object. Rez it, and let's follow this explanation.

Before anything, right click the object to edit, then click the "Content" tab. When we do this, we're inspecting the contents of the ROOT PRIM. You should see:

The "[Black Tulip] Bathtub Controller" script
The "[Black Tulip] Bathtub Controller ~CFG~" configuration notecard
Five soundclips
Three textures (for particle effects)

What does this mean?
That the script, the configuration notecard, textures for particle effects and soundclips, if any, have to be dropped into the ROOT PRIM. This is the default when we simply right click an object, then select "Edit" from the menu.

Having this clear, now let's examine the sample object in detail. It consists of seven linked prims: A (mesh) bathtub and six regular prims (five boxes, one cylinder). Right click to edit, click "Edit linked", and now:

Inspect the mesh bathtub prim: There's a water surface that by default renders transparent (empty bathtub)
The water surface, which is one face of the mesh object, will have an animated texture on it, and it will also emit particles.
Inspect now the description of this prim. It says:

Bath Water;3;4;4;9;3;0.3#Steam

Inspect now all of the regular prims and their descriptions. They say:

Bubbles
Steam
Bubbles
Steam
Bubbles
Faucet;19;1;1;0.1;-1;0.8#Running Water

We may have up to three particle effects.
This does not mean "up to three particle emitters".

Suppose you have a bubbles effect, for a jacuzzi. Now suppose that you need those bubbles to be emitted from four different prims. The script allows you to do that. The effect is the same: bubbles. And then, one or several prims may have it assigned.

It happens the same with the animated texture effects. You may have a big tub with three separate sections, all of them having a same animated water effect in their prims. You may have that same effect in the three prims.

These effects have a name that YOU decide. This name will show in the menu. WHERE do you assign this name? In the configuration notecard. Then you also use the name in the prims. The notecard part is explained in the THE CONFIGURATION NOTECARD section below.

It may sound a bit confusing at this point. Worry not. Let's examine it with one of the effects, to realize that indeed it's very easy to do this.

Open up the [Black Tulip] Bathtub Controller ~CFG~ configuration notecard. Look for the first settings line, which reads this way:

p1Name = Steam

This means:

We're going to define particles effect #1
We're giving that effect the name Steam
Steam will show as a button in the bathtub menu
When activated, it will start a particles effect in ALL PRIMS having Steam as a part of the description
When deactivated, the particles in all prims having Steam as a part of the description, will stop
The properties defining this particles effect are ALL the particle properties that begin by p1 in the configuration notecard

Instead of having a predefined name, that may or may not suit our requirements, the script allows us to give the name we prefer, to show in the menu.

IMPORTANT: This name should never be above 24 characters. This is a scripting limitation. Keep the name short.

SO: Prims that show an effect (animated texture/particles), have a special text in their description. We decide this name in the configuration notecard, then USE IT, exactly as written, in the description of the prims.

You may have several prims for the same effect. You are only limited by the amount of free memory of the script. Check this value after the configuration notecard has been loaded, which shows a message like:

[08:25] [Black Tulip] Bathtub - SAMPLE OBJECT:
[Bathtub Controller v1] Reading notecard: done.
Available Memory: 13102 bytes.

SETUP: FORMAT OF THE DESCRIPTIONS

To tell the script which of the linked primitives are relevant (particles emitters, animated textures), we have to write specific words (CASE SENSITIVE) in the DESCRIPTION of each primitive (DESCRIPTION - not the name, don't confuse them!)

The format of the descriptions is as follows:

parameter

or

parameter1#parameter2

It doesn't matter the order the parameters are written, as long as a # character separates them.

Let's list again the descriptions in the prims of the sample object:

Bath Water;3;4;4;9;3;0.3#Steam
Bubbles
Steam
Bubbles
Steam
Bubbles
Faucet;19;1;1;0.1;-1;0.8#Running Water

There are two prims where the # character shows:

Bath Water;3;4;4;9;3;0.3#Steam
Faucet;19;1;1;0.1;-1;0.8#Running Water

That means, each one of those prims runs TWO effects.

For example, the prim with the following description:

Bath Water;3;4;4;9;3;0.3#Steam

is running an effect called Steam (we'll have this word in the configuration notecard), and it's also running an effect called Bath Water. However, this Bath Water effect seems... complicated. There are ; characters and some numbers. What does this mean? This means that the effect is an ANIMATED TEXTURE. Animated textures need some information for the script, and we give this information in the description of the prim, according to the rules that are explained in the next subsection.

We can see now, that the prim with the following description:

Faucet;19;1;1;0.1;-1;0.8#Running Water

is running an effect called Running Water (that name will show up in the configuration notecard too) and an effect called Faucet. We see again the ; character and numbers, so yes, that Faucet effect is also an animated texture.

Does it matter if we write first Running Water, then all that's related to the animated texture? It matters not. Write them in the order that you prefer. And that would be it.

Set the DESCRIPTIONS according to these simple rules, drop the main script and the configuration notecard in your linked object, and your bathtub/shower/related is ready to go!

SETUP: FORMAT OF THE DESCRIPTIONS - ANIMATED TEXTURES

Animated water in SL by using a texture that we "animate" is done one of the two possible ways:

A texture containing different "frames" of the water animation (we call this "cell animation" - for example, rippling waves)
A texture designed to slide (for example, water falling on a cascade/faucet/etc.)

Whenever we want an animated texture, we have to tell the script:

The type of texture animation
The speed (low numbers for a slow animation, high for a faster animation)
In which face the animation should play (or if it should play in all the faces at once)

Apart from this, when we want a cell animation, the script needs to know how many vertical frames (we call this "x") and how many horizontal frames (we call this "y") the texture contains.

To avoid entering into technical details that may confuse at this point, let's just see the description format when we want animated textures as flames, and then a couple of very common examples that, most likely, will be the ones you will use :-)

General format:

EFFECT_NAME;code_for_animation_type;x;y;speed;face;transparency

EFFECT_NAME
This is the "code word" for the script that we've associated in the configuration notecard (next section). Write it as is. Case sensitive!

code_for_animation_type
If you use a cell animation: 3
If you use a slide animation: 19

x
If you use a cell animation: you type here how many VERTICAL frames the animation has
If you use a slide animation: you type here the number 0

y
If you use a cell animation: you type here how many HORIZONTAL frames the animation has
If you use a slide animation: you type here the number 0

speed
Here you type the frames per second to show (if cell animation), or the speed the animation will slide

face

-1            The animation will be applied to ALL THE FACES of the prim
face_number   The animation will be applied to the face face_number of the prim

transparency
Here you type a number from 0 to 1, to specify how transparent the animated texture is, when the animated water should be visible. 0 is transparent and 1 is opaque.

SETUP: FORMAT OF THE DESCRIPTIONS - ANIMATED TEXTURES: EXAMPLES

Bath Water;3;4;4;9;3;0.3

Bath Water is the effect name, specified in the notecard
This is a cell animation (code 3) having x = 4 vertical frames, y = 4 horizontal frames
The speed is 9 frames per second
It will show in face 3 of the prim
Transparency is set to 0.3: This is quite transparent

Faucet;19;1;1;0.1;-1;0.8

Faucet is the effect name, specified in the notecard
This is a slide animation (code 19), so in both x and y we type the number 0
The speed is 0.1
It will show in face -1, which is the code for ALL THE FACES of the prim
Transparency is set to 0.8: This is almost opaque

It is very important to indicate the face!
Nowadays, it's very likely that we will use a multi-face mesh, and we want to animate only one face in that case, not the whole mesh! :-)

(Why just one or all faces? This is a scripting limitation. The animated texture can work only in all faces at once, or in just one of them. If you hear otherwise than one-or-all at once, it's true that there's a trick, but it's not a reliable one, and may get "fixed" by LL at any time!)

SETUP: THE CONFIGURATION NOTECARD

The configuration notecard is named [Black Tulip] Bathtub Controller ~CFG~, and it allows us to:

Write comment lines, for our own clarifications. Comment lines always begin with a # character.
Define the name of the up to three particles effects used. Those names should be used as part of the prim descriptions.
Define the name of the up to two animated water effects used. Those names should be used as part of the prim descriptions.
Define what sounds are available for loop sound choices (up to nine)
Define the special FAUCET part of the bathtub/shower/etc.
Define which extra buttons we want to add to the menu, to call other scripts from them, having a maximum of 3 buttons.

With the exception of comment lines, all of the other lines have the structure:

parameter = value

The accepted parameter keywords are:

p1Name	In here, we specify the name of the particles effect #1 This is how the name will show as a menu button option This is also the part of the description the script expects to find for the prims that should emit particles for this effect When the effect is active, the defined particles effect shows in all the prims associated to it When the effect is inactive, the particles effect stops in all the prims associated to it
p2Name	Same than for p1Name, but for particles effect #2
p3Name	Same than for p1Name, but for particles effect #3
w1Name	In here, we specify the name of the animated water effect #1 This is how the name will show as a menu button option This is also the part of the description the script expects to find for the prims that should have animated textures When the effect is active, the animated texture shows with the transparency amount indicated in the description When the effect is inactive, the animated texture is not visible
w2Name	Same than for w1Name, but for animated texture #2
Faucet	In here, we define some specifics for what we'll understand a FAUCET is
sound	In here, we specify the name of a soundclip that will be offered as a loopsound to be played We may add up to nine sound lines, each one specifying a different soundclip
button	In here, we specify what other scripts will be called from a menu option We may add up to three button lines, for three different actions

Then there's the whole section related to defining the particles effects. Refer to the FILLING THE PARTICLES SECTION and the EXTRA NOTES ABOUT FILLING THE PARTICLES SECTION sections of the documentation to learn about. The provided configuration notecard contains three effects that may work fairly enough to you. At most, you may only need to change the texture for your own.

p1Name, p2Name, p3Name, w1Name and w2Name are immediate: We only need to write a name like the Faucet, Bath Water, Steam, etc. names in the included configuration notecard. We DECIDE those names, being subject only to a few rules, given the way they're going to be used by the script:

We have to make sure those names ARE NOT LONGER than 24 characters
Make sure that they DO NOT contain the | character

The rest of the accepted values need a bit more of explanation. Let's see that now.

sound = MenuLabel | SoundclipInObject

If we specify a sound clip name after sound = , this sound will be played as a loop sound when the SL light point turns on. The sound clip has to exist in the object, otherwise, no sound will be played.

Faucet = type:group | soundclipNameOpen | soundclipNameClosed

A faucet is a special element. It has to be one of the particle groups, or one of the animated texture groups.

When we activate a faucet:

The sound soundclipNameOpen (which HAS TO EXIST in the prim with the script) is played
The associated effect starts (particles/animated texture)
If there was a loop sound, then it's turned on

When we turn off a faucet:

The sound soundclipNameClosed (which HAS TO EXIST in the prim with the script ) is played
The associated effect STOPS (particles - if animated texture, this is hidden)
If there was a loop sound, it's turned off

type:group indicate which effect exactly to use:

type is 0
The effect is the animated texture
group is 1: The effect used is w1Name
group is 2: The effect used is w2Name

type is 1
The effect is particles
group is 1: The effect used is p1Name
group is 2: The effect used is p2Name
group is 3: The effect used is p3Name

NOTE in the sample object provided that we CAN use the word Faucet for animated texture/particle effect. There's no confusion because in that case, we type Faucet AFTER p1Name =, etc., while Faucet = tells the script "and now we define a faucet". This way, your menu can indeed show the word Faucet, which may be very clear for the final user.

button = button_label|link_msg_number|link_prim|text_to_send

This one is a little more complicated, and it is only required if you plan to add extra buttons that call other scripts. Skip this section if you are not doing this for now.

In order to call, execute or launch another script from our script (bathtub controller, in this case), we have to use a communication mechanism called linked messages. This is a mechanism that allows scripts to send messages to other scripts in the same linked object, and to listen to possible messages coming from other scripts in the same linked object.

When we use a button line, it means that it will add a button on the menu. This button menu, upon click, will SEND a message to ANOTHER SCRIPT that could be in ANY of the prims of our linked object. That another script should be listening, and will expect to know from us:

A code number that should be specified in the script documentation. That is link_msg_number in the notecard line.
A message. That is text_to_send in the notecard line.
A UUID. The lamps controller script sends the UUID of the avatar having clicked the menu.

Apart from this, the script needs a couple more data items to know about:

What text will show on the menu button?
That is button_label in the notecard line.
IMPORTANT: It should not have more than 24 characters.

To what primitive this message is being sent.
That is link_prim in the notecard line.

Unless your application has very specific requirements, this link_prim code will be one of the following, meaning:

1	This will send the message to the root prim IF our object consists of more than one prim linked (Or there's an avatar sitting on a single-prim item)
-1	This will send the message to all prims in the linked object
-2	This will send the message to all prims BUT the one containing the SENDER (lamps controller) script
-3	This will send the message to all child prims (that is, all prims BUT the root prim)
-4	This will send the message to the prim where the SENDER (lamps controller) script is in (-4 could be seen as the opposite code of -2)

Please check the documentation of the other scripts you wish to send linked messages from this one, to make sure of how exactly you should write the line. The lines explained above are the generic ideas valid for every script accepting linked messages, but this documentation cannot replace any other script's documentation for their own interface. Check with the creator of the other script how this should be done.

SETUP: THE CONFIGURATION NOTECARD - EXTRA NOTES ABOUT FILLING THE PARTICLES SECTION

A default steam effect, a default bubbles effect and a default running down water effect are provided in the sample configuration notecard included in the sample object; you can use those effects as a reference to tweak and get your own effects. (You will also need your own textures.)

If the notecard says:

p1Name = Steam

that means that all the particle parameters named p1* (meaning "parameters whose name start by p1") will define the Steam effect. Same for p2Name and the p2* parameters, and p3Name and the p3* parameters. Keep this in mind when you write down the instructions for your customers :-)

The three effects have the same structure, p1*, p2* and p3*, so we're going to refer to the three of them indistinctly by just naming the properties particle* (for example, particleFlags will refer to p1Flags, p2Flags and p3Flags.)

SETUP: THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT

Check the following section on this page, knowing that:

[Black Tulip] ***Script Name*** [MODULE] refers to [Black Tulip] Bathtub Controller [MODULE]
CODE_NUMBER is -28640987
NAME_ON_MENU is Bathtub

AVSitter line looks like: BUTTON Bathtub|-28640987
MLP line looks like: LINKMSG Bathtub | 1,-4,-28640987,fromMLP

You have example AVpos and .MENUITEMS notecards with your purchase. Remember that this works too with AVSitter 2.

TROUBLESHOOTING

Q: I click the water/particle options on the menu, but no visible outcome shows. What's going wrong?

A: Most likely, there's not a particles source/animated texture source defined in the object. Double-check the DESCRIPTION of the prim you expect to be a SL particles source/animated texture source.

Q: I hear no sound when I change the volume from the menu. What could be going wrong?

A: Make sure that there are sound clips on the "Content" tab of the prim with the script. Make sure that the names coincides exactly with the names given in the configuration notecard. Make sure also that sounds aren't muted.

For any other problem not described here, please give a complete description of your issue in the following online form.

I'll get back to you after I have read your report and replicated your issue inworld, according to your description of it. Please, be detailed.

-- Auryn Beorn

Black Tulip - Scripts

Pages

Thursday, May 1, 2014