use std::collections::HashSet;
use std::path::Path;
use vrm_spec::vrmc_vrm_1_0::{HumanBoneName, VRMC_VRM, VRMCVrmSchema};
use crate::constraint::{self, NodeConstraint};
use crate::diagnostic::{Diagnostic, LoadOptions, ValidationMode};
use crate::expressions::Expressions;
use crate::first_person::FirstPerson;
use crate::humanoid::{HumanBone, Humanoid};
use crate::image::AvatarImage;
use crate::instance::AvatarInstance;
use crate::look_at::LookAt;
use crate::material::{AvatarTexture, Material};
use crate::meta::AvatarMeta;
use crate::node::{self, AvatarNode};
use crate::primitive::RenderPrimitive;
use crate::skin::Skin;
use crate::spring_bone::SpringBone;
use crate::{ImageId, MaterialId, NodeId, PrimitiveId, SkinId, TextureId};
use vrm_spec::vrmc_spring_bone_1_0::{VRMC_SPRING_BONE, VrmcSpringBoneSchema};
#[derive(Debug, Clone)]
pub struct AvatarAsset {
meta: AvatarMeta,
humanoid: Humanoid,
expressions: Expressions,
primitives: Vec<RenderPrimitive>,
look_at: Option<LookAt>,
pub(crate) images: Vec<AvatarImage>,
pub(crate) materials: Vec<Material>,
pub(crate) textures: Vec<AvatarTexture>,
pub(crate) skins: Vec<Skin>,
node_constraints: Vec<NodeConstraint>,
spring_bone: SpringBone,
pub(crate) first_person: FirstPerson,
nodes: Vec<AvatarNode>,
vrmc_vrm: Option<VRMCVrmSchema>,
}
impl AvatarAsset {
pub(crate) fn new() -> Self {
Self {
meta: AvatarMeta::default(),
humanoid: Humanoid::default(),
expressions: Expressions::default(),
primitives: Vec::new(),
look_at: None,
images: Vec::new(),
materials: Vec::new(),
textures: Vec::new(),
skins: Vec::new(),
node_constraints: Vec::new(),
spring_bone: SpringBone::default(),
first_person: FirstPerson::default(),
nodes: Vec::new(),
vrmc_vrm: None,
}
}
pub fn meta(&self) -> &AvatarMeta {
&self.meta
}
pub(crate) fn with_meta(mut self, meta: AvatarMeta) -> Self {
self.meta = meta;
self
}
pub fn humanoid(&self) -> &Humanoid {
&self.humanoid
}
pub(crate) fn with_humanoid(mut self, humanoid: Humanoid) -> Self {
self.humanoid = humanoid;
self
}
pub fn expressions(&self) -> &Expressions {
&self.expressions
}
pub(crate) fn with_expressions(mut self, expressions: Expressions) -> Self {
self.expressions = expressions;
self
}
pub fn primitives(&self) -> &[RenderPrimitive] {
&self.primitives
}
pub fn primitive(&self, id: PrimitiveId) -> Option<&RenderPrimitive> {
self.primitives.get(id.index())
}
pub(crate) fn with_primitives(mut self, primitives: Vec<RenderPrimitive>) -> Self {
self.primitives = primitives;
self
}
pub fn look_at(&self) -> Option<&LookAt> {
self.look_at.as_ref()
}
pub(crate) fn with_look_at(mut self, look_at: LookAt) -> Self {
self.look_at = Some(look_at);
self
}
pub fn images(&self) -> &[AvatarImage] {
&self.images
}
pub fn image(&self, id: ImageId) -> Option<&AvatarImage> {
self.images.get(id.index())
}
pub fn materials(&self) -> &[Material] {
&self.materials
}
pub fn material(&self, id: MaterialId) -> Option<&Material> {
self.materials.get(id.index())
}
pub fn textures(&self) -> &[AvatarTexture] {
&self.textures
}
pub fn texture(&self, id: TextureId) -> Option<&AvatarTexture> {
self.textures.get(id.index())
}
pub fn base_color(
&self,
material_index: u32,
color_type: crate::MaterialColorType,
) -> [f32; 4] {
let Some(material) = self.materials.get(material_index as usize) else {
return [1.0, 1.0, 1.0, 1.0];
};
match color_type {
crate::MaterialColorType::Color => material.base_color_factor,
crate::MaterialColorType::EmissionColor => [
material.emissive_factor[0],
material.emissive_factor[1],
material.emissive_factor[2],
1.0,
],
crate::MaterialColorType::ShadeColor => material
.mtoon()
.map(|mtoon| mtoon.shade_color.extend(1.0).to_array())
.unwrap_or([1.0; 4]),
crate::MaterialColorType::MatcapColor => material
.mtoon()
.map(|mtoon| mtoon.matcap_factor.extend(1.0).to_array())
.unwrap_or([1.0; 4]),
crate::MaterialColorType::RimColor => material
.mtoon()
.map(|mtoon| mtoon.parametric_rim_color_factor.extend(1.0).to_array())
.unwrap_or([1.0; 4]),
crate::MaterialColorType::OutlineColor => material
.mtoon()
.map(|mtoon| mtoon.outline_color_factor.extend(1.0).to_array())
.unwrap_or([1.0; 4]),
}
}
pub fn instantiate(&self) -> AvatarInstance {
AvatarInstance::new()
}
pub fn skins(&self) -> &[Skin] {
&self.skins
}
pub fn skin(&self, id: SkinId) -> Option<&Skin> {
self.skins.get(id.index())
}
#[cfg(test)]
pub(crate) fn with_skins(mut self, skins: Vec<Skin>) -> Self {
self.skins = skins;
self
}
pub fn node_constraints(&self) -> &[NodeConstraint] {
&self.node_constraints
}
pub(crate) fn with_node_constraints(mut self, node_constraints: Vec<NodeConstraint>) -> Self {
self.node_constraints = node_constraints;
self
}
pub fn spring_bone(&self) -> &SpringBone {
&self.spring_bone
}
pub(crate) fn with_spring_bone(mut self, spring_bone: SpringBone) -> Self {
self.spring_bone = spring_bone;
self
}
pub fn first_person(&self) -> &FirstPerson {
&self.first_person
}
pub fn nodes(&self) -> &[AvatarNode] {
&self.nodes
}
pub fn node(&self, id: NodeId) -> Option<&AvatarNode> {
self.nodes.get(id.index())
}
pub(crate) fn with_nodes(mut self, nodes: Vec<AvatarNode>) -> Self {
self.nodes = nodes;
self
}
pub fn compute_world_matrices(
&self,
bone_updates: &[crate::instance::BoneUpdate],
) -> Vec<glam::Mat4> {
node::compute_world_matrices(&self.nodes, bone_updates)
}
pub fn compute_joint_matrices(
&self,
skin: &Skin,
bone_updates: &[crate::instance::BoneUpdate],
) -> Vec<glam::Mat4> {
node::compute_joint_matrices(&self.nodes, skin, bone_updates)
}
pub fn vrmc_vrm(&self) -> Option<&VRMCVrmSchema> {
self.vrmc_vrm.as_ref()
}
pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, crate::LoadError> {
Ok(Self::from_file_with_options(path, LoadOptions::default())?.asset)
}
pub fn from_bytes(bytes: &[u8]) -> Result<Self, crate::LoadError> {
Ok(Self::from_bytes_with_options(bytes, LoadOptions::default())?.asset)
}
pub fn from_file_with_options<P: AsRef<Path>>(
path: P,
options: LoadOptions,
) -> Result<LoadOutcome, crate::LoadError> {
let path_ref = path.as_ref();
let bytes = std::fs::read(path_ref).map_err(|source| crate::LoadError::Io {
path: path_ref.to_path_buf(),
source,
})?;
Self::from_bytes_with_options_and_base(&bytes, options, path_ref.parent())
}
pub fn from_bytes_with_options(
bytes: &[u8],
options: LoadOptions,
) -> Result<LoadOutcome, crate::LoadError> {
Self::from_bytes_with_options_and_base(bytes, options, None)
}
fn from_bytes_with_options_and_base(
bytes: &[u8],
options: LoadOptions,
base: Option<&Path>,
) -> Result<LoadOutcome, crate::LoadError> {
let mut gltf = gltf::Gltf::from_slice_without_validation(bytes)?;
validate_raw_node_graph(gltf.document.as_json())?;
crate::image::validate_raw_sources(gltf.document.as_json())?;
crate::primitive::validate_referenced_primitive_positions(gltf.document.as_json())?;
validate_required_extensions(&gltf.document)?;
validate_gltf_document(&gltf.document)?;
let buffers = gltf::import_buffers(&gltf.document, base, gltf.blob.take())?;
let doc = gltf.document;
let schema = Self::parse_vrm_schema(&doc)?;
let mut diagnostics = Vec::new();
collect_optional_extension_diagnostics(&doc, options.validation, &mut diagnostics);
collect_material_compatibility_diagnostics(&doc, &mut diagnostics);
validate_vrm_semantics(&doc, &schema, options.validation, &mut diagnostics)?;
let meta = AvatarMeta::load_meta(&schema.meta);
let humanoid = Humanoid::load_humanoid(&schema.humanoid);
let expressions = schema
.expressions
.as_ref()
.map(Expressions::load_expressions)
.unwrap_or_default();
let look_at = schema.look_at.as_ref().map(LookAt::load_look_at);
let first_person = schema
.first_person
.as_ref()
.map(FirstPerson::load_first_person)
.unwrap_or_default();
let primitives = load_primitives(&doc, &buffers)?;
let images = load_images(&doc, &buffers, base)?;
crate::image::validate_thumbnail(
&images,
schema
.meta
.thumbnail_image
.as_ref()
.map(|index| index.value()),
)?;
let materials = load_materials(&doc)?;
let textures = crate::material::load_textures(&doc);
let skins = load_skins(&doc, &buffers)?;
let node_constraints = load_constraints(&doc)?;
let spring_bone = load_spring_bone(&doc, options.validation, &mut diagnostics)?;
let nodes = node::load_nodes(&doc);
let asset = Self {
meta,
humanoid,
expressions,
primitives,
look_at,
images,
materials,
textures,
skins,
node_constraints,
spring_bone,
first_person,
nodes,
vrmc_vrm: Some(schema),
};
Ok(LoadOutcome { asset, diagnostics })
}
fn parse_vrm_schema(doc: &gltf::Document) -> Result<VRMCVrmSchema, crate::LoadError> {
match doc.extension_value(VRMC_VRM) {
Some(value) => Ok(serde_json::from_value(value.to_owned())?),
None if doc.extension_value("VRM").is_some() => {
Err(crate::LoadError::UnsupportedVrmVersion)
}
None => Err(crate::LoadError::MissingVrmExtension),
}
}
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, crate::LoadError> {
Self::from_file(path)
}
pub fn load_with_options<P: AsRef<Path>>(
path: P,
options: LoadOptions,
) -> Result<LoadOutcome, crate::LoadError> {
Self::from_file_with_options(path, options)
}
pub const fn capabilities() -> crate::Capabilities {
crate::Capabilities::current()
}
pub(crate) fn validate_programmatic(&self) -> Result<(), crate::BuildError> {
let invalid = |message: String| crate::BuildError::InvalidAsset(message);
if self.meta.name().trim().is_empty() {
return Err(invalid("meta.name must not be empty".to_string()));
}
if self.meta.authors().is_empty()
|| self
.meta
.authors()
.iter()
.any(|author| author.trim().is_empty())
{
return Err(invalid(
"meta.authors must contain at least one non-empty author".to_string(),
));
}
if self
.meta
.license_url()
.is_none_or(|license| license.trim().is_empty())
{
return Err(invalid("meta.license_url must not be empty".to_string()));
}
if self
.meta
.references()
.is_some_and(|references| references.is_empty())
{
return Err(invalid(
"meta.references must contain at least one item when present".to_string(),
));
}
if let Some(look_at) = &self.look_at {
look_at
.validate_programmatic()
.map_err(crate::BuildError::InvalidAsset)?;
}
for (position, node) in self.nodes.iter().enumerate() {
if node.index as usize != position {
return Err(invalid(format!(
"node storage position {position} does not match node index {}",
node.index
)));
}
if !node.initial_translation.is_finite()
|| !node.initial_rotation.is_finite()
|| !node.initial_scale.is_finite()
{
return Err(invalid(format!(
"node {position} contains a non-finite transform"
)));
}
if !is_positive_uniform_scale(node.initial_scale.to_array()) {
return Err(invalid(format!(
"node {position} must use a positive uniform scale"
)));
}
if node
.parent
.is_some_and(|parent| parent as usize >= self.nodes.len() || parent == node.index)
{
return Err(invalid(format!("node {position} has an invalid parent")));
}
let mut unique_children = HashSet::new();
for &child in &node.children {
if child as usize >= self.nodes.len()
|| child == node.index
|| !unique_children.insert(child)
{
return Err(invalid(format!("node {position} has an invalid child")));
}
if self.nodes[child as usize].parent != Some(node.index) {
return Err(invalid(format!(
"node {position} and child {child} disagree about their relationship"
)));
}
}
if let Some(parent) = node.parent
&& !self.nodes[parent as usize].children.contains(&node.index)
{
return Err(invalid(format!(
"node {position} and parent {parent} disagree about their relationship"
)));
}
let mut ancestors = HashSet::new();
let mut cursor = node.parent;
while let Some(parent) = cursor {
if !ancestors.insert(parent) {
return Err(invalid(format!(
"node hierarchy contains a cycle through node {parent}"
)));
}
cursor = self
.nodes
.get(parent as usize)
.and_then(|ancestor| ancestor.parent);
}
}
let mut assigned_nodes = HashSet::new();
for (bone, node) in self.humanoid.bones() {
if node.0 as usize >= self.nodes.len() {
return Err(invalid(format!(
"humanoid bone `{bone:?}` references missing node {}",
node.0
)));
}
if !assigned_nodes.insert(node.0) {
return Err(invalid(format!(
"node {} is assigned to more than one humanoid bone",
node.0
)));
}
}
for required in REQUIRED_HUMAN_BONES {
let bone = HumanBone::from(required);
if self.humanoid.bone(bone).is_none() {
return Err(invalid(format!(
"humanoid bone `{}` is required",
human_bone_name(required)
)));
}
}
let node_parents = self
.nodes
.iter()
.map(|node| node.parent.map(|parent| parent as usize))
.collect::<Vec<_>>();
let mapped_bones = self
.humanoid
.bones()
.map(|(&bone, node)| (bone, node.0 as usize));
if let Some(violation) = crate::humanoid::hierarchy_violations(mapped_bones, &node_parents)
.into_iter()
.next()
{
return Err(invalid(violation.message()));
}
for (skin_index, skin) in self.skins.iter().enumerate() {
if skin.joints().len() != skin.inverse_bind_matrices().len() {
return Err(invalid(format!(
"skin {skin_index} must have one inverse bind matrix per joint"
)));
}
if skin
.joints()
.iter()
.any(|&node| node as usize >= self.nodes.len())
|| skin.inverse_bind_matrices().iter().any(|matrix| {
matrix
.to_cols_array()
.iter()
.any(|component| !component.is_finite())
})
{
return Err(invalid(format!(
"skin {skin_index} contains an invalid joint or matrix"
)));
}
}
for (texture_index, texture) in self.textures.iter().enumerate() {
if texture.image_id().index() >= self.images.len() {
return Err(invalid(format!(
"texture {texture_index} references a missing image"
)));
}
}
let validate_texture =
|label: &str, texture: Option<&crate::TextureInfo>| -> Result<(), crate::BuildError> {
if let Some(texture) = texture {
if texture.texture_id().index() >= self.textures.len() {
return Err(invalid(format!("{label} references a missing texture")));
}
let transform = texture.transform();
if !transform.rotation.is_finite()
|| transform.offset.iter().any(|value| !value.is_finite())
|| transform.scale.iter().any(|value| !value.is_finite())
{
return Err(invalid(format!("{label} has a non-finite UV transform")));
}
}
Ok(())
};
for (material_index, material) in self.materials.iter().enumerate() {
validate_texture(
&format!("material {material_index} base color texture"),
material.base_color_texture(),
)?;
validate_texture(
&format!("material {material_index} normal texture"),
material.normal_texture().map(|normal| &normal.texture),
)?;
validate_texture(
&format!("material {material_index} emissive texture"),
material.emissive_texture(),
)?;
if let Some(mtoon) = material.mtoon() {
for (name, texture) in [
("shade multiply", mtoon.shade_multiply_texture.as_ref()),
("shading shift", mtoon.shading_shift_texture.as_ref()),
("matcap", mtoon.matcap_texture.as_ref()),
("rim multiply", mtoon.rim_multiply_texture.as_ref()),
(
"outline width multiply",
mtoon.outline_width_multiply_texture.as_ref(),
),
(
"UV animation mask",
mtoon.uv_animation_mask_texture.as_ref(),
),
] {
validate_texture(
&format!("material {material_index} {name} texture"),
texture,
)?;
}
}
}
for (primitive_index, primitive) in self.primitives.iter().enumerate() {
if primitive.node_index() as usize >= self.nodes.len() {
return Err(invalid(format!(
"primitive {primitive_index} references a missing node"
)));
}
if primitive
.material_index()
.is_some_and(|material| material >= self.materials.len())
|| primitive
.texture_index()
.is_some_and(|texture| texture >= self.textures.len())
|| primitive
.skin_index()
.is_some_and(|skin| skin >= self.skins.len())
{
return Err(invalid(format!(
"primitive {primitive_index} references a missing asset object"
)));
}
if primitive
.indices()
.iter()
.any(|&index| index as usize >= primitive.positions().len())
{
return Err(invalid(format!(
"primitive {primitive_index} contains an out-of-range vertex index"
)));
}
}
let mut expression_names = HashSet::new();
for expression in self.expressions.iter() {
if expression.name().is_empty() || !expression_names.insert(expression.name()) {
return Err(invalid(
"expression names must be non-empty and unique".to_string(),
));
}
crate::expressions::validate_override_semantics(
expression.name(),
expression.override_blink(),
expression.override_mouth(),
expression.override_look_at(),
)
.map_err(invalid)?;
for bind in expression.morph_target_binds() {
let matching: Vec<_> = self
.primitives
.iter()
.filter(|primitive| primitive.node_index() == bind.node_index())
.collect();
if matching.is_empty()
|| matching.iter().any(|primitive| {
bind.target_index() as usize >= primitive.morph_targets().len()
})
|| !bind.weight().is_finite()
|| !(0.0..=1.0).contains(&bind.weight())
{
return Err(invalid(format!(
"expression `{}` contains an invalid morph target bind",
expression.name()
)));
}
}
for bind in expression.material_color_binds() {
if bind.material_index as usize >= self.materials.len()
|| bind.target_value.iter().any(|value| !value.is_finite())
{
return Err(invalid(format!(
"expression `{}` contains an invalid material color bind",
expression.name()
)));
}
}
for bind in expression.texture_transform_binds() {
if bind.material_index as usize >= self.materials.len()
|| bind.scale.iter().any(|value| !value.is_finite())
|| bind.offset.iter().any(|value| !value.is_finite())
{
return Err(invalid(format!(
"expression `{}` contains an invalid texture transform bind",
expression.name()
)));
}
}
}
for annotation in &self.first_person.mesh_annotations {
if annotation.node_index as usize >= self.nodes.len()
|| !self
.primitives
.iter()
.any(|primitive| primitive.node_index() == annotation.node_index)
{
return Err(invalid(format!(
"first-person annotation references node {} without a mesh",
annotation.node_index
)));
}
}
constraint::validate_programmatic(&self.node_constraints, self.nodes.len())
.map_err(invalid)?;
crate::spring_bone::validate_programmatic(&self.nodes, &self.spring_bone)
.map_err(invalid)?;
Ok(())
}
}
fn validate_raw_node_graph(root: &gltf::json::Root) -> Result<(), crate::LoadError> {
let node_count = root.nodes.len();
let mut indegree = vec![0usize; node_count];
let mut children = vec![Vec::new(); node_count];
for (parent, node) in root.nodes.iter().enumerate() {
for child in node.children.as_deref().unwrap_or_default() {
let child = child.value();
if child >= node_count {
return Err(crate::LoadError::InvalidVrm(format!(
"/nodes/{parent}/children references missing node {child}"
)));
}
indegree[child] += 1;
if indegree[child] > 1 {
return Err(crate::LoadError::InvalidVrm(format!(
"node {child} has more than one parent"
)));
}
children[parent].push(child);
}
}
let mut roots: std::collections::VecDeque<_> = indegree
.iter()
.enumerate()
.filter_map(|(index, °ree)| (degree == 0).then_some(index))
.collect();
let mut visited = 0usize;
while let Some(parent) = roots.pop_front() {
visited += 1;
for &child in &children[parent] {
indegree[child] -= 1;
if indegree[child] == 0 {
roots.push_back(child);
}
}
}
if visited != node_count {
return Err(crate::LoadError::InvalidVrm(
"node hierarchy contains a cycle".to_string(),
));
}
Ok(())
}
#[derive(Debug)]
pub struct LoadOutcome {
pub asset: AvatarAsset,
pub diagnostics: Vec<Diagnostic>,
}
fn validate_required_extensions(doc: &gltf::Document) -> Result<(), crate::LoadError> {
crate::extension_declarations::validate(doc.as_json()).map_err(crate::LoadError::InvalidVrm)?;
for extension in doc.extensions_required() {
if !SUPPORTED_EXTENSIONS.contains(&extension) {
return Err(crate::LoadError::UnsupportedRequiredExtension(
extension.to_string(),
));
}
}
Ok(())
}
fn validate_gltf_document(doc: &gltf::Document) -> Result<(), crate::LoadError> {
let mut root = doc.as_json().clone();
root.extensions_required
.retain(|extension| !SUPPORTED_EXTENSIONS.contains(&extension.as_str()));
gltf::Document::from_json(root)?;
Ok(())
}
const SUPPORTED_EXTENSIONS: &[&str] = &[
"VRMC_vrm",
"VRMC_materials_mtoon",
"VRMC_materials_hdr_emissiveMultiplier",
"VRMC_node_constraint",
"VRMC_springBone",
"VRMC_springBone_extended_collider",
"KHR_materials_unlit",
"KHR_materials_emissive_strength",
"KHR_texture_transform",
];
fn collect_optional_extension_diagnostics(
doc: &gltf::Document,
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
) {
if validation != ValidationMode::Permissive {
return;
}
let required: HashSet<_> = doc.extensions_required().collect();
for extension in doc.extensions_used() {
if !SUPPORTED_EXTENSIONS.contains(&extension) && !required.contains(extension) {
diagnostics.push(Diagnostic::warning(
"VRM_UNSUPPORTED_OPTIONAL_EXTENSION",
"/extensionsUsed",
format!(
"optional extension `{extension}` is not interpreted; its fallback data is used"
),
));
}
}
}
fn collect_material_compatibility_diagnostics(
doc: &gltf::Document,
diagnostics: &mut Vec<Diagnostic>,
) {
const LEGACY: &str = "VRMC_materials_hdr_emissiveMultiplier";
const KHR: &str = "KHR_materials_emissive_strength";
for material in doc.materials() {
if material.extension_value(LEGACY).is_none() {
continue;
}
let index = material.index().unwrap_or(0);
diagnostics.push(Diagnostic::warning(
"VRM_DEPRECATED_HDR_EMISSIVE_MULTIPLIER",
format!("/materials/{index}/extensions/{LEGACY}"),
format!("`{LEGACY}` is archived; prefer `{KHR}` for new assets"),
));
if material.emissive_strength().is_some() {
diagnostics.push(Diagnostic::warning(
"VRM_EMISSIVE_STRENGTH_PRECEDENCE",
format!("/materials/{index}/extensions"),
format!("both emissive strength extensions are present; `{KHR}` takes precedence"),
));
}
}
}
const REQUIRED_HUMAN_BONES: [HumanBoneName; 15] = [
HumanBoneName::Hips,
HumanBoneName::Spine,
HumanBoneName::Head,
HumanBoneName::LeftUpperLeg,
HumanBoneName::LeftLowerLeg,
HumanBoneName::LeftFoot,
HumanBoneName::RightUpperLeg,
HumanBoneName::RightLowerLeg,
HumanBoneName::RightFoot,
HumanBoneName::LeftUpperArm,
HumanBoneName::LeftLowerArm,
HumanBoneName::LeftHand,
HumanBoneName::RightUpperArm,
HumanBoneName::RightLowerArm,
HumanBoneName::RightHand,
];
fn validate_vrm_semantics(
doc: &gltf::Document,
schema: &VRMCVrmSchema,
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
) -> Result<(), crate::LoadError> {
let node_count = doc.nodes().count();
if schema.spec_version != "1.0" {
return Err(crate::LoadError::InvalidVrm(format!(
"unsupported VRMC_vrm specVersion `{}` (expected 1.0)",
schema.spec_version
)));
}
let bones = &schema.humanoid.human_bones.0;
let mut assigned_nodes: HashSet<usize> = HashSet::new();
for &required in &REQUIRED_HUMAN_BONES {
let bone = bones
.get(&required)
.and_then(|entry| entry.as_ref())
.ok_or_else(|| {
crate::LoadError::InvalidVrm(format!(
"humanoid bone `{}` is required but missing",
human_bone_name(required)
))
})?;
let node_index = bone.node.map(|index| index.value()).ok_or_else(|| {
crate::LoadError::InvalidVrm(format!(
"humanoid bone `{}` has no node assignment",
human_bone_name(required)
))
})?;
if node_index >= node_count {
return Err(crate::LoadError::InvalidVrm(format!(
"humanoid bone `{}` references missing node {}",
human_bone_name(required),
node_index
)));
}
if !assigned_nodes.insert(node_index) {
return Err(crate::LoadError::InvalidVrm(format!(
"node {} is assigned to more than one humanoid bone",
node_index
)));
}
}
if schema.meta.name.trim().is_empty() {
semantic_violation(
validation,
diagnostics,
"VRM_META_NAME_EMPTY",
"/extensions/VRMC_vrm/meta/name",
"meta.name must not be empty",
)?;
}
if schema.meta.authors.is_empty()
|| schema
.meta
.authors
.iter()
.any(|author| author.trim().is_empty())
{
semantic_violation(
validation,
diagnostics,
"VRM_META_AUTHORS_INVALID",
"/extensions/VRMC_vrm/meta/authors",
"meta.authors must contain at least one non-empty author",
)?;
}
if schema.meta.references.as_ref().is_some_and(Vec::is_empty) {
semantic_violation(
validation,
diagnostics,
"VRM_META_REFERENCES_EMPTY",
"/extensions/VRMC_vrm/meta/references",
"meta.references must contain at least one item when present",
)?;
}
if let Some(look_at) = &schema.look_at {
crate::look_at::validate_schema(look_at).map_err(crate::LoadError::InvalidVrm)?;
}
for (name, entry) in bones {
if REQUIRED_HUMAN_BONES.contains(name) {
continue;
}
let bone = entry.as_ref().ok_or_else(|| {
crate::LoadError::InvalidVrm(format!(
"humanoid bone `{}` must be an object containing `node`",
human_bone_name(*name)
))
})?;
let node_index = bone.node.map(|index| index.value()).ok_or_else(|| {
crate::LoadError::InvalidVrm(format!(
"humanoid bone `{}` must contain `node`",
human_bone_name(*name)
))
})?;
if node_index >= node_count {
return Err(crate::LoadError::InvalidVrm(format!(
"humanoid bone `{}` references missing node {}",
human_bone_name(*name),
node_index
)));
}
if !assigned_nodes.insert(node_index) {
return Err(crate::LoadError::InvalidVrm(format!(
"node {} is assigned to more than one humanoid bone",
node_index
)));
}
}
validate_node_transforms(doc, validation, diagnostics)?;
validate_humanoid_hierarchy(doc, &schema.humanoid.human_bones, validation, diagnostics)?;
validate_vrm_references(doc, schema)?;
Ok(())
}
fn validate_node_transforms(
doc: &gltf::Document,
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
) -> Result<(), crate::LoadError> {
for node in doc.nodes() {
let (_, _, scale) = node.transform().decomposed();
if !is_positive_uniform_scale(scale) {
let path = format!("/nodes/{}/scale", node.index());
match validation {
ValidationMode::Strict => {
return Err(crate::LoadError::InvalidVrm(format!(
"{path}: every node scale must be positive and uniform"
)));
}
ValidationMode::Permissive => diagnostics.push(Diagnostic::warning(
"VRM_NODE_SCALE_INVALID",
path,
"every node scale must be positive and uniform",
)),
}
}
}
Ok(())
}
fn is_positive_uniform_scale(scale: [f32; 3]) -> bool {
let max_scale = scale.iter().copied().fold(0.0_f32, f32::max);
let uniform_tolerance = max_scale * 2.0e-3;
scale.iter().all(|value| value.is_finite() && *value > 0.0)
&& (scale[0] - scale[1]).abs() <= uniform_tolerance
&& (scale[1] - scale[2]).abs() <= uniform_tolerance
}
fn validate_humanoid_hierarchy(
doc: &gltf::Document,
bones: &vrm_spec::vrmc_vrm_1_0::HumanBones,
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
) -> Result<(), crate::LoadError> {
let mut parents = vec![None; doc.nodes().count()];
for node in doc.nodes() {
for child in node.children() {
parents[child.index()] = Some(node.index());
}
}
let mapped_bones = bones.0.iter().filter_map(|(name, entry)| {
entry
.as_ref()
.and_then(|bone| bone.node.map(|node| (HumanBone::from(*name), node.value())))
});
for violation in crate::humanoid::hierarchy_violations(mapped_bones, &parents) {
let bone_name = violation.bone().spec_name();
let message = violation.message();
match validation {
ValidationMode::Strict => return Err(crate::LoadError::InvalidVrm(message)),
ValidationMode::Permissive => diagnostics.push(Diagnostic::warning(
"VRM_HUMANOID_HIERARCHY_INVALID",
format!("/extensions/VRMC_vrm/humanoid/humanBones/{bone_name}"),
message,
)),
}
}
Ok(())
}
fn validate_vrm_references(
doc: &gltf::Document,
schema: &VRMCVrmSchema,
) -> Result<(), crate::LoadError> {
if let Some(thumbnail) = schema.meta.thumbnail_image.as_ref()
&& thumbnail.value() >= doc.images().count()
{
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_vrm/meta/thumbnailImage references missing image {}",
thumbnail.value()
)));
}
if let Some(first_person) = &schema.first_person {
if first_person
.mesh_annotations
.as_ref()
.is_some_and(Vec::is_empty)
{
return Err(crate::LoadError::InvalidVrm(
"/extensions/VRMC_vrm/firstPerson/meshAnnotations must contain at least one item when present"
.to_string(),
));
}
for (index, annotation) in first_person
.mesh_annotations
.as_deref()
.unwrap_or_default()
.iter()
.enumerate()
{
let node = annotation.node.as_ref().ok_or_else(|| {
crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_vrm/firstPerson/meshAnnotations/{index}/node is required"
))
})?;
let node_index = node.value();
if node_index >= doc.nodes().count()
|| doc
.nodes()
.nth(node_index)
.and_then(|node| node.mesh())
.is_none()
{
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_vrm/firstPerson/meshAnnotations/{index}/node must reference a node with a mesh"
)));
}
}
}
let validate_expression = |name: &str,
location: String,
expression: &vrm_spec::vrmc_vrm_1_0::Expression|
-> Result<(), crate::LoadError> {
crate::expressions::validate_override_semantics(
name,
expression
.override_blink
.map(crate::ExpressionOverrideType::from)
.unwrap_or_default(),
expression
.override_mouth
.map(crate::ExpressionOverrideType::from)
.unwrap_or_default(),
expression
.override_look_at
.map(crate::ExpressionOverrideType::from)
.unwrap_or_default(),
)
.map_err(|message| crate::LoadError::InvalidVrm(format!("{location}: {message}")))?;
for (name, empty) in [
(
"morphTargetBinds",
expression
.morph_target_binds
.as_ref()
.is_some_and(Vec::is_empty),
),
(
"materialColorBinds",
expression
.material_color_binds
.as_ref()
.is_some_and(Vec::is_empty),
),
(
"textureTransformBinds",
expression
.texture_transform_binds
.as_ref()
.is_some_and(Vec::is_empty),
),
] {
if empty {
return Err(crate::LoadError::InvalidVrm(format!(
"{location}/{name} must contain at least one item when present"
)));
}
}
for (index, bind) in expression
.morph_target_binds
.as_deref()
.unwrap_or_default()
.iter()
.enumerate()
{
let node_index = bind.node.value();
let Some(mesh) = doc.nodes().nth(node_index).and_then(|node| node.mesh()) else {
return Err(crate::LoadError::InvalidVrm(format!(
"{location}/morphTargetBinds/{index}/node must reference a node with a mesh"
)));
};
if mesh
.primitives()
.any(|primitive| bind.index >= primitive.morph_targets().count())
{
return Err(crate::LoadError::InvalidVrm(format!(
"{location}/morphTargetBinds/{index}/index is out of range"
)));
}
if !bind.weight.is_finite() || !(0.0..=1.0).contains(&bind.weight) {
return Err(crate::LoadError::InvalidVrm(format!(
"{location}/morphTargetBinds/{index}/weight must be in 0..=1"
)));
}
}
for (index, bind) in expression
.material_color_binds
.as_deref()
.unwrap_or_default()
.iter()
.enumerate()
{
if bind.material.value() >= doc.materials().count()
|| bind.target_value.len() != 4
|| bind
.target_value
.iter()
.any(|&value| !is_representable_f32(value))
{
return Err(crate::LoadError::InvalidVrm(format!(
"{location}/materialColorBinds/{index} has an invalid material or targetValue"
)));
}
}
for (index, bind) in expression
.texture_transform_binds
.as_deref()
.unwrap_or_default()
.iter()
.enumerate()
{
let valid_vector = |value: Option<&Vec<f64>>| {
value.is_none_or(|value| {
value.len() == 2
&& value
.iter()
.all(|&component| is_representable_f32(component))
})
};
if bind.material.value() >= doc.materials().count()
|| !valid_vector(bind.scale.as_ref())
|| !valid_vector(bind.offset.as_ref())
{
return Err(crate::LoadError::InvalidVrm(format!(
"{location}/textureTransformBinds/{index} is invalid"
)));
}
}
Ok(())
};
if let Some(expressions) = &schema.expressions {
if let Some(preset) = &expressions.preset {
for (name, expression) in &preset.0 {
let name = crate::expressions::preset_expression_name(name);
validate_expression(
name,
format!("/extensions/VRMC_vrm/expressions/preset/{name}"),
expression,
)?;
}
}
if let Some(custom) = &expressions.custom {
for (name, expression) in custom {
if crate::expressions::is_preset_expression_name(name) {
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_vrm/expressions/custom/{name} conflicts with a preset expression name"
)));
}
validate_expression(
name,
format!("/extensions/VRMC_vrm/expressions/custom/{name}"),
expression,
)?;
}
}
}
Ok(())
}
fn is_representable_f32(value: f64) -> bool {
value.is_finite() && (value as f32).is_finite()
}
fn semantic_violation(
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
code: &'static str,
path: &'static str,
message: &'static str,
) -> Result<(), crate::LoadError> {
match validation {
ValidationMode::Strict => Err(crate::LoadError::InvalidVrm(format!("{path}: {message}"))),
ValidationMode::Permissive => {
diagnostics.push(Diagnostic::warning(code, path, message));
Ok(())
}
}
}
fn human_bone_name(name: HumanBoneName) -> String {
serde_json::to_value(name)
.ok()
.and_then(|value| value.as_str().map(str::to_owned))
.unwrap_or_else(|| format!("{name:?}"))
}
fn load_primitives(
doc: &gltf::Document,
buffers: &[gltf::buffer::Data],
) -> Result<Vec<RenderPrimitive>, crate::LoadError> {
crate::primitive::load_primitives(doc, buffers)
}
fn load_images(
doc: &gltf::Document,
buffers: &[gltf::buffer::Data],
base: Option<&Path>,
) -> Result<Vec<AvatarImage>, crate::LoadError> {
crate::image::load_images(doc, buffers, base)
}
fn load_materials(doc: &gltf::Document) -> Result<Vec<Material>, crate::LoadError> {
crate::material::load_materials(doc)
}
fn load_skins(
doc: &gltf::Document,
buffers: &[gltf::buffer::Data],
) -> Result<Vec<Skin>, crate::LoadError> {
crate::skin::load_skins(doc, buffers)
}
fn load_constraints(doc: &gltf::Document) -> Result<Vec<NodeConstraint>, crate::LoadError> {
constraint::load_constraints(doc)
}
fn load_spring_bone(
doc: &gltf::Document,
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
) -> Result<SpringBone, crate::LoadError> {
let Some(value) = doc.extension_value(VRMC_SPRING_BONE) else {
return Ok(SpringBone::default());
};
let schema =
serde_json::from_value::<VrmcSpringBoneSchema>(value.to_owned()).map_err(|source| {
crate::LoadError::InvalidExtension {
extension: VRMC_SPRING_BONE,
location: "/extensions/VRMC_springBone".to_string(),
source,
}
})?;
let normalized = crate::spring_bone::validate_schema_with_plane_normalization(
doc,
&schema,
validation == ValidationMode::Permissive,
)?;
if normalized {
diagnostics.push(Diagnostic::warning(
"VRM_SPRING_COLLIDER_PLANE_NORMAL_NORMALIZED",
"/extensions/VRMC_springBone/colliders/*/extensions/VRMC_springBone_extended_collider/shape/plane/normal",
"a finite extended plane collider normal was normalized in permissive mode",
));
}
let mut spring_bone = SpringBone::load_spring_bone(&schema);
crate::spring_bone::sort_springs_by_ancestry(doc, &mut spring_bone);
Ok(spring_bone)
}