littlejsengine 1.24.3 → 1.26.0

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
@@ -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;
@@ -685,13 +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_NORMAL(v)
-{
-    ASSERT_VECTOR2_VALID(v);
-    ASSERT(abs(v.lengthSquared()-1) < .01, 'Vector2 is not normal.', v);
-}
+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
@@ -714,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
@@ -945,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
@@ -955,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
@@ -965,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
@@ -994,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
@@ -1156,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
@@ -1169,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(); }
@@ -483,35 +497,43 @@ 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.
+    /** 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
@@ -599,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);
@@ -634,11 +657,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
@@ -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;
         }
 
@@ -336,11 +382,13 @@ class ParticleEmitter extends EngineObject
         this.additive && setAdditiveBlendMode(false);
     }
 
-    /** is emitter actively spawning */
-    isActive() { return !this.emitTime || this.getAliveTime() < this.emitTime; }
+    /** is emitter actively spawning
+     *  @return {boolean} */
+    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;
@@ -548,8 +596,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
@@ -30,7 +29,6 @@ function LOG             (){}
 function debugInit       (){}
 function debugUpdate     (){}
 function debugRender     (){}
-function debugRenderPost (){}
 function debugRect       (){}
 function debugPoly       (){}
 function debugCircle     (){}
@@ -42,16 +40,21 @@ 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(){}
 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 +64,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(){}