Plugins + Scripts SceneDirector

I consider this version "good enough" to no longer be considered a preview. I've been using it long enough in all my personal scenes to be quite satisfied with the functionality it offers.

The main new feature are...

Triggers​

These come in two variants.

State Triggers

This is a new component, available on all atoms. As with all other components, disable/enable it, or reorder the components, depending on what control do you want to have on the Atom, and to customize the UI.
This component:

• Runs trigger actions when the Atom's State is activated or deactivated.
  • When smoothly transitioning to the state, its activation triggers fire together with all other actions, controlled by the "Trigger Actions At" value.
  • Deactivation triggers run when the transition away from the state finishes. Which can be after the activation trigger of the target state is run.
• Activation triggers can be also defined for sub-states, if they are enabled for the state.
  • The main state's activation trigger can be excluded from activating during sub-state animations, if you want to fire it only when the state itself is activated, not when it randomly animates back into the main sub-state.

Note: Consider using Custom Properties instead of manual activation triggers if possible. Especially if you want to control the property's value in pretty much all states. Triggers are more useful if yo

u want to use them to change some values only in few select states, and they also allow you to run actions on other atoms, not just the controlled one.

Note2: It's ok to run actions on SceneDirector itself from these triggers. Some useful examples include:

• Use sub-state Sequence (new addition, see below) to run various actions with (randomized) delays between them, and then switch the Atom to another State at the end of the sequence.
• Synchronize State switches of atom B from sub-state changes of atom A.

Transition Triggers

Define these on a specific transition from one state to another:

• One trigger that runs different set of actions when tahe transition starts, ends, and a value trigger (in 0-1 range) during the transition.
• The transition value progresses at a constant speed and it is not affected by the transition's interpolator, or transition chain/mid-state behavior.
• Transition end actions will not run if the transition is cancelled (by snap-applying a different state).

Few video examples.

A simple scene with only two States created for the Person Atom. Start/End transition triggers control the clothing properties, and turn on/off the spotlight. Transition Value trigger is used to control the slider.

Spoiler: Video: transition triggers

A dedicated Empty Atom which is used as a state machine. Its states control the clothing properties. Thanks to the automatic transition chaining, one state change command can be used to progress through the various clothing stages over time.

Spoiler: Video: State machine using state triggers to control clothing

Component Improvements​

• Morph Group component settings can now be saved and merge-loaded. Useful to configure your controlled morph groups (for individual hands, face, whatever you prefer) once (per gender), and then reuse them on any other controlled atom in any scene.
• When adding a new morph to a Morph Group for already existing atom's setup, it will be captured to all existing states with its current value. Previously it was added with the default morph value.
• Custom Parameters settings can also be saved and merge-loaded. Of course, when loading onto another atom, it must have the same storables/params available. The plugin will print the list of not-found parameters to VAM's log. For parameters in plugins, it will try to find a matching plugin by name, even if it's not loaded into the same slot. But the plugin must be already loaded, it won't magically start adding plugins to your atoms on its own.
• The light component now includes the render mode (auto/vertex/pixel light)

Sub-state Handling Improvements

• Previously, sub-state animation/progression stopped as soon as the atom was asked to transition to another state. Now they will continue animating until the transition actually starts progressing. This happens when the transition has a Delay, or if the transition conditionally waits for another atom.
• Sequence sub-state Animation Mode - similar to Cycle, but stops after the last sub-state ; useful for executing a sequence of actions with (optionally randomized) delays, especially when combined with triggers.

An example of sub-state mixed continuing animation. In older versions the animation would pause when using one of these options to delay a transition.

Spoiler: Video: State change sync in action

The dude has the "climb onto the bed" transition scheduled immediately, but he waits for the girl to finish her transition first. Previously he would just freeze during this, now he continues his idle until it's his time to move.

Other Improvements

• Added public triggers to snap-apply atom states. Normal apply respects transitions, snap-apply activates the state directly.
• Changed how clicking on the Apply State and Apply Pose buttons behaves in the UI. Previously it automagically decided whether to normal-apply or snap-apply the states. Now simple click always normal-applies, and ctrl-click snap-applies. Old behavior remains in VR, since it's hard to ctrl-click there.
• Use shift-click or ctrl-click to move atom state or pose up/down in the list, by 10 or 100 spots, respectively.
• Extended the maximal length of transition chains to 50 steps. The defaults are still intentionally quite short, so make sure to tweak these per-atom settings at the top of the Transitions tab if needed.

Fixes​

• Custom Properties of type StringChooser did not display the popup with the options in the State UI, so they were completely useless.
• Custom Properties of type String or StringChooser did not store the per-state values in the scene file correctly.
• SceneDirector's state handling/animation could be broken if VAM/other plugins threw exceptions when setting their Custom Properties. This happened especially when removing some plugins referenced from Custom Properties.
• Recursive expressions would sometimes not respect the "evaluate a variable only once per frame" rule, leading to stack overflow exceptions

Credits for resources used in the examples from this update:

• Girl: heavily customized version of Nagisa by XNPVV
• Dude: The Dude by sneakyone
• Clothing: maru01, SupaRioAmateur, JaxZoa, VL_13, DateKnight
• Scene: Rocky Cabin by TacoCat and Living Room by TacoCat

Custom Parameters component​

This new features allows you to create your own component which will control any triggerable parameters you add to it. If it's a value that can modified from a trigger, it can be added to this custom component. All other SceneDirector features will work with this component, just like the built-in ones.

• You can find the UI to create and tweak the custom components on the Atom-Components-Custom tab.
• Add triggerable params from any storable of the controlled atom.
• Atom State UI is automatically created for any params added to the component. You can choose the order in which they appear, the UI column, and the UI label, for each of them.
• Custom Params will store/apply with states, smoothly transition or animate via sub-state mixes, just like the built-in ones.
• You can add drivers for scalar (toggle/slider/string) Custom Params.

The video below shows this feature - where and how to add Custom Params, and how to use them in idle animation which uses sub-state mixes:

Spoiler: Video: Custom Param Tutorial

The following video is a bit more advanced, displaying how Drivers can be used to control Custom Params.

Spoiler: Video: Drivers for Custom Param

And yes, if you wanted to achieve just the result from this video, a slider+trigger for the four params would probably be a simpler solution, since it can do linear interpolations natively (but not much more). However, rthe Expression/Driver system is much more flexible ; you could trivially add a toggle to control whether the wetness controls only the gloss or the cloth overlay ; you could make the gloss range configurable ; or the wetness itself could be derived from penetration duration, BodyLanguage's stimulation, or anything else. Anything more complex than a linear interpolation of a couple values gets very messy very quickly with triggers in my experience.

For a reference, here is the wetness setup based on BodyLanguage's stimulation and recent orgasm count I am using in one of my scenes:

SubState Mix Changes​

• When animating atom's parameters via sub-state mixes, any changes to currently relevant sub-state values will be applied to the mix immediately.
• Implemented Odd/Even sub-state animation mode. If this is enabled, the atom will bounce between random mixes of odd and even states (the main state being considered state 0 = even). This allows for controlled ping-pong animation but still with some randomized variations.

The video below shows all these features in action:

• Wetness controlled by the setup shown in the video above. Whenever I move the wetness slider in the video, it gets applied to the animated states immediately.
• The idle animation uses the new Odd/Even mode, with the butt-sway using two sub-states for either side for some variation.

Spoiler: Video: All New Features Combined

Technical note about the sub-state mix changes:
Before this update, whenever the atom started animating transition from one sub-state mix to another, it would pre-compute both mixes and then transition between them. So any changes to the source or target sub-states while the atom was transitioning would not show, only once another transition to the modified sub-state started. So in the example video above, before this change, the wetness slider changes would not show up on the skin immediately ; only after the next butt-bounce would the skin wetness transition to the new set of values.
This can be actually seen in the top video (the tutorial), which was recorded before I implement this change. Even after I change all sub-state colors to red, the top still transitions to black once, because it recorded that value just before I changed it. Overall, the old behavior was fine originally, but with Drivers implemented it got quite confusing and useless.

Other Changes​

• Fixed Drivers not loading correctly for Morphs
• Changed Properties controlled by Driver Expressions to still respect their minimum/maximum limits, if they are hard-limited in the corresponding VaM's UI.
• Changed the slider for floating-point variables to be limited to 0-1 range by default. It can be moved past the limits of course.

Fixes​

• Fixed log and log10 expression functions being swapped
• Fixed empty expressions still applying their last recorded value when being used as a driver, instead of behaving as a no-op. Now it will be possible to set up an empty driver and then override it with a custom expression only in some states.
• Fixed Chapter Index int variable source being misspelled
• Fixed exception being thrown on plugin destroy/reload

Drivers​

The main new feature of this update is the addition of Drivers, which let you drive any(*) of the component properties by mathematical expressions. Some ideas/examples for use of drivers are shown at the bottom of this update.

Drivers for atom properties are defined on the Components-Drivers tab. For now the expression system supports only scalar values, so drivers are available only for boolean (toggle), int/float (slider) and string properties. Support for colors, vectors (positions) and rotations will be added later.

For more information, check the Variables, Expressions and Drivers documentation (hopefully I will update it before this gets approved and published! )

Atom-scoped Variables​

Closely related to drivers, in addition to the previously existing global variables defined on the main Variables tab, each atom now also has its own Components-Variables tab. The UI is the same, the variables and expressions defined here are visible only for that atom's expressions. It's useful mostly for organizing the variables, removing the global clutter. In the future expressions will be able to reference variables from other atoms too, but now you are limited to:

• Global expressions can reference only other global variables/expressions.
• Atom-scoped expressions can reference either variables/expressions defined at the same atom's scope, or global variables/expressions.

Live Editing​

When a sub-state is applied, and therefore now transitions/sub-state animations are running, editing properties of that sub-state in the plugin's UI will apply them to the scene directly. Just like editing atoms directly in VAM's native UI would work.

Other Changes​

• UIObject component can control the state of slider and toggle values,
• Various tweaks and fixes

Driver Examples​

Example 1 - Blinking Light​

A light source with intensity updated by a driver. In this example it will be blinking at user-controllable amplitude and frequency, using a simple sine-wave shape for the intensity.

Step 1:
Define user-controlled variables. The source being set to Public Value means that the plugin will create a triggerable param for each of them. The sliders have a trigger defined on them, setting the individual values (not shown in the picture)

Step 2:
Define an expression variable at the LightHeart atom. This expression will update the angle to a value between 0 and 360 degrees. Sine of the angle will then later make the intensity blink. This is a bit more complex expressions, showing several features of the expression system:

1. Expressions can reference themselves. The plugin ensures that each variable will be evaluated at most once each frame. This means that we can use the frame's duration and the current variable's value to compute the next frame's value, which results a smooth transition/animation.
2. Expressions support conditional if-statements. In this example:
   • If the user-defined frequency is zero, the angle will smoothly transition towards the zero value. That will effectively stop the blinking, but not stop it at whatever angle it was when the frequency got set to zero, instead if will smoothly return to the neutral intensity.
   • Otherwise advance the angle by the frame's duration multiplied by the frequency, looping at 360 degrees ; the magical 6 multiplication factor is just 360/60, so the angle will advance by 360 per second when the frequency is 60 (and yes that's not Hz, that's beats per minute, I mistyped the slider's label)

Step 3:
Last step defines the actual Driver for the Intensity property of the Light atom. The complex math was all in the angle which drivers the flashing, this just applies the sine-wave multiplied by the amplitude, with the neutral intensity added. Rather simple.

And the video blow shows the result:

Spoiler: Video: User-controller blinking light

Example 2 - Morphs Controlled by Morphs​

This simple example controls the tongue length morph as 10-times the belly bulge 4 morph, which comes from the BodyLanguage plugin.
Realistically you would probably use the penetration depth to control something like this, and use a more complex morph setup. Probably with some kind of smoothing/delay (delay is quite tricky to implement exactly, but slow smoothing would do a similar trick).

Step 1:
Add a variable tracking the bulge's morph value. Remember that the morph must be marked as a "favorite" for it to show in VaM's geometry storable.

Step 2:
Set up drivers for any of the morphs controlled by SceneDirector on the atom. Naturally, you must first set up controlled morphs on the Morphs tab, not shown here. In the scene where I tested this, I already had a group of Face morphs configured, so I just chose the tongue length morph for this example.

And this is the result:

Spoiler: Video: Jackycracky's Tifa being spoiled by a dildo

New Variable Source - Param​

This allows you to track any public storable param of anything in the scene as a variable.
While usage of variables and expressions is still limited mostly to text formatting, you can already use this feature to show any boolean, floating-point or string param value in the scene on UI objects.

Other Changes​

• Support for SexyFluids v10.f4
  • Automatically create a component for each fluid emitter, including custom emitters.
  • Adding/renaming/removing emitters in SexyFluids will automatically refresh that atom's components in SceneDirector.
  • As a side-effect, SceneDirector will no longer take so long to initialize when controlling an atom with SexyFluids attached (it used to wait to see if it might be a female with alt-futa plugin before initializing the fluid components, now it can refresh whenever it needs to).
• Capturing SexyFluids state will now set the preset to none ("no change"), rather than the currently selected fluid preset.