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

# SampledAnimation

An animation that cycles through a series of frames at a constant interval.

```
struct SampledAnimation<Value> where Value : AnimatableData
```

## Overview

To specify the data that the animation samples, set one of the `frames`
properties that matches the animated property’s type. For example, set the
[`frames`](/documentation/RealityKit/SampledAnimation/frames-2j4nj) property to interpolate
<doc://com.apple.documentation/documentation/Swift/Float> values.

The following code designates a [`SampledAnimation`](/documentation/RealityKit/SampledAnimation) to animate a propery of
type <doc://com.apple.documentation/documentation/Swift/Float> by specifying
the generic typed syntax. The code queues an array of values: `1.0`, `2.0`,
and `3.0`.

```swift
// Define the animation type.
typealias SampledAnimationType = SampledAnimation<Float>

// Define the animated property values.
let frameArray: [Float] = [1.0, 2.0, 3.0]
```

To determine how fast the animation progresses from frame to frame, define
this structure’s [`frameInterval`](/documentation/RealityKit/SampledAnimation/frameInterval) property. The following
code specifies a one-second delay between value changes before initializing
the animation object.

```swift
// Define a one-second frame interval.
let interval: TimeInterval = 1

// Create the animation.
let sampleAnim = SampledAnimationType(
    frames: frameArray,
    name: "sampledAnim1",
    frameInterval: interval
    isAdditive: true,
    bindTarget: .transform,
    blendLayer: 100,
    repeatMode: .autoReverse,
    fillMode: .backwards,
    trimStart: 1.0,
    trimEnd: 10.0,
    trimDuration: 9.0,
    offset: 2.0,
    delay: 1.0,
    speed: 2.0
)
```

## Topics

### Creating an animation

[`init(frames: [Value], name: String, tweenMode: TweenMode, frameInterval: Float, isAdditive: Bool, bindTarget: BindTarget?, blendLayer: Int32, repeatMode: AnimationRepeatMode, fillMode: AnimationFillMode, trimStart: TimeInterval?, trimEnd: TimeInterval?, trimDuration: TimeInterval?, offset: TimeInterval, delay: TimeInterval, speed: Float)`](/documentation/RealityKit/SampledAnimation/init(frames:name:tweenMode:frameInterval:isAdditive:bindTarget:blendLayer:repeatMode:fillMode:trimStart:trimEnd:trimDuration:offset:delay:speed:))

Creates an animation with a collection of frames that represent
incremental steps in the overall timeline.

[`init(jointNames: [String], frames: [Value], name: String, tweenMode: TweenMode, frameInterval: Float, isAdditive: Bool, isScaleAnimated: Bool, isRotationAnimated: Bool, isTranslationAnimated: Bool, bindTarget: BindTarget?, blendLayer: Int32, repeatMode: AnimationRepeatMode, fillMode: AnimationFillMode, trimStart: TimeInterval?, trimEnd: TimeInterval?, trimDuration: TimeInterval?, offset: TimeInterval, delay: TimeInterval, speed: Float)`](/documentation/RealityKit/SampledAnimation/init(jointNames:frames:name:tweenMode:frameInterval:isAdditive:isScaleAnimated:isRotationAnimated:isTranslationAnimated:bindTarget:blendLayer:repeatMode:fillMode:trimStart:trimEnd:trimDuration:offset:delay:speed:))

Creates an animation that interpolates between two configurations of the
given joints.

### Configuring the animation

[`var name: String`](/documentation/RealityKit/SampledAnimation/name)

A textual name for the animation.

[`var bindTarget: BindTarget`](/documentation/RealityKit/SampledAnimation/bindTarget)

A textual name that identifies the particular property that animates.

[`var blendLayer: Int32`](/documentation/RealityKit/SampledAnimation/blendLayer)

The order in which the framework composites the animation.

[`var jointNames: [String]`](/documentation/RealityKit/SampledAnimation/jointNames)

The names of the joints to animate.

[`var isRotationAnimated: Bool`](/documentation/RealityKit/SampledAnimation/isRotationAnimated)

A Boolean value that indicates whether the animation observes rotational
changes in the entity’s transform.

[`var isScaleAnimated: Bool`](/documentation/RealityKit/SampledAnimation/isScaleAnimated)

A Boolean value that indicates whether the animation observes changes in
the entity’s size.

[`var isTranslationAnimated: Bool`](/documentation/RealityKit/SampledAnimation/isTranslationAnimated)

A Boolean value that indicates whether the animation observes
translational changes in the entity’s transform.

[`var additive: Bool`](/documentation/RealityKit/SampledAnimation/additive)

A Boolean value that indicates whether the animation builds on the
current state of the target entity or resets the state before running.

[`var tweenMode: TweenMode`](/documentation/RealityKit/SampledAnimation/tweenMode)

An option that determines how animation frames transition.

### Defining frames data

[`var frames: [JointTransforms]`](/documentation/RealityKit/SampledAnimation/frames-4eeex)

An array of joint transforms in which each element represents a discrete
state of the target entity at a given point in the animation’s timeline.

[`var frames: [Transform]`](/documentation/RealityKit/SampledAnimation/frames-4qotl)

An array of transforms in which each element represents a discrete state
of the target entity at a given point in the animation’s timeline.

[`var frames: [Double]`](/documentation/RealityKit/SampledAnimation/frames-2hobp)

An array of double-precision values in which each element represents a
discrete state of the animated property at a given point in the
animation’s timeline.

[`var frames: [Float]`](/documentation/RealityKit/SampledAnimation/frames-2j4nj)

An array of floating-point values in which each element represents a
discrete state of the animated property at a given point in the
animation’s timeline.

[`var frames: [simd_quatf]`](/documentation/RealityKit/SampledAnimation/frames-2h6tu)

An array of quaternions in which each element represents a discrete
state of the animated property at a given point in the animation’s
timeline.

[`var frames: [SIMD2<Float>]`](/documentation/RealityKit/SampledAnimation/frames-9luwf)

An array of floating-point pairs in which each element represents a
discrete state of the animated property at a given point in the
animation’s timeline.

[`var frames: [SIMD3<Float>]`](/documentation/RealityKit/SampledAnimation/frames-1zxo)

An array of floating-point triplets in which each element represents a
discrete state of the animated property at a given point in the
animation’s timeline.

[`var frames: [SIMD4<Float>]`](/documentation/RealityKit/SampledAnimation/frames-2ywfx)

An array of floating-point quadruples in which each element represents a
discrete state of the animated property at a given point in the
animation’s timeline.

### Timing the animation

[`var frameInterval: Float`](/documentation/RealityKit/SampledAnimation/frameInterval)

The duration within the animation timeline for each frame in the frames
array.

[`var start: TimeInterval`](/documentation/RealityKit/SampledAnimation/start)

An integer multiple of the frame interval at which the animation plays.

[`var end: TimeInterval`](/documentation/RealityKit/SampledAnimation/end)

An integer multiple of the frame interval at which the animation stops.

[`var speed: Float`](/documentation/RealityKit/SampledAnimation/speed)

A factor that changes the animation’s rate of playback.

[`var delay: TimeInterval`](/documentation/RealityKit/SampledAnimation/delay)

An amount of time that elapses before the animation plays.

[`var duration: TimeInterval`](/documentation/RealityKit/SampledAnimation/duration)

The total playback time of the animation.

[`var offset: TimeInterval`](/documentation/RealityKit/SampledAnimation/offset)

The time, in seconds, at which the animation begins within the duration.

[`var trimDuration: TimeInterval?`](/documentation/RealityKit/SampledAnimation/trimDuration)

An optional duration that overrides the calculated duration.

[`var trimStart: TimeInterval?`](/documentation/RealityKit/SampledAnimation/trimStart)

The optional time, in seconds, at which the animation plays.

[`var trimEnd: TimeInterval?`](/documentation/RealityKit/SampledAnimation/trimEnd)

The optional time, in seconds, at which the animation stops.

### Repeating animation playback

[`var repeatMode: AnimationRepeatMode`](/documentation/RealityKit/SampledAnimation/repeatMode)

An option that determines how the animation repeats.

[`var fillMode: AnimationFillMode`](/documentation/RealityKit/SampledAnimation/fillMode)

An option that determines which data displays outside of the normal
duration.

### Processing skeletal animations

[`func processAndCreateAnimation(retargeting: RetargetingConfiguration, operations: [SampledAnimation<Value>.SkeletalAnimationOperation], name: String) throws -> any AnimationDefinition`](/documentation/RealityKit/SampledAnimation/processAndCreateAnimation(retargeting:operations:name:))

Processes skeletal animation with the specified retargeting and operations.

[`func processAndCreateAnimation(for: SkeletonResource?, operations: [SampledAnimation<Value>.SkeletalAnimationOperation], name: String) throws -> any AnimationDefinition`](/documentation/RealityKit/SampledAnimation/processAndCreateAnimation(for:operations:name:))

Processes skeletal animation with the specified operations.

[`struct SkeletalAnimationOperation`](/documentation/RealityKit/SampledAnimation/SkeletalAnimationOperation)

Operations that can be performed on skeletal animations.

### Initializers

[`init(weightNames: [String], frames: [Value], name: String, tweenMode: TweenMode, frameInterval: Float, isAdditive: Bool, bindTarget: BindTarget?, blendLayer: Int32, repeatMode: AnimationRepeatMode, fillMode: AnimationFillMode, trimStart: TimeInterval?, trimEnd: TimeInterval?, trimDuration: TimeInterval?, offset: TimeInterval, delay: TimeInterval, speed: Float)`](/documentation/RealityKit/SampledAnimation/init(weightNames:frames:name:tweenMode:frameInterval:isAdditive:bindTarget:blendLayer:repeatMode:fillMode:trimStart:trimEnd:trimDuration:offset:delay:speed:))

Creates an animation that blends between a configuration of blend targets.

### Instance Properties

[`var frames: [BlendShapeWeights]`](/documentation/RealityKit/SampledAnimation/frames-9jtu9)

An array of weights in which each element represents a discrete
state of the target entity at a given point in the animation’s timeline.

[`var weightNames: [String]`](/documentation/RealityKit/SampledAnimation/weightNames)

The names of the weights to animate.

## Relationships

### Conforms To

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

---

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)