Check that your box contains the following assets:

• [Black Tulip] Faces PRO v2.0 - AVsitter Plugin
• [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~
• [Black Tulip] Rest Head v2.0
• [Black Tulip] Reset Facial Expressions (P6)
• [Black Tulip] SAMPLE Fireplace w.AVsitter 2
• [Black Tulip] Proof Of Purchase - Faces PRO 2 Plugin
• [Black Tulip] Faces PRO - AVsitter Plugin ~DOC~
• [Black Tulip] SAMPLE Fireplace w.AVsitter 2 - COMPLETE

If any of these is missing, contact Auryn Beorn for a replacement.

• Bento facial expressions for Bento mesh heads are now possible in your items
• Turn the facial expressions on/off
• Notecard configuration to define your expressions and add extra ANIM lines
• New skipAVpos notecard command (Version 2)
• Version 2 of the script now reads notecards named as:
  
  

      AVpos
      AVpos 1
      AVpos 2
      ...
      [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~
      [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ 1
      [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ 2
      ...
  

• Improved internal memory management. If you use the same expression over and over different animations, you can store safely up to 500 of them. Use short names! (Version 2)
• You can now use the name of an ANIM line in subsequent ANIM lines if they're meant to have the same expression. (Version 2)
• You can overlap two or more facial expressions to be played at once. (Version 2)
• If the FIRST of the expressions has a NEGATIVE TIME, said expression will be repeated every number of POSITIVE SECONDS, independently of the rest of the expressions. This allows for instance to keep the mouth open while playing a sequence of facial expressions. (Version 2)
• This first of the expressions with negative time also allows to have more than one facial expression played at once. (Version 2)
• The following command atop of the AVpos notecard:
  
  ADJUST [BENTOFACE]|-31450010
  
  now shows a menu with options to turn the faces on/off AND load a set of animations built for a specific head (maximum of 8 heads). (Version 2)

Our step by step example consists of a fireplace with three poses for couples. One of them is a repeat to show one of the extra features of this script versus the basic version. This teaches us how to use the script, and how to use it when more than one avatar is involved (which might be the usual).

Rez the included [Black Tulip] SAMPLE Fireplace w.AVsitter 2 sample object. It's prepared with AVsitter 2 and, important, including the [AV]faces script. You need [AV]faces if you want to trigger the facial expressions in default avatars and have access to the [DUMP] function that outputs all the ANIM lines.

Drop the included animation [Black Tulip] Rest Head (P0). This is perhaps the most important step.

Open the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin ~CFG~ configuration notecard and change the number next to maxSitters = to the total number of sitters of your engine.

Now let's observe the two blocks of face elements that it contains. They're separated visually on purpose, and the script expects them in that order.

The first block contains the list of system facial expressions and the name of the Bento animation that will be used on a mesh head, separated by the pipe character | . You can replace the supplied names with your own animations, or leave them as-is if you're using our Black Tulip Bento facial expressions set.

It is very important to leave all the lines with all the SYSTEM facial expressions. The script may not work correctly otherwise. It is also very important NOT TO CHANGE THE ORDER of the lines in this first block. Otherwise we're making it incompatible with one of AVsitter's [AV]faces features.

The second block of face lines is simply a list of other animations that we'll be using in our ANIM lines that do not correspond to any of the default. We must define them first here, and then we can use them in our ANIM lines by that same name.

The script will read both the AVpos notecard and the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin ~CFG~ notecard for ANIM lines. Although the majority of the ANIM lines are in the AVpos notecard, the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin ~CFG~ notecard can be used to launch Bento animations that don't have a system equivalent. They can be on the AVpos notecard too and [AV]faces will launch them - they simply won't have an effect in the default system avatar, only in the Bento heads.

If we choose to include ANIM lines in the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin ~CFG~ notecard, we must write first which SITTER is the corresponding one. The provided sample notecard shows this.

Now we check the ANIM lines in the AVpos notecard and make the list of animations that we have to use:

• express_laugh_emote: [Black Tulip] Faces - express_laugh_emote
• express_toothsmile: [Black Tulip] Faces - express_toothsmile
• express_bored_emote: [Black Tulip] Faces - express_bored_emote
• express_disdain: [Black Tulip] Faces - express_disdain

(These animations are part of our Bento animations kit, which is sold apart - no transfer versions are included in the final sample to see the effect.)

We then check the ANIM lines in the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin ~CFG~ configuration notecard and make the list of the remaining animations that we use:

• [Black Tulip] Faces - open_mouth_anim #1
• [Black Tulip] Faces - tongue_animation

(These animations are part of a store group gift - no transfer versions are included in the final sample to see the effect.)

We change permissions for next owner of the animations to either no copy/transfer or copy/no transfer, and after that, we drop them in the engine.

Then we drop the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin ~CFG~ configuration notecard with all the data we need.

Now we have to answer to this question: How many avatars is our engine for?

In our example case, the engine is for TWO avatars. This means that we have to drop TWO copies of the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin script inside the engine. (Change permissions for next owner in inventory before dropping the script or it will self delete).

This script reads first from the [Black Tulip] Faces PRO v1.0 - AVsitter Plugin ~CFG~ notecard and then directly from the AVpos notecard. It notifies when it's done.

And we're ready to go :-)

You can find the finished sample as the [Black Tulip] SAMPLE Fireplace w.AVsitter 2 - COMPLETE object.

NOTE: Not all animations of all creators are made the same. In some cases, you may find that after stopping the animation, you're still stuck in the pose. You can use the supplied [Black Tulip] Reset Facial Expressions (P6) animation by playing it directly from inventory, and if that doesn't work, then you need to undeform your avatar in the Avatar Health menu (at least in Firestorm). This [Black Tulip] Reset Facial Expressions (P6) animation is NOT used by the script, and you can give it away freely if you wish.

NOTE: If you want to include a FACES script to turn the Bento faces animations on/off, you have to write a line like this on top of your AVpos notecard:

ADJUST FACES|-31450010

Keep in mind that [FACES] is already used by [AV]faces.

The BENTO Faces BASIC script is included in this package. Read here for its documentation and remember that you can't mix the scripts. Your engine must have either all BASIC scripts, or all PRO scripts.

Our step by step example consists of a fireplace with three poses for couples. Rez the included [Black Tulip] SAMPLE Fireplace w.AVsitter 2 sample object. It's prepared with AVsitter 2 and, important, including the [AV]faces script. You need [AV]faces if you want to trigger the facial expressions in default avatars and have access to the [DUMP] function that outputs all the ANIM lines.

Drop the included animation [Black Tulip] Rest Head v2.0. This is perhaps the most important step.

Open the [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ configuration notecard and change the number next to maxSitters = to the total number of sitters of your engine. For example, set it this way: maxSitters = 2 (since this sample engine is meant for 2 avatars).

The next line says:
skipAVpos = 1

This means that the script will NOT read the AVpos notecards contained in the engine, it will skip directly to the script's own. If you want the script to read your AVpos notecards, set the numeric value to 0:
skipAVpos = 0

Let's observe now the following block:

BEGIN HEAD = Default

face = express_bored_emote | [Black Tulip] Faces - express_bored_emote POSE
face = express_bored_emote5 | [Black Tulip] Faces - express_bored_emote POSE P5
face = express_embarrassed_emote | [Black Tulip] Faces - express_embarrassed_emote POSE
face = express_open_mouth | [Black Tulip] Faces - express_open_mouth POSE
face = express_open_mouth5 | [Black Tulip] Faces - express_open_mouth POSE P5

END HEAD

The block is built within the:

BEGIN HEAD = HeadName

END HEAD

structure.

The script needs at least one mandatory HEAD block, and the HeadName must be set to Default. Also, this Default block must be the first one in the notecard. We'll talk more about this block after we've completed the step-by-step guide.

Within the HEAD block, we write the facial expressions we will be using in the engine, and which Bento animations will be used in each expression. We write it as:

face = expressionName | animationAssetInInventoryName

Memory saving tip: Use short names both in the expressionName and in the animationAssetInventoryName (which means renaming your animation files in the object).

The [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ notecard can be used to launch Bento animations that don't have a system equivalent. They can be on the AVpos notecard too and [AV]faces will launch them - they simply won't have an effect in the default system avatar, only in the Bento heads.

If we choose to include ANIM lines in the [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ notecard, we must write first which SITTER is the corresponding one. The provided sample notecard shows this.

The basic format of the ANIM lines is the same basic format it has in AVsitter:

ANIM animNameInMenu|expressionName|timeToRepeat

It can be a little more complex than that, as we'll see later.

We change permissions for next owner of the animations to either no copy/transfer or copy/no transfer, and after that, we drop them in the engine.

Then we drop the [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ configuration notecard with all the data we need.

Now we have to answer to this question: How many avatars is our engine for?

In our example case, the engine is for TWO avatars. This means that we have to drop TWO copies of the [Black Tulip] Faces PRO v2.0 - AVsitter Plugin script inside the engine. (Change permissions for next owner in inventory before dropping the script or it will self delete).

This script reads first from the [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ notecard and then directly from the AVpos notecard. It notifies when it's done.

And we're ready to go :-)

You can find the finished sample as the [Black Tulip] SAMPLE Fireplace w.AVsitter 2 - COMPLETE object.

NOTE: Not all animations of all creators are made the same. In some cases, you may find that after stopping the animation, you're still stuck in the pose. You can use the supplied [Black Tulip] Reset Facial Expressions (P6) animation by playing it directly from inventory, and if that doesn't work, then you need to undeform your avatar in the Avatar Health menu (at least in Firestorm). This [Black Tulip] Reset Facial Expressions (P6) animation is NOT used by the script, and you can give it away freely if you wish.

NOTE: If you want to include a FACES button to turn the Bento faces animations on/off, you have to write a line like this on top of your AVpos notecard:

ADJUST FACES|-31450010

Keep in mind that [FACES] is already used by [AV]faces. The indicated ADJUST command will open a menu with on/off options and more.

Let's check out the ANIM lines of SITTER 0 defined in the sample configuration notecard:

SITTER 0

ANIM Cozy 1|express_bored_emote|14
ANIM Cozy 2|express_open_mouth@express_embarrassed_emote|5|express_open_mouth5|14
ANIM Cozy 1a|express_bored_emote@express_embarrassed_emote|-3|express_open_mouth5|10

The first ANIM line has no mystery about it. When the Cozy 1 pose is selected in AVsitter, the express_bored_emote associated animation (in the face line definition) will play every 14 seconds.

The second ANIM line, to be triggered when the Cozy 2 pose is selected in AVsitter combines two elements. The first one is the composed expression:

express_open_mouth@express_embarrassed_emote

The @ character separates expressions. What happens here? That express_open_mouth AND express_embarrassed_emote are played together. In a way, we can say that they overlap. They will play at once, and after 5 seconds, we move on to playing the animation associated to the expression express_open_mouth5. 14 seconds later we go back to the beginning, and play the overlapped expressions. And so on and so forth.

The expressions triggered when Cozy 1a is selected from the AVsitter menu have a similar format, but let's check a little yet important difference.

ANIM Cozy 1a|express_bored_emote@express_embarrassed_emote|-3|express_open_mouth5|10

The first expression, composed of two overlapping animations, is to be played every... MINUS THREE seconds? What does that mean? It means that it will be triggered every 3 seconds, independently of any other expressions in the ANIM line. The second expression will be triggered every 10 seconds, and overlapped to that time, the first expression will be triggered every 3 seconds.

This special use of negative time works only for the first of the expressions indicated in an ANIM line. If the negative time appears in any other position of the ANIM line, it will behave as if the time were written as a positive number.

Now that we've examined the format, we can understand what the ANIM lines for SITTER 1 will do:

SITTER 1

ANIM Cozy 1|express_bored_emote|17
ANIM Cozy 2|express_open_mouth@express_embarrassed_emote|-5|express_bored_emote|17

IMPORTANT: If you're using overlapped expressions, this is, using the @ command, then do NOT include [AV]faces in your engine or you'll have often script errors.

Let's check the mandatory Default block at the top part of the notecard:

BEGIN HEAD = Default

face = express_bored_emote | [Black Tulip] Faces - express_bored_emote POSE
face = express_bored_emote5 | [Black Tulip] Faces - express_bored_emote POSE P5
face = express_embarrassed_emote | [Black Tulip] Faces - express_embarrassed_emote POSE
face = express_open_mouth | [Black Tulip] Faces - express_open_mouth POSE
face = express_open_mouth5 | [Black Tulip] Faces - express_open_mouth POSE P5

END HEAD

Now, suppose you have purchased a set of facial expressions made specifically for heads of the Lelutka brand. You would add a block like this, after the Default one:

BEGIN HEAD = Lelutka

face = express_bored_emote | [Lelutka] express_bored_emote
face = express_bored_emote5 | [Lelutka] express_bored_emote P5
face = express_embarrassed_emote | [Lelutka] express_embarrassed_emote
face = express_open_mouth | [Lelutka] express_open_mouth
face = express_open_mouth5 | [Lelutka] express_open_mouth P5

END HEAD

And this would make for the menu to show a Lelutka option together with Default. You can repeat this process, up to EIGHT (8) different brands.

Things to keep in mind:

• The brand name cannot use more than 24 bytes (usually, this is 24 characters).
• The more brands we add, the less memory we have to add facial expression animations.
• There have to be the same amount of face lines in each head brand, with the expressions listed in the same order.

The loading set procedure is per sitter, so one sitter may be using the Default set if they like, and another sitter use another brand they prefer for their head.

Q: I've added the ADJUST line in AVpos, but the button isn't showing under [ADJUST].

A: First, make sure that you have only one ADJUST line in your AVpos notecard. Use the Search feature for this. If you have one ADJUST line, for instance:

ADJUST COLOR|12345

then you need to modify the ADJUST line like, for example:

ADJUST COLOR|12345|FACES|-31450010

It is likely that you're using one of the first versions of AVsitter 2. Update to the latest version to have all of AVsitter's feature - including this one.

• The configuration notecard is now named:
  
  [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~
  This is to prevent confusion with using this new notecard format and the previous version of the script.
• New [Black Tulip] Rest Head v2.0 animation. It should fix most of the issues with the tongue getting stuck in newer heads.
• New skipAVpos notecard command
  
  

      skipAVpos = 1
      The script will NOT read the AVpos notecards
  
      skipAVpos = 0
      The script will read the AVpos notecards (default behaviour if the skipAVpos line is not present)
  

• The script now reads notecards named as:
  
  

      AVpos
      AVpos 1
      AVpos 2
      ...
      [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~
      [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ 1
      [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ 2
      ...
  

• Improved internal memory management. If you use the same expression over and over different animations, you can store safely up to 500 of them. Use short names!
• You can now use the name of an ANIM line in subsequent ANIM lines if they're meant to have the same expression. Example:
  
  

      ANIM MyAnim|express_bored_emote|14|express_open_mouth|1
      ANIM AnotherAnim|MyAnim
      ANIM YetAnotherAnim|MyAnim
  

• You can now overlap two or more facial expressions to be played at once. Use the @ character to separate them. Example:
  
  ANIM MyAnim|express_bored_emote@express_embarrassed_emote|14
  
  This will play both express_bored_emote AND express_embarrassed_emote, together, every 14 seconds.
• If the FIRST of the expressions has a NEGATIVE TIME, said expression will be repeated every number of POSITIVE SECONDS, independently of the rest of the expressions. This allows for instance to keep the mouth open while playing a sequence of facial expressions:
  
  ANIM MyAnim|express_open_mouth|-1|express_embarrassed_emote|14
  
  In this line, the first expression has a negative value, -1. We take it as positive, 1. So express_open_mouth will be triggered each 1 seconds. Besides, we have express_embarrassed_emote, to be triggered every 14 seconds.
• This first of the expressions with negative time also allows the @ character to have more than one facial expression played at once:
  
  ANIM MyAnim|express_open_mouth@express_bored_emote|-5|express_embarrased_emote|17
• The following command atop of the AVpos notecard:
  
  ADJUST [BENTOFACE]|-31450010
  
  now shows a menu.
  
  

      Default          HEAD 1      HEAD 2
      HEAD 3          HEAD 4      HEAD 5
      HEAD 6          HEAD 7      HEAD 8
      [^ AVsitter]    [On/Off]      [G. On/Off]
  

  
  
  Default is the default set of expressions that will load first, always. It is created by writing a block like this in the [Black Tulip] Faces PRO v2.0 - AVsitter Plugin ~CFG~ notecard, before the SITTER keywords.
  For example:
  
  

  BEGIN HEAD = Default
  
  face = express_bored_emote | [Black Tulip] Faces - express_bored_emote POSE
  face = express_embarrassed_emote | [Black Tulip] Faces - express_embarrassed_emote POSE
  face = express_open_mouth | [Black Tulip] Faces - open_mouth_anim #1
  
  END HEAD
  

  
  Then HEAD 1...HEAD 8 (maximum is 8, anything over that will be ignored) are the names of specific heads we have facial expressions for. For instance, if we have specific facial expressions for Lelutka and LAQ heads, we write for example the following before the SITTER keywords:
  
  

  BEGIN HEAD = Lelutka
  
  face = express_bored_emote | [Black Tulip] Faces - express_bored_emote POSE
  face = express_embarrassed_emote | [Black Tulip] Faces - express_embarrassed_emote POSE
  face = express_open_mouth | [Black Tulip] Faces - open_mouth_anim #1
  
  END HEAD
  
  
  BEGIN HEAD = LAQ
  
  face = express_bored_emote | [Black Tulip] Faces - express_bored_emote POSE
  face = express_embarrassed_emote | [Black Tulip] Faces - express_embarrassed_emote POSE
  face = express_open_mouth | [Black Tulip] Faces - open_mouth_anim #1
  
  END HEAD
  

  
  
  The last line, containing these buttons:
  
  [^ AVsitter] [On/Off] [G. On/Off]
  
  [^ AVsitter] - Goes back to the AVsitter menu
  [On/Off] - Turns On/Off the Bento faces. Resets back to On when the corresponding avatar stands up. (This setting works per sitter.)
  [G. On/Off] - Turns On/Off the Bento faces. Does not reset back to On when the avatar stands up. This is a global setting available only to the object owner. (This setting works per sitter.)