Runtime Configuration Data Explained

Overview

Each expression type (viseme, emote, head, eye, blink, etc.) is composed of one or more ExpressionComponent configurations. For example, SALSA maintains a list of viseme configurations as List<LipsyncExpression> visemes. Each viseme in the list has its configuration definition held in the expData field, which is of the type Expression. Within this data type, there are two lists you need to be aware of for runtime configuration. Each expression component has an entry in the following lists:

  1. List<ExpressionComponent> components: contains runtime data which is registered in the QueueProcessor each time an animation is triggered. If this data is not complete, it can result in runtime null-references.
  2. List<InspectorControllerHelperData> controllerVars: holds the serialized animation controller data as it is configured in Inspector. Since the individual controller types are extended from the base controller interface, serializing the controller data for the Custom Inspector is problematic. This collection of helper data is baked into the ExpressionComponent.controller at runtime startup.

NOTE: While it is technically not necessary to configure the expData.controllerVars data in a runtime setup, it is recommended to populate this data set to ensure the Inspector is updated correctly while testing design-time implementations and to utilize the existing codebase for controller baking.


So to summarize using SALSA as an example:

  • SALSA has one or more viseme configurations stored in List<LipsyncExpression> visemes
  • Each viseme is made up of one or more expression components, each have a definition contained in Salsa.visemes[index].<Expression>expData.
  • Within expData each ExpressionComponent configuration is defined in two index-matched lists:
    1. List<ExpressionComponent> components: defining the expression component's runtime data.
    2. List<InspectorControllerHelperData> controllerVars: defining the serialized data for design-time use in the Custom Inspector.

Path to Configuration Data

Each SALSA Suite module utilizes the same expression component configuration data structure. To access the configuration lists, the paths are as follows:

SALSA would look like this:

Salsa.visemes[index].expData.components[componentIndex]
Salsa.visemes[index].expData.controllerVars[componentIndex]

EmoteR is very similar:

Emoter.emotes[index].expData.components[componentIndex]
Emoter.emotes[index].expData.controllerVars[componentIndex]

And Eyes:

Eyes.eyes[index].expData.components[componentIndex]
Eyes.eyes[index].expData.controllerVars[componentIndex]
Eyes.heads[index].expData.components[componentIndex]
Eyes.heads[index].expData.controllerVars[componentIndex]
Eyes.blinklids[index].expData.components[componentIndex]
Eyes.blinklids[index].expData.controllerVars[componentIndex]
Eyes.tracklids[index].expData.components[componentIndex]
Eyes.tracklids[index].expData.controllerVars[componentIndex]

Configuration Data Detail

This section will focus on the ExpressionComponent data in the two expData lists as they pertain to runtime configuration.

Runtime Component Data

i.e. Salsa.visemes[index].expData.components[componentIndex]

Component data defines all fields required for runtime implementation of the ExpressionComponent. All aspects of this definition can be defined at runtime. However, it is recommended to use the List<InspectorControllerHelperData> controllerVars list to store the animation controller data and then bake the data into the controller using the built-in methods. This is primarily for design-time testing where the Inspector may be used to tune or trouble-shoot your scene at runtime. But, also automatically configures certain fields that are required for specific modules.

Common Component Data

For runtime configuration, the following fields are available for component configuration.

NOTE: Some fields are only used by certain modules (i.e. EmoteR) and others may only be used by certain controller types (i.e. bone controllers). For example: Timing usage varies between Suite modules. SALSA does not use the 'hold' timing and EmoteR can use the Delay timing.

Component Data Fields

Noteable fields within a <Expression>expData.List<ExpressionComponent>components list element:

<string> name: the name of the component.
<ExpressionComponent.ControlType> controlType: animation controller enum (i.e. Shape, Bone, Sprite, etc.).
<float> durationDelay: animation timing Delay -- only used by emotes.
<float> durationOn: animation timing On.
<float> durationHold: animation timing Hold.
<float> durationOff: animation timing Off. <bool> isPersistent: see module documentation for persistence.
<bool> useOffset: for bone definition
<bool> useOffsetFollow: for bone definition
<LerpEasings.EasingType> easing: Easing type, default: Cubic Out.
<bool> isAnimatorControlled: force animation mergeback mode. <IExpressionController> controller: typically baked with serialized field data.


Usage example: A SALSA viseme assuming at least one viseme with one ExpressionComponent defined:

Salsa salsa;
Expression expressionData = salsa.visemes[0].expData;
ExpressionComponent expressionComponent = expressionData.components[0];
expressionComponent.name = "component #1";
expressionComponent.controlType = ExpressionComponent.ControlType.Shape; // choose the appropriate animation controller.
expressionComponent.durationOn = 0.08f; // animation ON timing.
expressionComponent.durationHold = 0.00f; // animation HOLD timing -- not used in SALSA.
expressionComponent.durationOff = 0.08f; // animation OFF timing.

[2021-09-28] NOTE: Work in progress...more updates soon.