littlejsengine 1.24.3 → 1.25.0

package/src/engineEditor.js

@@ -14,7 +14,7 @@
 
 /**
  *  @callback EditorPlayFromCallback - Puts the player at a world position, for the level editor's Play from mouse
- *  @param {Vector2} pos - Where to start playing
+ *  @param {any} pos - Where to start playing, a Vector2 from the 2D editor and a Vector3 from the 3D one
  *  @memberof Editor
  */
 
@@ -32,25 +32,29 @@
  */
 
 /**
- *  @typedef {Object} EditorToolAt - What the level editor gives the callbacks of a tool of the game's own
- *  @property {any} pos - Where the mouse is in the level: a Vector2 in the 2D editor; in the 3D one a Vector3 on
+ *  @template [P=Vector2]
+ *  @typedef {Object} EditorToolAt - What the level editor gives the callbacks of a tool of the game's own; P is
+ *    the type of pos, a Vector2 for a 2D tool, the default, and Vector3|undefined for a 3D one
+ *  @property {P} pos - Where the mouse is in the level: a Vector2 in the 2D editor; in the 3D one a Vector3 on
  *    the level or the ground, undefined when the mouse is over the panel
  *  @property {Vector2|undefined} cell - 2D: the tile cell under the mouse on the selected tile layer
- *  @property {any} ray - 3D: the mouse's Ray3D
+ *  @property {Ray3D|undefined} ray - 3D: the mouse's Ray3D
  *  @property {boolean} shift - Is Shift held
  *  @property {boolean} ctrl - Is Ctrl held
  *  @memberof Editor
  */
 
 /**
- *  @typedef {Object} EditorTool - A tool of the game's own for the level editor, see LevelEditor.addTool
+ *  @template [P=Vector2]
+ *  @typedef {Object} EditorTool - A tool of the game's own for the level editor, see LevelEditor.addTool; P is the
+ *    type of its pos, as EditorToolAt has it
  *  @property {string} [key] - The key that picks it, as addKey spells one
  *  @property {string} [hint] - The hint line while it is on
- *  @property {function(EditorToolAt): any} [onPress] - The left button went down in the level; returning false
+ *  @property {function(EditorToolAt<P>): any} [onPress] - The left button went down in the level; returning false
  *    says the press was not the tool's
- *  @property {function(EditorToolAt): any} [onDrag] - Each frame it is held
- *  @property {function(EditorToolAt): any} [onRelease] - It was let go
- *  @property {function(EditorToolAt): any} [onDraw] - Each frame the tool is on, to draw its cursor or preview
+ *  @property {function(EditorToolAt<P>): any} [onDrag] - Each frame it is held
+ *  @property {function(EditorToolAt<P>): any} [onRelease] - It was let go
+ *  @property {function(EditorToolAt<P>): any} [onDraw] - Each frame the tool is on, to draw its cursor or preview
  *  @memberof Editor
  */
 
@@ -143,7 +147,7 @@ class LevelEditor
         this.keys = {};
         /** @type {Array<{label: string, onClick: Function, title: string}>} */
         this.buttons = [];
-        /** @type {Object<string, EditorTool>} */
+        /** @type {Object<string, EditorTool<any>>} */
         this.tools = {};
     }
 
@@ -161,7 +165,7 @@ class LevelEditor
 
     /** Put the player at a position, a Vector2 in the 2D editor and a Vector3 in the 3D one; set it or override it
      *  and the editor has Play from mouse, which starts play there
-     *  @param {any} pos */
+     *  @param {any} pos - A Vector2 from the 2D editor, a Vector3 from the 3D one */
     onPlayFrom(pos) {}
 
     /** Called when the editor opens, to set or override */
@@ -244,8 +248,9 @@ class LevelEditor
      *    in 3D
      *  - What the callbacks change through edit2D or edit3D is one undo: the editor ends the stroke at the release,
      *    and takes it back when the right button or Escape ends the press
+     *  @template [P=Vector2]
      *  @param {string} name
-     *  @param {EditorTool} tool - {key, hint, onPress, onDrag, onRelease, onDraw}, each optional; onPress returning
+     *  @param {EditorTool<P>} tool - {key, hint, onPress, onDrag, onRelease, onDraw}, each optional; onPress returning
      *    false says the press was not the tool's */
     addTool(name, tool)
     {
@@ -260,7 +265,10 @@ class LevelEditor
     open()
     {
         if (editorOther?.wanted())
-            return editorOther.open();
+        {
+            editorOther.open();
+            return;
+        }
         if (!editorSession)
             editorCameraScale = cameraScale; // a new session starts at the game's zoom, a return keeps the editor's
         editorSession = true;
@@ -272,7 +280,10 @@ class LevelEditor
     close()
     {
         if (editorOther?.active())
-            return editorOther.close();
+        {
+            editorOther.close();
+            return;
+        }
         editorSession = false;
         editorSetOpen(false);
     }
@@ -1084,6 +1095,8 @@ let editorStroke;
 
 // during a big edit, the layers whose cell by cell redraws are held off, with the redraw each had of its own
 let editorHeldRedraws;
+// the live layers a change can only show by drawing them again whole, drawn when it is done
+const editorRedrawWhole = new Set;
 
 // make a big edit, a fill, clear, undo, apply or revert, with each layer's cell by cell redraws held off, a game's
 // tile callback's included; the stroke's end draws each layer it touched again whole
@@ -1110,6 +1123,11 @@ function editorSetCell(layer, pos, gid)
     source.data[index] = gid;
     if (live.destroyed) return before; // a layer the game let go of, the map still has the change
 
+    // a plain cell draws itself here; held draws, a game's onTile, which may change the cells around, and its own
+    // drawing over the layer show only when the whole layer draws again, once the change is done
+    if (editorHeldRedraws || editorHas('onTile') || live.onRedraw !== TileLayer.prototype.onRedraw)
+        editorRedrawWhole.add(live);
+
     if (editorHeldRedraws && !editorHeldRedraws.has(live))
     {
         editorHeldRedraws.set(live, live.hasOwnProperty('redrawTileData') ? live.redrawTileData : undefined);
@@ -1187,8 +1205,7 @@ function editorUndo(redo=false)
     editorChanged(stroke);
 }
 
-// after a change the tile layers it touched draw again whole, so a game's onRedraw decoration sees the new tiles,
-// and the maps it touched are autosaved; a resized map is made again by the game, with the editor staying open
+// after a change the tile layers it touched that need it draw again whole, and the maps it touched are autosaved; a resized map is made again by the game, with the editor staying open
 function editorChanged(stroke)
 {
     editorRedraw(stroke);
@@ -1197,11 +1214,11 @@ function editorChanged(stroke)
     stroke.some((entry)=> entry.resize) && editorHas('onRestart') && levelEditor.onRestart();
 }
 
-// the tile layers a stroke touched draw again whole
+// the tile layers a stroke touched that need it draw again whole
 function editorRedraw(stroke)
 {
     for (const layer of new Set(stroke.filter((entry)=> entry.layer).map((entry)=> entry.layer)))
-        layer.live.destroyed || layer.live.redraw();
+        editorRedrawWhole.delete(layer.live) && !layer.live.destroyed && layer.live.redraw();
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1708,6 +1725,40 @@ function editorGidMirror(gid)
     return t ? editorTileToGid(t.tile, (4 - t.direction) % 4, !t.mirror) : gid;
 }
 
+// a stamp's object turned a quarter clockwise with it: its place by the stamp, its body by its own rotation, which
+// Tiled turns clockwise about the object's place, so the place needs no other move
+function editorStampObjectTurn(entry, width)
+{
+    const offset = vec2(entry.offset.y, width - entry.offset.x), object = entry.object;
+    return {...entry, offset, ...(object && {object: {...object, rotation: ((object.rotation || 0) + 90) % 360}})};
+}
+
+// a stamp's object mirrored left to right with it: its rotation the other way, a polygon's points mirrored about its
+// place, a tile object's image flipped, and a box, ellipse, text or tile, placed by a corner, placed by the corner
+// that becomes it, its width along its turn from the mirrored place; mirrored twice it is as it was
+function editorStampObjectMirror(entry, width)
+{
+    const offset = vec2(width - entry.offset.x, entry.offset.y), object = entry.object;
+    if (!object) return {...entry, offset};
+    const mirrored = {...object, rotation: object.rotation ? -object.rotation : 0};
+    const points = (list)=> list.map((p)=> ({...p, x: -p.x}));
+    if (object.polygon || object.polyline)
+    {
+        object.polygon && (mirrored.polygon = points(object.polygon));
+        object.polyline && (mirrored.polyline = points(object.polyline));
+    }
+    else
+    {
+        // Tiled's pixels run down, the stamp's cells up
+        const angle = (object.rotation || 0) * PI / 180, w = object.width || 0, {x: tw, y: th} = entry.tileSize ?? vec2(1);
+        offset.x -= w * cos(angle) / tw;
+        offset.y -= w * sin(angle) / th;
+    }
+    if (object.gid)
+        mirrored.gid = (object.gid ^ 0x80000000) >>> 0; // Tiled's flip across
+    return {...entry, offset, object: mirrored};
+}
+
 // a stamp turned a quarter turn clockwise on screen, or back, its cells, their tiles and its objects together; cell
 // (x, y) goes to (y, width - 1 - x), so the bottom row becomes the left column, its left end at the top
 function editorStampTurn(stamp, back=false)
@@ -1715,7 +1766,7 @@ function editorStampTurn(stamp, back=false)
     for (let turns = back ? 3 : 1; turns--;)
     {
         const {width, height} = stamp;
-        const objects = stamp.objects?.map((object)=> ({...object, offset: vec2(object.offset.y, width - object.offset.x)}));
+        const objects = stamp.objects?.map((entry)=> editorStampObjectTurn(entry, width));
         stamp = {width: height, height: width, grids: stamp.grids.map((grid)=>
         {
             const turned = [];
@@ -1732,7 +1783,7 @@ function editorStampTurn(stamp, back=false)
 function editorStampMirror(stamp)
 {
     const {width, height} = stamp;
-    const objects = stamp.objects?.map((object)=> ({...object, offset: vec2(width - object.offset.x, object.offset.y)}));
+    const objects = stamp.objects?.map((entry)=> editorStampObjectMirror(entry, width));
     return {width, height, grids: stamp.grids.map((grid)=>
     {
         const mirrored = [];
@@ -1864,8 +1915,9 @@ function editorClear()
     editorStrokeEnd();
 }
 
-// the objects of a map's object layers inside a tile area, each {group, type, offset, object}: the index of its
-// object layer, its offset from the area's bottom left corner, and a copy of it, as a stamp keeps them
+// the objects of a map's object layers inside a tile area, each {group, type, offset, object, tileSize}: the index of
+// its object layer, its offset from the area's bottom left corner, a copy of it, and the map's tile size in pixels,
+// which a mirror reads its width in cells by, as a stamp keeps them
 function editorAreaObjects(layer, area)
 {
     const corner = layer.live.pos.add(area.min), far = layer.live.pos.add(area.max).add(vec2(1));
@@ -1874,7 +1926,7 @@ function editorAreaObjects(layer, area)
         const ids = new Set(editorObjectsIn(objectLayer, corner, far));
         return (objectLayer.group?.objects ?? []).filter((object)=> ids.has(object.id)).map((object)=>
             ({group, type: object.type || object.class, offset: editorObjectPos(layer.record, object).subtract(corner),
-            object: editorObjectsCopy(object)}));
+            object: editorObjectsCopy(object), tileSize: vec2(layer.record.map.tilewidth || 1, layer.record.map.tileheight || 1)}));
     });
 }
 

package/src/engineInput.js

@@ -248,7 +248,6 @@ function keyDirection(up='ArrowUp', down='ArrowDown', left='ArrowLeft', right='A
 }
 
 /** Returns true if mouse button is down
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
@@ -259,7 +258,6 @@ function mouseIsDown(button)
 }
 
 /** Returns true if mouse button was pressed
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
@@ -270,7 +268,6 @@ function mouseWasPressed(button)
 }
 
 /** Returns true if mouse button was released
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
@@ -498,7 +495,7 @@ function inputInit()
     {
         // fix stalled audio requiring user interaction, a keyboard only game has no other gesture
         if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-            audioContext.resume();
+            audioResume();
 
         // keys typed into an html text field are the player's typing, not game input;
         // a key already down still releases on keyup, which only lets go of keys that are down
@@ -584,7 +581,7 @@ function inputInit()
 
         // fix stalled audio requiring user interaction
         if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-            audioContext.resume();
+            audioResume();
 
         // a press in the bars around a letterboxed canvas is not one on its edge; a drag out of it still moves; under
         // pointer lock the mouse stays where the lock began, which may be in a bar, and every click is the game's
@@ -684,7 +681,7 @@ function inputInit()
 
             // fix stalled audio requiring user interaction
             if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-                audioContext.resume();
+                audioResume();
 
             // when the touch gamepad is enabled it owns touch input: suppress the
             // touch->mouse passthrough entirely unless touchGamepadPassthrough is set
@@ -1449,7 +1446,7 @@ function touchGamepadPointerDown(e, zone)
 
     // resume audio on first interaction
     if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-        audioContext.resume();
+        audioResume();
 
     // while paused, any touch is the start button; a control belongs to the first finger on it until that
     // finger lifts, so a second finger landing on the same one neither takes it over nor lets it go

package/src/engineMath.js

@@ -413,8 +413,10 @@ function lineTest(posStart, posEnd, testFunction, normal)
     const totalLength = (dx*dx + dy*dy)**.5;
     if (!totalLength) return;
 
-    // current integer cell we are in
+    // current integer cell we are in, the one below a whole start heading down the grid, which it goes into
     const pos = posStart.floor();
+    if (dx < 0 && pos.x === posStart.x) --pos.x;
+    if (dy < 0 && pos.y === posStart.y) --pos.y;
 
     // normalize ray direction
     const dirX = dx / totalLength;
@@ -687,11 +689,6 @@ function isVector2(v) { return v instanceof Vector2 && v.isValid(); }
 // vector2 asserts
 function ASSERT_VECTOR2_VALID(v) { ASSERT(isVector2(v), 'Vector2 is invalid.', v); }
 function ASSERT_NUMBER_VALID(n) { ASSERT(isNumber(n), 'Number is invalid.', n); }
-function ASSERT_VECTOR2_NORMAL(v)
-{
-    ASSERT_VECTOR2_VALID(v);
-    ASSERT(abs(v.lengthSquared()-1) < .01, 'Vector2 is not normal.', v);
-}
 
 /**
  * 2D Vector object with vector math library

package/src/engineObject.js

@@ -483,19 +483,23 @@ class EngineObject
     }
 
     /** Convert from local space to world space
-     *  @param {Vector2} pos - local space point */
+     *  @param {Vector2} pos - local space point
+     *  @return {Vector2} */
     localToWorld(pos) { return this.pos.add(pos.rotate(this.angle)); }
 
     /** Convert from world space to local space
-     *  @param {Vector2} pos - world space point */
+     *  @param {Vector2} pos - world space point
+     *  @return {Vector2} */
     worldToLocal(pos) { return pos.subtract(this.pos).rotate(-this.angle); }
 
     /** Convert from local space to world space for a vector (rotation only)
-     *  @param {Vector2} vec - local space vector */
+     *  @param {Vector2} vec - local space vector
+     *  @return {Vector2} */
     localToWorldVector(vec) { return vec.rotate(this.angle); }
 
     /** Convert from world space to local space for a vector (rotation only)
-     *  @param {Vector2} vec - world space vector */
+     *  @param {Vector2} vec - world space vector
+     *  @return {Vector2} */
     worldToLocalVector(vec) { return vec.rotate(-this.angle); }
 
     /** Called to check if a tile collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually.
@@ -634,11 +638,6 @@ class EngineObject
         this.collideRaycast = collideRaycast;
     }
 
-    /** @deprecated since 1.20, use collideLevel
-     *  @type {boolean} */
-    get collideTiles() { return this.collideLevel; }
-    set collideTiles(collide) { this.collideLevel = collide; }
-
     /** Returns string containing info about this object for debugging
      *  @return {string} */
     toString()

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'); }