Script: My Snowglobe - Music Edition

[Black Tulip] Snowglobe - Music Edition (Script for Designers)

(c) 2014 Auryn Beorn

Snowglobe Music 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
  • HOW TO SET UP THE SPINNING PARTS
  • IMPORTANT NOTES ABOUT THE SNOW PARTICLES
  • THE CONFIGURATION NOTECARD
• WHERE DO I PURCHASE SONGS?
• THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT
• TROUBLESHOOTING

FEATURES

• Start/Stop at the same time:
  Light, Spin Parts (keys, stars...), Particles Snow, Animated Texture
• Start/Stop those effects independently when the global effect is ON
• Change the light color
• Change the animated texture type (slide/rotate) - Global setting
• Change the speed of the animated texture - Global setting
• Notecard configuration for the songs
• It allows each song having different sample duration (i.e., a song may have its samples being 9.5 seconds and another song have its samples being 9.8 seconds)
• Volume is changed via menu
• 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!)

SET UP: WHAT SCRIPT TO USE?

There are two scripts contained in your folder:

[Black Tulip] Snowglobe - Music Edition MESH
[Black Tulip] Snowglobe - Music Edition MESH [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] Snowglobe - Music Edition MESH

The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] Snowglobe - Music Edition MESH [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] Snowglobe - Music Edition MESH
[Black Tulip] Snowglobe - Music Edition MESH [MODULE]

SETUP: EXAMINING THE SAMPLE OBJECT

With this script, you may control the following:

• Start/Stop at the same time:
  Light, Spin Parts (keys, stars...), Particles Snow, Animated Texture
• Start/Stop those effects independently when the global effect is ON
• Change the light color
• Change the animated texture type (slide/rotate) - Global setting
• Change the speed of the animated texture - Global setting
• Notecard configuration for the songs
• It allows each song having different sample duration (i.e., a song may have its samples being 9.5 seconds and another song have its samples being 9.8 seconds)

We'll understand better what this means by examining the [Black Tulip] Snowglobe - MUSIC SCRIPTED SAMPLE 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] Snowglobe - Music Edition MESH" script.

What does this mean?
That the script and texture for particle effects, 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. The sample object has no particle textures used (and so particles will show as a little dot), but you can drop your texture and set it up as indicated later.

You should also see:

• The [Black Tulip] Snowglobe - Music Edition MESH ~CFG~ configuration notecard
• Several sample soundclips.

Having this clear, now let's examine the sample object in detail. It consists of two linked prims: The snowglobe itself, and a winding key. Right click to edit, click "Edit linked", and now:

• Inspect the snowglobe prim. Check its description. It says:

animTexture;2#snow#light

• Inspect now the winding key's description. It says:

spinPrim;<1.0,0.0,0.0>;1.0;1.0

What do these descriptions mean? That's what we cover in the next section.

SETUP: FORMAT OF THE DESCRIPTIONS

With this script, we may have the following:

• One light point
• One animated texture point
• One particle snow emitter point (please check the "Important notes about the snow particles!" section for more)
• As many spinning parts as you could need

If you rez the sample [Black Tulip] Snowglobe - MUSIC SCRIPTED SAMPLE object and click it to get the menu, you'll see, as soon as you select ON/OFF to start all the effects, that the winding key spins. But there it is only one prim that will be the snow emitter, only one prim that will be the light point, and only one prim that will have the texture animated.

To tell the script which these primitives are in our LINKED object, we have to write specific words (CASE SENSITIVE) in the DESCRIPTION of each primitive (DESCRIPTION - not the name, don't confuse them!)

• Expected description for a light point: light
• Expected description for a snow emitter: snow
• Expected description for an animated texture prim: animTexture;FACE_NUMBER (see here for how to get the face number if you don't know how; if you want all sides animated, type -1 as FACE_NUMBER)
• Expected description for a spinning part: see the following section, HOW TO SET UP THE SPINNING PARTS

We may want a primitive being, at the same time, animated texture AND snow emitter.
Is this possible?

Yes. The description we should write would be, in that case:

animTexture;2#snow

Does this mean, if we want to have light, snow AND animated texture in the same prim, we could write:

animTexture;2#snow#light

and it would work? YES

Does this mean, if we want a spinning part AND snow, we could write:

spinPrim;<0.0,0.0,1.0>;1.0;1.0#snow

and it would work? YES

Does it matter if we write first snow, light or any other? It matters not. Write them as you prefer. Only what specifies how the prim will spin has a very specific format to be respected, but that is explained following.

And that would be it.

Set the DESCRIPTIONS according to these simple rules, drop the main script in your linked object, and your snowglobe is ready to go!

SETUP: HOW TO SET UP THE SPINNING PARTS

As you can check in the sample [Black Tulip] Snowglobe - MUSIC SCRIPTED SAMPLE object, this script allows you to ALSO rotate, by spinning, all the child prims you wish to rotate (until you hit the script's memory limit - don't worry, this won't happen with five/ten spinning prims). You could also make the root prim to rotate. Perhaps this is not what you would like anyway, but feel free to make a copy of your object and try this if you're curious about :-) (basically, it will make the whole object to spin around the root)

We have to begin by rezzing our object.
Set the rotation of the ROOT PRIM to:

X = 0.00
Y = 0.00
Z = 0.00

Don't worry if your object doesn't look like you have designed it. You will be able of rotating it again as you wish ONCE you have gathered the values for the spin vectors.

Rez the [Black Tulip] Snowglobe - MUSIC SCRIPTED SAMPLE sample object to follow this explanation. The captures are taken with a different object, but the principle is the same: pay special attention to the sections of the diagram that are highlighted.

Set its root rotation as said above:

X = 0.00
Y = 0.00
Z = 0.00

Now go into Edit linked parts. Click the winding key.

Check its description field. It says:

spinPrim;<0.0,0.0,1.0>;1.0;1.0

What does this mean?

The first that we have to know is that the script will read the semicolons (;) and take all the values between them.
So in the case above:

spinPrim;<0.0,0.0,1.0>;1.0;1.0

we see that there are FOUR pieces of information:

spinPrim
<0.0,0.0,1.0>
1.0
1.0

It is VERY IMPORTANT the order these values appear! If they don't appear in this exact order, the script won't be able to read the values of the prim we want to spin.

What each of those values mean?

First one:

spinPrim

means that the script has to consider this prim as a spinning one. The word has to be written exactly as said above. It IS case sensitive!

The second one:

<0.0,0.0,1.0>

is the spin vector. Don't worry, it is explained after this how to obtain it correctly.

The third one:

1.0

is the spin rate value. It is a number with decimals that, to make it easy to understand, we can think of as the velocity, so the smaller the value we type in, the slower the piece will spin and the reverse.

and the last one:

1.0

might be complicated to understand and, anyway, it doesn't make sense if our prims are not physical. Since this last one can be very technical, we will leave it always as 1.0. If you have the knowledge to follow the explanations from the wiki, then you can learn more about it in this wiki page: http://wiki.secondlife.com/wiki/LlTargetOmega

This last value corresponds to the gain parameter the wiki mentions there.

And how the spin vector has been obtained?

With the object having the root rotation set to <0.00 ,0.00, 0.00> (as stated above), and being in WORLD COORDINATES mode, we choose the axis we want the object rotating around.

• If the axis is X, the RED one, we write the spin vector as: <1.0, 0.0, 0.0>
• If the axis is Y, the GREEN one, we write the spin vector as: <0.0, 1.0, 0.0>
• If the axis is Z, the BLUE one, we write the spin vector as: <0.0, 0.0, 1.0>

IMPORTANT NOTES ABOUT THE SNOW PARTICLES

You would expect that the SIZE of your snowglobe affected somehow to the snow emitted, and in fact, this happens by using this tool. If your SNOW EMITTER PRIM is smaller, the particles effect covers less volume. If bigger, it covers more. It attempts to always fill the snowglobe, INSIDE.

To be able to achieve this, the script, internally, takes the smallest dimension of the prim where you say the snow will emit, and it will adapt the effect to that smallest dimension.

Example: if the size of the primitive you decide to be the snow emitter is X = 1.0, Y = 0.5, Z = 2.0, then the script will take 0.5 to decide how far the particles will get.

From this, a DESIGN TIP is that you set the SPHERE that snowglobes use to have as the primitive emitting snow (you can see that in fact in the sample object included). The sphere of the snowglobe will have the same size for X, Y, Z, or at least, very similar sizes among them, so the snow effect will adapt nicely to the size of your snowglobe.

If you see that your particles barely show up, check if you're using a different primitive as emitter as well as the sizes (as it could be the ground cylinder in the provided sample: Z is quite smaller than X and Y, and that value would be the one taken for the snow effect.)

Please read the following notes about WHERE to drop the particle texture if you use any, and setting permissions: IMPORTANT NOTE ABOUT THE PARTICLES

SETUP: THE CONFIGURATION NOTECARD

The configuration notecard is named [Black Tulip] Snowglobe - Music Edition MESH ~CFG~ needs to be written to provide all the data we want to:

• Specify which samples compose a full song
• Specify which name we want showing up on the menu for each song
• Specify the sample duration per song
• Say if we want the script to be silent or, on the contrary, to whisper in local chat the title of the selected song

(No other mode than whisper is allowed to prevent spamming avatars around that, most likely, won't be interested in knowing about songs being played.)

This data needs to be written in a specific way, so let's examine the [Black Tulip] Snowglobe - Music Edition MESH ~CFG~ notecard.

The lines beginning by:

#

are comments in the notecard.

They give important reminders, so don't delete them unless you don't need them. Comment lines won't use more script memory. Comment lines won't make your script laggier. Comment lines won't make your script work slower.

So it is OKAY if you leave them for your own reference. The comments in the notecard from your package explain all the parameters: You may want to leave those comments.

The sample notecard (not the one in the snowglobe) shows as:

# [Black Tulip] Snowglobe - Music Edition MESH ~CFG~
#
#   SaySongInChat = M
#       M can be 0 or 1
#           0 for a silent script
#           1 for the script whispering in local chat the title of the song being played
#
#   Put as many of the follow lines as songs you wish to offer - Limit: 20
#   Song = BaseName | TitleMenu | SampleDuration
#       BaseName    The base name all the samples for a same song share
#       TitleMenu       The title we want appearing in the menu to select song
#                           Max: 35 characters
#       SampleDuration  Sample duration, in seconds, for the samples of that specific song
#                               A default value of 9.5 will be provided if the value is not
#                               in the range [0.1, 9.95] (10.0 won't be accepted - for your safety)

SaySongInChat = 0

Song = BaseName | TitleMenu | SampleDuration

After all the comment lines, we find the following:

SaySongInChat = 0

This means that the script will NOT say anything when a song is played. If we wish to have the script whispering which song is going to be played once selected, we would write instead:

SaySongInChat = 1

And then the lines that would define the songs. We should write ONE line with the following format PER SONG:

Song = BaseName | TitleMenu | SampleDuration

What do BaseName, TitleMenu and SampleDuration mean here?

BaseName
This is the base name all the samples for a same song share. This will be clear with an example.

Let's suppose we have a song composed of five samples, named:

Little_Black_Rain_Cloud-0
    Little_Black_Rain_Cloud-1
    Little_Black_Rain_Cloud-2
    Little_Black_Rain_Cloud-3
    Little_Black_Rain_Cloud-4

By writing the following line in the configuration notecard:

Song = Little_Black_Rain_Cloud- | Little Black Rain Cloud | 9.5

we can see that the first part, BaseName, says:

Little_Black_Rain_Cloud-

The script will look for all the samples in your object with name beginning by Little_Black_Rain_Cloud- and will find all the samples mentioned above, so internally, it will know that the five samples above are all part of the same song.

IMPORTANT: All spaces around the specified name in the notecard will be DISCARDED. This has consequences. If your samples are, for example:

Little_Black_Rain_Cloud 0
    Little_Black_Rain_Cloud 1
    Little_Black_Rain_Cloud 2

and you specify in the notecard:

Song = Little_Black_Rain_Cloud | Little Black Rain Cloud | 9.5

this would make the script to look for sample names like:

Little_Black_Rain_Cloud0
    Little_Black_Rain_Cloud1
    Little_Black_Rain_Cloud2

and not like:

Little_Black_Rain_Cloud 0
    Little_Black_Rain_Cloud 1
    Little_Black_Rain_Cloud 2

Rename your samples accordingly before running into this issue. Usually, all songs you purchase will have names that won't be a problem in this regard.

TitleMenu
The title we want appearing in the menu to select song.
Max: 35 characters - Longer titles will be cut to fit this

Continuing with the sample line said above:

Song = Little_Black_Rain_Cloud | Little Black Rain Cloud | 9.5

we find

Little Black Rain Cloud

as value for TitleMenu, so this will be shown in the menu as the title for that song.

SampleDuration
Sample duration, in seconds, for the samples of that specific song.
A default value of 9.5 will be provided if the value is not in the range [0.1, 9.95] (10.0 won't be accepted - for your safety)

In the sample line we're using to explain this:

Song = Little_Black_Rain_Cloud | Little Black Rain Cloud | 9.5

we are saying that all the samples that are part of this song have a duration of 9.5 seconds. Since this value is in the allowed range for the script (greater or equal than 0.1 AND less or equal than 9.95), it will be accepted as the sample duration - for that one song.

WHERE DO I PURCHASE SONGS?

In order to have this item working, you will need, of course, to have songs to work with!

You can always check the Second Life Marketplace for songs. I sell some public domain, full permissions songs that you may use in items you create, at my main store.

But then, you can create yourself the samples you need and upload them. I explain all the procedure in the "Music!" book, which you can purchase in Marketplace or inworld.

This might be, perhaps, the best choice: that you look for public domain sources and you create your own samples. Be careful and do not use songs that have copyright!

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] Snowglobe - Music Edition MESH [MODULE]
CODE_NUMBER is -18640887
NAME_ON_MENU is Snowglobe

AVSitter line looks like: BUTTON Snowglobe|-18640887
MLP line looks like: LINKMSG Snowglobe | 1,-4,-18640887,fromMLP

You have example AVpos and .MENUITEMS notecards with your purchase. Remember that this works too with AVSitter 2.

TROUBLESHOOTING

Q: I click the animated texture/light/particle options on the menu, but no visible outcome shows. What's going wrong?

A: Most likely, there's not a light source/particles source/animated texture source defined in the object. Double-check the DESCRIPTION of the prim you expect to be a SL light source/particles source/animated texture source.


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