A component that represents a collection of animations that an entity can play.
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.
@Image(
source: realitycomposerpro-animationlibrary,
alt: "A screenshot of Reality Composer Pro showing the Animation Library in the Inspector. It contains two elements representing animations that have been added to the animation library. The animations are named walk and idle."
)
At runtime, your app can access and play the animations that the entity stores.
```swift
// 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 ``Entity/init(named:in:)``.
2. Retrieve the entity's animation resources from its ``Entity/availableAnimations`` property.
3. Add the animations to an animation library.
The following example shows how you can set up an animation library:
```swift
// 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.
```swift
// 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 ``Entity/playAnimation(_:transitionDuration:startsPaused:)`` method.
Creates an empty animation library.
- Parameter automaticallyPlaysDefaultAnimation: Whether to automatically play the
default animation when the entity is added to a scene and enabled. When `true`,
the animation system plays the default animation automatically. When `false`,
animations require manual playback. See ``automaticallyPlaysDefaultAnimation``
for details.
## Example
```swift
var library = AnimationLibraryComponent(automaticallyPlaysDefaultAnimation: true)
library.animations["walk"] = walkAnimation
library.defaultKey = "walk"
entity.components.set(library)
```
get · iOS 27.0+
automaticallyPlaysDefaultAnimation
TypeScript
get automaticallyPlaysDefaultAnimation(): boolean
Swift declaration
var automaticallyPlaysDefaultAnimation: Bool { get }
Whether to automatically play the default animation when the entity is added to a scene and enabled.
Default value is false, meaning the default animation will not be automatically played by default. This
value can only be set when initializing `AnimationLibraryComponent`
When set to `true`, the animation system automatically plays the default animation
when the entity is added to a scene and enabled. The animation that auto-plays is determined by
``AnimationLibraryComponent/defaultKey``. If `defaultKey` is set, the system plays the
animation stored under that key. If `defaultKey` is not set, the system plays the first animation in
the library. If the library contains no animations, auto-play has no effect.
This is useful for background objects with looping animations, idle character states, or any entity whose
animation should start without requiring code.
When set to `false`, animations require manual playback using
``Entity/playAnimation(_:transitionDuration:startsPaused:)``. Use manual playback when
you need to control timing, pass custom parameters, or coordinate animation start with other game logic.
Disabling the entity or removing the `AnimationLibraryComponent` will stop any auto-playing animation.
- Returns:
- `true` if automatically play default animation is enabled
- `false` if automatically play default animation is disabled
## Example
```swift
var library = AnimationLibraryComponent(automaticallyPlaysDefaultAnimation: true)
library["idle"] = idleAnimation
library.defaultKey = "idle"
entity.components.set(library)
// Animation plays automatically when the entity is added to a scene and enabled
```
get · iOS 18.0+
defaultAnimation
TypeScript
get defaultAnimation(): (AnimationResource) | null
Swift declaration
var defaultAnimation: AnimationResource? { get }
The default animation resource.
The component looks up the resource by key if ``AnimationLibraryComponent/defaultKey``
is non-`nil` and the library contains an animation that the key identifies.
Otherwise, the component returns the first entry in the library.
Creates an animation library from a dictionary that associates an animation’s data with its name.
- Parameter animations: A dictionary of animation resources that you key by name.
- Parameter automaticallyPlaysDefaultAnimation: Whether to automatically play the
default animation when the entity is added to a scene and enabled. When `true`,
the animation system plays the default animation automatically. When `false`,
animations require manual playback. See ``automaticallyPlaysDefaultAnimation``
for details.
## Example
```swift
var library = AnimationLibraryComponent(
animations: ["walk": walkAnimation, "run": runAnimation],
automaticallyPlaysDefaultAnimation: true)
library.defaultKey = "walk"
entity.components.set(library)
```
get · iOS 18.0+
animations
TypeScript
get animations(): AnimationLibraryComponent_AnimationCollection
Swift declaration
var animations: AnimationLibraryComponent.AnimationCollection
The collection of animations an entity can play.
set · iOS 18.0+
animations
TypeScript
set animations(value: AnimationLibraryComponent_AnimationCollection)
Swift declaration
var animations: AnimationLibraryComponent.AnimationCollection
Creates an animation library from a dictionary that associates an animation’s data with its name.
- Parameter animations: A dictionary of animation resources that you key by name.
get · iOS 18.0+
defaultKey
TypeScript
get defaultKey(): (string) | null
Swift declaration
var defaultKey: String? { get set }
The name of the default animation resource.
Returns `nil` if you don't set a default animation, or if the component can't find it.
set · iOS 18.0+
defaultKey
TypeScript
set defaultKey(value: (string) | null)
Swift declaration
var defaultKey: String? { get set }
The name of the default animation resource.
Returns `nil` if you don't set a default animation, or if the component can't find it.
get · iOS 18.0+
unkeyedResources
TypeScript
get unkeyedResources(): (Array<AnimationResource>) | null
Swift declaration
var unkeyedResources: [AnimationResource]? { get }
The library's animation resources that don't have a queryable name.
- Returns: An array of the animation resources that don't have a key; otherwise, `nil`.
Removes all the component's references to an animation resource.
- Parameter resource: An animation resource with references that the component removes.
init · iOS 18.0+
init
TypeScript
static init(): AnimationLibraryComponent
Swift declaration
init()
Creates an empty animation library.
Skipped declarations
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
