Skip to main content

Crate harmonica

Crate harmonica 

Source
Expand description

§Harmonica

Physics-based animation tools for 2D and 3D applications.

Harmonica provides:

  • Spring: A damped harmonic oscillator for smooth, realistic motion
  • Projectile: A simple projectile simulator for particles and projectiles

§Role in charmed_rust

Harmonica is a foundational crate that supplies physics-based motion used across the ecosystem:

  • bubbletea uses it for time-based animation helpers.
  • bubbles uses it to animate components like progress bars.
  • demo_showcase uses it to demonstrate smooth, springy UI motion.

§Spring Example

use harmonica::{fps, Spring};

// Initialize the spring once
let spring = Spring::new(fps(60), 6.0, 0.2);

// Update in your animation loop
let mut pos = 0.0;
let mut vel = 0.0;
let target = 100.0;

// Simulate for 2 seconds (120 frames at 60 FPS)
for _ in 0..120 {
    (pos, vel) = spring.update(pos, vel, target);
}

// Position should approach target
assert!((pos - target).abs() < 5.0);

§Projectile Example

use harmonica::{fps, Point, Vector, Projectile, TERMINAL_GRAVITY};

// Create a projectile with gravity
let mut projectile = Projectile::new(
    fps(60),
    Point::new(0.0, 0.0, 0.0),
    Vector::new(10.0, -5.0, 0.0),
    TERMINAL_GRAVITY,
);

// Update each frame
let pos = projectile.update();

§Damping Ratios

The damping ratio determines the spring’s behavior:

  • Over-damped (ζ > 1): No oscillation, slow return to equilibrium
  • Critically-damped (ζ = 1): Fastest return without oscillation
  • Under-damped (ζ < 1): Oscillates around equilibrium with decay

§Attribution

The spring algorithm is based on Ryan Juckett’s damped harmonic motion: https://www.ryanjuckett.com/damped-springs/

Modules§

prelude
Prelude module for convenient imports.

Structs§

Point
A point in 3D space.
Projectile
A projectile with position, velocity, and acceleration.
Spring
Precomputed spring motion parameters for efficient animation updates.
Vector
A vector in 3D space representing magnitude and direction.

Constants§

GRAVITY
Standard gravity vector for traditional coordinate systems.
TERMINAL_GRAVITY
Gravity vector for terminal coordinate systems.

Functions§

fps
Returns a time delta for a given number of frames per second.