<!--
{
  "availability" : [
    "iOS: 18.0.0 -",
    "iPadOS: 18.0.0 -",
    "macCatalyst: 18.0.0 -",
    "macOS: 15.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/PlayAnimationAction",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation19PlayAnimationActionV"
  },
  "title" : "PlayAnimationAction"
}
-->

# PlayAnimationAction

An action that plays an animation on the given target entity with a range of playback options.

```
struct PlayAnimationAction
```

## Overview

Use this action to initiate the playback of animations in a data-driven way.
For example, this action can play an animation group which contains a nested action, which plays
another animation with specific playback properties.

This action plays the [`AnimationResource`](/documentation/RealityKit/AnimationResource) from the[`AnimationLibraryComponent`](/documentation/RealityKit/AnimationLibraryComponent) on the
[`targetEntity`](/documentation/RealityKit/PlayAnimationAction/targetEntity). Add all animations to the animation library
component that this action will play, ensuring the name of the animation matches the [`animationName`](/documentation/RealityKit/PlayAnimationAction/animationName)
being supplied.

[`useParentedControllers`](/documentation/RealityKit/PlayAnimationAction/useParentedControllers) is used to determine the playback
behavior of the animation this action is playing. Set this to `true` to control the playback of the
animation. Calling methods such as [`pause()`](/documentation/RealityKit/AnimationPlaybackController/pause()) and
[`resume()`](/documentation/RealityKit/AnimationPlaybackController/resume()) on the animation playback controller generated
from this action will give you control of the animation being played. When the action ends, the animation playback
also ends.
Set this to `false` to ensure the animation being played runs independently of the action. This would behave as
a one shot animation.

The example below is the animation group that the action will play. This contains a sequence containing
a single `FromToByAnimation<Transform>`, and character animation.

```swift
// Create an animation group sequence from a range of animations.
let finalAnimation = try AnimationResource
    .group(with: [walkAnimation, moveToAnimation])
```

The example below creates an animation sequence. The final animation in the sequence is an animation generated from the action.
This action plays an animation that exist within the [`targetEntity`](/documentation/RealityKit/PlayAnimationAction/targetEntity) [`AnimationLibraryComponent`](/documentation/RealityKit/AnimationLibraryComponent).

```swift
// An action which plays an animation, with parented controllers.
let playAnimationAction = PlayAnimationAction(animationName: "finalAnimation",
                                              transitionDuration: 0.2,
                                              useParentedControllers: true)

// Creates an animation from the action.
//
// Parented controllers is active. This ensures the action
// plays the entire length of the animation that is being played.
//
// The parameter `finalAnimationDuration` is set to the length
// of the animation group to play.
let finalPlayAnimation = try AnimationResource
    .makeActionAnimation(for: playAnimationAction,
                         duration: finalAnimationDuration)

// Create a sequence of animations that will play. 
//
// The action will play last in the sequence.
let animationSequence = try AnimationResource
    .sequence(with: [idleAnimation, startWalkAnimation, finalPlayAnimation])

// Play the sequence animation that will play the action last.
let animationPlaybackController = entity.playAnimation(animationSequence)
```

> Note: If ``doc://com.apple.RealityKit/documentation/RealityKit/PlayAnimationAction/useParentedControllers`` is set to `true`, the animation will play for the
> duration of the action. Set the duration of the action to match the length of the animation being played
> to ensure the entire animation plays.

> Important: This action does not animate a bound property, such as ``doc://com.apple.RealityKit/documentation/RealityKit/BindTarget/transform``.

## Topics

### Initializers

[`init(animationName: String, targetEntity: ActionEntityResolution, transitionDuration: TimeInterval, blendLayer: Int, separateAnimatedValue: Bool, useParentedControllers: Bool, handoffType: AnimationHandoffType)`](/documentation/RealityKit/PlayAnimationAction/init(animationName:targetEntity:transitionDuration:blendLayer:separateAnimatedValue:useParentedControllers:handoffType:))

Creates a new play animation action.

### Instance Properties

[`var animatedValueType: (any AnimatableData.Type)?`](/documentation/RealityKit/PlayAnimationAction/animatedValueType)

The type for the value that the action modifies over time.

[`var animationName: String`](/documentation/RealityKit/PlayAnimationAction/animationName)

The name of the animation resource within the target entity animation library component to start playing.

[`var blendLayer: Int`](/documentation/RealityKit/PlayAnimationAction/blendLayer)

An integer that specifies the order in which to apply animations when more than one animation is playing.

[`var handoffType: AnimationHandoffType`](/documentation/RealityKit/PlayAnimationAction/handoffType)

Type of handoff behavior between a currently-playing animation
and the new animation.

[`var separateAnimatedValue: Bool`](/documentation/RealityKit/PlayAnimationAction/separateAnimatedValue)

When set to false, this value indicates that the animation will write directly to the entity’s base value.
When set to true, this value indicates that the animation will write to an interim value for
the duration of the animation. If this value is set to true then when the
animation completes, the entity’s value will be reset to the base value.

[`var targetEntity: ActionEntityResolution`](/documentation/RealityKit/PlayAnimationAction/targetEntity)

The entity to play the animation.

[`var transitionDuration: TimeInterval`](/documentation/RealityKit/PlayAnimationAction/transitionDuration)

The duration in seconds over which the animation fades in or cross-fades.

[`var useParentedControllers: Bool`](/documentation/RealityKit/PlayAnimationAction/useParentedControllers)

A Boolean that indicates whether to parent the new animation’s controller to the controller managing this action.

## Relationships

### Conforms To

[`EntityAction`](/documentation/RealityKit/EntityAction)

[`Encodable`](/documentation/Swift/Encodable)

[`Decodable`](/documentation/Swift/Decodable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)