One Logo Pool Ball
X
Github
Discord

System

RealityFoundation · IOS API REFERENCE

PlayAnimationAction

struct · iOS 18.0+ · SDK 27.1

struct PlayAnimationAction

An action that plays an animation on the given target entity with a range of playback options. 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`` from the``AnimationLibraryComponent`` on the ``PlayAnimationAction/targetEntity``. Add all animations to the animation library component that this action will play, ensuring the name of the animation matches the ``PlayAnimationAction/animationName`` being supplied. ``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 ``AnimationPlaybackController/pause()`` and ``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 ``PlayAnimationAction/targetEntity`` ``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 ``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 ``BindTarget/transform``.

Members (15)

get · iOS 18.0+

blendLayer

TypeScript
get blendLayer(): number
Swift declaration
var blendLayer: Int

An integer that specifies the order in which to apply animations when more than one animation is playing. Animations in a lower layer are applied before animations in a higher layer. Animations in the same layer are applied in the order in which the animations where started.

set · iOS 18.0+

blendLayer

TypeScript
set blendLayer(value: number)
Swift declaration
var blendLayer: Int

An integer that specifies the order in which to apply animations when more than one animation is playing. Animations in a lower layer are applied before animations in a higher layer. Animations in the same layer are applied in the order in which the animations where started.

get · iOS 18.0+

handoffType

TypeScript
get handoffType(): AnimationHandoffType
Swift declaration
var handoffType: AnimationHandoffType

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

set · iOS 18.0+

handoffType

TypeScript
set handoffType(value: AnimationHandoffType)
Swift declaration
var handoffType: AnimationHandoffType

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

get · iOS 18.0+

targetEntity

TypeScript
get targetEntity(): ActionEntityResolution
Swift declaration
var targetEntity: ActionEntityResolution

The entity to play the animation.

set · iOS 18.0+

targetEntity

TypeScript
set targetEntity(value: ActionEntityResolution)
Swift declaration
var targetEntity: ActionEntityResolution

The entity to play the animation.

init · iOS 18.0+

init

TypeScript
static init(animationName: string, targetEntity?: ActionEntityResolution, transitionDuration?: number, blendLayer?: number, separateAnimatedValue?: boolean, useParentedControllers?: boolean, handoffType?: AnimationHandoffType): PlayAnimationAction
Swift declaration
init(animationName: String, targetEntity: ActionEntityResolution = .sourceEntity, transitionDuration: TimeInterval = 0.0, blendLayer: Int = 0, separateAnimatedValue: Bool = true, useParentedControllers: Bool = false, handoffType: AnimationHandoffType = .compose)

Creates a new play animation action. - Parameters: - animationName: The name of the animation resource within the target entity animation library component to start playing. - targetEntity: The entity to play the animation. - transitionDuration: The duration in seconds over which the animation fades in or cross-fades. - blendLayer: An integer that specifies the order in which to apply animations when more than one animation is playing. - 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. - useParentedControllers: Whether to parent the new animation's controller to the controller managing this action. - handoffType: Type of handoff behavior between a currently-playing animation and the new animation.

get · iOS 18.0+

animationName

TypeScript
get animationName(): string
Swift declaration
var animationName: String

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

set · iOS 18.0+

animationName

TypeScript
set animationName(value: string)
Swift declaration
var animationName: String

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

get · iOS 18.0+

transitionDuration

TypeScript
get transitionDuration(): number
Swift declaration
var transitionDuration: TimeInterval

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

set · iOS 18.0+

transitionDuration

TypeScript
set transitionDuration(value: number)
Swift declaration
var transitionDuration: TimeInterval

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

get · iOS 18.0+

separateAnimatedValue

TypeScript
get separateAnimatedValue(): boolean
Swift declaration
var separateAnimatedValue: Bool

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.

set · iOS 18.0+

separateAnimatedValue

TypeScript
set separateAnimatedValue(value: boolean)
Swift declaration
var separateAnimatedValue: Bool

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.

get · iOS 18.0+

useParentedControllers

TypeScript
get useParentedControllers(): boolean
Swift declaration
var useParentedControllers: Bool

A Boolean that indicates whether to parent the new animation's controller to the controller managing this action. Setting the value of this property to true indicates the action has control over the playback of the animation. Setting this to false indicates the animation plays independently from the action, behaving as a one shot animation

set · iOS 18.0+

useParentedControllers

TypeScript
set useParentedControllers(value: boolean)
Swift declaration
var useParentedControllers: Bool

A Boolean that indicates whether to parent the new animation's controller to the controller managing this action. Setting the value of this property to true indicates the action has control over the playback of the animation. Setting this to false indicates the animation plays independently from the action, behaving as a one shot animation

Skipped declarations

1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.

PlayAnimationAction.animatedValueType

Passing a Swift type itself is not supported.

All RealityFoundation types →