Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OmarMtya/enginejs-module/llms.txt

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

A sprite sheet is a single image file that packs multiple animation frames into a grid of rows and columns. Instead of loading a separate image per frame, you load one file and tell Engine.js which region to display — advancing through columns automatically to produce animation. The Sprite class holds all the information needed to slice that grid and advance frames at the right speed.

​
What Is a Sprite Sheet?

Imagine a run-cycle made of four frames, each 64 × 64 pixels, arranged side by side in one PNG. The full image is 256 × 64 px. Each frame occupies one column; all frames in this example live on row 0. Engine.js draws only the current column at any given moment, stepping to the next column after the per-frame interval elapses. 
┌──────┬──────┬──────┬──────┐
│  F0  │  F1  │  F2  │  F3  │  ← row 0
└──────┴──────┴──────┴──────┘
   col 0  col 1  col 2  col 3

​
The Sprite Class

new Sprite(row, cols, altura, anchura, velocidad)
ParameterTypeDescription
rowintWhich row of the sprite sheet to play (0-indexed)
colsintTotal number of columns (frames) in the sheet
alturanumberHeight of a single frame in pixels
anchuranumberWidth of a single frame in pixels
velocidadnumberTotal animation duration in seconds; internally converted to the per-frame interval

​
Velocity Formula

The constructor converts the total animation duration into a per-frame interval using: 
this.velocidad = parseFloat(velocidad) / (this.cols / parseFloat(velocidad));
This means velocidad is the total number of seconds you want the full animation cycle to last. The engine divides that evenly across all columns so each frame is displayed for the same duration.

​
Internal Frame State

Every Sprite instance tracks its playback position with a frame object created in the constructor: 
this.frame = { valor: 0, ultimo: null };
FieldDescription
frame.valorCurrent column index (starts at 0)
frame.ultimoTimestamp (ms) of the last frame advance (null until the first tick)
You do not need to update frame manually — Engine.js manages it inside DibujarSprite on every render tick.

​
Using Sprites

1

Prepare your sprite sheet image

Load the sprite sheet with a standard Image object.
const sheet = new Image();
sheet.src = './assets/run-cycle.png'; // 4 frames wide, 1 row
2

Create a Sprite instance

Describe the layout of the sheet: which row to play, how many columns it has, the pixel size of each frame, and how long the full cycle should last.
const sprite = new $g.Sprite(
  0,    // row 0
  4,    // 4 columns
  64,   // frame height in px
  64,   // frame width in px
  0.5   // 0.5 seconds for the full animation cycle
);
3

Pass both to Imagen

Supply the Image as the first argument and the Sprite as the second argument to $g.Imagen.
const imagen = new $g.Imagen(sheet, sprite);
4

Assign to a Transform and create the Figura

Attach the Imagen to a Transform and set tipo: 'imagen' on the Figura.
const player = new $g.Figura({
  tipo: 'imagen',
  transform: new $g.Transform({
    x: 200, y: 300,
    imagen: new $g.Imagen(sheet, sprite)
  })
});
$g.AgregarFigura(player);

​
Full Example

const sheet = new Image();
sheet.src = './assets/run-cycle.png'; // 4 frames wide, 1 row

const sprite = new $g.Sprite(
  0,    // row 0
  4,    // 4 columns
  64,   // frame height
  64,   // frame width
  0.5   // 0.5 seconds total animation
);

const player = new $g.Figura({
  tipo: 'imagen',
  transform: new $g.Transform({
    x: 200, y: 300,
    imagen: new $g.Imagen(sheet, sprite)
  })
});
$g.AgregarFigura(player);

​
How Frame Advance Works

On every render tick, Engine.js calls DibujarSprite. It computes which region of the sprite sheet to show by multiplying the current column index by the frame width: 
let frameX = sprite.anchura * sprite.frame.valor;
c.drawImage(
  src,
  frameX, sprite.altura * sprite.row,  // source x, y
  sprite.anchura, sprite.altura,        // source width, height
  transform.x, transform.y,            // destination x, y
  sprite.anchura, sprite.altura         // destination width, height
);
After drawing, Engine.js checks whether enough time has passed to advance to the next frame: 
if (sprite.frame.ultimo < Date.now() - (sprite.velocidad * 1000)) {
  sprite.frame.valor = ++sprite.frame.valor % sprite.cols;
  sprite.frame.ultimo = Date.now();
}
When frame.valor reaches cols - 1, the modulo wraps it back to 0, creating a seamless loop.

​
Rendered Size for Sprite Figures

For sprite-based figures, Engine.js uses Sprite.anchura and Sprite.altura as both the source clip size and the destination draw size — not Transform.anchura and Transform.altura. The same values are also used by tocandoFondo when calculating floor collision:
fondo = Environment.altura - this.transform.imagen.sprite.altura;
If you need a different on-screen size, set Sprite.anchura and Sprite.altura to match your desired display dimensions.
Wait for the image to fully load before calling $g.IniciarAnimacion(). If the browser hasn’t decoded the image yet, drawImage may render a blank frame or throw. Use the onload callback to be safe:
const sheet = new Image();
sheet.onload = () => {
  $g.IniciarAnimacion();
};
sheet.src = './assets/run-cycle.png';

​
Next Steps

Static Images

Render a non-animated image with the Imagen class

Sound

Add audio playback to figures with Sonido

Animation Loop

How IniciarAnimacion and DetenerAnimacion work

Sprite API

Full Sprite API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us