littlejsengine 1.18.26 → 1.18.28

package/dist/littlejs.d.ts

@@ -514,6 +514,13 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let gamepadDirectionEmulateStick: boolean;
+    /** If true, axes that do not rest near center are ignored on gamepads without
+     *  standard mapping. Steering wheels and flight sticks report pedal and throttle
+     *  axes that rest at full deflection, which otherwise reads as a stick held down.
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let gamepadAxisFilterEnable: boolean;
     /** If true the WASD keys are also routed to the direction keys (for better accessibility)
      *  @type {boolean}
      *  @default
@@ -780,6 +787,10 @@ declare module "littlejsengine" {
      *  @param {boolean} enable
      *  @memberof Settings */
     export function setGamepadDirectionEmulateStick(enable: boolean): void;
+    /** Set if axes that do not rest near center are ignored on non-standard gamepads
+     *  @param {boolean} enable
+     *  @memberof Settings */
+    export function setGamepadAxisFilterEnable(enable: boolean): void;
     /** Set if true the WASD keys are also routed to the direction keys
      *  @param {boolean} enable
      *  @memberof Settings */
@@ -1817,6 +1828,11 @@ declare module "littlejsengine" {
      *  @type {OffscreenCanvasRenderingContext2D}
      *  @memberof Draw */
     export let workReadContext: OffscreenCanvasRenderingContext2D;
+    /** Extra canvas to composite behind the engine canvases when combining canvases
+     *  Set by plugins that render to their own canvas below the LittleJS canvases
+     *  @type {HTMLCanvasElement}
+     *  @memberof Draw */
+    export let backgroundCanvas: HTMLCanvasElement;
     /** The size of the main canvas (and other secondary canvases)
      *  @type {Vector2}
      *  @memberof Draw */
@@ -2050,6 +2066,12 @@ declare module "littlejsengine" {
      *  @param {boolean} [additive]
      *  @memberof Draw */
     export function setAdditiveBlendMode(additive?: boolean): void;
+    /** Set an extra canvas to composite behind the engine canvases when combining
+     *  Plugins that insert their own canvas below the LittleJS canvases should set
+     *  this so it appears in screenshots and video capture
+     *  @param {HTMLCanvasElement} [canvas]
+     *  @memberof Draw */
+    export function setBackgroundCanvas(canvas?: HTMLCanvasElement): void;
     /** Combines LittleJS canvases onto the main canvas
      *  This is necessary for things like screenshots and video
      *  @memberof Draw */
@@ -2565,11 +2587,29 @@ declare module "littlejsengine" {
         randomness: any;
         /** @property {number} - Sample rate for this sound */
         sampleRate: number;
-        /** @property {number} - Percentage of this sound currently loaded */
+        /** @property {number} - How many samples per channel this sound has */
+        sampleLength: number;
+        /** @property {AudioBuffer} - Decoded audio shared by every play of this sound
+         *  @type {AudioBuffer} */
+        sampleBuffer: AudioBuffer;
+        /** @private @type {Array<Array<number>|Float32Array>} */
+        private _sampleChannels;
+        /** @property {number} - Percentage of this sound currently loaded, sounds
+         *  fetched from a url stay at 0 until decoding completes */
         loadedPercent: number;
         /** @property {SoundLoadCallback} - function to call when sound is loaded */
         onloadCallback: (sound: Sound) => Sound;
-        sampleChannels: any[][];
+        /** @param {Array<Array<number>|Float32Array>} sampleChannels */
+        set sampleChannels(arg: (number[] | Float32Array)[]);
+        /** Sample data for each channel
+         *  Sounds keep their samples in an audio buffer, so reading this rebuilds
+         *  the arrays from it and caches them. The copies are safe to hold onto,
+         *  playing a sound detaches the buffer's own channel arrays.
+         *  @type {Array<Array<number>|Float32Array>} */
+        get sampleChannels(): (number[] | Float32Array)[];
+        /** Move this sound's samples into an audio buffer that every play can share
+         *  Does nothing if there is already a buffer or no samples to build one from */
+        buildSampleBuffer(): void;
         /** Play the sound
          *  Sounds may not play until a user interaction occurs
          *  @param {Vector2} [pos] - World space position to play the sound if any
@@ -2722,6 +2762,25 @@ declare module "littlejsengine" {
      *  @return {AudioBufferSourceNode} - The source node of the sound played, may be undefined if play fails
      *  @memberof Audio */
     export function playSamples(sampleChannels: any[], volume?: number, rate?: number, pan?: number, loop?: boolean, sampleRate?: number, gainNode?: GainNode, offset?: number, onended?: AudioEndedCallback): AudioBufferSourceNode;
+    /** Play an audio buffer with given settings
+     *  The buffer can be shared by any number of sounds playing at once
+     *  @param {AudioBuffer} buffer - The audio buffer to play
+     *  @param {number}   [volume] - How much to scale volume by
+     *  @param {number}   [rate] - The playback rate to use
+     *  @param {number}   [pan] - How much to apply stereo panning
+     *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
+     *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
+     *  @param {number}   [offset] - Offset in seconds to start playback from
+     *  @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 */
+    export function playAudioBuffer(buffer: AudioBuffer, volume?: number, rate?: number, pan?: number, loop?: boolean, gainNode?: GainNode, offset?: number, onended?: AudioEndedCallback): AudioBufferSourceNode;
+    /** Copy arrays of samples into a new audio buffer
+     *  @param {Array}  sampleChannels - Array of arrays of samples (for stereo playback)
+     *  @param {number} [sampleRate=44100] - Sample rate for the sound
+     *  @return {AudioBuffer} - The audio buffer holding the samples
+     *  @memberof Audio */
+    export function createAudioBuffer(sampleChannels: any[], sampleRate?: number): AudioBuffer;
     /** Generate and play a ZzFX sound
      *
      *  <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>

package/dist/littlejs.esm.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.26';
+const engineVersion = '1.18.28';
 
 /** Frames per second to update
  *  @type {number}
@@ -3037,6 +3037,14 @@ let gamepadsEnable = true;
  *  @memberof Settings */
 let gamepadDirectionEmulateStick = true;
 
+/** If true, axes that do not rest near center are ignored on gamepads without
+ *  standard mapping. Steering wheels and flight sticks report pedal and throttle
+ *  axes that rest at full deflection, which otherwise reads as a stick held down.
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let gamepadAxisFilterEnable = true;
+
 /** If true the WASD keys are also routed to the direction keys (for better accessibility)
  *  @type {boolean}
  *  @default
@@ -3375,6 +3383,11 @@ function setGamepadsEnable(enable) { gamepadsEnable = enable; }
  *  @memberof Settings */
 function setGamepadDirectionEmulateStick(enable) { gamepadDirectionEmulateStick = enable; }
 
+/** Set if axes that do not rest near center are ignored on non-standard gamepads
+ *  @param {boolean} enable
+ *  @memberof Settings */
+function setGamepadAxisFilterEnable(enable) { gamepadAxisFilterEnable = enable; }
+
 /** Set if true the WASD keys are also routed to the direction keys
  *  @param {boolean} enable
  *  @memberof Settings */
@@ -4119,6 +4132,12 @@ let workReadCanvas;
  *  @memberof Draw */
 let workReadContext;
 
+/** Extra canvas to composite behind the engine canvases when combining canvases
+ *  Set by plugins that render to their own canvas below the LittleJS canvases
+ *  @type {HTMLCanvasElement}
+ *  @memberof Draw */
+let backgroundCanvas;
+
 /** The size of the main canvas (and other secondary canvases)
  *  @type {Vector2}
  *  @memberof Draw */
@@ -5270,6 +5289,13 @@ function setAdditiveBlendMode(additive=true)
     drawContext.globalCompositeOperation = additive ? 'lighter' : 'source-over';
 }
 
+/** Set an extra canvas to composite behind the engine canvases when combining
+ *  Plugins that insert their own canvas below the LittleJS canvases should set
+ *  this so it appears in screenshots and video capture
+ *  @param {HTMLCanvasElement} [canvas]
+ *  @memberof Draw */
+function setBackgroundCanvas(canvas) { backgroundCanvas = canvas; }
+
 /** Combines LittleJS canvases onto the main canvas
  *  This is necessary for things like screenshots and video
  *  @memberof Draw */
@@ -5282,6 +5308,8 @@ function combineCanvases()
     // leaving workContext.fillStyle transparent can't silently no-op this
     workContext.fillStyle = '#000';
     workContext.fillRect(0,0,w,h);
+    if (backgroundCanvas)
+        workContext.drawImage(backgroundCanvas, 0, 0, w, h);
     glCopyToContext(workContext);
     workContext.drawImage(mainCanvas, 0, 0);
     mainContext.drawImage(workCanvas, 0, 0);
@@ -5680,6 +5708,7 @@ function inputClear()
     touchGamepadStickPointerId.length = 0; // release floating sticks so they re-anchor
     gamepadStickData.length = 0;
     gamepadDpadData.length = 0;
+    gamepadAxisCentered.length = 0;
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5917,6 +5946,11 @@ const inputData = [[]];
 
 // gamepad internal variables
 const gamepadStickData = [], gamepadDpadData = [], gamepadHadInput = [];
+// per gamepad, how many consecutive frames each axis has rested inside the
+// dead zone, used to tell stick axes from axes that rest at full deflection
+const gamepadAxisCentered = [];
+// how long an axis must rest inside the dead zone before it counts as a stick
+const gamepadAxisCenteredFrames = 15;
 
 // touch gamepad internal variables
 const touchGamepadTimer = new Timer, touchGamepadButtons = [], touchGamepadSticks = [];
@@ -6165,7 +6199,7 @@ function inputUpdate()
         // gamepad: any button held or stick moved
         let gamepadActive = false;
         for (let s = gamepadStickCount(); s-- && !gamepadActive;)
-            gamepadActive = gamepadStick(s).lengthSquared() > .04;
+            gamepadActive = gamepadStick(s).lengthSquared() > .2;
         for (let b = 17; b-- && !gamepadActive;)
             gamepadActive = gamepadIsDown(b);
 
@@ -6193,12 +6227,12 @@ function inputUpdate()
     // gamepads are updated by engine every frame automatically
     function gamepadsUpdate()
     {
+        const deadZoneMin=.3, deadZoneMax=.8;
         const applyDeadZones = (v)=>
         {
-            const min=.3, max=.8;
             const deadZone = (v)=>
-                v > min ? percent(v, min, max) :
-                v < -min ? -percent(-v, min, max) : 0;
+                v > deadZoneMin ? percent(v, deadZoneMin, deadZoneMax) :
+                v < -deadZoneMin ? -percent(-v, deadZoneMin, deadZoneMax) : 0;
             return vec2(deadZone(v.x), deadZone(-v.y)).clampLength();
         };
 
@@ -6282,6 +6316,7 @@ function inputUpdate()
                 gamepadStickData[i] = undefined;
                 gamepadDpadData[i] = undefined;
                 gamepadHadInput[i] = undefined;
+                gamepadAxisCentered[i] = undefined;
                 continue;
             }
 
@@ -6290,8 +6325,30 @@ function inputUpdate()
             const dpad = gamepadDpadData[i] ?? (gamepadDpadData[i] = vec2());
 
             // read analog sticks
+            // gamepads without standard mapping (steering wheels, flight sticks)
+            // can report axes that rest at full deflection instead of center,
+            // which would otherwise read as a stick held down forever, so only
+            // trust an axis once it has rested inside the dead zone for a moment
+            const isStandard = gamepad.mapping === 'standard';
+            const centered = gamepadAxisCentered[i] ?? (gamepadAxisCentered[i] = []);
+            const readAxis = (j)=>
+            {
+                const v = gamepad.axes[j];
+                if (isStandard && j < 4)
+                    return v; // spec guarantees axes 0-3 are the two sticks
+                if (!gamepadAxisFilterEnable)
+                    return v;
+
+                // once an axis has proven it rests at center it stays trusted,
+                // otherwise moving it would immediately disqualify it again
+                const frames = centered[j] | 0;
+                if (frames > gamepadAxisCenteredFrames)
+                    return v;
+                centered[j] = abs(v) < deadZoneMin ? frames + 1 : 0;
+                return 0;
+            };
             for (let j = 0; j < gamepad.axes.length-1; j+=2)
-                sticks[j>>1] = applyDeadZones(vec2(gamepad.axes[j],gamepad.axes[j+1]));
+                sticks[j>>1] = applyDeadZones(vec2(readAxis(j), readAxis(j+1)));
 
             // read buttons
             let hadInput = false;
@@ -6917,7 +6974,15 @@ class Sound
         this.randomness = randomness ?? 0;
         /** @property {number} - Sample rate for this sound */
         this.sampleRate = audioDefaultSampleRate;
-        /** @property {number} - Percentage of this sound currently loaded */
+        /** @property {number} - How many samples per channel this sound has */
+        this.sampleLength = 0;
+        /** @property {AudioBuffer} - Decoded audio shared by every play of this sound
+         *  @type {AudioBuffer} */
+        this.sampleBuffer = undefined;
+        /** @private @type {Array<Array<number>|Float32Array>} */
+        this._sampleChannels = undefined;
+        /** @property {number} - Percentage of this sound currently loaded, sounds
+         *  fetched from a url stay at 0 until decoding completes */
         this.loadedPercent = 0;
         /** @property {SoundLoadCallback} - function to call when sound is loaded */
         this.onloadCallback = onloadCallback;
@@ -6933,8 +6998,10 @@ class Sound
             this.randomness = zzfxSound[randomnessIndex] ?? defaultRandomness;
             zzfxSound[randomnessIndex] = 0;
 
-            // generate the zzfx samples
+            // generate the zzfx samples, then hand them to an audio buffer so
+            // the plain arrays can be released and every play shares the buffer
             this.sampleChannels = [zzfxG(...zzfxSound)];
+            this.buildSampleBuffer();
             this.loadedPercent = 1;
             onloadCallback?.(this);
         }
@@ -6946,6 +7013,45 @@ class Sound
         }
     }
 
+    /** Sample data for each channel
+     *  Sounds keep their samples in an audio buffer, so reading this rebuilds
+     *  the arrays from it and caches them. The copies are safe to hold onto,
+     *  playing a sound detaches the buffer's own channel arrays.
+     *  @type {Array<Array<number>|Float32Array>} */
+    get sampleChannels()
+    {
+        const buffer = this.sampleBuffer;
+        if (!this._sampleChannels && buffer)
+        {
+            const channels = [];
+            for (let i = 0; i < buffer.numberOfChannels; i++)
+                channels.push(buffer.getChannelData(i).slice());
+            this._sampleChannels = channels;
+        }
+        return this._sampleChannels;
+    }
+
+    /** @param {Array<Array<number>|Float32Array>} sampleChannels */
+    set sampleChannels(sampleChannels)
+    {
+        // new samples invalidate the buffer built from the old ones
+        this._sampleChannels = sampleChannels;
+        this.sampleBuffer = undefined;
+        this.sampleLength = sampleChannels?.[0]?.length || 0;
+    }
+
+    /** Move this sound's samples into an audio buffer that every play can share
+     *  Does nothing if there is already a buffer or no samples to build one from */
+    buildSampleBuffer()
+    {
+        if (this.sampleBuffer || !this._sampleChannels || headlessMode) return;
+
+        this.sampleBuffer = createAudioBuffer(this._sampleChannels, this.sampleRate);
+
+        // the buffer owns the samples now, release the arrays we built it from
+        this._sampleChannels = undefined;
+    }
+
     /** Play the sound
      *  Sounds may not play until a user interaction occurs
      *  @param {Vector2} [pos] - World space position to play the sound if any
@@ -6964,7 +7070,7 @@ class Sound
         ASSERT(isNumber(randomnessScale), 'randomnessScale must be a number');
 
         if (!soundEnable || headlessMode) return;
-        if (!this.sampleChannels) return;
+        if (!this.sampleBuffer && !this._sampleChannels) return;
 
         let pan;
         if (pos)
@@ -7031,7 +7137,7 @@ class Sound
      *  @return {number} - How long the sound is in seconds (0 if loading)
      */
     getDuration()
-    { return this.sampleChannels?.[0]?.length / this.sampleRate || 0; }
+    { return this.sampleLength / this.sampleRate || 0; }
 
     /** Check if sound is loaded, for sounds fetched from a url
      *  @return {boolean} - True if sound is loaded and ready to play
@@ -7049,36 +7155,11 @@ class Sound
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
         
-        // convert audio buffer to sample channels across multiple frames
-        const channelCount = audioBuffer.numberOfChannels;
-        const samplesPerFrame = 1e5;
-        const sampleChannels = [];
-        for (let channel = 0; channel < channelCount; channel++)
-        {
-            const channelData = audioBuffer.getChannelData(channel);
-            const channelLength = channelData.length;
-            sampleChannels[channel] = new Array(channelLength);
-            let sampleIndex = 0;
-            while (sampleIndex < channelLength)
-            {
-                // yield to next frame
-                await new Promise(resolve => setTimeout(resolve, 0));
-
-                // copy chunk of samples
-                const endIndex = min(sampleIndex + samplesPerFrame, channelLength);
-                for (; sampleIndex < endIndex; sampleIndex++)
-                    sampleChannels[channel][sampleIndex] = channelData[sampleIndex];
-
-                // update loaded percent
-                const samplesTotal = channelCount * channelLength;
-                const samplesProcessed = channel * channelLength + sampleIndex;
-                this.loadedPercent = samplesProcessed / samplesTotal;
-            }
-        }
-        
-        // setup the sound to be played
+        // keep the decoded buffer as is, it is exactly what playback needs and
+        // every play shares it, no channel data is read or copied
         this.sampleRate = audioBuffer.sampleRate;
-        this.sampleChannels = sampleChannels;
+        this.sampleLength = audioBuffer.length;
+        this.sampleBuffer = audioBuffer;
         this.loadedPercent = 1;
         this.onloadCallback?.(this);
     }
@@ -7154,7 +7235,12 @@ class SoundInstance
         if (this.isPlaying())
             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);
+
+        // build the shared buffer if it was not made at load time, then play it
+        this.sound.buildSampleBuffer();
+        this.source = this.sound.sampleBuffer ?
+            playAudioBuffer(this.sound.sampleBuffer, this.volume, this.rate, this.pan, this.loop, this.gainNode, offset, this.onendedCallback) :
+            playSamples(this.sound.sampleChannels, this.volume, this.rate, this.pan, this.loop, this.sound.sampleRate, this.gainNode, offset, this.onendedCallback);
         if (this.source)
         {
             this.startTime = audioContext.currentTime - offset;
@@ -7329,19 +7415,54 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
 
     if (!audioIsRunning())
     {
-        // fix stalled audio, this sound won't be able to play
+        // fix stalled audio, don't build a buffer that can't be played
         audioContext.resume();
         return;
     }
 
-    // create buffer and source
+    const buffer = createAudioBuffer(sampleChannels, sampleRate);
+    return playAudioBuffer(buffer, volume, rate, pan, loop, gainNode, offset, onended);
+}
+
+/** Copy arrays of samples into a new audio buffer
+ *  @param {Array}  sampleChannels - Array of arrays of samples (for stereo playback)
+ *  @param {number} [sampleRate=44100] - Sample rate for the sound
+ *  @return {AudioBuffer} - The audio buffer holding the samples
+ *  @memberof Audio */
+function createAudioBuffer(sampleChannels, sampleRate=audioDefaultSampleRate)
+{
     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));
+    return buffer;
+}
+
+/** Play an audio buffer with given settings
+ *  The buffer can be shared by any number of sounds playing at once
+ *  @param {AudioBuffer} buffer - The audio buffer to play
+ *  @param {number}   [volume] - How much to scale volume by
+ *  @param {number}   [rate] - The playback rate to use
+ *  @param {number}   [pan] - How much to apply stereo panning
+ *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
+ *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
+ *  @param {number}   [offset] - Offset in seconds to start playback from
+ *  @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 playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode, offset=0, onended)
+{
+    if (!soundEnable || headlessMode) return;
+
+    if (!audioIsRunning())
+    {
+        // fix stalled audio, this sound won't be able to play
+        audioContext.resume();
+        return;
+    }
+
+    // setup source, many sources can share one buffer
+    const source = audioContext.createBufferSource();
     source.buffer = buffer;
     source.playbackRate.value = rate;
     source.loop = loop;
@@ -16808,6 +16929,9 @@ class ThreeJSPlugin
         rootElement.insertBefore(threeCanvas, rootElement.firstChild);
         threeCanvas.style.cssText = mainCanvas.style.cssText;
 
+        // composite the 3D canvas into screenshots and video capture
+        setBackgroundCanvas(threeCanvas);
+
         // render automatically each frame after the engine renders
         engineAddPlugin(undefined, ()=> this.render());
     }
@@ -16992,6 +17116,7 @@ export
     glCircleSides,
     gamepadsEnable,
     gamepadDirectionEmulateStick,
+    gamepadAxisFilterEnable,
     inputWASDEmulateDirection,
     touchInputEnable,
     touchGamepadEnable,
@@ -17048,6 +17173,7 @@ export
     setTouchInputEnable,
     setGamepadsEnable,
     setGamepadDirectionEmulateStick,
+    setGamepadAxisFilterEnable,
     setInputWASDEmulateDirection,
     setTouchGamepadEnable,
     setTouchGamepadPassthrough,
@@ -17163,6 +17289,7 @@ export
     workContext,
     workReadCanvas,
     workReadContext,
+    backgroundCanvas,
     mainCanvasSize,
     textureInfos,
     drawCount,
@@ -17188,6 +17315,7 @@ export
     drawText,
     drawTextScreen,
     setAdditiveBlendMode,
+    setBackgroundCanvas,
     combineCanvases,
     engineImageFont,
     ImageFont,
@@ -17275,6 +17403,8 @@ export
     speakStop,
     getNoteFrequency,
     playSamples,
+    playAudioBuffer,
+    createAudioBuffer,
     zzfx,
     zzfxG,