1use std::collections::HashSet;
2use std::path::Path;
3use vrm_spec::vrmc_vrm_1_0::{HumanBoneName, VRMC_VRM, VRMCVrmSchema};
4
5use crate::constraint::{self, NodeConstraint};
6use crate::diagnostic::{Diagnostic, LoadOptions, ValidationMode};
7use crate::expressions::Expressions;
8use crate::first_person::FirstPerson;
9use crate::humanoid::{HumanBone, Humanoid};
10use crate::image::AvatarImage;
11use crate::instance::AvatarInstance;
12use crate::look_at::LookAt;
13use crate::material::{AvatarTexture, Material};
14use crate::meta::AvatarMeta;
15use crate::node::{self, AvatarNode};
16use crate::primitive::RenderPrimitive;
17use crate::skin::Skin;
18use crate::spring_bone::SpringBone;
19use crate::{ImageId, MaterialId, NodeId, PrimitiveId, SkinId, TextureId};
20use vrm_spec::vrmc_spring_bone_1_0::{VRMC_SPRING_BONE, VrmcSpringBoneSchema};
21
22#[derive(Debug, Clone)]
30pub struct AvatarAsset {
31 meta: AvatarMeta,
32 humanoid: Humanoid,
33 expressions: Expressions,
34 primitives: Vec<RenderPrimitive>,
35 look_at: Option<LookAt>,
36 pub(crate) images: Vec<AvatarImage>,
37 pub(crate) materials: Vec<Material>,
38 pub(crate) textures: Vec<AvatarTexture>,
39 pub(crate) skins: Vec<Skin>,
40 node_constraints: Vec<NodeConstraint>,
41 spring_bone: SpringBone,
42 pub(crate) first_person: FirstPerson,
43 nodes: Vec<AvatarNode>,
44 vrmc_vrm: Option<VRMCVrmSchema>,
45}
46
47impl AvatarAsset {
48 pub(crate) fn new() -> Self {
49 Self {
50 meta: AvatarMeta::default(),
51 humanoid: Humanoid::default(),
52 expressions: Expressions::default(),
53 primitives: Vec::new(),
54 look_at: None,
55 images: Vec::new(),
56 materials: Vec::new(),
57 textures: Vec::new(),
58 skins: Vec::new(),
59 node_constraints: Vec::new(),
60 spring_bone: SpringBone::default(),
61 first_person: FirstPerson::default(),
62 nodes: Vec::new(),
63 vrmc_vrm: None,
64 }
65 }
66
67 pub fn meta(&self) -> &AvatarMeta {
69 &self.meta
70 }
71
72 pub(crate) fn with_meta(mut self, meta: AvatarMeta) -> Self {
74 self.meta = meta;
75 self
76 }
77
78 pub fn humanoid(&self) -> &Humanoid {
80 &self.humanoid
81 }
82
83 pub(crate) fn with_humanoid(mut self, humanoid: Humanoid) -> Self {
85 self.humanoid = humanoid;
86 self
87 }
88
89 pub fn expressions(&self) -> &Expressions {
91 &self.expressions
92 }
93
94 pub(crate) fn with_expressions(mut self, expressions: Expressions) -> Self {
96 self.expressions = expressions;
97 self
98 }
99
100 pub fn primitives(&self) -> &[RenderPrimitive] {
102 &self.primitives
103 }
104
105 pub fn primitive(&self, id: PrimitiveId) -> Option<&RenderPrimitive> {
107 self.primitives.get(id.index())
108 }
109
110 pub(crate) fn with_primitives(mut self, primitives: Vec<RenderPrimitive>) -> Self {
112 self.primitives = primitives;
113 self
114 }
115
116 pub fn look_at(&self) -> Option<&LookAt> {
118 self.look_at.as_ref()
119 }
120
121 pub(crate) fn with_look_at(mut self, look_at: LookAt) -> Self {
123 self.look_at = Some(look_at);
124 self
125 }
126
127 pub fn images(&self) -> &[AvatarImage] {
129 &self.images
130 }
131
132 pub fn image(&self, id: ImageId) -> Option<&AvatarImage> {
134 self.images.get(id.index())
135 }
136
137 pub fn materials(&self) -> &[Material] {
139 &self.materials
140 }
141
142 pub fn material(&self, id: MaterialId) -> Option<&Material> {
144 self.materials.get(id.index())
145 }
146
147 pub fn textures(&self) -> &[AvatarTexture] {
149 &self.textures
150 }
151
152 pub fn texture(&self, id: TextureId) -> Option<&AvatarTexture> {
154 self.textures.get(id.index())
155 }
156
157 pub fn base_color(
162 &self,
163 material_index: u32,
164 color_type: crate::MaterialColorType,
165 ) -> [f32; 4] {
166 let Some(material) = self.materials.get(material_index as usize) else {
167 return [1.0, 1.0, 1.0, 1.0];
168 };
169
170 match color_type {
171 crate::MaterialColorType::Color => material.base_color_factor,
172 crate::MaterialColorType::EmissionColor => [
173 material.emissive_factor[0],
174 material.emissive_factor[1],
175 material.emissive_factor[2],
176 1.0,
177 ],
178 crate::MaterialColorType::ShadeColor => material
179 .mtoon()
180 .map(|mtoon| mtoon.shade_color.extend(1.0).to_array())
181 .unwrap_or([1.0; 4]),
182 crate::MaterialColorType::MatcapColor => material
183 .mtoon()
184 .map(|mtoon| mtoon.matcap_factor.extend(1.0).to_array())
185 .unwrap_or([1.0; 4]),
186 crate::MaterialColorType::RimColor => material
187 .mtoon()
188 .map(|mtoon| mtoon.parametric_rim_color_factor.extend(1.0).to_array())
189 .unwrap_or([1.0; 4]),
190 crate::MaterialColorType::OutlineColor => material
191 .mtoon()
192 .map(|mtoon| mtoon.outline_color_factor.extend(1.0).to_array())
193 .unwrap_or([1.0; 4]),
194 }
195 }
196
197 pub fn instantiate(&self) -> AvatarInstance {
200 AvatarInstance::new()
201 }
202
203 pub fn skins(&self) -> &[Skin] {
205 &self.skins
206 }
207
208 pub fn skin(&self, id: SkinId) -> Option<&Skin> {
210 self.skins.get(id.index())
211 }
212
213 #[cfg(test)]
214 pub(crate) fn with_skins(mut self, skins: Vec<Skin>) -> Self {
215 self.skins = skins;
216 self
217 }
218
219 pub fn node_constraints(&self) -> &[NodeConstraint] {
221 &self.node_constraints
222 }
223
224 pub(crate) fn with_node_constraints(mut self, node_constraints: Vec<NodeConstraint>) -> Self {
226 self.node_constraints = node_constraints;
227 self
228 }
229
230 pub fn spring_bone(&self) -> &SpringBone {
232 &self.spring_bone
233 }
234
235 pub(crate) fn with_spring_bone(mut self, spring_bone: SpringBone) -> Self {
237 self.spring_bone = spring_bone;
238 self
239 }
240
241 pub fn first_person(&self) -> &FirstPerson {
243 &self.first_person
244 }
245
246 pub fn nodes(&self) -> &[AvatarNode] {
248 &self.nodes
249 }
250
251 pub fn node(&self, id: NodeId) -> Option<&AvatarNode> {
253 self.nodes.get(id.index())
254 }
255
256 pub(crate) fn with_nodes(mut self, nodes: Vec<AvatarNode>) -> Self {
258 self.nodes = nodes;
259 self
260 }
261
262 pub fn compute_world_matrices(
264 &self,
265 bone_updates: &[crate::instance::BoneUpdate],
266 ) -> Vec<glam::Mat4> {
267 node::compute_world_matrices(&self.nodes, bone_updates)
268 }
269
270 pub fn compute_joint_matrices(
272 &self,
273 skin: &Skin,
274 bone_updates: &[crate::instance::BoneUpdate],
275 ) -> Vec<glam::Mat4> {
276 node::compute_joint_matrices(&self.nodes, skin, bone_updates)
277 }
278
279 pub fn vrmc_vrm(&self) -> Option<&VRMCVrmSchema> {
281 self.vrmc_vrm.as_ref()
282 }
283
284 pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, crate::LoadError> {
289 Ok(Self::from_file_with_options(path, LoadOptions::default())?.asset)
290 }
291
292 pub fn from_bytes(bytes: &[u8]) -> Result<Self, crate::LoadError> {
297 Ok(Self::from_bytes_with_options(bytes, LoadOptions::default())?.asset)
298 }
299
300 pub fn from_file_with_options<P: AsRef<Path>>(
304 path: P,
305 options: LoadOptions,
306 ) -> Result<LoadOutcome, crate::LoadError> {
307 let path_ref = path.as_ref();
308 let bytes = std::fs::read(path_ref).map_err(|source| crate::LoadError::Io {
309 path: path_ref.to_path_buf(),
310 source,
311 })?;
312 Self::from_bytes_with_options_and_base(&bytes, options, path_ref.parent())
313 }
314
315 pub fn from_bytes_with_options(
318 bytes: &[u8],
319 options: LoadOptions,
320 ) -> Result<LoadOutcome, crate::LoadError> {
321 Self::from_bytes_with_options_and_base(bytes, options, None)
322 }
323
324 fn from_bytes_with_options_and_base(
325 bytes: &[u8],
326 options: LoadOptions,
327 base: Option<&Path>,
328 ) -> Result<LoadOutcome, crate::LoadError> {
329 let mut gltf = gltf::Gltf::from_slice_without_validation(bytes)?;
332 validate_raw_node_graph(gltf.document.as_json())?;
333 crate::image::validate_raw_sources(gltf.document.as_json())?;
334 crate::primitive::validate_referenced_primitive_positions(gltf.document.as_json())?;
335 validate_required_extensions(&gltf.document)?;
336 validate_gltf_document(&gltf.document)?;
337 let buffers = gltf::import_buffers(&gltf.document, base, gltf.blob.take())?;
338 let doc = gltf.document;
339
340 let schema = Self::parse_vrm_schema(&doc)?;
342 let mut diagnostics = Vec::new();
343 collect_optional_extension_diagnostics(&doc, options.validation, &mut diagnostics);
344 collect_material_compatibility_diagnostics(&doc, &mut diagnostics);
345 validate_vrm_semantics(&doc, &schema, options.validation, &mut diagnostics)?;
346 let meta = AvatarMeta::load_meta(&schema.meta);
347 let humanoid = Humanoid::load_humanoid(&schema.humanoid);
348 let expressions = schema
349 .expressions
350 .as_ref()
351 .map(Expressions::load_expressions)
352 .unwrap_or_default();
353 let look_at = schema.look_at.as_ref().map(LookAt::load_look_at);
354 let first_person = schema
355 .first_person
356 .as_ref()
357 .map(FirstPerson::load_first_person)
358 .unwrap_or_default();
359
360 let primitives = load_primitives(&doc, &buffers)?;
362 let images = load_images(&doc, &buffers, base)?;
363 crate::image::validate_thumbnail(
364 &images,
365 schema
366 .meta
367 .thumbnail_image
368 .as_ref()
369 .map(|index| index.value()),
370 )?;
371 let materials = load_materials(&doc)?;
372 let textures = crate::material::load_textures(&doc);
373 let skins = load_skins(&doc, &buffers)?;
374 let node_constraints = load_constraints(&doc)?;
375 let spring_bone = load_spring_bone(&doc, options.validation, &mut diagnostics)?;
376 let nodes = node::load_nodes(&doc);
377
378 let asset = Self {
379 meta,
380 humanoid,
381 expressions,
382 primitives,
383 look_at,
384 images,
385 materials,
386 textures,
387 skins,
388 node_constraints,
389 spring_bone,
390 first_person,
391 nodes,
392 vrmc_vrm: Some(schema),
393 };
394 Ok(LoadOutcome { asset, diagnostics })
395 }
396
397 fn parse_vrm_schema(doc: &gltf::Document) -> Result<VRMCVrmSchema, crate::LoadError> {
398 match doc.extension_value(VRMC_VRM) {
399 Some(value) => Ok(serde_json::from_value(value.to_owned())?),
400 None if doc.extension_value("VRM").is_some() => {
401 Err(crate::LoadError::UnsupportedVrmVersion)
402 }
403 None => Err(crate::LoadError::MissingVrmExtension),
404 }
405 }
406
407 pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, crate::LoadError> {
429 Self::from_file(path)
430 }
431
432 pub fn load_with_options<P: AsRef<Path>>(
434 path: P,
435 options: LoadOptions,
436 ) -> Result<LoadOutcome, crate::LoadError> {
437 Self::from_file_with_options(path, options)
438 }
439
440 pub const fn capabilities() -> crate::Capabilities {
442 crate::Capabilities::current()
443 }
444
445 pub(crate) fn validate_programmatic(&self) -> Result<(), crate::BuildError> {
446 let invalid = |message: String| crate::BuildError::InvalidAsset(message);
447
448 if self.meta.name().trim().is_empty() {
449 return Err(invalid("meta.name must not be empty".to_string()));
450 }
451 if self.meta.authors().is_empty()
452 || self
453 .meta
454 .authors()
455 .iter()
456 .any(|author| author.trim().is_empty())
457 {
458 return Err(invalid(
459 "meta.authors must contain at least one non-empty author".to_string(),
460 ));
461 }
462 if self
463 .meta
464 .license_url()
465 .is_none_or(|license| license.trim().is_empty())
466 {
467 return Err(invalid("meta.license_url must not be empty".to_string()));
468 }
469 if self
470 .meta
471 .references()
472 .is_some_and(|references| references.is_empty())
473 {
474 return Err(invalid(
475 "meta.references must contain at least one item when present".to_string(),
476 ));
477 }
478 if let Some(look_at) = &self.look_at {
479 look_at
480 .validate_programmatic()
481 .map_err(crate::BuildError::InvalidAsset)?;
482 }
483
484 for (position, node) in self.nodes.iter().enumerate() {
485 if node.index as usize != position {
486 return Err(invalid(format!(
487 "node storage position {position} does not match node index {}",
488 node.index
489 )));
490 }
491 if !node.initial_translation.is_finite()
492 || !node.initial_rotation.is_finite()
493 || !node.initial_scale.is_finite()
494 {
495 return Err(invalid(format!(
496 "node {position} contains a non-finite transform"
497 )));
498 }
499 if !is_positive_uniform_scale(node.initial_scale.to_array()) {
500 return Err(invalid(format!(
501 "node {position} must use a positive uniform scale"
502 )));
503 }
504 if node
505 .parent
506 .is_some_and(|parent| parent as usize >= self.nodes.len() || parent == node.index)
507 {
508 return Err(invalid(format!("node {position} has an invalid parent")));
509 }
510 let mut unique_children = HashSet::new();
511 for &child in &node.children {
512 if child as usize >= self.nodes.len()
513 || child == node.index
514 || !unique_children.insert(child)
515 {
516 return Err(invalid(format!("node {position} has an invalid child")));
517 }
518 if self.nodes[child as usize].parent != Some(node.index) {
519 return Err(invalid(format!(
520 "node {position} and child {child} disagree about their relationship"
521 )));
522 }
523 }
524 if let Some(parent) = node.parent
525 && !self.nodes[parent as usize].children.contains(&node.index)
526 {
527 return Err(invalid(format!(
528 "node {position} and parent {parent} disagree about their relationship"
529 )));
530 }
531
532 let mut ancestors = HashSet::new();
533 let mut cursor = node.parent;
534 while let Some(parent) = cursor {
535 if !ancestors.insert(parent) {
536 return Err(invalid(format!(
537 "node hierarchy contains a cycle through node {parent}"
538 )));
539 }
540 cursor = self
541 .nodes
542 .get(parent as usize)
543 .and_then(|ancestor| ancestor.parent);
544 }
545 }
546
547 let mut assigned_nodes = HashSet::new();
548 for (bone, node) in self.humanoid.bones() {
549 if node.0 as usize >= self.nodes.len() {
550 return Err(invalid(format!(
551 "humanoid bone `{bone:?}` references missing node {}",
552 node.0
553 )));
554 }
555 if !assigned_nodes.insert(node.0) {
556 return Err(invalid(format!(
557 "node {} is assigned to more than one humanoid bone",
558 node.0
559 )));
560 }
561 }
562
563 for required in REQUIRED_HUMAN_BONES {
564 let bone = HumanBone::from(required);
565 if self.humanoid.bone(bone).is_none() {
566 return Err(invalid(format!(
567 "humanoid bone `{}` is required",
568 human_bone_name(required)
569 )));
570 }
571 }
572
573 let node_parents = self
574 .nodes
575 .iter()
576 .map(|node| node.parent.map(|parent| parent as usize))
577 .collect::<Vec<_>>();
578 let mapped_bones = self
579 .humanoid
580 .bones()
581 .map(|(&bone, node)| (bone, node.0 as usize));
582 if let Some(violation) = crate::humanoid::hierarchy_violations(mapped_bones, &node_parents)
583 .into_iter()
584 .next()
585 {
586 return Err(invalid(violation.message()));
587 }
588
589 for (skin_index, skin) in self.skins.iter().enumerate() {
590 if skin.joints().len() != skin.inverse_bind_matrices().len() {
591 return Err(invalid(format!(
592 "skin {skin_index} must have one inverse bind matrix per joint"
593 )));
594 }
595 if skin
596 .joints()
597 .iter()
598 .any(|&node| node as usize >= self.nodes.len())
599 || skin.inverse_bind_matrices().iter().any(|matrix| {
600 matrix
601 .to_cols_array()
602 .iter()
603 .any(|component| !component.is_finite())
604 })
605 {
606 return Err(invalid(format!(
607 "skin {skin_index} contains an invalid joint or matrix"
608 )));
609 }
610 }
611
612 for (texture_index, texture) in self.textures.iter().enumerate() {
613 if texture.image_id().index() >= self.images.len() {
614 return Err(invalid(format!(
615 "texture {texture_index} references a missing image"
616 )));
617 }
618 }
619
620 let validate_texture =
621 |label: &str, texture: Option<&crate::TextureInfo>| -> Result<(), crate::BuildError> {
622 if let Some(texture) = texture {
623 if texture.texture_id().index() >= self.textures.len() {
624 return Err(invalid(format!("{label} references a missing texture")));
625 }
626 let transform = texture.transform();
627 if !transform.rotation.is_finite()
628 || transform.offset.iter().any(|value| !value.is_finite())
629 || transform.scale.iter().any(|value| !value.is_finite())
630 {
631 return Err(invalid(format!("{label} has a non-finite UV transform")));
632 }
633 }
634 Ok(())
635 };
636 for (material_index, material) in self.materials.iter().enumerate() {
637 validate_texture(
638 &format!("material {material_index} base color texture"),
639 material.base_color_texture(),
640 )?;
641 validate_texture(
642 &format!("material {material_index} normal texture"),
643 material.normal_texture().map(|normal| &normal.texture),
644 )?;
645 validate_texture(
646 &format!("material {material_index} emissive texture"),
647 material.emissive_texture(),
648 )?;
649 if let Some(mtoon) = material.mtoon() {
650 for (name, texture) in [
651 ("shade multiply", mtoon.shade_multiply_texture.as_ref()),
652 ("shading shift", mtoon.shading_shift_texture.as_ref()),
653 ("matcap", mtoon.matcap_texture.as_ref()),
654 ("rim multiply", mtoon.rim_multiply_texture.as_ref()),
655 (
656 "outline width multiply",
657 mtoon.outline_width_multiply_texture.as_ref(),
658 ),
659 (
660 "UV animation mask",
661 mtoon.uv_animation_mask_texture.as_ref(),
662 ),
663 ] {
664 validate_texture(
665 &format!("material {material_index} {name} texture"),
666 texture,
667 )?;
668 }
669 }
670 }
671
672 for (primitive_index, primitive) in self.primitives.iter().enumerate() {
673 if primitive.node_index() as usize >= self.nodes.len() {
674 return Err(invalid(format!(
675 "primitive {primitive_index} references a missing node"
676 )));
677 }
678 if primitive
679 .material_index()
680 .is_some_and(|material| material >= self.materials.len())
681 || primitive
682 .texture_index()
683 .is_some_and(|texture| texture >= self.textures.len())
684 || primitive
685 .skin_index()
686 .is_some_and(|skin| skin >= self.skins.len())
687 {
688 return Err(invalid(format!(
689 "primitive {primitive_index} references a missing asset object"
690 )));
691 }
692 if primitive
693 .indices()
694 .iter()
695 .any(|&index| index as usize >= primitive.positions().len())
696 {
697 return Err(invalid(format!(
698 "primitive {primitive_index} contains an out-of-range vertex index"
699 )));
700 }
701 }
702
703 let mut expression_names = HashSet::new();
704 for expression in self.expressions.iter() {
705 if expression.name().is_empty() || !expression_names.insert(expression.name()) {
706 return Err(invalid(
707 "expression names must be non-empty and unique".to_string(),
708 ));
709 }
710 crate::expressions::validate_override_semantics(
711 expression.name(),
712 expression.override_blink(),
713 expression.override_mouth(),
714 expression.override_look_at(),
715 )
716 .map_err(invalid)?;
717 for bind in expression.morph_target_binds() {
718 let matching: Vec<_> = self
719 .primitives
720 .iter()
721 .filter(|primitive| primitive.node_index() == bind.node_index())
722 .collect();
723 if matching.is_empty()
724 || matching.iter().any(|primitive| {
725 bind.target_index() as usize >= primitive.morph_targets().len()
726 })
727 || !bind.weight().is_finite()
728 || !(0.0..=1.0).contains(&bind.weight())
729 {
730 return Err(invalid(format!(
731 "expression `{}` contains an invalid morph target bind",
732 expression.name()
733 )));
734 }
735 }
736 for bind in expression.material_color_binds() {
737 if bind.material_index as usize >= self.materials.len()
738 || bind.target_value.iter().any(|value| !value.is_finite())
739 {
740 return Err(invalid(format!(
741 "expression `{}` contains an invalid material color bind",
742 expression.name()
743 )));
744 }
745 }
746 for bind in expression.texture_transform_binds() {
747 if bind.material_index as usize >= self.materials.len()
748 || bind.scale.iter().any(|value| !value.is_finite())
749 || bind.offset.iter().any(|value| !value.is_finite())
750 {
751 return Err(invalid(format!(
752 "expression `{}` contains an invalid texture transform bind",
753 expression.name()
754 )));
755 }
756 }
757 }
758
759 for annotation in &self.first_person.mesh_annotations {
760 if annotation.node_index as usize >= self.nodes.len()
761 || !self
762 .primitives
763 .iter()
764 .any(|primitive| primitive.node_index() == annotation.node_index)
765 {
766 return Err(invalid(format!(
767 "first-person annotation references node {} without a mesh",
768 annotation.node_index
769 )));
770 }
771 }
772
773 constraint::validate_programmatic(&self.node_constraints, self.nodes.len())
774 .map_err(invalid)?;
775 crate::spring_bone::validate_programmatic(&self.nodes, &self.spring_bone)
776 .map_err(invalid)?;
777
778 Ok(())
779 }
780}
781
782fn validate_raw_node_graph(root: &gltf::json::Root) -> Result<(), crate::LoadError> {
783 let node_count = root.nodes.len();
784 let mut indegree = vec![0usize; node_count];
785 let mut children = vec![Vec::new(); node_count];
786
787 for (parent, node) in root.nodes.iter().enumerate() {
788 for child in node.children.as_deref().unwrap_or_default() {
789 let child = child.value();
790 if child >= node_count {
791 return Err(crate::LoadError::InvalidVrm(format!(
792 "/nodes/{parent}/children references missing node {child}"
793 )));
794 }
795 indegree[child] += 1;
796 if indegree[child] > 1 {
797 return Err(crate::LoadError::InvalidVrm(format!(
798 "node {child} has more than one parent"
799 )));
800 }
801 children[parent].push(child);
802 }
803 }
804
805 let mut roots: std::collections::VecDeque<_> = indegree
806 .iter()
807 .enumerate()
808 .filter_map(|(index, °ree)| (degree == 0).then_some(index))
809 .collect();
810 let mut visited = 0usize;
811 while let Some(parent) = roots.pop_front() {
812 visited += 1;
813 for &child in &children[parent] {
814 indegree[child] -= 1;
815 if indegree[child] == 0 {
816 roots.push_back(child);
817 }
818 }
819 }
820 if visited != node_count {
821 return Err(crate::LoadError::InvalidVrm(
822 "node hierarchy contains a cycle".to_string(),
823 ));
824 }
825 Ok(())
826}
827
828#[derive(Debug)]
830pub struct LoadOutcome {
831 pub asset: AvatarAsset,
833 pub diagnostics: Vec<Diagnostic>,
835}
836
837fn validate_required_extensions(doc: &gltf::Document) -> Result<(), crate::LoadError> {
838 crate::extension_declarations::validate(doc.as_json()).map_err(crate::LoadError::InvalidVrm)?;
839 for extension in doc.extensions_required() {
840 if !SUPPORTED_EXTENSIONS.contains(&extension) {
841 return Err(crate::LoadError::UnsupportedRequiredExtension(
842 extension.to_string(),
843 ));
844 }
845 }
846 Ok(())
847}
848
849fn validate_gltf_document(doc: &gltf::Document) -> Result<(), crate::LoadError> {
852 let mut root = doc.as_json().clone();
853 root.extensions_required
854 .retain(|extension| !SUPPORTED_EXTENSIONS.contains(&extension.as_str()));
855 gltf::Document::from_json(root)?;
856 Ok(())
857}
858
859const SUPPORTED_EXTENSIONS: &[&str] = &[
860 "VRMC_vrm",
861 "VRMC_materials_mtoon",
862 "VRMC_materials_hdr_emissiveMultiplier",
863 "VRMC_node_constraint",
864 "VRMC_springBone",
865 "VRMC_springBone_extended_collider",
866 "KHR_materials_unlit",
867 "KHR_materials_emissive_strength",
868 "KHR_texture_transform",
869];
870
871fn collect_optional_extension_diagnostics(
872 doc: &gltf::Document,
873 validation: ValidationMode,
874 diagnostics: &mut Vec<Diagnostic>,
875) {
876 if validation != ValidationMode::Permissive {
877 return;
878 }
879 let required: HashSet<_> = doc.extensions_required().collect();
880 for extension in doc.extensions_used() {
881 if !SUPPORTED_EXTENSIONS.contains(&extension) && !required.contains(extension) {
882 diagnostics.push(Diagnostic::warning(
883 "VRM_UNSUPPORTED_OPTIONAL_EXTENSION",
884 "/extensionsUsed",
885 format!(
886 "optional extension `{extension}` is not interpreted; its fallback data is used"
887 ),
888 ));
889 }
890 }
891}
892
893fn collect_material_compatibility_diagnostics(
894 doc: &gltf::Document,
895 diagnostics: &mut Vec<Diagnostic>,
896) {
897 const LEGACY: &str = "VRMC_materials_hdr_emissiveMultiplier";
898 const KHR: &str = "KHR_materials_emissive_strength";
899
900 for material in doc.materials() {
901 if material.extension_value(LEGACY).is_none() {
902 continue;
903 }
904 let index = material.index().unwrap_or(0);
905 diagnostics.push(Diagnostic::warning(
906 "VRM_DEPRECATED_HDR_EMISSIVE_MULTIPLIER",
907 format!("/materials/{index}/extensions/{LEGACY}"),
908 format!("`{LEGACY}` is archived; prefer `{KHR}` for new assets"),
909 ));
910 if material.emissive_strength().is_some() {
911 diagnostics.push(Diagnostic::warning(
912 "VRM_EMISSIVE_STRENGTH_PRECEDENCE",
913 format!("/materials/{index}/extensions"),
914 format!("both emissive strength extensions are present; `{KHR}` takes precedence"),
915 ));
916 }
917 }
918}
919
920const REQUIRED_HUMAN_BONES: [HumanBoneName; 15] = [
922 HumanBoneName::Hips,
923 HumanBoneName::Spine,
924 HumanBoneName::Head,
925 HumanBoneName::LeftUpperLeg,
926 HumanBoneName::LeftLowerLeg,
927 HumanBoneName::LeftFoot,
928 HumanBoneName::RightUpperLeg,
929 HumanBoneName::RightLowerLeg,
930 HumanBoneName::RightFoot,
931 HumanBoneName::LeftUpperArm,
932 HumanBoneName::LeftLowerArm,
933 HumanBoneName::LeftHand,
934 HumanBoneName::RightUpperArm,
935 HumanBoneName::RightLowerArm,
936 HumanBoneName::RightHand,
937];
938
939fn validate_vrm_semantics(
943 doc: &gltf::Document,
944 schema: &VRMCVrmSchema,
945 validation: ValidationMode,
946 diagnostics: &mut Vec<Diagnostic>,
947) -> Result<(), crate::LoadError> {
948 let node_count = doc.nodes().count();
949 if schema.spec_version != "1.0" {
950 return Err(crate::LoadError::InvalidVrm(format!(
951 "unsupported VRMC_vrm specVersion `{}` (expected 1.0)",
952 schema.spec_version
953 )));
954 }
955
956 let bones = &schema.humanoid.human_bones.0;
957 let mut assigned_nodes: HashSet<usize> = HashSet::new();
958
959 for &required in &REQUIRED_HUMAN_BONES {
960 let bone = bones
961 .get(&required)
962 .and_then(|entry| entry.as_ref())
963 .ok_or_else(|| {
964 crate::LoadError::InvalidVrm(format!(
965 "humanoid bone `{}` is required but missing",
966 human_bone_name(required)
967 ))
968 })?;
969 let node_index = bone.node.map(|index| index.value()).ok_or_else(|| {
970 crate::LoadError::InvalidVrm(format!(
971 "humanoid bone `{}` has no node assignment",
972 human_bone_name(required)
973 ))
974 })?;
975 if node_index >= node_count {
976 return Err(crate::LoadError::InvalidVrm(format!(
977 "humanoid bone `{}` references missing node {}",
978 human_bone_name(required),
979 node_index
980 )));
981 }
982 if !assigned_nodes.insert(node_index) {
983 return Err(crate::LoadError::InvalidVrm(format!(
984 "node {} is assigned to more than one humanoid bone",
985 node_index
986 )));
987 }
988 }
989
990 if schema.meta.name.trim().is_empty() {
991 semantic_violation(
992 validation,
993 diagnostics,
994 "VRM_META_NAME_EMPTY",
995 "/extensions/VRMC_vrm/meta/name",
996 "meta.name must not be empty",
997 )?;
998 }
999 if schema.meta.authors.is_empty()
1000 || schema
1001 .meta
1002 .authors
1003 .iter()
1004 .any(|author| author.trim().is_empty())
1005 {
1006 semantic_violation(
1007 validation,
1008 diagnostics,
1009 "VRM_META_AUTHORS_INVALID",
1010 "/extensions/VRMC_vrm/meta/authors",
1011 "meta.authors must contain at least one non-empty author",
1012 )?;
1013 }
1014 if schema.meta.references.as_ref().is_some_and(Vec::is_empty) {
1015 semantic_violation(
1016 validation,
1017 diagnostics,
1018 "VRM_META_REFERENCES_EMPTY",
1019 "/extensions/VRMC_vrm/meta/references",
1020 "meta.references must contain at least one item when present",
1021 )?;
1022 }
1023
1024 if let Some(look_at) = &schema.look_at {
1025 crate::look_at::validate_schema(look_at).map_err(crate::LoadError::InvalidVrm)?;
1026 }
1027
1028 for (name, entry) in bones {
1029 if REQUIRED_HUMAN_BONES.contains(name) {
1030 continue;
1031 }
1032 let bone = entry.as_ref().ok_or_else(|| {
1033 crate::LoadError::InvalidVrm(format!(
1034 "humanoid bone `{}` must be an object containing `node`",
1035 human_bone_name(*name)
1036 ))
1037 })?;
1038 let node_index = bone.node.map(|index| index.value()).ok_or_else(|| {
1039 crate::LoadError::InvalidVrm(format!(
1040 "humanoid bone `{}` must contain `node`",
1041 human_bone_name(*name)
1042 ))
1043 })?;
1044 if node_index >= node_count {
1045 return Err(crate::LoadError::InvalidVrm(format!(
1046 "humanoid bone `{}` references missing node {}",
1047 human_bone_name(*name),
1048 node_index
1049 )));
1050 }
1051 if !assigned_nodes.insert(node_index) {
1052 return Err(crate::LoadError::InvalidVrm(format!(
1053 "node {} is assigned to more than one humanoid bone",
1054 node_index
1055 )));
1056 }
1057 }
1058
1059 validate_node_transforms(doc, validation, diagnostics)?;
1060 validate_humanoid_hierarchy(doc, &schema.humanoid.human_bones, validation, diagnostics)?;
1061 validate_vrm_references(doc, schema)?;
1062
1063 Ok(())
1064}
1065
1066fn validate_node_transforms(
1067 doc: &gltf::Document,
1068 validation: ValidationMode,
1069 diagnostics: &mut Vec<Diagnostic>,
1070) -> Result<(), crate::LoadError> {
1071 for node in doc.nodes() {
1072 let (_, _, scale) = node.transform().decomposed();
1073 if !is_positive_uniform_scale(scale) {
1074 let path = format!("/nodes/{}/scale", node.index());
1075 match validation {
1076 ValidationMode::Strict => {
1077 return Err(crate::LoadError::InvalidVrm(format!(
1078 "{path}: every node scale must be positive and uniform"
1079 )));
1080 }
1081 ValidationMode::Permissive => diagnostics.push(Diagnostic::warning(
1082 "VRM_NODE_SCALE_INVALID",
1083 path,
1084 "every node scale must be positive and uniform",
1085 )),
1086 }
1087 }
1088 }
1089 Ok(())
1090}
1091
1092fn is_positive_uniform_scale(scale: [f32; 3]) -> bool {
1093 let max_scale = scale.iter().copied().fold(0.0_f32, f32::max);
1094 let uniform_tolerance = max_scale * 2.0e-3;
1095 scale.iter().all(|value| value.is_finite() && *value > 0.0)
1096 && (scale[0] - scale[1]).abs() <= uniform_tolerance
1097 && (scale[1] - scale[2]).abs() <= uniform_tolerance
1098}
1099
1100fn validate_humanoid_hierarchy(
1101 doc: &gltf::Document,
1102 bones: &vrm_spec::vrmc_vrm_1_0::HumanBones,
1103 validation: ValidationMode,
1104 diagnostics: &mut Vec<Diagnostic>,
1105) -> Result<(), crate::LoadError> {
1106 let mut parents = vec![None; doc.nodes().count()];
1107 for node in doc.nodes() {
1108 for child in node.children() {
1109 parents[child.index()] = Some(node.index());
1110 }
1111 }
1112 let mapped_bones = bones.0.iter().filter_map(|(name, entry)| {
1113 entry
1114 .as_ref()
1115 .and_then(|bone| bone.node.map(|node| (HumanBone::from(*name), node.value())))
1116 });
1117 for violation in crate::humanoid::hierarchy_violations(mapped_bones, &parents) {
1118 let bone_name = violation.bone().spec_name();
1119 let message = violation.message();
1120 match validation {
1121 ValidationMode::Strict => return Err(crate::LoadError::InvalidVrm(message)),
1122 ValidationMode::Permissive => diagnostics.push(Diagnostic::warning(
1123 "VRM_HUMANOID_HIERARCHY_INVALID",
1124 format!("/extensions/VRMC_vrm/humanoid/humanBones/{bone_name}"),
1125 message,
1126 )),
1127 }
1128 }
1129 Ok(())
1130}
1131
1132fn validate_vrm_references(
1133 doc: &gltf::Document,
1134 schema: &VRMCVrmSchema,
1135) -> Result<(), crate::LoadError> {
1136 if let Some(thumbnail) = schema.meta.thumbnail_image.as_ref()
1137 && thumbnail.value() >= doc.images().count()
1138 {
1139 return Err(crate::LoadError::InvalidVrm(format!(
1140 "/extensions/VRMC_vrm/meta/thumbnailImage references missing image {}",
1141 thumbnail.value()
1142 )));
1143 }
1144
1145 if let Some(first_person) = &schema.first_person {
1146 if first_person
1147 .mesh_annotations
1148 .as_ref()
1149 .is_some_and(Vec::is_empty)
1150 {
1151 return Err(crate::LoadError::InvalidVrm(
1152 "/extensions/VRMC_vrm/firstPerson/meshAnnotations must contain at least one item when present"
1153 .to_string(),
1154 ));
1155 }
1156 for (index, annotation) in first_person
1157 .mesh_annotations
1158 .as_deref()
1159 .unwrap_or_default()
1160 .iter()
1161 .enumerate()
1162 {
1163 let node = annotation.node.as_ref().ok_or_else(|| {
1164 crate::LoadError::InvalidVrm(format!(
1165 "/extensions/VRMC_vrm/firstPerson/meshAnnotations/{index}/node is required"
1166 ))
1167 })?;
1168 let node_index = node.value();
1169 if node_index >= doc.nodes().count()
1170 || doc
1171 .nodes()
1172 .nth(node_index)
1173 .and_then(|node| node.mesh())
1174 .is_none()
1175 {
1176 return Err(crate::LoadError::InvalidVrm(format!(
1177 "/extensions/VRMC_vrm/firstPerson/meshAnnotations/{index}/node must reference a node with a mesh"
1178 )));
1179 }
1180 }
1181 }
1182
1183 let validate_expression = |name: &str,
1184 location: String,
1185 expression: &vrm_spec::vrmc_vrm_1_0::Expression|
1186 -> Result<(), crate::LoadError> {
1187 crate::expressions::validate_override_semantics(
1188 name,
1189 expression
1190 .override_blink
1191 .map(crate::ExpressionOverrideType::from)
1192 .unwrap_or_default(),
1193 expression
1194 .override_mouth
1195 .map(crate::ExpressionOverrideType::from)
1196 .unwrap_or_default(),
1197 expression
1198 .override_look_at
1199 .map(crate::ExpressionOverrideType::from)
1200 .unwrap_or_default(),
1201 )
1202 .map_err(|message| crate::LoadError::InvalidVrm(format!("{location}: {message}")))?;
1203
1204 for (name, empty) in [
1205 (
1206 "morphTargetBinds",
1207 expression
1208 .morph_target_binds
1209 .as_ref()
1210 .is_some_and(Vec::is_empty),
1211 ),
1212 (
1213 "materialColorBinds",
1214 expression
1215 .material_color_binds
1216 .as_ref()
1217 .is_some_and(Vec::is_empty),
1218 ),
1219 (
1220 "textureTransformBinds",
1221 expression
1222 .texture_transform_binds
1223 .as_ref()
1224 .is_some_and(Vec::is_empty),
1225 ),
1226 ] {
1227 if empty {
1228 return Err(crate::LoadError::InvalidVrm(format!(
1229 "{location}/{name} must contain at least one item when present"
1230 )));
1231 }
1232 }
1233
1234 for (index, bind) in expression
1235 .morph_target_binds
1236 .as_deref()
1237 .unwrap_or_default()
1238 .iter()
1239 .enumerate()
1240 {
1241 let node_index = bind.node.value();
1242 let Some(mesh) = doc.nodes().nth(node_index).and_then(|node| node.mesh()) else {
1243 return Err(crate::LoadError::InvalidVrm(format!(
1244 "{location}/morphTargetBinds/{index}/node must reference a node with a mesh"
1245 )));
1246 };
1247 if mesh
1248 .primitives()
1249 .any(|primitive| bind.index >= primitive.morph_targets().count())
1250 {
1251 return Err(crate::LoadError::InvalidVrm(format!(
1252 "{location}/morphTargetBinds/{index}/index is out of range"
1253 )));
1254 }
1255 if !bind.weight.is_finite() || !(0.0..=1.0).contains(&bind.weight) {
1256 return Err(crate::LoadError::InvalidVrm(format!(
1257 "{location}/morphTargetBinds/{index}/weight must be in 0..=1"
1258 )));
1259 }
1260 }
1261 for (index, bind) in expression
1262 .material_color_binds
1263 .as_deref()
1264 .unwrap_or_default()
1265 .iter()
1266 .enumerate()
1267 {
1268 if bind.material.value() >= doc.materials().count()
1269 || bind.target_value.len() != 4
1270 || bind
1271 .target_value
1272 .iter()
1273 .any(|&value| !is_representable_f32(value))
1274 {
1275 return Err(crate::LoadError::InvalidVrm(format!(
1276 "{location}/materialColorBinds/{index} has an invalid material or targetValue"
1277 )));
1278 }
1279 }
1280 for (index, bind) in expression
1281 .texture_transform_binds
1282 .as_deref()
1283 .unwrap_or_default()
1284 .iter()
1285 .enumerate()
1286 {
1287 let valid_vector = |value: Option<&Vec<f64>>| {
1288 value.is_none_or(|value| {
1289 value.len() == 2
1290 && value
1291 .iter()
1292 .all(|&component| is_representable_f32(component))
1293 })
1294 };
1295 if bind.material.value() >= doc.materials().count()
1296 || !valid_vector(bind.scale.as_ref())
1297 || !valid_vector(bind.offset.as_ref())
1298 {
1299 return Err(crate::LoadError::InvalidVrm(format!(
1300 "{location}/textureTransformBinds/{index} is invalid"
1301 )));
1302 }
1303 }
1304 Ok(())
1305 };
1306
1307 if let Some(expressions) = &schema.expressions {
1308 if let Some(preset) = &expressions.preset {
1309 for (name, expression) in &preset.0 {
1310 let name = crate::expressions::preset_expression_name(name);
1311 validate_expression(
1312 name,
1313 format!("/extensions/VRMC_vrm/expressions/preset/{name}"),
1314 expression,
1315 )?;
1316 }
1317 }
1318 if let Some(custom) = &expressions.custom {
1319 for (name, expression) in custom {
1320 if crate::expressions::is_preset_expression_name(name) {
1321 return Err(crate::LoadError::InvalidVrm(format!(
1322 "/extensions/VRMC_vrm/expressions/custom/{name} conflicts with a preset expression name"
1323 )));
1324 }
1325 validate_expression(
1326 name,
1327 format!("/extensions/VRMC_vrm/expressions/custom/{name}"),
1328 expression,
1329 )?;
1330 }
1331 }
1332 }
1333 Ok(())
1334}
1335
1336fn is_representable_f32(value: f64) -> bool {
1337 value.is_finite() && (value as f32).is_finite()
1338}
1339
1340fn semantic_violation(
1341 validation: ValidationMode,
1342 diagnostics: &mut Vec<Diagnostic>,
1343 code: &'static str,
1344 path: &'static str,
1345 message: &'static str,
1346) -> Result<(), crate::LoadError> {
1347 match validation {
1348 ValidationMode::Strict => Err(crate::LoadError::InvalidVrm(format!("{path}: {message}"))),
1349 ValidationMode::Permissive => {
1350 diagnostics.push(Diagnostic::warning(code, path, message));
1351 Ok(())
1352 }
1353 }
1354}
1355
1356fn human_bone_name(name: HumanBoneName) -> String {
1358 serde_json::to_value(name)
1359 .ok()
1360 .and_then(|value| value.as_str().map(str::to_owned))
1361 .unwrap_or_else(|| format!("{name:?}"))
1362}
1363
1364fn load_primitives(
1365 doc: &gltf::Document,
1366 buffers: &[gltf::buffer::Data],
1367) -> Result<Vec<RenderPrimitive>, crate::LoadError> {
1368 crate::primitive::load_primitives(doc, buffers)
1369}
1370
1371fn load_images(
1372 doc: &gltf::Document,
1373 buffers: &[gltf::buffer::Data],
1374 base: Option<&Path>,
1375) -> Result<Vec<AvatarImage>, crate::LoadError> {
1376 crate::image::load_images(doc, buffers, base)
1377}
1378
1379fn load_materials(doc: &gltf::Document) -> Result<Vec<Material>, crate::LoadError> {
1380 crate::material::load_materials(doc)
1381}
1382
1383fn load_skins(
1384 doc: &gltf::Document,
1385 buffers: &[gltf::buffer::Data],
1386) -> Result<Vec<Skin>, crate::LoadError> {
1387 crate::skin::load_skins(doc, buffers)
1388}
1389
1390fn load_constraints(doc: &gltf::Document) -> Result<Vec<NodeConstraint>, crate::LoadError> {
1391 constraint::load_constraints(doc)
1392}
1393
1394fn load_spring_bone(
1395 doc: &gltf::Document,
1396 validation: ValidationMode,
1397 diagnostics: &mut Vec<Diagnostic>,
1398) -> Result<SpringBone, crate::LoadError> {
1399 let Some(value) = doc.extension_value(VRMC_SPRING_BONE) else {
1400 return Ok(SpringBone::default());
1401 };
1402 let schema =
1403 serde_json::from_value::<VrmcSpringBoneSchema>(value.to_owned()).map_err(|source| {
1404 crate::LoadError::InvalidExtension {
1405 extension: VRMC_SPRING_BONE,
1406 location: "/extensions/VRMC_springBone".to_string(),
1407 source,
1408 }
1409 })?;
1410 let normalized = crate::spring_bone::validate_schema_with_plane_normalization(
1411 doc,
1412 &schema,
1413 validation == ValidationMode::Permissive,
1414 )?;
1415 if normalized {
1416 diagnostics.push(Diagnostic::warning(
1417 "VRM_SPRING_COLLIDER_PLANE_NORMAL_NORMALIZED",
1418 "/extensions/VRMC_springBone/colliders/*/extensions/VRMC_springBone_extended_collider/shape/plane/normal",
1419 "a finite extended plane collider normal was normalized in permissive mode",
1420 ));
1421 }
1422 let mut spring_bone = SpringBone::load_spring_bone(&schema);
1423 crate::spring_bone::sort_springs_by_ancestry(doc, &mut spring_bone);
1424 Ok(spring_bone)
1425}