- Write comment lines, for our own clarifications. Comment lines always begin with a # character.
- Define timezones
- Define sound clips for the different sound functions
- Add the pendulum configuration
- Define which extra buttons we want to add to the menu, to call other scripts from them, having a maximum of 2 buttons (grandfather clock) or 5 buttons (analog clock).
With the exception of comment lines, all of the other lines have the structure:
parameter = value
There are many shared configuration parts, so we will clarify when needed, to which clock script we're referring to: grandfather clock script or analog clock script, basic edition.
Setting up Timezones
There's no way to have the clock adjusting automatically to your timezone within SL. But you can setup the clock so several timezones will be available for your users. They are setup in the [Black Tulip] Analog Clock ~CFG~ configuration notecard. Ideally, you would list them ordered in time, for the << TZONE and TZONE >> buttons will navigate through them in the order they have been defined in the notecard.
When we want to add a timezone to our list, we add a line with the following format:
timezone = additionToGMT|abbreviated name|locations list
timezone is written like that, case sensitive: it's the word that tells the script, we're now defining a timezone. We also leave the = sign after it. The script needs it, to know what values are we giving next.
abbreviated name and locations list are informative texts that will show up on the menu. For example, the following configuration line:
timezone = +9|UTC+9|Tokyo
makes for the following text to show on the menu:
Timezone: UTC+9 (Tokyo)
The additionToGMT value requires more explanation.
The time function used returns the current time in GMT (which is also UTC). In order to have the hands display the time in the timezone of your choice, the script needs to know how many hours to add, or subtract. This is the value we type in additionToGMT. If we type +1, the script calculates the current hour in GMT, and adds one, showing then that final result. If we type -8 (to have the clock in SLT), the script calculates the current hour in GMT, and subtracts eight, showing then the final result.
If you want to include timezones like India, which is shifted 5:30 hours with respect to UTC, you should type +5.5 for this value. Why +5.5? Because the last 0.5 is half an hour. Minutes go from 0 to 59, while normal decimals (to put it easily) range from .0 to .9999999..., so we have to transform minutes accordingly.
It's not complicated anyway. There are just a few timezones that are shifted not an exact hour, and the amount of minutes is either 30 or 45. So when you want a timezone that is shifted 30 minutes, you add .5, when you want a timezone that is shifted 45 minutes, you add .75 (three quarters of unit).
The configuration notecard included in your package already contains a list covering many timezones. You may want to make a copy of this, and shorten that list as you prefer (or making it longer!). You may also prefer including other timezones. Clicking here, you'll go to a wikipedia page that gives you information enough to build your own list. This wikipedia page may be useful too, and this one contains a list of the official abbreviations.
Then we have the following configuration line:
startInTimezone = -8
That is telling the clock which timezone will start showing, after reading the configuration notecard. The number we indicate must correspond to the first number of one of the timezone = additionToGMT|abbreviated name|locations list lines we've defined as timezones, this is, additionToGMT.
Setting up Sounds
The basic edition of the analog clock script lets you define two sounds: one for tick, and another one for tock. They will play alternatively each second. We define them in the [Black Tulip] Analog Clock ~CFG~ configuration notecard. The provided notecard shows this:
tickSoundclip = [Black Tulip] Clock Tick Sound tockSoundclip = [Black Tulip] Clock Tock Sound
We simply have to add the sound clip name after the tickSoundclip variable for tick sound, and after the tockSoundclip variable for tock sound. Then we have to include the soundclips in the object, in the same prim where the script is. Remember to change permissions of the sound clips too!
The grandfather clock version of the analog clock script lets you define several sounds, for tick-tock sound, and a variety of chime and bells combinations. They're all defined in the [Black Tulip] Analog Clock ~CFG~ configuration notecard. To clarify, the notecard includes a comment line:
# Soundclips configuration
and under it, we find all the variables related to the sound clips. Let explain now which they are, what's their use, and what we're expected to set up there.
First, we can define one sound for tick, and another one for tock. They will play alternatively each second. The provided notecard shows where and how:
tickSoundclip = [Black Tulip] Clock Tick Sound #2 tockSoundclip = [Black Tulip] Clock Tock Sound #2
We simply have to add the sound clip name after the tickSoundclip variable for tick sound, and after the tockSoundclip variable for tock sound.
The next three variables we find, are related to the chime sound. Let's read what the notecard contains, and we'll see what that means, for our own use:
chimeSoundclip = [Black Tulip] Clock Chime #2 chimeTime = 3 chimeSoundState = 0
The first one, chimeSoundclip, is to indicate which soundclip to use as chime, when the clock strikes a new hour. Then, in chimeTime, we have to indicate how many seconds long the sound clip is. The script needs this information. The number of seconds may have decimals.
Then, chimeSoundState indicates what of three possible choices should happen when the clock strikes a new hour:
- 0: When the clock strikes a new hour, it will sound as many chimes as hours.
- 1: When the clock strikes a new hour, it will sound just one chime.
- 2: When the clock strikes a new hour, nothing will sound.
This can be changed in the menu, so this is a starting choice for your customers.
The next two lines are to include chime sounds for quarters and half an hour:
quarterSoundclip = [Black Tulip] Clock - Quarter Sound halfSoundclip = [Black Tulip] Clock - Half Hour Sound
Those sounds can later be turned on/off under the Chimes >> menu. If the half hour sound is turned off, but quarters are turned on, then there will sound the quarter sound too, at half the hour.
The rest of variables are necessary if we want the clock to play music before the chimes, when the clock strikes a new hour. These variables are:
preludeMusicBase = [Black Tulip] Clock Melody #2 - totalPreludeSamples = 4 preludeSampleTime = 9.5 preludeLastSampleTime = 1.4
Let's study them now.
If we want a melody sounding before the chimes do, when the clock strikes a new hour, we will need one, or more soundclips, containing this melody. We indicate how many of these soundclips in the totalPreludeSamples variable. In the provided example, this is 4, which means that the melody is divided in 4 soundclips. If our melody is just one sound clip, we would write 1 in there.
All samples but the last one will have the same length. We indicate this in the preludeSampleTime variable. 9.5 seconds is quite standard, but if your samples are 9.8 seconds, then instead of typing 9.5, you type there 9.8.
The last sample will normally have different length. We indicate this in the preludeLastSampleTime variable. If our song has just one sample, we will write for preludeSampleTime and preludeLastSampleTime the same value.
Finally, what is preludeMusicBase? It's the common name that all sound clips have, before the number that indicates in which order of the sequence they are. Let's observe the sample names:
[Black Tulip] Clock Melody #2 -1 [Black Tulip] Clock Melody #2 -2 [Black Tulip] Clock Melody #2 -3 [Black Tulip] Clock Melody #2 -4
They all start by the name given in preludeMusicBase, and then they're numbered from 1 to the totalPreludeSamples we've specified. If your sound samples aren't numbered this way, they you have to change them, so they are numbered like this.
Notice that there's not a space after the last character given in preludeMusicBase and the number indicating the order in the sequence.
Remember that we have to include all the specified soundclips in the object, in the same prim where the script is. Remember to change permissions for next owner of the sound clips too!
Setting up Optional Buttons
This feature is common to both scripts. The grandfather clock allows up to two extra buttons, and the analog clock allows up to five extra buttons. These optional button lines have the following format:
button = button_label|link_msg_number|link_prim|text_to_send|show_menu_again
This one is a little more complicated, and it is only required if you plan to add extra buttons that call other scripts. Skip this part if you are not doing this for now, making sure that no button lines are in the configuration notecard.
In order to "call", "execute" or "launch" another script from our main script, we have to use a communication mechanism called linked messages. This is a mechanism that allows scripts to send messages to other scripts in the same linked object, and to listen to possible messages coming from other scripts in the same linked object.
When we use a button line, it means that it will add a button on the menu. This button menu, upon click, will SEND a message to ANOTHER SCRIPT that could be in ANY of the prims of our linked object. That another script should be listening, and will expect to know from us:
A code number that should be specified in the script documentation. That is link_msg_number in the notecard line.
A message. That is text_to_send in the notecard line.
A UUID. The barbeque controller script sends the UUID of the avatar having clicked the menu.
If the main menu should show up after executing the action. That is show_menu_again in the notecard line. We type there 0 if the menu should not show up after the action, and we type 1 if the menu should show again after the action. To better understand this, check what happens when clicking the example Snow Red and Stop Snow do. Snow Red shows the script menu again after calling the particles script: if you check the configuration notecard, it has a value of 1 for show_menu_again. When clicking Stop Snow, the script menu doesn't show. If you check the configuration notecard, it has a value of 0 for show_menu_again.
Apart from this, the main script needs a couple more data items to know about:
What text will show on the menu button?
That is button_label in the notecard line.
IMPORTANT: It should not have more than 24 characters.
To what primitive this message is being sent.
That is link_prim in the notecard line.
Unless your application has very specific requirements, this link_prim code will be one of the following, meaning:
| 1 | This will send the message to the root prim IF our object consists of more than one prim linked (Or there's an avatar sitting on a single-prim item) |
| -1 | This will send the message to all prims in the linked object |
| -2 | This will send the message to all prims BUT the one containing the SENDER (this script controller) script |
| -3 | This will send the message to all child prims (that is, all prims BUT the root prim) |
| -4 | This will send the message to the prim where the SENDER (this script controller) script is in (-4 could be seen as the opposite code of -2) |
Please check the documentation of the other scripts you wish to send linked messages from this one, to make sure of how exactly you should write the line. The lines explained above are the generic ideas valid for every script accepting linked messages, but this documentation cannot replace any other script's documentation for their own interface. Check with the creator of the other script how this should be done.
