Sunday, December 14, 2014

Script: Candles - Animated Texture Edition

[Black Tulip] Candles - Animated Texture Edition (Script for Designers)

(c) 2014 Auryn Beorn

Candles - Animated Texture Edition 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.

TABLE OF CONTENTS



FEATURES


  • Start/Stop at the same time:
    • Candle flames
    • Sound
    • Light (SL light point)
  • Start/Stop independently the effects listed above when the global effect is ON
  • Change the light color, radius, intensity and fall off of this SL-light point.
  • Change the sound volume.
  • Personalize the SL light point colors to show on the menu, in the configuration notecard.
  • Add up to three extra buttons to call other scripts.
  • 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!)

NOTE: It is NOT mandatory to add a sound. The included sample object, indeed, has no sound clips at all.


SET UP: WHAT SCRIPT TO USE?


There are two scripts contained in your folder:

[Black Tulip] Candles - Animated Texture Edition
[Black Tulip] Candles - Animated Texture Edition [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] Candles - Animated Texture Edition

The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] Candles - Animated Texture Edition [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.


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] Candles - Animated Texture Edition
[Black Tulip] Candles - Animated Texture Edition [MODULE]


SETUP: EXAMINING THE SAMPLE OBJECT


With this script, you may control the following:

  • One light point
  • As many animated-texture flames as you could need

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

First of all, click it to get the menu. You'll see, as soon as you select ON/OFF to start all the effects, that the flames show and are animated, the sound is on (if there's a sound and the selected volume isn't Off, of course :-) ) and the SL light emits. But there it is only one prim that will be the SL light point.

How is this done? Let's examine the object. Right click the sample object to edit it, then click the "Content" tab. When we do this, we're inspecting the contents of the ROOT PRIM. You should see:

  • The [Black Tulip] Candles - Animated Texture Edition script
  • The [Black Tulip] Candles - Animated Texture Edition ~CFG~ configuration notecard
  • A sample script, [Black Tulip] Particle Snow Example for Buttons, which is absolutely not necessary to make your flames work. It's included to illustrate how to add extra buttons with extra functionality, but by all means remove it and the associated entry menus in your own objects.

What does this mean?
That all the necessary assets, this is, candles script, the configuration notecard, and soundclip 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 four linked prims: different candlesticks and candle setups, all of them prepared to hold texture animated flames. Right click to edit, click "Edit linked", and now:

  • Inspect the root prim, which should be the three candles on a plate with an adornment. This is the SL-light point.
  • Inspect now the description of this prim. It says:

candleFlame;3;4;4;15;2#light

  • This means, this prim contains animated candle flames, and is also the SL-light point. Later we go in more detail about how the description is built exactly.
  • Inspect now any of the other child prims (they will highlight in blue). Inspect the description. It says:

candleFlame;3;4;4;15;1

  • This means, each of these prims will have animated textures. Later we go in more detail for this.

Now that we've inspected the object, let's study the details of the descriptions format.


SETUP: FORMAT OF THE DESCRIPTIONS


To tell the script which of the linked primitives are relevant (particle effects, animated texture effects or SL-light point), 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.

As we've seen, when inspecting the sample object, the following parameter-keyword would indicate that the prim is a SL-light point:

light

There is another possibility (explained below): animFire.

If we want a primitive having, for example, animated candle flames, and being at the same time a SL light point, then we write the:

candleFlame;3;4;4;15;2#light

combination. The # character will separate parameters, and it does not matter the order we choose to write the parameters.

This:

light#candleFlame;3;4;4;15;2

would have the same effect.


The possible descriptions this script recognizes are:

Expected description for a light point: light
Expected description for animated-texture flames: candleFlame (there's more to this one, explained next)

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

NOTE: Setting the description for the animated-texture candle flames takes a little more work. We explain this now.

Animated candle flames in SL are often created by animating a texture, which consists of a texture containing different "frames" of the fire animation (we call this "cell animation")

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 very common example that, most likely, will be the one you will use :-)

General format:

candleFlame;code_for_animation_type;x;y;speed;face

candleFlame
This is the code word for the script. Write it as is. Case sensitive!

code_for_animation_type
We're using cell animation in this case, so: 3

x
For cell animation: we type here how many VERTICAL frames the animation has

y
For cell animation: we type here how many HORIZONTAL frames the animation has

speed
Here we type the frames per second to show for this cell animation

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 (you type here the face number!)

EXAMPLE


candleFlame;3;4;4;9;-1

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 -1, which is the code for ALL THE FACES of the prim.

(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!)


THE CONFIGURATION NOTECARD


The configuration notecard is named [Black Tulip] Candles - Animated Texture Edition ~CFG~, and it allows us to:

  • Write comment lines, for our own clarifications. Comment lines always begin with a # character.
  • Define what colors we want to be shown as menu options. for the SL light point.
  • Define which extra buttons we want to add to the menu, to call other scripts from them, having a maximum of 2 buttons.

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

parameter = value

The accepted parameter keywords are:

soundIn here, we specify the name of a soundclip that will sound when the SL light point turns on, if any
buttonIn here, we decide which extra buttons will show up in our menu, and what other scripts they will call

Now, let's explain how the values are written and what they mean.

lightColor = button_label|color_code

The SL light point may have a color we specify. There's a submenu entry, L.Color, that will show a list of colors we define in the notecard. We define the colors by specifying, separated by the | character, what name should show on the menu, and the actual color code for that menu entry.

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.

How do we write the color code? Check HOW TO WRITE THE COLOR CODE and examine the configuration notecard with the examples.


button = button_label|link_msg_number|link_prim|text_to_send|show_menu_again

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 part if you are not doing this for now, making sure that no button lines are in the configuration notecard.

In order to "call", "execute" or "launch" another script from our main script, 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 barbeque controller script sends the UUID of the avatar having clicked the menu.
If the main menu should show up after executing the action. That is show_menu_again in the notecard line. We type there 0 if the menu should not show up after the action, and we type 1 if the menu should show again after the action. To better understand this, check what happens when clicking the example Snow Red, Snow Green and Stop Snow do. Snow Red and Snow Green show the candles menu again after calling the particles script: if you check the configuration notecard, they have a value of 1 for show_menu_again. When clicking Stop Snow, the candles menu doesn't show. If you check the configuration notecard, it has a value of 0 for show_menu_again.

Apart from this, the main 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:

1This 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)
-1This will send the message to all prims in the linked object
-2This will send the message to all prims BUT the one containing the SENDER (this controller) script
-3This will send the message to all child prims (that is, all prims BUT the root prim)
-4This will send the message to the prim where the SENDER (this 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 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] Candles - Animated Texture Edition [MODULE]
CODE_NUMBER is -38640983
NAME_ON_MENU is Candles

AVSitter line looks like: BUTTON Candles|-38640983
MLP line looks like: LINKMSG Candles | 1,-4,-38640983,fromMLP

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


TROUBLESHOOTING


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

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


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

A: Make sure that there's a sound clip on the Content tab of the prim with the script.


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