Animation and Tweening API Reference - fraxel/animation

All animation and tweening utilities are imported from fraxel/animation. The module covers numeric property tweening, composable tween sequences, sprite-sheet keyframe generation, and a full library of easing functions. For a conceptual overview and practical recipes, see the Animation guide.

tween(options)

Creates a tween that interpolates a numeric property on a target object over time. Returns a TweenController you can use to pause, resume, or stop the animation.

import { tween, easeOutQuad } from 'fraxel/animation'

const controller = tween({
  target: sprite,
  prop: 'opacity',
  from: 0,
  to: 1,
  duration: 0.5,
  easing: easeOutQuad,
  onUpdate: (value) => console.log('opacity:', value),
  onComplete: () => console.log('fade in done'),
})

Options

target

required

The object whose property will be interpolated. Any object with numeric properties works — nodes, plain objects, etc.

prop

keyof T

required

The name of the property to animate. Must be a key that holds a number value on target.

from

number

required

The start value of the interpolation.

number

required

The end value of the interpolation.

duration

number

required

Total duration of the tween in seconds.

easing

EasingFn

default:"linear"

An easing function (t: number) => number that maps normalised time t (0–1) to an eased output. Defaults to linear. See the easing functions table below.

onUpdate

(value: number) => void

Called every frame with the current interpolated value. Useful for side-effects that don’t directly map to a property.

onComplete

() => void

Called once when the tween finishes (progress reaches 1).

TweenController

tween() returns a TweenController with the following interface:

const t = tween({ ... })

t.pause()      // Pause the tween at its current position
t.resume()     // Resume from where it was paused
t.stop()       // Stop the tween and reset elapsed time to 0
t.isPlaying    // boolean — true while the tween is running
t.progress     // number  — normalised progress from 0 to 1

Usage with hooks

import { useMount } from 'fraxel/hooks'
import { tween, easeOutBounce } from 'fraxel/animation'
import { useNode, PrimaryNode } from 'fraxel'

function DropIn() {
  const sprite = useNode(PrimaryNode.Sprite)

  useMount(() => {
    tween({
      target: sprite.node,
      prop: 'opacity',
      from: 0,
      to: 1,
      duration: 0.8,
      easing: easeOutBounce,
    })
  })

  return <sprite ref={sprite} textureId={COIN} />
}

tweenValue(options)

Identical to tween() but without a target object or property name. The interpolated value is delivered exclusively via onUpdate. Returns a TweenController.

import { tweenValue } from 'fraxel/animation'

tweenValue({
  from: 0,
  to: 100,
  duration: 1,
  onUpdate: (value) => console.log(value),
})

from

number

required

Start value.

number

required

End value.

duration

number

required

Duration in seconds.

easing

EasingFn

default:"linear"

Easing function applied to the normalised time. See easing functions.

onUpdate

(value: number) => void

Receives the current interpolated value every frame.

onComplete

() => void

Called when the tween finishes.

sequence(tweens)

Runs an array of TweenController instances one after another — each tween starts only after the previous one finishes. Returns void (no controller is returned for the sequence itself).

import { tween, sequence } from 'fraxel/animation'

sequence([
  tween({ target: sprite, prop: 'opacity', from: 0, to: 1, duration: 0.5 }),
  tween({ target: sprite, prop: 'positionX', from: 0, to: 200, duration: 1 }),
])

tweens

TweenController[]

required

An ordered array of tween controllers. The first tween plays immediately; subsequent tweens are paused and resume once the prior tween completes.

Pass pre-constructed TweenController objects — tween() starts playing immediately, so sequence() internally pauses every tween except the first and resumes each one in turn.

parallel(tweens)

Runs an array of TweenController instances simultaneously — all tweens start at the same time. Returns void.

import { tween, parallel } from 'fraxel/animation'

parallel([
  tween({ target: sprite, prop: 'opacity', from: 0, to: 1, duration: 0.5 }),
  tween({ target: sprite, prop: 'scale', from: 0.5, to: 1, duration: 0.5 }),
])

tweens

TweenController[]

required

Array of tween controllers to run simultaneously. Each is immediately resumed.

animationFromSheet(sprite, textureId, options)

Creates a complete Animation object from a sprite sheet. Combines keyframesFromSheet() with automatic FPS calculation — fps = (columns × rows) / duration. The returned object is ready to pass to an <animation-player> node.

import { animationFromSheet } from 'fraxel/animation'

const idle = animationFromSheet(sprite, IDLE_TEXTURE, {
  columns: 4,
  duration: 1,
  loop: true,
})

const walk = animationFromSheet(sprite, WALK_TEXTURE, {
  columns: 4,
  rows: 2,
  range: [0, 7],
  duration: 2,
  loop: true,
})

return (
  <animation-player
    animations={() => ({ idle, walk })}
    currentAnim="idle"
  />
)

sprite

Sprite | NodeReference<PrimaryNode.Sprite>

required

The sprite instance or a NodeReference created with useNode(). When a NodeReference is passed, the animation is built lazily when the animations factory is evaluated.

textureId

symbol | null | undefined

required

Texture symbol returned by loadTexture(). Pass null to keep the sprite’s current texture across all frames. Pass undefined to use the sprite’s current texture for UV calculations.

options.columns

number

default:"1"

Number of columns in the sprite sheet grid.

options.rows

number

default:"1"

Number of rows in the sprite sheet grid.

options.range

[number, number]

Optional [from, to] tuple (0-indexed, inclusive) to select a subset of frames from the full grid. For example, [0, 3] selects the first four frames.

options.duration

number

required

Total animation duration in seconds. FPS is derived as (columns × rows) / duration.

options.loop

boolean

Whether the animation should loop after the last frame.

Returns Animation — { keyframes: AnimationKeyframe[], fps: number, loop?: boolean }.

keyframesFromSheet(sprite, textureId, columns, rows, range?)

Generates a raw keyframe array from a sprite sheet. Use this when you need fine-grained control over FPS or want to compose keyframes manually. animationFromSheet() calls this internally.

import { keyframesFromSheet } from 'fraxel/animation'

// All frames from a 4×2 sheet
const allFrames = keyframesFromSheet(sprite, WALK_TEXTURE, 4, 2)

// First row only
const walkFrames = keyframesFromSheet(sprite, WALK_TEXTURE, 4, 2, [0, 3])

// Second row only
const runFrames = keyframesFromSheet(sprite, WALK_TEXTURE, 4, 2, [4, 7])

sprite

Sprite

required

The Sprite instance to animate. Source texture dimensions are read directly from the sprite.

textureId

symbol | null | undefined

required

Texture symbol used to read image dimensions and set textureId on frame zero. Pass null to leave the texture unchanged.

columns

number

default:"1"

Number of columns in the sprite sheet grid.

rows

number

default:"1"

Number of rows in the sprite sheet grid.

range

[number, number]

Optional [from, to] tuple (0-indexed, inclusive) selecting a frame range. Defaults to the full sheet [0, columns × rows − 1].

Returns AnimationKeyframe[] — array of frame callbacks ready for an Animation definition.

kfFromProp(node, property, value)

Creates a single keyframe that sets a property on a node to a given value when the frame is reached.

import { kfFromProp } from 'fraxel/animation'

const frame0 = kfFromProp(sprite, 'textureId', IDLE_TEXTURE)
const frame1 = kfFromProp(sprite, 'margin', new Vector2(16, 0))

node

T extends Node

required

Any Fraxel node instance.

property

K extends keyof T

required

The property name to set on the node.

value

T[K]

required

The value to assign to the property when this keyframe fires.

Returns AnimationKeyframe — a callback (time: number) => void that sets node[property] = value.

multiKF(keyframes)

Combines multiple keyframes into a single keyframe that executes all of them in the same frame. Useful for changing both the texture and UV offset simultaneously on frame zero.

import { multiKF, kfFromProp } from 'fraxel/animation'

const frame0 = multiKF([
  kfFromProp(sprite, 'textureId', IDLE_TEXTURE),
  kfFromProp(sprite, 'margin', new Vector2(0, 0)),
])

keyframes

AnimationKeyframe[]

required

Array of keyframes to merge. All will be called with the same time argument when the combined keyframe fires.

Returns AnimationKeyframe — a single callback that invokes every provided keyframe.

Easing Functions

All easing functions implement EasingFn = (t: number) => number, mapping normalised time t (0–1) to an eased output value.

import {
  linear,
  easeInQuad,
  easeOutQuad,
  easeInOutQuad,
  easeInCubic,
  easeOutCubic,
  easeInOutCubic,
  easeBackOut,
  easeBackInOut,
  easeOutBounce,
  easeInBounce,
  easeOutElastic,
} from 'fraxel/animation'

Function	Signature	Description
`linear`	`(t: number) => number`	No easing — constant speed
`easeInQuad`	`(t: number) => number`	Slow start, accelerates (quadratic)
`easeOutQuad`	`(t: number) => number`	Fast start, decelerates (quadratic)
`easeInOutQuad`	`(t: number) => number`	Slow start and slow end (quadratic)
`easeInCubic`	`(t: number) => number`	Cubic acceleration from zero
`easeOutCubic`	`(t: number) => number`	Cubic deceleration to zero
`easeInOutCubic`	`(t: number) => number`	Cubic slow start and slow end
`easeBackOut`	`(t: number) => number`	Overshoots target then settles back
`easeBackInOut`	`(t: number) => number`	Overshoots in both directions
`easeOutBounce`	`(t: number) => number`	Bounces at the end like a dropped ball
`easeInBounce`	`(t: number) => number`	Bounces at the start
`easeOutElastic`	`(t: number) => number`	Spring-like elastic overshoot at the end

You can supply any function that matches (t: number) => number as a custom easing. The input t is always clamped to [0, 1] by the tween engine before it is passed to the easing function.

// Custom cubic bezier-inspired easing
const myEase = (t: number) => t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2

tween({ target: sprite, prop: 'opacity', from: 0, to: 1, duration: 1, easing: myEase })

Related guides

Animation guide — AnimationPlayer, reactive currentAnim, and sprite sheet workflow
Nodes 2D API — <animation-player> node props reference
Math API — Vector2 used in kfFromProp margin values

Hooks

Nodes

Modules

Animation and Tweening API Reference - fraxel/animation

tween(options)

Options

TweenController

Usage with hooks

tweenValue(options)

sequence(tweens)

parallel(tweens)

animationFromSheet(sprite, textureId, options)

keyframesFromSheet(sprite, textureId, columns, rows, range?)

kfFromProp(node, property, value)

multiKF(keyframes)

Easing Functions

Related guides

Build docs developers (and LLMs) love

Hooks

Nodes

Modules

Documentation Index

​tween(options)

​Options

​TweenController

​Usage with hooks

​tweenValue(options)

​sequence(tweens)

​parallel(tweens)

​animationFromSheet(sprite, textureId, options)

​keyframesFromSheet(sprite, textureId, columns, rows, range?)

​kfFromProp(node, property, value)

​multiKF(keyframes)

​Easing Functions

Related guides

Build docs developers (and LLMs) love

tween(options)

Options

TweenController

Usage with hooks

tweenValue(options)

sequence(tweens)

parallel(tweens)

animationFromSheet(sprite, textureId, options)

keyframesFromSheet(sprite, textureId, columns, rows, range?)

kfFromProp(node, property, value)

multiKF(keyframes)

Easing Functions