Sprites, animation and atlases

Creating sprites from images or atlases, driving frame animation, and the positioning trap that catches almost everyone.

pos is the centre, not the top-left

Renderable.anchorPoint defaults to (0.5, 0.5), so a sprite's pos is its centre. Container forces (0, 0) instead, which is why containers and sprites appear to disagree.

// a 64×64 sprite at (100, 100) covers 68..132, not 100..164
const s = new Sprite(100, 100, { image: "hero", framewidth: 64, frameheight: 64 });

s.anchorPoint.set(0, 0);   // switch to top-left positioning if you prefer

Writing top-left maths against the centred default puts everything half a sprite off, with no error. It is the most common source of "close but subtly wrong" placement.

Constructing a sprite

From a plain image:

const hero = new Sprite(x, y, {
    image: "hero",          // preloaded asset name
    framewidth: 32,
    frameheight: 32,
});

From a texture atlas region:

const atlas = new TextureAtlas(loader.getJSON("sprites"), loader.getImage("sprites"));
const coin = new Sprite(x, y, { image: atlas, region: "coin_01.png" });

framewidth / frameheight define the animation grid on a sheet. Omit them and the whole image is one frame.

Animation

hero.addAnimation("idle", [0, 1, 2, 3], 100);   // frames, ms per frame
hero.addAnimation("walk", [4, 5, 6, 7]);
hero.addAnimation("die",  [8, 9], 150);

hero.setCurrentAnimation("walk");
hero.setCurrentAnimation("die", "idle");                          // chain to idle when it ends
hero.setCurrentAnimation("die", { loop: false });                 // play once, hold the last frame
hero.setCurrentAnimation("die", { loop: false, onComplete: fn }); // …and call fn when it does
hero.setCurrentAnimation("use", { next: "idle", onComplete: fn }); // call fn, then chain to idle
hero.setCurrentAnimation("run", { onFrame: (frame) => {            // each frame playback reaches
    if (frame === 3 || frame === 8) footstep();
} });

if (hero.isCurrentAnimation("walk")) { /* … */ }

Frame indices are into the framewidth/frameheight grid. With an atlas, use atlas.getAnimationSettings([regionNames]) and spread it into the Sprite settings, or atlas.createAnimationFromName([regionNames]), which returns a ready-made Sprite. On a fixed-cell spritesheet only numeric indices are accepted — passing region names throws.

The second argument to setCurrentAnimation is polymorphic. A string chains to that animation when this one ends. An options object takes { loop, next, speed, onComplete, onFrame }, and only an explicit loop: false stops the looping. A bare function is the legacy form: it fires at every cycle end, and only holds the last frame if it returns false. Omit the argument entirely and the animation loops forever.

onFrame(frame) is called with frame 0 when the animation starts, then with each frame playback reaches, so a footstep or a hit lands on its frame without polling getCurrentAnimationFrame(). A long tick reports every frame it goes past. It is not called for a frame set with setAnimationFrame, nor for the frame 0 a play-once animation would wrap to. Keep the callback in a field when you call setCurrentAnimation every frame: re-selecting keeps the first one anyway.

With both next and onComplete, the callback runs first and the chained animation starts with none of its own, so a one-off action (a pickup, an attack) needs no manual switch back to idle.

Re-selecting the animation that is already current is a no-op, so calling setCurrentAnimation every frame is safe, and an isCurrentAnimation check around it adds nothing. An unknown id throws.

Texture atlases

TextureAtlas reads several formats:

source	how
TexturePacker / Free Texture Packer JSON	new TextureAtlas(loader.getJSON(name), loader.getImage(name))
Aseprite JSON export	same as TexturePacker — the format is detected from meta.app
Aseprite .aseprite / .ase binary	loader type "aseprite", which stores the composited image and a JSON sidecar under the one asset name
ShoeBox	JSON export using the melonJS exporter settings file; same call as TexturePacker
fixed-cell spritesheet	new TextureAtlas({ framewidth, frameheight, anchorPoint }, loader.getImage(name))
multi-page	pass an array of atlas JSON objects as the first argument

Helpers: createSpriteFromName(name), createAnimationFromName([names]), getAnimationSettings([names]).

Atlases matter for performance: the GPU batchers bind several textures at once (up to renderer.maxTextures), so a handful of separate images still batch — but once a frame crosses that many distinct textures the batch has to flush. Packing into one atlas keeps everything on a single binding.

Visual properties

sprite.setTint("#ff8000");   // multiply tint
sprite.alpha = 0.5;
sprite.flipX(true);                   // mirror horizontally
sprite.flipY(true);
sprite.blendMode = "additive";        // see the effects skill for the full list
sprite.scale(2, 2);                   // ← multiplicative, see below

scale() is multiplicative, not absolute. Calling it every frame compounds. For absolute scaling reset first:

sprite.currentTransform.identity();
sprite.currentTransform.scale(s, s, 1);

This bites hardest with pooled sprites, which arrive carrying their previous life's transform.

NineSliceSprite

For panels and dialogue boxes that stretch without distorting their corners:

new NineSliceSprite(x, y, {
    image: "panel", width: 300, height: 120,
    insetx: 12, insety: 12,     // lowercase x/y — `insetX` is silently ignored
});

width and height are mandatory and the constructor throws without them. The insets default to a quarter of the frame.

Pooling

Frequently spawned sprites should be pooled:

import { createPool } from "melonjs";

const bulletPool = createPool((x, y) => {    // me.pool is deprecated
    const instance = new Bullet(x, y);
    return { instance, reset: (x, y) => instance.onResetEvent(x, y) };
});
const b = bulletPool.get(x, y);             // new Bullet(x, y), or reset(x, y) on a reused one
world.removeChild(b);                       // returns it to bulletPool automatically

Two consequences:

• A recyclable class's onResetEvent must reset everything its lifetime mutates — alpha, tint, scale, animation state. Anything you forget carries over to the next use.
• Pool-recycled objects do not fire onDestroyEvent on removal. Pair event subscriptions with onActivateEvent / onDeactivateEvent instead.

Symptom → cause

symptom	cause
everything offset by half a sprite	top-left maths against the centred anchorPoint
sprite grows every frame	scale() is multiplicative — reset the transform
a recycled sprite keeps its old look	onResetEvent does not restore every mutated property
event handlers leak on pooled objects	bound in the constructor rather than onActivateEvent
animation never advances	no framewidth/frameheight, so the sheet is one frame
animation plays once and stops	{ loop: false }, or a callback that returned false
sprites do not batch	more distinct textures in one frame than renderer.maxTextures
nine-slice corners stretch anyway	insetX/insetY instead of insetx/insety

Related skills

• melonjs-renderables — anchors, draw order, custom draw
• melonjs-getting-started — preloading images and atlases