Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OmarMtya/engine.js/llms.txt

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

Building a well-structured scene in Engine.js is straightforward once you understand how objects are layered, how the Attributes panel maps to each figure’s properties, and when to involve the physics system. This page walks through the recommended end-to-end workflow, from planning your scene to iterating on it after a live test.
Engine.js runs entirely in the browser and does not persist scene state to a server or local file. If you refresh the page, your scene will be lost. Avoid accidental refreshes while working.
1

Plan your scene

Before placing any objects, sketch out the structure of your scene on paper or in your head. Decide which elements are background (static scenery), which are interactive (platforms, characters, collectibles), and which are foreground or UI overlays. This planning step prevents expensive re-ordering later, because layer order in Engine.js is determined by insertion order.
2

Add background objects first

Objects added to the scene first are rendered at the bottom of the layer stack (index 0). Add your floor tiles, walls, and static backdrop squares before adding any character or interactive objects. Use the Add Square button (#agregarCuadro) for rectangular shapes or Add Circle (#agregarCirculo) for round shapes. Background objects are typically large, non-rigid, and positioned to fill the edges of the canvas.
// Engine.js adds a default square at (100, 100) — reposition via Attributes
let floor = new $g.Figura({
    tipo: "cuadrado",
    transform: new $g.Transform({
        x: 0,
        y: 380,
        anchura: 500,
        altura: 20,
        relleno: "#555555"
    })
});
$g.AgregarFigura(floor);
$g.Dibujar();
3

Configure transforms

Select each object in the Hierarchy panel to open its Attributes. Use the number inputs for X, Y, Anchura (width), and Altura (height) to position and size the object precisely. For circles, set the Radio (radius) instead of width and height. Every keystroke updates the canvas live via $g.Dibujar(), so you see changes instantly without pressing Play.
4

Add images for visual objects

To replace a solid-color fill with a graphic, check the Imagen checkbox in the Attributes panel for that figure. A file picker appears — select a local image file. The engine loads it as an HTMLImageElement and wraps it in a $g.Imagen instance attached to the figure’s transform. The figure type automatically updates to imagen when a file is loaded.Only square and image-type figures support the Image option; circles use their fill color only.
5

Configure sprite animations

If the image you loaded is a sprite sheet (a grid of animation frames), enable the Sprite toggle beneath the image preview. Fill in the following fields to describe the sheet layout:
FieldDescription
Número de hileraWhich row of frames to animate (1-based)
Número de columnasTotal columns (frames) across the sheet
Altura (Sprite individual)Pixel height of a single frame
Anchura (Sprite individual)Pixel width of a single frame
Velocidad (Segundos por frame)Delay between frames — lower = faster
All five values are required and are applied together so that partially filled fields do not cause inconsistent state.
6

Attach physics

Enable the Rígido checkbox for any figure that should respond to gravity and collide with other objects. Once enabled, the Gravedad (gravity) input appears. Set an appropriate value for the feel you want:
  • 0.1 — floaty / space-like
  • 0.5 — normal, earthlike gravity
  • 1.0+ — heavy, fast-falling objects
The Colisión checkbox is enabled by default, meaning the object participates in collision detection. Uncheck it if you want a ghost-like object that falls through everything.
// Attach a rigid body with normal gravity
figura.rigido = new $g.Rigido();
figura.rigido.valor = 0.5;
7

Add sound effects

Check the Sonido checkbox in the Attributes panel to attach audio to a figure. Upload an audio file and choose how it activates using the Tipo de activación dropdown:
Activation ModeWhen it plays
inicialAs soon as the simulation starts
colisionWhen this figure collides with another
colisionInversaWhen this figure stops colliding (leaves contact)
Collision-based audio modes require the figure to also have Rígido enabled — without a rigid body, collision events are never fired.You can also set a Global Audio track using the volume icon in the toolbar. This track plays continuously whenever the scene is running and pauses when you press Pause.
8

Test with Play

Press the Play button in the header to start the simulation. The animation loop begins, physics simulate each frame, sprite animations advance, and sounds trigger according to their activation modes. Note that the Attributes panel is hidden and objects cannot be selected or edited while the simulation is running — this is by design to prevent mid-simulation state corruption.
9

Iterate

Press Pause to stop the simulation. The canvas freezes at the last simulated frame and the hierarchy becomes selectable again. Click any object in the hierarchy to reopen the Attributes panel and adjust its properties. Repeat until the scene behaves as intended.

​
Layer Ordering Strategy

Engine.js renders figures in the order they appear in the $g.figuras array. Index 0 is drawn first (furthest back), and the last index is drawn on top. A practical three-tier approach works well for most scenes:
TierLayer positionExamples
BackgroundBottom (index 0+)Sky, ground, walls, backdrops
InteractiveMiddlePlayer character, enemies, platforms, collectibles
Foreground / UITop (highest index)Score overlays, front-of-scene decorations
Use the ↑ and ↓ arrow buttons in the Attributes panel header to reorder the selected object within the stack. The canvas updates immediately after each move.

​
Using the Layout Switcher

The Window icon button (bottom-left toolbar) cycles through three canvas layout presets:
  • Default — canvas centered, hierarchy on the left, attributes on the right
  • Canvas Right — canvas moves to the right side of the workspace
  • Canvas Left — canvas moves to the left side of the workspace
Choose whichever arrangement suits your monitor size or personal preference. The layout preference is saved to localStorage and restored on the next page load.

​
Physics Gravity Value Guidance

Gravity is applied per-object, not globally. This means different objects in the same scene can fall at different rates — useful for feathers vs. boulders, or for layered parallax effects. 
// Space / floaty
figura.rigido.valor = 0.1;

// Normal earthlike gravity
figura.rigido.valor = 0.5;

// Heavy / fast drop
figura.rigido.valor = 1.5;
When tuning gravity, start at 0.5 and adjust in increments of 0.1 while testing with Play, rather than jumping straight to extreme values.

Build docs developers (and LLMs) love

Get started for freeTalk to us