Script: Fireplaces v2

Documentation ยท Fireplaces v2

Fireplaces v2 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.

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] Fireplaces v2
  • [Black Tulip] Fireplaces v2 ~CFG~
  • [Black Tulip] Fireplaces v2 - AUXILIARY TOOL
  • [Black Tulip] Fireplaces v2 - AUXILIARY TOOL ~CFG~
  • [Black Tulip] Proof Of Purchase - Fireplaces v2
  • [Black Tulip] Fireplaces v2 ~DOC~

and these sample assets, necessary to follow the step-by-step guide:

  • [Black Tulip] Fireplace #1 - Start Here
  • [Black Tulip] Fire Crackling
  • [Black Tulip] Fireplace #1 - 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.

Features list

  • Starts/Stops all the fire effects (animated textures, particles)
  • Light on/off for the light points we define
  • Light menu options
  • Access menu options
  • It can work with AVsitter or standalone
  • New clickMode variable, shows the menu when you want it to

Step by Step Guide

The configuration notecard has already set up two particles effects (sparks and smoke), 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] Fireplace #1 - Start Here

and think in what we want to achieve from it:

  • When we turn the fireplace on, the animated fire will light, sparks and smoke particles will emit.
  • When we turn the fireplace off, the animated fire will disappear, the sparks and smoke particles will stop.
  • While it's on, we want a sound clip for fire crackling noise
  • We want to set up a light point so when we turn the light on/off, the light will emit from that point we've decided.
  • We want that this menu shows on touch, unless it's setup together with another engine like AVsitter; then it will show only from the corresponding AVsitter button

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 prim will be the particles smoke: the logs. So we click on Edit linked, click on the logs prim, then click on the General tab, and change the description this way, to the word smoke:

Now we decide which prim will be the particle sparks: the animated fire. Still with Edit linked checked, we select that prim, make sure we're on the General tab, and write this description, sparks:

If we want that this prim is also the light point, then we add the # character as a separator in the description, and after it, we add the word light. The whole description is now sparks#light as the picture shows:

This animated texture turns on and off, so we're not done yet. First, the script has to know how to animate it. We write another # character in the description and then the following data, sparks#light#flames;19;1;1;0.5;-1 :

In the advanced section we'll see what flames;19;1;1;0.5;-1 means and how to obtain it.

Finally, we have to tell the script how transparent it is this prim when showing, and how transparent when in off state. We can also specify glow values. So we write another # character and the following, showHide=a:

being the final description for this prim sparks#light#flames;19;1;1;0.5;-1#showHide=a

This last part is only to identify the prim as special, as a prim that will show and hide when turned on and off. It needs of a second part: Information on the configuration notecard to tell what happens exactly when on and when off. The auxiliary tool will tell us what to write on the configuration notecard. We study it in the next section.

So far, we've set up the following:

  • Source of smoke particles
  • Source of sparks particles
  • Light source
  • Animated texture prim parameters
  • We've marked this prim too as a prim that will show/hide when the fire is on/off, the rest of the definition of this being in the configuration notecard

The rest of the parameters are set up in the notecard, to help things being simple in your first time using the script. The particles go at the end because they're a long section. 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 prims that should show/hide when we click ON/OFF. Those prims must be already identified, like we've shown (the parameter showHide=name) in the description, and now we're using the auxiliary tool to set them up.

To use it, we first drop the [Black Tulip] Fireplaces v2 - AUXILIARY TOOL ~CFG~ configuration notecard into the contents of the fireplace, and after it, the [Black Tulip] Fireplaces v2 - AUXILIARY TOOL script. The script is immediately ready to work.

When we do this, we set the prims that show/hide with the transparency and glow that we want for them when we turn on the fireplace.

Then we click for the menu:

and select the SAVE F.ON option. This outputs text in local chat:

Now we make the fire prim completely transparent (and remove the glow):

Then we click on SAVE F.OFF, which outputs the following text in chat:

Now with those lines, we add them to the main [Black Tulip] Fireplaces v2 ~CFG~ configuration notecard. You'll find them added to help in this first experience, but remember that you have to do this with yours, removing these example lines and changing them with yours.

Once we're done with the auxiliary tool, we click for its menu and select [DELETE]. This will remove the [Black Tulip] Fireplaces v2 - AUXILIARY TOOL script and its configuration notecard, [Black Tulip] Fireplaces v2 - AUXILIARY TOOL ~CFG~, from the prim's inventory.

Completing our basic setup

Drop the included [Black Tulip] Fire Crackling sample sound in the fireplace object's contents. Then drop the [Black Tulip] Fireplaces v2 ~CFG~ configuration notecard. Then change permissions for next owner of the [Black Tulip] Fireplaces v2 script, and drop it in too. The script starts reading the configuration notecard. Once it's done, your fireplace is 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 fireplace included so you can compare with your own setup, in case you run into trouble. It's the [Black Tulip] Fireplace #1 - Finished Sample object.

Advanced Setup

The advanced setup of this script involves the following:

  • Learning how to set up the animated texture (Description Format)
  • Learning a note on the prims marked with showHide (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)
  • Learning important details about the particles setup (Notecard Configuration in Detail)

Description Format

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

About the showHide part: Write a different identifier per prim you want to show/hide. Keep the name as short as possible. Two prims must not have the same identifier. If one of them is showHide=a, then the other one must be, for example, showHide=b.

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:

BUTTON Fire|-31401000

As a button under the [ADJUST] menu in AVsitter 2, we must include this line ON TOP of the AVpos notecard:

ADJUST Fire|-31401000

From any other script, what we need to know is that the linked message must send a -31401000 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.

Important details about the particles setup (how to use textures)

This script allows us to emit a different texture every N seconds. We indicate that in two steps. First, in this line:

timeForEffectChange = 0.5

This would mean that, if activated, one or the two particle effects would emit a different texture every 0.5 seconds. Now, where do we say if this is activated, and how do we add more than one texture name to one particle effect?

Notice this line:

p1TexturesMode = 0

When set to 0, it means that no different textures are emitted. We set that value to 1 to say "emit different textures, in the order I write them". We set that value to 2 to say "emit these different textures randomly". This last option may be the one you prefer in case you use the feature.

How do we specify these different textures? Typing one:

p1Texture = 

line per texture (after the = sign we would write the texture name). Notice that the second effect has similar parameters, but named with the starting p2 name.

IMPORTANT: If you plan on using a particles emitter that is not the root prim (most likely case), then you must drop the texture in the prim with the script and in the emitter prim. If you don't do this, you will see the default texture, a circle.

Observe that there's a similar parameter for the radius of the particles effect:

p1RadiusMode = 0

While it's set to 0, the radius is static, but if we change this to 1, the radius will randomly change from 0 to the radius value we've set using the same timing than the textures.

You can change parameters like the color, the size, the transparency... We're not going to explain particles here, but we invite you to explore our books on the topic at Marketplace:

Important: If your objects aren't designed so the center of the bounding box coincides with the place where you want particles to emit, you will need to add an extra prim that will contain the particles texture and where the particles script will be dropped. The sample objects have their bounding boxes correctly set, so no extra prims are needed.


Q: I've set textures in the configuration notecard, but instead I keep seeing circles. What can be done to fix this?

A: Remember this note from the documentation.
IMPORTANT: If you plan on using a particles emitter that is not the root prim (most likely case), then you must drop the texture in the prim with the script and in the emitter prim. If you don't do this, you will see the default texture, a circle.

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.