Contents

SkeletonResource

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

Declaration

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 type and the 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.

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 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:

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:), configure the constraints you need, then wrap the rig in an 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:

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:

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 with init(from:).

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 for the full flow and the available matching strategies.

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

Topics

Creating a skeleton resource

Defining the joint hierarchy

Configuring animation evaluation

Initializers

Instance Properties

See Also

Skeletons and retargeting