Module `animation`

Skeletal animation sampling, pose blending, and transition utilities.

Use sample_local_pose to sample clips before applying blend or inertialization. Build renderer-facing matrices with write_global_pose, then send those matrices through the renderer's UpdatePose message.

Quick Reference

Item	Kind	Description
`blend`	mod	Allocation-free local-pose and blend-space utilities.
`graph`	mod	Code-authored skeletal animation state machines and asynchronous clip pooling.
`inertialization`	mod	Retained local-pose inertialization for discontinuity-free transitions.
`packed`	mod	Packed animation storage and allocation-free pose sampling.
`root_motion`	mod	Root-motion extraction and composition utilities.
`skeletal`	mod	Local-pose sampling, global-pose construction, and pose comparison.
`AnimationBonePositionComparison`	struct
`BonePositionDifference`	struct
`AnimationComparisonError`	enum
`PoseError`	enum
`compare_animation_bone_positions`	fn
`sample_local_pose`	fn
`sample_pose`	fn
`write_global_pose`	fn

Modules

blend — Allocation-free local-pose and blend-space utilities.
graph — Code-authored skeletal animation state machines and asynchronous clip pooling.
inertialization — Retained local-pose inertialization for discontinuity-free transitions.
packed — Packed animation storage and allocation-free pose sampling.
root_motion — Root-motion extraction and composition utilities.
skeletal — Local-pose sampling, global-pose construction, and pose comparison.

Structs

`AnimationBonePositionComparison`

struct AnimationBonePositionComparison {
    pub differences: Vec<BonePositionDifference>,
}

Defined in crates/byte-engine/src/animation/skeletal.rs:100-103

The AnimationBonePositionComparison struct reports global bone-position differences for two sampled animations.

Fields

differences: Vec<BonePositionDifference>

Stores one position comparison for every bone, in skeleton node order.

Implementations

```
fn largest_difference(&self) -> Option<&BonePositionDifference>
```
Related: BonePositionDifference

Returns the bone with the largest global-position difference.

Trait Implementations

`impl ArchivePointee for AnimationBonePositionComparison`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for AnimationBonePositionComparison`

`impl Clone for AnimationBonePositionComparison`

fn clone(&self) -> AnimationBonePositionComparison

`impl Debug for AnimationBonePositionComparison`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for AnimationBonePositionComparison`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for AnimationBonePositionComparison`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for AnimationBonePositionComparison`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for AnimationBonePositionComparison`

`impl LayoutRaw for AnimationBonePositionComparison`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for AnimationBonePositionComparison`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for AnimationBonePositionComparison`

fn eq(&self, other: &AnimationBonePositionComparison) -> bool

`impl Pointable for AnimationBonePositionComparison`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for AnimationBonePositionComparison`

```
type Metadata = ()
```

`impl Read for AnimationBonePositionComparison`

`impl StructuralPartialEq for AnimationBonePositionComparison`

`impl WithSubscriber for AnimationBonePositionComparison`

`BonePositionDifference`

struct BonePositionDifference {
    pub node: usize,
    pub first: [f32; 3],
    pub second: [f32; 3],
    pub distance: f32,
}

Defined in crates/byte-engine/src/animation/skeletal.rs:87-96

The BonePositionDifference struct reports one bone's global-position difference between two sampled poses.

Fields

node: usize

Identifies the bone in the shared skeleton node order.
first: [f32; 3]

Stores the first animation's global bone position.
second: [f32; 3]

Stores the second animation's global bone position.
distance: f32

Stores the Euclidean distance between Self::first and Self::second.

Trait Implementations

`impl ArchivePointee for BonePositionDifference`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for BonePositionDifference`

`impl Clone for BonePositionDifference`

fn clone(&self) -> BonePositionDifference

Related: BonePositionDifference

`impl Copy for BonePositionDifference`

`impl Debug for BonePositionDifference`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for BonePositionDifference`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for BonePositionDifference`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for BonePositionDifference`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for BonePositionDifference`

`impl LayoutRaw for BonePositionDifference`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for BonePositionDifference`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for BonePositionDifference`

fn eq(&self, other: &BonePositionDifference) -> bool

Related: BonePositionDifference

`impl Pointable for BonePositionDifference`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for BonePositionDifference`

```
type Metadata = ()
```

`impl Read for BonePositionDifference`

`impl StructuralPartialEq for BonePositionDifference`

`impl WithSubscriber for BonePositionDifference`

Enums

`AnimationComparisonError`

enum AnimationComparisonError {
    NonFiniteTime,
    SkeletonNodeCountMismatch {
        first: usize,
        second: usize,
    },
    SkeletonLayoutMismatch {
        node: usize,
    },
}

Defined in crates/byte-engine/src/animation/skeletal.rs:355-370

The AnimationComparisonError enum identifies invalid inputs to bone-position comparison.

Variants

NonFiniteTime

A sample time is NaN or infinite.
SkeletonNodeCountMismatch

The animations use skeletons with different node counts.
SkeletonLayoutMismatch

The skeletons use different names or parent links at one node.

Trait Implementations

`impl ArchivePointee for AnimationComparisonError`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for AnimationComparisonError`

`impl Clone for AnimationComparisonError`

fn clone(&self) -> AnimationComparisonError

Related: AnimationComparisonError

`impl Copy for AnimationComparisonError`

`impl Debug for AnimationComparisonError`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Display for AnimationComparisonError`

fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

`impl Downcast for AnimationComparisonError`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for AnimationComparisonError`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for AnimationComparisonError`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for AnimationComparisonError`

`impl<K> Equivalent for AnimationComparisonError`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Error for AnimationComparisonError`

`impl Instrument for AnimationComparisonError`

`impl LayoutRaw for AnimationComparisonError`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for AnimationComparisonError`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for AnimationComparisonError`

fn eq(&self, other: &AnimationComparisonError) -> bool

Related: AnimationComparisonError

`impl Pointable for AnimationComparisonError`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for AnimationComparisonError`

```
type Metadata = ()
```

`impl Read for AnimationComparisonError`

`impl StructuralPartialEq for AnimationComparisonError`

`impl ToString for AnimationComparisonError`

```
fn to_string(&self) -> String
```

`impl WithSubscriber for AnimationComparisonError`

`PoseError`

enum PoseError {
    LocalPoseLength {
        expected: usize,
        actual: usize,
    },
}

Defined in crates/byte-engine/src/animation/skeletal.rs:330-338

The PoseError enum identifies local poses that cannot be converted to global matrices.

Variants

LocalPoseLength

The local pose and skeleton contain different numbers of nodes.

Trait Implementations

`impl ArchivePointee for PoseError`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for PoseError`

`impl Clone for PoseError`

```
fn clone(&self) -> PoseError
```
Related: PoseError

`impl Copy for PoseError`

`impl Debug for PoseError`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Display for PoseError`

fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

`impl Downcast for PoseError`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for PoseError`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for PoseError`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for PoseError`

`impl<K> Equivalent for PoseError`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Error for PoseError`

`impl Instrument for PoseError`

`impl LayoutRaw for PoseError`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for PoseError`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for PoseError`

```
fn eq(&self, other: &PoseError) -> bool
```
Related: PoseError

`impl Pointable for PoseError`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for PoseError`

```
type Metadata = ()
```

`impl Read for PoseError`

`impl StructuralPartialEq for PoseError`

`impl ToString for PoseError`

```
fn to_string(&self) -> String
```

`impl WithSubscriber for PoseError`

Functions

`compare_animation_bone_positions`

fn compare_animation_bone_positions(first_animation: &resource_management::resources::animation::Animation, first_time: f32, second_animation: &resource_management::resources::animation::Animation, second_time: f32) -> Result<AnimationBonePositionComparison, AnimationComparisonError>

Defined in crates/byte-engine/src/animation/skeletal.rs:121-166

Compares global bone positions from two animations sampled at independent times.

The clips must use skeletons with the same node order, names, and parent links. Sampling follows sample_local_pose, so times outside authored key ranges use the sampler's endpoint behavior. Use AnimationBonePositionComparison::largest_difference to inspect the most discontinuous bone, or AnimationBonePositionComparison::differences to inspect every bone.

`sample_local_pose`

fn sample_local_pose(animation: &resource_management::resources::animation::Animation, time: f32, output: &mut Vec<resource_management::resources::skeleton::LocalTransform>)

Defined in crates/byte-engine/src/animation/skeletal.rs:15-34

Samples one clip into a complete source-skeleton local pose.

Missing curves retain their node's rest-local component. The caller owns the output so retained animation state can reuse its capacity each frame. Next, blend or inertialize the local pose before calling write_global_pose.

`sample_pose`

fn sample_pose(animation: &resource_management::resources::animation::Animation, target_skeleton: &resource_management::resources::skeleton::Skeleton, pose_map: &resource_management::resources::skeleton::SkeletonPoseMap, time: f32, source_locals: &mut Vec<resource_management::resources::skeleton::LocalTransform>, target_locals: &mut Vec<resource_management::resources::skeleton::LocalTransform>, output: &mut Vec<math::Matrix>)

Defined in crates/byte-engine/src/animation/skeletal.rs:67-83

Samples an animation clip into global matrices for a compatible target skeleton.

The caller owns all pose storage so a retained animation player can reuse it each frame without allocating. Next, send the resulting matrices through the renderer's UpdatePose message for the renderable that owns the target skeleton.

`write_global_pose`

fn write_global_pose(skeleton: &resource_management::resources::skeleton::Skeleton, local_pose: &[resource_management::resources::skeleton::LocalTransform], output: &mut Vec<math::Matrix>) -> Result<(), PoseError>

Defined in crates/byte-engine/src/animation/skeletal.rs:40-60

Builds global skeleton matrices from a complete local pose.

Skeleton validation guarantees that every parent matrix precedes its children. The output retains capacity across calls.

animation

On this page