vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
use std::collections::HashSet;

use serde_json::Value;

/// Validates the glTF-wide relationship between extension declarations and
/// extension objects before a format-specific loader interprets them.
pub(crate) fn validate(root: &gltf::json::Root) -> Result<(), String> {
    let used = unique_names(&root.extensions_used, "extensionsUsed")?;
    let required = unique_names(&root.extensions_required, "extensionsRequired")?;

    for extension in required {
        if !used.contains(extension) {
            return Err(format!(
                "extensionsRequired entry `{extension}` must also appear in extensionsUsed"
            ));
        }
    }

    let value = serde_json::to_value(root)
        .map_err(|error| format!("failed to inspect glTF extension declarations: {error}"))?;
    validate_core_value(&value, &used, "")
}

fn unique_names<'a>(names: &'a [String], property: &str) -> Result<HashSet<&'a str>, String> {
    let mut unique = HashSet::with_capacity(names.len());
    for name in names {
        if !unique.insert(name.as_str()) {
            return Err(format!("duplicate `{name}` entry in {property}"));
        }
    }
    Ok(unique)
}

fn validate_core_value(value: &Value, used: &HashSet<&str>, path: &str) -> Result<(), String> {
    match value {
        Value::Object(object) => {
            for (key, child) in object {
                match key.as_str() {
                    // `extras` is application-defined data and may contain a
                    // property named `extensions` with unrelated semantics.
                    "extras" => {}
                    "extensions" => {
                        validate_extension_map(child, used, &child_path(path, key))?;
                    }
                    _ => validate_core_value(child, used, &child_path(path, key))?,
                }
            }
        }
        Value::Array(array) => {
            for (index, child) in array.iter().enumerate() {
                validate_core_value(child, used, &child_path(path, &index.to_string()))?;
            }
        }
        _ => {}
    }
    Ok(())
}

fn validate_extension_map(value: &Value, used: &HashSet<&str>, path: &str) -> Result<(), String> {
    let Value::Object(extensions) = value else {
        return Ok(());
    };
    for (extension, payload) in extensions {
        if !used.contains(extension.as_str()) {
            return Err(format!(
                "extension object `{extension}` at {path} is missing from extensionsUsed"
            ));
        }
        validate_known_extension_payload(extension, payload, used, &child_path(path, extension))?;
    }
    Ok(())
}

fn validate_known_extension_payload(
    extension: &str,
    payload: &Value,
    used: &HashSet<&str>,
    path: &str,
) -> Result<(), String> {
    match extension {
        "VRMC_vrm" => validate_vrm_payload(payload, used, path),
        "VRMC_vrm_animation" => validate_vrma_payload(payload, used, path),
        "VRMC_materials_mtoon" => validate_mtoon_payload(payload, used, path),
        "VRMC_node_constraint" => validate_constraint_payload(payload, used, path),
        "VRMC_springBone" => validate_spring_bone_payload(payload, used, path),
        "VRMC_springBone_extended_collider" => {
            validate_property(payload, used, path)?;
            validate_named_property(payload, "shape", used, path)
        }
        "VRMC_materials_hdr_emissiveMultiplier"
        | "KHR_materials_unlit"
        | "KHR_materials_emissive_strength"
        | "KHR_texture_transform" => validate_property(payload, used, path),
        // An unknown extension payload is opaque. Its fallback behavior is
        // determined solely by whether the extension is required.
        _ => Ok(()),
    }
}

fn validate_vrm_payload(payload: &Value, used: &HashSet<&str>, path: &str) -> Result<(), String> {
    validate_property(payload, used, path)?;
    validate_named_property(payload, "meta", used, path)?;

    if let Some(humanoid) = child(payload, "humanoid") {
        let humanoid_path = child_path(path, "humanoid");
        validate_property(humanoid, used, &humanoid_path)?;
        if let Some(human_bones) = child(humanoid, "humanBones") {
            validate_property_map_values(
                human_bones,
                used,
                &child_path(&humanoid_path, "humanBones"),
            )?;
        }
    }

    if let Some(first_person) = child(payload, "firstPerson") {
        let first_person_path = child_path(path, "firstPerson");
        validate_property(first_person, used, &first_person_path)?;
        validate_named_property_array(first_person, "meshAnnotations", used, &first_person_path)?;
    }

    if let Some(look_at) = child(payload, "lookAt") {
        let look_at_path = child_path(path, "lookAt");
        validate_property(look_at, used, &look_at_path)?;
        for range_map in [
            "rangeMapHorizontalInner",
            "rangeMapHorizontalOuter",
            "rangeMapVerticalDown",
            "rangeMapVerticalUp",
        ] {
            validate_named_property(look_at, range_map, used, &look_at_path)?;
        }
    }

    if let Some(expressions) = child(payload, "expressions") {
        let expressions_path = child_path(path, "expressions");
        validate_property(expressions, used, &expressions_path)?;
        for group in ["preset", "custom"] {
            let Some(items) = child(expressions, group) else {
                continue;
            };
            let items_path = child_path(&expressions_path, group);
            let Value::Object(items) = items else {
                continue;
            };
            for (name, expression) in items {
                let expression_path = child_path(&items_path, name);
                validate_property(expression, used, &expression_path)?;
                for binds in [
                    "morphTargetBinds",
                    "materialColorBinds",
                    "textureTransformBinds",
                ] {
                    validate_named_property_array(expression, binds, used, &expression_path)?;
                }
            }
        }
    }
    Ok(())
}

fn validate_vrma_payload(payload: &Value, used: &HashSet<&str>, path: &str) -> Result<(), String> {
    validate_property(payload, used, path)?;
    if let Some(humanoid) = child(payload, "humanoid") {
        let humanoid_path = child_path(path, "humanoid");
        validate_property(humanoid, used, &humanoid_path)?;
        if let Some(human_bones) = child(humanoid, "humanBones") {
            let human_bones_path = child_path(&humanoid_path, "humanBones");
            validate_property(human_bones, used, &human_bones_path)?;
            validate_property_map_values(human_bones, used, &human_bones_path)?;
        }
    }
    if let Some(expressions) = child(payload, "expressions") {
        let expressions_path = child_path(path, "expressions");
        validate_property(expressions, used, &expressions_path)?;
        for group in ["preset", "custom"] {
            if let Some(items) = child(expressions, group) {
                validate_plain_property_map_values(
                    items,
                    used,
                    &child_path(&expressions_path, group),
                )?;
            }
        }
    }
    validate_named_property(payload, "lookAt", used, path)
}

fn validate_mtoon_payload(payload: &Value, used: &HashSet<&str>, path: &str) -> Result<(), String> {
    validate_property(payload, used, path)?;
    for texture in [
        "shadeMultiplyTexture",
        "shadingShiftTexture",
        "matcapTexture",
        "rimMultiplyTexture",
        "outlineWidthMultiplyTexture",
        "uvAnimationMaskTexture",
    ] {
        validate_named_property(payload, texture, used, path)?;
    }
    Ok(())
}

fn validate_constraint_payload(
    payload: &Value,
    used: &HashSet<&str>,
    path: &str,
) -> Result<(), String> {
    validate_property(payload, used, path)?;
    let Some(constraint) = child(payload, "constraint") else {
        return Ok(());
    };
    let constraint_path = child_path(path, "constraint");
    validate_property(constraint, used, &constraint_path)?;
    for kind in ["roll", "aim", "rotation"] {
        validate_named_property(constraint, kind, used, &constraint_path)?;
    }
    Ok(())
}

fn validate_spring_bone_payload(
    payload: &Value,
    used: &HashSet<&str>,
    path: &str,
) -> Result<(), String> {
    validate_property(payload, used, path)?;
    if let Some(Value::Array(colliders)) = child(payload, "colliders") {
        let colliders_path = child_path(path, "colliders");
        for (index, collider) in colliders.iter().enumerate() {
            let collider_path = child_path(&colliders_path, &index.to_string());
            validate_property(collider, used, &collider_path)?;
            validate_named_property(collider, "shape", used, &collider_path)?;
        }
    }
    validate_named_property_array(payload, "colliderGroups", used, path)?;
    if let Some(Value::Array(springs)) = child(payload, "springs") {
        let springs_path = child_path(path, "springs");
        for (index, spring) in springs.iter().enumerate() {
            let spring_path = child_path(&springs_path, &index.to_string());
            validate_property(spring, used, &spring_path)?;
            validate_named_property_array(spring, "joints", used, &spring_path)?;
        }
    }
    Ok(())
}

fn validate_property(value: &Value, used: &HashSet<&str>, path: &str) -> Result<(), String> {
    let Some(extensions) = child(value, "extensions") else {
        return Ok(());
    };
    validate_extension_map(extensions, used, &child_path(path, "extensions"))
}

fn validate_named_property(
    parent: &Value,
    name: &str,
    used: &HashSet<&str>,
    path: &str,
) -> Result<(), String> {
    let Some(value) = child(parent, name) else {
        return Ok(());
    };
    validate_property(value, used, &child_path(path, name))
}

fn validate_named_property_array(
    parent: &Value,
    name: &str,
    used: &HashSet<&str>,
    path: &str,
) -> Result<(), String> {
    let Some(Value::Array(values)) = child(parent, name) else {
        return Ok(());
    };
    let array_path = child_path(path, name);
    for (index, value) in values.iter().enumerate() {
        validate_property(value, used, &child_path(&array_path, &index.to_string()))?;
    }
    Ok(())
}

fn validate_property_map_values(
    value: &Value,
    used: &HashSet<&str>,
    path: &str,
) -> Result<(), String> {
    let Value::Object(values) = value else {
        return Ok(());
    };
    for (name, value) in values {
        if name != "extensions" && name != "extras" {
            validate_property(value, used, &child_path(path, name))?;
        }
    }
    Ok(())
}

fn validate_plain_property_map_values(
    value: &Value,
    used: &HashSet<&str>,
    path: &str,
) -> Result<(), String> {
    let Value::Object(values) = value else {
        return Ok(());
    };
    for (name, value) in values {
        validate_property(value, used, &child_path(path, name))?;
    }
    Ok(())
}

fn child<'a>(value: &'a Value, name: &str) -> Option<&'a Value> {
    value.as_object()?.get(name)
}

fn child_path(parent: &str, segment: &str) -> String {
    let escaped = segment.replace('~', "~0").replace('/', "~1");
    format!("{parent}/{escaped}")
}