Common Doc

There are several sections of the documentation that are repeated in many scripts, like how to obtain a color code, how to know the face number of a certain face, setting permissions... Since all those parts are common, instead of repeating them in each documentation, they're listed in this page, linked in every page that makes use of them.

Also, many of the scripts have a module version. In this page you'll find the general documentation, and each script page will say what's the specific number to use.


NOTE: Since this section is generic to all scripts, in here we type:

[Black Tulip] ASSET

to refer to each and every purchased asset that has permissions set either as copy/no modify/no transfer or as FULL PERMS. This is, each and every script, sound clip, texture, animation... That is included in your package. The following procedure has to be done to EACH asset.

In order to abide by the license of use of this tool, you have to make sure you change permissions for next owner for the scripts the following way:

No Copy, or No Transfer, for all scripts in the package

To do this:

  • In your inventory, right click over the [Black Tulip] ASSET script
  • Select the "Properties" option. This opens a window where you can find a line at bottom saying:

Next owner can:
[ ] Modify [X] Copy [X] Transfer

By checking those marks we ALLOW what next owner can do. By leaving them empty, we're restricting what next owner can do.

If your item is COPY/NO TRANSFER, you should adjust the permissions for next owner this way:

So now, permissions for next owner in this script are: copy/no modify/no transfer

If your item is NO COPY/TRANSFER, you should adjust the permissions for next owner this way:

So now, permissions for next owner in this script are: no copy/no modify/transfer

REPEAT THIS for every other [Black Tulip] ASSET contained in your purchase!

Always use an alt (avatar) to check the permissions for next owner before selling or gifting your object. Read here for a detailed explanation about the basics of permissions in SL.


In case you've never done this, the following is an explanation of how to obtain the face number of a specific face, which you sure will need with mesh objects :-)

Right click your object and select Edit.

  • Click Select Face on the Edit window so that Select Face is checked.
  • Click on the face whose face number you want to know
  • Click at the same time the keys:


You will receive in local/nearby chat, or in a little popup/alert window, the number of the face you have selected.

If you continue editing your object, you may want to click back on Move, so you can normally move prims, etc.

NOTE: Some scripts also included an auxiliary script in their supplies, [Black Tulip] Side Numbering, which, when dropped into a primitive, puts on each side a number: the corresponding side number.

This script is a modification of the original idea, from Xylor Baysklef, so if we edit the prim and change its shape, or hollow, or path cut it, it recalculates the face numbers (which the original script didn't perform). You know when this happens because you'll see the numbers blinking for a moment while the script is recalculating the new values. After two seconds, approximately, you can be sure that you have the right values again. Said script isn't included anymore with new releases, for the first method is faster and will not re-texture the object with face numbers.

Of course, as a final choice, you can also use trial and error, or for more information check the documentation here:


The colors are expected to be written as a script would understand them.
To make it easy, there's an auxiliary script that will give you the color code of a prim face you click, [Black Tulip] Say Color Number.

Full explanation of said auxiliary script, and further notes about how to write colors in scripts (should you be interested) can be found in this blog post.


NOTE: Since this section is generic to all scripts having MODULE versions, in here we type:

[Black Tulip] ***Script Name*** [MODULE]

to refer to the [MODULE] version of the script [Black Tulip] ***Script Name*** (for example, if your script is [Black Tulip] Lamps Controller, then the module version is [Black Tulip] Lamps Controller [MODULE])


to refer to the code number that is specific to each script, and that is used in the llMessageLinked call, the BUTTON example line for AVSitter (and AVSitter 2) and the LINKMSG line for MLP.



to refer to the suggested name to be used on the button menu, to call the script.

There is one script which is a variation of the main script, but ready to integrate with other tools you have that include the ability to send messages:

[Black Tulip] ***Script Name*** [MODULE]

You should modify your existing system to add a new entry in your menus, so when you click an option to open the menus from this tool, you should add the following code in your script/system:

llMessageLinked(LINK_THIS, CODE_NUMBER, "message", toucherKey);

If you work with MLP, you can easily add a NAME_ON_MENU button in the main menu by adding the following line in the .MENUITEMS notecard:


fromMLP would be here the message passed in a llMessageLinked call.

Your box has a .MENUITEMS notecard with this included, so you can study how and where to add it.

If you work with AVSitter it is also easy to add a button in the main menu to open the script.
All you have to do is to include a line such as:


in your AVpos notecard.

Your box has an AVpos notecard with this included, so you can study how and where to add it.

NOTE: Yes, this will work with AVSitter 2.

If you're having a custom script done (or you're doing it yourself), "message" could be a text you show to the user in local chat, any text that could be useful to you (to give information to the user, extra parameters that you could need...)


If you've never worked with particles and don't know what all those parameters mean, you may check the free [Black Tulip] Your Very Basic Particle Templates package. Those scripts use a very similar naming like the notecard expects.

If you want to learn more about particles, you may also check the books devoted to the "Particles" topic at the store.
They will teach you what each of the properties mean and slowly lead you to a profound understanding of how to create any particles effect you may wish.

Any sample object for a script that allows for particle ability, also provides example effects defined in the configuration notecard that is included with the object. You can always use those effects as a reference to tweak/base to start working and create your own effects.

When the script handles more than one effect, then they are named particle1*, particle2*, etc. This notation simply means, that particle1* refers to any possible particle property, numbered with 1. For example, particle1Flags would refer to particleFlags for the effect #1. The notecard always tells, in a comment line, which effect is which. Also, keep in mind that each effect corresponds to a specific button label on the menu: if you need to create an effect which is quite different than what the button tells, remember you'll have to write this down in the documentation for your customers.

So, when a script handles more than one effect, we'll realize that all effects have the same structure, particle1*, particle2*, so we're going to refer to both indistinctly by just naming the properties particle* (for example, particleFlags will refer to particle1Flags, particle2Flags...)

If you have knowledge about particles, then you need to know that THREE parameters expect to be filled in a very specific way, explained now.

These parameters are, specifically:



This parameter refers to the FLAGS of the particle system (wind, follow velocity, etc.) The script expects that you assign to it a whole number, which will be the result of adding one or several numbers, depending on the flags that we want to activate, according to the following table:

PSYS_PART_BOUNCE_MASK               4
PSYS_PART_WIND_MASK                 8
PSYS_PART_RIBBON_MASK               1024

For example, if we want to activate PSYS_PART_INTERP_COLOR_MASK, PSYS_PART_BOUNCE_MASK and PSYS_PART_FOLLOW_VELOCITY_MASK, we would add the corresponding values, that is:

PSYS_PART_BOUNCE_MASK               4

so the value we would assign to the particleFlags parameter in the notecard would be 37, as follows:

particleFlags = 37


This parameter refers to the PATTERN of the particle system (drop, angle, etc.) The script expects that you assign to it a whole number, depending on the pattern you wish to choose (one and only one), according to the following table:

PSYS_SRC_PATTERN_DROP                   1
PSYS_SRC_PATTERN_ANGLE                  4


This one is added for completeness, but for now it's not being used.

All scripts with particle functionality allow with no problems the new PSYS_PART_RIBBON_MASK flag. Only the new ones have also parameters for the new particle properties, glow and blend functions (older scripts will be updated to include them). Refer to the official wiki documentation for the allowed values.


Because of some scripting limitations associated to the permissions system, it is mandatory that you drop the texture you wish to use in your particles effect into TWO prims:

  • In the "Content" tab of the prim you want emitting particles
  • In the "Content" tab of the prim containing your main script

It is VERY IMPORTANT that the textures have THE SAME NAME in the two primitives.

Exception: If your emitter is the script with the main script, then you do not need to have the texture duplicated.

Remember also to change permissions for next owner for your textures!


At Black Tulip, we want to help you become a good builder and make your builds as efficient as possible. Since the introduction of Mesh objects into Second Life, there is a new method of accounting for the impact of a build on the sim or parcel where the build is rezzed: Land Impact (LI). A major rolling restart performed to introducing Pathfinder in the grid, brought also several important changes to the LI algorithm which benefit us as builders, if used correctly. This new system allows you as a builder to reduce the burden your builds place on the Second Life servers.

To help you take advantage of this new system, follow the steps outlined below. Only if you have an old viewer you may need the auxiliary scripts included in a box.

Edit your build.

Go to the "Features" tab on the Edit window.

Select CONVEX HULL for the Physics Type. This will apply the property to the WHOLE LINKSET of your build. This may have consequences for the physical boundaries, but we will talk about that next.

Now, if you have any prims in your build that need to be phantom, select "Edit Linked Parts" (or "Edit Linked") and click one of the prims you wish to be phantom.

Then select for its Physics Type, NONE.

Repeat these steps until you have all of the phantom prims you want, to be in fact, phantom.


And the best of all is that if you use FEW scripts... The LI is not going to suffer!

NOTE: Convex Hull simplifies the geometry of the build and gets rid of the holes. If you find invisible walls preventing you from walking through your builds, perhaps this is the problem. It is possible to workaround that problem. Set the Convex Hull prim to None in those cases. Perhaps you will need to add a couple of boxes to your build, to emulate the surface, but if they are also set to Convex Hull, you will continue being benefited from the reduction in the LI. Non tortured boxes are the cheapest regular prims in terms of LI. Two boxes will account as LI: 1 in the new system.

IMPORTANT: As indicated above, if you're using an old viewer that doesn't show the "Physics Type" option in your "Edit" window, you will have to unpack the [Black Tulip] Physics Type Auxiliary Scripts box. The correspondence of actions as detailed above, and which script to use in each case, is:

Change the whole build to "Convex Hull"
Edit the object.
Drop the [Black Tulip] Change my Physics Type to CONVEX HULL - LINKSET script into the object.

Change one prim to "Convex Hull"
Edit the object. Click "Edit Linked Parts". Click the prim you want to set as Convex Hull.
Drop the [Black Tulip] Change my Physics Type to CONVEX HULL - Any Prim script into the prim.

Change the whole build to "Prim"
Edit the object.
Drop the [Black Tulip] Change my Physics Type to PRIM - LINKSET script into the object.

Change one prim to "Prim"
Edit the object. Click "Edit Linked Parts". Click the prim you want to set as PRIM.
Drop the [Black Tulip] Change my Physics Type to PRIM - Any Prim script into the object.

Change one CHILD prim to "None"
Edit the object. Click "Edit Linked Parts". Click the prim you want to set as None.
Drop the [Black Tulip] Change my Physics Type to NONE - Child Prim Only! script into the prim.

IMPORTANT: The ROOT prim CANNOT have the Physics Type set to NONE. So the script above is to be used only in child prims, never for the root.

Those scripts self-delete once they have performed its duty. Your object will become clean of these scripts and having the Physics Type changed.