@zakkster/lite-spring

🧲 What is lite-spring?

@zakkster/lite-spring is a physics-based spring for any numeric value — not tied to DOM, React, or any framework.

It gives you:

• 🧲 Spring class for single values (position, opacity, scale)
• 📊 SpringPool for N springs in SoA Float32Arrays (particles, grids, UI lists)
• ⚙️ Per-spring stiffnesses[] and dampings[] in pool
• ⏯️ timeScale on both Spring and SpringPool
• 🎯 criticalDamping() computes zero-overshoot damping
• 🎛️ 6 named presets: snappy, bouncy, gentle, wobbly, stiff, slow
• 💥 kick(impulse) for velocity injection
• 🧹 Semi-implicit Euler integration (stable, fast)
• 🪶 < 1.5 KB minified

Part of the @zakkster/lite-* ecosystem — micro-libraries built for deterministic, cache-friendly game development.

🚀 Install

npm i @zakkster/lite-spring

🕹️ Quick Start

import { Spring, SpringPool, springPreset } from '@zakkster/lite-spring';

// Single spring
const cam = new Spring(...springPreset.gentle);
cam.target = playerX;
cam.update(dt);
camera.x = cam.value;

// Pool of 100 springs (zero-GC)
const pool = new SpringPool(100, 200, 15);
pool.stiffnesses[0] = 400; // per-spring override
pool.setTarget(0, 100);
pool.update(dt);
element.style.transform = `translateX(${pool.values[0]}px)`;

// Slow-motion
pool.timeScale = 0.25;

📊 Comparison

| Library | Size | Framework | Pool | Per-spring config | Install | |---------|------|-----------|------|-------------------|---------| | React Spring | ~15 KB | React only | No | Yes | npm i @react-spring/core | | Wobble | ~3 KB | Standalone | No | Yes | npm i wobble | | lite-spring | < 1.5 KB | None | SoA pool | Yes | npm i @zakkster/lite-spring |

⚙️ API

new Spring(stiffness, damping, initial?)

.update(dt) — Advance. Returns current value.

.target — Set the value the spring chases

.snap(v) — Instantly set value, zero velocity

.kick(impulse) — Add velocity

.isAtRest(threshold?) — True when settled

.timeScale — 0 = frozen, 0.5 = slow-motion

new SpringPool(capacity, stiffness, damping)

.stiffnesses: Float32Array / .dampings: Float32Array — Per-spring overrides

.setTarget(idx, val) / .snap(idx, val) / .kick(idx, impulse)

.update(dt) / .reset() / .timeScale

criticalDamping(stiffness, mass?) — Compute zero-overshoot damping

springPreset — { snappy, bouncy, gentle, wobbly, stiff, slow }

🧪 Benchmark

100 springs, 60fps:
  React Spring: React reconciliation overhead per spring
  Wobble:       Object instance per spring
  lite-spring:  SoA Float32Arrays, single update() loop, zero allocation

📦 TypeScript

Full declarations included in lite-spring.d.ts.

📚 LLM-Friendly Documentation

See llms.txt for AI-optimized metadata and usage examples.

License

MIT