Skip to main content

vrm_runtime/
avatar.rs

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/// A loaded VRM 1.0 avatar: the parsed VRM data (meta, humanoid, expressions,
23/// look-at, first-person, spring bones, constraints) plus the renderable
24/// glTF assets (nodes, primitives, materials, skins, images).
25///
26/// Load it with [`AvatarAsset::from_bytes`] / [`AvatarAsset::load`], or compose
27/// it programmatically with [`crate::AvatarAssetBuilder`]. Drive a frame with
28/// [`crate::AvatarRuntime`].
29#[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    /// Returns a reference to the [`AvatarMeta`].
68    pub fn meta(&self) -> &AvatarMeta {
69        &self.meta
70    }
71
72    /// Builder method that sets the [`AvatarMeta`].
73    pub(crate) fn with_meta(mut self, meta: AvatarMeta) -> Self {
74        self.meta = meta;
75        self
76    }
77
78    /// Returns a reference to the [`Humanoid`].
79    pub fn humanoid(&self) -> &Humanoid {
80        &self.humanoid
81    }
82
83    /// Builder method that sets the [`Humanoid`].
84    pub(crate) fn with_humanoid(mut self, humanoid: Humanoid) -> Self {
85        self.humanoid = humanoid;
86        self
87    }
88
89    /// Returns a reference to the [`Expressions`].
90    pub fn expressions(&self) -> &Expressions {
91        &self.expressions
92    }
93
94    /// Builder method that sets the [`Expressions`].
95    pub(crate) fn with_expressions(mut self, expressions: Expressions) -> Self {
96        self.expressions = expressions;
97        self
98    }
99
100    /// Returns the list of [`RenderPrimitive`]s parsed from the model.
101    pub fn primitives(&self) -> &[RenderPrimitive] {
102        &self.primitives
103    }
104
105    /// Resolves a type-safe primitive identifier.
106    pub fn primitive(&self, id: PrimitiveId) -> Option<&RenderPrimitive> {
107        self.primitives.get(id.index())
108    }
109
110    /// Builder method that sets the primitive list.
111    pub(crate) fn with_primitives(mut self, primitives: Vec<RenderPrimitive>) -> Self {
112        self.primitives = primitives;
113        self
114    }
115
116    /// Returns the [`LookAt`] configuration, if present.
117    pub fn look_at(&self) -> Option<&LookAt> {
118        self.look_at.as_ref()
119    }
120
121    /// Builder method that sets the [`LookAt`] configuration.
122    pub(crate) fn with_look_at(mut self, look_at: LookAt) -> Self {
123        self.look_at = Some(look_at);
124        self
125    }
126
127    /// Returns the list of [`AvatarImage`]s parsed from the model.
128    pub fn images(&self) -> &[AvatarImage] {
129        &self.images
130    }
131
132    /// Resolves a type-safe image identifier.
133    pub fn image(&self, id: ImageId) -> Option<&AvatarImage> {
134        self.images.get(id.index())
135    }
136
137    /// Returns common glTF materials with optional MToon parameters.
138    pub fn materials(&self) -> &[Material] {
139        &self.materials
140    }
141
142    /// Resolves a type-safe material identifier.
143    pub fn material(&self, id: MaterialId) -> Option<&Material> {
144        self.materials.get(id.index())
145    }
146
147    /// Returns the glTF texture objects, kept separate from image data.
148    pub fn textures(&self) -> &[AvatarTexture] {
149        &self.textures
150    }
151
152    /// Resolves a type-safe texture identifier.
153    pub fn texture(&self, id: TextureId) -> Option<&AvatarTexture> {
154        self.textures.get(id.index())
155    }
156
157    /// Returns the initial (base) color for the given material attribute.
158    ///
159    /// Returns white `[1, 1, 1, 1]` when the material index is out of range or
160    /// the material does not support `color_type`.
161    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    /// Creates a mutable runtime state (expression weights, bone rotations,
198    /// look-at target) detached from this avatar.
199    pub fn instantiate(&self) -> AvatarInstance {
200        AvatarInstance::new()
201    }
202
203    /// Returns the list of [`Skin`]s.
204    pub fn skins(&self) -> &[Skin] {
205        &self.skins
206    }
207
208    /// Resolves a type-safe skin identifier.
209    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    /// Returns the list of [`NodeConstraint`]s.
220    pub fn node_constraints(&self) -> &[NodeConstraint] {
221        &self.node_constraints
222    }
223
224    /// Builder method that sets the parsed node constraints.
225    pub(crate) fn with_node_constraints(mut self, node_constraints: Vec<NodeConstraint>) -> Self {
226        self.node_constraints = node_constraints;
227        self
228    }
229
230    /// Returns the [`SpringBone`] configuration.
231    pub fn spring_bone(&self) -> &SpringBone {
232        &self.spring_bone
233    }
234
235    /// Builder method that sets the [`SpringBone`] data.
236    pub(crate) fn with_spring_bone(mut self, spring_bone: SpringBone) -> Self {
237        self.spring_bone = spring_bone;
238        self
239    }
240
241    /// Returns the [`FirstPerson`] configuration.
242    pub fn first_person(&self) -> &FirstPerson {
243        &self.first_person
244    }
245
246    /// Returns the parsed node tree.
247    pub fn nodes(&self) -> &[AvatarNode] {
248        &self.nodes
249    }
250
251    /// Resolves a type-safe node identifier.
252    pub fn node(&self, id: NodeId) -> Option<&AvatarNode> {
253        self.nodes.get(id.index())
254    }
255
256    /// Builder method that sets the node tree.
257    pub(crate) fn with_nodes(mut self, nodes: Vec<AvatarNode>) -> Self {
258        self.nodes = nodes;
259        self
260    }
261
262    /// Computes the world transform matrix of every node, applying the given bone rotations.
263    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    /// Computes the joint matrices for `skin`, applying the given bone rotations.
271    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    /// Returns the raw [`VRMCVrmSchema`] this avatar was parsed from.
280    pub fn vrmc_vrm(&self) -> Option<&VRMCVrmSchema> {
281        self.vrmc_vrm.as_ref()
282    }
283
284    /// Loads and parses a VRM avatar from a file path.
285    ///
286    /// Relative buffer and image URIs are resolved against the file's parent
287    /// directory, including percent-encoded image paths.
288    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    /// Parses a VRM avatar from an in-memory byte slice.
293    ///
294    /// Images must be embedded in buffer views or PNG/JPEG data URIs. Use
295    /// [`Self::from_file`] when the document contains external references.
296    pub fn from_bytes(bytes: &[u8]) -> Result<Self, crate::LoadError> {
297        Ok(Self::from_bytes_with_options(bytes, LoadOptions::default())?.asset)
298    }
299
300    /// Loads an avatar and returns any diagnostics produced by the selected
301    /// validation mode. Relative buffer and image URIs are resolved against
302    /// the file's parent directory.
303    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    /// Parses an avatar and returns diagnostics for recoverable violations.
316    /// Unresolved external buffer and image references are rejected.
317    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        // gltf-json recursively validates node graphs. Reject cycles with an
330        // iterative preflight first so hostile input cannot overflow the stack.
331        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        // VRM Features
341        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        // glTF Features
361        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    /// Loads a VRM 1.0 asset from a file using strict validation.
408    ///
409    /// Relative external buffers and images are resolved against the file's
410    /// parent directory. Use [`Self::load_with_options`] to collect diagnostics
411    /// from permissive validation.
412    ///
413    /// # Errors
414    ///
415    /// Returns [`crate::LoadError`] when the file cannot be read, its glTF or
416    /// VRM data is invalid, an image cannot be decoded, or it requires an
417    /// unsupported extension.
418    ///
419    /// # Examples
420    ///
421    /// ```no_run
422    /// use vrm_runtime::AvatarAsset;
423    ///
424    /// let avatar = AvatarAsset::load("avatar.vrm")?;
425    /// println!("{}", avatar.meta().name());
426    /// # Ok::<(), vrm_runtime::LoadError>(())
427    /// ```
428    pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, crate::LoadError> {
429        Self::from_file(path)
430    }
431
432    /// Loads a VRM asset from a file with explicit validation options.
433    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    /// Returns the feature set implemented by this crate version.
441    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, &degree)| (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/// An avatar plus warnings emitted by permissive validation.
829#[derive(Debug)]
830pub struct LoadOutcome {
831    /// The validated immutable avatar asset.
832    pub asset: AvatarAsset,
833    /// Recoverable issues reported while loading in permissive mode.
834    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
849/// Runs glTF's structural validation while letting this crate validate the
850/// VRM ecosystem extensions that the upstream glTF crate does not know about.
851fn 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
920/// Human bones that VRM 1.0 requires to be present on every humanoid.
921const 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
939/// Rejects VRMC_vrm documents that deserialize cleanly but violate VRM 1.0
940/// semantic requirements, including metadata cardinalities, all-node scale,
941/// humanoid mappings, and extension references.
942fn 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
1356/// Serde name of a [`HumanBoneName`] variant, e.g. `Hips` -> `hips`.
1357fn 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}