vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
//! Official VRM specification sample conformance tests.

use std::path::{Path, PathBuf};

use vrm_runtime::{AvatarAsset, LoadOptions, ValidationMode};

const SPEC_SAMPLES: [&str; 5] = [
    "Seed-san/vrm/Seed-san.vrm",
    "VRM1_Constraint_Twist_Sample/vrm/VRM1_Constraint_Twist_Sample.vrm",
    "VRMC_materials_mtoon_UV_Animation_Test/vrm/VRMC_materials_mtoon_UV_Animation_Test.vrm",
    "VRMC_vrm_expressions_isBinary_Overrides/vrm/VRMC_vrm_expressions_isBinary_Overrides.vrm",
    "VRMC_vrm_expressions_isBinary_Overridden/vrm/VRMC_vrm_expressions_isBinary_Overridden.vrm",
];

fn specification_samples() -> PathBuf {
    if let Some(path) = std::env::var_os("VRM_SPECIFICATION_DIR") {
        return PathBuf::from(path).join("samples");
    }

    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
    let workspace_checkout = manifest.join("../../vrm-specification/samples");
    if workspace_checkout.is_dir() {
        workspace_checkout
    } else {
        manifest.join("../vrm-specification/samples")
    }
}

fn sample(relative_path: &str) -> PathBuf {
    specification_samples().join(relative_path)
}

fn official_samples_available() -> bool {
    let seed_san = sample(SPEC_SAMPLES[0]);
    if seed_san.is_file() {
        true
    } else {
        eprintln!(
            "skipping official VRM sample tests because {} is unavailable",
            seed_san.display()
        );
        false
    }
}

#[test]
fn loads_every_official_vrm_1_0_sample() {
    if !official_samples_available() {
        return;
    }
    for relative_path in SPEC_SAMPLES {
        let path = sample(relative_path);
        // Two expression samples currently encode an explicitly empty
        // `meta.references`, which violates its schema `minItems` constraint
        // but is safe to recover from in permissive mode.
        AvatarAsset::from_file_with_options(
            &path,
            LoadOptions {
                validation: ValidationMode::Permissive,
            },
        )
        .unwrap_or_else(|error| panic!("failed to load {}: {error}", path.display()));
    }
}

#[test]
fn seed_san_preserves_gltf_material_indices() {
    if !official_samples_available() {
        return;
    }
    let path = sample("Seed-san/vrm/Seed-san.vrm");
    let avatar = AvatarAsset::from_file(&path).expect("Seed-san must load");
    let (document, _, _) = gltf::import(&path).expect("Seed-san is valid glTF");

    assert_eq!(
        avatar.materials().len(),
        document.materials().len(),
        "materials must preserve glTF indices so expression material binds target the correct material"
    );
}

#[test]
fn official_feature_samples_expose_their_declared_extensions() {
    if !official_samples_available() {
        return;
    }
    let seed_san =
        AvatarAsset::from_file(sample("Seed-san/vrm/Seed-san.vrm")).expect("Seed-san loads");
    assert!(
        seed_san.expressions().iter().any(|expression| {
            !expression.texture_transform_binds().is_empty()
                || !expression.material_color_binds().is_empty()
        }),
        "Seed-san is the official expression texture-transform sample"
    );
    assert!(
        !seed_san.node_constraints().is_empty(),
        "Seed-san is the official node-constraint sample"
    );
    assert!(
        !seed_san.spring_bone().springs.is_empty(),
        "Seed-san is the official spring-bone sample"
    );

    let twist = AvatarAsset::from_file(sample(
        "VRM1_Constraint_Twist_Sample/vrm/VRM1_Constraint_Twist_Sample.vrm",
    ))
    .expect("constraint sample loads");
    assert!(
        !twist.node_constraints().is_empty(),
        "constraint sample must retain its constraints"
    );
    assert!(
        twist.look_at().is_some(),
        "constraint sample must retain its bone LookAt configuration"
    );
}

#[test]
fn official_mtoon_uv_sample_preserves_material_and_texture_mapping() {
    if !official_samples_available() {
        return;
    }
    let avatar = AvatarAsset::load(sample(
        "VRMC_materials_mtoon_UV_Animation_Test/vrm/VRMC_materials_mtoon_UV_Animation_Test.vrm",
    ))
    .expect("the official MToon sample loads");

    assert_eq!(avatar.materials().len(), 3);
    for (index, material) in avatar.materials().iter().enumerate() {
        let base_texture = material
            .base_color_texture()
            .expect("every sample quad has a base-color texture");
        let mtoon = material.mtoon().expect("every sample material is MToon");
        assert_eq!(base_texture.texture_id().index(), index);
        assert_eq!(
            mtoon
                .shade_multiply_texture
                .as_ref()
                .expect("every sample quad has a shade texture")
                .texture_id()
                .index(),
            index
        );
        assert_eq!(
            avatar
                .texture(base_texture.texture_id())
                .unwrap()
                .image_id()
                .index(),
            index
        );
    }

    assert_eq!(
        avatar.materials()[0]
            .mtoon()
            .unwrap()
            .uv_animation_scroll_x_speed_factor,
        1.0
    );
    assert_eq!(
        avatar.materials()[1]
            .mtoon()
            .unwrap()
            .uv_animation_scroll_y_speed_factor,
        1.0
    );
    assert_eq!(
        avatar.materials()[2]
            .mtoon()
            .unwrap()
            .uv_animation_rotation_speed_factor,
        1.0
    );
}