littlejsengine 1.24.3 → 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

@@ -7,7 +7,7 @@
  * - TileLayer for rendering, TileCollisionLayer for physics
  * - Collision callbacks for tile interactions with objects
  * - Optimized raycast support for tile-based physics
- * - Integration with Box2D physics via Box2DTileLayer plugin
+ * - Integration with Box2D physics via the Box2dTileLayer plugin
  * @namespace TileLayers
  */
 
@@ -16,6 +16,28 @@
 ///////////////////////////////////////////////////////////////////////////////
 // Tile Layer System
 
+/** A Tiled map as Tiled saves it as JSON, what tileLayersLoad and objectLayersLoad take and tileLayersFromLDtk
+ *  makes; the fields read are listed, and the rest of the file is kept as it is
+ *  @typedef {Object} TiledMap
+ *  @property {number} width - Cells across
+ *  @property {number} height - Cells up
+ *  @property {number} [tilewidth] - A tile's width in pixels
+ *  @property {number} [tileheight] - A tile's height in pixels
+ *  @property {Array<Object>} layers - Tile layers, object layers and groups of them, bottom first
+ *  @property {Array<Object>} [tilesets] - The first one's margin, spacing and columns are read
+ *  @property {number} [nextlayerid]
+ *  @property {number} [nextobjectid]
+ *  @property {string} [orientation]
+ *  @property {string} [renderorder]
+ *  @property {boolean} [infinite]
+ *  @property {string} [type]
+ *  @property {string|number} [version] - A number in files from Tiled before 1.6
+ *  @property {string} [tiledversion]
+ *  @property {number} [compressionlevel]
+ *  @property {string} [backgroundcolor]
+ *  @property {Array<Object>} [properties]
+ *  @memberof TileLayers */
+
 /** Keep track of all tile layers with collision
  *  @type {Array<TileCollisionLayer>}
  *  @memberof TileLayers */
@@ -90,7 +112,7 @@ function tileCollisionTest(pos, size=vec2(), callbackObject, solidOnly=true)
  *  @param {Vector2} posEnd
  *  @param {EngineObject|TileCollisionCallback} [callbackObject] - Callback, engine object, or undefined
  *  @param {Vector2} [normal] - Optional normal of the surface hit
- *  @param {boolean} [solidOnly=true] - Only check solid layers?
+ *  @param {boolean} [solidOnly] - Only check solid layers?
  *  @return {Vector2|undefined} - where the ray meets the first tile hit, nudged just inside it, or undefined if no hit
  *  @memberof TileLayers */
 function tileCollisionRaycast(posStart, posEnd, callbackObject, normal, solidOnly=true)
@@ -151,7 +173,7 @@ function tileLayerTileInfo(t, tile)
  * - An object or image layer keeps its index, with its slot in the returned array left empty
  * - A hidden layer (visible false) is loaded, its collision included, but not drawn; its render
  *   is a no-op, delete that and call redraw() to show it
- *  @param {Object}   tileMapData - Level data from exported data
+ *  @param {TiledMap} [tileMapData] - Level data from exported data, a 50 by 50 empty level when left out
  *  @param {TileInfo} [tileInfo] - Default tile info (used for size and texture), tile() by default, none when no image is loaded
  *  @param {number}   [renderOrder] - Render order of the top layer
  *  @param {number|string} [collisionLayer] - Layer to use for collision if any, by its index or its name
@@ -165,10 +187,7 @@ function tileLayersLoad(tileMapData, tileInfo=tileLayerDefaultTile(), renderOrde
     {
         // default level data if loading failed
         const s = 50;
-        tileMapData = {};
-        tileMapData.height = tileMapData.width = s;
-        tileMapData.layers = [{}];
-        tileMapData.layers[0].data = new Array(s*s).fill(0);
+        tileMapData = {width: s, height: s, layers: [{data: new Array(s*s).fill(0)}]};
     }
 
     // the editor, in debug builds, keeps the map as the source of its edits and brings back autosaved ones
@@ -310,7 +329,7 @@ const tileLayersLDtkTypes = {Int: 'int', Float: 'float', Bool: 'bool', String: '
  * - The level editor edits the map this returns, and saves it as a Tiled map
  * @param {Object} ldtk - The LDtk project, its JSON
  * @param {number|string} [level] - Which level, by its index or its identifier
- * @return {Object} - A Tiled map: width, height, tilewidth, tileheight, tilesets and layers
+ * @return {TiledMap} - A Tiled map: width, height, tilewidth, tileheight, tilesets and layers
  * @example
  * const map = tileLayersFromLDtk(await fetchJSON('world.ldtk'), 'Level_0');
  * const layers = tileLayersLoad(map, tile(0, 16), 0, 'Collisions'); // its IntGrid layer is solid
@@ -441,7 +460,7 @@ const objectLayersTypes = new Map;
  *  - Adding a name again replaces it
  *  @param {string} name - The type the objects have in Tiled
  *  @param {Function} make - A class made at each object's position, or a function called with it
- *  @param {Object} [defaults] - Properties set on each one made, the level editor shows inputs for them
+ *  @param {Object<string, any>} [defaults] - Properties set on each one made, the level editor shows inputs for them
  *  @param {TileInfo} [tileInfo] - An icon for the level editor
  *  @memberof TileLayers
  *  @example
@@ -462,7 +481,7 @@ function objectLayersAddType(name, make, defaults={}, tileInfo)
  *  - The object's properties in Tiled are set over the type's defaults: numbers, booleans, strings, and colors,
  *    and for a Vector2 default the string x,y
  *  - An object whose type was not added is skipped, with a warning in debug builds
- *  @param {Object} tileMapData - The same Tiled map given to tileLayersLoad
+ *  @param {TiledMap} tileMapData - The same Tiled map given to tileLayersLoad
  *  @return {Array<any>} - What each object's type made, a function that made nothing is left out
  *  @memberof TileLayers */
 function objectLayersLoad(tileMapData)
@@ -556,7 +575,7 @@ class TileLayerData
     /** Create a tile layer data object, one for each tile in a TileLayer
      *  @param {number}  [tile] - The tile to use, from 0 like tile(); undefined is an empty cell that draws nothing
      *  @param {number}  [direction] - Integer direction of tile, in 90 degree increments
-     *  @param {boolean} [mirror] - If the tile should be mirrored along the x axis
+     *  @param {boolean} [mirror] - If the tile is flipped left to right
      *  @param {Color}   [color] - Color of the tile */
     constructor(tile, direction=0, mirror=false, color=new Color)
     {
@@ -565,7 +584,7 @@ class TileLayerData
         this.tile = tile;
         /** @property {number} - Integer direction of tile, in 90 degree increments */
         this.direction = direction;
-        /** @property {boolean} - If the tile should be mirrored along the x axis */
+        /** @property {boolean} - If the tile is flipped left to right */
         this.mirror = mirror;
         /** @property {Color} - Color of the tile */
         this.color = color.copy();
@@ -641,7 +660,7 @@ class CanvasLayer extends EngineObject
     *  @param {Vector2} [size] - Size in world space
     *  @param {Color}   [color] - Color to modulate with
     *  @param {number}  [angle] - Angle to rotate by
-    *  @param {boolean} [mirror] - If true image is flipped along the Y axis
+    *  @param {boolean} [mirror] - If true the image is flipped left to right
     *  @param {Color}   [additiveColor] - Additive color to be applied if any
     *  @param {boolean} [screenSpace=drawScreenSpace] - If true the pos and size are in screen space
     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to */
@@ -825,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
@@ -870,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;
@@ -931,7 +950,7 @@ class TileLayer extends CanvasLayer
      *  @param {TileInfo} [tileInfo] - Tile info to use, untextured if undefined
      *  @param {Color}    [color=WHITE] - Color to modulate with
      *  @param {number}   [angle] - Angle to rotate by
-     *  @param {boolean}  [mirror] - Is image flipped along the Y axis?
+     *  @param {boolean}  [mirror] - Is the image flipped left to right?
      *  @param {Color}    [additiveColor] - Additive color to be applied if any */
     drawLayerTile(pos, size=vec2(1), tileInfo, color=WHITE,
     angle=0, mirror, additiveColor)
@@ -1066,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);
@@ -1198,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;
@@ -117,18 +117,44 @@ function formatTime(t)
 
 /** Fetches a JSON file from a URL and returns the parsed JSON object. Must be used with await!
  *  @param {string} url - URL of JSON file
- *  @return {Promise<object>}
+ *  @return {Promise<any>} - The parsed JSON, any shape, as response.json() gives it
  *  @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}`);
-    const json = await response.json();
+        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); }
+    catch (e)
+    {
+        // a dev server answers a mistyped path with its own page, which is no JSON, so the error says which file
+        throw new Error(`fetchJSON: ${url} is not JSON` + (loadIsWebPage(text) ?
+            ', it is a web page, so the path may be wrong' : ': ' + e.message));
+    }
     editorJSONFetched(url, json); // debug builds remember the file a level came from, to save it by that name
     return json;
 }
 
+// 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
@@ -238,7 +264,9 @@ 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
         }
     }
     catch { LOG('readSaveData: localStorage unavailable — using defaults'); }
@@ -255,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;
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -285,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,12 +45,13 @@ 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)
 let glColorMask = -1;
 // ORed onto the additive color of every quad and onto every poly point's color as a draw is queued; the light system's
-// emissive pass sets a grey with the mask at 0xff000000, so a draw comes out that grey in its own shape
+// emissive pass sets a gray with the mask at 0xff000000, so a draw comes out that gray in its own shape
 let glColorAdditive = 0;
 // a texture drawn into with the canvas's own transform and its size, the light system's lightmap while its pass
 // runs: a target set and ended inside it, like a tile layer redrawn in a renderLight, goes back to it, not the canvas
@@ -119,6 +120,7 @@ function glInit(rootElement)
         glCanvas = glContext = undefined;
         glEnable = false;
         glCanBeEnabled = false;
+        glDeviceFailed = true; // the device, not the game, turned it off
         return;
     }
 
@@ -218,6 +220,15 @@ function glInit(rootElement)
             '}'                       // end of shader
         );
 
+        // a device that can not build the engine's own programs draws with Canvas2D, as after a lost context
+        if (glFailedPrograms.has(glShader) || glFailedPrograms.has(glPolyShader))
+        {
+            console.error('LittleJS: WebGL can not draw on this device, using Canvas2D');
+            glEnable = glCanBeEnabled = false;
+            glDeviceFailed = true;
+            glCanvas.style.display = 'none';
+        }
+
         // init buffers
         const glInstanceData = new ArrayBuffer(gl_ARRAY_BUFFER_SIZE);
         glPositionData = new Float32Array(glInstanceData);
@@ -464,13 +475,23 @@ function glCreateProgram(vsSource, fsSource)
 
     // build the program
     const program = glContext.createProgram();
-    glContext.attachShader(program, glCompileShader(vsSource, glContext.VERTEX_SHADER));
-    glContext.attachShader(program, glCompileShader(fsSource, glContext.FRAGMENT_SHADER));
+    const vertexShader = glCompileShader(vsSource, glContext.VERTEX_SHADER);
+    const fragmentShader = glCompileShader(fsSource, glContext.FRAGMENT_SHADER);
+    glContext.attachShader(program, vertexShader);
+    glContext.attachShader(program, fragmentShader);
     glContext.linkProgram(program);
 
-    // check for errors
-    if (debug && !glContext.getProgramParameter(program, glContext.LINK_STATUS))
-        throw glContext.getProgramInfoLog(program);
+    // check for errors in every build, as a driver may refuse what another takes: a debug build throws, a release
+    // one says why once and marks the program, which the engine's draws then do without
+    if (!glContext.getProgramParameter(program, glContext.LINK_STATUS))
+    {
+        const log = glContext.getProgramInfoLog(program) + '\n' +
+            glContext.getShaderInfoLog(vertexShader) + glContext.getShaderInfoLog(fragmentShader);
+        if (debug)
+            throw log;
+        console.error('LittleJS: a shader failed to build\n' + log);
+        glFailedPrograms.add(program);
+    }
     return program;
 }
 
@@ -486,17 +507,39 @@ 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)
 {
-    return shader.program ||= glCreateProgram(gl_VERTEX_SOURCE,
+    shader.program || glShaderTrack(shader);
+    const program = shader.program ||= glCreateProgram(gl_VERTEX_SOURCE,
         '#version 300 es\n' +
         'precision highp float;' +
         'uniform sampler2D iChannel0;' + // the texture
         '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
@@ -554,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);
 }
 
@@ -631,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);
 }
 
@@ -673,6 +717,8 @@ function glFlush()
                 const height = glRenderTarget ? mainCanvasSize.y : glCanvas.height;
                 glContext.uniform3f(uniform('iResolution'), width, height, 1);
                 glContext.uniform1i(uniform('premultipliedTexture'), +premultiplied);
+                if (program === glShader)
+                    glShaderPremultiplied = premultiplied; // a Shader that did not build draws with the engine's
             }
         }
         if (!glPolyMode && !glBatchShader && glShaderPremultiplied !== premultiplied)
@@ -730,8 +776,8 @@ function glSetAntialias(antialias=true)
  *  @param {number} [uv0Y]
  *  @param {number} [uv1X]
  *  @param {number} [uv1Y]
- *  @param {number} [rgba=-1] - white is -1
- *  @param {number} [rgbaAdditive=0] - black is 0
+ *  @param {number} [rgba] - white is -1
+ *  @param {number} [rgbaAdditive] - black is 0
  *  @memberof WebGL */
 function glDraw(x, y, sizeX, sizeY, angle=0, uv0X=0, uv0Y=0, uv1X=1, uv1Y=1, rgba=-1, rgbaAdditive=0)
 {