Overview for Eyes.cs

The Eyes module inspector is similar in design to SALSA and EmoteR, but is template-driven to help ensure a valid design-time configuration is achieved. However, you may still want programmatic run-time control to make settings changes. Eyes has an underlying API that provides this functionality, allowing developers to programmatically configure and control your workflow. SALSA LipSync Suite, which includes the Eyes module, is a complete re-write of the original v1 code, and Eyes was pulled out of RandomEyes into its own module, therefore the previous RandomEyes API is not valid for SALSA LipSync Suite.

The following properties and methods are available for: CrazyMinnow.SALSA.Eyes.cs

Properties (for Eyes configuration)

There are many public fields available in the Eyes library. Most of these are implemented for Eyes runtime configuration and control.

System Properties

Character Root Transform characterRoot

This provides Eyes with a character forward direction reference.

QueueProcessor QueueProcessor queueProcessor

A QueueProcessor is a required reference link needed to initiate priority-based animations. If setting SALSA up in a runtime environment, a QueueProcessor must be instantiated and SALSA must know where it is.

Look Target Transform lookTarget

When configured, Setting the look target activates head, eye, and eyelid tracking on that target.


Affinity bool useAffinity

Affinity towards a tracked target, similar to attention span.

Percentage [Range(0f, 1f)] float affinityPercentage = 0.75f

Specify the percentage of time the character should stay focused on the target. Drops into random mode when random head or eyes are enabled.

Timer Vector2 affinityTimerRange = Vector2(2f, 5f)

Min/Max timer range for affinity updates.

Has Affinity bool hasAffinity

Tracks the affinity state.


Update Delay [Range(0f, 1f)] float updateDelay = 0.07

The delay in seconds between analysis updates. The default is typically fine.


Sprite Flipping bool useSpriteFlipping

Select this to automatically flip tracking calculations with scale or sprite axis.

Flip Type enum FlipType flipType

Do you flip your 2D characters direction using Transform scale or SpriteRenderer axis? FlipType.Transform_X FlipType.Transform_Y FlipType.SpriteRenderer_X FlipType.SpriteRenderer_Y

Flip Reference

Transform flipScale
Link to the Transform used to flip scale on the X or Y axis.
SpriteRenderer flipSprite
Link to the SpriteRenderer used to flip a Sprite the X or Y axis.
bool flipState
Tracks the flip state. (true = flipped left, false = right)


Parent Random Targets

When enabled, the random head and eye targets will be parented to the character root.
void ParentRandomTargets(bool status)

Show Scene Gizmos bool showSceneGizmos

Scene gizmos help to demonstrate the effects of changing properties.


Cancel Animation List<AnimCancel> animCancel

Link any bones here when you want their mecanim animation to be canceled out.

Head Configuration

Some properties are only visible in certain templates

Enable Processing

Enable/disable head processing.
void EnableHead(bool status)

Head Templates enum HeadTemplates

When setting the head template from code, use the following method:
void BuildHeadTemplate(HeadTemplates headTemplate)

  • HeadTemplates.None (No head configured)
  • HeadTemplates.Bone_Rotation_XY (Rotation on the X and Y axis. Typical of a 3D character)
    Defaults to one head expression with one Transform component.
  • HeadTemplates.Bone_Rotation_Z (Rotation on the Z axis. Typical of a 2D character)
    Defaults to one head expression with one Transform component.

Target Offset Vector3 headTargetOffset

Since there is typically a vertical gap between the head bone and eye bones, you may want a vertical offset of the head target to ensure random position generation and tracking keep the head and eyes aligned in a natural way.

Rotation Clamp Vector3 headClamp

Head maximum horizontal(Y), vertical(X), or rotational(Z) degrees of movement before clamping.

Facing Camera bool headFacingCamera

If your 2D character faces the camera, use this to flip the head tracking calculations automatically when a tracked target moves from left to right.


Random bool headRandom

Generate random head movement when no target is linked or affinity is enabled and the character currently has no affinity.

FoV Degrees Vector3 headRandomFov

Head random movement field of view in degrees: Vertical(X), horizontal(Y), or rotational(Z).

Timer Vector2 headRandTimerRange

Min/Max timer range for random head movement.

Distance Vector2 headRandDistRange

Min/Max random head position range.


Target Gizmo float headTargetRadius

Scene target gizmo radius (the green sphere).

Fix Axis / Restore Axis

Unity uses a left handed coordinate system. If your characters head bone is not aligned to this system, you must use this option to automatically apply corrective hierarchy. X positive (Right) Y positive (up) * Z positive (forward)

Fix: void FixAllTransformAxes(ref eyes.heads, true)
Restore: void FixAllTransformAxes(ref eyes.heads, false)


Head Expression

Name String

Access the expression name field using an Eyes reference:
eyes.heads[expressionIndex].expData.name


Head Component

Name String

Access the component name field using an Eyes reference:
eyes.heads[expressionIndex].expData.components[componentIndex].name

Animation Timings (On) bool

Access the animation On timing using an Eyes reference:
eyes.heads[expressionIndex].expData.components[componentIndex].durationOn

Disable Smoothly bool

Access smooth disable using an Eyes reference:
eyes.heads[expressionIndex].expData.components[componentIndex].isSmoothDisable

Easing enum LerpEasings.EasingType

Access animation easing types using an Eyes reference:
eyes.heads[expressionIndex].expData.components[componentIndex].easing

Bone/Transform Transform

Access the bone slot using an Eyes reference:
eyes.heads[expressionIndex].expData.controllerVars[componentIndex].bone


Eye Configuration

Some properties are only visible in certain templates

Enable Processing

Enable/disable eye processing.
void EnableEye(bool status)

Eye Templates enum EyeTemplates

When setting the eye template from code, use the following method:
void BuildEyeTemplate(EyeTemplates eyeTemplate)

  • EyeTemplates.None (No eyes configured)
  • EyeTemplates.Bone_Rotation (Rotation on the X and Y axis. Typical of a 3D character)
    Defaults to two eye expressions with one Transform component on each.
  • EyeTemplates.Bone_Position (Position on the X and Y axis. Typical of a 2D character)
    Defaults to two eye expressions with one Transform component on each.
  • EyeTemplates.BlendShapes
    Defaults to two eye expressions with four SkinnedMeshRenderer components on each (up, right, down, left).
  • EyeTemplates.Sprite_Sectors
    Defaults to one eye expression with one Sprite component per sector.
  • EyeTemplates.Texture_Sectors
    Defaults to one eye expression with one Texture component per sector.
  • EyeTemplates.Material_Sectors
    Defaults to one eye expression with one Material component per sector.

Sector Count enum SectorCount sectorCount

When using a sector template, set the sectorCount, then pass it to the BuildEyeSectorTemplate method:
sectorCount = SectorCount.Nine

  • SectorCount.Two (left, right)
  • SectorCount.Three (left, center, right)
  • SectorCount.Five (center, up, right, down, left)
  • SectorCount.Nine (center, up, upRight, right, downRight, down, downLeft, left, upLeft)

void BuildEyeSectorTemplate(SectorCount, ExpressionComponent.ControlType, bool);
Passing true will clear the eyes expression list before building the template.

2D Processing bool eye2DProcessing

2D processing tracks and generates random on a plane perpendicular to the characters forward direction.


Clamp Degrees Vector3 eyeClamp = Vector3(25f, 45f, 0f)

Clamps eye rotation on the vertical(X) and horizontal(Y) axes.

Range of Motion float eyeRangeOfMotion2D

Positional range of motion. For 2D eyes that orbit around the Z/forward axis.


Random bool eyeRandom

Enable random eye movement.

Fov Degrees Vector3 eyeRandomFov = Vector3(2.5f, 5f, 10f)

Eye random movement field of view in degrees: vertical(X), horizontal(Y), or rotational(Z). Used when there is no look target or randomly generated head target.

Fov Offset Vector2 eyeRandTrackFov = Vector2(0.1f, 0.05f)

Eye random movement maximum horizontal and vertical offset from a target. This could be the look target in System Properties or a random generated head target position (saccadic movement).

Timer Vector2 eyeRandTimerRange = Vector2(0.25f, 1f)

Min/Max timer range for random eye movement.

Distance Vector2 eyeRandDistRange = Vector2(1f, 1f)

Min/Max random eye position distance.


Target Gizmo float eyeTargetRadius

Scene target gizmo radius (the yellow sphere).


Proportional Movement

When using the Bone_Position template for eyes that orbit around the Z/forward axis, you can use this if your character has different sized eyes and want them to move proportionally. All eyes must be linked before use.
void CalculateProportionalEye()

Fix Axis / Restore Axis

Unity uses a left handed coordinate system. If your characters eye bones are not aligned to this system, you must use this option to automatically apply corrective hierarchy. X positive (Right) Y positive (up) * Z positive (forward)

Fix: void FixAllTransformAxes(ref eyes.eyes, true)
Restore: void FixAllTransformAxes(ref eyes.eyes, false)


Eye Expression

Create Gizmo

Blendshape eyes need at least one manually created eye gizmo. Since Eyes does not know where a blendshape-based eye is, the gizmo serves as our point of reference for tracking calculations. Each independently blendshape controlled eye should have it's own gizmo. The gizmo need to be parented to the characters head, and positioned where the eye is (or between the eyes for multiple eyes controlled with one set of blendshapes). Use the method below to create a gizmo and use it's returned reference to position and parent it correctly.
EyeGizmo CreateEyeGizmo(string name, Transform parent)

Name String

Access the expression name field using an Eyes reference:
eyes.eyes[expressionIndex].expData.name


Eye Component

Name String

Access the component name field using an Eyes reference. Blendshape and Sector templates use a special component naming convention that must remain unmodified.
eyes.eyes[expressionIndex].expData.components[componentIndex].name

Animation Timings (On) bool

Access the animation On timing using an Eyes reference:
eyes.eyes[expressionIndex].expData.components[componentIndex].durationOn

Disable Smoothly bool

Access smooth disable using an Eyes reference:
eyes.eyes[expressionIndex].expData.components[componentIndex].isSmoothDisable

Easing enum LerpEasings.EasingType

Access animation easing types using an Eyes reference:
eyes.eyes[expressionIndex].expData.components[componentIndex].easing

Component Dynamics float

Adjusts the range of overall expression component movement. eyes.eyes[expressionIndex].expData.components[componentIndex].frac

Controller Type enum ControlType

Don't use this, use the BuildEyeTemplate method instead.

Controller SkinnedMeshRenderer, Transform, Sprite, Texture, Material, UMA

Access the controller slot using an Eyes reference:
eyes.eyes[expressionIndex].expData.controllerVars[componentIndex].smr
eyes.eyes[expressionIndex].expData.controllerVars[componentIndex].bone
eyes.eyes[expressionIndex].expData.controllerVars[componentIndex].sprites
eyes.eyes[expressionIndex].expData.controllerVars[componentIndex].textures
eyes.eyes[expressionIndex].expData.controllerVars[componentIndex].materials
eyes.eyes[expressionIndex].expData.controllerVars[componentIndex].umaUepProxy


Eyelid Configuration

Some properties are only visible in certain templates

Enable Processing

Enable/disable eyelid processing.
void EnableEyelid(bool status)

Eyelid Templates enum EyeTemplates

When setting the eyelid template from code, use the following method:
void BuildEyelidTemplate(EyelidTemplates eyelidTemplate)

  • EyelidTemplates.None
    No eye configured
  • EyelidTemplates.Bone_Rotation (Rotation on the X and Y axis.)
    Defaults to two eyelid expressions with two Transform components on each (upper, lower).
  • EyelidTemplates.Bone_Position (Position on the X and Y axis.)
    Defaults to two eyelid expressions with two Transform components on each (upper, lower).
  • EyelidTemplates.BlendShapes
    Defaults to two eyelid expressions with the number of SkinnedMeshRenderer components matching the Eyelid Selection option in properties (both=2, upper=1, lower=1).
  • EyelidTemplates.Sprite_Swap
    Defaults to two eyelid expressions with one Sprite component on each.
  • EyelidTemplates.Texture_Swap
    Defaults to two eyelid expressions with one Material component on each.
  • EyelidTemplates.Material_Swap
    Defaults to two eyelid expressions with one Texture component on each.
  • EyelidTemplates.UMA
    Defaults to two eyelid expressions with the number of UMA components matching the Eyelid Selection option in properties (both=2, upper=1, lower=1).

Random bool blinkRandom

Enable random blinking.

Timer Vector2 blinkRandTimerRange = Vector2(0.5f, 5f)

Min/Max timer range for random blinking.

Eyelid Selection enum EyelidSelection

Select upper lids only, lower lids only, or both upper and lower lids.
void SetEyelidShapeSelection(EyelidSelection selection)

  • EyelidSelection.Both
  • EyelidSelection.Upper
  • EyelidSelection.Lower

Track Eyes bool eyelidTracking

When enabled, eyelids will track eye movement. Tracking won't work if your upper and lower lids are controlled by a single control (like the boxhead test character).

Timing (On) float eyelidTrackDuration

Eyelid tracking animation on duration. The amount of time it take to move the lids towards a new target position.

Percent of Eyes [Range(0f, 1f)] float eyelidPercentEyes = 0.5f

Eyelids will move a percentage of the eye movement.


Eyelid Expression

Name String

Access the expression name field using an Eyes reference:
eyes.eyelids[expressionIndex].expData.name


Eyelid Component

Name String

Access the component name field using an Eyes reference. The blendshape template uses a special component naming convention that must remain unmodified.
eyes.eyelids[expressionIndex].expData.components[componentIndex].name

Animation Timings (On) bool

Access the animation On timing using an Eyes reference:
eyes.eyelids[expressionIndex].expData.components[componentIndex].durationOn

Animation Timings (Hold) bool

Access the animation Hold timing using an Eyes reference:
eyes.eyelids[expressionIndex].expData.components[componentIndex].durationHold

Animation Timings (Off) bool

Access the animation Off timing using an Eyes reference:
eyes.eyelids[expressionIndex].expData.components[componentIndex].durationOff

Disable Smoothly bool

Access smooth disable using an Eyes reference:
eyes.eyelids[expressionIndex].expData.components[componentIndex].isSmoothDisable

Easing enum LerpEasings.EasingType

Access animation easing types using an Eyes reference:
eyes.eyelids[expressionIndex].expData.components[componentIndex].easing

Component Dynamics float

Adjusts the range of overall expression component movement. eyes.eyelids[expressionIndex].expData.components[componentIndex].frac

Controller Type enum ControlType

Don't use this, use the BuildEyeTemplate method instead.

Controller SkinnedMeshRenderer, Transform, Sprite, Texture, Material, UMA

Access the controller slot using an Eyes reference:
eyes.eyelids[expressionIndex].expData.controllerVars[componentIndex].smr eyes.eyelids[expressionIndex].expData.controllerVars[componentIndex].bone eyes.eyelids[expressionIndex].expData.controllerVars[componentIndex].sprites eyes.eyelids[expressionIndex].expData.controllerVars[componentIndex].textures eyes.eyelids[expressionIndex].expData.controllerVars[componentIndex].materials eyes.eyelids[expressionIndex].expData.controllerVars[componentIndex].umaUepProxy

Methods

void ParentRandomTargets(bool status)

Set random head and eye targets to be parented to the characterRoot or the scene root.

AxisFixed FixTransformAxis(ref List<EyesExpression> expressions, int expIdx, int comIdx, bool fix)

Fix a transform axis for a specific expression component.

void FixAllTransformAxes(ref List<EyesExpression> expressions, bool fix)

Fix all transform axes in the heads, eyes, or eyelids lists.
FixAllTransformAxes(ref eyes.heads, 0, 0, true)
FixAllTransformAxes(ref eyes.eyes, 0, 0, true)
FixAllTransformAxes(ref eyes.eyelids, 0, 0, true)

Transform AddParent(Transform child)

Add and return a parent to Transform parameter.

void BuildHeadTemplate(HeadTemplates headTemplate)

Build a head template.

void BuildEyeTemplate(EyeTemplates eyeTemplate)

Build an eye template.

void BuildEyelidTemplate(EyelidTemplates eyelidTemplate)

Build an eyelid template.

void AddBoneExpression(ref List<EyesExpression> expressions, ExpressionComponent.ExpressionType expressionType)

Add a new bone expression.
AddBoneExpression(ref eyes.heads, ExpressionComponent.ExpressionType.Head)
AddBoneExpression(ref eyes.eyes, ExpressionComponent.ExpressionType.Eye)
AddBoneExpression(ref eyes.eyelids, ExpressionComponent.ExpressionType.Eyelid)

void AddBoneComponent(ref List<EyesExpression> expressions, int expIdx, ExpressionComponent.ExpressionType expressionType)

Add a new bone component to a bone expression.
AddBoneComponent(ref eyes.heads, 0, ExpressionComponent.ExpressionType.Head)
AddBoneComponent(ref eyes.eyes, 0, ExpressionComponent.ExpressionType.Eye)
AddBoneComponent(ref eyes.eyelids, 0, ExpressionComponent.ExpressionType.Eyelid)

void AddEyeShapeExpression()

Add a new eye shape expression.

void AddEyeSectorExpression()

Add a new eye sector expression.

void AddEyelidShapeExpression()

Add a new eyelid shape expression.

void AddEyelidSwapExpression(ExpressionComponent.ControlType controlType)

Add a new eyelid swap expression.

void AddEyelidSwapComponent(int expIdx, ExpressionComponent.ControlType controlType)

Add a new eyelid swap component.

void AddEyelidUMAExpression()

Add a new eyelid UMA expression.

bool RemoveExpression(ref List<EyesExpression> expressions, int expIdx)

Remove any expression.
RemoveExpression(ref eyes.heads, 0)
RemoveExpression(ref eyes.eyes, 0)
RemoveExpression(ref eyes.eyelids, 0)

bool RemoveComponent(ref List<EyesExpression> expressions, int expIdx, int comIdx)

Remove any component.
RemoveComponent(ref eyes.heads, 0, 0)
RemoveComponent(ref eyes.eyes, 0, 0)
RemoveComponent(ref eyes.eyelids, 0, 0)

void CaptureMin(ref List<EyesExpression> expressions)

When setting up blink bones, use this to capture the rest state.

void CaptureMax(ref List<EyesExpression> expressions)

When setting up blink bones, use this to capture the max extent state.

void ReturnMin(ref List<EyesExpression> expressions)

When setting up blink bones, use this to return to the rest state after capturing the max state.

void SetEyelidShapeSelection(EyelidSelection selection)

Set the eyelid shape selection to both, upper, or lower eyelids.

  • EyelidSelection.Both
  • EyelidSelection.Upper
  • EyelidSelection.Lower

void CalculateProportionalEye()

When using the Bone_Position template for eyes that orbit around the Z/forward axis, you can use this if your character has different sized eyes and want them to move proportionally. All eyes must be linked before use.

void NewRandomHeadTarget()

Generate a new random head target position.

void NewRandomEyeTarget()

Generate a new random eye target position.

void NewBlink()

Perform a blink using the inspector On, Hold, and Off timings.

void NewBlink(float on, float hold, float off)_

Perform a blink using custom one-time timings for On, Hold, and Off.

static void FindTransform(Transform characterRoot, string regexSearch)

Use this to search the characters hierarchy using a regular expression search string.

static void FindBlendIndex(SkinnedMeshRenderer smr, string regexSearch)

Use this to search a SkinnedMeshRenderer for a blendshape name using regular expression.

void UpdateRuntimeExpressionControllers(ref List<EyesExpression> expressions)

When setup up a character at runtime, call this for each Eyes module being used. This is the last step before calling Initialize().
UpdateRuntimeExpressionControllers(ref eyes.heads)
UpdateRuntimeExpressionControllers(ref eyes.eyes)
UpdateRuntimeExpressionControllers(ref eyes.eyelids)

void Initialize()

When setting up a character at runtime, call this last after everything else is setup.