littlejsengine 1.13.4 → 1.14.2

package/src/engineAudio.js

@@ -1,4 +1,4 @@
-/** 
+/**
  * LittleJS Audio System
  * - <a href=https://killedbyapixel.github.io/ZzFX/>ZzFX Sound Effects</a> - ZzFX Sound Effect Generator
  * - <a href=https://keithclark.github.io/ZzFXM/>ZzFXM Music</a> - ZzFXM Music System
@@ -21,10 +21,21 @@ let audioContext = new AudioContext;
  *  @memberof Audio */
 let audioMasterGain;
 
+/** Default sample rate used for sounds
+ *  @default 44100
+ *  @memberof Audio */
+const audioDefaultSampleRate = 44100;
+
+/** Check if the audio context is running and available for playback
+ *  @return {boolean} - True if the audio context is running
+ *  @memberof Audio */
+function audioIsRunning()
+{ return audioContext.state === 'running'; }
+
 function audioInit()
 {
     if (!soundEnable || headlessMode) return;
-    
+
     audioMasterGain = audioContext.createGain();
     audioMasterGain.connect(audioContext.destination);
     audioMasterGain.gain.value = soundVolume; // set starting value
@@ -32,14 +43,14 @@ 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>
  * @example
  * // create a sound
  * const sound_example = new Sound([.5,.5]);
- * 
+ *
  * // play the sound
  * sound_example.play();
  */
@@ -56,33 +67,41 @@ class Sound
 
         /** @property {number} - World space max range of sound */
         this.range = range;
-
         /** @property {number} - At what percentage of range should it start tapering */
         this.taper = taper;
-
         /** @property {number} - How much to randomize frequency each time sound plays */
         this.randomness = 0;
+        /** @property {number} - Sample rate for this sound */
+        this.sampleRate = audioDefaultSampleRate;
+        /** @property {number} - Percentage of this sound currently loaded */
+        this.loadedPercent = 0;
 
+        // generate zzfx sound now for fast playback
         if (zzfxSound)
         {
-            // generate zzfx sound now for fast playback
-            const defaultRandomness = .05;
-            this.randomness = zzfxSound[1] != undefined ? zzfxSound[1] : defaultRandomness;
-            zzfxSound[1] = 0; // generate without randomness
+            // remove randomness so it can be applied on playback
+            const randomnessIndex = 1, defaultRandomness = .05;
+            this.randomness = zzfxSound[randomnessIndex] !== undefined ? 
+                zzfxSound[randomnessIndex] : defaultRandomness;
+            zzfxSound[randomnessIndex] = 0;
+
+            // generate the zzfx samples
             this.sampleChannels = [zzfxG(...zzfxSound)];
-            this.sampleRate = zzfxR;
+            this.loadedPercent = 1;
         }
     }
 
     /** Play the sound
-     *  @param {Vector2} [pos] - World space position to play the sound, sound is not attenuated if null
-     *  @param {number}  [volume] - How much to scale volume by (in addition to range fade)
-     *  @param {number}  [pitch] - How much to scale pitch by (also adjusted by this.randomness)
-     *  @param {number}  [randomnessScale] - How much to scale randomness
-     *  @param {boolean} [loop] - Should the sound loop
-     *  @return {AudioBufferSourceNode} - The audio source node
+     *  Sounds may not play until a user interaction occurs
+     *  @param {Vector2} [pos] - World space position to play the sound if any
+     *  @param {number}  [volume] - How much to scale volume by
+     *  @param {number}  [pitch] - How much to scale pitch by
+     *  @param {number}  [randomnessScale] - How much to scale pitch randomness
+     *  @param {boolean} [loop] - Should the sound loop?
+     *  @param {boolean} [paused] - Should the sound start paused
+     *  @return {SoundInstance} - The audio source node
      */
-    play(pos, volume=1, pitch=1, randomnessScale=1, loop=false)
+    play(pos, volume=1, pitch=1, randomnessScale=1, loop=false, paused=false)
     {
         if (!soundEnable || headlessMode) return;
         if (!this.sampleChannels) return;
@@ -105,75 +124,55 @@ class Sound
             // get pan from screen space coords
             pan = worldToScreen(pos).x * 2/mainCanvas.width - 1;
         }
-
-        // play the sound
-        const playbackRate = pitch + pitch * this.randomness*randomnessScale*rand(-1,1);
-        this.gainNode = audioContext.createGain();
-        this.source = playSamples(this.sampleChannels, volume, playbackRate, pan, loop, this.sampleRate, this.gainNode);
-        return this.source;
-    }
-
-    /** Set the sound volume of the most recently played instance of this sound
-     *  @param {number}  [volume] - How much to scale volume by
-     */
-    setVolume(volume=1)
-    {
-        if (this.gainNode)
-            this.gainNode.gain.value = volume;
-    }
-
-    /** Stop the last instance of this sound that was played
-     *  @param {number}  [fadeTime] - How long to fade out (seconds)
-     */
-    stop(fadeTime=0)
-    {
-        if (!this.source)
-            return;
         
-        // ramp off gain
-        const startFade = audioContext.currentTime;
-        const endFade = startFade + fadeTime;
-        this.gainNode.gain.linearRampToValueAtTime(1, startFade);
-        this.gainNode.gain.linearRampToValueAtTime(0, endFade);
-        this.source.stop(endFade);
-        this.source = undefined;
+        // Create and return sound instance
+        const rate = pitch + pitch * this.randomness*randomnessScale*rand(-1,1);
+        return new SoundInstance(this, volume, rate, pan, loop, paused);
     }
     
-    /** Get source of most recent instance of this sound that was played
-     *  @return {AudioBufferSourceNode}
+    /** Play a music track that loops by default
+     *  @param {number} [volume] - Volume to play the music at
+     *  @param {boolean} [loop] - Should the music loop?
+     *  @param {boolean} [paused] - Should the music start paused
+     *  @return {SoundInstance} - The audio source node
      */
-    getSource() { return this.source; }
+    playMusic(volume=1, loop=true, paused=false)
+    { return this.play(undefined, volume, 1, 0, loop, paused); }
 
-    /** Play the sound as a note with a semitone offset
+    /** 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 {Vector2} [pos] - World space position to play the sound, sound is not attenuated if null
-     *  @param {number}  [volume=1] - How much to scale volume by (in addition to range fade)
-     *  @return {AudioBufferSourceNode} - The audio source node
+     *  @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)
-    { return this.play(pos, volume, 2**(semitoneOffset/12), 0); }
+    {
+        const pitch = getNoteFrequency(semitoneOffset, 1);
+        return this.play(pos, volume, pitch, 0);
+    }
 
     /** Get how long this sound is in seconds
      *  @return {number} - How long the sound is in seconds (undefined if loading)
      */
-    getDuration() 
+    getDuration()
     { return this.sampleChannels && this.sampleChannels[0].length / this.sampleRate; }
-    
-    /** Check if sound is loading, for sounds fetched from a url
-     *  @return {boolean} - True if sound is loading and not ready to play
+
+    /** Check if sound is loaded, for sounds fetched from a url
+     *  @return {boolean} - True if sound is loaded and ready to play
      */
-    isLoading() { return !this.sampleChannels; }
+    isLoaded() { return this.loadedPercent === 1; }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 
-/** 
+/**
  * 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
  * @example
  * // create a sound
  * const sound_example = new SoundWave('sound.mp3');
- * 
+ *
  * // play the sound
  * sound_example.play();
  */
@@ -205,26 +204,202 @@ class SoundWave extends Sound
         const response = await fetch(filename);
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
-        this.sampleChannels = [];
-        for (let i = audioBuffer.numberOfChannels; i--;)
-            this.sampleChannels[i] = Array.from(audioBuffer.getChannelData(i));
+        
+        // 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
         this.sampleRate = audioBuffer.sampleRate;
+        this.sampleChannels = sampleChannels;
+        this.loadedPercent = 1;
         if (this.onloadCallback)
             this.onloadCallback();
     }
 }
 
-/** Play an mp3, ogg, or wav audio from a local file or url
- *  @param {string}  filename - Location of sound file to play
- *  @param {number}  [volume] - How much to scale volume by
- *  @param {boolean} [loop] - True if the music should loop
- *  @return {SoundWave} - The sound object for this file
- *  @memberof Audio */
-function playAudioFile(filename, volume=1, loop=false)
+///////////////////////////////////////////////////////////////////////////////
+
+/** 
+ * Sound Instance - Wraps an AudioBufferSourceNode for individual sound control
+ * Represents a single playing instance of a sound with pause/resume capabilities
+ * @example
+ * // Play a sound and get an instance for control
+ * const jumpSound = new Sound([.5,.5,220]);
+ * const instance = jumpSound.play();
+ * 
+ * // Control the individual instance
+ * instance.setVolume(.5);
+ * instance.pause();
+ * instance.unpause();
+ * instance.stop();
+ */
+class SoundInstance
 {
-    if (!soundEnable || headlessMode) return;
+    /** Create a sound instance
+     *  @param {Sound}    sound    - The sound object
+     *  @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]   - Should the sound loop?
+     *  @param {boolean}  [paused] - Should the sound start paused? */
+    constructor(sound, volume=1, rate=1, pan=0, loop=false, paused=false)
+    {
+        ASSERT(sound instanceof Sound, 'SoundInstance requires a valid Sound object');
+        ASSERT(volume >= 0, 'Sound volume must be positive or zero');
+        ASSERT(rate >= 0, 'Sound rate must be positive or zero');
+        ASSERT(isNumber(pan), 'Sound pan must be a number');
+
+        /** @property {Sound} - The sound object */
+        this.sound = sound;
+        /** @property {number} - How much to scale volume by */
+        this.volume = volume;
+        /** @property {number} - The playback rate to use */
+        this.rate = rate;
+        /** @property {number} - How much to apply stereo panning */
+        this.pan = pan;
+        /** @property {boolean} - Should the sound loop */
+        this.loop = loop;
+        /** @property {number} - Timestamp for audio context when paused */
+        this.pausedTime = 0;
+        /** @property {number} - Timestamp for audio context when started */
+        this.startTime = undefined;
+        /** @property {GainNode} - Gain node for the sound */
+        this.gainNode = undefined;
+        /** @property {AudioBufferSourceNode} - Source node of the audio */
+        this.source = undefined;
+        // setup end callback and start sound
+        this.onendedCallback = (source)=>
+        {
+            if (source === this.source)
+                this.source = undefined;
+        };
+        if (!paused)
+            this.start();
+    }
+
+    /** Start playing the sound instance from the offset time
+     *  @param {number} [offset] - Offset in seconds to start playback from 
+     */
+    start(offset=0)
+    {
+        ASSERT(offset >= 0, 'Sound start offset must be positive or zero');
+        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);
+        this.startTime = audioContext.currentTime - offset;
+        this.pausedTime = undefined;
+    }
+
+    /** Set the volume of this sound instance
+     *  @param {number} volume */
+    setVolume(volume)
+    {
+        ASSERT(volume >= 0, 'Sound volume must be positive or zero');
+        this.volume = volume;
+        if (this.gainNode)
+            this.gainNode.gain.value = volume;
+    }
+
+    /** Stop this sound instance and reset position to the start */
+    stop(fadeTime=0)
+    {
+        ASSERT(fadeTime >= 0, 'Sound fade time must be positive or zero');
+        if (this.isPlaying())
+        {
+            if (fadeTime)
+            {
+                // ramp off gain
+                const startFade = audioContext.currentTime;
+                const endFade = startFade + fadeTime;
+                this.gainNode.gain.linearRampToValueAtTime(1, startFade);
+                this.gainNode.gain.linearRampToValueAtTime(0, endFade);
+                this.source.stop(endFade);
+            }
+            else
+                this.source.stop();
+        }
+        this.pausedTime = 0;
+        this.source = undefined;
+        this.startTime = undefined;
+    }
+
+    /** Pause this sound instance */
+    pause()
+    {
+        if (this.isPaused())
+            return;
+
+        // save current time and stop sound
+        this.pausedTime = this.getCurrentTime();
+        this.source.stop();
+        this.source = undefined;
+        this.startTime = undefined;
+    }
 
-    return new SoundWave(filename,0,0,0, s=>s.play(undefined, volume, 1, 1, loop));
+    /** Unpauses this sound instance */
+    resume()
+    {
+        if (!this.isPaused())
+            return;
+        
+        // restart sound from paused time
+        this.start(this.pausedTime);
+    }
+
+    /** Check if this instance is currently playing
+     *  @return {boolean} - True if playing
+     */
+    isPlaying() { return !!this.source; }
+
+    /** Check if this instance is paused and was not stopped
+     *  @return {boolean} - True if paused
+     */
+    isPaused() { return !this.isPlaying(); }
+
+    /** Get the current playback time in seconds
+     *  @return {number} - Current playback time
+     */
+    getCurrentTime()
+    {
+        const deltaTime = mod(audioContext.currentTime - this.startTime, 
+            this.getDuration());
+        return this.isPlaying() ? deltaTime : this.pausedTime;
+    }
+
+    /** Get the total duration of this sound
+     *  @return {number} - Total duration in seconds
+     */
+    getDuration() { return this.sound.getDuration() / this.rate; }
+
+    /** Get source of this sound instance
+     *  @return {AudioBufferSourceNode}
+     */
+    getSource() { return this.source; }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -278,9 +453,11 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
  *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
  *  @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
  *  @memberof Audio */
-function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=zzfxR, gainNode) 
+function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=audioDefaultSampleRate, gainNode, offset=0, onended)
 {
     if (!soundEnable || headlessMode) return;
 
@@ -305,16 +482,20 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
     const pannerNode = new StereoPannerNode(audioContext, {'pan':clamp(pan, -1, 1)});
     source.connect(pannerNode).connect(gainNode);
 
-    // play the sound
-    if (audioContext.state != 'running')
+    // callback when the sound ends
+    if (onended)
+        source.addEventListener('ended', ()=> onended(source));
+
+    if (!audioIsRunning())
     {
-        // fix stalled audio and play
-        audioContext.resume().then(()=>source.start());
+        // fix stalled audio, this sound won't be able to play
+        audioContext.resume();
+        return;
     }
-    else
-        source.start();
 
-    // return sound
+    // play and return sound
+    const startOffset = offset * rate;
+    source.start(0, startOffset);
     return source;
 }
 
@@ -322,18 +503,13 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
 // ZzFXMicro - Zuper Zmall Zound Zynth - v1.3.2 by Frank Force
 
 /** Generate and play a ZzFX sound
- *  
+ *
  *  <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
  *  @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 playSamples([zzfxG(...zzfxSound)]); }
 
-/** Sample rate used for all ZzFX sounds
- *  @default 44100
- *  @memberof Audio */
-const zzfxR = 44100; 
-
 /** Generate samples for a ZzFX sound
  *  @param {number}  [volume] - Volume scale (percent)
  *  @param {number}  [randomness] - How much to randomize frequency (percent Hz)
@@ -357,11 +533,10 @@ const zzfxR = 44100;
  *  @param {number}  [tremolo] - Trembling effect, rate controlled by repeat time (percent)
  *  @param {number}  [filter] - Filter cutoff frequency, positive for HPF, negative for LPF (Hz)
  *  @return {Array} - Array of audio samples
- *  @memberof Audio
- */
+ *  @memberof Audio */
 function zzfxG
 (
-    volume = 1, 
+    volume = 1,
     randomness = .05,
     frequency = 220,
     attack = 0,
@@ -369,11 +544,11 @@ function zzfxG
     release = .1,
     shape = 0,
     shapeCurve = 1,
-    slide = 0, 
-    deltaSlide = 0, 
-    pitchJump = 0, 
-    pitchJumpTime = 0, 
-    repeatTime = 0, 
+    slide = 0,
+    deltaSlide = 0,
+    pitchJump = 0,
+    pitchJumpTime = 0,
+    repeatTime = 0,
     noise = 0,
     modulation = 0,
     bitCrush = 0,
@@ -385,19 +560,19 @@ function zzfxG
 )
 {
     // init parameters
-    let sampleRate = zzfxR,
-        PI2 = PI*2, 
+    let sampleRate = audioDefaultSampleRate,
+        PI2 = PI*2,
         startSlide = slide *= 500 * PI2 / sampleRate / sampleRate,
-        startFrequency = frequency *= 
+        startFrequency = frequency *=
             (1 + rand(randomness,-randomness)) * PI2 / sampleRate,
-        modOffset = 0, // modulation offset  
+        modOffset = 0, // modulation offset
         repeat = 0,    // repeat offset
         crush = 0,     // bit crush offset
         jump = 1,      // pitch jump timer
         length,        // sample length
         b = [],        // sample buffer
         t = 0,         // sample time
-        i = 0,         // sample index 
+        i = 0,         // sample index
         s = 0,         // sample value
         f,             // wave frequency
 
@@ -405,7 +580,7 @@ function zzfxG
         quality = 2, w = PI2 * abs(filter) * 2 / sampleRate,
         cos = Math.cos(w), alpha = Math.sin(w) / 2 / quality,
         a0 = 1 + alpha, a1 = -2*cos / a0, a2 = (1 - alpha) / a0,
-        b0 = (1 + sign(filter) * cos) / 2 / a0, 
+        b0 = (1 + sign(filter) * cos) / 2 / a0,
         b1 = -(sign(filter) + cos) / a0, b2 = b0,
         x2 = 0, x1 = 0, y2 = 0, y1 = 0;
 
@@ -451,7 +626,7 @@ function zzfxG
                 0);                                      // post release
 
             s = delay ? s/2 + (delay > i ? 0 :           // delay
-                (i<length-delay? 1 : (length-i)/delay) * // release delay 
+                (i<length-delay? 1 : (length-i)/delay) * // release delay
                 b[i-delay|0]/2/volume) : s;              // sample delay
 
             if (filter)                                  // apply filter
@@ -463,14 +638,14 @@ function zzfxG
         t += f + f*noise*Math.sin(i**5);        // noise
 
         if (jump && ++jump > pitchJumpTime)     // pitch jump
-        { 
+        {
             frequency += pitchJump;             // apply pitch jump
             startFrequency += pitchJump;        // also apply to start
             jump = 0;                           // stop pitch jump time
-        } 
+        }
 
         if (repeatTime && !(++repeat % repeatTime)) // repeat
-        { 
+        {
             frequency = startFrequency;   // reset frequency
             slide = startSlide;           // reset slide
             jump ||= 1;                   // reset pitch jump time

package/src/engineBuild.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-/** 
+/**
  * LittleJS Build System
  * - Combine input files
  * - Run custom build steps
@@ -76,8 +76,8 @@ Build
     `${BUILD_FOLDER}/${ENGINE_NAME}.js`,
     [
         `${SOURCE_FOLDER}/engine.js`,
-        `${SOURCE_FOLDER}/engineDebug.js`, 
-        ...engineSourceFiles, 
+        `${SOURCE_FOLDER}/engineDebug.js`,
+        ...engineSourceFiles,
         ...enginePluginFiles
     ],
     [], true
@@ -89,8 +89,8 @@ Build
     `${BUILD_FOLDER}/${ENGINE_NAME}.release.js`,
     [
         `${SOURCE_FOLDER}/engine.js`,
-        `${SOURCE_FOLDER}/engineRelease.js`, 
-        ...engineSourceFiles, 
+        `${SOURCE_FOLDER}/engineRelease.js`,
+        ...engineSourceFiles,
         ...enginePluginFiles
     ],
     [], true
@@ -109,8 +109,8 @@ Build
     'Build Engine -- ESM',
     `${BUILD_FOLDER}/${ENGINE_NAME}.esm.js`,
     [
-        `${BUILD_FOLDER}/${ENGINE_NAME}.js`, 
-        `${SOURCE_FOLDER}/engineExport.js`, 
+        `${BUILD_FOLDER}/${ENGINE_NAME}.js`,
+        `${SOURCE_FOLDER}/engineExport.js`,
         `${PLUGIN_FOLDER}/pluginExport.js`
     ],
     [typeScriptBuildStep]
@@ -121,8 +121,8 @@ Build
     'Build Engine -- ESM minified release',
     `${BUILD_FOLDER}/${ENGINE_NAME}.esm.min.js`,
     [
-        `${BUILD_FOLDER}/${ENGINE_NAME}.release.js`, 
-        `${SOURCE_FOLDER}/engineExport.js`, 
+        `${BUILD_FOLDER}/${ENGINE_NAME}.release.js`,
+        `${SOURCE_FOLDER}/engineExport.js`,
         `${PLUGIN_FOLDER}/pluginExport.js`
     ],
     [uglifyBuildStep, addLicenseStep]