SugarSpring
Damped spring physics + Newtonian projectile simulation
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
Spring
dampingRatio < 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 & collections
SpringChain::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
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by harmonica (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Spring | new(deltaTime, angularFrequency, dampingRatio, reducedMotionOverride?) | Create a spring; non-finite / dt ≤ 0 / ω < 1e-9 / ζ ≤ 0 / coefficient overflow refused |
| Spring | update(pos, vel, target) | Step the simulation; snaps to [target, 0] under reduced motion |
| Spring | settled(pos, vel, target, threshold?) | Completion predicate on position AND velocity |
| Spring | fps($fps) / fromPreset($preset, $dt?, $override?) | deltaTime helper; five hand-tuned presets |
| SpringConfig | new(tension, friction, mass) → spring() | react-spring-style triple; exposes public readonly ω/ζ |
| SpringChain | tick(): self / isComplete() / currentPositions() | Stage hand-off on settle; under reduced motion final positions land after 2n−1 ticks, complete on 2n |
| SpringCollection | tick(): self / settled() / velocity($id) / get($id) | Many named springs, one driver |
| Easing | Linear, QuadraticIn … CubicOut … BackInOut → ease($t) | 16 preset curves implementing EasingFunction |
| CubicBezier | new(x1, y1, x2, y2) → evaluate($t) | CSS-style timing function (Newton + bounded subdivision) |
| Projectile | new(deltaTime, position, velocity, acceleration) → update() | Explicit Euler; returns a new instance — reassign it |
| Point / Vector | new(x, y, z = 0.0) | Finite-checked 2D/3D values; Vector: add/sub/scale/dot/cross/normalize/lerp/length |
| Gravity | standard() / 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.
Spring
Damped harmonic oscillator — settles smoothly to its target.
Projectile
Newtonian projectile sim with gravity + bouncing.