Sunday, February 15, 2015

Script: Theme Texture Change - Materials & Basic

[Black Tulip] Theme Texture Change
&
[Black Tulip] Theme Texture Change - Materials
(Scripts for Designers)

(c) 2015 Auryn Beorn


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.

Because the materials and non-materials version of this script are so similar to setup, we'll document both in this page, referring to differences when they exist.

TABLE OF CONTENTS



FEATURES


  • Define as many texture themes as you need, grouped in the categories you need. They are stored in notecards, but UUIDs do not show in the notecards.
  • Menu timeout to reduce lag - no open listeners after timeout (0.001 ms script time when idle)
  • Final user can change access to owner only/everybody/group
  • Menu can be integrated into tools such as MLPv2, AVsitter... (AVsitter version 2 works too!)


SET UP: WHAT SCRIPT TO USE?


There are two scripts contained in your folder:

Materials version:

[Black Tulip] Theme Texture Change - Materials
[Black Tulip] Theme Texture Change - Materials [MODULE]

Non-Materials version:

[Black Tulip] Theme Texture Change
[Black Tulip] Theme Texture Change [MODULE]

We need to use ONLY ONE of them in a given product.

Which one? How to choose?

The [MODULE] version, as explained in the THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT section, will allow you to use this script integrated with other scripts that allow sending linked messages, such as the Multi Love Pose (MLP) or AVSitter for multiavatar, multianimation devices.

So, depending on what we need, we'll use the following script as main one:

Normal use - We want the menu to show when the object is clicked:
[Black Tulip] Theme Texture Change - Materials (Materials version)
[Black Tulip] Theme Texture Change (Non materials version)

The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] Theme Texture Change - Materials [MODULE] (Materials version)
[Black Tulip] Theme Texture Change [MODULE] (Non materials version)

Once we've chosen the right main script, we have to set some descriptions in the primitives of the object, following the instructions below.


SETUP: CHANGE PERMISSIONS FOR NEXT OWNER


Check the following section on this page, knowing that each [Black Tulip] ASSET refers to the following scripts:

Materials version:

[Black Tulip] Theme Texture Change - Materials
[Black Tulip] Theme Texture Change - Materials [MODULE]

Non-Materials version:

[Black Tulip] Theme Texture Change
[Black Tulip] Theme Texture Change [MODULE]


SETUP: CREATING TEXTURE THEMES


You will need a full permissions object for this. That's why no sample has been included. Rez your full permissions object (permissions for next owner can and should be different!) If it looks like plywood at this moment, that is okay. We will make the screenshots starting with a plywood object too :-)


Your object may be just one prim, or several linked prims. It matters not. This does matter, though: those prims you want to be affected by the texture change routine... Change their description.

How should we change the description?

Let's look at the example object to get the first idea:


Pay attention to the description:

t;bed

That is, t; and then, bed. This means, t; indicates that the prim will react to texture changes. We can write the name we wish after that, but it's recommended to keep it short, and not to leave leading or trailing spaces around it. Also, do not repeat texts after t; If one prim has bed, then other prims shouldn't have bed as well.

(NOTE: Some of my scripts allow for multiple parts in the descriptions, separated by the # character. You can use the texture change script together with them, but the t; part needs to be the first one, always.)

Once all our prims have their description changed, following this simple rule, let's go for the next steps.

Edit the object, and drop the [Black Tulip] Theme Creator - Materials - AUXILIARY TOOL script in it ([Black Tulip] Theme Creator - AUXILIARY TOOL for the non-materials version).

Next, texture your object as you prefer.


and click for a menu.

Materials version shows:


And non materials version shows:


The difference is that the materials version shows an extra Create NoAlpha button. We'll explain what that extra button is for once we're familiar with the procedure.

Let's just click Create! for now.

This tells things in local (nearby) chat:


(The materials version outputs more text than the non materials version, for it adds all the normal, specular and alpha mode information.)

What do we do with those lines?

We save them in a notecard, as tidy as we can. We can leave the timestamp lines if we want, but the notecard will read faster if we remove them.

IMPORTANT NOTE: Because of deciding on a different base name for the notecards and forgetting to change that in the script, the local chat says something about a BT_THEME notecard. That's not correct. It should say something about a BT_TEXTURE notecard. This typo will be corrected in future versions, meanwhile, please keep this mind, so you're not confused about the notecard name! The correct base name is BT_TEXTURE. Apologies for this typo.

Notecard with timestamps:


Notecard without timestaps:


IMPORTANT: If you leave the timestamp line without the opening bracket delimiting the time, the textures will not be read correctly. For example, if instead of this timestamp line:

[19:19:19] My Sample Object to test scripts:

we remove the initial [ character and leave something like this (which can happen easily when copying/pasting from chat):

19:19:19] My Sample Object to test scripts:

or this:

My Sample Object to test scripts:

the textures will not be read correctly.

If unsure, then remove entirely the timestamp line and leave only the texture data, as shown on the above "Notecard without timestamps" picture.


Does this notecard need a specific name? It does. It needs to begin, always, by BT_TEXTURE. Then we write : and then, the name we want for our theme. For example, we can call this notecard BT_TEXTURE:Bed 0. That means, Bed 0 will show up as a menu option, once we're done.

If we change our mind about how this theme should look like, all we have to do is change the texturing, and again, click the Create! button, then replace the notecard content.

What if we add prims later, but that don't have any t; parts in their description? Then you're good to go. What if those prims have any t; parts in their descriptions? We texture and again click Create!, then replace the notecard content.

Let's create another theme, this time, calling the notecard, BT_TEXTURE:Bed 1, for a Bed 1 option on the menu.


With these two theme notecards, we're ready to try out our texture change script! Click one more time for the menu, select [*DELETE*] and then confirm:


The object is now ready for the theme texture change script.


PREPARING OUR FINISHED OBJECT


Now that we've deleted the auxiliary script, we begin by editing our object and dropping the theme notecards in it:


Then we add the corresponding script to the object (depending on if Materials version, or not, if [MODULE], or not):


And when we click on the object, there they show: the buttons that will apply the stored texture choices, when clicked.


Easy!

NOTE: Actually, we can drop the theme texture notecards at any time, without having to reset the script. The script will silently reload the list to rebuild the menus.


TEXTURE CHANGE OPTIONS, IN DETAIL


Now that we've seen how easy it is to create themes and have them added, let's explore in detail what else we can do, and how.

The first thing we're going to learn is how to create submenus of options.

The allowed notecard names for this script should begin by BT_TEXTURE, then followed by the : character, as we've already seen when creating our first theme notecard. Then we write something, and that something shows up as a menu button.

For example, we've written:

BT_TEXTURE:Bed 0
BT_TEXTURE:Bed 1

and that made for two buttons to show on the main menu: Bed 0 and Bed 1

If we're creating more themes for the complete bed, but then we want also themes only for the bed cover, we may want to have these Bed 0, Bed 1, etc... under a Bed submenu. How do we do that?

Simply renaming the notecards to this:

BT_TEXTURE:Bed:Bed 0
BT_TEXTURE:Bed:Bed 1

will make for it.

Notice how now we have a Bed submenu:


and when we click, the Bed 0 and Bed 1 options show. The menu also tells us that we're inside the Bed submenu:


In order to give clues to our users, as to whether they will be applying a final texture, or will be entering a submenu, we can rename the notecards this way:

BT_TEXTURE:Bed *:Bed 0
BT_TEXTURE:Bed *:Bed 1

and have the buttons show this way (I've added two more theme notecards to show the difference):


We can create nested submenus by simply separating the names with the : character. This implies, the : will never be part of a menu/theme name. We're limited into how many submenu levels we can use by the notecard length name, which is 63. If we use short names, we'll be able to nest more submenus than if we use long names.


Now, let's suppose that we want to create a texture theme, but we would like that some faces of the involved prims remain unchanged.

Just drop the included [Black Tulip] Theme Texture Change - Texture to Ignore texture on the faces that should not be included as part of a theme. Click on Create!, and notice how the information for those faces isn't output, then save the content to a theme notecard.


When we use this theme, the cover won't change its texture. We can exclude as many faces as we need.

Remember this: Only those prims having their description to begin by t; and your text choice, will be acknowledged as prims that will have their texture changing. The other prims will not be a part of the themes.

We can recreate themes at any time. We can link, unlink, recreate in case of doubt... The auxiliary tool is pretty flexible, thanks to the t; part of the description of the involved prims.


And, to finish with the extra options... What's the Create NoAlpha button for, in the materials auxiliary tool?

This option is to help bypassing a current bug in the viewers. When ALM (Advanced Lighting Mode) is on, because of this bug, we may notice that non-alpha textures will show as alpha anyway, having the annoying Open GL alpha bug to happen (this alpha bug isn't related to SL but to the used graphics library, Open GL).

If all of your textures being part of a theme are completely flat, then use this option, Create NoAlpha, instead of Create! It will cause for a specific value to be set to 0.

If we have a mix of alpha and non alpha textures, and/or transparency settings, then use Create!, and make sure of setting to 0 a specific value of the texture lines corresponding to that texture and face. If you don't know how to obtain a face number, then click here.

Observe the highlighted number 1 almost at the end of the two lines that have all the information for that texture face, having two | characters around. When your texture is flat, when it is not alpha, that 1 should be set to 0 instead.


We will have to do this manually if our object presents a combination of alpha-non alpha textures and/or transparency options. The bug may not necessarily happen with all the textures, but it's better to be aware of this and how to bypass it.

This, of course, affects only to the materials version. The non-materials version doesn't even have the Create NoAlpha button.


SETUP: THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT

Check the following section on this page, knowing that:

[Black Tulip] ***Script Name*** [MODULE] refers to [Black Tulip] Theme Texture Change - Materials [MODULE] (Materials version) or [Black Tulip] Theme Texture Change [MODULE] (Non materials version)
CODE_NUMBER is -1864098
NAME_ON_MENU is Texture

AVSitter line looks like: BUTTON Texture|-1864098
MLP line looks like: LINKMSG Texture | 1,-4,-1864098,fromMLP

You have example AVpos and .MENUITEMS notecards with your purchase. Remember that this works too with AVSitter 2.

IMPORTANT: If you want the texture menu under the [ADJUST] menu of AVsitter 2, then the line to write is:

ADJUST Texture|-1864098

or

ADJUST [Texture]|-1864098

or any other writing you prefer for it.


TROUBLESHOOTING


Q: When I'm using the auxiliary tool and click Create!, no texture information is output. What could be happening?

A: Make sure that the description of the prims that should be affected by the texture theme, begins by t; and then the text you want (but try to keep it short.) The auxiliary tool only outputs information when the description begins by t;


For any other problem not described here, please give a complete description of your issue in the following online form.

I'll get back to you after I have read your report and replicated your issue inworld, according to your description of it. Please, be detailed.

-- Auryn Beorn