Friday, October 31, 2014

Script: Simple Music Box

[Black Tulip] Simple Music Box - for Builders

(c) 2012 Auryn Beorn

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.

TABLE OF CONTENTS



FEATURES


  • Notecard configuration: It allows your song having the sample duration you need
  • Up to 256 spinning prims can be safely included
  • 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] Simple Music Box - Basic Edition
[Black Tulip] Simple Music Box - Basic 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] Simple Music Box - Basic Edition

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


SETUP: EXAMINING THE SAMPLE OBJECT


Rez the sample [Black Tulip] Simple Music Box - Sample Object from your box. It will load the configuration and output owner-say messages like the following (memory report for yours may vary):

[15:30] [Black Tulip] Simple Music Box - Sample Object: Reading configuration notecard...
[15:30] [Black Tulip] Simple Music Box - Sample Object: Read configuration: Done. Free memory for the script: 39250 bytes

Once we read the Read configuration: Done, we may proceed to click the object in order to bring up a menu.

So, click it. As soon as you click it, you have a menu showing with the following options:

[Stop/Play]    [Volume]       [*RESET*]
[Access]       [---]          [Close]

Using this is very simple. Clicking Stop/Play, the current song will start/stop and IF there are spinning parts defined (as the documentation explains below), the spinning parts will move when the song is playing, and stop once the song finishes.

*RESET* will ask us for confirmation to reset the script. Only the owner of the object is able to perform this operation.

By clicking Volume we get the following secondary menu to change the volume of the sounds played:

[Off]    [10%]    [25%]
[50%]    [75%]    [100%]
[^Up]    [---]    [Close]

Then finally by clicking Access in the main menu we get the following menu, which allows us to change who will be able to access to the menu and thus pick a song, play/stop them and change the volume:

[Everybody]    [Owner only]    [Group]
[^Up]          [---]           [Close]

How do we set up our furniture/items to make this work? We'll see it by inspecting the sample object in detail.

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] Simple Music Box - Basic Edition script.
  • The [Black Tulip] Simple Music Box ~config~ configuration notecard
  • Several sample soundclips.

What does this mean? That the script and sound clips, 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 several linked prims: The music box parts, little engine pieces and a winding key. Right click to edit, click "Edit linked", and now:

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

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

What does this description mean? That's what we cover in the next section.


SETUP: HOW TO SET UP THE SPINNING PARTS


As you can check in the sample [Black Tulip] Simple Music Box - Sample Object object, this script allows you to ALSO rotate, by spinning, all the child prims you wish to rotate. 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] My Music Box - Sample Object sample object to follow this explanation. 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>


SETUP: THE CONFIGURATION NOTECARD


The configuration notecard is named [Black Tulip] Simple Music Box ~config~ and needs to be written to provide all the data we want to:

  • Specify the sample duration of the song

This data needs to be written in a specific way, so let's examine the [Black Tulip] Simple Music Box ~config~ 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 shows as:

# [Black Tulip] Simple Music Box ~config~
#
#   SampleDuration = N
#       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)

SampleDuration = 9.5

After all the comment lines, we find the following:

SampleDuration = 9.5

So as the notecard says, it is the 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]


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] Simple Music Box - Basic Edition [MODULE]
CODE_NUMBER is -18640985
NAME_ON_MENU is Music

AVSitter line looks like: BUTTON Music|-18640985
MLP line looks like: LINKMSG Music | 1,-4,-18640985,fromMLP

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


If you run into any problem with this script, 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
Posted by at
Labels: , ,