littlejsengine 1.25.0 → 1.26.1

package/src/engineAudio.js

@@ -38,7 +38,8 @@ if (audioMasterGain)
 // soundVolume can be set directly, so the master gain follows it each frame
 function audioUpdateVolume()
 {
-    if (audioMasterGain && soundVolume !== audioMasterVolume)
+    // a volume that is not a number, from a slider's text say, is not handed on, where every frame it would throw
+    if (audioMasterGain && soundVolume !== audioMasterVolume && isFinite(soundVolume))
         audioMasterGain.gain.value = audioMasterVolume = soundVolume;
 }
 
@@ -126,7 +127,6 @@ function audioStateChange()
  *  - The output node is disconnected from everything else first, so it only feeds the speakers
  *  - The two ends of a chain must already be connected to each other, like effectA.connect(effectB)
  *  - Call with no arguments to remove the effect, an effect that was the master goes back to feeding the master gain
- *  - Debug video capture records the end of the master chain, but loses its tap if the effect changes mid-capture
  *  @param {AudioNode|AudioEffectNodes} [input] - Node or effect the master gain connects to
  *  @param {AudioNode|AudioEffectNodes} [output] - Node or effect that connects to the audio destination, defaults to the input's output
  *  @memberof Audio */
@@ -181,11 +181,16 @@ function audioEffectNode(effectOrNode, key)
     return /** @type {AudioNode} */ (effectOrNode);
 }
 
+// a value for an audio param, which throws on one that is not finite, so a release build, with no asserts to stop it,
+// takes NaN or Infinity as the value given in its place: silent, centered or the normal rate
+const audioFinite = (value, otherwise)=> isFinite(value) ? value : otherwise;
+
 // ramp an audio param to a value, cancelling anything already scheduled so stacked calls don't fight;
 // returns when the ramp ends
 function audioParamRamp(param, value, fadeTime=0)
 {
     ASSERT(fadeTime >= 0, 'fadeTime must be positive or zero');
+    value = audioFinite(value, 0), fadeTime = audioFinite(fadeTime, 0);
     const startTime = audioContext.currentTime;
     param.cancelScheduledValues(startTime);
     if (fadeTime)
@@ -201,7 +206,7 @@ function audioParamRamp(param, value, fadeTime=0)
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * @callback SoundLoadCallback - Function called when sound is loaded
+ * @callback SoundLoadCallback - Function called once a sound has loaded, or failed to, which sound.isLoaded() tells
  * @param {Sound} sound
  * @memberof Audio
  */
@@ -232,7 +237,8 @@ class Sound
      *  @param {number} [randomness] - How much to randomize frequency each time sound plays, for zzfx sounds it overrides the array's own randomness, which 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
+     *  @param {SoundLoadCallback} [onloadCallback] - Called once the sound has loaded, or its file failed to, so a
+     *    game counting its sounds goes on; isLoaded says which
      */
     constructor(asset, randomness, range, taper=soundDefaultTaper, onloadCallback)
     {
@@ -291,7 +297,7 @@ class Sound
 
             // remove randomness so it can be applied on playback, a value passed in wins over the array's
             const randomnessIndex = 1;
-            this.randomness = randomness ?? zzfxSound[randomnessIndex] ?? .05;
+            this.randomness = randomness ?? clamp(zzfxSound[randomnessIndex] ?? .05); // 0 to 1, as one passed in
             zzfxSound[randomnessIndex] = 0;
 
             // generate the zzfx samples, then hand them to an audio buffer so
@@ -307,7 +313,12 @@ class Sound
             // report failures rather than leaving an unhandled rejection, the sound just stays unloaded and silent
             const filename = asset + '';
             engineAddLoad(this.loadSound(filename).catch(e=> // startup waits for it, and a release build says why too
-                console.warn('Sound load failed for', filename, '-', e?.message ?? e)));
+            {
+                console.warn('Sound load failed for', filename, '-', e?.message ?? e);
+                // failed, not loaded and its callback threw; one that throws here says so, a load is no place to stop
+                try { this.loadedPercent === 1 || this.onloadCallback?.(this); }
+                catch (callbackError) { console.warn('Sound onloadCallback failed for', filename, '-', callbackError); }
+            }));
         }
     }
 
@@ -390,8 +401,8 @@ class Sound
             {
                 // apply range based fade
                 const lengthSquared = cameraPos.distanceSquared(pos);
-                if (lengthSquared > range*range)
-                    return; // out of range
+                if (lengthSquared >= range*range)
+                    return; // out of range, at it too, where the fade is silent
 
                 // attenuate volume by distance, full volume out to the taper and a fade past it,
                 // so a taper of 1 plays at full volume right up to the range
@@ -467,14 +478,14 @@ class Sound
      */
     isLoaded() { return this.loadedPercent === 1; }
     
-    /** Loads a sound from a URL and decodes it into sample data.
+    /** Loads a sound from a URL and decodes it into sample data
     *  @param {string} filename
     *  @return {Promise} */
     async loadSound(filename)
     {
-        const response = await fetch(filename);
+        const response = await loadFetch(filename, 'loadSound'); // named, with the hint for a page opened from disk
         if (!response.ok)
-            throw new Error(`Failed to load sound from ${filename}: ${response.status} ${response.statusText}`);
+            throw new Error(`loadSound: could not load ${filename}, HTTP ${response.status} ${response.statusText}`);
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
         
@@ -525,11 +536,11 @@ class SoundInstance
         /** @property {Sound} - The sound object */
         this.sound = sound;
         /** @property {number} - How much to scale volume by */
-        this.volume = volume;
+        this.volume = audioFinite(volume, 0);
         /** @property {number} - The playback rate to use */
-        this.rate = rate;
+        this.rate = audioFinite(rate, 1);
         /** @property {number} - How much to apply stereo panning */
-        this.pan = pan;
+        this.pan = audioFinite(pan, 0);
         /** @property {boolean} - Should the sound loop */
         this.loop = loop;
         /** @property {number|undefined} - Where it is in the sound while not playing, in the sound's own seconds, undefined while playing
@@ -621,7 +632,7 @@ class SoundInstance
     {
         ASSERT(volume >= 0, 'Sound volume must be positive or zero');
         ASSERT(fadeTime >= 0, 'Sound fade time must be positive or zero');
-        this.volume = volume;
+        this.volume = volume = audioFinite(volume, 0);
         this.gainNode && audioParamRamp(this.gainNode.gain, volume, fadeTime);
     }
 
@@ -631,7 +642,7 @@ class SoundInstance
     setPan(pan)
     {
         ASSERT(isNumber(pan), 'Sound pan must be a number');
-        this.pan = pan;
+        this.pan = pan = audioFinite(pan, 0);
         if (this.pannerNode)
             this.pannerNode.pan.value = clamp(pan, -1, 1);
     }
@@ -649,7 +660,7 @@ class SoundInstance
             this.startOffset = this.getCurrentTime();
             this.startTime = audioContext.currentTime;
         }
-        this.rate = rate;
+        this.rate = rate = audioFinite(rate, 1);
         if (this.source)
             this.source.playbackRate.value = rate;
     }
@@ -725,7 +736,9 @@ class SoundInstance
         if (!this.isPlaying()) return this.pausedTime;
         const duration = this.getDuration();
         const place = this.startOffset + (audioContext.currentTime - this.startTime) * this.rate;
-        return duration ? mod(place, duration) : 0; // a sound still loading has no length yet
+        // a sound still loading has no length yet; a loop goes around, a one shot past its end, before its ended
+        // event, stays at its end, so a pause there does not play it again on resume
+        return !duration ? 0 : this.loop ? mod(place, duration) : min(place, duration);
     }
 
     /** Get the length of the sound in its own seconds, the same at any rate; divide by the rate for how long it takes to play
@@ -865,6 +878,8 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
         return;
     }
 
+    volume = audioFinite(volume, 0), rate = audioFinite(rate, 1), pan = audioFinite(pan, 0);
+
     // setup source, many sources can share one buffer
     const source = audioContext.createBufferSource();
     source.buffer = buffer;
@@ -920,8 +935,8 @@ function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
  *  @param {number}  [release] - Release time, how fast sound fades out (seconds)
  *  @param {number}  [shape] - Shape of the sound wave
  *  @param {number}  [shapeCurve] - Squareness of wave (0=square, 1=normal, 2=pointy)
- *  @param {number}  [slide] - How much to slide frequency (kHz/s)
- *  @param {number}  [deltaSlide] - How much to change slide (kHz/s/s)
+ *  @param {number}  [slide] - How much to slide frequency, 1 is about 500 Hz a second, as ZzFX has it
+ *  @param {number}  [deltaSlide] - How much to change slide each second, in the units of slide
  *  @param {number}  [pitchJump] - Frequency of pitch jump (Hz)
  *  @param {number}  [pitchJumpTime] - Time of pitch jump (seconds)
  *  @param {number}  [repeatTime] - Resets some parameters periodically (seconds)
@@ -932,7 +947,8 @@ function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
  *  @param {number}  [sustainVolume] - Volume level for sustain (percent)
  *  @param {number}  [decay] - Decay time, how long to reach sustain after attack (seconds)
  *  @param {number}  [tremolo] - Trembling effect, rate controlled by repeat time (percent)
- *  @param {number}  [filter] - Filter cutoff frequency, positive for HPF, negative for LPF (Hz)
+ *  @param {number}  [filter] - Filter cutoff, positive for HPF, negative for LPF; the cutoff is about twice this in
+ *    Hz, as ZzFX has it, and its resonance can take the samples past 1
  *  @return {Float32Array} - The audio samples
  *  @memberof Audio */
 function zzfxG

package/src/engineBuild.mjs

@@ -42,6 +42,7 @@ const enginePluginFiles =
 [
     `${PLUGIN_FOLDER}/medalSystem.js`,
     `${PLUGIN_FOLDER}/newgrounds.js`,
+    `${PLUGIN_FOLDER}/wavedash.js`,
     `${PLUGIN_FOLDER}/postProcess.js`,
     `${PLUGIN_FOLDER}/lightSystem.js`,
     `${PLUGIN_FOLDER}/audioEffects.js`,
@@ -55,6 +56,8 @@ const enginePluginFiles =
     `${PLUGIN_FOLDER}/pathFinder.js`,
     `${PLUGIN_FOLDER}/math3d.js`,
     `${PLUGIN_FOLDER}/render3d.js`,
+    `${PLUGIN_FOLDER}/render3dMesh.js`,
+    `${PLUGIN_FOLDER}/render3dObject.js`,
     `${PLUGIN_FOLDER}/render3dExtras.js`,
     `${PLUGIN_FOLDER}/render3dVoxels.js`,
     `${PLUGIN_FOLDER}/render3dLevel.js`,
@@ -292,7 +295,9 @@ function typeScriptBuildStep(filename)
         // strictNullChecks keeps undefined in the types, where tsc would drop it from accessors and object types
         // whatever the JSDoc says, so a game in strict mode can set render3D.shader = undefined and is told a
         // flare may be missing; a game not in strict mode reads the same types as before
-        execSync(`npx -p typescript tsc "${filename}" --declaration --allowJs --emitDeclarationOnly --strictNullChecks --outFile "${tsFilename}"`);
+        // the target names the library tsc types with: without it tsc takes ES5's, where Map and Set do not resolve
+        // and come out as any, which went unseen while a dependency brought @types/node, which declares them
+        execSync(`npx -p typescript tsc "${filename}" --declaration --allowJs --emitDeclarationOnly --strictNullChecks --target es2022 --outFile "${tsFilename}"`);
 
         // Make declare module part use the package name littlejsengine
         let fileContent = fs.readFileSync(tsFilename, 'utf8');

package/src/engineDebug.js

@@ -6,7 +6,7 @@
  * - setDebugKeysAlways lets those keys work with the overlay closed too
  * - ASSERT and LOG macros for development (removed in release builds)
  * - Debug primitive rendering (rectangles, circles, lines, points, text)
- * - Screenshot and video capture support
+ * - Screenshot support
  * - FPS counter and performance watermark
  * - Debug overlay shows mouse position and picked objects
  * @namespace Debug
@@ -84,7 +84,24 @@ function ASSERT(assert, ...output)
 {
     if (assert) return;
     console.assert(assert, ...output)
-    throw new Error('Assert failed!'); // halt execution
+    // the error says what went wrong, so an error box or overlay that shows only the error shows the message too: a
+    // value with a toString of its own as that, a vec2 or a color, a plain object as JSON, an object of a class with
+    // none by its class's name, each cut at 200 characters, so a whole level is not the message
+    const text = output.map((value)=>
+    {
+        let text;
+        try
+        {
+            const prototype = value && typeof value === 'object' ? Object.getPrototypeOf(value) : undefined;
+            text = prototype === Object.prototype || prototype === null ? JSON.stringify(value) :
+                prototype && value.toString === Object.prototype.toString ?
+                '[' + (value.constructor?.name || 'object') + ']' : String(value);
+        }
+        catch { text = Object.prototype.toString.call(value); }
+        text = String(text); // JSON of nothing, as from a toJSON that returns nothing, is undefined
+        return text.length > 200 ? text.slice(0, 199) + '…' : text;
+    }).join(' ');
+    throw new Error(text ? 'Assert failed: ' + text : 'Assert failed!'); // halt execution
 }
 
 /** Log to console if debug is enabled, does nothing in release builds
@@ -329,19 +346,6 @@ function debugUpdate()
         if (keyWasPressed('Digit0'))
             levelEditor.isOpen ? levelEditor.close() : levelEditor.open();
     }
-    if (debugVideoCaptureIsActive())
-    {
-        // control to stop video capture, a capture the overlay started also stops when the overlay closes,
-        // one the game started from code runs until it calls debugVideoCaptureStop
-        if (debugKeys ? keyWasPressed('Digit8') : debugVideoCapture.fromOverlay)
-            debugVideoCaptureStop();
-    }
-    else if (debugKeys && keyWasPressed('Digit8'))
-    {
-        debugVideoCaptureStart();
-        if (debugVideoCapture)
-            debugVideoCapture.fromOverlay = true;
-    }
 }
 
 // the text beside the mouse, with the same shadow as the overlay
@@ -440,20 +444,13 @@ function debugRender()
 {
     if (debugTakeScreenshot)
     {
-        // combine canvases, remove alpha and save, before the capture check so it is taken during video capture too
+        // combine canvases, remove alpha and save
         glFlush();
         combineCanvases();
         saveCanvas(mainCanvas);
         debugTakeScreenshot = 0;
     }
 
-    if (debugVideoCaptureIsActive())
-    {
-        // don't show debug info when capturing video, but still drop the expired primitives so they don't pile up
-        debugPrimitives = debugPrimitives.filter(r=>r.timer<0);
-        return;
-    }
-
     // flush any gl sprites before drawing debug info
     glFlush();
 
@@ -682,7 +679,6 @@ function debugRender()
             debugContext.fillText('6: Debug Sound', x, y += h);
             debugContext.fillStyle = '#fff';
             debugContext.fillText('7: Save Screenshot', x, y += h);
-            debugContext.fillText('8: Toggle Video Capture', x, y += h);
             debugContext.fillStyle = debugTweakables ? '#f00' : '#fff';
             debugContext.fillText('9: Tweakables', x, y += h);
             debugContext.fillStyle = levelEditor.isOpen ? '#f00' : '#fff';
@@ -757,143 +753,6 @@ function debugRender()
     }
 }
 
-function debugRenderPost() { debugVideoCaptureIsActive() && debugVideoCaptureUpdate(); }
-
-///////////////////////////////////////////////////////////////////////////////
-// video capture - records video and audio at 60 fps using MediaRecorder API
-
-// internal variables used to capture video
-let debugVideoCapture, debugVideoCaptureIcon;
-
-/** Check if video capture is active
- *  @memberof Debug
- *  @return {boolean} */
-function debugVideoCaptureIsActive() { return !!debugVideoCapture; }
-
-/** Start capturing video
- *  @memberof Debug */
-function debugVideoCaptureStart()
-{
-    ASSERT(!debugVideoCaptureIsActive(), 'Already capturing video!');
-
-    // everything that can fail where recording is unsupported is in the try, a missing captureStream
-    // or a MediaRecorder that refuses webm throws here and is cleaned up rather than stopping the game
-    const captureTimer = new Timer(0, true);
-    const chunks = [];
-    let videoTrack, mediaRecorder, audioStreamDestination, silentAudioSource, audioTapNode;
-    try
-    {
-        // setup captureStream to capture manually by passing 0
-        const stream = mainCanvas.captureStream(0);
-        videoTrack = stream.getVideoTracks()[0];
-        videoTrack.applyConstraints({frameRate:frameRate}).catch(()=>{});
-
-        // set up the media recorder
-        mediaRecorder = new MediaRecorder(stream,
-            {mimeType:'video/webm;codecs=vp8'});
-        mediaRecorder.ondataavailable = (e)=> chunks.push(e.data);
-        mediaRecorder.onstop = ()=>
-        {
-            const blob = new Blob(chunks, {type: 'video/webm'});
-            const url = URL.createObjectURL(blob);
-            saveDataURL(url, 'capture.webm', 1e3);
-        };
-
-        if (soundEnable)
-        {
-            // create silent audio source
-            // fixes issue where video can not start recording without audio
-            silentAudioSource = new ConstantSourceNode(audioContext, { offset: 0 });
-            silentAudioSource.connect(audioMasterGain);
-            silentAudioSource.start();
-
-            // tap the end of the master chain so a master effect is in the recording
-            // (a master effect swapped mid-capture drops the tap, the rest records silent)
-            audioTapNode = audioMasterEffectOutput || audioMasterGain;
-            audioStreamDestination = audioContext.createMediaStreamDestination();
-            audioTapNode.connect(audioStreamDestination);
-            for (const track of audioStreamDestination.stream.getAudioTracks())
-                stream.addTrack(track); // add audio tracks to capture stream
-        }
-
-        // start recording
-        mediaRecorder.start();
-    }
-    catch(e)
-    {
-        LOG('Video capture not supported in this browser!');
-        videoTrack?.stop();
-        silentAudioSource?.stop();
-        if (audioStreamDestination)
-        {
-            // the tap may not have been made before the failure
-            try { audioTapNode.disconnect(audioStreamDestination); }
-            catch { }
-        }
-        return;
-    }
-
-    if (!debugVideoCaptureIcon)
-    {
-        // create recording icon to show it is capturing video
-        debugVideoCaptureIcon = document.createElement('div');
-        debugVideoCaptureIcon.style.position = 'absolute';
-        debugVideoCaptureIcon.style.padding = '9px';
-        debugVideoCaptureIcon.style.color = '#f00';
-        debugVideoCaptureIcon.style.font = '50px monospace';
-        document.body.appendChild(debugVideoCaptureIcon);
-    }
-    // show recording icon, only once recording has started
-    debugVideoCaptureIcon.textContent = '';
-    debugVideoCaptureIcon.style.display = '';
-
-    LOG('Video capture started.');
-
-    // save debug video info
-    debugVideoCapture =
-    {
-        mediaRecorder,
-        captureTimer,
-        videoTrack,
-        silentAudioSource,
-        audioStreamDestination,
-        audioTapNode
-    };
-}
-
-/** Stop capturing video and save to disk
- *  @memberof Debug */
-function debugVideoCaptureStop()
-{
-    ASSERT(debugVideoCaptureIsActive(), 'Not capturing video!');
-
-    // stop recording
-    LOG(`Video capture ended. ${debugVideoCapture.captureTimer.get().toFixed(2)} seconds recorded.`);
-    debugVideoCaptureIcon.style.display = 'none';
-    debugVideoCapture.silentAudioSource?.stop();
-    debugVideoCapture.mediaRecorder?.stop();
-    debugVideoCapture.videoTrack?.stop();
-    if (debugVideoCapture.audioStreamDestination)
-    {
-        // the tap is already gone if the master effect changed during the capture
-        try { debugVideoCapture.audioTapNode.disconnect(debugVideoCapture.audioStreamDestination); }
-        catch { }
-    }
-    debugVideoCapture = undefined;
-}
-
-// update video capture, called automatically by engine
-function debugVideoCaptureUpdate()
-{
-    ASSERT(debugVideoCaptureIsActive(), 'Not capturing video!');
-
-    // save the video frame
-    combineCanvases();
-    debugVideoCapture.videoTrack.requestFrame();
-    debugVideoCaptureIcon.textContent = '● REC '
-        + formatTime(debugVideoCapture.captureTimer.get());
-}
-
 ///////////////////////////////////////////////////////////////////////////////
 // debug utility functions
 
@@ -913,7 +772,8 @@ function debugProtectConstant(obj)
                 get: ()=> values[prop],
                 set: (value)=> 
                 {
-                    ASSERT(false, `Cannot modify engine constant. Attempted to set constant (${obj}) property '${prop}' to '${value}'.`);
+                    ASSERT(false, `engine constants like RED can not be changed, change a copy made with copy(); ` +
+                        `tried to set ${prop} of ${obj} to ${value}`);
                 },
                 enumerable: true
             });