Skip to main content

vibe/animation/
presets.rs

1//! The 10-Family Animation Presets Catalog for VibeScript (Zero-Heap).
2//!
3//! Provides canonical animation templates across:
4//! 1. Spatial Kinematics
5//! 2. Dynamics & Material Physics
6//! 3. Mesh & Topology
7//! 4. Thermodynamic Phase
8//! 5. Optics & Spectral Waves
9//! 6. Acoustic Synthesis
10//! 7. Multi-Track Timelines
11//! 8. HUD & UI Glassmorphism
12//! 9. Sensory Outbound Haptics
13//! 10. Generative Stochastic Fields
14
15use crate::animation::families;
16use crate::animation::pga::Motor;
17
18/// The 10 Animation Families.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
20pub enum AnimationFamily {
21    SpatialKinematics,
22    PhysicalDynamics,
23    MeshTopology,
24    ThermodynamicPhase,
25    OpticsWaves,
26    AcousticSpectral,
27    MultiTrackTimelines,
28    HudGlassUi,
29    OutboundHaptics,
30    GenerativeFields,
31}
32
33impl AnimationFamily {
34    /// Constructs from name.
35    pub fn from_name(name: &str) -> Option<Self> {
36        match name.to_ascii_lowercase().replace('_', "-").as_str() {
37            "spatial-kinematics" | "kinematics" => Some(Self::SpatialKinematics),
38            "physical-dynamics" | "dynamics" => Some(Self::PhysicalDynamics),
39            "mesh-topology" | "topology" => Some(Self::MeshTopology),
40            "thermodynamic-phase" | "thermodynamics" => Some(Self::ThermodynamicPhase),
41            "optics-waves" | "optics" => Some(Self::OpticsWaves),
42            "acoustic-spectral" | "acoustic" => Some(Self::AcousticSpectral),
43            "multitrack-timelines" | "multitrack" => Some(Self::MultiTrackTimelines),
44            "hud-glass-ui" | "hud" | "glass" => Some(Self::HudGlassUi),
45            "outbound-haptics" | "haptics" => Some(Self::OutboundHaptics),
46            "generative-fields" | "generative" => Some(Self::GenerativeFields),
47            _ => None,
48        }
49    }
50
51    /// Name.
52    pub fn name(&self) -> &'static str {
53        match self {
54            Self::SpatialKinematics => "spatial_kinematics",
55            Self::PhysicalDynamics => "physical_dynamics",
56            Self::MeshTopology => "mesh_topology",
57            Self::ThermodynamicPhase => "thermodynamic_phase",
58            Self::OpticsWaves => "optics_waves",
59            Self::AcousticSpectral => "acoustic_spectral",
60            Self::MultiTrackTimelines => "multitrack_timelines",
61            Self::HudGlassUi => "hud_glass_ui",
62            Self::OutboundHaptics => "outbound_haptics",
63            Self::GenerativeFields => "generative_fields",
64        }
65    }
66}
67
68/// A standard animation evaluation output record.
69#[derive(Debug, Clone, Copy, PartialEq)]
70pub struct AnimationSample {
71    pub scalar: f64,
72    pub vector: [f64; 3],
73    pub motor: Motor,
74    pub secondary: f64,
75    pub settled: bool,
76}
77
78impl Default for AnimationSample {
79    fn default() -> Self {
80        Self {
81            scalar: 0.0,
82            vector: [0.0; 3],
83            motor: Motor::identity(),
84            secondary: 0.0,
85            settled: false,
86        }
87    }
88}
89
90/// Metadata describing an animation preset.
91#[derive(Debug, Clone, Copy, PartialEq, Eq)]
92pub struct PresetInfo {
93    pub family: &'static str,
94    pub preset: &'static str,
95    pub description: &'static str,
96}
97
98/// Return a static list of all available presets across all 10 families.
99pub fn list_all_presets() -> &'static [PresetInfo] {
100    &[
101        // 1. Spatial Kinematics
102        PresetInfo {
103            family: "spatial_kinematics",
104            preset: "orbit_spin",
105            description: "Harmonic circular orbit in XZ plane with rotational tracking",
106        },
107        PresetInfo {
108            family: "spatial_kinematics",
109            preset: "hero_drift",
110            description: "Smooth cinematic ScLERP glide between two 3D rigid poses",
111        },
112        PresetInfo {
113            family: "spatial_kinematics",
114            preset: "elastic_snap",
115            description: "High-stiffness overshoot translation to target coordinate",
116        },
117        PresetInfo {
118            family: "spatial_kinematics",
119            preset: "geodesic_warp",
120            description: "Non-Euclidean metric contraction across space-time manifold",
121        },
122        // 2. Physical Dynamics
123        PresetInfo {
124            family: "physical_dynamics",
125            preset: "spring_settle",
126            description: "1D critically damped spring relaxation",
127        },
128        PresetInfo {
129            family: "physical_dynamics",
130            preset: "bouncy_drop",
131            description: "Underdamped gravitational restitution bounce",
132        },
133        PresetInfo {
134            family: "physical_dynamics",
135            preset: "verlet_wave",
136            description: "Symplectic Verlet wave height propagation",
137        },
138        PresetInfo {
139            family: "physical_dynamics",
140            preset: "gravity_well",
141            description: "Inverse-square orbital attraction toward central attractor",
142        },
143        PresetInfo {
144            family: "physical_dynamics",
145            preset: "collision_rebound",
146            description: "Instantaneous momentum-conserving impulse decay",
147        },
148        // 3. Mesh Topology
149        PresetInfo {
150            family: "mesh_topology",
151            preset: "morph_laplacian",
152            description: "Smooth geometric Laplacian surface interpolation",
153        },
154        PresetInfo {
155            family: "mesh_topology",
156            preset: "origami_unfold",
157            description: "Simplicial complex dimension unfolding from 0-simplex to 2-simplex",
158        },
159        PresetInfo {
160            family: "mesh_topology",
161            preset: "stalk_focus",
162            description: "Topological sheaf restriction focusing on active subtree",
163        },
164        PresetInfo {
165            family: "mesh_topology",
166            preset: "topology_collapse",
167            description: "Homotopy contraction to single singular boundary point",
168        },
169        // 4. Thermodynamic Phase
170        PresetInfo {
171            family: "thermodynamic_phase",
172            preset: "heat_diffuse",
173            description: "Exponential thermal dissipation and entropy expansion",
174        },
175        PresetInfo {
176            family: "thermodynamic_phase",
177            preset: "crystallize",
178            description: "First-order nucleation phase transition boundary",
179        },
180        PresetInfo {
181            family: "thermodynamic_phase",
182            preset: "thermal_glow",
183            description: "Blackbody spectral radiation intensity curve",
184        },
185        PresetInfo {
186            family: "thermodynamic_phase",
187            preset: "implode",
188            description: "High-pressure volumetric collapse into core singularity",
189        },
190        // 5. Optics & Waves
191        PresetInfo {
192            family: "optics_waves",
193            preset: "doppler_shift",
194            description: "Relativistic wavefront compression and frequency shift",
195        },
196        PresetInfo {
197            family: "optics_waves",
198            preset: "fresnel_glow",
199            description: "Schlick approximation rim radiance curve",
200        },
201        PresetInfo {
202            family: "optics_waves",
203            preset: "refractive_pulse",
204            description: "Snell law refractive index modulation across D7 manifold",
205        },
206        PresetInfo {
207            family: "optics_waves",
208            preset: "chromatic_aberration",
209            description: "Wavelength dispersion splitting RGB channels",
210        },
211        PresetInfo {
212            family: "optics_waves",
213            preset: "caustic_flow",
214            description: "Interferometric specular caustic illumination envelope",
215        },
216        // 6. Acoustic Spectral
217        PresetInfo {
218            family: "acoustic_spectral",
219            preset: "adsr_pulse",
220            description: "Standard Attack-Decay-Sustain-Release amplitude envelope",
221        },
222        PresetInfo {
223            family: "acoustic_spectral",
224            preset: "binaural_sweep",
225            description: "Stereo interaural phase disparity spatial pan",
226        },
227        PresetInfo {
228            family: "acoustic_spectral",
229            preset: "resonant_formant",
230            description: "Multi-pole acoustic vocal tract resonant peak sweep",
231        },
232        // 7. Multi-Track Timelines
233        PresetInfo {
234            family: "multitrack_timelines",
235            preset: "polymetric_sync",
236            description: "Polymetric 3:4:5 cross-rhythm phase synchronization",
237        },
238        PresetInfo {
239            family: "multitrack_timelines",
240            preset: "keyframe_blend",
241            description: "Smooth Hermite spline curve through multi-channel keys",
242        },
243        PresetInfo {
244            family: "multitrack_timelines",
245            preset: "stagger_cascade",
246            description: "Progressive cascade delay across N entity indices",
247        },
248        // 8. HUD & UI Glassmorphism
249        PresetInfo {
250            family: "hud_glass_ui",
251            preset: "glass_reveal",
252            description: "Smooth frosted-glass backdrop blur and scale-up reveal",
253        },
254        PresetInfo {
255            family: "hud_glass_ui",
256            preset: "chromatic_pulse",
257            description: "Micro-dispersion neon border accent wave",
258        },
259        PresetInfo {
260            family: "hud_glass_ui",
261            preset: "frosted_fade",
262            description: "Background surface transmission depth interpolation",
263        },
264        PresetInfo {
265            family: "hud_glass_ui",
266            preset: "focus_halo",
267            description: "Radial gaze-tracking luminance focus vignette",
268        },
269        // 9. Outbound Haptics
270        PresetInfo {
271            family: "outbound_haptics",
272            preset: "vibro_click",
273            description: "30ms sharp tactile mechanical click transient",
274        },
275        PresetInfo {
276            family: "outbound_haptics",
277            preset: "heartbeat_pulse",
278            description: "Dual-impulse systolic / diastolic cardiac envelope",
279        },
280        PresetInfo {
281            family: "outbound_haptics",
282            preset: "kinesthetic_resist",
283            description: "Nonlinear motor torque brake resistance against velocity",
284        },
285        // 10. Generative Stochastic Fields
286        PresetInfo {
287            family: "generative_fields",
288            preset: "simplex_flow",
289            description: "Coherent turbulent vector field velocity advection",
290        },
291        PresetInfo {
292            family: "generative_fields",
293            preset: "vortex_swirl",
294            description: "Logarithmic spiral angular momentum vortex",
295        },
296        PresetInfo {
297            family: "generative_fields",
298            preset: "brownian_drift",
299            description: "Continuous Wiener process stochastic random walk",
300        },
301    ]
302}
303
304/// Evaluate a preset by family name and preset name at time `t` (seconds).
305pub fn evaluate_preset(family: AnimationFamily, preset: &str, t: f64) -> AnimationSample {
306    families::dispatch(family, preset, t)
307}
308
309#[cfg(test)]
310mod tests {
311    use super::*;
312
313    #[test]
314    fn test_family_from_name() {
315        assert_eq!(
316            AnimationFamily::from_name("spatial-kinematics"),
317            Some(AnimationFamily::SpatialKinematics)
318        );
319        assert_eq!(
320            AnimationFamily::from_name("hud"),
321            Some(AnimationFamily::HudGlassUi)
322        );
323        assert_eq!(
324            AnimationFamily::from_name("dynamics"),
325            Some(AnimationFamily::PhysicalDynamics)
326        );
327    }
328
329    #[test]
330    fn test_list_all_presets() {
331        let all = list_all_presets();
332        assert!(all.len() >= 30, "expected at least 30 presets in catalog");
333    }
334
335    #[test]
336    fn test_evaluate_all_families() {
337        let families = [
338            AnimationFamily::SpatialKinematics,
339            AnimationFamily::PhysicalDynamics,
340            AnimationFamily::MeshTopology,
341            AnimationFamily::ThermodynamicPhase,
342            AnimationFamily::OpticsWaves,
343            AnimationFamily::AcousticSpectral,
344            AnimationFamily::MultiTrackTimelines,
345            AnimationFamily::HudGlassUi,
346            AnimationFamily::OutboundHaptics,
347            AnimationFamily::GenerativeFields,
348        ];
349
350        for fam in families {
351            let presets = list_all_presets().iter().filter(|p| p.family == fam.name());
352            for p in presets {
353                let sample = evaluate_preset(fam, p.preset, 0.5);
354                assert!(!sample.scalar.is_nan());
355                assert!(!sample.vector[0].is_nan());
356            }
357        }
358    }
359}