Script: Candles v2
Documentation · Candles v2
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.
Follow these directions carefully. Complete the Step by Step Guide in the first place and then go to the Advanced Setup section for a detailed explanation of all the features. There's a Troubleshooting section at the end. Before asking for help, check that your problem isn't one of the problems described in there.
License of Use: Click here to read the License of use.
What's included in your purchase
Check that your box contains the following assets:
- [Black Tulip] Candles - Animated Texture Edition v2
- [Black Tulip] Candles - Animated Texture Edition v2 ~CFG~
- [Black Tulip] Proof Of Purchase - Candles [AnimText.Ed] v2
- [Black Tulip] Candles - Animated Texture Edition v2 ~DOC~
- [Black Tulip] Say Color Number ~AUX TOOL~
and these sample assets, necessary to follow the step-by-step guide:
- [Black Tulip] Candles SAMPLE - Start here
- [Black Tulip] Candle Fire
- [Black Tulip] Example Menu for Candles - clickMode = 1
- [Black Tulip] Candles SAMPLE - Finished Sample
If any of these is missing, contact Auryn Beorn for a replacement. Keep in mind that sample assets are never provided in full perms state. They're included to illustrate how to use the script.
- Lights on/off the animated candle textures
- Light on/off for the light points we define
- Light menu options
- Access menu options
- It can work with AVsitter, other scripts we write, or standalone
- New clickMode variable, shows the menu when you want it to
- Light color definition: Define the light colors as you prefer
Step by Step Guide
The configuration notecard has already set up a light color definition and the other variables (clickMode and button), so we're going to make this step by step guide as short and simple as possible. Let's rez the sample object [Black Tulip] Candles SAMPLE - Start here
and think in what we want to achieve from it:
- When we turn the candles on, the animated flames will light, the light points will turn on.
- When we turn the candles off, the animated flames vanish, the light points turn off.
- While it's on, we want a sound clip for candle fire noise
- We want to set up several light points so when we turn the light on/off, the light will emit from those points we've decided.
- We want that this menu shows on touch always.
This is telling us one thing: some prims are special, and they need to be recognized by the script, somehow. This somehow will be by writing things in the corresponding prim description (don't confuse it with the prim name).
First we will decide which prims will have animated flames. As it turns out with this sample, it's all of them, so we have to write something in each of the prim descriptions. So we click on Edit linked, click on the root prim, then click on the General tab, and change the description this way, to the text candleFlame;3;4;4;15;4 :
Now we repeat with all the other prims, until they all have the same description, except the last number. What the description means is something we'll explain in the advanced setup section. The last number, though, it's important that we learn what it means now: It's the face number of the face with the animated flames. The root prim had this as number 4, but the other prims may have a different number, so let's show screenshots for each one of them, with the correct number.
Now we decide which prims are the light points. The ones temporarily tinted in red on the picture.
If we want that these prims are also light points, then we add the # character as a separator in the description, and after it, we add the word light. The whole description is now candleFlame;3;4;4;15;2#light as the pictures show:
In the advanced section we'll see what candleFlame;3;4;4;15;2 means and how to obtain it.
So far, we've set up the following:
- Animated texture prims parameters
- Light sources
The rest of the parameters are set up in the notecard, to help things being simple in your first time using the script. The light colors go at the end because they're the longest part. We can write above those parameters the necessary ones to make the animated fire show and hide. In order to obtain the specific values we want, we use the auxiliary tool that we explain in the next section.
Close the edit window if it still was open, and let's continue.
The auxiliary tool
The auxiliary tool helps us to obtain the values the script expects for the color we want for the light points. It's important to note that all light points will share the same light settings.
To use it, we first create a box, texture it blank so you can see the colors, and then drop the [Black Tulip] Say Color Number ~AUX TOOL~ script. The script is immediately ready to work.
When we do this, we color one of the box faces with the color we want for the light. For example, if we color the face as white, then we click on it to get the color value, we would write a line like this one in the [Black Tulip] Candles - Animated Texture Edition v2 ~CFG~ configuration notecard for this light color:
lightColor = White|<1, 1, 1>
Then we change the color, click on that face, repeat. We may have up to ten different light colors in the configuration notecard, as the one provided shows.
Once we're done with the auxiliary tool, we edit the object and simply delete it. If we're no longer using the box, we'll delete the box as well.
Completing our basic setup
Drop the included [Black Tulip] Candle Fire sample sound in the candles object's contents. Then drop the [Black Tulip] Candles - Animated Texture Edition v2 ~CFG~ configuration notecard. Then change permissions for next owner of the [Black Tulip] Candles - Animated Texture Edition v2 script, and drop it in too. The script starts reading the configuration notecard. Once it's done, your candles are ready to go!
We discuss in the next section all the related notes about the advanced setup, including how to make this script work with AVsitter. Read those notes carefully.
There's a finished candles object included so you can compare with your own setup, in case you run into trouble. It's the [Black Tulip] Candles SAMPLE - Finished Sample object.
The advanced setup of this script involves the following:
- Learning how to set up the animated texture (Description Format)
- Learning the parameter clickMode of the configuration notecard, which allows us, among others, to be able to use this script with AVsitter and others (Notecard Configuration in Detail)
- Learning the button parameter of the configuration notecard (Notecard Configuration in Detail)
We've already seen that the description of a prim serves us to identify it in several manners, but there's one part that was left for further detail: how to write the data related to the animated texture.
The general format of the animated texture flames is:
All the values but ANIM_TYPE_CODE are copied from the llSetTextureAnim function. The function header is:
llSetTextureAnim( integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate );
so we can see that in X we type what we find in sizex, in Y what we find in sizey, in SPEED what we find in rate, and in FACE what we find in face. ALL_SIDES must be translated to the -1 value.
And what about ANIM_TYPE_CODE? This parameter is what we find in mode. To make it easy and avoid an explication that involves adding and converting numbers to base 10, we're just putting here the two most used values:
- The usual ANIM SMOOTH animation has the value 19
- The usual CELL ANIMATION (many small frames playing as an animation) has the value 3
Notecard Configuration in Detail
The clickMode parameter.
When we have two scripts that react on click on the same prim, by clicking that prim we get the two scripts acting at once, which often means having two menus, one hiding the other one. Our older scripts solved this with a different version of the script called [MODULE], which only showed the menu when called from another script, AVsitter for example. We have updated this to get all the possible behaviours in a single script to maintain (which is easier also for developing).
clickMode is a variable that admits one of three values (0, 1, 2), and that it is specified in the notecard. Each value means this:
- 0: The menu shows on touch no matter what. We want to use 0 when no other script is on the root prim/or the same prim showing its own menu.
- 1: Touch never shows menu: Link Messages ONLY. This means that, for example, the menu would show only if we click a certain button in AVsitter, and only through that button.
- 2: Touch if not sitting. If sitting, Link Message. This means that if no one is sitting on the furniture, we can click on it and get the menu. But if there's just one avatar sitting on the furniture, the menu will show only through the corresponding AVsitter (eg.) options.
The starting sample notecard that comes with your package has this value:
clickMode = 2
This means that the setup we've made will work this way: if no one sits, we click and get the menu. But we can setup for example AVsitter, and as soon as someone sits, only those that sit will get the menu, through AVsitter buttons.
If you don't plan to use AVsitter or other scripts that can send link messages, you can change that value to 0. If you leave it set to 2 the behaviour isn't going to change, unless someone sits. So knowing this, adjust this parameter as it fits best to your application.
The button parameter.
The button parameter has this structure:
button = buttonNameOnMenu|linkMsgCode|sendToPrim|textToSend|reshow
- buttonNameOnMenu: The text we want showing on the menu button
- linkMsgCode: The code number to send
- sendToPrim: To which prim link number are we sending this? (-1 for all prims)
- textToSend: The text we're sending (optional)
- reshow: 1 if we want the menu to show again when we click the button, 0 otherwise
If we want this button to have the menu return to AVsitter, we write this on the notecard:
button = [^ AVsitter]|90005|-1||0
This is what this line means:
- [^ AVsitter]: The text we want showing on the menu button
- 90005: The code number to send
- -1: To which prim link number are we sending this (all prims)
- textToSend: The text we're sending is empty here, but notice that we write the | separator anyway
- reshow: 0 because we don't want to reshow our fireplace menu since we're asking AVsitter to show its own.
Consult with the scripter of the other script you want to make work through this button how to configure it. Refer them to this documentation.
Using clickMode and button to set your engine with AVsitter and other scripts
How do we show the button in AVsitter, or other scripts?
As a normal button in AVSitter, we must include this line in the menu where we want to show the option, in the AVpos notecard:
As a button under the [ADJUST] menu in AVsitter 2, we must include this line ON TOP of the AVpos notecard:
From any other script, what we need to know is that the linked message must send a -31402000 code number. Consult with your scripter if you don't know what this means.
If you used the previous version of this script, you may have noticed that the code number has changed. The old version code is no longer valid in this one.
This script also allows a third party to turn on the candles, turn them off, and launch the candles menu. This is useful when clickMode is set to 1. For example, a house controller script could turn on/off the candles without having to go through the menu.
Explanation coming soon!
No problems described yet.
If after having followed the directions and checked the troubleshooting list, you have problems making the script work, please click here for the customer service form.