Wednesday, February 12, 2014

Marine's Goodies Sublimator manual

Hello and thank you for buying the Sublimator from Marine's Goodies. This equipment allows you to play the animations contained inside very easily, finding the animation you want in two clicks, and to add your own animations without any other action than to actually put them in the Sublimator.

The Sublimator is a HUD (an object you attach on your view rather than on your avatar) with buttons that you click on in order to choose the animation you want to play. It is usually worn on the left of the screen but you can move it to the right if you want.

This manual is written in the form of a small tutorial with pictures, to take you through all there is to know about this product.

Basic use

The very most basic way to use the Sublimator is to click on the "All" button, which brings up a menu with the names of all the animations contained into the HUD (42 animations if it hasn't been modified). To switch to the next and previous pages, simply click on the ">>" and "<<" buttons on the menu. Then press the button corresponding to the animation you want to play, and voila. Press "STOP" to stop. It doesn't get any easier than this.

Once you have selected at least an animation, the top button takes its name and if you click on it, it will switch it on and off.

The HUD is made for playing static poses, animations, dances, sits etc, but it is not an Animation Overrider, it is not supposed to play walks, runs and jumps. This is why it will temporarily stop its currently playing animation while you move, and resume it when you stop.

Hide and show the HUD

You can move the HUD out of the way by clicking on the slightly darker area around it, and you can show it again by clicking on the same area on the edge of your screen :


You surely didn't miss all the other buttons with text on them : "bend", "cum", "kneel"... All these buttons are actually shortcuts to certain subsets of animations. These subsets are defined by filters, which will display only the matching animations on the menu that shows. If a filter results in only one animation to be played, then it will play it immediately without bringing up the menu.

This is handy because let's be honest, browsing through 5 pages of 9 animations at a time on the "All" menu is not fun.

So if you want to lay down, for example, simply click on the "lay" button and you will see that the menu that comes only shows all the animation which names contain the word "lay". Same for "kneel" (there are more than one page of them), "cum", "stand", etc.

Adding new animations

Adding or removing animations is done through the Edit window of your viewer. Drop your Sublimator on the ground (because most animations are no-transfer and you can't add no-transfer items to an attachment directly), right-click on it, select "Edit" (or hold Ctrl and right-click if you're on the RLV, that's faster), go to the "Content" tab and you see all the animations the Sublimator contains.

Drag and drop your own into it, or right-click on some of the animations contained in it and select "Delete" to remove them.

Every time the contents of the Sublimator change, the filters are rebuilt. It takes a little time, but this is to spare you from having to wait while using it.

Once done, take your Sublimator back into your inventory and wear it.

Adding a new filter

Let's suppose you want to make your own filter, for example you want to see on the menu only the poses that make you kneel backward. You already know that the menu can only display up to 9 animations per page and you don't want to have to browse too much. To do this, simply click and hold for a short time your mouse button on an empty button, like the one under "stand" :

Once you release the mouse button, a different dialog box appears :

In the big white field, enter "bwd" and click on "submit". Be advised that pressing the Enter key will not validate the entry, it will merely add a new line (you'll see later why it is useful) :

You immediately see the button you've just clicked on, turn yellow and have "bwd" written on it.

This is exactly what you've just entered as a filter. Moreso, a new dialog appears, with only two animations listed : "kneel bwd" and "kneel open bwd". These are the only two anims with "bwd" in the name :

Once you are tired with a filter, you can change or remove it it by clicking and holding on its button again and either entering a new filter or leaving the field empty before pressing "Submit".

This is particularly handy if you want to add your own animations (because the filters already present cover the existing ones pretty well already), but hold on, filters can be made a lot more sophisticated.

As you have noticed, filters are essentially a way to filter (duh) certain animations and hide the others from the menu, in order to go to the one you want much more rapidly. There are several ways to retain an animation and have it shown on the menu:

- By specifying what word(s) its name must contain.
- By specifying what word(s) its name must not contain.
- By specifying its exact name.
- By specifying a name it must not be equal to.
- By linking some or all of the above constraints to make the filter even more restrictive (in other words, in order to satisfy your filter, an animation X must satisfy the constraint 1 and the constraint 2 and the constraint 3 etc).

So the longer the filter, the fewer the animations displayed on the menu, because the more constraints specified.

To do this, you have to learn a quick syntax when writing in the dialog box that asks you for a new filter to create :

- If you write a word, only animations with a name containing this word will be displayed. For example, if you write "lay" it will display all the "lay" animations ("lay down", "lay back" etc) on the menu, but also the "display" animations ("display", "display bend" etc) because "display" contains "lay".

- If you write an exclamation mark ("!") before that word, then it indicates a negation. It will do the opposite of above and display only the animations with a name that does not contain that word. For example, if you write "!kneel" it will display everything except the kneeling animations.

- If you write an "equal" sign ("=") before the word (but after the exclamation mark if any, so if you need both it will look like "!=word" and not "=!word"), only the animation which name is equal to the word will be displayed. Attention, some animations have parameters into their names (such as the height offset to set automatically, see below, or some expressions such as smiling or opening the mouth), these parameters do not count. For example, "=cum lay" will match "cum lay:1.16/10:express_open_mouth:express_toothsmile", since only the first part counts, everything after the first colon (":") is discarded.

- If you write the exclamation mark before the equal sign, it will do the opposite and display all the other animations, but not this one.

- If you add an opening bracket ("[") just before the word (but after the "!" if any, and it is not compatible with "="), it will display only the animations which name begins with the word you specified. For example, if you write "[l", it will display all the "lay" animations, but also the "leg" ones, since all those animations begin with a "l".

- If you add a closing bracket ("]") just after the word (and it is not compatible with "=" either), it will display only the animations which name ends with the word you specified. For example, if you write "lay]" it will display only "cum lay" and "display" (there would be 12 animations if you hadn't added the bracket), because only those two end with the letters "lay".

- Likewise, the "!" sign indicates a negation and will exclude what you write after it.

This is the syntax for one filter, but you can write several filters on the same line, to make it more restrictive. Just separate the filters with commas (","), each filter obeying the same syntax as detailed above.

For example, if you wanted only the "lay" animations ("lay down", "lay back" etc) but not the "display" ones or the "cum lay" one, the filter would be :

Which means "I want the animations with a name containing 'lay', but not the ones containing 'display' or 'cum'". This is exactly the filter specified in the "lay" button, by the way.

To put it more formally, the Sublimator reads this filter like "lay AND NOT display AND NOT cum".

Notice that the Sublimator only writes "lay" on the button and not "lay,!display,!cum", which would look a bit dirty on the screen. The button will only display up to 10 characters, and will truncate at the first comma or newline it finds.

Now, you could want more animations displayed on the menu and not fewer, meaning you could want several of these groups of filters set on one button. For example, suppose you want all the sits and all the stands on the same menu. You simply write "sit" on the first line of the field, and "stand" on the second line after having pressed the Enter key, like this :

This gives you a menu with both the sits and the stands.

Formally, it is read "sit OR stand", and both lines follow the same syntax as explained above.

The problem is that it becomes difficult to find out what that button does, simply by reading it, because it merely shows the text "sit". How to know that it stands for "sit or stand" and not just "sit" ?

Well, you can give your filter a label. To do this, add a minus sign ("-") as the very first character of the very first line of your filter, and the whole line will be taken as the label and not as a formula. So in our case, you would write this :

This calls your filter "sit/stand" (without the minus sign) and displays exactly that on the button. It makes it clearer, doesn't it ?

Please note, that the case does not matter. If you write "SIT" in capitals, it will still match all the sit animations. So a good habit is to begin all labels with a capital letter (like "Sit/stand" instead of "sit/stand") and write all actual filters in lowercase (no capitals at all). This helps telling easily what buttons have a label (hence a complex filter) and what buttons have a simple filter.

As indicated above, if a filter yields only one result, no menu is shown and the animation is played immediately. This makes it easy to make quick direct shortcuts to your favorite animations.

How to change the altitude

You must have noticed, if you are on a viewer that handles the @adjustheight RLV command, that certain animations automatically adjust your altitude so you stay in contact with the ground. Those are the animations that put your feet off the floor and they are very sensitive to the height of your avatar, and whether you wear high shoes or not.

Without that automatic offset, you would either have to use the Z-offset provided with your viewer (my RLV has one but some viewers such as Firestorm do not, at the time of this writing), or even worse, you would have to modify the "Hover" value of your shape, provided it is modifiable.

Those animations are the animations with a special parameter indicating the pelvis-to-foot distance of the avatar (mine is 1.16 m and that's what you see in those names), and a number indicating the amount of correction to apply. It looks like "1.16/9".

You normally don't have to bother with this since it is automatic, but if you want to further correct the offset, you can use the three buttons on the upper right corner of the HUD :

It is simple, the upper one makes your avatar raise by 0.01, the lower one makes it sink by 0.01 and the middle one resets the correction.

And if you add some animations made by other people (or by you), you may want to add such parameters as well... and this is where it gets a bit complicated.

First you have to know the pelvis-to-foot distance of the avatar that was used to make that animation. It is not all that easy to find out, and usually it is done by trial and error. Plus, it assumes that the feet of the avatar used to create that animation were touching the ground in the first place, which is not guaranteed.

But I have done most of the work for you and compiled some values into a spreadsheet that you will find here :

All you have to do is to remove any shoes you are wearing, set your avatar Z-offset to 0, create a new shape (right-click on a folder in your inventory, then choose "New Body Parts >" and then "New Shape"), then wear it. This new shape is the shape commonly known as "Ruth", and is what you will work with to find out the "pelvis-to-foot" distance of the avatar shape that was used to create that animation.

While wearing this shape, edit it (right-click on your avatar then select "Edit My Shape") and play with the following sliders :

- Body > Height
- Torso > Torso Length
- Legs > Legs Length

You should find a configuration that brings your avatar close enough to the ground to your liking. Look at the three values that you've set and find them in the spreadsheet above, or find the closest ones. By interpolating, you should be able to find a good approximation of the pelvis-to-foot distance.

For example, if you find that the animation X works best with a Body Height of 30, a Legs Length of 70 and a Torso Length of 10, you just find the closest numbers on the spreadsheet : that would be 25, 50 and 0 respectively. Under those numbers you find a pelvis-to-foot distance of 0.9. But since the Legs Length is roughly halfway between 50 and 100 rather than close to 50, maybe it would be wiser to interpolate between those two values. In other words, you take the two pelvis-to-foot distances found under 25/50/0 and 25/100/0, which are 0.9 and 1.1 respectively, and you take the average, which gives you 1.0.

You can notice on the spreadsheet that adding 25 to the Body Height adds about 0.1 to the pelvis-to-foot distance, that adding 50 to the Legs Length adds about 0.2, and that the Torso Length is of lesser importance, but still significant enough to be included in the calculations.

Then you need to know the factor to apply, that is a bit easier, since it depends on how low the pelvis is compared to a standing straight pose :

- Kneeling high (like "kneel pray") : 4
- Kneeling halfway down (like "kneel up") : 6
- Kneeling low (like "kneel closed") : 8
- Sitting : 9
- Laying : 10

To find out the exact number you need, you can take a look at the names of the animations provided in the Sublimator out of the box. As a rule of thumb, if the number you selected makes your avatar sink too much into the ground, choose a higher number (provided the pelvis-to-foot distance you've calculated is correct). If it makes you float too high, choose a lower number.

If you really want to know, this value corresponds to ten times the "scalar" value in the @adjustheight RLV command. So if you calculated a pelvis-to-foot distance of 1.1 and a factor of 9, the Sublimator will send the command "@adjustheight:1.1;0.9;0.0=force" to your RLV. The "0.0" part may change according to the correction you add by clicking on the 3 offset buttons shown above.

Those two values, once set correctly, will ensure your avatar stays in contact with the ground, not sinking nor floating in the air, regardless of your own shape and the height of the shoes you are wearing.

Just add ":firstvalue/secondvalue" at the end of the name of the animation and you're set. For example, if you found a pelvis-to-foot distance of 0.9 for a kneeling animation, add ":0.9/10" at the end of its name.

How to tweak the feet

You will notice that certain poses (in particular the kneels) will bend your feet oddly if you are wearing rigged high heels or boots. This is because those poses are made for barefoot girls so the feet are extended, and high heels are actually flat feet hidden under mesh feet that look stretched. So if the flat feet are extended, the attached rigged feet are extended even further, making it look unnatural and frankly painful.

To remedy to this, you are given 4 different gestures called "Tiptoes" (you need to activate them first), that allow you to control the angle of your feet : either straight or extended, with the hands tightened in a fist or relaxed. Simply press F9, Shift-F9 or Ctrl-F9 to force them to 0° with the hands tightened in fists, 0° with the hands relaxed, or 90° respectively, and press F10 to release them.

In this particular kneeling pose, the hands are supposed to be relaxed, so all you need to do is press Shift-F9 and...

Fixed !

How to tweak the text

This part is quite easy. Nearly each button of the HUD has text written over it, but whether this text is aligned correctly or not depends on your UI size (by default, the UI size is 1.0 and it can be changed in the Preferences, on the "Advanced" tab). If you're like me and you use 0.93, no problem the text should be aligned perfectly. But if you don't, then you will want to align it manually. To do this, use the three buttons to the right of the "All" button :

The upper one moves all the buttons up (but not the texts), the lower one moves them down, and the middle one resets the offset. Easy.

How to tweak the textures

Like every other product I make, I want your Sublimator to be your own. So the box includes four textures that you can use for the buttons, three for the big buttons and one for the smaller ones. The textures are full-perms so you can save them on your hard drive and modify them (with Gimp, Photoshop or what you like), upload them and apply them onto your HUD.

The HUD itself does not change the colors of the buttons, except the top one (orange or green). So if you want a different color scheme, feel free to tint it the way you like. Just keep in mind that it always writes the text in black.

How to update

There might be new versions of the Sublimator in the future, with bug fixes, improvements, new animations, who knows. The Sublimator does not check for a new version automatically but you can do it manually yourself when you want, by clicking on the small transparent "U" button on the lower right corner of the HUD :

If a new update is available, it will be delivered to you for free. Be advised that pressing the "U" button freezes the Sublimator for 20 seconds (that's a built-in SL delay).

That's all, have fun !