Tile Animation

Tile animation allows individual tiles within a tileset to display dynamic visual changes over time. Animations are defined as sequences of frames, each pointing to a specific tile ID in the tileset and a duration for how long that frame should be displayed.

interface TileAnimationFrameJSON {
    duration: number; // in ms
    tileid: number;
}

Animator

The Animator manages tile animations for sprites. It tracks which frame of an animation should currently be displayed, updates the frame based on elapsed time, and loops or stops the sequence according to its configuration. The Animator ensures that the correct tile from the tileset is shown at each moment.

Creating a Tile Animation

To create a tile animation, first define an array of animation frames for a tile in your tileset.
Each frame specifies the tile ID and duration in milliseconds.

Here is the tileset image used for the animation:

The Player Run animation uses a sequence of tiles in the following order: 0 → 1 → 2 → 1.

Next, create an Animator node for the sprite you want to animate. The Animator controls which frame is displayed at each moment.

Use the play method to start an animation sequence:

• tileXY – the coordinates of the tile in the tileset grid where the animation begins.
• options – optional configuration:
  • repeat: whether the animation should loop continuously
  • restart: whether to restart the animation if it is already playing

const { createRenderer, Camera, Scene, Color, Sprite, Tileset, Animator, assets } = TilemapRenderer;

const main = async () => {
    const width = 300;
    const height = 400;

    const playerImage = await assets.loadImage("../images/player.png");

    // Create renderer
    const renderer = createRenderer("webgl2");
    renderer.setSize(width, height);
    renderer.setClearColor(new Color(0, 0, 0, 1));

    // Create camera and scene
    const camera = new Camera(width, height);
    const scene = new Scene();

    // Create tileset with animation frames
    const tileset = new Tileset({
        name: "Player",
        imagewidth: 80,
        imageheight: 32,
        columns: 5,
        tilecount: 10,
        tilewidth: 16,
        tileheight: 16,
        tiles: [
            {
                id: 0,
                animation: [
                    { tileid: 0, duration: 160 },
                    { tileid: 1, duration: 160 },
                    { tileid: 2, duration: 160 },
                    { tileid: 1, duration: 160 }
                ]
            }
        ]
    });

    // Add canvas to document
    const canvas = renderer.getCanvas();
    document.body.appendChild(canvas);

    // Add textures to renderer
    renderer.addTextures([tileset], { ["Player"]: playerImage });

    // Initialize renderer
    await renderer.init();

    // Create sprite and assign tileset
    const sprite = new Sprite({ tileset });
    sprite.position.set(50, 50);
    sprite.scale.scale(2);
    scene.addNode(sprite);

    // Create Animator and play animation
    const animator = new Animator(sprite);

    sprite.addNode(animator);

    animator.play([0, 0], { repeat: true });

    // Animation loop
    let dt = 0;
    let prevTime = 0;
    const loop = () => {
        requestAnimationFrame(t => {
            loop();

            t *= 0.001;
            dt = t - (prevTime || t);
            prevTime = t;

            animator.update(dt);
            renderer.render(scene, camera);
        });
    };

    loop();
};

main();

Live Demo

The demo below shows an animation of sprite:

click here to open in separate window