Cfg Tool

THE CONFIGURATION TOOL, IN DETAIL



While following the "Step-by-step Guide" section of this documentation, we've seen which options to use in the configuration tool in order to set up our doors. This tool has some more convenient options that will help you while you prepare your doors, or if you need to restore the information from an already made build, in order to modify the setup.


THE "[Black Tulip] Configure Doors v2 ~CFG~" NOTECARD FORMAT


When we open the supplied "[Black Tulip] Configure Doors v2 ~CFG~" notecard, we find the following text, which is ready for you to begin with the "Step-by-step Guide" and set up the sample:

# [Black Tulip] Configure Doors v2 ~CFG~
# Add a line per door name

DoorName = Main Door
DoorName = Kitchen Door

# Add a line per allowed avatar - Do NOT use display names.
LEGACY NAMES only - http://wiki.secondlife.com/wiki/Category:LSL_Legacy_Name

First: Lines beginning with # are comments, and thus ignored by the configuration tool. You can use them to keep your comments about the build, or to add any relevant information that might help you.

As we explained, prims that will be considered as doors must have a distinctive NAME, and doors that are supposed to open and close together will have the same NAME. Since our doors may be composed of one or more prims, when several prims are part of the door, we'll name all of them the same, so that the script can recognize them as a group to move them in a single block.

The supplied notecard tells the "[Black Tulip] Configure Doors v2" script that there are two groups of prims defining our doors, here:

DoorName = Main Door
DoorName = Kitchen Door

One is the group composed of all prims named: Main Door
The other is the group composed of all prims named: Kitchen Door

So, as we can see, DoorName is a keyword for the notecard, and after the = sign, we write the NAME we've given to the prims that belong to a group. We write one of these DoorName = lines PER GROUP OF PRIMS. Not per prim involved. The door has seven prims? ONLY ONE LINE in the notecard with the common name they all have.

Let's reinforce once again these points:

  • IMPORTANT: Be careful when writing these names, as the script will look for them in a case sensitive way.
    This means that "Main Door", "Main door" and "main door" are *different* names.
  • IMPORTANT: Do not use leading or trailing spaces for your name.
    The script will omit any leading/trailing spaces in the name, which will cause to ignore any relevant prim using them.
  • IMPORTANT: Do not use names that are too long. The configuration tool needs to rename the prims once you're done.
    If your names hit the maximum length allowed, the controller will not work correctly. Keep names under 60 characters.

Once the definition of the prim groups is finished, we find a comment line saying:

# Add a line per allowed avatar - Do NOT use display names.
LEGACY NAMES only - http://wiki.secondlife.com/wiki/Category:LSL_Legacy_Name

Below this comment line we would write all the LEGACY NAMES (one user name per line) of avatars that may also use this configuration tool when the access mode has been set to "White List". This is explained under the "EXTRAS: ACCESS" section of this page. To sum it up, the configuration tool expects in the corresponding configuration notecard:

  • Names of the prims that belong to a door
  • Legacy names of avatars we grant access to use the configuration tool


MAIN OPTIONS


As we explained, once we have our "[Black Tulip] Configure Doors v2 ~CFG~" notecard ready, we have to:

  • Edit our build (DO NOT TICK "Edit Linked Parts")
  • Drop the "[Black Tulip] Configure Doors v2 ~CFG~" notecard in the "Content" tab.
  • Drop the "[Black Tulip] Configure Doors v2" script in the "Content" tab.

The script then notifies us when the configuration notecard is read. At this moment, by clicking our build, we get a menu with the following options:

    Save Closed     Close All       Restore Data
    Save Open       Open All        Output Data
    CONFIRM!        Play            *RESET*
    ---             Memory Rep      Access

Let's study now, in detail, what each of those options performs.

NOTE: The listen for this menu is set to TEN MINUTES. This means that from the moment you bring the menu up, you have up to ten minutes to click on a button to select an option. After this time, the menu expires and you will have to click to bring it up again. The reason of existing this timeout is to avoid having a permanently open listen, which would only contribute to server side lag.


MAIN OPTIONS: SAVE CLOSED, CLOSE ALL


[Save Closed]
For every primitive belonging to a door, according to their names and correct setup of the "[Black Tulip] Configure Doors v2 ~CFG~" notecard, when "Save Closed" is clicked, the following information is stored as a part of the "Closed State" of the doors:

  • Position of each primitive
  • Rotation of each primitive
  • Size of each primitive
  • Sculpt Prim (Please check further notes on sculpts in the "SCULPT PRIMS: WHAT ABOUT THEM?" section)

If the primitive is not a part of a door, no information at all is recorded about it. The memory usage involves ONLY the door primitives.

If there was a previously recorded closed state, the tool will overwrite it WITHOUT a warning.

[Close All]
This will CHANGE all the prims to the stored closed state. This means that the:
  • Position
  • Rotation
  • Size
  • Sculpt
values of each door prim will be changed to the stored ones when clicking "Save Closed".

If no values have been recorded for the closed state, the script will output a message in your local chat window, warning you about this circumstance.


MAIN OPTIONS: SAVE OPEN, OPEN ALL


[Save Open]
For every primitive belonging to a door, according to their names and correct setup of the "[Black Tulip] Configure Doors v2 ~CFG~" notecard, when "Save Open" is clicked, the following information is stored as a part of the "Open State" of the doors:

  • Position of each primitive
  • Rotation of each primitive
  • Size of each primitive
  • Sculpt Prim (Please check further notes on sculpts in the "SCULPT PRIMS: WHAT ABOUT THEM?" section)

If the primitive is not a part of a door, no information at all is recorded about it. The memory usage involves ONLY the door primitives.

If there was a previously recorded open state, the tool will overwrite it WITHOUT a warning.

[Open All]
This will CHANGE all the prims to the stored open state. This means that the:

  • Position
  • Rotation
  • Size
  • Sculpt
values of each door prim will be changed to the stored ones when clicking "Save Open". If no values have been recorded for the open state, the script will output a message in your local chat window, warning you about this circumstance.


MAIN OPTIONS: PLAY, OUTPUT DATA, CONFIRM!


[Play]
Once we have stored both the closed and open states, by clicking this option, the tool enters in a loop where it plays the closed, open, closed, open... states, every three seconds. While in this loop, clicking the object makes the looping stop. The purpose is so that we can zoom and focus in each group of doors in a large, complex build, and see them opening and closing, so we're sure that they are in the positions we want.

NOTE: If there are unsaved states, the script will remind us and won't enter into the loop, because there's not enough data saved to set the doors.

[Output Data]
This will output all the relevant data to be copied into the "[Black Tulip] Door Controller v2 ~CFG~" notecard for the current saved open and closed states. The purpose of this function is so you can make a backup of your work at any time, not having to use "CONFIRM!", for the latter has some more consequences that we discuss next, which aren't suited for just making a backup.

[CONFIRM!]
When everything is set as you desire, this is the option you should click.

Same as when clicking "Output Data", this will output all the relevant data to be copied into the "[Black Tulip] Door Controller v2 ~CFG~" notecard for the current saved open and closed states, and it will perform some more actions:
  • To prevent mistakes, it will DELETE from your build both the "[Black Tulip] Configure Doors v2 ~CFG~" and the "[Black Tulip] Configure Doors v2" script
  • It RENAMES the door prims in a certain way

For example, if you're using the provided sample object, you will notice that the prims are renamed this way:

Main Door - Now we have the two prims named as follows:
    Main Door#1
    Main Door#2

Kitchen Door - Now we have the one prim named as follows:
    Kitchen Door#1

Of course, this means that AFTER using the "CONFIRM!" function we will not be able to use our build as-is with our existent "[Black Tulip] Configure Doors v2 ~CFG~" notecard, since the prim names have changed.

However, here is the good news: we will be able to RESTORE the information saved in the "[Black Tulip] Door Controller v2 ~CFG~" final notecard. This is explained in the "EXTRAS: MISCELLANEOUS FUNCTIONS" section. (Remember in any case to make a copy before you start with the whole configuration tool!)


EXTRAS

The configuration tool has a few more options accessible from the main menu:

    [Memory Rep]
    [Restore Data]
    [*RESET*]
    [Access]

They will allow us to restore a build from backup data, change the access mode to the tools, tell how much free memory is available at any time, and the ability of resetting and thus starting from the beginning again, clearing all data.


EXTRAS: ACCESS MODE


[Access]
This opens the "Access" submenu, which contains the following options:

    Everybody   Owner Only      Group
    ^Up         White List      Close

It's thanks to this menu that we can work with this configuration tool... or others can work with the configuration tool, and obtain the required output, play the closed/open states, confirm... The "Access" menu can be accessed only by the owner, and defines what kind of "group work" we desire.

[Everybody]
This makes it so that everybody is able to access the menu of the configuration tool and use all the options with the exception of "Access" and "*RESET*"

[Owner Only]
Only the owner of the object is able to operate the menu. Select this one when you want to work alone, without others accessing the menu.

[Group]
Only people having active the same group the build has, may access the menu.

[White List]
Only people in the white list section of the "[Black Tulip] Configure Doors v2 ~CFG~" notecard may use the menu.

[^Up]
Goes back to the main menu

[Close]
Closes the menu and the listen

Default access mode is "Owner Only".

Remember that the "[Black Tulip] Configure Doors v2 ~CFG~" notecard has one comment line indicating:

# Add a line per allowed avatar - Do NOT use display names. LEGACY NAMES only - http://wiki.secondlife.com/wiki/Category:LSL_Legacy_Name

It is below this comment line where we would write all the LEGACY NAMES (one user name per line) of avatars that may also use this configuration tool when the access mode has been set to "White List".

What is a legacy name?
It's the avatar's name under the format:
    FirstName LastName

Before October 2010, when creating an account, we had the choice of writing our first name and then selecting a last name from a list. For example, I chose the name "Auryn" and the last name "Beorn", which makes my LEGACY NAME to be "Auryn Beorn".

After that, residents couldn't choose a last name anymore, so they only were able to choose a first name. Internally, the last name "Resident" is added. For example, my alt, created after October 2010, has the name "Auryn" and that's it, for I couldn't pick a last name for her. This means that her LEGACY NAME is "Auryn Resident".

NOTE: Legacy names are CASE SENSITIVE. Write them exactly as you see them for the notecard.


EXTRAS: MISCELLANEOUS FUNCTIONS


[Memory Rep]
This outputs in local/nearby chat a line informing us of the available memory for the script. Always keep an eye on this if your build has a large amount of prims that should be doors!

[Restore Data]
As a new and quite handy feature in this v2 version, by clicking this option, we can MODIFY AN EXISTING BUILD we may have completed and want now to rework.

As has been explained earlier, when we hit "CONFIRM!", the configuration tool outputs in chat all the data we need, and renames our prims in a certain way. This means that if we attempt to use the configuration tool again, we should manually rename the prims back... but why do this? The configuration tool can do this for us, and what's better, allow us to continue working from the saved closed/open states, which is extremely useful if we want to modify a finished build after open/closed states have been set.

In order to have the "Restore Data" function work, we have to do this:

  • Rez a finished build after the prims have been renamed
  • Edit it and delete the "[Black Tulip] Door Controller v2" *IF* it's in the build
  • If the "[Black Tulip] Door Controller v2 ~CFG~" notecard is in the build, DO NOT DELETE IT!
  • If the "[Black Tulip] Door Controller v2 ~CFG~" notecard is missing, then drop it in the build (of course, the one with the data of that specific build!)
  • Now drop the "[Black Tulip] Configure Doors v2 ~CFG~" notecard. It doesn't matter if the prim names don't match.
  • Drop the "[Black Tulip] Configure Doors v2" script
  • Click to bring the menu up
  • Select "Restore Data"

And that's it: the script has now RESTORED the open/closed states, renamed the prims back, and you can continue working if, for example, after confirming a build, you realize you wanted to change something.

After doing this, we continue working as normally, and once done, we again click "CONFIRM!"

[*RESET*]
This option is available only for the owner, and allows him/her to reset the configuration tool. Beware that all the recorded data will be lost with NO OUTPUT! This function asks for confirmation: make sure you really want to reset!


SCULPT PRIMS: WHAT ABOUT THEM?


As we'll see in the «THE "[Black Tulip] Door Controller v2 ~CFG~" NOTECARD FORMAT, IN DETAIL» section, "INDIVIDUAL PRIM PARAMETERS" subsection, *when* sculpt prim data is recorded, it is output as the last field per each prim being a sculpt prim, having the format:

    UUID-of-the-sculpt-prim-here,code_number_for_the_stitching_type

We know, though, that MANY sculpt creators don't allow this in their licenses. When a sculpt creator says that you're not allowed to distribute their maps in full permissions state, that INCLUDES the following restriction: the UUID should never be distributed either. Why? Because all you need is access to the UUID to be able to use the sculpt map EVEN IF YOU DON'T HAVE SUCH MAP IN YOUR INVENTORY. Scripts can easily use sculpt maps by just knowing the UUID.

This means that the UUID written in the notecard, in many cases, will NOT abide by the license of the maps we bought, and thus, we shouldn't use them.

If we were talking about sounds, for example, it would suffice to just drop a copy/no modify/no transfer sound (for example) and copy the sound clip *name* in the notecard. In the case of sculpt maps, a line with the format:

name_of_the_sculpt_map_dropped_with_the_script_in_contents,code_number_for_the_stitching_type

would be the required data, should we prefer to drop the sculpt map as a texture in the build.

But this will not work with sculpt maps either! Because of permissions restrictions, if we drop for example a no transfer sculpt map in the build, and name it instead of saying the UUID, this will only raise an exception.

Then why even bother in adding this feature?

Because you can do as you wish with your own created sculpt maps. If you create sculpt maps and don't mind the UUIDs being visible, this IS a useful feature. It is in this case when, instead of using the "[Black Tulip] Configure Doors v2" script to configure your build, you use the "[Black Tulip] Configure Doors v2 + SCULPTS" one.

NOTE: This "[Black Tulip] Configure Doors v2 + SCULPTS" script will save sculpt prim data for ANY PRIM that is sculpted. You may want only a few of them. You should manually REMOVE the sculpt data from the prims that are sculpts, but that are NOT meant to swap the sculpt map. Or you can use the tip explained under the "ADVANCED USE TIPS" section.
Subscribe to: Posts (Atom)