Skip to main content

vrm_runtime/
expressions.rs

1use vrm_spec::vrmc_vrm_1_0::{self, ExpressionPresetName};
2
3/// Returns the canonical JSON key for a VRM preset expression.
4pub(crate) fn preset_expression_name(name: &ExpressionPresetName) -> &'static str {
5    match name {
6        ExpressionPresetName::Happy => "happy",
7        ExpressionPresetName::Angry => "angry",
8        ExpressionPresetName::Sad => "sad",
9        ExpressionPresetName::Relaxed => "relaxed",
10        ExpressionPresetName::Surprised => "surprised",
11        ExpressionPresetName::Aa => "aa",
12        ExpressionPresetName::Ih => "ih",
13        ExpressionPresetName::Ou => "ou",
14        ExpressionPresetName::Ee => "ee",
15        ExpressionPresetName::Oh => "oh",
16        ExpressionPresetName::Blink => "blink",
17        ExpressionPresetName::BlinkLeft => "blinkLeft",
18        ExpressionPresetName::BlinkRight => "blinkRight",
19        ExpressionPresetName::Neutral => "neutral",
20        ExpressionPresetName::LookUp => "lookUp",
21        ExpressionPresetName::LookDown => "lookDown",
22        ExpressionPresetName::LookLeft => "lookLeft",
23        ExpressionPresetName::LookRight => "lookRight",
24    }
25}
26
27/// Reports whether a name is reserved by the VRM preset-expression registry.
28pub(crate) fn is_preset_expression_name(name: &str) -> bool {
29    matches!(
30        name,
31        "happy"
32            | "angry"
33            | "sad"
34            | "relaxed"
35            | "surprised"
36            | "aa"
37            | "ih"
38            | "ou"
39            | "ee"
40            | "oh"
41            | "blink"
42            | "blinkLeft"
43            | "blinkRight"
44            | "lookUp"
45            | "lookDown"
46            | "lookLeft"
47            | "lookRight"
48            | "neutral"
49    )
50}
51
52/// A blend-shape bind: the morph target on a node that an expression drives.
53#[derive(Debug, Clone)]
54pub struct MorphTargetBind {
55    node_index: u32,
56    target_index: u32,
57    weight: f32,
58}
59
60impl MorphTargetBind {
61    /// Creates a bind for a node's morph target with its maximum weight.
62    pub fn new(node_index: u32, target_index: u32, weight: f32) -> Self {
63        Self {
64            node_index,
65            target_index,
66            weight,
67        }
68    }
69
70    /// Returns the glTF node index containing the target mesh.
71    pub fn node_index(&self) -> u32 {
72        self.node_index
73    }
74
75    /// Returns the morph target index within the node's mesh.
76    pub fn target_index(&self) -> u32 {
77        self.target_index
78    }
79
80    /// Returns the target weight reached at full expression input.
81    pub fn weight(&self) -> f32 {
82        self.weight
83    }
84}
85
86/// A material color bind: the color attribute of a material that an
87/// expression shifts toward `target_value`.
88#[derive(Debug, Clone)]
89pub struct MaterialColorBind {
90    /// The glTF material index to modify.
91    pub material_index: u32,
92    /// The material color property to modify.
93    pub color_type: MaterialColorType,
94    /// The value reached at full expression input.
95    pub target_value: [f32; 4],
96}
97
98/// A UV transform bind: the texture scale/offset of a material that an
99/// expression animates.
100#[derive(Debug, Clone)]
101pub struct TextureTransformBind {
102    /// The glTF material index whose textures are modified.
103    pub material_index: u32,
104    /// The UV scale reached at full expression input.
105    pub scale: [f32; 2],
106    /// The UV offset reached at full expression input.
107    pub offset: [f32; 2],
108}
109
110/// A single accumulated morph weight (node + target index), ready to apply.
111#[derive(Debug, Clone, Copy, PartialEq)]
112pub struct MorphTargetUpdate {
113    node_index: u32,
114    target_index: u32,
115    weight: f32,
116}
117
118impl MorphTargetUpdate {
119    pub(crate) fn new(node_index: u32, target_index: u32, weight: f32) -> Self {
120        Self {
121            node_index,
122            target_index,
123            weight,
124        }
125    }
126
127    /// Returns the glTF node index containing the updated target.
128    pub fn node_index(&self) -> u32 {
129        self.node_index
130    }
131
132    /// Returns the updated morph target index.
133    pub fn target_index(&self) -> u32 {
134        self.target_index
135    }
136
137    /// Returns the accumulated morph weight.
138    pub fn weight(&self) -> f32 {
139        self.weight
140    }
141}
142
143/// An accumulated material color shift (delta over the base color).
144#[derive(Debug, Clone, Copy, PartialEq)]
145pub struct MaterialColorUpdate {
146    material_index: u32,
147    color_type: MaterialColorType,
148    target_value: [f32; 4],
149    weight: f32,
150}
151
152impl MaterialColorUpdate {
153    /// Creates a weighted update for one material color property.
154    pub fn new(
155        material_index: u32,
156        color_type: MaterialColorType,
157        target_value: [f32; 4],
158        weight: f32,
159    ) -> Self {
160        Self {
161            material_index,
162            color_type,
163            target_value,
164            weight,
165        }
166    }
167
168    /// Returns the raw glTF material index to update.
169    pub fn material_index(&self) -> u32 {
170        self.material_index
171    }
172
173    /// Returns the material color property to update.
174    pub fn color_type(&self) -> MaterialColorType {
175        self.color_type
176    }
177
178    /// Returns the expression's full-weight target value.
179    pub fn target_value(&self) -> [f32; 4] {
180        self.target_value
181    }
182
183    /// Returns the accumulated expression influence.
184    pub fn weight(&self) -> f32 {
185        self.weight
186    }
187}
188
189/// An accumulated UV transform shift (delta over scale 1 / offset 0).
190#[derive(Debug, Clone, Copy, PartialEq)]
191pub struct TextureTransformUpdate {
192    material_index: u32,
193    scale: [f32; 2],
194    offset: [f32; 2],
195    weight: f32,
196}
197
198impl TextureTransformUpdate {
199    /// Creates a weighted UV scale and offset update for one material.
200    pub fn new(material_index: u32, scale: [f32; 2], offset: [f32; 2], weight: f32) -> Self {
201        Self {
202            material_index,
203            scale,
204            offset,
205            weight,
206        }
207    }
208
209    /// Returns the raw glTF material index to update.
210    pub fn material_index(&self) -> u32 {
211        self.material_index
212    }
213
214    /// Returns the expression's full-weight UV scale.
215    pub fn scale(&self) -> [f32; 2] {
216        self.scale
217    }
218
219    /// Returns the expression's full-weight UV offset.
220    pub fn offset(&self) -> [f32; 2] {
221        self.offset
222    }
223
224    /// Returns the accumulated expression influence.
225    pub fn weight(&self) -> f32 {
226        self.weight
227    }
228}
229
230/// The output of evaluating one expression at a given weight: every bind
231/// expanded into an update list.
232#[derive(Debug, Clone, Default)]
233pub struct ExpressionEvaluation {
234    /// Morph target weights emitted by the expression.
235    pub morph_updates: Vec<MorphTargetUpdate>,
236    /// Material color updates emitted by the expression.
237    pub material_color_updates: Vec<MaterialColorUpdate>,
238    /// Texture transform updates emitted by the expression.
239    pub texture_transform_updates: Vec<TextureTransformUpdate>,
240}
241
242/// Whether an active expression suppresses (`Block`) or scales down (`Blend`)
243/// the procedural expressions of a category.
244#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
245pub enum ExpressionOverrideType {
246    /// Leaves procedural expressions in this category unchanged.
247    #[default]
248    None,
249    /// Suppresses procedural expressions in this category.
250    Block,
251    /// Scales procedural expressions down by the active expression weight.
252    Blend,
253}
254
255impl From<vrmc_vrm_1_0::ExpressionOverrideType> for ExpressionOverrideType {
256    fn from(schema: vrmc_vrm_1_0::ExpressionOverrideType) -> Self {
257        match schema {
258            vrmc_vrm_1_0::ExpressionOverrideType::None => Self::None,
259            vrmc_vrm_1_0::ExpressionOverrideType::Block => Self::Block,
260            vrmc_vrm_1_0::ExpressionOverrideType::Blend => Self::Blend,
261        }
262    }
263}
264
265/// Enforces the VRM rule that an expression cannot override its own category.
266///
267/// The same validator is used before loading schema expressions and before a
268/// programmatically composed asset is accepted, keeping both creation paths
269/// semantically identical.
270pub(crate) fn validate_override_semantics(
271    name: &str,
272    override_blink: ExpressionOverrideType,
273    override_mouth: ExpressionOverrideType,
274    override_look_at: ExpressionOverrideType,
275) -> Result<(), String> {
276    let invalid_override = if matches!(name, "blink" | "blinkLeft" | "blinkRight")
277        && override_blink != ExpressionOverrideType::None
278    {
279        Some(("overrideBlink", "blink"))
280    } else if matches!(name, "aa" | "ih" | "ou" | "ee" | "oh")
281        && override_mouth != ExpressionOverrideType::None
282    {
283        Some(("overrideMouth", "mouth"))
284    } else if matches!(name, "lookUp" | "lookDown" | "lookLeft" | "lookRight")
285        && override_look_at != ExpressionOverrideType::None
286    {
287        Some(("overrideLookAt", "look-at"))
288    } else {
289        None
290    };
291
292    if let Some((field, category)) = invalid_override {
293        return Err(format!(
294            "expression `{name}` must set `{field}` to `none`; an expression cannot override its own {category} category"
295        ));
296    }
297
298    Ok(())
299}
300
301/// The material attribute a color bind targets.
302#[derive(Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd)]
303pub enum MaterialColorType {
304    /// The base color factor.
305    Color,
306    /// The emissive color factor.
307    EmissionColor,
308    /// The MToon shade color factor.
309    ShadeColor,
310    /// The MToon matcap color factor.
311    MatcapColor,
312    /// The MToon rim color factor.
313    RimColor,
314    /// The MToon outline color factor.
315    OutlineColor,
316}
317
318/// A named, combinable facial/motion expression (e.g. "happy", "blink").
319///
320/// Holds the binds it drives and the override rules for the procedural
321/// mouth / blink / gaze categories. `is_binary` expressions only ever output
322/// 0 or 1.
323#[derive(Debug, Clone)]
324pub struct Expression {
325    name: String,
326    is_binary: bool,
327    override_blink: ExpressionOverrideType,
328    override_mouth: ExpressionOverrideType,
329    override_look_at: ExpressionOverrideType,
330    morph_target_binds: Vec<MorphTargetBind>,
331    material_color_binds: Vec<MaterialColorBind>,
332    texture_transform_binds: Vec<TextureTransformBind>,
333}
334
335impl Expression {
336    /// Creates an empty, continuous expression with the given name.
337    pub fn new(name: impl Into<String>) -> Self {
338        Self {
339            name: name.into(),
340            is_binary: false,
341            morph_target_binds: Vec::new(),
342            material_color_binds: Vec::new(),
343            texture_transform_binds: Vec::new(),
344            override_blink: ExpressionOverrideType::default(),
345            override_mouth: ExpressionOverrideType::default(),
346            override_look_at: ExpressionOverrideType::default(),
347        }
348    }
349
350    /// Returns the preset or custom expression name.
351    pub fn name(&self) -> &str {
352        &self.name
353    }
354
355    /// Replaces the morph targets driven by this expression.
356    pub fn with_morph_target_binds(mut self, binds: Vec<MorphTargetBind>) -> Self {
357        self.morph_target_binds = binds;
358        self
359    }
360
361    /// Configures VRM binary thresholding for this expression.
362    pub fn with_binary(mut self, is_binary: bool) -> Self {
363        self.is_binary = is_binary;
364        self
365    }
366
367    /// Sets how this expression affects procedural blink expressions.
368    pub fn with_override_blink(mut self, value: ExpressionOverrideType) -> Self {
369        self.override_blink = value;
370        self
371    }
372
373    /// Sets how this expression affects procedural mouth expressions.
374    pub fn with_override_mouth(mut self, value: ExpressionOverrideType) -> Self {
375        self.override_mouth = value;
376        self
377    }
378
379    /// Sets how this expression affects procedural look-at expressions.
380    pub fn with_override_look_at(mut self, value: ExpressionOverrideType) -> Self {
381        self.override_look_at = value;
382        self
383    }
384
385    /// Replaces the material colors driven by this expression.
386    pub fn with_material_color_binds(mut self, binds: Vec<MaterialColorBind>) -> Self {
387        self.material_color_binds = binds;
388        self
389    }
390
391    /// Replaces the texture transforms driven by this expression.
392    pub fn with_texture_transform_binds(mut self, binds: Vec<TextureTransformBind>) -> Self {
393        self.texture_transform_binds = binds;
394        self
395    }
396
397    /// Reports whether input is thresholded to zero or one at 0.5.
398    pub fn is_binary(&self) -> bool {
399        self.is_binary
400    }
401    /// Returns the procedural blink override behavior.
402    pub fn override_blink(&self) -> ExpressionOverrideType {
403        self.override_blink
404    }
405    /// Returns the procedural mouth override behavior.
406    pub fn override_mouth(&self) -> ExpressionOverrideType {
407        self.override_mouth
408    }
409    /// Returns the procedural look-at override behavior.
410    pub fn override_look_at(&self) -> ExpressionOverrideType {
411        self.override_look_at
412    }
413
414    /// Returns the morph target binds in declaration order.
415    pub fn morph_target_binds(&self) -> &[MorphTargetBind] {
416        &self.morph_target_binds
417    }
418
419    /// Returns the material color binds in declaration order.
420    pub fn material_color_binds(&self) -> &[MaterialColorBind] {
421        &self.material_color_binds
422    }
423
424    /// Returns the texture transform binds in declaration order.
425    pub fn texture_transform_binds(&self) -> &[TextureTransformBind] {
426        &self.texture_transform_binds
427    }
428
429    fn load_expression(name: impl Into<String>, expression: &vrmc_vrm_1_0::Expression) -> Self {
430        let is_binary = expression.is_binary.unwrap_or(false);
431
432        // overrideMouth/Blink/LookAt: optional in the schema. When present, convert the
433        // schema's enum to ours via From; when absent, fall back to ExpressionOverrideType::None.
434        let override_blink = expression
435            .override_blink
436            .map(ExpressionOverrideType::from)
437            .unwrap_or_default();
438        let override_mouth = expression
439            .override_mouth
440            .map(ExpressionOverrideType::from)
441            .unwrap_or_default();
442        let override_look_at = expression
443            .override_look_at
444            .map(ExpressionOverrideType::from)
445            .unwrap_or_default();
446
447        let morph_target_binds = expression
448            .morph_target_binds
449            .as_deref()
450            .unwrap_or_default()
451            .iter()
452            .map(|bind| {
453                MorphTargetBind::new(
454                    bind.node.value() as u32,
455                    bind.index as u32,
456                    bind.weight as f32,
457                )
458            })
459            .collect();
460
461        let material_color_binds = expression
462            .material_color_binds
463            .as_deref()
464            .unwrap_or_default()
465            .iter()
466            .map(|bind| {
467                let color_type = match bind.r#type {
468                    vrmc_vrm_1_0::MaterialColorType::Color => MaterialColorType::Color,
469                    vrmc_vrm_1_0::MaterialColorType::EmissionColor => {
470                        MaterialColorType::EmissionColor
471                    }
472                    vrmc_vrm_1_0::MaterialColorType::ShadeColor => MaterialColorType::ShadeColor,
473                    vrmc_vrm_1_0::MaterialColorType::MatcapColor => MaterialColorType::MatcapColor,
474                    vrmc_vrm_1_0::MaterialColorType::RimColor => MaterialColorType::RimColor,
475                    vrmc_vrm_1_0::MaterialColorType::OutlineColor => {
476                        MaterialColorType::OutlineColor
477                    }
478                };
479                let target = &bind.target_value;
480                MaterialColorBind {
481                    material_index: bind.material.value() as u32,
482                    color_type,
483                    target_value: [
484                        target[0] as f32,
485                        target[1] as f32,
486                        target[2] as f32,
487                        target[3] as f32,
488                    ],
489                }
490            })
491            .collect();
492
493        let texture_transform_binds = expression
494            .texture_transform_binds
495            .as_deref()
496            .unwrap_or_default()
497            .iter()
498            .map(|bind| {
499                let scale = bind
500                    .scale
501                    .as_ref()
502                    .map(|s| [s[0] as f32, s[1] as f32])
503                    .unwrap_or([1.0, 1.0]);
504                let offset = bind
505                    .offset
506                    .as_ref()
507                    .map(|o| [o[0] as f32, o[1] as f32])
508                    .unwrap_or([0.0, 0.0]);
509                TextureTransformBind {
510                    material_index: bind.material.value() as u32,
511                    scale,
512                    offset,
513                }
514            })
515            .collect();
516
517        Self {
518            name: name.into(),
519            is_binary,
520            override_blink,
521            override_mouth,
522            override_look_at,
523            morph_target_binds,
524            material_color_binds,
525            texture_transform_binds,
526        }
527    }
528
529    /// Evaluates all binds after clamping or binary-thresholding `input_weight`.
530    pub fn evaluate(&self, input_weight: f32) -> ExpressionEvaluation {
531        let input_weight = if self.is_binary {
532            f32::from(input_weight >= 0.5)
533        } else if input_weight.is_finite() {
534            input_weight.clamp(0.0, 1.0)
535        } else {
536            0.0
537        };
538
539        ExpressionEvaluation {
540            morph_updates: self
541                .morph_target_binds
542                .iter()
543                .map(|bind| {
544                    MorphTargetUpdate::new(
545                        bind.node_index(),
546                        bind.target_index(),
547                        bind.weight() * input_weight,
548                    )
549                })
550                .collect(),
551            material_color_updates: self
552                .material_color_binds
553                .iter()
554                .map(|bind| {
555                    MaterialColorUpdate::new(
556                        bind.material_index,
557                        bind.color_type,
558                        bind.target_value,
559                        input_weight,
560                    )
561                })
562                .collect(),
563            texture_transform_updates: self
564                .texture_transform_binds
565                .iter()
566                .map(|bind| {
567                    TextureTransformUpdate::new(
568                        bind.material_index,
569                        bind.scale,
570                        bind.offset,
571                        input_weight,
572                    )
573                })
574                .collect(),
575        }
576    }
577}
578
579/// The ordered list of expressions defined by an avatar (presets and customs).
580#[derive(Debug, Clone, Default)]
581pub struct Expressions {
582    items: Vec<Expression>,
583}
584
585impl Expressions {
586    /// Creates an ordered expression collection.
587    pub fn new(items: Vec<Expression>) -> Self {
588        Self { items }
589    }
590
591    /// Iterates over preset and custom expressions in stored order.
592    pub fn iter(&self) -> impl Iterator<Item = &Expression> {
593        self.items.iter()
594    }
595
596    /// Finds an expression by its exact preset or custom name.
597    pub fn get(&self, name: &str) -> Option<&Expression> {
598        self.items
599            .iter()
600            .find(|expression| expression.name() == name)
601    }
602
603    /// Returns the number of expressions.
604    pub fn len(&self) -> usize {
605        self.items.len()
606    }
607
608    /// Reports whether the collection contains no expressions.
609    pub fn is_empty(&self) -> bool {
610        self.items.is_empty()
611    }
612
613    pub(crate) fn load_expressions(expressions: &vrmc_vrm_1_0::Expressions) -> Self {
614        let mut items = Vec::new();
615
616        if let Some(preset) = &expressions.preset {
617            for (preset_name, expr) in &preset.0 {
618                let name = preset_expression_name(preset_name);
619                items.push(Expression::load_expression(name, expr));
620            }
621        }
622
623        if let Some(custom) = &expressions.custom {
624            for (custom_name, expr) in custom {
625                items.push(Expression::load_expression(custom_name, expr));
626            }
627        }
628
629        Self::new(items)
630    }
631}