User Guide for Troy McConaghy's Holo-Emitter System

What is This?

This is the User Guide for a holo-emitter system that works in the virtual world Second Life (and it should also work in OpenSimulator). The system is a set of scripts written in Linden Scripting Language (LSL). Those scripts are open source (GPL2) so you can change them to suit your needs. You can get them from a variety of places:

• The Second Life Marketplace (for zero Linden dollars). The scripts will be delivered to your SL account in a box, which will appear in your SL inventory. If you rez the box and click it, it will give you a folder containing the scripts.
• A Git repository on GitHub named ttmc/HoloEmitterSystem.

Introduction

In Star Trek, there's something called a holodeck, which is a room where you can simulate just about anything, from a beach resort to a spaceship. You just tell the computer what you want and it appears. The things that appear are holograms and they are generated by so-called holo-emitters.

I made something similar for the virtual world Second Life (and it should also work in OpenSimulator). You click the holo-emitter, it gives you a menu of scenes, you pick a scene and it appears. Simple.

I made it so that the scene can be spread out over an entire sim. That way, you could easily change the sim (e.g. from a city to a meadow) to suit your mood. You could also use the holo-emitter system to move scenes from one part of a sim to another part, because the objects in a scene move relative to the holo-emitter. You'd just pack up the scene at its original location, move the holo-emitter, and rez the scene again at the new location.

I hope this guide is enough to get you started. I assume a certain amount of familiarity with things like inventory, permissions, and building.

The Holo-Emitter System

There are four scripts that work together to make the holo-emitter system work. They are named:

Holo-Emitter Script

Scene-Container Script

Object Script A

Object Script B

and there may be a version number (like “v1.0”) tacked onto each name. Please make sure you have all four scripts or the system won't work.

Basics

The holo-emitter (an object) contains a set of scene-containers (also objects). Each scene-container contains a set of objects (the objects that make up a scene). To use my holo-emitter system, your scene must be made up of objects that you can modify and copy. To repeat: you must be able to modify and copy every object in your scenes. (You don't need to be able to sell/transfer though, unless you want to give or sell the loaded holo-emitter to someone else in the future.)

When you click the holo-emitter, it looks at its contents (scene-containers) and uses that to give you a menu of scenes bases on the names of those scene-containers. When you select a particular scene, the holo-emitter rezzes that scene-container. The scene-container then rezzes all objects in its contents and then vanishes. The contents fly to their proper position then stop. Voila!

Now let's go through the steps to pack a scene into a scene-container object and then put the scene-container object into a holo-emitter object.

Packing Up a Scene

1. Rez an object which will serve as your holo-emitter. Any object will do, provided that you can modify it.
2. You may want to change the name of your holo-emitter object to “Holo-Emitter” or something like that.
3. Copy the script named “Holo-Emitter Script” into your holo-emitter object's contents (by dragging it from your inventory into the contents of your holo-emitter object).
4. You could have built your scene (a set of objects in the same sim as your holo-emitter object) before Step 1, but if you didn't then build it now.
5. You should link together as many of the objects in your scene as you can. This will make your scene rez faster later on.
6. For each object in your scene, copy “Object Script A” into the object's contents, and copy “Object Script B” into the object's contents.
7. For each object in your scene, take the object into your inventory (by right-clicking it and selecting “Take”). NOTE: Don't select multiple objects and “Take” them all into your inventory at once; take them into your inventory one at a time.
8. Rez an object which will serve as the scene-container for your scene. Any object will do, provided that you can modify it.
9. Rename the scene-container object “Scene1” or something like that. Keep the name short (10 characters or fewer), because it will be used by the holo-emitter when giving you the menu of scenes later on.
10. Make sure the scene-container object has modify and copy permissions (by checking those boxes on the General tab in the Edit window). [Note: I'm not sure if this step is necessary all the time. Use your judgment.]
11. Copy the script named “Scene-Container Script” from your inventory into the contents of the scene-container object.
12. For each scene object in your inventory, copy the object into the contents of the scene-container object (by dragging it from your inventory into the scene-container object's contents).
13. CRITICAL STEP: While editing the scene-container object, go to the General tab in the Edit window and change the Description to “live” (without the quotes). This activates the scene-container so that when it gets rezzed, it automatically rezzes all its contents and then deletes itself. [Note: You can make it stop doing that by changing the Description to something else.]
14. Take the scene-container object into your inventory.
15. Copy the scene-container object from your inventory into the holo-emitter object.

That's all. Next time you click the holo-emitter object, it will automatically detect the new scene-container object and add it to the menu of scenes.

How to Add/Remove Objects from a Scene-Container

1. Copy the scene-container object from the holo-emitter's contents to your inventory.
2. Right-click on the scene-container object in your inventory and select “Properties”.
3. Change the Description to something other than “live”.
4. Rez the scene-container object.
5. Edit the scene-container object and go to the Contents tab.
6. To remove objects, just right-click them in the Contents and select Delete.
7. To add objects, do as in Steps 6, 7 and 12 from the previous set of instructions.
8. Take the scene-container object back into your inventory. Maybe give it a new name to help you keep organized. (To do that, right-click it in your inventory and select Rename.)
9. Delete the old scene-container object from the holo-emitter's contents (Right-click it then select Delete).
10. Copy the new scene-container object to the holo-emitter's contents.

Important Notes

Issues with using the holo-emitter system on group-owned land

One user reported that she could use the system to rez scenes, and so could others, but as soon as she logged out, others couldn't rez scenes anymore. It would just fail silently. The emitter was on a parcel deeded to a group (i.e. group-owned land). We found that the problem got solved by 1) deeding the holo-emitter object to the landowning group and 2) checking the box in “Top Menu – World – About Land – Options” to allow group members to “Create Objects”.

Limitations on Number of Objects or Scenes

Scenes can have any number of objects. Of course, the more objects there are in a scene, the longer it will take for it to rez. (Note: there is a built-in, hardwired delay between the rezzing of each object in a scene.) A holo-emitter can also hold any number of scene-container objects, but only the first eleven will show up in the blue pop-up dialog box when you click the holo-emitter (and the twelfth button will always say 'Clear'). Feel free to change the holo-emitter script so that more scenes could be chosen (e.g. maybe change it to have a hierarchical menu or use chat commands instead).

Object centers can't go underground

If you move the holo-emitter so that an object in a scene at the new location would have its center under the ground, then that object will not go to their correct position (relative to the holo-emitter) – the object's center will go to a point on the ground near the correct position instead. This happens because an object can't move itself so that its center is below ground level.

Object centers can't go into other sims

If you move the holo-emitter so that an object in a scene at the new location would have its center outside the current sim, then the object will try to move itself there, but it will probably fail and end up in your “Lost And Found” folder (in your inventory).

Watch out if there are two or more holo-emitters in the same sim

If you have two or more holo-emitters in the same sim, then there will be crosstalk and it won't be pretty! That doesn't mean it's impossible. To have two or more holo-emitters in the same sim, you just need to edit the “Global constants” section at the start of each script (for those that have one). Change the channel numbers and make sure they are consistent (e.g. HE_channel must have the same value in all scripts). A copy of the Global constants section of the “Holo-Emitter Script” is shown below:

// Global constants
// These should be changed if there are any other holo-emitters 
// in the sim, both here and in all other scripts
integer delete_channel = -3423489;
integer menu_channel   = -1847395;
integer HE_channel     = -9385735;

Remove Object Script B to make an object permanent

If you don't want an object in a scene to vanish when you select “Clear” or when a new scene is chosen, then remove Object Script B from the object's inventory. Object Script B is pretty simple: it just listens for a special command (on the delete_channel) to tell it to delete the object in which it is contained.

Copyright and License

This user guide is copyright © 2012 Troy McConaghy. It is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. (The scripts and software code for the holo-emitter system are under a separate license. See the code itself for more information.)