littlejsengine 1.16.2 → 1.17.5

package/src/engineAudio.js

@@ -44,29 +44,46 @@ function audioInit()
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * Sound Object - Stores a sound for later use and can be played positionally
+ * Sound Object - Stores a sound for later
+ * - this can be used to load and play wave, mp3, and ogg files
+ * - it can also create sounds using the ZzFX sound generator
+ * - can attenuate and apply stereo panning to sounds
+ * - sound instance control with pause/resume capability
  *
  * <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
  * @memberof Audio
  * @example
- * // create a sound
+ * // load an audio asset file
+ * const sound_example = new Sound('sound.mp3');
+ *
+ * // create a zzfx sound
  * const sound_example = new Sound([.5,.5]);
  *
- * // play the sound
+ * // play a sound
  * sound_example.play();
  */
 class Sound
 {
-    /** Create a sound object and cache the zzfx samples for later use
-     *  @param {Array}  zzfxSound - Array of zzfx parameters, ex. [.5,.5]
+    /**
+     * @callback SoundLoadCallback - Function called when sound is loaded
+     * @param {Sound} sound
+     * @memberof Audio
+     */
+    
+    /** Create a sound object and cache the audio for later use
+     *  @param {string|Array} [asset] - Filename of audio file or zzfx array
+     *  @param {number} [randomness] - How much to randomize frequency each time sound plays, for zzfx sounds the zzfx default is used if undefined
      *  @param {number} [range=soundDefaultRange] - World space max range of sound
      *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
+     *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
      */
-    constructor(zzfxSound, range=soundDefaultRange, taper=soundDefaultTaper)
+    constructor(asset, randomness, range=soundDefaultRange, taper=soundDefaultTaper, onloadCallback)
     {
         if (!soundEnable || headlessMode) return;
 
-        ASSERT(!zzfxSound || isArray(zzfxSound), 'zzfxSound is invalid');
+        ASSERT(!asset || isArray(asset) || isString(asset), 'asset must be a file name or zzfx array');
+        ASSERT(randomness === undefined || isNumber(randomness), 'randomness must be a number');
+        ASSERT(randomness === undefined || randomness >= 0 && randomness <=1, 'randomness must be between 0 and 1');
         ASSERT(isNumber(range), 'range must be a number');
         ASSERT(isNumber(taper), 'taper must be a number');
 
@@ -75,24 +92,35 @@ class Sound
         /** @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;
+        this.randomness = randomness ?? 0;
         /** @property {number} - Sample rate for this sound */
         this.sampleRate = audioDefaultSampleRate;
         /** @property {number} - Percentage of this sound currently loaded */
         this.loadedPercent = 0;
+        /** @property {SoundLoadCallback} - function to call when sound is loaded */
+        this.onloadCallback = onloadCallback;
 
-        // generate zzfx sound now for fast playback
-        if (zzfxSound)
+        if (Array.isArray(asset))
         {
+            // generate zzfx sound
+            const zzfxSound = asset;
+
             // remove randomness so it can be applied on playback
-            const randomnessIndex = 1, defaultRandomness = .05;
-            this.randomness = zzfxSound[randomnessIndex] !== undefined ? 
-                zzfxSound[randomnessIndex] : defaultRandomness;
+            const defaultRandomness = randomness ?? .05;
+            const randomnessIndex = 1;
+            this.randomness = zzfxSound[randomnessIndex] ?? defaultRandomness;
             zzfxSound[randomnessIndex] = 0;
 
             // generate the zzfx samples
             this.sampleChannels = [zzfxG(...zzfxSound)];
             this.loadedPercent = 1;
+            onloadCallback?.(this);
+        }
+        else if (typeof asset === 'string')
+        {
+            // load the audio file
+            const filename = asset;
+            this.loadSound(filename);
         }
     }
 
@@ -144,7 +172,7 @@ class Sound
      *  @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
+     *  @return {SoundInstance} - The sound instance
      */
     playMusic(volume=1, loop=true, paused=false)
     { return this.play(undefined, volume, 1, 0, loop, paused); }
@@ -154,7 +182,7 @@ class Sound
      *  @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
+     *  @return {SoundInstance} - The sound instance
      */
     playNote(semitoneOffset=0, pos, volume)
     {
@@ -167,57 +195,14 @@ class Sound
      *  @return {number} - How long the sound is in seconds (undefined if loading)
      */
     getDuration()
-    { return this.sampleChannels && this.sampleRate ? this.sampleChannels[0].length / this.sampleRate : 0; }
+    { return this.sampleChannels?.[0]?.length / 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
      */
     isLoaded() { return this.loadedPercent === 1; }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-/**
- * Sound Wave Object - Loads and stores an audio file for later use
- * - this can be used to load and play wave, mp3, and ogg files
- * @extends Sound
- * @memberof Audio
- * @example
- * // load an audio asset file
- * const sound_example = new SoundWave('sound.mp3');
- *
- * // play the sound
- * sound_example.play();
- */
-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 {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');
-        ASSERT(isNumber(randomness), 'randomness must be a number');
-
-        /** @property {SoundLoadCallback} - callback function to call when sound is loaded */
-        this.onloadCallback = onloadCallback;
-        this.randomness = randomness;
-        filename && this.loadSound(filename);
-    }
-
-    /** Loads a sound from a URL and decodes it into sample data. Must be used with await!
+    /** Loads a sound from a URL and decodes it into sample data.
     *  @param {string} filename
     *  @return {Promise<void>} */
     async loadSound(filename)
@@ -259,8 +244,7 @@ class SoundWave extends Sound
         this.sampleRate = audioBuffer.sampleRate;
         this.sampleChannels = sampleChannels;
         this.loadedPercent = 1;
-        if (this.onloadCallback)
-            this.onloadCallback(this);
+        this.onloadCallback?.(this);
     }
 }
 
@@ -463,7 +447,7 @@ function speak(text, language='', volume=1, rate=1, pitch=1)
 
 /** Stop all queued speech
  *  @memberof Audio */
-function speakStop() {speechSynthesis && speechSynthesis.cancel();}
+function speakStop() {speechSynthesis?.cancel();}
 
 /** Get frequency of a note on a musical scale
  *  @param {number} semitoneOffset - How many semitones away from the root note

package/src/engineDebug.js

@@ -49,7 +49,7 @@ let debugPrimitives = [], debugPhysics = false, debugRaycast = false, debugParti
 /** 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
+ *  @param {...Object} output - error message output
  *  @memberof Debug */
 function ASSERT(assert, ...output)
 {
@@ -59,13 +59,13 @@ function ASSERT(assert, ...output)
 }
 
 /** Log to console if debug is enabled, does nothing in release builds
- *  @param {...Object} [output] - message output
+ *  @param {...Object} output - message output
  *  @memberof Debug */
 function LOG(...output) { console.log(...output); }
 
 /** Draw a debug rectangle in world space
  *  @param {Vector2} pos
- *  @param {Vector2} [size=Vector2()]
+ *  @param {Vector2} [size=vec2(0)]
  *  @param {Color|string} [color]
  *  @param {number} [time]
  *  @param {number} [angle]
@@ -389,7 +389,7 @@ function debugRender()
         if (tileCollisionTest(mousePos))
         {
             // show floored tile pick for tile collision
-            drawRect(mousePos.floor().add(vec2(.5)), vec2(1), rgb(1,1,0,.5));
+            drawRect(mousePos.floor().add(vec2(.5)), vec2(1), rgb(1,1,0,.5), 0, false);
         }
     }
 
@@ -468,8 +468,8 @@ function debugRender()
     if (debugObject)
     {
         const raycastHitPos = tileCollisionRaycast(debugObject.pos, mousePos);
-        raycastHitPos && drawRect(raycastHitPos.floor().add(vec2(.5)), vec2(1), rgb(0,1,1,.3));
-        drawLine(mousePos, debugObject.pos, .1, raycastHitPos ? rgb(1,0,0,.5) : rgb(0,1,0,.5));
+        raycastHitPos && drawRect(raycastHitPos.floor().add(vec2(.5)), vec2(1), rgb(0,1,1,.3), 0, false);
+        drawLine(mousePos, debugObject.pos, .1, raycastHitPos ? rgb(1,0,0,.5) : rgb(0,1,0,.5), undefined, undefined, false);
 
         let debugText = 'mouse pos = ' + mousePos;
         if (tileCollisionLayers.length)
@@ -706,8 +706,8 @@ function debugProtectConstant(obj)
         props.forEach(prop =>
         {
             Object.defineProperty(obj, prop, {
-                get: () => values[prop],
-                set: (value) => 
+                get: ()=> values[prop],
+                set: (value)=> 
                 {
                     ASSERT(false, `Cannot modify engine constant. Attempted to set constant (${obj}) property '${prop}' to '${value}'.`);
                 },