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.

Engine.js drives its canvas rendering through a central animation loop. Understanding how the loop starts, stops, and interacts with the editor UI is essential for both building scenes and extending the engine’s behavior. This page explains the lifecycle of a playback session, how to control it programmatically, and how canvas click detection ties into the system.

​
The Animation Loop

The engine exposes three core rendering methods on the global $g object:
MethodDescription
$g.Animar()Starts the continuous animation loop. Each frame re-renders all figures and advances physics.
$g.DetenerAnimacion()Stops the running animation loop. The canvas freezes at the last rendered frame.
$g.Dibujar()Renders a single static frame. Does not start or stop an ongoing loop.
Use $g.Animar() when you need live simulation and $g.Dibujar() when you only need to reflect a property change on the canvas without entering the full loop. 
// Start the animation loop
$g.Animar();

// Stop the animation loop and render a static frame
$g.DetenerAnimacion();
$g.Dibujar();
Calling $g.Dibujar() while the animation loop is already running will not stop the loop — it simply draws one extra frame. Always call $g.DetenerAnimacion() first if you want to halt simulation.
After making a property change to a figure at edit time, call $g.Dibujar() to immediately reflect the update on the canvas without starting the animation loop. This is how the editor’s Attributes panel keeps the canvas in sync with every keystroke.

​
The Play/Pause Button Flow

The #play button in the header toggles between two states. The animando global boolean tracks which state is active. The full sequence for each transition is:
1

Press Play

The animando flag is set to true and the animation loop begins.
animando = true;
$g.Animar();
2

Editor enters play mode

The Attributes panel (#atributos) is hidden so property values cannot be changed mid-simulation. The currently selected object is deselected and the hierarchy list is refreshed without click listeners so objects cannot be selected.
// Attributes panel hidden
document.querySelector("#atributos").style.display = 'none';
objetoSeleccionado = null;
actualizarLista(true);   // re-renders list without click listeners
3

Global audio plays and click detection is disabled

If a global background audio track has been loaded (sonidoGlobal), it begins playing. Canvas click detection is then disabled so user interaction with the canvas is not misinterpreted as object selection.
if (sonidoGlobal) {
    sonidoGlobal.play();
}
$g.DetectarClick(false);   // disables canvas object selection
4

Press Pause

The animando flag is set to false, the loop is stopped, and a static frame is drawn to freeze the canvas at its final simulation state.
animando = false;
$g.DetenerAnimacion();
$g.Dibujar();
5

Editor restores edit mode

The hierarchy list is re-rendered with click listeners so objects become selectable again. Global audio is paused, and canvas click detection is re-enabled so figures can be selected by clicking them.
actualizarLista();   // re-adds click listeners to hierarchy items
if (sonidoGlobal) {
    sonidoGlobal.pause();
}
$g.DetectarClick();   // re-enables canvas object selection

​
Programmatic Playback Control

You can trigger the same play/pause logic directly from code without relying on the button. The pattern mirrors what the #play click handler does: 
// Start simulation programmatically
animando = true;
$g.Animar();

// Stop simulation programmatically and restore a static view
animando = false;
$g.DetenerAnimacion();
$g.Dibujar();
Keep animando in sync with your calls so that any code that checks the flag (such as the hierarchy list renderer) behaves correctly.

​
Canvas Click Detection

$g.DetectarClick() controls whether the engine listens for clicks on the canvas and maps them to figures. 
// Enable click detection (default state in the editor)
$g.DetectarClick();

// Disable click detection (used during play mode)
$g.DetectarClick(false);
During play mode, click detection is disabled so user interactions with the canvas are not misinterpreted as object selection. When the editor returns to pause/edit mode, detection is automatically re-enabled.

​
The Click Listener Callback

When click detection is active, $g.clickListener is called with the Figura object that was clicked. You can override this callback to add custom selection logic: 
$g.clickListener = function(figura) {
    console.log('Clicked figure:', figura.nombre);
    // figura is the Figura object that was clicked
};
The default implementation set by the editor selects the clicked object and updates the hierarchy list and Attributes panel: 
$g.clickListener = function(figura) {
    actualizarLista();
    objetoSeleccionado = figura;
    seleccionarObjeto(false);
};

​
Physics During Animation

When the animation loop is running, every figure that has a rigido component attached will have gravity and collision simulated each frame. The rigido.valor property controls the gravity strength applied to that object. Objects without a rigido component remain stationary during playback. Typical gravity values and their feel:
ValueEffect
0.1Very floaty — suitable for space or underwater scenes
0.5Normal gravity — good general starting point
1.0+Heavy, fast-falling objects
Physics simulation only runs while $g.Animar() is active. Pausing stops all physics advancement immediately, and calling $g.Dibujar() renders the frozen state.

Build docs developers (and LLMs) love

Get started for freeTalk to us