littlejsengine 1.25.0 → 1.26.1

package/src/engineInput.js

@@ -198,9 +198,11 @@ function inputClear()
  *  @memberof Input */
 function keyIsDown(key, device=0)
 {
-    ASSERT(isStringLike(key), 'key must be a number or string');
-    ASSERT(typeof key !== 'string' || key.length > 1, "keys are codes like 'KeyW' or 'Space', not characters");
-    ASSERT(device > 0 || typeof key !== 'number' || key < 5, 'use code string for keyboard');
+    ASSERT(isStringLike(key), 'keyIsDown: key must be a code like \'KeyA\' or a number', key);
+    ASSERT(typeof key !== 'string' || key.length > 1,
+        "keyIsDown: keys are codes like 'KeyW' or 'Space', not characters", key);
+    ASSERT(device > 0 || typeof key !== 'number' || key < 5,
+        "keyIsDown: keyboard keys are codes like 'KeyA' or 'Space', the numbers 0 to 4 are mouse buttons", key);
     return !!(inputData[device]?.[key] & 1) && !inputCaptureHides(device);
 }
 
@@ -211,9 +213,11 @@ function keyIsDown(key, device=0)
  *  @memberof Input */
 function keyWasPressed(key, device=0)
 {
-    ASSERT(isStringLike(key), 'key must be a number or string');
-    ASSERT(typeof key !== 'string' || key.length > 1, "keys are codes like 'KeyW' or 'Space', not characters");
-    ASSERT(device > 0 || typeof key !== 'number' || key < 5, 'use code string for keyboard');
+    ASSERT(isStringLike(key), 'keyWasPressed: key must be a code like \'KeyA\' or a number', key);
+    ASSERT(typeof key !== 'string' || key.length > 1,
+        "keyWasPressed: keys are codes like 'KeyW' or 'Space', not characters", key);
+    ASSERT(device > 0 || typeof key !== 'number' || key < 5,
+        "keyWasPressed: keyboard keys are codes like 'KeyA' or 'Space', the numbers 0 to 4 are mouse buttons", key);
     return !!(inputData[device]?.[key] & 2) && !inputCaptureHides(device);
 }
 
@@ -224,9 +228,11 @@ function keyWasPressed(key, device=0)
  *  @memberof Input */
 function keyWasReleased(key, device=0)
 {
-    ASSERT(isStringLike(key), 'key must be a number or string');
-    ASSERT(typeof key !== 'string' || key.length > 1, "keys are codes like 'KeyW' or 'Space', not characters");
-    ASSERT(device > 0 || typeof key !== 'number' || key < 5, 'use code string for keyboard');
+    ASSERT(isStringLike(key), 'keyWasReleased: key must be a code like \'KeyA\' or a number', key);
+    ASSERT(typeof key !== 'string' || key.length > 1,
+        "keyWasReleased: keys are codes like 'KeyW' or 'Space', not characters", key);
+    ASSERT(device > 0 || typeof key !== 'number' || key < 5,
+        "keyWasReleased: keyboard keys are codes like 'KeyA' or 'Space', the numbers 0 to 4 are mouse buttons", key);
     return !!(inputData[device]?.[key] & 4) && !inputCaptureHides(device);
 }
 
@@ -253,7 +259,7 @@ function keyDirection(up='ArrowUp', down='ArrowDown', left='ArrowLeft', right='A
  *  @memberof Input */
 function mouseIsDown(button)
 {
-    ASSERT(isNumber(button), 'mouse button must be a number');
+    ASSERT(isNumber(button), 'mouseIsDown: button is 0 (left), 1 (middle) or 2 (right)', button);
     return keyIsDown(button);
 }
 
@@ -263,7 +269,7 @@ function mouseIsDown(button)
  *  @memberof Input */
 function mouseWasPressed(button)
 {
-    ASSERT(isNumber(button), 'mouse button must be a number');
+    ASSERT(isNumber(button), 'mouseWasPressed: button is 0 (left), 1 (middle) or 2 (right)', button);
     return keyWasPressed(button);
 }
 
@@ -273,7 +279,7 @@ function mouseWasPressed(button)
  *  @memberof Input */
 function mouseWasReleased(button)
 {
-    ASSERT(isNumber(button), 'mouse button must be a number');
+    ASSERT(isNumber(button), 'mouseWasReleased: button is 0 (left), 1 (middle) or 2 (right)', button);
     return keyWasReleased(button);
 }
 
@@ -500,16 +506,19 @@ function inputInit()
         // 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
         const typing = isTextInput(e.target) || isTextInput(document.activeElement);
-        if (!e.repeat && !typing)
+        // a key already held, a keydown the browser did not mark as a repeat, is not pressed again, but with Cmd down
+        // it is: a Mac sends no keyup for a key let go while Cmd is held, so each tap of Cmd+Z comes as a keydown alone
+        if (!e.repeat && !typing && (!inputKeysHeld.has(e.code) || e.metaKey))
         {
             inputKeysHeld.add(e.code);
-            // an arrow its alias already holds down is not pressed again, like its release waits for both
+            // an arrow its alias already holds down is not pressed again, like its release waits for both; a release
+            // earlier this frame is kept, so a quick release and press reads as both
             if (!(inputWASDEmulateDirection && inputKeysHeld.has(inputArrowToWASD[e.code]) && inputData[0][e.code] & 1))
-                inputData[0][e.code] = 3;
+                inputData[0][e.code] = 3 | inputData[0][e.code] & 4;
             // an alias presses its arrow's slot too, unless the arrow itself already holds it down
             const remap = remapKey(e.code);
             if (remap !== e.code && !(inputData[0][remap] & 1))
-                inputData[0][remap] = 3;
+                inputData[0][remap] = 3 | inputData[0][remap] & 4;
         }
 
         // try to prevent default browser handling of input
@@ -587,7 +596,7 @@ function inputInit()
         // pointer lock the mouse stays where the lock began, which may be in a bar, and every click is the game's
         if (!pointerLockIsActive() && !inCanvas(e.x, e.y))
             return;
-        inputData[0][e.button] = 3;
+        inputData[0][e.button] = 3 | inputData[0][e.button] & 4; // a release earlier this frame is kept
 
         const mousePosScreenLast = mousePosScreen;
         mousePosScreen = mouseEventToScreen(vec2(e.x,e.y));
@@ -647,8 +656,9 @@ function inputInit()
     }
     function onContextMenu(e)
     {
-        // prevent right click menu, but a text field keeps its copy and paste menu
-        if (inputPreventDefault && !isTextInput(e.target))
+        // prevent right click menu, but a text field keeps its copy and paste menu and a link its open in new tab
+        const target = /** @type {HTMLElement} */ (e.target);
+        if (inputPreventDefault && !isTextInput(target) && !target?.closest?.('a[href]'))
             e.preventDefault();
     }
     function onBlur()
@@ -669,6 +679,10 @@ function inputInit()
         // handle all touch events the same way
         function handleTouch(e)
         {
+            // fix stalled audio requiring user interaction, with touch input off too since the page's sound needs it
+            if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
+                audioResume();
+
             if (!touchInputEnable)
             {
                 // turned off mid touch, the finger that drove the mouse lets go of it
@@ -679,10 +693,6 @@ function inputInit()
             }
             inputLastTouchTime = performance.now();
 
-            // fix stalled audio requiring user interaction
-            if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-                audioResume();
-
             // when the touch gamepad is enabled it owns touch input: suppress the
             // touch->mouse passthrough entirely unless touchGamepadPassthrough is set
             // (its own zones drive gameplay via pointer events)
@@ -741,7 +751,7 @@ function inputInit()
                     else if (inputWasTouching && touch.identifier === inputTouchIdentifier)
                         mouseDeltaScreen = mouseDeltaScreen.add(mousePosScreen.subtract(mousePosScreenLast));
                     else if (pressTouch && inCanvas(pressTouch.clientX, pressTouch.clientY))
-                        inputData[0][button] = 3; // a tap in the bars around the canvas is not a press
+                        inputData[0][button] = 3 | inputData[0][button] & 4; // a tap in the bars is not a press
                     // the finger left after a pinch moves the mouse from where it is, with no jump and no press
                     inputTouchIdentifier = pinching ? undefined : touch.identifier;
                 }

package/src/engineMath.js

@@ -68,7 +68,7 @@ const sign = (x) => Math.sign(x);
  *  @param {...number} values
  *  @return {number}
  *  @memberof Math */
-const hypot = (...values) => Math.hypot(...values);
+const hypot = Math.hypot; // not a function of its own, which would gather its arguments into an array each call
 
 /** Returns log2 of value passed in
  *  @param {number} x
@@ -366,7 +366,7 @@ function oscillate(frequency=1, amplitude=1, t=time, offset=0, type=0)
  * @param {any} n
  * @return {boolean}
  * @memberof Math */
-function isNumber(n) { return typeof n === 'number' && !isNaN(n); }
+function isNumber(n) { return typeof n === 'number' && n === n; } // NaN is the one number not equal to itself
 
 /**
  * Check if a value is stringifiable — i.e. it has a toString that returns
@@ -687,8 +687,8 @@ function vec2(x=0, y) { return new Vector2(x, y ?? x); }
 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_VALID(v) { ASSERT(isVector2(v), 'expected a vec2', v); }
+function ASSERT_NUMBER_VALID(n) { ASSERT(isNumber(n), 'expected a number', n); }
 
 /**
  * 2D Vector object with vector math library
@@ -711,7 +711,8 @@ class Vector2
         this.x = x;
         /** @property {number} - Y axis location */
         this.y = y;
-        ASSERT(this.isValid(), 'Constructed Vector2 is invalid.', this);
+        ASSERT(this.isValid(), 'vec2: x and y must be numbers (add, subtract, multiply and divide take a vec2, scale a number)',
+            this); // one literal, as it is built at every vector made in a debug build
     }
 
     /** Sets values of this vector and returns self
@@ -942,7 +943,21 @@ class Vector2
  * @return {Color}
  * @memberof Math
  */
-function rgb(r, g, b, a) { return new Color(r, g, b, a); }
+function rgb(r, g, b, a)
+{
+    debug && (r > 2 || g > 2 || b > 2) && colorRangeWarn('rgb(255, 0, 0) is rgb(1, 0, 0)');
+    return new Color(r, g, b, a);
+}
+
+// a color given as 0 to 255 or as percents, as other tools take them, said once in a debug build; a value a little
+// past 1 is a bright color, which is why only past 2 counts
+let colorRangeWarned = false;
+function colorRangeWarn(example)
+{
+    if (colorRangeWarned) return;
+    colorRangeWarned = true;
+    console.warn('color values are 0 to 1 here, not 0 to 255 or percents: ' + example);
+}
 
 /**
  * Create a color object with HSLA values, white by default
@@ -952,7 +967,11 @@ function rgb(r, g, b, a) { return new Color(r, g, b, a); }
  * @param {number} [a=1] - alpha
  * @return {Color}
  * @memberof Math */
-function hsl(h, s, l, a) { return new Color().setHSLA(h, s, l, a); }
+function hsl(h, s, l, a)
+{
+    debug && (s > 2 || l > 2) && colorRangeWarn('hsl(.5, 100, 50) is hsl(.5, 1, .5)');
+    return new Color().setHSLA(h, s, l, a);
+}
 
 /**
  * Check if object is a valid Color
@@ -962,7 +981,7 @@ function hsl(h, s, l, a) { return new Color().setHSLA(h, s, l, a); }
 function isColor(c) { return c instanceof Color && c.isValid(); }
 
 // color asserts
-function ASSERT_COLOR_VALID(c) { ASSERT(isColor(c), 'Color is invalid.', c); }
+function ASSERT_COLOR_VALID(c) { ASSERT(isColor(c), 'expected a color', c); }
 
 /**
  * Color object (red, green, blue, alpha) with some helpful functions
@@ -991,7 +1010,7 @@ class Color
         this.b = b;
         /** @property {number} - Alpha */
         this.a = a;
-        ASSERT(this.isValid(), 'Constructed Color is invalid.', this);
+        ASSERT(this.isValid(), 'Color: r, g, b and a must be numbers', this);
     }
 
     /** Sets values of this color and returns self
@@ -1153,10 +1172,12 @@ class Color
      * @return {string} */
     toString(useAlpha = true)
     {
-        if (debug && !this.isValid())
-            return '#000';
-        const toHex = (c)=> ((c=round(clamp(c)*255))<16 ? '0' : '') + c.toString(16);
-        return '#' + toHex(this.r) + toHex(this.g) + toHex(this.b) + (useAlpha ? toHex(this.a) : '');
+        if (!this.isValid())
+            return '#000'; // in release too, as a canvas would keep its last color for #NaN
+
+        // two hex digits of a channel of 0 to 1, kept in here as the script build shares its top level with the game
+        const colorHex = (c)=> ((c = round(clamp(c) * 255)) < 16 ? '0' : '') + c.toString(16);
+        return '#' + colorHex(this.r) + colorHex(this.g) + colorHex(this.b) + (useAlpha ? colorHex(this.a) : '');
     }
 
     /** Set this color from a hex code
@@ -1166,7 +1187,7 @@ class Color
     {
         ASSERT(isStringLike(hex), 'Color hex code must be a string');
         ASSERT(hex[0] === '#', 'Color hex code must start with #');
-        ASSERT([4,5,7,9].includes(hex.length), 'Invalid hex');
+        ASSERT([4,5,7,9].includes(hex.length), 'setHex: use #rgb, #rgba, #rrggbb or #rrggbbaa', hex);
 
         if (hex.length < 6)
         {

package/src/engineObject.js

@@ -80,6 +80,9 @@ class EngineObject
         this.shader = undefined;
         /** @property {boolean} - Does this object draw into the light system's shadow map; false for a floor layer, a background, a pickup */
         this.castShadow = true;
+        /** @property {boolean} - Does this object draw into the light system's background map, which a
+         *  DirectionalLight lights only at its edges facing the light; for a background layer, with castShadow false */
+        this.castBackgroundShadow = false;
         /** @property {number} - With the light system, how much it lights itself: 0 lit only by the lights, 1 full
          *  brightness in its own colors whatever the lights do, between partly; drawn into the lightmap through
          *  renderEmissive, as 3D's emissive. Exact for solid pixels; a partly transparent one is self lit by its alpha
@@ -179,23 +182,18 @@ class EngineObject
                 child.updateTransforms();
     }
 
-    /** Update the object physics, called automatically by engine once each frame. Can be overridden to stop or change how physics works for an object. */
+    /** Update the object physics, called automatically by engine once each frame. Can be overridden to stop or change how physics works for an object
+     *  - With many solids each mover finds those near it through a grid, which follows a solid after its own physics
+     *    update: a solid an override moves for another object, a lift carrying a crate, is found there from the next
+     *    update on */
     updatePhysics()
     {
         // child objects do not have physics
-        ASSERT(!this.parent);
+        ASSERT(!this.parent, 'updatePhysics: a child has no physics of its own, its parent moves it');
 
         // bail if a collision callback destroyed us mid-frame
         if (this.destroyed) return;
 
-        // limit max speed to prevent missing collisions, only for what collides: with solids, or with tiles while it
-        // has a mass, which tile collision needs; anything else moves as fast as it is told
-        if (this.clampSpeed && enablePhysicsSolver && (this.collideSolidObjects || this.collideLevel && this.mass))
-        {
-            this.velocity.x = clamp(this.velocity.x, -objectMaxSpeed, objectMaxSpeed);
-            this.velocity.y = clamp(this.velocity.y, -objectMaxSpeed, objectMaxSpeed);
-        }
-
         // physics sanity checks
         ASSERT(this.angleDamping >= 0 && this.angleDamping <= 1, 'angleDamping must be 0 to 1, the fraction kept each frame');
         ASSERT(this.damping >= 0 && this.damping <= 1, 'damping must be 0 to 1, the fraction of velocity kept each frame');
@@ -211,6 +209,14 @@ class EngineObject
             this.velocity.x += gravity.x * this.gravityScale;
             this.velocity.y += gravity.y * this.gravityScale;
         }
+        // limit max speed to prevent missing collisions, after gravity so no move is past it, only for what collides:
+        // with solids, or with tiles while it has a mass, which tile collision needs; anything else moves as fast as
+        // it is told
+        if (this.clampSpeed && enablePhysicsSolver && (this.collideSolidObjects || this.collideLevel && this.mass))
+        {
+            this.velocity.x = clamp(this.velocity.x, -objectMaxSpeed, objectMaxSpeed);
+            this.velocity.y = clamp(this.velocity.y, -objectMaxSpeed, objectMaxSpeed);
+        }
         this.pos.x += this.velocity.x;
         this.pos.y += this.velocity.y;
         this.angle += this.angleVelocity *= this.angleDamping;
@@ -235,7 +241,8 @@ class EngineObject
         {
             // check collisions against solid objects
             const epsilon = .001; // necessary to push slightly outside of the collision
-            for (const o of engineObjectsCollideStaticLast)
+            // with many solids, only those near it, as a grid finds them, in the same order
+            for (const o of engineCollideGrid ? engineCollideGridWalk(this) : engineObjectsCollideStaticLast)
             {
                 // skip destroyed, child objects, self collision, or objects with no box
                 if (o.destroyed || o.parent || o === this || !o.size.x || !o.size.y) continue;
@@ -256,6 +263,8 @@ class EngineObject
                     // notify objects of collision and check if should be resolved
                     const collide1 = this.collideWithObject(o);
                     const collide2 = o.collideWithObject(this);
+                    // a callback may have moved either one, the grid follows
+                    engineCollideGrid?.built && engineCollideGridPlace(engineCollideGrid.built, o);
                     if (!collide1 || !collide2)
                     {
                         engineObjectsCollidePairAdd(this, o);
@@ -406,34 +415,38 @@ class EngineObject
                             return;
                         }
 
-                        // move to previous X position and bounce
-                        this.pos.x = oldPos.x;
+                        // move against the wall and bounce, its side on the tile edge it moved toward, rounded in the
+                        // layer's space as its collision test is; back to its previous X when that spot is not clear
+                        const snapEpsilon = .0001, layerX = hitLayer.pos.x, offsetX = this.size.x/2 + snapEpsilon;
+                        // never back past where it was: a leading edge already on a grid line would step back by
+                        // the epsilon and take its trailing edge into the tile behind, which nothing tests, since
+                        // only X is blocked; between there and the wall it covers no column it did not cover before
+                        const movingLeft = this.pos.x < oldPos.x;
+                        const snap = layerX + (movingLeft ?
+                            floor(oldPos.x - layerX - this.size.x/2) + offsetX :
+                            ceil( oldPos.x - layerX + this.size.x/2) - offsetX);
+                        const x = movingLeft ? min(snap, oldPos.x) : max(snap, oldPos.x);
+                        this.pos.x = tileCollisionTest(vec2(x, oldPos.y), this.size, this) ? oldPos.x : x;
                         this.velocity.x *= -restitution;
                     }
                     if (isBlockedY || !isBlockedX)
                     {
-                        if (wasFalling)
-                        {
-                            // adjust position to slightly away from nearest tile
-                            // this prevents gap between object and ground
-                            const epsilon = .0001;
-                            const offset = this.size.y/2 + epsilon;
-                            // rounded in the layer's space as its collision test is, or a bottom a hair below a
-                            // grid line would round to the row under it, inside the floor, and fall through
-                            const layerY = hitLayer.pos.y;
-                            this.pos.y = layerY + (gravityY < 0 ?
-                                floor(oldPos.y - layerY - this.size.y/2) + offset :
-                                ceil( oldPos.y - layerY + this.size.y/2) - offset);
-
-                            // set ground object for tile collision
-                            this.groundObject = hitLayer;
-                        }
-                        else
-                        {
-                            // move to previous Y position
-                            this.pos.y = oldPos.y;
-                            this.groundObject = undefined;
-                        }
+                        // adjust position to slightly away from the nearest tile, the floor or the ceiling it moved
+                        // toward, which prevents a gap between them; rounded in the layer's space as its collision
+                        // test is, or a bottom a hair below a grid line would round to the row under it, inside the
+                        // floor, and fall through; back to its previous Y when that spot is not clear
+                        const epsilon = .0001;
+                        const offset = this.size.y/2 + epsilon;
+                        const layerY = hitLayer.pos.y;
+                        const y = layerY + (this.pos.y < oldPos.y ?
+                            floor(oldPos.y - layerY - this.size.y/2) + offset :
+                            ceil( oldPos.y - layerY + this.size.y/2) - offset);
+                        const isClear = this.pos.y !== oldPos.y && !tileCollisionTest(vec2(this.pos.x, y), this.size, this);
+                        this.pos.y = isClear ? y : oldPos.y;
+
+                        // set ground object for tile collision
+                        this.groundObject = wasFalling ? hitLayer : undefined;
+
                         // bounce velocity
                         this.velocity.y *= -restitution;
                     }
@@ -443,7 +456,7 @@ class EngineObject
         }
     }
 
-    /** Update the object, called automatically by engine once each frame. Does nothing by default. */
+    /** Update the object, called automatically by engine once each frame. Does nothing by default */
     update() {}
 
     /** Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder */
@@ -453,10 +466,11 @@ class EngineObject
         drawTile(this.pos, this.drawSize || this.size, this.tileInfo, this.color, this.angle, this.mirror, this.additiveColor, glEnable, false);
     }
 
-    /** Optional hook called during the light system plugin's lightmap pass to draw this object's lightmap contribution. Does nothing by default. */
+    /** Optional hook called during the light system plugin's lightmap pass to draw this object's lightmap contribution. Does nothing by default */
     renderLight() {}
 
-    /** Draw this object into the light system's shadow map, called during its shadow pass when castShadow is set.
+    /** Draw this object into the light system's shadow map, called during its shadow pass when castShadow is set, and into
+     *  its background map when castBackgroundShadow is set and a DirectionalLight is out.
      *  Calls render() by default so the object casts its own shape; override to cast a different one, like a blob at a character's feet so its body stays lit;
      *  screen space WebGL draws in render() are skipped during the pass */
     renderShadow() { this.render(); }
@@ -502,20 +516,24 @@ class EngineObject
      *  @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.
+    /** 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
      *  - Called for each solid tile the physics tests, which can be several times a frame for the same tile, and for
      *    positions it only tries, so keep it free of side effects or guard them to once a frame
      *  - this.pos has already moved, so a check on where it came from, like a one way platform, needs the position
      *    saved in update, as the platformer example does
+     *  - For the point of impact, like sparks where a bullet hit, raycast from where this frame's move started,
+     *    this.pos minus this.velocity, to this.pos with tileCollisionRaycast, as the platformer's Bullet does
      *  @param {number}  tileData - the value of the tile at the position
      *  @param {Vector2} pos - the tile's bottom left corner in world space
      *  @return {boolean} - true if the collision should be resolved by modifying it's position and velocity */
     collideWithTile(tileData, pos) { return tileData > 0; }
 
-    /** Called by the engine to check if an object collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually.
+    /** Called by the engine to check if an object collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually
      *  - Both objects of a touching pair are asked once a frame, whichever order they update in; an object that
      *    destroys itself here is gone at the end of the frame and is still asked about the pairs left this frame, so a
      *    bullet that should hit one thing checks its own destroyed flag first
+     *  - With many solids each mover finds those near it through a grid, which follows the other object after this
+     *    returns; a third object moved here is found where it is now from the next update on
      *  @param {EngineObject} object - the object to test against
      *  @param {Vector3} [push] - what it would take to move this object clear, a Vector3 from the 3D plugin, undefined in 2D
      *  @return {boolean} - true if the collision should be resolved by modifying it's position and velocity
@@ -603,7 +621,8 @@ class EngineObject
      *  @param {EngineObject} child */
     removeChild(child)
     {
-        ASSERT(child.parent === this && this.children.includes(child));
+        ASSERT(child.parent === this && this.children.includes(child), 'removeChild: that object is not a child of this one',
+            child);
         const i = this.children.indexOf(child);
         if (i < 0) return; // not a child of this one, release has no assert
         this.children.splice(i, 1);

package/src/engineParticles.js

@@ -67,7 +67,7 @@ class ParticleEmitter extends EngineObject
      *  @param {number} [angleSpeed]        - How fast are particles rotating, in radians per frame (at 60fps)
      *  @param {number} [damping]           - How much to dampen particle speed, per-frame velocity multiplier (1 = no damping, .9 = lose 10% speed each frame)
      *  @param {number} [angleDamping]      - How much to dampen particle angular speed, per-frame multiplier (1 = no damping)
-     *  @param {number} [gravityScale]      - How much gravity effect particles
+     *  @param {number} [gravityScale]      - How much gravity affects particles
      *  @param {number} [particleConeAngle] - Half angle each side of the emitter's angle for a particle's start angle, PI is any angle
      *  @param {number} [fadeRate]          - Fraction of life spent fading: half at fade-in (start), half at fade-out (end). e.g. .2 = 10% fade-in, 80% full opacity, 10% fade-out
      *  @param {number} [randomness]    - Apply extra randomness percent
@@ -109,13 +109,34 @@ class ParticleEmitter extends EngineObject
     )
     {
         super(pos, vec2(), tileInfo, angle, undefined, renderOrder);
+        if (debug)
+        {
+            // the arguments come in a long row, so one out of place is named rather than emitting NaN particles
+            ASSERT(typeof emitSize === 'number' || isVector2(emitSize), 'ParticleEmitter: emitSize must be a number or vec2',
+                emitSize);
+            ASSERT(!tileInfo || tileInfo instanceof TileInfo, 'ParticleEmitter: tileInfo must be a TileInfo or undefined',
+                tileInfo);
+            const numbers = {emitTime, emitRate, emitConeAngle, particleTime, sizeStart, sizeEnd, speed, angleSpeed,
+                damping, angleDamping, gravityScale, particleConeAngle, fadeRate, randomness};
+            // plain strings, as a message is built at every emitter made in a debug build
+            for (const name in numbers)
+                ASSERT(isNumber(numbers[name]),
+                    'ParticleEmitter: an argument is not a number, they may be out of order; its name and value:',
+                    name, numbers[name]);
+            const colors = {colorStartA, colorStartB, colorEndA, colorEndB};
+            for (const name in colors)
+                ASSERT(isColor(colors[name]),
+                    'ParticleEmitter: an argument is not a color, they may be out of order; its name and value:',
+                    name, colors[name]);
+        }
 
         // emitter settings
         /** @property {boolean} - Should particles be emitted in a circle */
         this.emitCircle = typeof emitSize === 'number';
         /** @property {Vector2} - World space size of the emitter, x is the diameter when emitCircle is set */
         this.emitSize = typeof emitSize === 'number' ? vec2(emitSize) : emitSize.copy();
-        /** @property {number} - How long to stay alive (0 is forever) */
+        /** @property {number} - How long to emit for in seconds, 0 is forever; raised while its particles are still
+         *  alive, it emits again for the added time */
         this.emitTime = emitTime;
         /** @property {number} - How many particles per second to spawn, does not emit if 0 */
         this.emitRate = emitRate;
@@ -188,6 +209,9 @@ class ParticleEmitter extends EngineObject
         this.velocityInheritance = 0;
         /** @property {number} - Particles owed to the emit rate, starts at one so the first comes out at once */
         this.emitTimeBuffer = 1;
+        /** @property {number} - Seconds of its emit time it has emitted for, counted by its updates
+         *  @type {number} */
+        this.emitElapsed = 0;
         /** @property {Array<Particle>} - Array of particles for this emitter
          *  @type {Array<Particle>} */
         this.particles = [];
@@ -196,6 +220,10 @@ class ParticleEmitter extends EngineObject
         /** @type {Vector2|undefined} */
         this.previousPos = undefined;
         this.previousAngle = this.angle;
+        // where it was last update, and how far back toward it the particle being made starts, 0 to 1: a moving
+        // emitter spreads an update's particles along its move, where they came out in a clump where it is
+        this.emitFrom = vec2();
+        this.emitBehind = 0;
     }
 
     /** Update the emitter to spawn particles, called automatically by engine once each frame */
@@ -221,20 +249,37 @@ class ParticleEmitter extends EngineObject
         }
         // tracked even while velocityInheritance is off, so turning it on does not jump
         this.previousAngle = this.angle;
+        this.emitFrom.x = this.previousPos.x;
+        this.emitFrom.y = this.previousPos.y;
         this.previousPos.x = this.pos.x;
         this.previousPos.y = this.pos.y;
 
         // update emitter
         if (this.isActive())
         {
-            // emit particles
+            // emit particles for the part of this update inside the emit time, counted by its own updates rather than
+            // the clock, so a one shot gives the same count whichever frame it is made on
             const rate = this.emitRate * particleEmitRateScale;
+            const step = this.emitTime ? min(timeDelta, this.emitTime - this.emitElapsed) : timeDelta;
+            this.emitElapsed += timeDelta;
             if (rate > 0 && rate < Infinity)
             {
-                // counted in particles, so a new rate applies at once
-                this.emitTimeBuffer += rate * timeDelta;
-                for (; this.emitTimeBuffer >= 1; --this.emitTimeBuffer)
-                    this.emitParticle();
+                // counted in particles, so a new rate applies at once; the update that ends the emit time adds a
+                // hair, as the steps' sum comes out a rounding under it and lost the last particle
+                this.emitTimeBuffer += rate * step + (this.emitTime && this.emitElapsed >= this.emitTime ? 1e-6 : 0);
+                // spread along the move since the last update, the last one where it is now; a jump further than
+                // anything travels in an update, twice objectMaxSpeed, a teleport or a respawn, spreads nothing
+                const travelled = this.emitFrom && this.pos.distance(this.emitFrom) <= 2 * objectMaxSpeed;
+                const count = floor(this.emitTimeBuffer);
+                try
+                {
+                    for (let i = count; i--; --this.emitTimeBuffer)
+                    {
+                        this.emitBehind = travelled ? i / count : 0;
+                        this.emitParticle();
+                    }
+                }
+                finally { this.emitBehind = 0; } // a create callback that throws leaves no offset for the next
             }
         }
         else if (this.particles.length === 0)
@@ -279,8 +324,9 @@ class ParticleEmitter extends EngineObject
         {
             // into the world: a local space particle is turned with the emitter when it draws instead
             this.emitCircle || (pos = pos.rotate(this.angle));
-            pos.x += this.pos.x;
-            pos.y += this.pos.y;
+            const behind = this.emitBehind; // back along its move, as the update spreads them
+            pos.x += this.pos.x + (this.emitFrom.x - this.pos.x) * behind;
+            pos.y += this.pos.y + (this.emitFrom.y - this.pos.y) * behind;
             angle += this.angle;
         }
 
@@ -338,10 +384,11 @@ class ParticleEmitter extends EngineObject
 
     /** is emitter actively spawning
      *  @return {boolean} */
-    isActive() { return !this.emitTime || this.getAliveTime() < this.emitTime; }
+    isActive() { return !this.emitTime || this.emitElapsed < this.emitTime; }
 
     /** Destroy the particle emitter
-     *  @param {boolean} [immediate] - true removes attached effects like particle emitters at once, false lets them finish first */
+     *  @param {boolean} [immediate] - true removes it and its particles at once, with no particleDestroyCallback for
+     *    them, false stops emitting and lets the particles finish first */
     destroy(immediate=false)
     {
         if (this.destroyed) return;

package/src/engineRelease.js

@@ -29,7 +29,6 @@ function LOG             (){}
 function debugInit       (){}
 function debugUpdate     (){}
 function debugRender     (){}
-function debugRenderPost (){}
 function debugRect       (){}
 function debugPoly       (){}
 function debugCircle     (){}
@@ -41,10 +40,7 @@ function debugClear      (){}
 function debugScreenshot (){}
 function debugShowErrors(){}
 function setDebugOverlay(){}
-function debugVideoCaptureIsActive(){ return false; }
-function debugVideoCaptureStart (){}
-function debugVideoCaptureStop  (){}
-function debugProtectConstant(o){ return o; }
+function debugProtectConstant(o){ return Object.freeze(o); } // a color constant stays as it is, in release too
 
 // the tweakables and the level editor are debug only
 function tweak(){}