Skip to content

Enabling Animation in Untold Engine

The Untold Engine simplifies adding animations to your rigged models, allowing for lifelike movement and dynamic interactions. This guide will show you how to set up and play animations for a rigged model.

How to Enable Animation

Step 1: Create an Entity

Start by creating an entity to represent your animated model.

let redPlayer = createEntity()

Load your rigged model's .untold runtime asset and link it to the entity. This step ensures the entity is visually represented in the scene.

setEntityMesh(entityId: redPlayer, filename: "redplayer", withExtension: "untold")

Step 3: Load the Animation

Load the animation data for your model by providing the exported animation .untold file and a name to reference the animation later.

setEntityAnimations(entityId: redPlayer, filename: "running", withExtension: "untold", name: "running")

For hierarchical or multi-mesh .untold assets, call animation APIs on the asset root. The engine resolves the root to every skinned render descendant and installs the clip on each target that has both a SkeletonComponent and a RenderComponent. This keeps split characters or multi-part rigged models animated as one actor.

Step 4: Set the Animation to play

Trigger the animation by referencing its name. This will set the animation to play on the entity.

changeAnimation(entityId: redPlayer, name: "running")

changeAnimation(entityId:name:withPause:), pauseAnimationComponent(entityId:isPaused:), setAnimationPlaybackSpeed(entityId:speed:), and removeAnimationClip(entityId:animationClip:) all operate on the entity and any descendant animation components. getAllAnimationClips(entityId:) returns the union of clip names found under the entity. getAnimationPlaybackSpeed(entityId:) returns the speed from the first resolved animation component.

Step 5. Pause the animation (Optional)

To pause the current animation, simply call the following function. The animation component will be paused for the current entity.

pauseAnimationComponent(entityId: redPlayer, isPaused: true)

Running the Animation

Once the animation is set up:

  1. Run the project: Your model will appear in the game window.
  2. Click on "Play" to enter Game Mode:
  3. The model will play the assigned animation in real time.

Tips and Best Practices

  • Name Animations Clearly: Use descriptive names like "running" or "jumping" to make it easier to manage multiple animations.
  • For split rigged assets, treat the load root as the public animation handle; do not manually chase child mesh entities unless you need custom per-part behavior.
  • Debug Orientation Issues: If the model’s animation appears misaligned, revisit the flip parameter or check the model’s export settings.
  • Combine Animations: For complex behaviors, load multiple animations (e.g., walking, idle, jumping) and switch between them dynamically.