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