<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/SkeletonResource",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation16SkeletonResourceC"
  },
  "title" : "SkeletonResource"
}
-->

# SkeletonResource

A self-contained skeleton asset for animating characters and articulated objects.

```
final class SkeletonResource
```

## Overview

A `SkeletonResource` encapsulates a skeleton’s joint hierarchy together with optional
inverse-kinematics resources and blend masks in a single value. Use a skeleton resource
to define the joint structure of a character, then share it with animation-related APIs
such as retargeting configurations, IK rigs, and animation graphs.

You create a skeleton resource by providing a name and the root of a joint hierarchy.
A skeleton resource is immutable once created — the same instance is
safe to reuse anywhere in your app, including from background threads, without copying.

### Build a skeleton from a joint hierarchy

Build a skeleton’s joint hierarchy using the [`SkeletonResource.Joint`](/documentation/RealityKit/SkeletonResource/Joint) type and the [`SkeletonResource.JointBuilder`](/documentation/RealityKit/SkeletonResource/JointBuilder) result
builder. Each joint has a name and a rest-pose transform relative to its parent; nesting
joints inside the trailing closure declares parent-child relationships. Joint names must
be unique among siblings — the initializer throws an error if any children of the same
parent share a name.

```swift
typealias Joint = SkeletonResource.Joint
let skeleton = try SkeletonResource(
    named: "Character",
    rootJoint: try Joint("root") {
        try Joint("spine", restPoseTransform: Transform(translation: [0, 0.1, 0])) {
            try Joint("shoulder", restPoseTransform: Transform(translation: [0, 0.15, 0])) {
                try Joint("upperArm", restPoseTransform: Transform(translation: [0, -0.3, 0])) {
                    try Joint("forearm", restPoseTransform: Transform(translation: [0, -0.3, 0])) {
                        try Joint("hand", restPoseTransform: Transform(translation: [0, -0.2, 0]))
                    }
                }
            }
        }
    }
)
```

### Add blend masks and inverse-kinematics resources

Blend masks let you control which joints an animation affects. Inverse-kinematics (IK)
resources let the runtime solve joint poses that meet positional or orientational targets —
for example, making a hand reach a point in space rather than following only pre-baked
motion. Bundle either or both into an [`SkeletonResource.AnimationEvaluation`](/documentation/RealityKit/SkeletonResource/AnimationEvaluation-swift.struct) value and supply it when
you create the skeleton; that data then stays fixed for the lifetime of the resource.
Both lists default to empty if you don’t need them.

Build a blend mask by listing per-joint weights between `0.0` (no animation) and
`1.0` (full animation). Joints you don’t list keep the default `1.0`, so one entry
is often enough to silence a whole body region:

```swift
let blendMasks: [SkeletonResource.BlendMask] = [
    .init(name: "armOnly", jointWeights: ["shoulder": 0.0]),
    .init(name: "handOnly", jointWeights: ["shoulder": 0.0, "upperArm": 0.0, "forearm": 0.0])
]
```

Build an IK rig from the same joint hierarchy with [`init(named:rootJoint:)`](/documentation/RealityKit/IKRig/init(named:rootJoint:)),
configure the constraints you need, then wrap the rig in an [`IKResource`](/documentation/RealityKit/IKResource). A skeleton
can carry more than one IK resource — for example, one configured for look-at
constraints and another for positional constraints — by passing each in the
`ikResources` array:

```swift
var rig = try IKRig(named: "armRig", rootJoint: rootJoint)
rig.constraints = [
    .parent(named: "Hand_Task", on: "hand",
            positionWeight: [50, 50, 50],
            orientationWeight: [60, 60, 60])
]
let ikResource = try IKResource(rig: rig)
```

Finally, pass both into the skeleton when you create it:

```swift
let skeleton = try SkeletonResource(
    named: "armSkeleton",
    rootJoint: rootJoint,
    animationEvaluation: .init(ikResources: [ikResource], blendMasks: blendMasks)
)
```

### Extract a skeleton from a loaded model

To pull a skeleton out of a USD-loaded model for use with the animation APIs, convert
the model’s [`MeshResource.Skeleton`](/documentation/RealityKit/MeshResource/Skeleton) with [`init(from:)`](/documentation/RealityKit/SkeletonResource/init(from:)).

```swift
let entity = try await Entity.load(named: "Character")
let modelEntity = entity as! ModelEntity
if let meshSkeleton = modelEntity.model?.mesh.contents.skeletons.first {
    let skeleton = try SkeletonResource(from: meshSkeleton)
}
```

### Use with retargeting

Pair a source and target `SkeletonResource` to build a retargeting configuration that
remaps animations across characters with different joint names or proportions, then
process source animations through it. See [`RetargetingConfiguration`](/documentation/RealityKit/RetargetingConfiguration) for the full
flow and the available matching strategies.

```swift
let config = try RetargetingConfiguration.automatchBiped(sourceSkeleton, to: targetSkeleton)
let retargeted = try sourceAnimation.processAndCreateAnimation(retargeting: config)
```

## Related Types

- [`SkeletonResource.Joint`](/documentation/RealityKit/SkeletonResource/Joint) — a single joint in the skeleton hierarchy.
- [`SkeletonResource.AnimationEvaluation`](/documentation/RealityKit/SkeletonResource/AnimationEvaluation-swift.struct) — bundle of IK resources and blend masks baked into the resource.
- [`SkeletonResource.BlendMask`](/documentation/RealityKit/SkeletonResource/BlendMask) — selective per-joint weighting for layered animation control.

## Topics

### Creating a skeleton resource

[`convenience init(named: String, rootJoint: SkeletonResource.Joint, animationEvaluation: SkeletonResource.AnimationEvaluation) throws`](/documentation/RealityKit/SkeletonResource/init(named:rootJoint:animationEvaluation:))

Creates a skeleton resource with the specified name, joint hierarchy, and animation-evaluation data.

### Defining the joint hierarchy

[`var rootJoint: SkeletonResource.Joint`](/documentation/RealityKit/SkeletonResource/rootJoint)

The root joint of the skeleton hierarchy.

[`struct Joint`](/documentation/RealityKit/SkeletonResource/Joint)

Describes a single joint of a `Skeleton`

[`struct JointBuilder`](/documentation/RealityKit/SkeletonResource/JointBuilder)

A result builder for declaratively constructing the children of a joint.

### Configuring animation evaluation

[`let animationEvaluation: SkeletonResource.AnimationEvaluation`](/documentation/RealityKit/SkeletonResource/animationEvaluation-swift.property)

Animation-evaluation data baked into this resource at construction time.

[`struct AnimationEvaluation`](/documentation/RealityKit/SkeletonResource/AnimationEvaluation-swift.struct)

A bundle of additional animation-related skeletal data the runtime consumes when
evaluating animations against this skeleton.

[`struct BlendMask`](/documentation/RealityKit/SkeletonResource/BlendMask)

Describes a single blend mask for selective animation control.

### Initializers

[`convenience init(from: MeshResource.Skeleton) throws`](/documentation/RealityKit/SkeletonResource/init(from:))

Creates a skeleton resource from a mesh resource skeleton.

### Instance Properties

[`let name: String`](/documentation/RealityKit/SkeletonResource/name)

Fast access to the name of the skeleton.

## Relationships

### Conforms To

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

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

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

---

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)