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
• SET UP
  
  • WHAT SCRIPT TO USE?
  • CHANGE PERMISSIONS FOR NEXT OWNER
  • EXAMINING THE SAMPLE OBJECT
  • FORMAT OF THE DESCRIPTIONS
  • THE CONFIGURATION NOTECARD
  • HOW TO GET THE FACE NUMBER
  • HOW TO WRITE THE COLOR CODE
• THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT
• TROUBLESHOOTING

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:

sound	In here, we specify the name of a soundclip that will sound when the SL light point turns on, if any
button	In 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:

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 (this 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 (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

Script: Lamps Controller

[Black Tulip] Lamps Controller v1 (Script for Designers)

(c) 2014 Auryn Beorn

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

TABLE OF CONTENTS

• FEATURES
• SET UP
  
  • WHAT SCRIPT TO USE?
  • CHANGE PERMISSIONS FOR NEXT OWNER
  • EXAMINING THE SAMPLE OBJECT
  • FORMAT OF THE DESCRIPTIONS
  • THE CONFIGURATION NOTECARD
  • HOW TO GET THE FACE NUMBER
  • HOW TO WRITE THE COLOR CODE
• THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT
• TROUBLESHOOTING

FEATURES

• Define one or several "lamps" in your object. Each lamp can be a whole prim or just a face of it.
• Decide the color, glow and full bright that each lamp will have per state.
• Decide how many states you want. The possibilities are:
  
  • Lamps that go on/off.
  • Lamps that go from off to min, from min to max, from max to off again.
  • Lamps that go from off to min, from min to med, from med to max, from max to off again.
• Define an additional SL-light point to illuminate the area when lamps are on.
• Change the state of each lamp individually, by clicking its face.
• Decide, if needed, a sound to play when the global state of lamps goes from off to on, from on to off (like a light switch).
• Change the state of all the lamps at the same time, from the menu..
• Switch the SL-light point on/off when the global state of the lamps is other than off.
• Change the light color, radius, intensity and fall off of this SL-light point.
• 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...
• You can add up to FOUR buttons to interact with (call) other scripts

SET UP: WHAT SCRIPT TO USE?

There are two scripts contained in your folder:

[Black Tulip] Lamps Controller
[Black Tulip] Lamps 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 lamps menu to show when the object is clicked:
[Black Tulip] Lamps Controller

The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] Lamps 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] Lamps 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] Lamps Controller
[Black Tulip] Lamps Controller [MODULE]

SETUP: EXAMINING THE SAMPLE OBJECT

With this script, you may control the following:

• One or several "lamps" in your object. Each lamp can be a whole prim or just a face of it.
• Decide the color, glow and full bright that each lamp will have per state.
• Decide how many states you want. The possibilities are:
  
  • Lamps that go on/off.
  • Lamps that go from off to min, from min to max, from max to off again.
  • Lamps that go from off to min, from min to med, from med to max, from max to off again.
• An additional SL-light point to illuminate the area when lamps are on.

We'll understand better what this means by examining the "[Black Tulip] Lamps Controller - 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] Lamps Controller" script
• The "[Black Tulip] Lamps Controller ~CFG~" configuration notecard
• Two sample sounds called "[Black Tulip] Switch ON" and "[Black Tulip] Switch OFF"

What does this mean?
That the script, the configuration notecard and the 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 three linked prims: A (mesh) flowers lamp, a copy of the same flowers lamp (smaller) and a box, playing the role of a base. Right click to edit, click "Edit linked", and now:

• Inspect the flowers of the bigger flower lamp under the texture tab: they have glow.
• Inspect now the description of this prim. It says:

lamp;flowerBig

• Now inspect the base of this flower lamp: there's nothing in particular to highlight under the texture tab. No glow, nothing relevant.
• Inspect the flowers of the smaller flower lamp under the texture tab: they also have glow.
• Inspect now the description of this prim. It says:

lamp;flowerSmall#light

• Inspect the base of this flower lamp: again, there's nothing in particular to highlight under the texture tab. No glow, nothing relevant.
• Inspect the box
• Nothing relevant under the texture tab
• No description given

Click any of the flowers of the bigger lamp. You should see that the glow changes, the color changes, and perhaps it also changed to full bright. Click that same flower again. More changes. Click it again. Then again. As you can observe, this lamp is cycling through three states when you click that specific face. If you click another flower, that cycling happens too. Every lamp will cycle independently when you click on it.

So, what constitutes a lamp? A face on a prim, or a whole prim.
What texture parameters change when we click on the lamp? Color, Glow, Full bright.

How do we tell the script what prim and what face is a lamp?
First, we give the prim a relevant description, explained next. Then, we add one or more configuration lines in the configuration notecard. The notecard part is explained in the "THE CONFIGURATION NOTECARD" section below.

The format of the description for a lamp is:

lamp;a_name_we_want

In our sample object, we've found this description:

lamp;flowerBig

lamp is the mandatory part, written exactly as is (CASE SENSITIVE), then flowerBig has been a name of our choice. This name will later be used in the configuration notecard, so we have to refer to it.

The second lamp has as description:

lamp;flowerSmall#light

What does this mean?

On one side, we find lamp;flowerSmall - This, as before, means that the prim is a lamp, and flowerSmall is a name of our choice that will be used in the configuration notecard.

Then we have a # character: this separates the lamp definition from the light point definition.
Then we have the light word in the description. When the script finds it, it knows that's the prim that should also work as a SL light point.

If you now click on a face that is NOT a lamp, you'll get a menu. In that menu, you can cycle the lamps state GLOBALLY. This means that all the lamps will be affected at the same time. Then you can also turn on/off the SL light point and change its properties. You may have several prims and faces as "lamps" that will have color, glow and full bright changed. But there it is only one prim that will be the SL light point.

IMPORTANT: It is advised that you leave at least ONE face in your object WITHOUT any kind of lamp definition. Otherwise, the menu will never show up, because the lamp cycling behaviour has precedence over the menu.

SETUP: FORMAT OF THE DESCRIPTIONS

To tell the script which of the linked primitives are relevant (lamps 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

Then, the other possibility is:

lamp;a_name_we_want

Like it was the case of:

lamp;flowerBig

If we want a primitive having lamps and being at the same time a SL light point, then we write the:

lamp;flowerSmall#light

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

This:

light#lamp;flowerSmall

would have the same effect.

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

SETUP: THE CONFIGURATION NOTECARD

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

• Write comment lines, for our own clarifications. Comment lines always begin with a # character.
• Define what sound clip to use when the SL light point turns on, if any.
• Define what sound clip to use when the SL light point turns off, if any.
• Define how many states the lamps will cycle among.
• Define which faces of our object are lamps, and which values of glow, full bright and color to use per state.
• Define which extra buttons we want to add to the menu, to call other scripts from them, having a maximum of 4 buttons.

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

parameter = value

The accepted parameter keywords are:

soundON	In here, we specify the name of a soundclip that will sound when the SL light point turns on, if any
soundOFF	In here, we specify the name of a soundclip that will sound when the SL light point turns off, if any
maxLightLevels	In here, we decide how many states our lamps will cycle through
button	In here, we decide which extra buttons will show up in our menu, and what other scripts they will call
[lamps]	Definition of the lamps: The way they're written is different than the parameters listed above

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

soundON = soundclip_name

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


soundOFF = soundclip_name

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


maxLightLevels = number

We can write here a number that should be either 2, 3 or 4. Depending on the number we type, we'll have the following lamp cycle:

2	From off to on; from on to off
3	From off to min; from min to max; from max to off
4	From off to min; from min to med; from med to max; from max to off

If nothing is specified, or a wrong number is written, the script will take 4 as default value.


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. Jump to the LAMP DEFINITION subsection if you are not doing this for now.

In order to call, execute or launch another script from our script (lamps 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 lamp controller 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.

LAMP DEFINITION

We finally get to see how the lamps are defined in the notecard. We will do this by following the example provided in the sample object.

Remember that we had a prim having as description:

lamp;flowerBig

Now check the following lines in the notecard:

flowerBig,1 = 0.2|0|<1,0,0>|0.4|0|<0,1,0>|0.6|1|<0,0,1>
flowerBig,2 = 0.2|0|<1,1,0>|0.4|0|<0,1,1>|0.6|1|<1,0,1>

These lines mean the following:

flowerBig,1 = 0.2|0|<1,0,0>|0.4|0|<0,1,0>|0.6|1|<0,0,1>

The prim having lamp;flowerBig in the description will display the following changes on face number 1 (the number after the comma right after flowerBig in the notecard line):

Values for the minimum light state in that face are given by the first 0.2|0|<1,0,0> group:

Glow:           0.2
Full Bright:    0 (So this means, NO full bright)
Color:          <1,0,0> (This would be red)

Values for the medium light state in that face are given by the second 0.4|0|<0,1,0> group:

Glow:           0.4
Full Bright:    0 (So this means, NO full bright)
Color:          <0,1,0> (This would be green)

Values for the maximum light state in that face are given by the third and last 0.6|1|<0,0,1> group:

Glow:           0.6
Full Bright:    1 (So this means, YES to full bright)
Color:          <0,0,1> (This would be blue)

Now similarly, we can quickly understand what the second line means:

flowerBig,2 = 0.2|0|<1,1,0>|0.4|0|<0,1,1>|0.6|1|<1,0,1>

The prim having lamp;flowerBig in the description will display the following changes on face number 2:

Values for the minimum light state in that face are given by the first 0.2|0|<1,1,0> group:

Glow:           0.2
Full Bright:    0 (So this means, NO full bright)
Color:          <1,1,0> (This would be yellow)

Values for the medium light state in that face are given by the second 0.4|0|<0,1,1> group:

Glow:           0.4
Full Bright:    0 (So this means, NO full bright)
Color:          <0,1,1> (This would be cyan)

Values for the maximum light state in that face are given by the third and last 0.6|1|<1,0,1> group:

Glow:           0.6
Full Bright:    1 (So this means, YES to full bright)
Color:          <1,0,1> (This would be magenta)

Now we can say that, speaking in general, a lamp is defined by a notecard line having the structure:

primDesc,FACE = Glow_Min|FB_Min|Color_Min|Glow_Med|FB_Med|Color_Med|Glow_Max|FB_Max|Color_Max

Where FACE is the face that will have glow, full bright (FB) and color changed during its light cycle.

NOTE: If we write -1 for FACE, then that means that ALL FACES in the prim will be a lamp, being subject to the cycle defined by the ONE notecard line.

IMPORTANT: In this case of all faces, the script will assume that all faces of said prim have the same color, glow and full bright values per state. This is a limitation imposed by design, to guarantee the maximum available memory possible for your linked lamps.

If you have a case where you would need to consider all faces separately, write them independently in the notecard.


IMPORTANT: We will write as many glow|full_bright|color groups as number of maxLightLevels we've indicated in the notecard. For example, this means that if we indicate:

maxLightLevels = 1

we only have to write lamp definitions as:

flowerBig,1 = 0.2|0|<1,0,0>

If we write:

maxLightLevels = 2

we would write the lamp definitions as:

flowerBig,1 = 0.2|0|<1,0,0>|0.4|0|<0,1,0>

and when we have:

maxLightLevels = 3

then we write the full lamp definition, as in the sample object:

flowerBig,1 = 0.2|0|<1,0,0>|0.4|0|<0,1,0>|0.6|1|<0,0,1>

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] Lamps Controller [MODULE]
CODE_NUMBER is -28640985
NAME_ON_MENU is Lamps

AVSitter line looks like: BUTTON Lamps|-28640985
MLP line looks like: LINKMSG Lamps | 1,-4,-28640985,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 options on the menu, but no visible outcome shows. What's going wrong?

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


Q: I hear no sounds when the lamps are turned on/off. What could be going wrong?

A: Make sure that there's a sound clip on the "Content" tab of the prim with the script. Make sure that the name coincides exactly with the name given in the configuration notecard.


Q: The menu doesn't show when I click on the object. What's going wrong?

A: Make sure that you have NOT assigned all prims and faces as lamps.


Q: Why are my lights being colored black? I haven't defined black anywhere.

A: Make sure that you've assigned color|glow|full_bright groups enough per lamp and face, according to the given value for the maxLightLevels parameter in the configuration notecard.



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

Script: Simple Light Controller

:: BLACK TULIP SIMPLE LIGHT CONTROLLER ::
:: Turn on/off all your light points with one script ::

Simple Light Controller at Marketplace
By Auryn Beorn (2012)

TABLE OF CONTENTS

• PURPOSE AND FEATURES
• INSTALL AND USE YOUR LIGHT CONTROLLER

PURPOSE AND FEATURES

The purpose of the "[Black Tulip] Simple Light Controller" script is to allow you to:

• Define one or many "light points" in your linked object
• Determine which color the light point will be
• Determine the intensity, radius and fall off for the light point
• Turn the light points on/off by clicking the object
• Optionally, turn on/off the full bright feature at the same time the light is activated/deactivated

Everything is controlled by a single script, so you can have as many light points as you wish in the same object at low lag cost.

But as you can see, this box contains four full permissions scripts, separated in two blocks:

• [Black Tulip] Light on/off (AU)
• [Black Tulip] Light on/off (OO)

Both scripts perform the same action: On touch, it turns on/off the lights in the defined light points.
The difference between them is:

• AU -> All Users - Everybody will be able to turn on/off the lights by clicking the object.
• OO -> Owner Only - Only the owner of the object will be able to turn on/off the lights by clicking the object.

• [Black Tulip] Light on/off + FB (AU)
• [Black Tulip] Light on/off + FB (OO)

Both scripts perform the same action: On touch, it turns on/off the lights AND the full bright property in the defined light points.

The difference between them is:

• AU -> All Users - Everybody will be able to turn on/off the lights AND the full bright property by clicking the object.
• OO -> Owner Only - Only the owner of the object will be able to turn on/off the lights AND the full bright property by clicking the object.

INSTALL AND USE YOUR LIGHT CONTROLLER

In order to have this system working in your object, you have to:

• Decide which are the "light points" in your linked object
• Give those primitives a *description* having the following format:

light;color;intensity;radius;falloff

where:

light	This word is written as is (case sensitive!)
color	A valid color for a LSL script (check the note below - there's an included tool to make this task *fast and easy*)
intensity	The intensity of the light point - Valid values range from 0.0 to 1.0
radius	The radius of the light point - Valid values range from 0.0 to 20.0
falloff	The falloff of the light point - Valid values range from 0.0 to 2.0

An example of valid description following the rules above:

light;<1,0.796078,0.592157>;1;5;0.75

This package includes the [Black Tulip] Color HUD tool for you easily writing a color correctly in this part. Check this link for all the "how's" (the documentation.)

YES: Each light point may have different colors, intensities, radius and falloff
Just set the description as you wish them, for each prim that will be a light point

Drop ONE of the following scripts:

• [Black Tulip] Light on/off (AU)
• [Black Tulip] Light on/off (OO)
• [Black Tulip] Light on/off + FB (AU)
• [Black Tulip] Light on/off + FB (OO)

in the "Content" tab of your object.

That's it. As soon as the script is dropped, it looks for all the defined light points and from that moment, clicking will turn/off all of them (and the full bright property, if the "FB" version of this script is used.)

IMPORTANT: Given to some scripting limits, if the descriptions are changed to modify the properties of the light, you should RESET the script. Keep this in mind when you design your own objects for sale, to instruct your customer to reset the script. If the description changes, this is a change not detected by a script - that's why we have to do it manually.

In case of doubt about its use, check the included sample object "[Black Tulip] Tiffany Lamp 1" and its setup.