littlejsengine 1.9.8 → 1.9.11

package/README.md

@@ -56,6 +56,7 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 - Robust arcade physics system with collision handling
 - Very fast collision and raycasting for tile maps
+- Full Box2d support using [super fast wasm build of box2d.js](https://github.com/kripken/box2d.js/)
 
 ### 🚀 Flexibility
 
@@ -209,6 +210,7 @@ Here are a few of the amazing games people made using LittleJS...
 - [Data Warrior: 13kb limit](https://js13kgames.com/2024/games/data-warrior-13kb-limit) - Vampire Survivors-like game by [rndD](https://github.com/rndD)
 - [The Way of the Dodo](https://js13kgames.com/2024/games/the-way-of-the-dodo) - Single button platformer by [repsej](https://github.com/repsej)
 - [Wendol Village](https://js13kgames.com/2024/games/wendol-village) - Warcraft-like RTS game by [sanojian](https://github.com/sanojian)
+- [Unblock](https://js13kgames.com/games/unblock) - Retro style space shooter by [Isaac Benitez](https://github.com/isacben)
 
 ![LittleJS Logo](examples/favicon.png)
 

package/dist/littlejs.d.ts

@@ -85,6 +85,11 @@ declare module "littlejsengine" {
      *  @param {Array} [objects=engineObjects] - List of objects to check
      *  @memberof Engine */
     export function engineObjectsCallback(pos?: Vector2, size?: number | Vector2, callbackFunction?: Function, objects?: any[]): void;
+    /** Add a new update function for a plugin
+     *  @param {Function} [updateFunction]
+     *  @param {Function} [renderFunction]
+     *  @memberof Engine */
+    export function engineAddPlugin(updateFunction?: Function, renderFunction?: Function): void;
     /**
      * LittleJS Debug System
      * - Press Esc to show debug overlay with mouse pick
@@ -470,6 +475,10 @@ declare module "littlejsengine" {
      *  @param {Number} scale
      *  @memberof Settings */
     export function setParticleEmitRateScale(scale: number): void;
+    /** Set if touch input is allowed
+     *  @param {Boolean} enable
+     *  @memberof Settings */
+    export function setTouchInputEnable(enable: boolean): void;
     /** Set if gamepads are enabled
      *  @param {Boolean} enable
      *  @memberof Settings */
@@ -1279,17 +1288,17 @@ declare module "littlejsengine" {
      *  @type {WebGL2RenderingContext}
      *  @memberof WebGL */
     export let glContext: WebGL2RenderingContext;
-    /** Set the WebGl texture, called automatically if using multiple textures
-     *  - This may also flush the gl buffer resulting in more draw calls and worse performance
-     *  @param {WebGLTexture} texture
-     *  @memberof WebGL */
-    export function glSetTexture(texture: WebGLTexture): void;
     /** Compile WebGL shader of the given type, will throw errors if in debug mode
      *  @param {String} source
      *  @param {Number} type
      *  @return {WebGLShader}
      *  @memberof WebGL */
     export function glCompileShader(source: string, type: number): WebGLShader;
+    /** Draw any sprites still in the buffer, copy to main canvas and clear
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+     *  @param {Boolean} [forceDraw]
+     *  @memberof WebGL */
+    export function glCopyToContext(context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, forceDraw?: boolean): void;
     /** Create WebGL program with given shaders
      *  @param {String} vsSource
      *  @param {String} fsSource
@@ -1301,11 +1310,34 @@ declare module "littlejsengine" {
      *  @return {WebGLTexture}
      *  @memberof WebGL */
     export function glCreateTexture(image: HTMLImageElement): WebGLTexture;
+    /** Add a sprite to the gl draw list, used by all gl draw functions
+     *  @param {Number} x
+     *  @param {Number} y
+     *  @param {Number} sizeX
+     *  @param {Number} sizeY
+     *  @param {Number} angle
+     *  @param {Number} uv0X
+     *  @param {Number} uv0Y
+     *  @param {Number} uv1X
+     *  @param {Number} uv1Y
+     *  @param {Number} rgba
+     *  @param {Number} [rgbaAdditive=0]
+     *  @memberof WebGL */
+    export function glDraw(x: number, y: number, sizeX: number, sizeY: number, angle: number, uv0X: number, uv0Y: number, uv1X: number, uv1Y: number, rgba: number, rgbaAdditive?: number): void;
+    /** Draw all sprites and clear out the buffer, called automatically by the system whenever necessary
+     *  @memberof WebGL */
+    export function glFlush(): void;
+    /** Set the WebGl texture, called automatically if using multiple textures
+     *  - This may also flush the gl buffer resulting in more draw calls and worse performance
+     *  @param {WebGLTexture} texture
+     *  @memberof WebGL */
+    export function glSetTexture(texture: WebGLTexture): void;
     /**
      * LittleJS Input System
      * - Tracks keyboard down, pressed, and released
      * - Tracks mouse buttons, position, and wheel
      * - Tracks multiple analog gamepads
+     * - Touch input is handled as mouse input
      * - Virtual gamepad for touch devices
      * @namespace Input
      */
@@ -1335,6 +1367,7 @@ declare module "littlejsengine" {
      * - Tracks keyboard down, pressed, and released
      * - Tracks mouse buttons, position, and wheel
      * - Tracks multiple analog gamepads
+     * - Touch input is handled as mouse input
      * - Virtual gamepad for touch devices
      * @namespace Input
      */

package/dist/littlejs.esm.js

@@ -194,8 +194,23 @@ function debugSaveDataURL(dataURL, filename)
     downloadLink.click();
 }
 
+/** Show error as full page of red text
+ *  @memberof Debug */
+function debugShowErrors()
+{
+    onunhandledrejection = (event)=>showError(event.reason);
+    onerror = (event, source, lineno, colno)=>
+        showError(`${event}\n${source}\nLn ${lineno}, Col ${colno}`);
+
+    const showError = (message)=>
+    {
+        document.body.style.backgroundColor = '#111';
+        document.body.innerHTML = `<pre style=color:#f00;font-size:50px>` + message;
+    }
+}
+
 ///////////////////////////////////////////////////////////////////////////////
-// Engine debug function (called automatically)
+// Engine debug functions (called automatically)
 
 function debugInit()
 {
@@ -326,7 +341,7 @@ function debugRender()
             const pos = worldToScreen(p.pos);
             overlayContext.translate(pos.x|0, pos.y|0);
             overlayContext.rotate(p.angle);
-            overlayContext.scale(1, -1);
+            overlayContext.scale(1, p.text ? 1 : -1);
             overlayContext.fillStyle = overlayContext.strokeStyle = p.color;
 
             if (p.text != undefined)
@@ -1500,6 +1515,13 @@ let gamepadDirectionEmulateStick = true;
  *  @memberof Settings */
 let inputWASDEmulateDirection = true;
 
+/** True if touch input is enabled for mobile devices
+ *  - Touch events will be routed to mouse events
+ *  @type {Boolean}
+ *  @default
+ *  @memberof Settings */
+let touchInputEnable = true;
+
 /** True if touch gamepad should appear on mobile devices
  *  - Supports left analog stick, 4 face buttons and start button (button 9)
  *  - Must be set by end of gameInit to be activated
@@ -1715,6 +1737,11 @@ function setGamepadDirectionEmulateStick(enable) { gamepadDirectionEmulateStick
  *  @memberof Settings */
 function setInputWASDEmulateDirection(enable) { inputWASDEmulateDirection = enable; }
 
+/** Set if touch input is allowed
+ *  @param {Boolean} enable
+ *  @memberof Settings */
+function setTouchInputEnable(enable) { touchInputEnable = enable; }
+
 /** Set if touch gamepad should appear on mobile devices
  *  @param {Boolean} enable
  *  @memberof Settings */
@@ -1954,9 +1981,9 @@ class EngineObject
 
         // apply physics
         const oldPos = this.pos.copy();
-        this.velocity.y += gravity * this.gravityScale;
         this.pos.x += this.velocity.x *= this.damping;
-        this.pos.y += this.velocity.y *= this.damping;
+        this.pos.y += this.velocity.y = this.damping * this.velocity.y 
+            + gravity * this.gravityScale;
         this.angle += this.angleVelocity *= this.angleDamping;
 
         // physics sanity checks
@@ -2085,19 +2112,22 @@ class EngineObject
                     const isBlockedX = tileCollisionTest(vec2(this.pos.x, oldPos.y), this.size, this);
                     if (isBlockedY || !isBlockedX)
                     {
-                        // set if landed on ground
-                        this.groundObject = wasMovingDown;
-
                         // bounce velocity
                         this.velocity.y *= -this.elasticity;
 
-                        // adjust next velocity to settle on ground
-                        const o = (oldPos.y - this.size.y/2|0) - (oldPos.y - this.size.y/2);
-                        if (o < 0 && o > this.damping * this.velocity.y + gravity * this.gravityScale) 
-                            this.velocity.y = this.damping ? (o - gravity * this.gravityScale) / this.damping : 0;
-
-                        // move to previous position
-                        this.pos.y = oldPos.y;
+                        // set if landed on ground
+                        if (this.groundObject = wasMovingDown)
+                        {
+                            // adjust position to slightly above nearest tile boundary
+                            // this prevents gap between object and ground
+                            const epsilon = .0001;
+                            this.pos.y = (oldPos.y-this.size.y/2|0)+this.size.y/2+epsilon;
+                        }
+                        else
+                        {
+                            // move to previous position
+                            this.pos.y = oldPos.y;
+                        }
                     }
                     if (isBlockedX)
                     {
@@ -2235,13 +2265,16 @@ class EngineObject
     /** Render debug info for this object  */
     renderDebugInfo()
     {
-        // show object info for debugging
-        const size = vec2(max(this.size.x, .2), max(this.size.y, .2));
-        const color1 = rgb(this.collideTiles?1:0, this.collideSolidObjects?1:0, this.isSolid?1:0, this.parent?.2:.5);
-        const color2 = this.parent ? rgb(1,1,1,.5) : rgb(0,0,0,.8);
-        drawRect(this.pos, size, color1, this.angle, false);
-        drawRect(this.pos, size.scale(.8), color2, this.angle, false);
-        this.parent && drawLine(this.pos, this.parent.pos, .1, rgb(0,0,1,.5), false);
+        if (debug)
+        {
+            // show object info for debugging
+            const size = vec2(max(this.size.x, .2), max(this.size.y, .2));
+            const color1 = rgb(this.collideTiles?1:0, this.collideSolidObjects?1:0, this.isSolid?1:0, this.parent?.2:.5);
+            const color2 = this.parent ? rgb(1,1,1,.5) : rgb(0,0,0,.8);
+            drawRect(this.pos, size, color1, this.angle, false);
+            drawRect(this.pos, size.scale(.8), color2, this.angle, false);
+            this.parent && drawLine(this.pos, this.parent.pos, .1, rgb(0,0,1,.5), false);
+        }
     }
 }
 /** 
@@ -2748,6 +2781,7 @@ function toggleFullscreen()
  * - Tracks keyboard down, pressed, and released
  * - Tracks mouse buttons, position, and wheel
  * - Tracks multiple analog gamepads
+ * - Touch input is handled as mouse input
  * - Virtual gamepad for touch devices
  * @namespace Input
  */
@@ -2881,7 +2915,8 @@ function inputUpdate()
     if (headlessMode) return;
 
     // clear input when lost focus (prevent stuck keys)
-    isTouchDevice || document.hasFocus() || clearInput();
+    if(!(touchInputEnable && isTouchDevice) && !document.hasFocus())
+        clearInput();
 
     // update mouse world space position
     mousePos = screenToWorld(mousePosScreen);
@@ -2942,6 +2977,10 @@ function inputInit()
     // mouse event handlers
     onmousedown   = (e)=>
     {
+        // fix stalled audio requiring user interaction
+        if (soundEnable && !headlessMode && audioContext && audioContext.state != 'running')
+            audioContext.resume();
+        
         isUsingGamepad = false; 
         inputData[0][e.button] = 3; 
         mousePosScreen = mouseToScreen(e); 
@@ -2953,7 +2992,7 @@ function inputInit()
     oncontextmenu = (e)=> false; // prevent right click menu
 
     // init touch input
-    if (isTouchDevice)
+    if (isTouchDevice && touchInputEnable)
         touchInputInit();
 }
 
@@ -3081,12 +3120,12 @@ function vibrateStop() { vibrate(0); }
 
 /** True if a touch device has been detected
  *  @memberof Input */
-const isTouchDevice = !headlessMode && window.ontouchstart !== undefined;
+const isTouchDevice = window.ontouchstart !== undefined;
 
 // touch gamepad internal variables
 let touchGamepadTimer = new Timer, touchGamepadButtons, touchGamepadStick;
 
-// try to enable touch mouse
+// enable touch input mouse passthrough
 function touchInputInit()
 {
     // add non passive touch event listeners
@@ -3110,8 +3149,8 @@ function touchInputInit()
     function handleTouchDefault(e)
     {
         // fix stalled audio requiring user interaction
-        if (soundEnable && audioContext && audioContext.state != 'running')
-            zzfx(0);
+        if (soundEnable && !headlessMode && audioContext && audioContext.state != 'running')
+            audioContext.resume();
 
         // check if touching and pass to mouse events
         const touching = e.touches.length;
@@ -3195,6 +3234,7 @@ function touchInputInit()
 // render the touch gamepad, called automatically by the engine
 function touchGamepadRender()
 {
+    if (!touchInputEnable || !isTouchDevice || headlessMode) return;
     if (!touchGamepadEnable || !touchGamepadTimer.isSet())
         return;
     
@@ -3323,6 +3363,7 @@ class Sound
             // generate zzfx sound now for fast playback
             const defaultRandomness = .05;
             this.randomness = zzfxSound[1] || defaultRandomness;
+            zzfxSound[1] = 0; // generate without randomness
             this.sampleChannels = [zzfxG(...zzfxSound)];
             this.sampleRate = zzfxR;
         }
@@ -3555,10 +3596,6 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
 
 ///////////////////////////////////////////////////////////////////////////////
 
-// internal tracking if audio was suspended when last sound was played
-// allows first suspended sound to play when audio is resumed
-let audioSuspended = false;
-
 /** 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
@@ -3574,20 +3611,21 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
     if (!soundEnable || headlessMode) return;
 
     // prevent sounds from building up if they can't be played
-    const audioWasSuspended = audioSuspended;
-    if (audioSuspended = audioContext.state != 'running')
+    if (audioContext.state != 'running')
     {
         // fix stalled audio
-        audioContext.resume();
+        audioContext.resume().then(()=>
+            playSamples(sampleChannels, volume, rate, pan, loop, sampleRate, gainNode));
 
         // prevent suspended sounds from building up
-        if (audioWasSuspended)
-            return;
+        return;
     }
 
     // create buffer and source
-    const buffer = audioContext.createBuffer(sampleChannels.length, sampleChannels[0].length, sampleRate), 
-        source = audioContext.createBufferSource();
+    const channelCount = sampleChannels.length;
+    const sampleLength = sampleChannels[0].length;
+    const buffer = audioContext.createBuffer(channelCount, sampleLength, sampleRate);
+    const source = audioContext.createBufferSource();
 
     // copy samples to buffer and setup source
     sampleChannels.forEach((c,i)=> buffer.getChannelData(i).set(c));
@@ -3601,7 +3639,8 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
     gainNode.connect(audioGainNode);
 
     // connect source to stereo panner and gain
-    source.connect(new StereoPannerNode(audioContext, {'pan':clamp(pan, -1, 1)})).connect(gainNode);
+    const pannerNode = new StereoPannerNode(audioContext, {'pan':clamp(pan, -1, 1)});
+    source.connect(pannerNode).connect(gainNode);
 
     // play and return sound
     source.start();
@@ -3617,7 +3656,7 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
  *  @param {Array} zzfxSound - Array of ZzFX parameters, ex. [.5,.5]
  *  @return {AudioBufferSourceNode} - The audio node of the sound played
  *  @memberof Audio */
-function zzfx(...zzfxSound) { return new Sound(zzfxSound).play(); }
+function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
 
 /** Sample rate used for all ZzFX sounds
  *  @default 44100
@@ -3626,7 +3665,7 @@ const zzfxR = 44100;
 
 /** Generate samples for a ZzFX sound
  *  @param {Number}  [volume] - Volume scale (percent)
- *  @param {Number}  [randomness] - Unused in this fuction, handled by Sound class
+ *  @param {Number}  [randomness] - How much to randomize frequency (percent Hz)
  *  @param {Number}  [frequency] - Frequency of sound (Hz)
  *  @param {Number}  [attack] - Attack time, how fast sound starts (seconds)
  *  @param {Number}  [sustain] - Sustain time, how long sound holds (seconds)
@@ -3652,7 +3691,7 @@ const zzfxR = 44100;
 function zzfxG
 (
     // parameters
-    volume = 1, randomness = 0, frequency = 220, attack = 0, sustain = 0,
+    volume = 1, randomness = .05, frequency = 220, attack = 0, sustain = 0,
     release = .1, shape = 0, shapeCurve = 1, slide = 0, deltaSlide = 0,
     pitchJump = 0, pitchJumpTime = 0, repeatTime = 0, noise = 0, modulation = 0,
     bitCrush = 0, delay = 0, sustainVolume = 1, decay = 0, tremolo = 0, filter = 0
@@ -3663,7 +3702,8 @@ function zzfxG
     // init parameters
     let PI2 = PI*2, sampleRate = zzfxR,
         startSlide = slide *= 500 * PI2 / sampleRate / sampleRate,
-        startFrequency = frequency *= PI2 / sampleRate,
+        startFrequency = frequency *= 
+            rand(1 + randomness, 1-randomness) * PI2 / sampleRate,
         b = [], t = 0, tm = 0, i = 0, j = 1, r = 0, c = 0, s = 0, f, length,
 
         // biquad LP/HP filter
@@ -4599,7 +4639,8 @@ function medalsInit(saveName)
         medalsForEach(medal=> medal.unlocked = (localStorage[medal.storageKey()] | 0));
 
     // engine automatically renders medals
-    addPluginRender(function()
+    engineAddPlugin(undefined, medalsRender);
+    function medalsRender()
     {
         if (!medalsDisplayQueue.length)
             return;
@@ -4623,7 +4664,7 @@ function medalsInit(saveName)
                 time > slideOffTime ? (time - slideOffTime) / medalDisplaySlideTime : 0;
             medal.render(hidePercent);
         }
-    });
+    }
 }
 
 /** Calls a function for each medal
@@ -5062,7 +5103,7 @@ const engineName = 'LittleJS';
  *  @type {String}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.9.8';
+const engineVersion = '1.9.11';
 
 /** Frames per second to update
  *  @type {Number}
@@ -5121,14 +5162,14 @@ let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
 const pluginUpdateList = [], pluginRenderList = [];
 
 /** Add a new update function for a plugin
- *  @param {Function} updateFunction
+ *  @param {Function} [updateFunction]
+ *  @param {Function} [renderFunction]
  *  @memberof Engine */
-function addPluginUpdate(updateFunction) { pluginUpdateList.push(updateFunction); }
-
-/** Add a new render function for a plugin
- *  @param {Function} renderFunction
- *  @memberof Engine */
-function addPluginRender(renderFunction) { pluginRenderList.push(renderFunction); }
+function engineAddPlugin(updateFunction, renderFunction)
+{
+    updateFunction && pluginUpdateList.push(updateFunction);
+    renderFunction && pluginRenderList.push(renderFunction);
+}
 
 ///////////////////////////////////////////////////////////////////////////////
 // Main engine functions
@@ -5301,10 +5342,11 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
     const styleBody = 
         'margin:0;overflow:hidden;' + // fill the window
         'background:#000;' +          // set background color
-        'touch-action:none;' +        // prevent mobile pinch to resize
-        'user-select:none;' +         // prevent mobile hold to select
+        'user-select:none;' +         // prevent hold to select
         '-webkit-user-select:none;' + // compatibility for ios
-        '-webkit-touch-callout:none'; // compatibility for ios
+        (!touchInputEnable ? '' :     // no touch css setttings
+        'touch-action:none;' +        // prevent mobile pinch to resize
+        '-webkit-touch-callout:none');// compatibility for ios
     document.body.style.cssText = styleBody;
     document.body.appendChild(mainCanvas = document.createElement('canvas'));
     mainContext = mainCanvas.getContext('2d');
@@ -5645,6 +5687,7 @@ export {
 	engineObjectsUpdate,
 	engineObjectsDestroy,
 	engineObjectsCallback,
+	engineAddPlugin,
 	
 	// Globals
 	debug,
@@ -5726,6 +5769,7 @@ export {
 	setObjectMaxSpeed,
 	setGravity,
 	setParticleEmitRateScale,
+	setTouchInputEnable,
 	setGamepadsEnable,
 	setGamepadDirectionEmulateStick,
 	setInputWASDEmulateDirection,
@@ -5811,10 +5855,13 @@ export {
 	// WebGL
 	glCanvas,
 	glContext,
-	glSetTexture,
 	glCompileShader,
+	glCopyToContext,
 	glCreateProgram,
 	glCreateTexture,
+	glDraw,
+	glFlush,
+	glSetTexture,
 
 	// Input
 	keyIsDown,
@@ -5874,4 +5921,5 @@ export {
 	medalsPreventUnlock,
 	medalsInit,
 	Medal,
-};
+};
+