animsmith-core 0.1.0

Engine-agnostic data model, sampling, measurements, and checks for the animsmith animation-clip linter
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

//! `in-place` — a clip's declared travel mode must match its measured
//! root motion. In-place clips drive entity velocity from gameplay and
//! expect no baked travel; root-motion clips are the opposite. A
//! mismatch makes the character glide or run in place at runtime.

use crate::check::{Check, CheckCtx, Readiness};
use crate::checks::root_motion_readiness;
use crate::finding::{Finding, Severity};
use crate::metrics::root_motion_speed_mps;

/// Measured horizontal root speed above this counts as travelling.
pub const TRAVEL_THRESHOLD_MPS: f64 = 0.5;

pub struct InPlace;

impl Check for InPlace {
    fn id(&self) -> &'static str {
        "in-place"
    }

    fn readiness(&self, ctx: &CheckCtx) -> Readiness {
        let any = ctx.clip_expectations().iter().any(|e| e.in_place.is_some());
        if any {
            root_motion_readiness(ctx.roles)
        } else {
            Readiness::Idle
        }
    }

    fn run(&self, ctx: &CheckCtx, out: &mut Vec<Finding>) {
        for (index, clip) in ctx.doc.clips.iter().enumerate() {
            let Some(expected) = ctx.expectations(index).in_place else {
                continue;
            };
            let measured = ctx
                .grid(index)
                .and_then(|grid| root_motion_speed_mps(&grid, ctx.roles));
            let Some(speed) = measured else {
                continue; // roles resolve (readiness gate); degenerate clip
            };
            let travels = speed >= TRAVEL_THRESHOLD_MPS;
            if expected && travels {
                out.push(
                    Finding::new(
                        self.id(),
                        Severity::Error,
                        format!(
                            "declared in-place but the root travels at {speed:.2} m/s — \
                             the character will glide at runtime"
                        ),
                    )
                    .clip(&clip.name)
                    .measured(speed)
                    .expected(0.0f64),
                );
            } else if !expected && !travels {
                out.push(
                    Finding::new(
                        self.id(),
                        Severity::Error,
                        format!(
                            "declared root-motion but the root is stationary \
                             ({speed:.2} m/s) — the character will run in place"
                        ),
                    )
                    .clip(&clip.name)
                    .measured(speed),
                );
            }
        }
    }
}