Theme toolbox

Transfers and remapping

Previous section < Installation and main menu

This section discusses the operations available through the "Transfers" sub-menu (pictured below). You can get to this specific sub-menu by clicking the relevant button in the Theme toolbox's main menu. These operations actually fall into 2 categories:

transfers and remapping: involve reading a (notecard or LSD) theme, updating it if required, optionally remapping the link numbers, and reencode it possibly on a different destination (notecard contents or LSD);
LSD operations: listing the LSD themes, deleting a theme, resetting the LSD storage and getting information about the available storage.

The transfers sub-menu

The Transfer process

In this context "transfer" means reading a theme, decoding it and reencoding it to a different destination. In the process, it is always upgraded, if required, to the latest version supported by the Theme-O-Matic, for example to support new properties that did not exist at the time the theme was created.

Both source and destination themes may either be notecard of LSD themes. Since scripts cannot create notecards, if the destination is a notecard then you will have to copy the lines generated in the chat just like when the themes are created during preparation phase. LSD themes, on the other hand, require no copy or paste operations on your part.

To make a theme transfer:

select a source theme by clicking the SourceTheme button. A new menu will open to allow you to select a notecard (or manually enter an UUID) or an LSD theme, as described previously.
Select a destination theme by clicking the Dest theme button. Again a menu will open to allow you to select either notecard contents (to be copied into a new notecard), an existing LSD theme or a new LSD theme.
If you want remapping to happen in the process then click the Remapping button (it has a checkmark if it's active), but first read the explanations below.
Click the PROCESS button to actually start the transfer, and pay attention to the messages in local chat.

Note: the source theme and destination name cannot be the same LSD theme.

LSD operations

The remaining buttons on this menu enable you to perform common LSD operations. They are identical to what is possible in the preparation phase:

List LSD: show the list of LSD themes inside this object,
LSD Available: shows the amount of free LSD storage, in bytes,
DELETE LSD: the (source) LSD theme will be erased. Nothing happens if the source theme is a notecard theme and not an LSD theme. To remove a notecard theme just delete it from the object's inventory!
RESET LSD!: completely reset the LSD storage, erasing any LSD themes and other data that may be in use by other scripts.

Since the last two operations are potentially destructive, a confirmation dialog box will be shown before the action takes place.

Theme remapping

Why

When you create a theme, information about which property has to be applied on which prim (and potentially face) is recorded and encoded. The keyword here is "which prim": all prims are assigned a number (more details about this on the SL wiki) starting from 1 (for the root prim) up to the number of prims composing the object, and this "link number" is used by themes.

The problem is that the link number is highly dependent on how the object is built and modified. If you unlink a prim, or add a new prim, then all link numbers get changed in a practically unpredictable way! This of course totally breaks themes as the prim and face properties are bound to be applied on the wrong prims.

As of v2.2 of the Theme-O-Matic the Theme toolbox now enables you to fix this problem by offering a mechanism to re-encode your themes with the new corrected link numbers. To do that we have to establish a correspondence (called a mapping) between the original object (used for the theme creation) and the modified object that had its prims added or removed.

The Map maker script

The mapping notecard can easily be created by using the Map Maker script inside the original object. Just equip your original object, as it was before you made any modification to its prims. Do not use any other script inside it. The Map Maker script will display a very simple menu system where you can choose one mapping type ("direct" or "reference") and generate the mapping.

Map maker menu : select the mapping type (direct or reference) and then click "Generate!"

The resulting mapping

You get to choose between two mapping types:

Direct mapping: the correspondence is made between the link numbers inside the original object (source) and inside the modified object (target). The Map maker will prepare the notecard only with the source link numbers, and you will have to manually enter the target link numbers (use -1 as target prim if said prim should be removed from the theme).
Reference mapping: here the word "reference" means that a reference will be constructed from each prim name and description. Later when remapping the theme the Theme Processor script (part of the Theme Toolbox package) will look for the same references in the modified object and construct the actual mapping from them. This is a very good solution that does not require you to manually edit the mapping notecard. The only minor drawback is that the reference (combination of prim name and description) is unique for every prim among the original and modified objects. In other words, you should give a meaningful name and/or description to each of your prims (do not leave the default "Object" name).

Since getting the link numbers from the viewer has been a rather unreliable operation, Reference mapping is the advised method, and it is used by default. If the uniqueness requirement for references is not satisfied the script will warn you when generating the mapping notecard.

When you have selected the desired mapping type and met the requirements, just click the Generate! button to create the notecard contents. The resulting lines will look like the following pictures. Copy them to a new notecard in your inventory, named ".mapping" (do not forget the leading dot).

A direct mapping

This is the list of prims in the source object. You have to fill in (after the "=>" arrows) the corresponding link numbers in the target object

A reference mapping

It contains the list of prims in the source object associated with a reference made of the prim's name and description. You do not need to manually alter this notecard.

Worth noting

If you opted for a direct mapping, do not forget to fill in the actual link numbers in the target object. If a prim used to exist in the source object but was removed from the target object, you can use -1 as the link number to signify that properties affecting this prim should be removed when remapping the theme. For example, a line like

4=>-1

means that prim #4 in the source object no longer exists in the target object.

This is entirely automatic if you opted for the reference mapping.

Remapping themes, step-by-step

Once you have your mapping notecard ready you can just forget about the Map maker and the source object. Everything else happens in the target object. Here are step-by-step instructions. FIrst of all, of course, always keep a safe copy in your inventory. Mistakes are easily made!

Equip your target object with your ".mapping" notecard, the Theme toolbox and Theme processor scripts, and all the theme notecards you plan to remap.
Click the object to open the main menu, then go to the Transfers sub-menu.
Select the source theme (notecard or LSD) as described above,
Select the destination theme (notecard contents, existing or new LSD theme),
Click the Remapping button to activate it (a checkmark √ shows it is active),
Click the PROCESS button to start the transfer and remapping.

Repeat steps 2 to 6 for all the themes you want to remap. Then you can test them by using, for example, the buttons from the main menu.