Sunday, November 2, 2014

Script: Fireplaces - Animated Texture Edition

[Black Tulip] Fireplaces - Animated Texture Edition (Script for Designers)

(c) 2013 Auryn Beorn

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


  • Start/Stop at the same time:
    • Fire 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.
  • 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 sound is the well known Crackling Fire from Philip Linden, which you can use if you wish in your builds.


SET UP: WHAT SCRIPT TO USE?


There are two scripts contained in your folder:

[Black Tulip] Fireplaces - Animated Texture Edition
[Black Tulip] Fireplaces - 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] Fireplaces - Animated Texture Edition

The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] Fireplaces - 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] Fireplaces - Animated Texture Edition
[Black Tulip] Fireplaces - 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 (regular prims, sculpted, mesh)

We'll understand better what this means by examining the [Black Tulip] Fireplaces AnimTex Edition - Sculpt & Mesh 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 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] Fireplaces - Animated Texture Edition script
  • 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 eight linked prims: Mesh planes for animated texture flames (and mesh logs), sculpt logs, sculpt fire for animated texture fire, and several SL-boxes also for flames. The sculpt logs are the root prim here. Right click to edit, click "Edit linked", and now:

  • Inspect the sculpted logs prim. This is the SL-light point.
  • Inspect now the description of this prim. It says:

light

  • This means, this prim is the SL-light point. Later we go in more detail about how the description is built exactly.
  • Inspect now any of the regular SL-boxes over the sculpted logs. Inspect the description. It says:

animFire;3;4;4;9;-1

  • This means, the SL-box will have animated textures. Later we go in more detail for this.
  • Now inspect the mesh planes just above the mesh logs. Inspect the description. It says:

animFire;3;4;4;9;0

  • Again, an animated texture.
  • Finally, inspect the sculpted fire over the sculpted logs. Inspect the description. It says:

animFire;19;0;0;0.1;-1

  • This means that this prim has animated texture.

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 flames, and being at the same time a SL light point, then we write the:

light#animFire;3;4;4;9;-1

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

This:

animFire;3;4;4;9;-1#light

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: animFire (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 flames takes a little more work. We explain this now.

Animated fires in SL are often created by animating a texture, which can be one of two possible types:

  • A texture containing different "frames" of the fire animation (we call this "cell animation")
  • A texture designed to slide on a sculpted/mesh fire having a fire flame shape

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 couple of very common examples that, most likely, will be the ones you will use :-)

General format:

animFire;code_for_animation_type;x;y;speed;face

animFire
This is the code word for the script. Write it as is. Case sensitive!

code_for_animation_type
If you use a cell animation: 3
If you use a slide animation: 19

x
If you use a cell animation: you type here how many VERTICAL frames the animation has
If you use a slide animation: you type here the number 0

y
If you use a cell animation: you type here how many HORIZONTAL frames the animation has
If you use a slide animation: you type here the number 0

speed
Here you type the frames per second to show (if cell animation), or the speed the animation will slide

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!)


EXAMPLES


animFire;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.

animFire;19;0;0;0.1;0

This is a slide animation (code 19), so in both x and y we type the number 0. The speed is 0.1. It will show in face 0 of the prim.

It is very important to indicate the face! Nowadays, it's very likely that we will use a multi-face mesh, and we want to animate only one face in that case, not the whole mesh! :-)

(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!)


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] Fireplaces - Animated Texture Edition [MODULE]
CODE_NUMBER is -18640987
NAME_ON_MENU is Fireplace

AVSitter line looks like: BUTTON Fireplace|-18640987
MLP line looks like: LINKMSG Fireplace | 1,-4,-18640987,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