littlejsengine 1.14.11 → 1.14.19

package/src/engine.js

@@ -30,7 +30,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.14.11';
+const engineVersion = '1.14.19';
 
 /** Frames per second to update
  *  @type {number}
@@ -91,29 +91,60 @@ let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
 ///////////////////////////////////////////////////////////////////////////////
 // plugin hooks
 
-const pluginUpdateList = [], pluginRenderList = [];
+const pluginList = [];
+class EnginePlugin
+{
+    constructor(update, render, glContextLost, glContextRestored)
+    {
+        this.update = update;
+        this.render = render;
+        this.glContextLost = glContextLost;
+        this.glContextRestored = glContextRestored;
+    }
+}
+
+/**
+ * @callback PluginCallback - Update or render function for a plugin
+ * @memberof Engine
+ */
 
 /** Add a new update function for a plugin
- *  @param {Function} [updateFunction]
- *  @param {Function} [renderFunction]
+ *  @param {PluginCallback} [update]
+ *  @param {PluginCallback} [render]
+ *  @param {PluginCallback} [glContextLost]
+ *  @param {PluginCallback} [glContextRestored]
  *  @memberof Engine */
-function engineAddPlugin(updateFunction, renderFunction)
+function engineAddPlugin(update, render, glContextLost, glContextRestored)
 {
-    ASSERT(!pluginUpdateList.includes(updateFunction));
-    ASSERT(!pluginRenderList.includes(renderFunction));
-    updateFunction && pluginUpdateList.push(updateFunction);
-    renderFunction && pluginRenderList.push(renderFunction);
+    // make sure plugin functions are unique
+    ASSERT(!pluginList.find(p=>
+        p.update === update && p.render === render &&
+        p.glContextLost === glContextLost &&
+        p.glContextRestored === glContextRestored));
+
+    const plugin = new EnginePlugin(update, render, glContextLost, glContextRestored);
+    pluginList.push(plugin);
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 // Main Engine Functions
 
+/**
+ * @callback GameInitCallback - Called after the engine starts, can be async
+ * @returns {void|Promise<void>}
+ * @memberof Engine
+ */
+/**
+ * @callback GameCallback - Update or render function for the game
+ * @memberof Engine
+ */
+
 /** Startup LittleJS engine with your callback functions
- *  @param {Function|function():Promise} gameInit - Called once after the engine starts up, can be async for loading
- *  @param {Function} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
- *  @param {Function} gameUpdatePost - Called after physics and objects are updated, even when paused, use for UI updates
- *  @param {Function} gameRender - Called before objects are rendered, use for drawing backgrounds/world elements
- *  @param {Function} gameRenderPost - Called after objects are rendered, use for drawing UI/overlays
+ *  @param {GameInitCallback} gameInit - Called once after the engine starts up, can be async for loading
+ *  @param {GameCallback} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
+ *  @param {GameCallback} gameUpdatePost - Called after physics and objects are updated, even when paused, use for UI updates
+ *  @param {GameCallback} gameRender - Called before objects are rendered, use for drawing backgrounds/world elements
+ *  @param {GameCallback} gameRenderPost - Called after objects are rendered, use for drawing UI/overlays
  *  @param {Array<string>} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png'])
  *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body
  *  @example
@@ -177,7 +208,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             wasUpdated = true;
             updateCanvas();
             inputUpdate();
-            pluginUpdateList.forEach(f=>f());
+            pluginList.forEach(plugin=>plugin.update?.());
 
             // update object transforms even when paused
             for (const o of engineObjects)
@@ -210,7 +241,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 updateCanvas();
                 inputUpdate();
                 gameUpdate();
-                pluginUpdateList.forEach(f=>f());
+                pluginList.forEach(plugin=>plugin.update?.());
                 engineObjectsUpdate();
 
                 // do post update
@@ -244,7 +275,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             for (const o of engineObjects)
                 o.destroyed || o.render();
             gameRenderPost();
-            pluginRenderList.forEach(f=>f());
+            pluginList.forEach(plugin=>plugin.render?.());
             touchGamepadRender();
             debugRender();
             glFlush();
@@ -365,11 +396,12 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     const promises = imageSources.map((src, textureIndex)=>
         new Promise(resolve =>
         {
+            ASSERT(isString(src), 'imageSources must be an array of strings');
+
             const image = new Image;
             image.onerror = image.onload = ()=>
             {
                 const textureInfo = new TextureInfo(image);
-                textureInfo.createWebGLTexture();
                 textureInfos[textureIndex] = textureInfo;
                 resolve();
             }
@@ -385,7 +417,6 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         {
             const textureInfo = new TextureInfo(new Image);
             textureInfos[0] = textureInfo;
-            textureInfo.createWebGLTexture();
             resolve();
         }));
     }
@@ -396,7 +427,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         promises.push(new Promise(resolve =>
         {
             let t = 0;
-            LOG(`${engineName} Engine v${engineVersion}`);
+            console.log(`${engineName} Engine v${engineVersion}`);
             updateSplash();
             function updateSplash()
             {
@@ -480,10 +511,16 @@ function engineObjectsCollect(pos, size, objects=engineObjects)
     return collectedObjects;
 }
 
+/**
+ * @callback ObjectCallbackFunction - Function that processes an object
+ * @param {EngineObject} uiObjects
+ *  @memberof Engine
+ */
+
 /** Triggers a callback for each object within a given area
- *  @param {Vector2} [pos]                 - Center of test area, or undefined for all objects
- *  @param {Vector2|number} [size]         - Radius of circle if float, rectangle size if Vector2
- *  @param {Function} [callbackFunction]   - Calls this function on every object that passes the test
+ *  @param {Vector2} [pos] - Center of test area, or undefined for all objects
+ *  @param {Vector2|number} [size] - Radius of circle if float, rectangle size if Vector2
+ *  @param {ObjectCallbackFunction} [callbackFunction] - Calls this function on every object that passes the test
  *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
  *  @memberof Engine */
 function engineObjectsCallback(pos, size, callbackFunction, objects=engineObjects)

package/src/engineAudio.js

@@ -47,6 +47,7 @@ function audioInit()
  * Sound Object - Stores a sound for later use and can be played positionally
  *
  * <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
+ * @memberof Audio
  * @example
  * // create a sound
  * const sound_example = new Sound([.5,.5]);
@@ -141,12 +142,12 @@ class Sound
 
     /** Play the sound as a musical note with a semitone offset
      *  This can be used to play music with chromatic scales
-     *  @param {number}  semitoneOffset - How many semitones to offset pitch
+     *  @param {number}  [semitoneOffset=0] - How many semitones to offset pitch
      *  @param {Vector2} [pos] - World space position to play the sound if any
      *  @param {number}  [volume=1] - How much to scale volume by
      *  @return {SoundInstance} - The audio source node
      */
-    playNote(semitoneOffset, pos, volume)
+    playNote(semitoneOffset=0, pos, volume)
     {
         const pitch = getNoteFrequency(semitoneOffset, 1);
         return this.play(pos, volume, pitch, 0);
@@ -169,6 +170,8 @@ class Sound
 /**
  * Sound Wave Object - Stores a wave sound for later use and can be played positionally
  * - this can be used to play wave, mp3, and ogg files
+ * @extends Sound
+ * @memberof Audio
  * @example
  * // create a sound
  * const sound_example = new SoundWave('sound.mp3');
@@ -178,22 +181,29 @@ class Sound
  */
 class SoundWave extends Sound
 {
+    /**
+     * @callback SoundLoadCallback - Function called when sound is loaded
+     * @param {SoundWave} sound
+     * @memberof Audio
+     */
+    
     /** Create a sound object and cache the wave file for later use
      *  @param {string} filename - Filename of audio file to load
      *  @param {number} [randomness] - How much to randomize frequency each time sound plays
      *  @param {number} [range=soundDefaultRange] - World space max range of sound
      *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
-     *  @param {Function} [onloadCallback] - callback function to call when sound is loaded
+     *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
      */
     constructor(filename, randomness=0, range, taper, onloadCallback)
     {
         super(undefined, range, taper);
         if (!soundEnable || headlessMode) return;
+        ASSERT(!filename || isString(filename), 'filename must be a string');
 
-        /** @property {Function} - callback function to call when sound is loaded */
+        /** @property {SoundLoadCallback} - callback function to call when sound is loaded */
         this.onloadCallback = onloadCallback;
         this.randomness = randomness;
-        this.loadSound(filename);
+        filename && this.loadSound(filename);
     }
 
     /** Loads a sound from a URL and decodes it into sample data. Must be used with await!
@@ -202,6 +212,8 @@ class SoundWave extends Sound
     async loadSound(filename)
     {
         const response = await fetch(filename);
+        if (!response.ok)
+            throw new Error(`Failed to load sound from ${filename}: ${response.status} ${response.statusText}`);
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
         
@@ -237,7 +249,7 @@ class SoundWave extends Sound
         this.sampleChannels = sampleChannels;
         this.loadedPercent = 1;
         if (this.onloadCallback)
-            this.onloadCallback();
+            this.onloadCallback(this);
     }
 }
 
@@ -246,6 +258,7 @@ class SoundWave extends Sound
 /** 
  * Sound Instance - Wraps an AudioBufferSourceNode for individual sound control
  * Represents a single playing instance of a sound with pause/resume capabilities
+ * @memberof Audio
  * @example
  * // Play a sound and get an instance for control
  * const jumpSound = new Sound([.5,.5,220]);
@@ -311,8 +324,16 @@ class SoundInstance
             this.stop();
         this.gainNode = audioContext.createGain();
         this.source = playSamples(this.sound.sampleChannels, this.volume, this.rate, this.pan, this.loop, this.sound.sampleRate, this.gainNode, offset, this.onendedCallback);
-        this.startTime = audioContext.currentTime - offset;
-        this.pausedTime = undefined;
+        if (this.source)
+        {
+            this.startTime = audioContext.currentTime - offset;
+            this.pausedTime = undefined;
+        }
+        else
+        {
+            this.startTime = undefined;
+            this.pausedTime = 0;
+        }
     }
 
     /** Set the volume of this sound instance
@@ -445,6 +466,12 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
 
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * @callback AudioEndedCallback - Function called when a sound ends
+ * @param {AudioBufferSourceNode} source
+ * @memberof Audio
+ */
+
 /** Play cached audio samples with given settings
  *  @param {Array}    sampleChannels - Array of arrays of samples to play (for stereo playback)
  *  @param {number}   [volume] - How much to scale volume by
@@ -454,13 +481,20 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
  *  @param {number}   [sampleRate=44100] - Sample rate for the sound
  *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing
  *  @param {number}   [offset] - Offset in seconds to start playback from
- *  @param {Function} [onended] - Callback for when the sound ends
- *  @return {AudioBufferSourceNode} - The audio node of the sound played
+ *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
+ *  @return {AudioBufferSourceNode} - The source node of the sound played, may be undefined if play fails
  *  @memberof Audio */
 function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=audioDefaultSampleRate, gainNode, offset=0, onended)
 {
     if (!soundEnable || headlessMode) return;
 
+    if (!audioIsRunning())
+    {
+        // fix stalled audio, this sound won't be able to play
+        audioContext.resume();
+        return;
+    }
+
     // create buffer and source
     const channelCount = sampleChannels.length;
     const sampleLength = sampleChannels[0].length;
@@ -486,13 +520,6 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
     if (onended)
         source.addEventListener('ended', ()=> onended(source));
 
-    if (!audioIsRunning())
-    {
-        // fix stalled audio, this sound won't be able to play
-        audioContext.resume();
-        return;
-    }
-
     // play and return sound
     const startOffset = offset * rate;
     source.start(0, startOffset);

package/src/engineDebug.js

@@ -47,10 +47,16 @@ let debugPrimitives = [], debugPhysics = false, debugRaycast = false, debugParti
 // Debug helper functions
 
 /** Asserts if the expression is false, does nothing in release builds
+ *  Halts execution if the assert fails and throws an error
  *  @param {boolean} assert
  *  @param {...Object} [output] - error message output
  *  @memberof Debug */
-function ASSERT(assert, ...output) { console.assert(assert, ...output); }
+function ASSERT(assert, ...output)
+{
+    if (assert) return;
+    console.assert(assert, ...output)
+    throw new Error('Assert failed!'); // halt execution
+}
 
 /** Log to console if debug is enabled, does nothing in release builds
  *  @param {...Object} [output] - message output
@@ -60,64 +66,72 @@ function LOG(...output) { console.log(...output); }
 /** Draw a debug rectangle in world space
  *  @param {Vector2} pos
  *  @param {Vector2} [size=Vector2()]
- *  @param {string}  [color]
- *  @param {number}  [time]
- *  @param {number}  [angle]
+ *  @param {Color|string} [color]
+ *  @param {number} [time]
+ *  @param {number} [angle]
  *  @param {boolean} [fill]
  *  @memberof Debug */
-function debugRect(pos, size=vec2(), color='#fff', time=0, angle=0, fill=false)
+function debugRect(pos, size=vec2(), color=WHITE, time=0, angle=0, fill=false)
 {
     if (typeof size === 'number')
         size = vec2(size); // allow passing in floats
-    ASSERT(typeof color === 'string', 'pass in css color strings');
-    debugPrimitives.push({pos, size, color, time:new Timer(time), angle, fill});
+    if (isColor(color))
+        color = color.toString();
+    pos = pos.copy();
+    size = size.copy();
+    const timer = new Timer(time);
+    debugPrimitives.push({pos:pos.copy(), size:size.copy(), color, timer, angle, fill});
 }
 
 /** Draw a debug poly in world space
  *  @param {Vector2} pos
  *  @param {Array<Vector2>} points
- *  @param {string}  [color]
- *  @param {number}  [time]
- *  @param {number}  [angle]
+ *  @param {Color|string} [color]
+ *  @param {number} [time]
+ *  @param {number} [angle]
  *  @param {boolean} [fill]
  *  @memberof Debug */
-function debugPoly(pos, points, color='#fff', time=0, angle=0, fill=false)
+function debugPoly(pos, points, color=WHITE, time=0, angle=0, fill=false)
 {
-    ASSERT(typeof color === 'string', 'pass in css color strings');
-    debugPrimitives.push({pos, points, color, time:new Timer(time), angle, fill});
+    if (isColor(color))
+        color = color.toString();
+    pos = pos.copy();
+    points = points.map(p=>p.copy());
+    const timer = new Timer(time);
+    debugPrimitives.push({pos, points, color, timer, angle, fill});
 }
 
 /** Draw a debug circle in world space
  *  @param {Vector2} pos
- *  @param {number}  [size] - diameter
- *  @param {string}  [color]
- *  @param {number}  [time]
+ *  @param {number} [size] - diameter
+ *  @param {Color|string} [color]
+ *  @param {number} [time]
  *  @param {boolean} [fill]
  *  @memberof Debug */
-function debugCircle(pos, size=0, color='#fff', time=0, fill=false)
+function debugCircle(pos, size=0, color=WHITE, time=0, fill=false)
 {
-    ASSERT(typeof color === 'string', 'pass in css color strings');
-    debugPrimitives.push({pos, size, color, time:new Timer(time), angle:0, fill});
+    if (isColor(color))
+        color = color.toString();
+    pos = pos.copy();
+    const timer = new Timer(time);
+    debugPrimitives.push({pos, size, color, timer, angle:0, fill});
 }
 
 /** Draw a debug point in world space
  *  @param {Vector2} pos
- *  @param {string}  [color]
- *  @param {number}  [time]
- *  @param {number}  [angle]
+ *  @param {Color|string} [color]
+ *  @param {number} [time]
+ *  @param {number} [angle]
  *  @memberof Debug */
 function debugPoint(pos, color, time, angle)
-{
-    ASSERT(typeof color === 'string', 'pass in css color strings');
-    debugRect(pos, undefined, color, time, angle);
-}
+{ debugRect(pos, undefined, color, time, angle); }
 
 /** Draw a debug line in world space
  *  @param {Vector2} posA
  *  @param {Vector2} posB
- *  @param {string}  [color]
- *  @param {number}  [width]
- *  @param {number}  [time]
+ *  @param {Color|string} [color]
+ *  @param {number} [width]
+ *  @param {number} [time]
  *  @memberof Debug */
 function debugLine(posA, posB, color, width=.1, time)
 {
@@ -131,7 +145,7 @@ function debugLine(posA, posB, color, width=.1, time)
  *  @param {Vector2} sizeA
  *  @param {Vector2} posB
  *  @param {Vector2} sizeB
- *  @param {string}  [color]
+ *  @param {Color|string} [color]
  *  @memberof Debug */
 function debugOverlap(posA, sizeA, posB, sizeB, color)
 {
@@ -147,18 +161,21 @@ function debugOverlap(posA, sizeA, posB, sizeB, color)
 }
 
 /** Draw a debug axis aligned bounding box in world space
- *  @param {string}  text
+ *  @param {string} text
  *  @param {Vector2} pos
- *  @param {number}  [size]
- *  @param {string}  [color]
- *  @param {number}  [time]
- *  @param {number}  [angle]
- *  @param {string}  [font]
+ *  @param {number} [size]
+ *  @param {Color|string} [color]
+ *  @param {number} [time]
+ *  @param {number} [angle]
+ *  @param {string} [font]
  *  @memberof Debug */
-function debugText(text, pos, size=1, color='#fff', time=0, angle=0, font='monospace')
+function debugText(text, pos, size=1, color=WHITE, time=0, angle=0, font='monospace')
 {
-    ASSERT(typeof color === 'string', 'pass in css color strings');
-    debugPrimitives.push({text, pos, size, color, time:new Timer(time), angle, font});
+    if (isColor(color))
+        color = color.toString();
+    pos = pos.copy();
+    const timer = new Timer(time);
+    debugPrimitives.push({text, pos, size, color, timer, angle, font});
 }
 
 /** Clear all debug primitives in the list
@@ -209,17 +226,30 @@ function debugSaveDataURL(dataURL, filename)
     downloadLink.click();
 }
 
-/** Show error as full page of red text
+/** Breaks on all asserts/errors, hides the canvas, and shows message in plain text
+ *  This is a good function to call at the start of your game to catch all errors
+ *  In release builds this function has no effect
  *  @memberof Debug */
 function debugShowErrors()
 {
     const showError = (message)=>
     {
         // replace entire page with error message
-        document.body.style.display = '';
-        document.body.style.backgroundColor = '#111';
-        document.body.innerHTML = `<pre style=color:#f00;font-size:50px;white-space:pre-wrap>` + message;
+        document.body.style = 'background-color:#111;margin:8px';
+        document.body.innerHTML = `<pre style=color:#f00;font-size:28px;white-space:pre-wrap>` + message;
     }
+    
+    const originalAssert = console.assert;
+    console.assert = (assertion, ...output)=>
+    {
+        originalAssert(assertion, ...output);
+        if (!assertion)
+        {
+            const message = output.join(' ');
+            const stack = new Error().stack;
+            throw 'Assertion failed!\n' + message + '\n' + stack;
+        }
+    };
     onunhandledrejection = (event)=>
         showError(event.reason.stack || event.reason);
     onerror = (message, source, lineno, colno)=>
@@ -387,7 +417,7 @@ function debugRender()
                 p.fill && overlayContext.fill();
                 overlayContext.stroke();
             }
-            else if (p.size === 0 || p.size.x === 0 && p.size.y === 0)
+            else if (p.size === 0 || (p.size.x === 0 && p.size.y === 0))
             {
                 // point
                 overlayContext.fillRect(-pointSize/2, -1, pointSize, 3);
@@ -414,7 +444,7 @@ function debugRender()
         });
 
         // remove expired primitives
-        debugPrimitives = debugPrimitives.filter(r=>r.time<0);
+        debugPrimitives = debugPrimitives.filter(r=>r.timer<0);
     }
 
     if (debugObject)