[Black Tulip] Barbeque Controller (Script for Designers)
(c) 2014 Auryn BeornBeta-test: Sei Lisa, Auryn Beorn
Barbeque 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
- Define one or several barbeque points in your object. Each "barbeque point" can be a whole prim or just a face of it.
- Decide the color and glow that each "barbeque point" will have when off, and when reaching the max.
- Define an additional SL-light point to illuminate the area when barbeque points are on.
- Define, if needed, a sound to play in loop when the global state is on.
- Start/Stop at the same time:
- Color and Glow cycle effect
- 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.
- Menu timeout to reduce lag - no open listeners after timeout (0.001 ms script time when idle)
- The script also scans the area every 20 seconds: if no avatars are around, the glow effect is stopped to reduce the impact on the server
- 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 TWO buttons to interact with (call) other scripts
SET UP: WHAT SCRIPT TO USE?
There are two scripts contained in your folder:
[Black Tulip] Barbeque Controller [Black Tulip] Barbeque 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] Barbeque Controller
The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] Barbeque 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] Barbeque 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] Barbeque Controller
[Black Tulip] Barbeque Controller [MODULE]
SETUP: EXAMINING THE SAMPLE OBJECT
With this script, you may control the following:
- One or several "barbeque points" in your object. Each "barbeque point" can be a whole prim or just a face of it.
- Decide the color and glow that each "barbeque point" will have when off, and when reaching the max.
- An additional SL-light point to illuminate the area when barbeque points are on.
- Define, if needed, a sound to play in loop when the global state is on.
- Start/Stop at the same time:
- Color and Glow cycle effect
- Sound
- Light (SL light point)
- Start/Stop independently the effects listed above when the global effect is ON
We'll understand better what this means by examining the [Black Tulip] Barbeque 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] Barbeque Controller script
- The [Black Tulip] Barbeque Controller ~CFG~ configuration notecard
- The well known sample sound called Crackling Fire
What does this mean?
That the script, the configuration notecard and the 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 three linked prims: A (mesh) barbeque and one box. Right click to edit, click "Edit linked", and now:
- Inspect the barbeque prim: the coals, which are one mesh face, will have a glow and color effect running on it.
- Inspect now the description of this prim. It says:
glowPoint;coals
- Inspect the red box and its description. It says:
glowPoint;redBox#light
What constitutes a barbeque prim? A face on a prim, or a whole prim.
What texture parameters cycle from initial to end, when we activate it from the menu? Color, Glow.
How do we tell the script what prim and what face is a barbeque point?
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 barbeque point is:
glowPoint;a_name_we_want
In our sample object, we've found this description:
glowPoint;coals
glowPoint is the mandatory part, written exactly as is (CASE SENSITIVE), then coals 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 barbeque point has as description:
glowPoint;redBox#light
What does this mean?
On one side, we find glowPoint;redBox - This, as before, means that the prim is a barbeque point, and redBox is a name of our choice that will be used in the configuration notecard.
Then we have a # character: this separates the barbeque point 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.
You may have several prims and faces as barbeque points that will have color and glow cycling when activated. But there it is only one prim that will be the SL light point.
SETUP: FORMAT OF THE DESCRIPTIONS
To tell the script which of the linked primitives are relevant (barbeque points 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:
glowPoint;a_name_we_want
Like it was the case of:
glowPoint;coals
If we want a primitive having barbeque points and being at the same time a SL light point, then we write the:
glowPoint;coals#light
combination. The # character will separate parameters, and it does not matter the order we choose to write the parameters.
This:
light#glowPoint;coals
would have the same effect.
The possible descriptions this script recognizes are:
Expected description for a barbeque point: glowPoint;a_name_we_want
Expected description for a light point: light
Set the DESCRIPTIONS according to these simple rules, drop the main script and the configuration notecard in your linked object, and your barbeque is ready to go!
SETUP: THE CONFIGURATION NOTECARD
The configuration notecard is named [Black Tulip] Barbeque 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 global effect is turned on, if any.
- Define which faces of our object are barbeque points, and which values of glow and color to use as initial and end cycle values.
- Define how many steps will use the cycle effect to go from initial to end and back to initial.
- Define how much time between steps in the glow cycle.
- 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 |
| totalSteps | In here, we specify how many steps will use the cycle effect to cover the full initial -$gt; end -> initial cycle for both color and glow. This means that if we define, for example, 20 steps, we have 10 steps to go from initial to end, then the remaining 10 to go from end to initial again |
| timeBetweenSteps | In here, we decide the time between steps in the glow cycle: the smaller the time, the heavier for the server. The minimum value accepted is 0.2 |
| button | In here, we decide which extra buttons will show up in our menu, and what other scripts they will call |
| [BBQ_points] | Definition of the barbeque points: 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.
sound = soundclip_name
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.
totalSteps = number
We can write here a number that should be greater or equal than 2. It has to be a whole number (no decimals).
For example, if we write:
totalSteps = 30
This means that when we turn on the glow/color cycle effect, the script will take the initial values given in the notecard for color and glow in each barbeque point, then perform 30/2 = 15 steps until reaching the final values given in the notecard for color and glow. Once the script reaches this end value, then the remaining 30 - 15 = 15 steps are used to go from the final values to the initial values again.
If nothing is specified, or a wrong number is written, the script will take 20 as default value.
timeBetweenSteps = number
When we activate the glow cycle effect, the script will run the totalSteps indicated above per initial_values -> end_values -> initial_values cycle. And how much time will pass between each step? The time, in seconds, that we specify after timeBetweenSteps =
The minimum value accepted, in an attempt to stress the servers the least possible, is 0.2. This value still gives for a smooth cycle when the sim has no lag. You can of course try with higher values: that would be even better in lag terms!
As an extra measure to help with lag, the script incorporates this mechanism:
When the color and glow cycle effect has been turned on, the script scans every 20 seconds for avatars in a distance of 20 meters from the object. If no avatars were found, then the color and glow cycle effect will be turned off automatically (so the server will not be stressed by calculations which nobody will see anyway!)
An user can, of course, cam from further than 20 meters and click to use the menu to start the glow effect again, but 20 seconds after, the scan will detect no avatars in 20 meters and will stop the effect again.
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 "BARBEQUE POINT DEFINITION" subsection if you are not doing this for now.
In order to "call", "execute" or "launch" another script from our script (barbeque 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 barbeque controller script sends the UUID of the avatar having clicked the menu.
Apart from this, the barbeque 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 (barbeque 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 (barbeque 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.
"BARBEQUE POINT" DEFINITION
We finally get to see how the barbeque points 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 part of the description:
glowPoint;redBox
Now check the following lines in the notecard:
redBox,1 = 0.1|<0.5,0,0>|0.2|<0,0.5,0> redBox,2 = 0.2|<0.5,0.5,0>|0.3|<0,0.5,0.5>
These lines mean the following:
redBox,1 = 0.1|<0.5,0,0>|0.2|<0,0.5,0>
The prim having glowPoint;redBox in the description will display the following changes on face number 1 (the number after the comma right after redBox in the notecard line):
Values for the initial color and glow values in the glow cycle in that face are given by the first 0.1|<0.5,0,0> group:
Glow: 0.1 Color: <0.5,0,0> (This would be dark red)
Values for the end color and glow values in the glow cycle in that face are given by the second 0.2|<0,0.5,0> group:
Glow: 0.2 Color: <0,0.5,0> (This would be dark green)
Now similarly, we can quickly understand what the second line means:
redBox,2 = 0.2|<0.5,0.5,0>|0.3|<0,0.5,0.5>
The prim having glowPoint;redBox in the description will display the following changes on face number 2:
Values for the initial color and glow values in the glow cycle in that face are given by the first 0.1|<0.5,0,0> group:
Glow: 0.2 Color: <0.5,0.5,0>
Values for the end color and glow values in the glow cycle in that face are given by the second 0.2|<0,0.5,0> group:
Glow: 0.3 Color: <0,0.5,0.5>
Now we can say that, speaking in general, a barbeque point is defined by a notecard line having the structure:
primDesc,FACE = Glow_Initial|Color_Initial|Glow_Final|Color_Final
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 barbeque point, 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 and glow values in the cycle. This is a limitation imposed by design, to guarantee the maximum available memory possible for your linked barbeque points.
If you have a case where you would need to consider all faces separately, write them independently in the notecard.
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] Barbeque Controller [MODULE]
CODE_NUMBER is -28640986
NAME_ON_MENU is BBQ
AVSitter line looks like: BUTTON BBQ|-28640986
MLP line looks like: LINKMSG BBQ | 1,-4,-28640986,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/glow options on the menu, but no visible outcome shows. What's going wrong?
A: Most likely, there's not a light source/glow source defined in the object. Double-check the DESCRIPTION of the prim you expect to be a SL light point/glow source.
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. Make sure that the name coincides exactly with the name given in the configuration notecard.
Q: Why are my "barbeque points" being colored black? I haven't defined black anywhere.
A: Make sure that you've assigned exactly TWO color|glow groups per "barbeque point" and face 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
