Script: Lamps v2

Documentation ยท Lamps Script v2

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.

IMPORTANT! This documentation is common to the Lamps v2 script and the LITE version because they work similarly. The LITE version doesn't have all the features. When one of the features is only available to the full version, it will be noted.

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] Lamps v2
  • [Black Tulip] Lamps v2 ~CFG~
  • [Black Tulip] Lamps v2 ~AUX TOOL~
  • [Black Tulip] Link Message Test for Lamps v2
  • [Black Tulip] Switch ON
  • [Black Tulip] Switch OFF
  • [Black Tulip] Proof Of Purchase - Lamps v2
  • [Black Tulip] Lamps v2 ~DOC~

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

  • [Black Tulip] Lamps v2 - SAMPLE OBJECT - Empty for Aux Tool
  • [Black Tulip] Lamps v2 - SAMPLE OBJECT - FINISHED

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

Full version:

  • Change color, transparency, glow, full bright, and SL light point options of your lamp(s) depending on its state
  • Lamp may cycle from on/off to min/med/max/off states
  • Extra SL light points can be added, controlled by menu
  • Light color options can be defined by the user
  • Light cycle can be played through an independent face (example: turn on a light bulb by clicking outside the lamp)
  • Lamp can play an on/off sound when turned on/off
  • Night Mode: Light cycles automatically with the SL day cycle
  • Menu can be launched by other scripts like AVsitter
  • Lamp can change its state through other script (for example, a custom home management system)
  • Lamp sends information to other scripts about the current state

LITE version:

  • Change color, transparency, glow, and full bright options of your lamp(s) depending on its state
  • Lamp may cycle from on/off to min/med/max/off states
  • Light cycle can be played through an independent face (example: turn on a light bulb by clicking outside the lamp)
  • Lamp can play an on/off sound when turned on/off
  • Menu can be launched by other scripts like AVsitter
  • Lamp can change its state through other script (for example, a custom home management system)
  • Lamp sends information to other scripts about the current state

Step by Step Guide

This script can be set up entirely by manually setting up a notecard, and we'll discuss the format in the Advanced section. However for this Step by Step Guide we'll use an auxiliary tool that will help a lot with setting up our lights.

The first concept that we need to have clear is that our lamp may go just from on to off back and forth, it may go from min to max and then to off, and it may go from min to med, from med to max and then from max to off. This is, the lamp can cycle through 2 states (on/off), 3 states (min/max/off) or 4 states (min/med/max/off). We have to indicate this in the configuration notecard and it will be explained at its time.

We begin by rezzing the object [Black Tulip] Lamps v2 - SAMPLE OBJECT - Empty for Aux Tool and inspecting it.

It consists of three linked objects: two identical lamps (except in the size), and a regular box (colored red). The regular box is our root prim, and all scripts and configuration items will be dropped in it. (This is the default behaviour when the whole object is selected).

What are we going to do with this? First we're going to decide which prims will be lamps, and which prims will be light points. A lamp is a prim face which will have color/transparency/glow and/or full bright changed as the states change. A light point is a prim that emits light. Lamps are also light points. Their light color, intensity, radius, and fall-off will cycle together with the color, transparency, glow, full bright. Extra light points can be defined if needed, and those will be controlled exclusively via menu.

For the purpose of illustrating the most possible in our Step by Step Guide, we'll set up the following:

  • The red box will be an extra light point, but it is not a lamp (full version only). This means that its color/transparency/glow and full bright will not change with the light cycle.
  • The small lamp will be a lamp: color, transparency, glow, full bright + light point properties.
  • The big lamp will be a lamp: color, transparency, glow, full bright + light point properties.

How do we set this up? First, we write things in each prim description. Which things?

  • The extra light point (full version only) needs the special keyword light in its description. So we edit linked parts, click on the red box, and write light in the description, as the picture shows:
  • The bigger lamp needs the special keyword lamp in its description, and something else. As we will see on the notecard, the configuration will refer to lamps by a name of our choice. We may want to call this prim flowerBig. Then we'll write lamp;flowerBig as description for it (notice the ; separating lamp and flowerBig):
  • Similarly, the smaller lamp needs the special keyword lamp followed by a ; and then followed by a word of our choice, for example, flowerSmall. So we write lamp;flowerSmall as the description of this prim:

Our sample object is ready for the auxiliary tool. Drop the [Black Tulip] Lamps v2 ~AUX TOOL~ script in the contents of our object, wait a second or two for the:

[07:10:40] [Black Tulip] Lamps v2 - SAMPLE OBJECT - Empty for Aux Tool:
[Lamps V2 AUX] Script is ready. Available memory, 30496 bytes

message, and click on it to observe the menu:

The idea is simple. First we decide how many states (transitions) our lamp will cycle through. We can choose 2, 3 or 4. For the sake of learning the most about the procedure, we'll choose 3 states. That means, our lamps will transition from an "off" state to an "on" or "min" state, then to a "max" state, and then again back to "off".

We set up the lamp the way we want it to look like in what matters to color, transparency, glow and full bright of some of the faces of the lamp. To illustrate this, we will change three faces per mesh lamp, being these faces numbers 1, 2, and 3. If we work with the Firestorm viewer, we can easily see the face number on the edit window. We also set up the light point properties as we like.

The way the lamp rezzes is good for an off state, so we click on Save Off on the menu. This saves to the script memory all the values for color, transparency, glow, and full bright, from each face, from the prims containing the lamp part in the description, and all the light properties that we've set for the lamp prims. If the script is reset, these values will be lost! Don't reset the script unless you're completely sure of what you're doing.

After saving the Off state, we have to decide color, transparency, glow and full bright per lamp prim, on the desired faces. To make it easy, we can change them all (faces 1, 2, 3) to yellow color, glow set to 0.02, leave the rest of faces and values untouched.

Now we decide how the light properties of the lamps should be. What color? What intensity? Radius? Fall-off? Again to make it simple, we will select each lamp prim and change the light intensity to 0.4, leaving the rest of values untouched.

Now we save these values with the auxiliary tool. Click to bring up the menu if the menu wasn't up, and select Save Min. After saving this, we can set the off values to check them at any time if we want by clicking on Set Off, and we can recover the min values by clicking the Set Min button.

We've saved the values of two out of three states. We would prepare and save now the "max" state, but instead of that, we're going to prepare and save the "med" state. The reason will be clear once we see the output for our notecard. So, for example, we tint green our lamp faces and give them a 0.10 value of glow:

and now we raise to 1 the intensity of their light points:

We click on Save Med to store our values and we can check if we wish that they're correct with the help of the Set buttons. Everything is good? Then it's time to [DUMP] the settings. This shows the following output:

which we copy/paste into a plain text editor, and clean it from timestamp lines and reminder lines:

Remember this: When we studied our setup, we decided that only faces number 1, 2, and 3 would show changes, in both lamp prims. So in order to save some script memory, we remove the lines corresponding to every other face not being 1, 2, or 3:

This script packs a lot of features, so saving memory is of great importance!

Now observe how we clean the end of the lines, to remove the last | and the last |;;; that would have been used if a fourth state had been used. First with the first lamp:

Then with the second lamp:

This data is ready to be pasted in our [Black Tulip] Lamps v2 ~CFG~ configuration notecard along with other important information. Let's observe a full [Black Tulip] Lamps v2 ~CFG~ configuration notecard (like the one included in your package) and let's talk about which parameters are relevant now, which ones will be explained in the advanced section.

Delete now the auxiliary script from the object, we won't be needing it any more.

Let's see now how the configuration notecard would look like when including the information of our lamps:

Oh, no, there's a lot of information in that notecard! Worry not. For now, we'll take a look at the following parameters:

  • soundON = [Black Tulip] Switch ON
  • soundOFF = [Black Tulip] Switch OFF
  • maxLightLevels = 3

The rest will be covered in the advanced section. You can leave them as they are. They are:

  • areaMgmSys
  • clickMode
  • lampName,light
  • lampName,face
  • lightColor (full version only)
  • button

So back to the easy parameters for now:

  • soundON = [Black Tulip] Switch ON
  • soundOFF = [Black Tulip] Switch OFF
  • maxLightLevels = 3

soundON is the name of a sound clip included in our object that we want to use as a sound to play when the lamp goes from off to on/min. Similarly, soundOFF is the name of a sound clip included in our object that we want to use as a sound to play when the lamp goes from any of the lighted states, to off. This package includes a couple of soundclips that you can use in your own creations.

Then we have maxLightLevels, which must be either 2, 3, or 4. If you want that your lamp goes on/off, then this number must be 2. If you want that your lamp goes off/min/max as we've done in this example, then this number must be 3. If you want the whole off/min/med/max range, then this number must be 4.

With all this, we're ready to drop things in our lamp. First we will change permissions for next owner to both sound clips. Make them no copy or no transfer, and drop them in the lamp.

Now drop the [Black Tulip] Lamps v2 ~CFG~ notecard:

And now change permissions for next owner and drop the [Black Tulip] Lamps v2 script:

The script will read the notecard and notify when it's done in local chat:

Notice that it has also turned off the lights. It begins in off state.

Clicking on the faces we've defined as lamps, the lamps will cycle automatically. Clicking anywhere else, we'll obtain the lights menu. We can cycle the lights from there too, with the ON/OFF button, and we can access to the extra light point button functions, Light ON/OFF and [MORE].

You have the [Black Tulip] Lamps v2 - SAMPLE OBJECT - FINISHED object in your package so you can check how the object has been set up, in case you get stuck at some point of this step by step guide.

Notice the Night Mode button. This is an option so the lamps cycle automatically with the SL day cycle. Don't forget adding this feature in your documentation to your customers!

There's more to this script, but it belongs to the advanced section. Specifically, these features:

  • Light color options can be defined by the user (full version only)
  • Light cycle can be played through an independent face (example: turn on a light bulb by clicking outside the lamp)
  • Menu can be launched by other scripts like AVsitter
  • Lamp can change its state through other script (for example, a custom home management system)
  • Lamp sends information to other scripts about the current state

Advanced Setup

The advanced setup covers the following features:

  • Light color options can be defined by the user (full version only)
  • Light cycle can be played through an independent face (example: turn on a light bulb by clicking outside the lamp)
  • Menu can be launched by other scripts like AVsitter
  • Lamp can change its state through other script (for example, a custom home management system)
  • Lamp sends information to other scripts about the current state

Some of these features are set in the configuration notecard. Others require of (advanced) scripting knowledge. It will be noted when this is the case.

Description Format in Detail

The description format allows for the # character as a separator, so you can use this script in conjunction with other scripts. For example, you could want to have a lamp whose texture changes. You can have both scripts working together as long as you use the # character to separate each description block.

Notecard Configuration in Detail

The notecard allows us to set up the following extra features:

  • Light color options can be defined by the user (full version only)
  • Light cycle can be played through an independent face (example: turn on a light bulb by clicking outside the lamp)
  • Menu can be launched by other scripts like AVsitter (button parameter)

Extra light points can have its color changed (they all change to the same color). We can define which colors will be available under the [MORE] [L.Color] submenu. This is done in the notecard (full version only). We use one line per color, and they have this format:

lightColor = button_label|color_code

button_label is the text that will show on the menu buttons. Maximum of 24 bytes or the script will throw an error. color_code is the LSL code of the color. If you have that your color is , then the LSL color is (you have to perform the operations and give the final result in the notecard).

The light cycle can be played through an independent face. What does this mean and what implications does this have? Suppose we have a lamp and we only want to make as a lamp face its light bulb. The light bulb will cycle when touched, but we can agree in the fact that having the user cam inside the lamp to reach the light bulb if they don't want to cycle through menu, is a bit of an inconvenience. So we can tell the script that there will be another face, perhaps the base of the lamp, that will also cycle the lamp lights, even though the base itself won't cycle. This makes our lamp easier to use to our final users.

We define this in the notecard this way:

lampName,switch,faceNumber

This implies that the prim has to be defined too as lamp in its description, for lampName is the assigned by us name of the lamp. The word switch is literal, and then faceNumber is the number of the face we want to be clickable for the cycle. In our hypothetic example, the face number of the base.

What else do we need to keep in mind? That there's always a need of an extra face they can click so they get the menu, since using this option doesn't show the menu, it only cycles the lamps. So in the case of our lamp, we can design our mesh so it has three faces: one for the light bulb, one for the base that will also cycle the lightbulb light, and one for the top of the lamp that will launch the menu.

Let's explore now how's the notecard involved in this feature: Menu can be launched by other scripts like AVsitter (button parameter).

We explain later what exactly clickMode means, but for now we leave its value set to 2 which means that if the avatar isn't sitting, they get the menu when clicking, but if they're sitting, they have to go through AVsitter's [ADJUST] button or whichever other way the scripts have to allow opening the Lamps menu. Once we're done setting our lamp as we want, we may want to go back to AVsitter (or the other script). We can do this thanks to the button parameter of the notecard.

The button parameter.

The button parameter has this structure:

button = buttonNameOnMenu|linkMsgCode|sendToPrim|textToSend|reshow

being:

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

How do we show the button in AVsitter?

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 Lamps|-31420000

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

ADJUST Lamps|-31420000

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 areaMgmSys parameter.

Finally, areaMgmSys lets us define a custom name that can be used from another script to, for example, group several lights into the same area to be lighted all together. This is covered in the Scripting API section, and it's advanced scripting.

Scripting API

The Scripting API is a guide for advanced scripters covering the following features of this script:

  • Menu can be launched by other scripts like AVsitter
  • Lamp can change its state through other script (for example, a custom home management system)
  • Lamp sends information to other scripts about the current state

Menu can be launched by other scripts like AVsitter

Send a linked message with this code number to show up the menu from your own script: -31420000

The previous section explains how to show the menu from AVsitter.

Lamp can change its state through other script (for example, a custom home management system)

The -31420002 message expects the following as the string parameter: A pipe separated string with the format state|areaMgmSys, where:

  • state can be one of the following, mirroring the lamp cycles: OFF, MIN, MED, MAX. Case sensitive!
  • areaMgmSys is the value we've defined in the notecard, to define separate areas of lamps.

Lamp sends information to other scripts about the current state

Whenever the lamps cycle, the script sends the following linked message:

llMessageLinked(
    LINK_SET, -31420001
    , newState + "|" + areaMgmSys + "|" + LampsLinks
    , avatarUUID);
  • newState will be one of these: OFF, MIN, MED, MAX.
  • areaMgmSys is the value we've defined in the notecard, to define separate areas of lamps.
  • LampsLinks is a ; separated list with the link numbers of the prims that are lamps.
  • avatarUUID is the UUID of the avatar clicking to cycle the lights.

Check the included [Black Tulip] Link Message Test for Lamps v2 sample script for examples on this.

Troubleshooting

Q: The script crashes when I add many lamps. What can I do?

A: Experiment to know how many lamps the script could handle without crashing, then the rest of lamps need each one a copy of the script and notecard (plus sounds) in their corresponding prims. Note though that the main menu could show up twice, so if the script crashes, perhaps the best solution is that every lamp prim contains its own copy of the script, notecard, and sounds.

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.