@zakkster/lite-tween

🎬 What is lite-tween?

@zakkster/lite-tween is a pre-allocated tween pool that drives property interpolation with zero per-frame allocation.

It gives you:

• 🎬 Single-property API: mgr.to(obj, 'x', 100, 1.0)
• 📊 SoA parallel Float64Arrays (pre-allocated at construction)
• ⏯️ timeScale for slow-motion / fast-forward / pause
• 🔍 seek(idx, t) for scrubbing and music sync
• 🛡️ killAllForKey(target, key) prevents tween stacking
• 🔁 Yoyo + repeat (-1 = infinite)
• ⏱️ Per-tween delay
• 📞 onUpdate / onComplete callbacks
• 🧹 Zero allocation per .to() call and per .update() frame
• 🪶 < 2 KB minified

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

🚀 Install

npm i @zakkster/lite-tween

🕹️ Quick Start

import TweenManager from '@zakkster/lite-tween';
import { easeOutBounce } from '@zakkster/lite-ease';

const mgr = new TweenManager(64);

// Tween multiple properties (compose single-property calls)
mgr.to(player, 'x', 100, 0.5, { ease: easeOutBounce });
mgr.to(player, 'y', 200, 0.5, { ease: easeOutBounce, delay: 0.1 });
mgr.to(player, 'alpha', 0, 0.3, { onComplete: () => player.destroy() });

// In game loop:
mgr.update(dt);

// Slow-motion
mgr.timeScale = 0.25;

// Prevent stacking
mgr.killAllForKey(player, 'x');
mgr.to(player, 'x', 200, 0.5);

📊 Comparison

| Library | Size | Allocations | Pool | timeScale | Install | |---------|------|-------------|------|-----------|---------| | GSAP | ~25 KB | High | No | Yes | npm i gsap | | tween.js | ~4 KB | Per tween | No | No | npm i @tweenjs/tween.js | | lite-tween | < 2 KB | Zero | SoA pool | Yes | npm i @zakkster/lite-tween |

⚙️ API

new TweenManager(capacity?)

.to(target, key, toValue, duration, opts?) — Returns slot index or -1

.update(dt) — Advance all tweens. Call every frame.

.timeScale — 0 = paused, 0.5 = half speed, 2 = double

.seek(idx, t) — Jump to normalized position 0–1

.isActive(idx) — Check if slot is running

.killAllForKey(target, key) — Cancel all tweens for a property

.cancelTarget(obj) / .cancel(idx) / .cancelAll()

.activeCount — Number of running tweens

🧪 Benchmark

1000 concurrent tweens, 60fps:
  GSAP:       Creates timeline objects per tween
  tween.js:   Allocates Tween instance per call
  lite-tween: Pre-allocated SoA pool, zero allocation per frame

📦 TypeScript

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

📚 LLM-Friendly Documentation

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

License

MIT