TweenManager

TweenManager is a singleton that manages all property tweening, number interpolation, and timeline sequencing. It uses an object pool for zero-GC per-frame performance.

It is mounted automatically by Game — you do not need to set it up manually.

import { getTweenManager } from "@carverjs/core/systems";

How It Works #

1. On Game mount, the TweenFlush internal component is created, which calls getTweenManager().tick(delta) every frame at priority -15.

2. Each frame, tick() runs:

   • Reads game phase via useGameStore.getState() — all tweens freeze during "loading", normal tweens freeze during "paused" / "gameover"

   • Iterates the active tween list, advancing timing, applying easing, and writing interpolated values to target properties

   • Processes repeat/yoyo cycles, fires callbacks, handles chain completion

   • Updates active timelines

3. On Game unmount, all tweens are killed, the pool is drained, and the singleton is destroyed.

Object Pool #

The TweenManager pre-allocates 64 Tween instances at startup. When a tween completes, it is reset and returned to the pool. The pool grows on demand up to a maximum of 512 active tweens.

This design ensures zero garbage collection pressure during gameplay — no objects are created or destroyed per frame.

Frame Priority #

Priority | System
---------|------------------
-50      | InputFlush
-48      | AudioFlush
-45      | Physics (Rapier)
-40      | earlyUpdate
-30      | fixedUpdate
-25      | CollisionFlush
-20      | update
-15      | TweenFlush          ← tweens apply here
-10      | lateUpdate
 -5      | GameLoopTick
  0      | R3F render

Tweens run after game logic (update at -20) so that tweens created in useGameLoop take effect the same frame. They run before lateUpdate (-10) so late-update code sees tween-applied values.

API #

getTweenManager() #

Returns the singleton TweenManager instance. Creates one if it doesn't exist.

destroyTweenManager() #

Kills all active tweens and timelines, drains the pool, and destroys the singleton. Called automatically when Game unmounts.

Tween Creation #

Group Controls #

TweenGroupControls provides pause(), resume(), kill(), and count for batch control over all tweens in a group.

Global Controls #

Frame Update #

Usage #

Most game code should use the useTween hook, which provides auto-cleanup on unmount. Direct manager access is useful for systems-level code:

import { getTweenManager } from "@carverjs/core/systems";

// Direct tween creation (no auto-cleanup — you manage lifecycle)
const controls = getTweenManager().create({
  target: someObject.position,
  to: { x: 10 },
  duration: 1,
  ease: "quad.out",
});

// Group control
getTweenManager().getGroup("ui").pause();
getTweenManager().getGroup("effects").kill();

// Number tween
getTweenManager().createNumber({
  from: 0,
  to: 100,
  duration: 2,
  onUpdate: (value) => {
    scoreDisplay = Math.round(value);
  },
});

Easing Utilities #

The easing module is also exported from @carverjs/core/systems:

import { Easing, resolveEasing, cubicBezier, steps } from "@carverjs/core/systems";

// Access any preset directly
const t = Easing["bounce.out"](0.5);

// Create a cubic bezier (CSS-compatible)
const myEase = cubicBezier(0.68, -0.55, 0.27, 1.55);

// Create step easing
const stepped = steps(5);

// Resolve an EasingInput to a function
const fn = resolveEasing("elastic.out");
const fn2 = resolveEasing([0.25, 0.1, 0.25, 1]);
const fn3 = resolveEasing((t) => t * t);

Type Definitions #

See Types for TweenConfig, NumberTweenConfig, TweenControls, TimelineConfig, TimelineControls, TweenGroupControls, EasingFn, EasingPreset, and EasingInput.