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.

Engine.js ships a lightweight physics model built around a single component: Rigido. Attaching a Rigido to a Figura opts that figure into the simulation — gravity pulls it downward each frame, it detects when it reaches the canvas floor, and it resolves overlaps with other rigid figures. Figures without a Rigido are completely inert and serve as pure visual elements.

​
The Rigido Component

new $g.Rigido(valor, sinColision)
​
valor
number
default:"9.8"
The starting gravity strength for this figure, measured in pixels per frame. This value grows slightly each frame, producing the characteristic acceleration of a falling object. It is also used as the initial velocity value when another figure lands on top of this one.
​
sinColision
boolean
default:"false"
When true, the figure is subject to gravity but is excluded from all collision resolution. It falls through floors and other rigid bodies without interacting with them. Useful for decorative particles or pass-through effects.

​
Internal State Properties

These are set automatically by the engine; you can read them but generally should not write them directly.
​
valorBackup
number
A copy of valor taken at construction time. Stored for potential future use in restoring the original gravity strength.
​
colision
boolean
default:"false"
true when the figure is currently resting on the canvas floor or on top of another rigid figure. The engine uses this flag to suppress gravity for that frame so the figure does not pass through the surface it is resting on.
​
tocandoPor
null
Initialised to null at construction time. Reserved as an internal tracking field on the Rigido component. Note that the tocadoPor reference used in collision resolution (the figure that landed on top of another) is stored directly on the Figura instance, not here.
​
gravedadReiniciada
boolean
default:"false"
An internal flag that the engine sets to true when a collision resets valor back to Environment.gravedad. On the very next tick the engine reads this flag, clears it, and also clears colision — this one-frame delay prevents physics glitches when two figures bounce against each other.

​
How Gravity Works

Every frame, for each figure that has a Rigido and is not currently in collision, the engine calls figura.afectarGravedad(): 
transform.y  += rigido.valor
rigido.valor += rigido.valor / (Environment.FPS * 100)
The second line is the acceleration step. Because valor grows by a fraction of itself every frame, the figure speeds up continuously — just like free-fall. At the default of 60 FPS and valor = 9.8, the increment per frame is tiny (9.8 / 6000 ≈ 0.0016), but it compounds over hundreds of frames into a convincing drop. 
// Slow-motion gravity
Environment.gravedad = 2.0;

const feather = new $g.Figura({
  tipo: 'cuadrado',
  transform: new $g.Transform({ x: 390, y: 0, anchura: 20, altura: 20, relleno: '#f1c40f' }),
  rigido: new $g.Rigido(2.0), // starts at 2.0, accelerates gently
});

$g.AgregarFigura(feather);
$g.Animar();

​
Floor Collision

Each frame, after afectarGravedad() is called, the engine calls figura.tocandoFondo(). This method computes the floor boundary:
  • For ordinary figures: fondo = Environment.altura - transform.altura
  • For sprite figures: fondo = Environment.altura - sprite.altura
If transform.y >= fondo, the figure is clamped to fondo and rigido.colision is set to true. On the next frame, gravity is skipped for that figure. If the figure is no longer at the boundary, colision is reset to false and gravity resumes.

​
Rigid-Body Collision

figura.tocandoRigidos() is called every frame (before afectarGravedad) for each figure that has a Rigido with sinColision = false. It filters Environment.figuras down to all other figures that also have a collision-eligible Rigido, then runs an AABB overlap test via the internal Tocando() utility. When two figures overlap and the other figure’s transform.y is greater (i.e. it is below the current figure in canvas space):
  1. The current figure is repositioned so its bottom edge sits flush with the top of the lower figure.
  2. rigido.colision is set to true, suppressing gravity for that frame.
  3. The lower figure’s tocadoPor property is set to the current figure (the impacting one).
  4. The lower figure inherits the current figure’s rigido.valor (velocity transfer on impact), simulating a push-down effect.
  5. The current figure’s rigido.valor is reset to Environment.gravedad, and gravedadReiniciada is flagged so the engine clears colision on the following tick.
Figures are sorted by Y-axis (descending — highest Y first) before collision resolution runs each frame. This ensures that the figure closest to the floor is resolved first, cascading the physics upward through any stack of objects correctly.

​
Creating a Static Platform

A figure whose Rigido has valor = 0 does not accelerate — gravity cannot speed up something that starts at zero. Other falling figures still collide with it and land on top of it normally. 
// A floor platform — gravity doesn't move it but others collide with it
const platform = new $g.Figura({
  tipo: 'cuadrado',
  transform: new $g.Transform({
    x: 0,
    y: 500,
    anchura: 800,
    altura: 20,
    relleno: '#888888',
  }),
  rigido: new $g.Rigido(0, false), // valor=0 means gravity doesn't accelerate it
});

$g.AgregarFigura(platform);
Register platforms before the figures that land on them. The engine initialises overlap resolution in array order, so a platform that exists in figuras before the falling ball will always be available as a collision target.

​
Pass-Through Figures (sinColision)

Setting sinColision = true makes a figure fall under gravity but skip all collision checks against other rigid bodies. It will also not be a valid landing target for other figures — Tocando() returns false for any pair where either side has sinColision = true. 
const ghost = new $g.Figura({
  tipo: 'circulo',
  transform: new $g.Transform({ x: 200, y: 0, radio: 20, relleno: '#95a5a6' }),
  rigido: new $g.Rigido(9.8, true), // falls freely, no collision
});

$g.AgregarFigura(ghost);
A figure with sinColision = true does not collide with the canvas floor either. It will fall past Environment.altura and disappear from view. If you need a pass-through figure to stop at the floor, you must manage transform.y manually.

​
Resetting the Simulation

When you call $g.DetenerAnimacion(), the engine cancels the animation frame, restores Environment.figuras from the backup snapshot taken at the start of Animar(), and resets the animando flag. Every figure reverts to its original position, and all Rigido values — including valor and colision — return to their initial state. 
// Stop and rewind the scene
$g.DetenerAnimacion();

// Resume from scratch
$g.Animar();

Figures

How Rigido attaches to a Figura.

Environment

Set global gravity before starting the loop.

Collision Detection Guide

Practical patterns for reading and reacting to collisions.

Rigido API Reference

Complete API reference for the Rigido class.

Build docs developers (and LLMs) love

Get started for freeTalk to us