littlejsengine 1.25.0 → 1.26.0

package/src/engineSettings.js

@@ -458,7 +458,11 @@ let soundPauseWhenHidden = true;
 /** Set position of camera in world space
  *  @param {Vector2} pos
  *  @memberof Settings */
-function setCameraPos(pos) { cameraPos = pos.copy(); }
+function setCameraPos(pos)
+{
+    ASSERT(isVector2(pos), 'setCameraPos: pos is a vec2, like vec2(5, 2)', pos);
+    cameraPos = pos.copy();
+}
 
 /** Set angle of camera in world space
  *  @param {number} angle
@@ -472,6 +476,7 @@ function setCameraScale(scale) { cameraScale = scale; }
 
 /** Set scale applied to engine time
  *  - 0 freezes the game like a pause, gameUpdatePost and input still run so the game can set it back
+ *  - Above 1 the fixed step runs that many updates each frame, so a large scale costs as many updates
  *  @param {number} scale - 0 or more
  *  @memberof Settings */
 function setTimeScale(scale)
@@ -491,12 +496,20 @@ function setCanvasColorTiles(colorTiles) { canvasColorTiles = colorTiles; }
 /** Set color to clear the canvas to before render, does not clear if alpha is 0
  *  @param {Color} color
  *  @memberof Settings */
-function setCanvasClearColor(color) { canvasClearColor = color.copy(); }
+function setCanvasClearColor(color)
+{
+    ASSERT(isColor(color), 'setCanvasClearColor: color is a Color, like hsl(.6, .5, .2)', color);
+    canvasClearColor = color.copy();
+}
 
 /** Set max size of the canvas
  *  @param {Vector2} size
  *  @memberof Settings */
-function setCanvasMaxSize(size) { canvasMaxSize = size.copy(); }
+function setCanvasMaxSize(size)
+{
+    ASSERT(isVector2(size), 'setCanvasMaxSize: size is a vec2, like vec2(1920, 1080)', size);
+    canvasMaxSize = size.copy();
+}
 
 /** Set minimum aspect ratio of the canvas (width/height), unused if 0
  *  @param {number} aspect
@@ -511,7 +524,11 @@ function setCanvasMaxAspect(aspect) { canvasMaxAspect = aspect; }
 /** Set fixed size of the canvas
  *  @param {Vector2} size
  *  @memberof Settings */
-function setCanvasFixedSize(size) { canvasFixedSize = size.copy(); }
+function setCanvasFixedSize(size)
+{
+    ASSERT(isVector2(size), 'setCanvasFixedSize: size is a vec2, like vec2(1280, 720)', size);
+    canvasFixedSize = size.copy();
+}
 
 /** Use nearest scaling algorithm for canvas for more pixelated look
  *  @param {boolean} pixelated
@@ -553,6 +570,7 @@ function setCanvasPixelRatio(pixelRatio) { canvasPixelRatio = pixelRatio; }
 function getCanvasPixelRatio() { return canvasPixelRatio ?? (devicePixelRatio || 1); }
 
 /** Set default font used for text rendering
+ *  - A family name with spaces or digits goes in quotes, as "'Press Start 2P'", or the canvas does not take it
  *  @param {string} font
  *  @memberof Settings */
 function setFontDefault(font) { fontDefault = font; }
@@ -641,7 +659,11 @@ function setGLCircleSides(sides)
 /** Set default size of tiles in pixels
  *  @param {Vector2} size
  *  @memberof Settings */
-function setTileDefaultSize(size) { tileDefaultSize = size.copy(); }
+function setTileDefaultSize(size)
+{
+    ASSERT(isVector2(size), 'setTileDefaultSize: size is a vec2, like vec2(16)', size);
+    tileDefaultSize = size.copy();
+}
 
 /** Default padding pixels around tiles
  *  @param {number} padding
@@ -666,12 +688,23 @@ function setObjectDefaultMass(mass) { objectDefaultMass = mass; }
 /** Set the fraction of velocity objects keep each frame, 1 keeps all of it, 0 stops at once
  *  @param {number} damp
  *  @memberof Settings */
-function setObjectDefaultDamping(damp) { objectDefaultDamping = damp; }
+function setObjectDefaultDamping(damp)
+{
+    ASSERT(damp >= 0 && damp <= 1,
+        'setObjectDefaultDamping: damping is 0 to 1, the fraction of velocity kept each frame', damp);
+    objectDefaultDamping = damp;
+}
 
 /** Set the fraction of angular velocity objects keep each frame, 1 keeps all of it, 0 stops at once
  *  @param {number} damp
  *  @memberof Settings */
-function setObjectDefaultAngleDamping(damp) { objectDefaultAngleDamping = damp; }
+function setObjectDefaultAngleDamping(damp)
+{
+    ASSERT(damp >= 0 && damp <= 1,
+        'setObjectDefaultAngleDamping: angle damping is 0 to 1, the fraction of angular velocity kept each frame',
+        damp);
+    objectDefaultAngleDamping = damp;
+}
 
 /** Set how much to bounce when a collision occurs
  *  @param {number} restitution
@@ -691,7 +724,11 @@ function setObjectMaxSpeed(speed) { objectMaxSpeed = speed; }
 /** Set how much gravity to apply to objects
  *  @param {Vector2} newGravity
  *  @memberof Settings */
-function setGravity(newGravity) { gravity = newGravity.copy(); }
+function setGravity(newGravity)
+{
+    ASSERT(isVector2(newGravity), 'setGravity: newGravity is a vec2, like vec2(0, -.01)', newGravity);
+    gravity = newGravity.copy();
+}
 
 /** Set the scale for the emit rate of particles, 0 disables particle emitters
  *  @param {number} scale
@@ -821,7 +858,8 @@ function setTouchGamepadVibration(ms) { touchGamepadVibration = ms; }
  *  @memberof Settings */
 function setVibrateEnable(enable) { vibrateEnable = enable; }
 
-/** Set if audio is enabled, false turns all sound off
+/** Set if audio is enabled, false turns all sound off; a setting for before sounds are made, since a sound made
+ *  while it is off has nothing to play and one already playing goes on; to mute while the game runs, setSoundVolume(0)
  *  @param {boolean} enable
  *  @memberof Settings */
 function setSoundEnable(enable) { soundEnable = enable; }
@@ -840,6 +878,7 @@ function setSoundIgnoreSilentSwitch(ignore)
  *  @memberof Settings */
 function setSoundVolume(volume)
 {
+    ASSERT(isNumber(volume) && abs(volume) < Infinity, 'setSoundVolume: volume must be a finite number, 1 is full', volume);
     soundVolume = volume;
     audioUpdateVolume(); // update gain immediately, sound off or not
 }

package/src/engineTileLayer.js

@@ -844,7 +844,7 @@ class TileLayer extends CanvasLayer
     redrawStart(clear=false)
     {
         if (!this.context) return;
-        ASSERT(drawContext !== this.context);
+        ASSERT(drawContext !== this.context, 'redrawStart: already started, call redrawEnd() first');
         clear || this.redrawIfSwitched(); // a partial redraw goes on top of the whole layer on the side in use
         
         // save current render settings
@@ -889,7 +889,7 @@ class TileLayer extends CanvasLayer
     redrawEnd()
     {
         if (!this.context) return;
-        ASSERT(drawContext === this.context);
+        ASSERT(drawContext === this.context, 'redrawEnd: call redrawStart() first');
 
         // set stuff back to normal, the camera first, so a target that was drawing before gets its own transform back
         [drawContext, mainCanvasSize, cameraPos, cameraScale, cameraAngle, canvasClearColor, glCustomShader] = this.savedRenderSettings;
@@ -1085,9 +1085,9 @@ class TileCollisionLayer extends TileLayer
         for (let y = y0; y < y1; ++y)
         for (let x = x0; x < x1; ++x)
         {
-            if (!this.collisionData[y*size.x + x]) continue;
+            if (!(this.collisionData[y*size.x + x] > 0)) continue; // solid is positive, a negative is a marker
             let end = x + 1; // a run of solid cells along the row
-            while (end < x1 && this.collisionData[y*size.x + end]) ++end;
+            while (end < x1 && this.collisionData[y*size.x + end] > 0) ++end;
             const count = end - x;
             const tileInfo = new TileInfo(vec2(x*cellPixels.x, textureHeight - (y+1)*cellPixels.y),
                 vec2(count*cellPixels.x, cellPixels.y), this.textureInfo, 0, 0);
@@ -1217,7 +1217,14 @@ class TileCollisionLayer extends TileLayer
         const hitPos = lineTest(t0 ? a.add(d.scale(t0)) : a, t1 < 1 ? a.add(d.scale(t1)) : posEnd.subtract(offset),
             testFunction, normal);
         if (hitPos)
+        {
+            // into the world, kept inside its tile there too, as adding the layer's place can round it onto the edge
+            const cell = hitPos.floor();
             hitPos.x += offset.x, hitPos.y += offset.y;
+            const inside = (v, low)=> v < low ? low : v < low + 1 ? v : low + 1 - max(1e-9, abs(low) * 1e-15);
+            hitPos.x = inside(hitPos.x, cell.x + offset.x);
+            hitPos.y = inside(hitPos.y, cell.y + offset.y);
+        }
         if (debugRaycast && hitPos)
         {
             const tilePos = hitPos.floor().add(vec2(.5));

package/src/engineUtilities.js

@@ -29,7 +29,7 @@ class Timer
      *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
     constructor(timeLeft, useRealTime=false)
     {
-        ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Constructed Timer is invalid.', timeLeft);
+        ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Timer: time must be a number of seconds', timeLeft);
         this.useRealTime = useRealTime;
         const globalTime = this.getGlobalTime();
         /** @type {number|undefined} */
@@ -42,7 +42,7 @@ class Timer
      *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds */
     set(timeLeft=0)
     {
-        ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
+        ASSERT(isNumber(timeLeft), 'Timer.set: time must be a number of seconds', timeLeft);
         const globalTime = this.getGlobalTime();
         this.time = globalTime + timeLeft;
         this.setTime = timeLeft;
@@ -121,9 +121,9 @@ function formatTime(t)
  *  @memberof Utilities */
 async function fetchJSON(url)
 {
-    const response = await fetch(url);
+    const response = await loadFetch(url, 'fetchJSON');
     if (!response.ok)
-        throw new Error(`Failed to fetch JSON from ${url}: ${response.status} ${response.statusText}`);
+        throw new Error(`fetchJSON: could not load ${url}, HTTP ${response.status} ${response.statusText}`);
     const text = await response.text();
     let json;
     try { json = JSON.parse(text); }
@@ -140,6 +140,21 @@ async function fetchJSON(url)
 // is a file's text a web page, as a dev server sends for a path it does not have
 const loadIsWebPage = (text)=> /^\s*</.test(text);
 
+// fetch a file for a loader, a failure to reach it named with the file and who asked, and with the usual cause when
+// the page was opened from a file on disk, where the browser lets it load nothing
+async function loadFetch(url, who)
+{
+    try { return await fetch(url); }
+    catch (error)
+    {
+        const fromDisk = globalThis.location?.protocol === 'file:';
+        const failed = new Error(`${who}: could not load ${url}, ${error.message}` + (fromDisk ?
+            ', the page was opened from a file, serve it from a local web server' : ''));
+        /** @type {any} */ (failed).cause = error; // what the browser said, as the error option newer libraries know
+        throw failed;
+    }
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Save a text file to disk
@@ -249,7 +264,7 @@ function readSaveData(saveName, defaultSaveData)
         if (data)
         {
             try { loadedData = JSON.parse(data); }
-            catch { LOG('readSaveData: corrupt JSON for', saveName, '— using defaults'); }
+            catch { console.warn('readSaveData: the save ' + saveName + ' can not be read, using the defaults'); }
             if (!loadedData || typeof loadedData !== 'object' || isArray(loadedData))
                 loadedData = {}; // only an object of saved values, never a string spread into its letters
         }
@@ -268,9 +283,26 @@ function writeSaveData(saveName, saveData)
     ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
     ASSERT(typeof saveData === 'object' && saveData !== null && !isArray(saveData),
         'writeSaveData: save data must be an object, readSaveData reads it back into one');
-    // tolerate localStorage being unavailable or quota exceeded
-    try { localStorage.setItem(saveName, JSON.stringify(saveData)); return true; }
-    catch { LOG('writeSaveData: failed to write', saveName); return false; }
+    // tolerate localStorage being unavailable or quota exceeded; in release too, a player's save going nowhere is
+    // not silent, and the warning says which it was
+    let text;
+    try { text = JSON.stringify(saveData); }
+    catch (error)
+    {
+        console.warn('writeSaveData: the save ' + saveName + ' can not be written as JSON, ' + error.message);
+        return false;
+    }
+    if (text === undefined) // a toJSON that returns nothing, which would be stored as the text undefined
+    {
+        console.warn('writeSaveData: the save ' + saveName + ' is nothing as JSON, it is not written');
+        return false;
+    }
+    try { localStorage.setItem(saveName, text); return true; }
+    catch
+    {
+        console.warn('writeSaveData: the save ' + saveName + ' could not be written, storage is full or off');
+        return false;
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -298,7 +330,7 @@ function noise1D(x)
     return lerp(noiseHash(i), noiseHash(i + 1), smoothStep(x - i));
 }
 
-/** 2D value noise — returns a smooth value in [0, 1] for any real (x, y).
+/** 2D value noise — returns a smooth value in [0, 1] for any real (x, y)
  *  @param {number} x
  *  @param {number} y
  *  @return {number}

package/src/engineWebGL.js

@@ -45,7 +45,7 @@ function glClampTextureSize(size) { return glMaxTextureSize ? min(size, glMaxTex
 let glAntialias = true;
 
 // WebGL internal variables not exposed to documentation
-let glMipmappedTextures = new WeakSet, glMipmapsUntilTarget = new WeakSet, glMipmapsStale = new Set, glPremultipliedTextures = new WeakSet, glShaderPremultiplied, glEnableBeforeLoss = true, glShader, glPolyShader, glPolyMode, glAdditive, glBatchAdditive, glActiveTexture, glArrayBuffer, glGeometryBuffer, glPositionData, glColorData, glBatchCount, glTextureInfos = new Set, glInstancedVAO, glPolyVAO, glFramebuffer, glRenderTarget, glShaderObjects = [], glCustomShader, glBatchShader, glProgramCustom, glTransform, glRenderTargetSaved, glUniformLocations = new WeakMap, glCanBeEnabled = true;
+let glMipmappedTextures = new WeakSet, glMipmapsUntilTarget = new WeakSet, glMipmapsStale = new Set, glPremultipliedTextures = new WeakSet, glShaderPremultiplied, glEnableBeforeLoss = true, glShader, glPolyShader, glPolyMode, glAdditive, glBatchAdditive, glActiveTexture, glArrayBuffer, glGeometryBuffer, glPositionData, glColorData, glBatchCount, glTextureInfos = new Set, glInstancedVAO, glPolyVAO, glFramebuffer, glRenderTarget, glShaderObjects = [], glCustomShader, glBatchShader, glProgramCustom, glTransform, glRenderTargetSaved, glUniformLocations = new WeakMap, glCanBeEnabled = true, glDeviceFailed = false;
 let glFailedPrograms = new WeakSet; // programs that did not build in a release build, which nothing draws with
 // ANDed onto every packed color as a draw is queued; the light system's shadow pass sets 0xff000000
 // to draw everything black with its alpha kept (rgbaInt packs alpha in the top byte)
@@ -120,6 +120,7 @@ function glInit(rootElement)
         glCanvas = glContext = undefined;
         glEnable = false;
         glCanBeEnabled = false;
+        glDeviceFailed = true; // the device, not the game, turned it off
         return;
     }
 
@@ -224,6 +225,7 @@ function glInit(rootElement)
         {
             console.error('LittleJS: WebGL can not draw on this device, using Canvas2D');
             glEnable = glCanBeEnabled = false;
+            glDeviceFailed = true;
             glCanvas.style.display = 'none';
         }
 
@@ -505,6 +507,7 @@ function glUniformLocation(program, name)
 // color, then the sprite's color and additive color apply as the engine's own fragment shader does
 function glShaderProgram(shader)
 {
+    shader.program || glShaderTrack(shader);
     const program = shader.program ||= glCreateProgram(gl_VERTEX_SOURCE,
         '#version 300 es\n' +
         'precision highp float;' +
@@ -512,13 +515,33 @@ function glShaderProgram(shader)
         'uniform vec3 iResolution;' +    // canvas size in pixels
         'uniform float iTime;' +         // engine time
         'uniform bool premultipliedTexture;' + // is the texture premultiplied, a render target or a smooth image
-        'in vec2 v,l;in vec4 d,e;out vec4 c;\n' + // a define needs its own line
+        'in vec2 v,l;in vec4 d,e;out vec4 c;' +
+        // main first, the snippet's mainImage declared for it, so a define in the snippet can not reach main's names
+        'void mainImage(out vec4,vec2);' +
+        'void main(){vec4 t;mainImage(t,v);' + gl_FRAGMENT_TINT_SOURCE + '}\n' + // a define needs its own line
         '#define localUV l\n' +
-        shader.fragmentCode + '\n' +
-        'void main(){vec4 t;mainImage(t,v);' + gl_FRAGMENT_TINT_SOURCE + '}');
+        shader.fragmentCode + '\n');
     return glFailedPrograms.has(program) ? glShader : program;
 }
 
+// a Shader compiled again after dispose is kept for a lost context again
+function glShaderTrack(shader) { glShaderObjects.includes(shader) || glShaderObjects.push(shader); }
+
+// let go of a Shader's programs, 2D and 3D, and of its place in the list; a batch drawing with it is drawn first
+function glShaderDispose(shader)
+{
+    const i = glShaderObjects.indexOf(shader);
+    i < 0 || glShaderObjects.splice(i, 1);
+    if (glContext && !headlessMode)
+    {
+        if (glBatchShader === shader) // a batch drawing with it is drawn first, the batch holds the Shader
+            glFlush();
+        for (const program of [shader.program, shader.program3D])
+            program && glContext.deleteProgram(program);
+    }
+    shader.program = shader.program3D = undefined;
+}
+
 /** Create WebGL texture from an image and init the texture settings
  *  Restores the active texture when done
  *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} [image]
@@ -574,8 +597,16 @@ function glCreateTexture(image, wrap=false, pixelated=tilesPixelated)
  *  @memberof WebGL */
 function glDeleteTexture(texture)
 {
-    if (!glContext) return;
-    
+    if (!glContext || !texture) return;
+
+    // what is batched with it is drawn first, since deleting unbinds it, and nothing keeps it after
+    if (texture === glActiveTexture)
+    {
+        glFlush();
+        glActiveTexture = undefined; // so nothing binds the deleted texture again
+    }
+    glMipmapsStale.delete(texture);
+    glPremultipliedTextures.delete(texture);
     glContext.deleteTexture(texture);
 }
 
@@ -651,13 +682,6 @@ function glUnregisterTextureInfo(textureInfo)
     // unset and destroy the texture, drawing what is batched with it first, since deleting unbinds it
     const glTexture = textureInfo.glTexture;
     textureInfo.glTexture = undefined;
-    if (glTexture && glTexture === glActiveTexture)
-    {
-        glFlush();
-        glActiveTexture = undefined; // so nothing binds the deleted texture again
-    }
-    glMipmapsStale.delete(glTexture);
-    glPremultipliedTextures.delete(glTexture);
     glDeleteTexture(glTexture);
 }