Contents

AnimationLibraryComponent

A component that represents a collection of animations that an entity can play.

Declaration

struct AnimationLibraryComponent

Overview

You use an AnimationLibraryComponent to access an entity’s animation resources. You can store animations with an entity by packaging them together into a .reality file. You can do this with Reality Composer Pro or by building a custom tool.

Create an animation library with Reality Composer Pro

Follow these steps to create an animation library for an entity:

  1. In the hierarchy view, select the entity you want to add animations to.

  2. In the inspector, click Add Component and select Animation Library from the list of components.

  3. Click the Add button (+) and select the USD files with animations.

At runtime, your app can access and play the animations that the entity stores.

// Load the entity you want to animate.
let robot = try await Entity(named: "robot")

// Access the animation library associated with the entity.
let animationLibrary = robot.components[AnimationLibraryComponent.self]

// Play the walk animation.
if let walkAnimation = animationLibrary.animations["walk"] {
    robot.playAnimation(walkAnimation)
}

Create an animation library by building your own tool

If you need to build a custom tool to create .reality files, you can use RealityKit to programmatically create an animation library by following these steps:

  1. Load an animation entity with init(named:in:).

  2. Retrieve the entity’s animation resources from its availableAnimations property.

  3. Add the animations to an animation library.

The following example shows how you can set up an animation library:

// Create an empty animation library component.
var animationLibrary = AnimationLibraryComponent()

// Load the entities containing the animations.
let entityIdleAnimation = try await Entity(named: "idle")
let entityWalkAnimation = try await Entity(named: "walk")

// Assign the animations to the library by name.
animationLibrary.animations["idle"] = entityIdleAnimation.availableAnimations.first
animationLibrary.animations["walk"] = entityWalkAnimation.availableAnimations.first

After you configure the animation library, you can assign it to an entity and serialize the entity to a file. RealityKit packages the animations for that entity when you save it to a .reality file.

// Load the entity you want to animate.
let robot = try! await Entity(named: "robot")

// Assign the animation library to the entity.
robot.components.set(animationLibrary)

// Write the entity with its animations to a file.
robot.write(to: fileURL)

To play one of the animations in your app, create an entity from the .reality file and then call its playAnimation(_:transitionDuration:startsPaused:) method.

Topics

Creating an animation library component

Accessing animations

Managing references to animations

Structures

See Also

Animation playback