Animation System

The Animation System offers a robust framework for managing animations on mesh objects. Whether you need simple playback or advanced control over timing, blending, and transitions, this system provides the tools to meet your requirements.

Overview

At its core, the Animation System facilitates animation playback for 3D models. Basic functions like playing and stopping animations cover most needs, while advanced options enable fine-tuned control for complex scenarios. These advanced features include adjusting playback speed, blending animations, and setting precise playback times to achieve synchronized and polished results.

The most commonly used functions are:

  • Play Animation: Starts a specified animation.

  • Stop Animation: Halts a specified animation.

Advanced control functions include:

  • Weight Control: Smoothly blend multiple animations by adjusting their weights.

  • Playback Speed: Modify animation speed, including reversing playback.

  • Normalized Time: Control playback progress using a normalized value (0 to 1).

  • Clamping and Unclamping: Pause an animation on its final frame or resume looping.

  • Animation Queries: Retrieve properties like duration, weight, and time scale for synchronization and calculations.

Basic Controls

To play an animation, use:

SgMesh:playAnimation("Running")

To stop the animation:

SgMesh:stopAnimation("Running")

Stopping an animation leaves it at its current frame. To reset it to the beginning, set the animation time to 0:

SgMesh:setAnimationTime("Running", 0)

Advanced Controls

Animation Weight

Control the visual influence of an animation on the mesh. Blending occurs when multiple animations have non-zero weights.

-- Set the animationWeight of the "Running" animation to 1
SgMesh:setAnimationWeight("Running", 1)

-- Gradually reduce the weight to 0 over 2 seconds
SgMesh:setAnimationWeight("Running", 0, 2)

-- Blend to 0.5 over 2 seconds starting from 0.2
SgMesh:setAnimationWeight("Running", 0.5, 2, 0.2)

If no starting weight is specified, the current value is used.

Note: Setting weight to 0 stops visual influence but doesn’t stop the animation. To prevent unwanted progression, also set the time scale to 0 (equivalent to stopAnimation).

Time Scale

Control the playback speed of animations:

-- Stop the "Running" animation
SgMesh:setAnimationTimeScale("Running", 0)

-- Reverse the "Running" animation over 2 seconds
SgMesh:setAnimationTimeScale("Running", -1, 2)

-- Accelerate playback to 1.5x speed over 3 seconds, starting at 0.5
SgMesh:setAnimationTimeScale("Running", 1.5, 3, 0.5)

If no starting time scale is provided, the current value is used. Setting time scale to 0 freezes the animation but retains visual influence (if weight is set to 1).

Timing Control

Set animation playback time using a normalized value (0 = start, 1 = end):

SgMesh:setAnimationTime("Death", 0.5)

Clamping and Unclamping

Pause an animation at its last frame with clamping. Useful for one-shot animations like a death sequence:

SgMesh:clampAnimation("Death")   -- Pause on end of animation
SgMesh:unclampAnimation("Death") -- Resume

Retrieve animation information

Get the absolute duration of an animation in seconds:

local duration = SgMesh:getAnimationDuration("Running")
print("Animation Duration:", duration)

Retrieve current weight or time scale:

local weight = SgMesh:getAnimationWeight("Running")
local timeScale = SgMesh:getAnimationTimeScale("Running")

Tips

Basic vs. Advanced Controls

playAnimation() and stopAnimation() are convenience functions that set both weight and time scale to 1 or 0. Avoid mixing these with manual adjustments to time scale and weight to prevent inconsistencies.