All 42 libraries

SugarSpring

Damped spring physics + Newtonian projectile simulation

inspired by charmbracelet/harmonica physics animation math reduced-motion

SugarSpring code coverage

Pure-math animation engine. Damped harmonic oscillators (Ryan-Juckett form, spring core mirrors charmbracelet/harmonica) for smooth scroll / overshoot, Newtonian projectile sim for arcs and particle effects, easing + bezier timing curves, spring chains and collections, and reduced-motion awareness throughout the spring-driven types. No terminal I/O anywhere.

Install

composer require sugarcraft/sugar-spring

Quickstart

use SugarCraft\Spring\{Spring, Projectile, Point, Vector};

$spring = new Spring(
    deltaTime:        Spring::fps(60),
    angularFrequency: 6.0,
    dampingRatio:     1.0,    // critical
);
$pos = 0.0; $vel = 0.0; $target = 100.0;
$frame = 0;
do {                                 // animate until settled, not for a
    [$pos, $vel] = $spring->update($pos, $vel, $target);
} while (!Spring::settled($pos, $vel, $target) && ++$frame < 600);

$ball = Projectile::new(
    deltaTime:    Spring::fps(60),
    position:     Point::zero(),
    velocity:     new Vector(5.0, 10.0),      // +y is up: Projectile::gravity() is (0, -9.81, 0)
    acceleration: Projectile::gravity(),
);
for ($i = 0; $i < 60; $i++) {
    $ball = $ball->update();                   // update() returns a NEW projectile — reassign
}

What's in the box

SpringdampingRatio < 1 oscillates, = 1 critical (no overshoot, fastest), > 1 over-damped. Non-positive frame time, zero/negative damping and near-zero frequency are refused at construction — a spring that cannot converge is illegal, not slow.
ProjectilePosition, velocity, acceleration vectors. Projectile::gravity() + terminalGravity() helpers (Y-up, with legacy Y-down spellings).
Easing & BezierAll 16 Easing cases (Linear plus the analytic Quadratic/Cubic/Bounce curves and the sin-modulated Elastic/Back family — the Back cases are not Penner's classic c1 polynomial) + CubicBezier matching the CSS transition-timing-function solver.
Chains & collectionsSpringChain::tick() hands off stage-to-stage on settle; SpringCollection drives many named springs with one tick and one settled() predicate.
Reduced motionEvery spring-composed type snaps to target when REDUCE_MOTION/PREFERS_REDUCED_MOTION is set (via sugar-colorprofile's Probe); the environment is probed once per process and remembered (Spring::resetReducedMotionProbe() re-reads it), and one spring can be pinned either way with reducedMotionOverride — evaluated per call, it always beats the memo; gate Projectile/easing yourself — the README shows the recipe.
Used in-treesugar-overlay transitions (Fade/Scale/Slide), candy-flappy's bird physics, sugar-widgets AnimatedProgress.
Terminal-agnosticNo ReactPHP, no ext-pcntl, no render path — pure values in, pure values out. Its sugar-core + sugar-colorprofile deps never touch a TTY here.
i18nEvery exception message runs through Lang::t() across 16 shipped locales.

Source & demos

Try the quickstart →

API

ClassMethodDescription
Springnew(deltaTime, angularFrequency, dampingRatio, reducedMotionOverride?)Create a spring; non-finite / dt ≤ 0 / ω < 1e-9 / ζ ≤ 0 / coefficient overflow refused
Springupdate(pos, vel, target)Step the simulation; snaps to [target, 0] under reduced motion
Springsettled(pos, vel, target, threshold?)Completion predicate on position AND velocity
Springfps($fps) / fromPreset($preset, $dt?, $override?)deltaTime helper; five hand-tuned presets
SpringConfignew(tension, friction, mass) → spring()react-spring-style triple; exposes public readonly ω/ζ
SpringChaintick(): self / isComplete() / currentPositions()Stage hand-off on settle; under reduced motion final positions land after 2n−1 ticks, complete on 2n
SpringCollectiontick(): self / settled() / velocity($id) / get($id)Many named springs, one driver
EasingLinear, QuadraticIn … CubicOut … BackInOut → ease($t)16 preset curves implementing EasingFunction
CubicBeziernew(x1, y1, x2, y2) → evaluate($t)CSS-style timing function (Newton + bounded subdivision)
Projectilenew(deltaTime, position, velocity, acceleration) → update()Explicit Euler; returns a new instance — reassign it
Point / Vectornew(x, y, z = 0.0)Finite-checked 2D/3D values; Vector: add/sub/scale/dot/cross/normalize/lerp/length
Gravitystandard() / terminal()Y-up acceleration vectors (Y-down spellings available)

Demos.

VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.

Looping recording of a damped spring easing smoothly to its target value

Spring

Damped harmonic oscillator — settles smoothly to its target.
Looping recording of a projectile tracing a gravity arc and bouncing off the floor

Projectile

Newtonian projectile sim with gravity + bouncing.
Looping recording of a projectile-driven particle field falling under terminal gravity

Particle

Projectile-driven particle field with terminal gravity.