littlejsengine 1.24.2 → 1.25.0

package/src/engineParticles.js

@@ -37,13 +37,13 @@
  * let pos = vec2(2,3);
  * let particleEmitter = new ParticleEmitter
  * (
- *     pos, 0, 1, 0, 500, PI,      // pos, angle, emitSize, emitTime, emitRate, emitCone
+ *     pos, 0, 1, 0, 500, PI,      // pos, angle, emitSize, emitTime, emitRate, emitConeAngle
  *     tile(0, 16),                // tileInfo
  *     rgb(1,1,1,1), rgb(0,0,0,1), // colorStartA, colorStartB
  *     rgb(1,1,1,0), rgb(0,0,0,0), // colorEndA, colorEndB
- *     1, .2, .2, .1, .05,  // particleTime, sizeStart, sizeEnd, particleSpeed, particleAngleSpeed
- *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleCone, fadeRate
- *     .5, true             // randomness, collide
+ *     1, .2, .2, .1, .05,  // particleTime, sizeStart, sizeEnd, speed, angleSpeed
+ *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleConeAngle, fadeRate
+ *     .5, true             // randomness, collideLevel
  * );
  */
 class ParticleEmitter extends EngineObject
@@ -336,7 +336,8 @@ class ParticleEmitter extends EngineObject
         this.additive && setAdditiveBlendMode(false);
     }
 
-    /** is emitter actively spawning */
+    /** is emitter actively spawning
+     *  @return {boolean} */
     isActive() { return !this.emitTime || this.getAliveTime() < this.emitTime; }
 
     /** Destroy the particle emitter
@@ -548,8 +549,8 @@ class Particle
                 }
                 if (isBlockedY || !isBlockedX)
                 {
-                    // down is the world's gravity, or the emitter's own fall in a world with none
-                    const down = gravity.y || emitter.gravity || 0;
+                    // down is the way it falls, the world's gravity by its gravityScale and the emitter's own
+                    const down = gravityY;
                     const wasFalling = this.velocity.y < 0 && down < 0 || this.velocity.y > 0 && down > 0;
                     if (wasFalling)
                         this.groundObject = hitLayer;

package/src/engineRelease.js

@@ -10,18 +10,17 @@
 
 'use strict';
 
-let debugWatermark = 0;
+let debugWatermark = false;
 let debugKey = '';
 let debugKeysAlways = false;
 let debugTweakables = false;
-let debugClearCount = 0;
-const debug = 0;
-const debugOverlay = 0;
-const debugPhysics = 0;
-const debugParticles = 0;
-const debugRaycast = 0;
-const debugGamepads = 0;
-const debugSound = 0;
+const debug = false;
+const debugOverlay = false;
+const debugPhysics = false;
+const debugParticles = false;
+const debugRaycast = false;
+const debugGamepads = false;
+const debugSound = false;
 const debugPointSize = .5;
 
 // debug commands are automatically removed from the final build
@@ -52,6 +51,14 @@ function tweak(){}
 function tweakButton(){}
 function tweakDivider(){}
 function tweakEngineDefaults(){}
+// the 2D editor's edit functions in a release build, which has no editor: there is nothing to edit and nothing
+// changes, and a game that calls them needs no guard; edit3D stays undefined, as it is with no 3D plugins
+const editorEdit2DRelease =
+{
+    map: undefined, layer: undefined, hover: undefined, get objects() { return []; }, get selection() { return new Set; },
+    paint(){ return false; }, changeObjects(){ return false; }, strokeEnd(){}, strokeCancel(){}, bulk(){},
+    undo(){ return false; }, toJSON(){ return ''; },
+};
 class LevelEditor
 {
     constructor()
@@ -61,7 +68,7 @@ class LevelEditor
     }
     get isOpen() { return false; }
     get is3D() { return false; }
-    get edit2D() { return undefined; }
+    get edit2D() { return editorEdit2DRelease; }
     get edit3D() { return undefined; }
     open(){} close(){} addKey(){} addButton(){} addTool(){}
     onTile(){} onRestart(){} onPlayFrom(){} onOpen(){} onClose(){} onUpdate(){} onDraw(){} onPanel(){}

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 */
@@ -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)

package/src/engineUtilities.js

@@ -117,18 +117,29 @@ 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);
     if (!response.ok)
         throw new Error(`Failed to fetch JSON from ${url}: ${response.status} ${response.statusText}`);
-    const json = await response.json();
+    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);
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Save a text file to disk
@@ -239,6 +250,8 @@ function readSaveData(saveName, defaultSaveData)
         {
             try { loadedData = JSON.parse(data); }
             catch { LOG('readSaveData: corrupt JSON for', saveName, '— using 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'); }

package/src/engineWebGL.js

@@ -46,11 +46,12 @@ 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 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
@@ -218,6 +219,14 @@ 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;
+            glCanvas.style.display = 'none';
+        }
+
         // init buffers
         const glInstanceData = new ArrayBuffer(gl_ARRAY_BUFFER_SIZE);
         glPositionData = new Float32Array(glInstanceData);
@@ -436,7 +445,7 @@ function glSetTextureWrap(texture, wrap=true)
 /** Compile WebGL shader of the given type, will throw errors if in debug mode
  *  @param {string} source
  *  @param {number} type
- *  @return {WebGLShader}
+ *  @return {WebGLShader|undefined} - undefined with no WebGL
  *  @memberof WebGL */
 function glCompileShader(source, type)
 {
@@ -456,7 +465,7 @@ function glCompileShader(source, type)
 /** Create WebGL program with given shaders
  *  @param {string} vsSource
  *  @param {string} fsSource
- *  @return {WebGLProgram}
+ *  @return {WebGLProgram|undefined} - undefined with no WebGL
  *  @memberof WebGL */
 function glCreateProgram(vsSource, fsSource)
 {
@@ -464,13 +473,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,7 +505,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)
 {
-    return shader.program ||= glCreateProgram(gl_VERTEX_SOURCE,
+    const program = shader.program ||= glCreateProgram(gl_VERTEX_SOURCE,
         '#version 300 es\n' +
         'precision highp float;' +
         'uniform sampler2D iChannel0;' + // the texture
@@ -497,6 +516,7 @@ function glShaderProgram(shader)
         '#define localUV l\n' +
         shader.fragmentCode + '\n' +
         'void main(){vec4 t;mainImage(t,v);' + gl_FRAGMENT_TINT_SOURCE + '}');
+    return glFailedPrograms.has(program) ? glShader : program;
 }
 
 /** Create WebGL texture from an image and init the texture settings
@@ -504,7 +524,7 @@ function glShaderProgram(shader)
  *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} [image]
  *  @param {boolean|Array<number>} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE, or the WebGL modes across and down
  *  @param {boolean} [pixelated] - Hard edged or smooth, undefined follows tilesPixelated
- *  @return {WebGLTexture}
+ *  @return {WebGLTexture|undefined} - undefined with no WebGL
  *  @memberof WebGL */
 function glCreateTexture(image, wrap=false, pixelated=tilesPixelated)
 {
@@ -673,6 +693,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 +752,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)
 {