Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sanchedev/tiny-engine/llms.txt

Use this file to discover all available pages before exploring further.

AnimationPlayer plays frame-based animations by calling a sequence of keyframe functions on each engine tick. Each keyframe function typically updates a sibling Sprite’s margin to display the correct frame from a sprite sheet. The player tracks the current frame index, advances it by fps × delta every update, and loops or ends the animation according to configuration. Because keyframes often reference a sibling Sprite node, the animations prop is a deferred function — it is called when the node starts (not at construction time) so that other nodes in the scene tree are guaranteed to be initialized first.

​
Usage

import { Vector2 } from 'tiny-engine'
import { useRefNode, useEvent } from 'tiny-engine/hooks'
import { PrimaryNode } from 'tiny-engine/nodes/enum'
import { kfFromSpriteSheet } from 'tiny-engine/animation'

const IDLE_TEXTURE  = await loadTexture('/assets/player-idle.png')
const WALK_TEXTURE  = await loadTexture('/assets/player-walk.png')

function Player() {
  const sprite = useRefNode(PrimaryNode.Sprite)
  const anim   = useRefNode(PrimaryNode.AnimationPlayer)

  return (
    <sprite
      ref={sprite}
      textureId={IDLE_TEXTURE}
      sourceSize={new Vector2(16, 16)}
      displaySize={new Vector2(32, 32)}
    >
      <animation-player
        ref={anim}
        animations={() => ({
          idle: { keyframes: kfFromSpriteSheet(sprite.node, IDLE_TEXTURE, 4), fps: 8, loop: true },
          walk: { keyframes: kfFromSpriteSheet(sprite.node, WALK_TEXTURE, 6), fps: 10, loop: true },
        })}
        currentAnim="idle"
      />
    </sprite>
  )
}

​
Props

​
animations
() => Record<string, Animation>
A function that returns a map of animation name → animation definition. The function is called once when the node starts, ensuring sibling nodes (like Sprite) are available. Each animation definition is { fps: number, keyframes: AnimationKeyframe[], loop?: boolean }.
​
currentAnim
string | SignalGetter<string>
The animation to play when the node starts. Pass a static string name to play a single animation immediately, or a SignalGetter<string> to switch animations reactively whenever the signal changes.
​
destroyOnEnd
boolean
When true, the node destroys itself automatically after the current non-looping animation ends. Ideal for one-shot effects like explosions or hit flashes. Defaults to false.
​
ref
NodeRef<PrimaryNode.AnimationPlayer>
A ref created by useRefNode(PrimaryNode.AnimationPlayer). Exposes the AnimationPlayer instance so you can call play(), stop(), add(), and define() imperatively.
​
id
string | symbol
Optional node identifier. Must match [a-zA-Z][a-zA-Z0-9-_]* when a string.

​
Events

Subscribe with useEvent.
Event nameCallback signatureDescription
animationChanged(newAnim: string, oldAnim: string | null) => voidFires when play() switches to a different animation.
animationEnded(anim: string) => voidFires when a non-looping animation reaches its last frame.
animationIndexChanged(index: number) => voidFires every time the frame index advances.
animationStopped(anim: string) => voidFires when stop() is called.
started() => voidFires once after the node starts and loads animations.
updated(delta: number) => voidFires every frame during the update cycle.
drawed(delta: number) => voidFires every frame during the draw cycle.
destroyed() => voidFires once when the node is removed.

​
Runtime methods

MethodDescription
play(animName, index?)Play the named animation, optionally starting from a specific frame index.
stop()Stop the current animation and reset the frame index to 0.
setNext(animName | null)Queue an animation to start automatically after the current one ends.
add(animName, animation)Register a single animation definition. Returns this for chaining.
define(animations)Register multiple animations at once. Returns this for chaining.

​
Runtime properties

PropertyTypeDescription
currentAnimstring | nullRead-only. The name of the currently playing animation.
indexnumberRead-only. The current integer frame index.

​
Reactive animation switching

Pass a computed signal to currentAnim to switch animations automatically based on game state: 
import { useComputed, useSignal } from 'tiny-engine/hooks'

function Player() {
  const sprite  = useRefNode(PrimaryNode.Sprite)
  const [isMoving, setIsMoving] = useSignal(false)
  const animName = useComputed(() => isMoving() ? 'walk' : 'idle')

  return (
    <sprite ref={sprite} textureId={IDLE_TEXTURE} sourceSize={[16, 16]}>
      <animation-player
        animations={() => ({
          idle: { keyframes: kfFromSpriteSheet(sprite.node, IDLE_TEXTURE, 4), fps: 8, loop: true },
          walk: { keyframes: kfFromSpriteSheet(sprite.node, WALK_TEXTURE, 6), fps: 10, loop: true },
        })}
        currentAnim={animName}
      />
    </sprite>
  )
}

​
One-shot effect example

function Explosion() {
  return (
    <sprite textureId={EXPLOSION_TEXTURE} sourceSize={[32, 32]}>
      <animation-player
        animations={() => ({
          explode: {
            keyframes: kfFromSpriteSheet(sprite.node, EXPLOSION_TEXTURE, 8),
            fps: 12,
            loop: false,
          },
        })}
        currentAnim="explode"
        destroyOnEnd
      />
    </sprite>
  )
}
The animations prop must be a function, not an object literal. The function is invoked on start, at which point sibling nodes (such as Sprite) are already initialised and safe to reference.
Use setNext() instead of listening to animationEnded when you simply want to chain two animations — it avoids unnecessary event wiring.
  • Animation guide — kfFromSpriteSheet, custom keyframe functions, and sprite sheet layout
  • Sprite — the texture node that keyframes typically update
  • useSignal — create reactive state for currentAnim
  • useComputed — derive animation names from game state

Build docs developers (and LLMs) love

Get started for freeTalk to us