Documentation · Show/Hide Faces (AVsitter plugin)
Show/Hide Faces (Avsitter plugin) script in Marketplace.
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.Follow these directions carefully. Complete the Step by Step Guide in the first place and then go to the Advanced Setup section for a detailed explanation of all the features. There's a Troubleshooting section at the end. Before asking for help, check that your problem isn't one of the problems described in there.
License of Use: Click here to read the License of use.
What's included in your purchase
Check that your box contains the following assets:
- [Black Tulip] Show/Hide Faces - AVsitter Plugin
- [Black Tulip] Show/Hide Faces - AVsitter Plugin ~CFG~
- [Black Tulip] Show/Hide Faces - AUXILIARY TOOL
- [Black Tulip] Show/Hide Faces - AUXILIARY TOOL ~CFG~
- [Black Tulip] Proof Of Purchase - Show/Hide Faces Plugin v1
- [Black Tulip] Show/Hide Faces - AVsitter Plugin - DOCS
and these sample assets, necessary to follow the step-by-step guide:
- [Black Tulip] Window and Curtain (Show/Hide ready) - SAMPLE
- [Black Tulip] Standing by the window #2
- [Black Tulip] Standing by the window #4
- [Black Tulip] Standing by the window #6
- [Black Tulip] Standing by the window #7
- [Black Tulip] Standing by the window #9
- [Black Tulip] Standing by the window #10
- AVpos
If any of these is missing, contact Auryn Beorn for a replacement. Keep in mind that sample assets are never provided in full perms state. They're included to illustrate how to use the script.
Features list
The main purpose of this tool is allowing you to show some faces of your object and hiding others when certain animations are being played.
For example, think of a BDSM bed (or post, or cross, or...) with chains. You may want that the chains only show when there are people using the bed, but when no one is on the bed, no chains would show. Or showing open cuffs left in a messy way.
You may want too that the chains show only when certain animations are being played, but invisible for the rest. If you're looking for a similar use to this (or exactly that one), and your sitter of choice is AVsitter, this is the script you're looking for.
- Define a configuration of faces for a setting we call the default setting: How will the object look like when no avatars are sitting on it? We can define this.
- Define a configuration of faces per animation. Several animations may have the same configuration, and there can be different configurations.
- If an animation has no assigned configuration, then the default one is used.
- The transparency in the configuration can be any value between 0 and 1: We're not limited to completely show or completely hide a face. We can partially show a face.
- In addition to changing the transparency value, we can also change the glow value per face. Check the Advanced Setup section of this documentation for that.
Step by Step Guide
The auxiliary tool makes quite simple to set up the script, so we'll use it always and only if we want to retouch something manually, we will check the Advanced Setup section (although we could use the auxiliary tool for that too.)
We recommend, though, that you edit your notecard in an offline text editor in your computer. This is: open your favorite plain text editor in your computer, and prepare your notecard in there. Saving offline is way quicker and less prone to errors than saving notecards in SL. When your notecard is ready, you can paste the content into a SL notecard.
The object we'll be working with to learn this script is not as fancy as the BDSM bed mentioned, but it shows everything you need to know and gives yet more ideas about what this script can be used for.
Setting up: Preliminaries
Rez the [Black Tulip] Window and Curtain (Show/Hide ready) - SAMPLE object and observe it. It consists of two linked prims: a curtain, and a window. It initially shows this way:
The object looks a little strange because of the faces that we show colored here:
(the curtain would look the same way from behind, also with an overlapped face)
The sample object begins showing all of its faces. Our goal will be show ones and hide others depending on the situation.
This is the behaviour we will make the script produce:
- Show the window closed and the curtain closed when no one is sitting on the object:
- Show the window closed and the curtain open when AVsitter plays some animations we specify:
- Show the window open and the curtain open too when AVsitter plays other animations we also specify:
- We will not assign a configuration for two animations. When AVsitter plays any of those, the script will show the default configuration, which will be the one when no one sits: closed window, closed curtain.
Notice that the behaviour we want to produce looks good once the prims are correctly positioned, which is what the pictures above show. But while we work, we will do with the linked prims positioned with some distance between them, so it's easier for us to select faces when we have to.
We can work this way and not worry because the script does not change position/rotation: it will affect to the transparency setting. Once we're done, we'll reposition prims so the window looks all fancy with the curtain :-)
Setting up: Changing prim descriptions
The next thing we're doing is changing the prim descriptions so the scripts recognize them. This is very important: we will change the description only of the involved prims. We won't change the description of those prims that have nothing to do with showing and hide.
Ideally, we must cover all of our prims and ask ourselves the question: will any face of this prim show or hide depending on the animation played? If the answer is no, then we ignore that prim and check next. If the answer is yes, then we must write a description with this format:
showHide=IdentifierIdentifier is a string that we choose. We recommend that this string is as short as possible, to avoid issues. Each involved prim must have its own unique identifier. In other words: do not use the same identifier in more than one prim.
We will be using short identifiers for our prims. The curtain will be a1, so the description is changed to what the picture shows:
and the window will be b1, so the correct description to write is:
Let's study now how to use the auxiliary tool
Setting up: The auxiliary tool
The auxiliary tool needs a couple of things:
- That you have not forgotten to set the prims' descriptions correctly.
- That you edit the [Black Tulip] Show/Hide Faces - AUXILIARY TOOL ~CFG~ notecard if needed. Normally, you won't need it (it's prepared for the most common case).
We will not need to edit the configuration notecard for our example, and probably won't need to edit it in many projects. It's there for that rare occasion when you would need that all faces in all prims, or just some prims, have the same alpha values, or if you also want to use the glow feature. Check the Advanced Setup section of the documentation for that, and worry not about editing that notecard now.
At this point, our sample object should have the descriptions correctly set as explained before. Right click on it to edit, click on the Content tab, and drop the following assets in its contents, in this order:
- The [Black Tulip] Show/Hide Faces - AUXILIARY TOOL ~CFG~ notecard
- The [Black Tulip] Show/Hide Faces - AUXILIARY TOOL script
When you have them in the object and see these messages in chat:
close the edit window.
Now we're going to edit our object to make completely transparent the faces that will not show on the default pose. Remember that this means: two curtain sides (in red, some pictures above) and the middle window frame with its glass. If you have difficulty doing this, remember that it's perfectly okay to tint the prims and make the faces easy to spot. Once we have it:
we click on it to bring up the auxiliary tool's menu, which gives us the following options:
Since we want this configuration to be the default one, click on the SHAVE SHOW D button to obtain some text in local (nearby) chat:
Copy that text in a plain text file in your computer and save the file. We'll work it once we have all the information that we need. Then set the transparency of the faces like this, for a different configuration for certain animations (open curtains, closed window):
click to bring up again the menu, and select SAVE SHOW. Then copy the text it outputs in your plain text file (and save it):
and then change the transparency so these faces show (open curtains, open window):
Bring up the menu again, and again click on SAVE SHOW, then copy the text it outputs in your text file (then save):
We don't have more different configurations to save, so now we bring up the menu and click on [DELETE], which deletes the script and configuration notecard from our object:
Now we move the prims so they look more logical:
and let's study how to make the final configuration notecard.
Setting up: The main configuration notecard
We do this part in a plain text editor in our computer. If you've followed the process explained before, you should have something like this showing in your text editor:
If you haven't followed that process, do it now because we are going to prepare the configuration notecard :-)
First, let's clean this up a little, removing all the lines with directions and timestamps until we have something like this:
What do we do with this? If we haven't set up the animations with AVsitter, then now it's the time to do it. Set up the AVsitter engine because we need the list of animation names on the AVsitter menu. There's an AVpos notecard included with this script, ready with all the animations, for the purposes of this documentation. In your own projects, you would need to create the AVpos notecard yourself.
Open the included AVpos notecard. It should look like this:
The names of the animations are these:
Stand 2 Stand 4 Stand 6 Stand 7 Stand 9 Stand 10
Yes, when we say here "the name of the animation", we refer to the identifier we give to it that shows as a button on the AVsitter menu. So it's not the asset name itself, but the identifier we choose.
We have now to decide:
- Which animations are good with the default configuration. For the purposes of this documentation, we decide that Stand 6 and Stand 9 don't need a different configuration than the default. They will not show on the configuration notecard, as a consequence of this decision (and the notecard will be faster to read by the script, having this one more available memory).
- Which animations will have the "open curtains, closed window" configuration. For the purposes of this documentation, we decide that Stand 2 and Stand 4 will have it.
- Which animations will have the "open curtains, open window" configuration. For the purposes of this documentation, we decide that Stand 7 and Stand 10 will have it.
If we review the process, we have that after retrieving the data corresponding to the default position, the first ANIMATION block we obtained was the one for "open curtains, closed window", and we want that configuration for the Stand 2 and Stand 4 animations. So we locate the first ANIMATION block in our text editor and select it:
copy and paste it below to duplicate the block:
and then write down the animation names after the ANIMATION = text:
Now you do the same with the remaining block, to practice :-) Make the second ANIMATION block configuration be ready for the Stand 7 and Stand 10 animations.
Once we have our final text ready (save often!):
we make a copy of the included [Black Tulip] Show/Hide Faces - AVsitter Plugin ~CFG~ notecard, open it:
and then copy/paste the complete information from our text editor, this way:
Now we save the notecard. We're almost done!
Setting up: Prepare AVsitter, drop the Show/Hide notecard and script
Drop in the contents of the object all the sample animation files included in this package, the AVpos notecard, and your AVsitter scripts:
Now drop the [Black Tulip] Show/Hide Faces - AVsitter Plugin ~CFG~ notecard and then, the [Black Tulip] Show/Hide Faces - AVsitter Plugin script.
Once the script finishes reading the notecard, the window and curtain will close if they weren't closed already.
Now we sit on the window and the script changes the configuration to the corresponding one for Stand 2 (first animation on the menu):
Change the animations and check that all the configurations correspond to the animations you wanted:
And now yes... We're done! May you create wonderful things with this script :-)
Update to V1.05
Upon customer request, there has been an update to this script. The first version allowed to do this:
- Define a configuration of faces for a setting we call the default setting: How will the object look like when no avatars are sitting on it? We can define this.
- Define a configuration of faces per animation. Several animations may have the same configuration, and there can be different configurations.
- If an animation has no assigned configuration, then the default one is used.
But what if we would like that a specific configuration is the most used when avatars are sitting? With version 1, we would have to write a long list of animations with the corresponding transparency et all definition, per face. This impacts in the available memory of the script. So this version 1.05 gives a step forward in making the script even easier, and using less memory.
Version 1.0 had this kind of block to define the default configuration when no one sits (for example):
DEFAULT STATE BEGIN b1:0@0.2,1@0.2,2@0.0,3@1.0,4@1.0,5@0.0;a1:0@1.0,1@0.0,2@1.0,3@0.0,4@1.0 DEFAULT STATE END
In version 1.05, we're adding a default configuration when at least one avatar is sitting, like this:
DEFAULT STATE AVS_ON BEGIN b1:0@0.2,1@0.2,2@0.0,3@1.0,4@1.0,5@0.0;a1:0@1.0,1@0.0,2@1.0,3@0.0,4@1.0 DEFAULT STATE AVS_ON END
The auxiliary tool (also updated) shows [SAV SHOWDAV] as the button to have us record this configuration. (The other button names have been reduced a little, they all say SAV instead of SAVE.)
Then, in version 1.05, the default configuration when someone is sitting has this format:
DEFAULT STATE AVS_ON BEGIN b1:0@0.2,1@0.2,2@0.0,3@1.0,4@1.0,5@0.0;a1:0@1.0,1@0.0,2@1.0,3@0.0,4@1.0 DEFAULT STATE AVS_ON END
and the auxiliary tool shows the [SAV SHOWDAV] button to have us record this configuration.
The rest is the same: the ANIMATION blocks have exactly the same structure.
Hopefully, this update will make your building time even easier :-)
If you have purchased the first version and have NOT received this update, please contact Auryn Beorn to receive it.
Advanced Setup
Description Format
This script can be used in conjunction with many other of Black Tulip's scripts as long as we remember this: If two scripts need using the description field, we will separate their values with the # character. Each script will read the part of the description needed and both will be able to coexist together. If it's three, then same rule applies: separate each description part with #
For example, if we're using the texture change and this script in the same object, the description of a prim that both shows/hides faces and changes textures should be written like this (example values):
t;mirror#showHide=m1Notecard Configuration in Detail
The complete format of a notecard line with show/hide data is:
primDesc1:face0@alpha+glow,face1@alpha+glow,...;primDesc2:face0@alpha+glow,face1@alpha+glow,...;...
The information relative to each prim is delimited by these tokens:
primDesc1 and ; for the first prim in the list, primDesc2 and ; for the second, and so on.
Let's analyze the information for the first prim: the rest have the same format. It's this, the text enclosed between primDesc1 and ;:
face0@alpha+glow,face1@alpha+glow,...
Troubleshooting
We haven't been notified of issues at the moment.
If after having followed the directions and checked the troubleshooting list, you have problems making the script work, please click here for the customer service form.
