vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
mod common;

use glam::Vec3;
use vrm_runtime::{
    AvatarAssetBuilder, AvatarMeta, HumanBone, NodeConstraint, NodeConstraintKind,
    RotationConstraint, Skin, SpringBone, SpringChain, SpringJoint,
};

fn builder() -> AvatarAssetBuilder {
    AvatarAssetBuilder::new()
        .with_meta(AvatarMeta::new(
            "Builder fixture",
            ["vrm-runtime"],
            "https://vrm.dev/licenses/1.0/",
        ))
        .with_humanoid(common::minimal_humanoid())
}

#[test]
fn builder_rejects_duplicate_humanoid_assignments() {
    let humanoid = common::minimal_humanoid().with_bone(HumanBone::Head, 1);
    let result = AvatarAssetBuilder::new()
        .with_meta(AvatarMeta::new(
            "Builder fixture",
            ["vrm-runtime"],
            "https://vrm.dev/licenses/1.0/",
        ))
        .with_humanoid(humanoid)
        .with_nodes(common::minimal_nodes())
        .build();

    assert!(result.is_err());
}

#[test]
fn builder_rejects_invalid_humanoid_hierarchy() {
    let mut nodes = common::minimal_nodes();
    nodes[1].children.retain(|child| *child != 2);
    nodes[2].parent = None;

    assert!(builder().with_nodes(nodes).build().is_err());
}

#[test]
fn builder_rejects_optional_bones_with_invalid_parent_relationships() {
    let mut missing_parent_nodes = common::minimal_nodes();
    let intermediate = missing_parent_nodes.len() as u32;
    missing_parent_nodes[11].children.push(intermediate);
    missing_parent_nodes.push(vrm_runtime::AvatarNode {
        index: intermediate,
        name: None,
        parent: Some(11),
        children: Vec::new(),
        initial_translation: Vec3::ZERO,
        initial_rotation: glam::Quat::IDENTITY,
        initial_scale: Vec3::ONE,
    });
    let missing_parent_humanoid =
        common::minimal_humanoid().with_bone(HumanBone::LeftIndexIntermediate, intermediate);
    assert!(
        AvatarAssetBuilder::new()
            .with_meta(AvatarMeta::new(
                "Builder fixture",
                ["vrm-runtime"],
                "https://vrm.dev/licenses/1.0/",
            ))
            .with_humanoid(missing_parent_humanoid)
            .with_nodes(missing_parent_nodes)
            .build()
            .is_err()
    );

    let mut wrong_branch_nodes = common::minimal_nodes();
    let toes = wrong_branch_nodes.len() as u32;
    wrong_branch_nodes[0].children.push(toes);
    wrong_branch_nodes.push(vrm_runtime::AvatarNode {
        index: toes,
        name: None,
        parent: Some(0),
        children: Vec::new(),
        initial_translation: Vec3::ZERO,
        initial_rotation: glam::Quat::IDENTITY,
        initial_scale: Vec3::ONE,
    });
    let wrong_branch_humanoid = common::minimal_humanoid().with_bone(HumanBone::LeftToes, toes);
    assert!(
        AvatarAssetBuilder::new()
            .with_meta(AvatarMeta::new(
                "Builder fixture",
                ["vrm-runtime"],
                "https://vrm.dev/licenses/1.0/",
            ))
            .with_humanoid(wrong_branch_humanoid)
            .with_nodes(wrong_branch_nodes)
            .build()
            .is_err()
    );
}

#[test]
fn builder_reports_a_transitively_invalid_parent_without_panicking() {
    let mut nodes = common::minimal_nodes();
    nodes[0].children.clear();
    nodes[0].parent = Some(1);
    nodes[1].children.push(0);
    nodes[1].parent = Some(99);

    let result = std::panic::catch_unwind(|| builder().with_nodes(nodes).build());

    assert!(matches!(result, Ok(Err(_))));
}

#[test]
fn builder_rejects_non_uniform_humanoid_scale() {
    let mut nodes = common::minimal_nodes();
    nodes[2].initial_scale = Vec3::new(1.0, 2.0, 1.0);

    assert!(builder().with_nodes(nodes).build().is_err());
}

#[test]
fn builder_rejects_invalid_scale_on_an_unmapped_node() {
    for scale in [Vec3::new(1.0, 2.0, 1.0), Vec3::new(1.0, 0.0, 1.0)] {
        let mut nodes = common::minimal_nodes();
        nodes.push(vrm_runtime::AvatarNode {
            index: nodes.len() as u32,
            name: None,
            parent: None,
            children: Vec::new(),
            initial_translation: Vec3::ZERO,
            initial_rotation: glam::Quat::IDENTITY,
            initial_scale: scale,
        });

        assert!(builder().with_nodes(nodes).build().is_err());
    }
}

#[test]
fn builder_rejects_invalid_constraint_references_and_cycles() {
    let invalid_reference = NodeConstraint {
        node_index: 1,
        constraint: NodeConstraintKind::Rotation(RotationConstraint {
            source: 99,
            weight: 1.0,
        }),
    };
    assert!(
        builder()
            .with_nodes(common::minimal_nodes())
            .with_constraints(vec![invalid_reference])
            .build()
            .is_err()
    );

    let cycle = vec![
        NodeConstraint {
            node_index: 1,
            constraint: NodeConstraintKind::Rotation(RotationConstraint {
                source: 2,
                weight: 1.0,
            }),
        },
        NodeConstraint {
            node_index: 2,
            constraint: NodeConstraintKind::Rotation(RotationConstraint {
                source: 1,
                weight: 1.0,
            }),
        },
    ];
    assert!(
        builder()
            .with_nodes(common::minimal_nodes())
            .with_constraints(cycle)
            .build()
            .is_err()
    );
}

#[test]
fn builder_rejects_invalid_skin_and_spring_references() {
    let mismatched_skin = Skin::new(vec![0, 1], vec![glam::Mat4::IDENTITY]);
    assert!(
        builder()
            .with_nodes(common::minimal_nodes())
            .with_skins(vec![mismatched_skin])
            .build()
            .is_err()
    );

    let spring = SpringBone {
        collider_groups: vec![],
        springs: vec![SpringChain {
            name: None,
            center_node: None,
            collider_groups: vec![],
            joints: vec![SpringJoint {
                node_index: 99,
                hit_radius: 0.0,
                stiffness: 1.0,
                gravity_power: 0.0,
                gravity_dir: Vec3::NEG_Y,
                drag_force: 0.5,
            }],
        }],
    };
    assert!(
        builder()
            .with_nodes(common::minimal_nodes())
            .with_spring_bone(spring)
            .build()
            .is_err()
    );
}