littlejsengine 1.20.0 → 1.22.0

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.20.0';
+const engineVersion = '1.22.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -40,11 +40,12 @@ const engineVersion = '1.20.0';
  *  @memberof Engine */
 const frameRate = 60;
 
-/** How many seconds each frame lasts, engine uses a fixed time step
+/** How many seconds the update covers: 1/60 with the fixed time step, or with engineVariableStep the time of the
+ *  display frame it runs on, times timeScale; while paused it keeps the last update's
  *  @type {number}
  *  @default 1/60
  *  @memberof Engine */
-const timeDelta = 1/frameRate;
+let timeDelta = 1/frameRate;
 
 /** Array containing all engine objects
  *  @type {Array<EngineObject>}
@@ -92,6 +93,75 @@ function setPaused(isPaused=true) { paused = isPaused; }
 
 // Engine internal variables
 let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
+
+// delta smoothing, after Time Delta Smoothing by Frank Force (2013): a frame is on screen for whole display frames,
+// so each delta is rounded to them and the rest is carried to the next, keeping the total real time; the frame
+// length is estimated from recent frames and kept internal, since the browser does not say what it is
+const frameDeltaHistory = [];
+let frameIntervalMS = 1e3 / 60, frameDeltaCarryMS = 0, frameDeltaCarryAverageMS = 0, frameDeltaSmoothing = true;
+function engineSmoothDelta(deltaMS)
+{
+    if (!(deltaMS > 0)) return 0;
+    if (deltaMS < 250) // a gap from a hidden tab is not a display frame
+    {
+        frameDeltaHistory.push(deltaMS);
+        frameDeltaHistory.length > 64 && frameDeltaHistory.shift();
+
+        // the frames each delta held are counted in the last estimate or in the lower quartile of the last 16,
+        // whichever the deltas fit better: the quartile is one frame even when a busy game misses most of them, and
+        // it takes over when the window moves to a display with another refresh rate, or the estimate went wrong
+        const recent = frameDeltaHistory.slice(-16).sort((a, b)=> a - b);
+        const [lastMS, lastOff] = engineFrameFit(frameIntervalMS);
+        const [quartileMS, quartileOff] = engineFrameFit(recent[recent.length >> 2]);
+        frameIntervalMS = lastOff <= quartileOff ? lastMS : quartileMS;
+
+        // deltas far from whole frames mean the display has no fixed refresh, with a margin so it does not flip
+        frameDeltaSmoothing = min(lastOff, quartileOff) < (frameDeltaSmoothing ? .2 : .12);
+    }
+
+    if (!frameDeltaSmoothing)
+    {
+        // deltas that are not whole frames of one length, like a variable refresh display, are the frame times
+        // as they are, with any carry paid, and smoothing starts over once they fit again
+        const rawMS = deltaMS + frameDeltaCarryMS;
+        frameDeltaCarryMS = min(rawMS, 0);
+        frameDeltaCarryAverageMS = 0;
+        return max(rawMS, 0);
+    }
+
+    // whole frames, 0 for one that came early or 2 after one was missed, the carry stays within half a frame; a
+    // little of its slow average is paid each frame, so jitter can not hold it at half a frame and flip every frame
+    const pullMS = frameDeltaCarryAverageMS / 32;
+    frameDeltaCarryMS += deltaMS;
+    const frames = round((frameDeltaCarryMS - pullMS) / frameIntervalMS);
+    if (frames < 1)
+        return 0; // the carry keeps it
+    const smoothMS = frames * frameIntervalMS + pullMS;
+    frameDeltaCarryMS -= smoothMS;
+    frameDeltaCarryAverageMS += (frameDeltaCarryMS - frameDeltaCarryAverageMS) / 32;
+    return smoothMS;
+}
+
+// fit the delta history as whole frames of about unitMS: the frame length is the least squares slope of time over
+// frames held, so jitter and whole ms timestamps average out, with how far the deltas are from whole frames
+function engineFrameFit(unitMS)
+{
+    let timeMS = 0, frames = 0, offMS = 0, sumF = 0, sumT = 0, sumFF = 0, sumFT = 0;
+    const count = frameDeltaHistory.length;
+    for (const d of frameDeltaHistory)
+    {
+        const held = max(1, round(d / unitMS));
+        timeMS += d;
+        frames += held;
+        offMS += abs(d - held * unitMS);
+        sumF += frames, sumT += timeMS, sumFF += frames * frames, sumFT += frames * timeMS;
+    }
+    const spread = count * sumFF - sumF * sumF;
+    return [spread ? (count * sumFT - sumF * sumT) / spread : unitMS, offMS / count / unitMS];
+}
+
+// where the fixed step's time counts from, moved when the variable step hands back so time goes on from there
+let timeFixedStart = 0, frameFixedStart = 0;
 let windowWidthLast = 0, windowHeightLast = 0, windowPixelRatioLast = 0;
 let engineUpdateInternal; // assigned by engineInit so engineStep can drive it
 let engineFrameScheduled = false; // a frame of the loop is asked for and has not run yet
@@ -109,6 +179,9 @@ function engineObjectsCollidePairAdd(asker, other, resolve=false)
     others.set(other, resolve);
 }
 let engineInitialized = false; // engineInit ran, with or without a canvas
+// the loads startup waits for, each counted for the loading screen, and how many are done; undefined once the game
+// loop starts
+let engineLoads, engineLoadsDone = 0;
 let engineObjectsUpdateCount = 0; // passes of engineObjectsUpdate so far, how a child knows it moved this pass
 const engineChildStack = []; // the children being updated, taken off the live lists so one leaving does not skip the next
 let showEngineVersion = true;
@@ -158,11 +231,68 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored, preRe
 ///////////////////////////////////////////////////////////////////////////////
 // Main Engine Functions
 
+/** Add something the game loads to what startup waits for: while engineInit and gameInit run, the game loop starts
+ *  once it is done, and the loading screen counts it; images from loadTexture and sounds from files are added on
+ *  their own, and a load that fails counts as done; after startup it does nothing
+ *  @param {Promise<any>} promise
+ *  @return {Promise<any>} - The same promise
+ *  @example
+ *  async function gameInit() { level = await engineAddLoad(fetchJSON('level.json')); }
+ *  @memberof Engine */
+function engineAddLoad(promise)
+{
+    if (engineLoads)
+    {
+        engineLoads.push(promise);
+        const done = ()=> { ++engineLoadsDone; };
+        promise.then(done, done);
+    }
+    return promise;
+}
+
+// wait for every load, the ones added while waiting too, drawing the loading screen each frame meanwhile
+async function engineWaitForLoads()
+{
+    let waiting = true;
+    const start = performance.now();
+    const drawFrame = ()=>
+    {
+        if (!waiting) return;
+        engineLoadingScreenDraw((performance.now() - start) / 1e3);
+        setTimeout(drawFrame, 16);
+    };
+    headlessMode || drawFrame();
+    try
+    {
+        for (let count; count !== engineLoads.length;)
+        {
+            count = engineLoads.length;
+            await Promise.allSettled(engineLoads);
+        }
+    }
+    finally { waiting = false; }
+}
+
+// one frame of the loading screen, once loading has taken half a second, so a fast load never shows it; input
+// while it shows is dropped, as it is under the splash
+function engineLoadingScreenDraw(elapsed)
+{
+    if (headlessMode || !loadingScreen || elapsed < .5) return;
+    inputClear();
+    engineUpdateCanvas();
+    loadingScreen(engineLoadsDone / engineLoads.length);
+}
+
 /**
  * @callback GameInitCallback - Called after the engine starts, can be async
  * @return {void|Promise<void>}
  * @memberof Engine
  */
+/**
+ * @callback LoadingScreenCallback - Draws the loading screen on mainContext, each frame while the game loads
+ * @param {number} progress - The part of the loads done, 0 to 1
+ * @memberof Engine
+ */
 /**
  * @callback GameCallback - Update or render function for the game
  * @memberof Engine
@@ -197,6 +327,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     // double-register listeners / double-add canvases on a second call
     if (engineInitialized) return;
     engineInitialized = true;
+    engineLoads = [], engineLoadsDone = 0;
     ASSERT(isArray(imageSources), 'pass in images as array');
 
     // allow passing in empty functions
@@ -236,6 +367,9 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         frameTimeLastMS = frameTimeMS;
         if (debug || debugWatermark)
             averageFPS = lerp(averageFPS, 1e3/(frameTimeDeltaMS||1), .05);
+        // the time the frame will be on screen, in whole display frames; engineStep's steps are exact already
+        if (!manualStepAtStart)
+            frameTimeDeltaMS = engineSmoothDelta(frameTimeDeltaMS);
         audioUpdateVolume();
         // the time keys work while the debug overlay is open, or always when debugKeysAlways is set
         const debugKeys = debug && (debugOverlay || debugKeysAlways);
@@ -248,32 +382,61 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         timeReal += frameTimeDeltaMS * debugScale / 1e3;
         const combinedScale = timeScale * debugScale;
         frameTimeDeltaMS *= combinedScale;
-        // paused or a time scale of 0 is frozen: it ticks on unscaled time, so the update rate stays fixed instead of
-        // following however fast the display refreshes, and gameUpdatePost and input still run to leave it
-        const frozen = paused || !combinedScale;
-        frameTimeBufferMS += frozen ? frameTimeDeltaUnscaledMS : frameTimeDeltaMS;
-        frameTimeBufferMS = min(frameTimeBufferMS, 50 * (frozen ? 1 : max(1, combinedScale))); // clamp min framerate
-
-        // apply time delta smoothing, improves smoothness of framerate in some browsers
-        let wasUpdated = false, deltaSmooth = 0;
-        if (frameTimeBufferMS < 0 && frameTimeBufferMS > -9)
+        let wasUpdated = false;
+        if (engineVariableStep)
         {
-            // force at least one update each frame since it is waiting for refresh
-            deltaSmooth = frameTimeBufferMS;
-            frameTimeBufferMS = 0;
+            // one update for the frame with timeDelta the time it covers, per-frame values are the game's to scale;
+            // engineStep's frames are exactly 1/60, its first too, which has no frame before it to take a delta from
+            if (frameTimeDeltaUnscaledMS > 0 || manualStepAtStart)
+            {
+                // frozen stands still as in the fixed step, and timeDelta keeps the last update's
+                const frozenTick = paused || !combinedScale;
+                if (!frozenTick)
+                {
+                    timeDelta = manualStepAtStart ? combinedScale / frameRate :
+                        min(frameTimeDeltaUnscaledMS, 50) * combinedScale / 1e3; // clamp min framerate
+                    time += timeDelta;
+                    ++frame;
+                }
+                engineTick(frozenTick);
+            }
         }
-
-        // update multiple frames if necessary in case of slow framerate
-        for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
+        else
         {
-            // read again each tick, so a pause set by the game stops the rest of this frame's catch-up ticks
-            const frozenTick = paused || !(timeScale * debugScale);
+            // paused or a time scale of 0 is frozen: it ticks on unscaled time, so the update rate stays fixed instead
+            // of following however fast the display refreshes, and gameUpdatePost and input still run to leave it
+            const frozen = paused || !combinedScale;
+            frameTimeBufferMS += frozen ? frameTimeDeltaUnscaledMS : frameTimeDeltaMS;
+            frameTimeBufferMS = min(frameTimeBufferMS, 50 * (frozen ? 1 : max(1, combinedScale))); // clamp min framerate
+
+            // apply time delta smoothing, improves smoothness of framerate in some browsers
+            let deltaSmooth = 0;
+            if (frameTimeBufferMS < 0 && frameTimeBufferMS > -9)
+            {
+                // force at least one update each frame since it is waiting for refresh
+                deltaSmooth = frameTimeBufferMS;
+                frameTimeBufferMS = 0;
+            }
 
-            // increment frame and update time, frozen does not advance time
-            if (!frozenTick)
-                time = frame++ / frameRate;
+            // update multiple frames if necessary in case of slow framerate
+            for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
+            {
+                // read again each tick, so a pause set by the game stops the rest of this frame's catch-up ticks
+                const frozenTick = paused || !(timeScale * debugScale);
 
-            // update game and objects, when frozen update everything except them
+                // increment frame and update time, frozen does not advance time
+                if (!frozenTick)
+                    time = timeFixedStart + (frame++ - frameFixedStart) / frameRate;
+                engineTick(frozenTick);
+            }
+
+            // add the time smoothing back in
+            frameTimeBufferMS += deltaSmooth;
+        }
+
+        // one tick of the loop: update game and objects, when frozen update everything except them
+        function engineTick(frozenTick)
+        {
             wasUpdated = true;
             engineUpdateCanvas();
             inputUpdate();
@@ -300,9 +463,6 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 renderFrame();
         }
 
-        // add the time smoothing back in
-        frameTimeBufferMS += deltaSmooth;
-
         // manual step turned on by this frame's updates, set the buffer the loop and smoothing just moved again
         if (engineManualStep && !manualStepAtStart)
             frameTimeBufferMS = -.5e3 / frameRate;
@@ -361,7 +521,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     }
 
     // skip setup if headless
-    if (headlessMode) return startEngine();
+    if (headlessMode) return startEngine([]);
 
     // ensure body exists for minimal HTML where the script runs before <body> is parsed
     if (!document.body)
@@ -439,14 +599,19 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         promises.push(splash);
     }
 
-    // wait for all the promises to finish
-    await Promise.all(promises);
-    return startEngine();
+    // the splash first, the images load under it, then the loading screen for the rest
+    showSplashScreen && await promises.at(-1);
+    return startEngine(promises);
 
-    async function startEngine()
+    // gameInit runs once the images are in, and the game loop starts once it and everything loaded while it ran are
+    // done, the loading screen showing in the meantime; an error in gameInit reaches the caller
+    async function startEngine(images)
     {
-        // wait for gameInit to load
-        await gameInit();
+        const init = (async ()=> { await Promise.all(images); await gameInit(); })();
+        engineAddLoad(init);
+        await engineWaitForLoads();
+        engineLoads = undefined;
+        await init;
         engineUpdateInternal = engineUpdate; // engineStep only runs once the game is set up
         engineManualStep || engineUpdate();
     }

package/src/engineAudio.js

@@ -220,9 +220,12 @@ class 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(asset, randomness, range=soundDefaultRange, taper=soundDefaultTaper, onloadCallback)
+    constructor(asset, randomness, range, taper=soundDefaultTaper, onloadCallback)
     {
         if (!soundEnable || headlessMode) return;
+        const rangeIsDefault = range === undefined;
+        if (rangeIsDefault)
+            range = soundDefaultRange;
 
         ASSERT(!asset || isArray(asset) || isStringLike(asset), 'asset must be a file name or zzfx array');
         ASSERT(randomness === undefined || isNumber(randomness), 'randomness must be a number');
@@ -232,6 +235,9 @@ class Sound
 
         /** @property {number} - World space max range of sound */
         this.range = range;
+        /** @property {boolean} - No range was given, so it got soundDefaultRange; played in 3D such a sound is heard
+         *  to render3D.soundDefaultRange instead, which is further */
+        this.rangeIsDefault = rangeIsDefault;
         /** @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
@@ -281,8 +287,8 @@ class Sound
             // load the audio file, a URL object as bundlers give works like its string;
             // report failures rather than leaving an unhandled rejection, the sound just stays unloaded and silent
             const filename = asset + '';
-            this.loadSound(filename).catch(e=>
-                LOG('Sound load failed for', filename, '-', e.message));
+            engineAddLoad(this.loadSound(filename).catch(e=>
+                LOG('Sound load failed for', filename, '-', e.message))); // startup waits for it
         }
     }
 
@@ -867,7 +873,7 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-// ZzFXMicro - Zuper Zmall Zound Zynth - v1.3.2 by Frank Force
+// ZzFXMicro - Zuper Zmall Zound Zynth - v1.4.0 by Frank Force
 
 /** Generate and play a ZzFX sound
  *
@@ -899,7 +905,7 @@ function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
  *  @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)
- *  @return {Array} - Array of audio samples
+ *  @return {Float32Array} - The audio samples
  *  @memberof Audio */
 function zzfxG
 (
@@ -937,7 +943,7 @@ function zzfxG
         crush = 0,     // bit crush offset
         jump = 1,      // pitch jump timer
         length,        // sample length
-        b = [],        // sample buffer
+        b,             // sample buffer
         t = 0,         // sample time
         i = 0,         // sample index
         s = 0,         // sample value
@@ -964,9 +970,12 @@ function zzfxG
         pitchJumpTime *= sampleRate;
         repeatTime = repeatTime * sampleRate | 0;
 
+    // allocate the full sample buffer up front, much faster than growing an array
+    length = attack + decay + sustain + release + delay | 0;
+    b = new Float32Array(length > 0 ? length : 0);
+
     // generate waveform
-    for (length = attack + decay + sustain + release + delay | 0;
-        i < length; b[i++] = s * volume)                   // sample
+    for (; i < length; b[i++] = s * volume)                 // sample
     {
         if (!(++crush%(bitCrush*100|0)))                   // bit crush
         {
@@ -1002,7 +1011,7 @@ function zzfxG
 
         f = (frequency += slide += deltaSlide) *// frequency
             cos(modulation*modOffset++);        // modulation
-        t += f + f*noise*sin(i**5);             // noise
+        t += f + f*noise*(i*i*PI2%2-1);         // noise
 
         if (jump && ++jump > pitchJumpTime)     // pitch jump
         {

package/src/engineBuild.mjs

@@ -49,11 +49,14 @@ const enginePluginFiles =
     `${PLUGIN_FOLDER}/drawUtilities.js`,
     `${PLUGIN_FOLDER}/textureSheet.js`,
     `${PLUGIN_FOLDER}/tweenSystem.js`,
+    `${PLUGIN_FOLDER}/sceneSystem.js`,
     `${PLUGIN_FOLDER}/pathFinder.js`,
     `${PLUGIN_FOLDER}/math3d.js`,
     `${PLUGIN_FOLDER}/render3d.js`,
     `${PLUGIN_FOLDER}/render3dExtras.js`,
     `${PLUGIN_FOLDER}/render3dVoxels.js`,
+    `${PLUGIN_FOLDER}/render3dLevel.js`,
+    `${PLUGIN_FOLDER}/particleEffects.js`,
     `${PLUGIN_FOLDER}/gltf.js`,
     `${PLUGIN_FOLDER}/threejs.js`,
 ];
@@ -63,6 +66,7 @@ const engineDebugFiles =
     `${PLUGIN_FOLDER}/tweakables.js`,
     `${PLUGIN_FOLDER}/render3dDebug.js`,
     `${SOURCE_FOLDER}/engineEditor.js`,
+    `${PLUGIN_FOLDER}/render3dEditor.js`,
 ];
 const engineExtraFiles =
 [

package/src/engineDebug.js

@@ -684,6 +684,14 @@ function debugRender()
             debugContext.fillText('9: Tweakables', x, y += h);
             debugContext.fillStyle = levelEditor.isOpen ? '#f00' : '#fff';
             debugContext.fillText('0: Edit Level', x, y += h);
+            for (const line of debugOverlayKeys)
+            {
+                // a key a debug plugin added, when it has something to say
+                const key = line();
+                if (!key) continue;
+                debugContext.fillStyle = key.on ? '#f00' : '#fff';
+                debugContext.fillText(key.text, x, y += h);
+            }
             debugContext.fillStyle = '#fff';
 
             let keysPressed = '';
@@ -910,4 +918,50 @@ function debugProtectConstant(obj)
     
     // freeze the object to prevent adding new properties
     return Object.freeze(obj);
-}
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// Input capture: the free camera and the 3D level editor take the keyboard and mouse, so the game under them reads
+// every key and mouse button as up, and no mouse movement or wheel; gamepads are left to the game
+
+let inputCaptureOn = false;      // something has taken the keyboard and mouse
+let inputCaptureReading = false; // it is reading them now
+let inputCaptureDeltaScreen, inputCaptureWheel = 0; // this update's mouse movement and wheel, for it alone
+
+// the game let go of a captured mouse itself, with pointerLockExit, since the debug tools last looked: a capture
+// that is lost without it is the browser's doing, which is how Chrome takes Escape
+let inputLockLetGo = false;
+function inputLockExit() { inputLockLetGo = true; }
+
+// the keys debug plugins add to the overlay's list, each a function that gives {text, on} or nothing to show
+const debugOverlayKeys = [];
+
+// take the keyboard and mouse from the game, or hand them back
+function inputCapture(on=true)
+{
+    inputCaptureOn = !!on;
+    inputCaptureDeltaScreen = vec2();
+    inputCaptureWheel = 0;
+}
+
+// read the input as the one that took it, keyIsDown and the rest work as always inside read
+function inputCaptureRead(read)
+{
+    const was = inputCaptureReading;
+    inputCaptureReading = true;
+    try { return read(); }
+    finally { inputCaptureReading = was; }
+}
+
+// if a read of the keyboard and mouse, device 0, is the game's while they are taken
+function inputCaptureHides(device) { return inputCaptureOn && !inputCaptureReading && !device; }
+
+// called first in inputUpdate: the mouse movement and wheel go to the one that took the input
+function inputCaptureMouse()
+{
+    if (!inputCaptureOn) return;
+    inputCaptureDeltaScreen = mouseDeltaScreen;
+    inputCaptureWheel = mouseWheel;
+    mouseDeltaScreen = vec2();
+    mouseWheel = 0;
+}