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.

The Sonido class lets you tie an HTMLAudioElement to a figure’s lifecycle. Rather than calling play() and pause() yourself, you declare when the sound should be active using the activacion property, and Engine.js handles the rest inside its physics loop and initialization routine.

​
The Sonido Class

new Sonido({ src, activacion })
ParameterTypeRequiredDescription
srcHTMLAudioElement✅A native browser Audio object pointing to your sound file
activacionstring✅One of 'inicial', 'colision', or 'colisionInversa' — controls when playback is triggered

​
Activation Modes

The sound plays immediately when Sonido is constructed, and again every time Inicializar() runs at the start of an animation loop. When DetenerAnimacion() is called, Engine.js automatically calls .pause() on every 'inicial' sound.Use this for: background music, ambient loops, intro sounds.
const bgMusic = new Audio('./assets/background.mp3');

const stage = new $g.Figura({
  tipo: 'cuadrado',
  transform: new $g.Transform({
    x: 0, y: 0,
    anchura: 800, altura: 600,
    relleno: '#1E1E2E',
    sonido: new $g.Sonido({ src: bgMusic, activacion: 'inicial' })
  })
});

​
Activation Mode Summary

activacionPlays when…Pauses when…Managed by…
'inicial'Sonido is constructed & on Inicializar()DetenerAnimacion()Constructor + motor.js
'colision'rigido.colision === truerigido.colision === falsetocandoRigidos()
'colisionInversa'rigido.colision === falserigido.colision === truetocandoRigidos()

​
Attaching Sound to a Figure

Pass a Sonido instance to the sonido property of a Transform. Sound is part of the transform, not the figure directly. 
const jumpSound = new Audio('./assets/jump.mp3');

const player = new $g.Figura({
  tipo: 'cuadrado',
  transform: new $g.Transform({
    x: 100, y: 100,
    anchura: 50, altura: 50,
    relleno: '#4F46E5',
    sonido: new $g.Sonido({ src: jumpSound, activacion: 'colision' })
  }),
  rigido: new $g.Rigido()
});

​
Full Example

The example below shows a player figure that plays a wind effect while airborne and a landing thud when it touches the floor: 
// Airborne wind sound
const windSound = new Audio('./assets/wind.mp3');

// Landing impact sound
const landSound = new Audio('./assets/land.mp3');

// Player — plays wind while falling, land sound on ground contact
const player = new $g.Figura({
  tipo: 'cuadrado',
  transform: new $g.Transform({
    x: 200, y: 50,
    anchura: 48, altura: 48,
    relleno: '#6366F1',
    sonido: new $g.Sonido({ src: landSound, activacion: 'colision' })
  }),
  rigido: new $g.Rigido()
});

$g.AgregarFigura(player);
$g.IniciarAnimacion();

​
How Engine.js Manages Playback

For 'colision' and 'colisionInversa' modes, Engine.js checks the figure’s audio state on every physics tick inside tocandoRigidos(): 
// 'colision' mode
if (this.rigido.colision && this.transform.sonido.src.paused) {
  this.transform.sonido.src.play();
}
if (!this.rigido.colision && !this.transform.sonido.src.paused) {
  this.transform.sonido.src.pause();
}
For 'colisionInversa' the logic is inverted — play() is called when colision is false and pause() when it is true. For 'inicial' sounds, Inicializar() calls .play() at the start of every animation loop, and DetenerAnimacion() calls .pause() on the same sounds when the loop is cancelled: 
// Inside DetenerAnimacion
Environment.figuras
  .filter(x => x.transform.sonido && x.transform.sonido.src && x.transform.sonido.activacion == 'inicial')
  .forEach(objeto => { objeto.transform.sonido.src.pause(); });
Setting activacion: 'inicial' calls src.play() immediately inside the Sonido constructor. Make sure the Audio element is ready and that your page has received a user gesture before constructing the Sonido instance — browsers block autoplay without prior user interaction.
'colision' and 'colisionInversa' are only evaluated inside tocandoRigidos(), which runs as part of Engine.js’s physics step. This means the figure must have a Rigido component for either of these modes to work. Additionally, the Rigido component must not have sinColision set to true — figures marked with sinColision skip collision detection entirely and their sound state will never be updated. A figure without rigido, or with rigido.sinColision = true, will never have its sound triggered or paused by collision state.

​
Next Steps

Physics & Collisions

How Rigido and collision detection work

Collision Detection Guide

Detecting and responding to collisions

Animation Loop

IniciarAnimacion and DetenerAnimacion in depth

Sonido API

Full Sonido API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us