littlejsengine 1.24.3 → 1.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.24.3",
+  "version": "1.26.0",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",
@@ -11,6 +11,8 @@
       "default": "./dist/littlejs.esm.js"
     },
     "./dist/*": "./dist/*",
+    "./plugins/*": "./plugins/*",
+    "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "repository": {
@@ -52,12 +54,10 @@
     "test:browser": "node test/browser/run.mjs"
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=22.12.0"
   },
   "devDependencies": {
     "bestzip": "^2.2.1",
-    "electron": "^38.2.0",
-    "electron-packager": "^17.1.2",
     "google-closure-compiler": "~20230502.0.0",
     "jsdoc": "~4.0.2",
     "roadroller": "~2.1.0",

package/plugins/box2d.js

@@ -35,7 +35,7 @@ let box2dDebug = false;
 let box2dTempVectors;
 function box2dTemp(v, slot=0)
 {
-    ASSERT(isVector2(v));
+    ASSERT(isVector2(v), 'Box2D: expected a vec2', v);
     const temp = (box2dTempVectors ||= [new box2d.instance.b2Vec2(), new box2d.instance.b2Vec2()])[slot];
     temp.Set(v.x, v.y);
     return temp;
@@ -88,6 +88,9 @@ function box2dWakeWithContacts(body)
         edge.get_other().SetAwake(true);
 }
 
+// a number Box2D can take: it stops for good on NaN or Infinity, and a release build has no asserts to catch one first
+const box2dFinite = (value, otherwise)=> isFinite(value) ? value : otherwise;
+
 // wake both bodies of a joint whose length, spring, ratio or strength changed, a sleeping body would stay where it was
 function box2dWakeJoint(joint)
 {
@@ -147,6 +150,64 @@ function box2dDestroyGears(joint)
  *  @memberof Box2D */
 function box2dSetDebug(enable) { box2dDebug = enable; }
 
+// the EngineObject physics fields a Box2D body does not read, each with what moves the body instead; a debug build
+// warns once a field when a game sets one, which did nothing and said nothing
+const box2dUnusedFields = {
+    velocity: 'setLinearVelocity', angleVelocity: 'setAngularVelocity', damping: 'setLinearDamping',
+    angleDamping: 'setAngularDamping', mass: 'setMass or the density of its shapes',
+    friction: 'the friction of its shapes, given to addBox and the rest',
+    restitution: 'the restitution of its shapes, given to addBox and the rest'};
+const box2dUnusedWarned = new Set, box2dUnusedStarts = new WeakMap;
+
+// the values of those fields as numbers, a vector as its two, then gravityScale, kept for the object
+function box2dUnusedFieldValues(o)
+{
+    const values = [];
+    for (const name in box2dUnusedFields)
+    {
+        const value = o[name];
+        value instanceof Vector2 ? values.push(value.x, value.y) : values.push(value);
+    }
+    values.push(o.gravityScale);
+    return values;
+}
+
+// warn once a field
+function box2dUnusedWarn(name, use)
+{
+    if (box2dUnusedWarned.has(name)) return;
+    box2dUnusedWarned.add(name);
+    console.warn('Box2dObject.' + name + ' does nothing on a Box2D body, use ' + use);
+}
+
+// warn once a field of one set on a Box2dObject, and of gravityScale set on the field, not with setGravityScale;
+// compared in place, as it runs for every body every step of a debug build
+function box2dCheckUnusedFields(o)
+{
+    const start = box2dUnusedStarts.get(o);
+    if (!start) return;
+    let i = 0;
+    for (const name in box2dUnusedFields)
+    {
+        const value = o[name];
+        let changed;
+        if (value instanceof Vector2)
+        {
+            changed = value.x !== start[i] || value.y !== start[i + 1];
+            i += 2;
+        }
+        else
+            changed = value !== start[i++];
+        changed && box2dUnusedWarn(name, box2dUnusedFields[name]);
+    }
+
+    // the body's own scale is a call into Box2D, asked only when the field changed since it was last asked,
+    // since setGravityScale sets both
+    if (o.gravityScale === start[i]) return;
+    start[i] = o.gravityScale;
+    Math.fround(o.gravityScale) === o.body.GetGravityScale() || box2dUnusedWarn('gravityScale', 'setGravityScale');
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /** 
  * Box2D Object - extend with your own custom physics objects
@@ -154,6 +215,10 @@ function box2dSetDebug(enable) { box2dDebug = enable; }
  * - Provides interface for Box2D body and fixture functions
  * - Each object can have multiple fixtures and joints
  * - Angular values are clockwise like angle: angular velocity, torque, joint angles, limits and motor speeds
+ * - Box2D moves the body, so the EngineObject physics fields do nothing on it: velocity, angleVelocity, damping,
+ *   angleDamping, mass, friction, restitution and gravityScale; use setLinearVelocity, setAngularVelocity,
+ *   setLinearDamping, setAngularDamping, setMass, the friction and restitution of its shapes and setGravityScale.
+ *   A debug build warns once when one of them is set
  * @extends EngineObject
  * @memberof Box2D
  */
@@ -196,6 +261,9 @@ class Box2dObject extends EngineObject
 
         this.body.object = this; // link body to this object
         box2d.objects.push(this); // keep track of all box2d objects
+
+        // a debug build notes the engine physics fields Box2D does not read, to warn when one is set
+        debug && box2dUnusedStarts.set(this, box2dUnusedFieldValues(this));
     }
 
     /** Destroy this object and its physics body
@@ -244,7 +312,7 @@ class Box2dObject extends EngineObject
             this.drawFixtures(this.color, this.lineColor, this.lineWidth);
     }
 
-    /** Render debug info */
+    /** Draw its fixtures for the debug view: yellow asleep, blue static, both when both */
     renderDebugInfo()
     {
         const isAsleep = !this.getIsAwake();
@@ -253,7 +321,7 @@ class Box2dObject extends EngineObject
         this.drawFixtures(color);
     }
 
-    /** Draws all this object's fixtures 
+    /** Draw all this object's fixtures 
      *  @param {Color}   [color]
      *  @param {Color}   [lineColor]
      *  @param {number}  [lineWidth]
@@ -303,7 +371,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Object} - The fixture made, Box2D's own */
     addShape(shape, density=1, friction=.2, restitution=0, isSensor=false)
     {
         ASSERT(isNumber(density), 'density must be a number');
@@ -332,7 +401,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Object|undefined} - The fixture made, Box2D's own, undefined for a shape too small to make */
     addBox(size=vec2(1), offset=vec2(), angle=0, density, friction, restitution, isSensor)
     {
         ASSERT(isVector2(size), 'size must be a Vector2');
@@ -341,8 +411,8 @@ class Box2dObject extends EngineObject
         ASSERT(isNumber(angle), 'angle must be a number');
 
         // Box2D stops for good on a box with almost no area, like addPoly no fixture is made from one
-        ASSERT(size.x * size.y > 1e-6, 'box is too small for Box2D');
-        if (!(size.x * size.y > 1e-6)) return;
+        ASSERT(size.x * size.y > 1e-6 && isFinite(size.x * size.y), 'box is too small or too big for Box2D');
+        if (!(size.x * size.y > 1e-6) || !isFinite(size.x * size.y)) return;
 
         const shape = new box2d.instance.b2PolygonShape();
         shape.SetAsBox(size.x/2, size.y/2, box2dTemp(offset), -angle);
@@ -357,7 +427,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Object|undefined} - The fixture made, Box2D's own, undefined for a shape too small to make */
     addPoly(points, density, friction, restitution, isSensor)
     {
         ASSERT(isArray(points), 'points must be an array');
@@ -404,7 +475,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Object|undefined} - The fixture made, Box2D's own, undefined for a shape too small to make */
     addRegularPoly(diameter=1, sides=8, density, friction, restitution, isSensor)
     {
         ASSERT(isNumber(diameter) && diameter>0, 'diameter must be a positive number');
@@ -424,7 +496,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Object|undefined} - The fixture made, Box2D's own, undefined for a shape too small to make */
     addRandomPoly(diameter=1, density, friction, restitution, isSensor)
     {
         ASSERT(isNumber(diameter) && diameter>0, 'diameter must be a positive number');
@@ -443,12 +516,14 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Object|undefined} - The fixture made, Box2D's own, undefined for a circle too big to make */
     addCircle(diameter=1, offset=vec2(), density, friction, restitution, isSensor)
     {
-        ASSERT(isNumber(diameter) && diameter>0, 'diameter must be a positive number');
+        ASSERT(isNumber(diameter) && diameter>0 && isFinite(diameter), 'diameter must be a positive number');
         ASSERT(isVector2(offset), 'offset must be a Vector2');
-        
+        if (!isFinite(diameter)) return; // Box2D stops for good on it, no fixture is made
+
         const shape = new box2d.instance.b2CircleShape();
         shape.set_m_p(box2dTemp(offset));
         shape.set_m_radius(diameter/2);
@@ -463,7 +538,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Object} - The fixture made, Box2D's own */
     addEdge(point1, point2, density, friction, restitution, isSensor)
     {
         ASSERT(isVector2(point1), 'point1 must be a Vector2');
@@ -481,7 +557,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Array<Object>} - The fixtures made, Box2D's own */
     addEdgeList(points, density, friction, restitution, isSensor)
     {
         ASSERT(isArray(points), 'points must be an array');
@@ -514,7 +591,8 @@ class Box2dObject extends EngineObject
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
-     *  @param {boolean} [isSensor] */
+     *  @param {boolean} [isSensor]
+     *  @return {Array<Object>} - The fixtures made, Box2D's own */
     addEdgeLoop(points, density, friction, restitution, isSensor)
     {
         ASSERT(isArray(points), 'points must be an array');
@@ -676,12 +754,14 @@ class Box2dObject extends EngineObject
     setAngularVelocity(angularVelocity)
     { this.body.SetAngularVelocity(-angularVelocity); }
 
-    /** Sets the linear damping
+    /** Sets the linear damping, Box2D's: a rate, 0 none and larger slows it faster, with no upper limit, where the
+     *  damping of an EngineObject is the fraction it keeps each frame and does nothing on a Box2dObject
      *  @param {number} damping */
     setLinearDamping(damping)
     { this.body.SetLinearDamping(damping); }
 
-    /** Sets the angular damping
+    /** Sets the angular damping, Box2D's: a rate, 0 none and larger slows its turning faster, with no upper limit;
+     *  angleDamping does nothing on a Box2dObject
      *  @param {number} damping */
     setAngularDamping(damping)
     { this.body.SetAngularDamping(damping); }
@@ -758,7 +838,7 @@ class Box2dObject extends EngineObject
             const f = Math.fround;
             const oldInertia = f(data.get_I() - box2dCenterInertia(oldMass, center.get_x(), center.get_y()));
             const inertia = momentOfInertia ?? oldInertia;
-            mass ??= oldMass;
+            mass = box2dFinite(mass ?? oldMass, oldMass);
             const offset = box2dCenterInertia(mass > 0 ? mass : 1, cx, cy); // a mass of 0 or less is 1 to Box2D
             const I = f(inertia + offset);
             data.set_mass(mass);
@@ -1079,13 +1159,15 @@ class Box2dJoint
         const bodyA = jointDef.get_bodyA(), bodyB = jointDef.get_bodyB();
         const bothLive = !box2d.isNull(bodyA) && !box2d.isNull(bodyB);
         ASSERT(bothLive, 'a joint needs two objects that are not destroyed');
-        ASSERT(box2d.instance.getPointer(bodyA) !== box2d.instance.getPointer(bodyB), 'a joint needs two different objects');
+        const twoObjects = !bothLive || box2d.instance.getPointer(bodyA) !== box2d.instance.getPointer(bodyB);
+        ASSERT(twoObjects, 'a joint needs two different objects');
 
         /** @property {Object} - The Box2d joint, 0 once it is destroyed, as it is when either object is */
         this.box2dJoint = 0;
-        if (!bothLive)
+        if (!bothLive || !twoObjects)
         {
-            // one of its objects is gone, so it is made destroyed, as it would be had it gone after
+            // one of its objects is gone, so it is made destroyed, as it would be had it gone after; a joint of an
+            // object to itself, which Box2D stops for good on, is made destroyed too in a release build
             box2d.instance.destroy(jointDef);
             return;
         }
@@ -1197,7 +1279,7 @@ class Box2dTargetJoint extends Box2dJoint
     
     /** Sets the joint frequency in Hertz, above 0, Box2D stops for good on 0
      *  @param {number} hz */
-    setFrequency(hz) { this.box2dJoint.SetFrequency(max(hz, 1e-3)); box2dWakeJoint(this.box2dJoint); }
+    setFrequency(hz) { this.box2dJoint.SetFrequency(max(box2dFinite(hz, 0), 1e-3)); box2dWakeJoint(this.box2dJoint); }
     
     /** Gets the joint frequency in Hertz
      *  @return {number} */
@@ -1260,11 +1342,11 @@ class Box2dDistanceJoint extends Box2dJoint
      *  @return {number} */
     getFrequency() { return this.box2dJoint.GetFrequency(); }
     
-    /** Set the damping ratio
+    /** Set how much the spring is damped, 0 for none and 1 to stop it bouncing
      *  @param {number} ratio */
     setDampingRatio(ratio) { this.box2dJoint.SetDampingRatio(ratio); box2dWakeJoint(this.box2dJoint); }
     
-    /** Get the damping ratio
+    /** Get how much the spring is damped, 0 for none and 1 to stop it bouncing
      *  @return {number} */
     getDampingRatio() { return this.box2dJoint.GetDampingRatio(); }
 }
@@ -1393,6 +1475,7 @@ class Box2dRevoluteJoint extends Box2dJoint
     setLimits(min, max)
     {
         ASSERT(min <= max, 'the lower limit must not be above the upper one');
+        min = box2dFinite(min, 0), max = box2dFinite(max, 0); // or on NaN, which passes the order check
         if (min > max) [min, max] = [max, min]; // Box2D stops on them reversed
         this.box2dJoint.SetLimits(-max, -min);
     }
@@ -1417,7 +1500,7 @@ class Box2dRevoluteJoint extends Box2dJoint
      *  @param {number} torque */
     setMaxMotorTorque(torque) { this.box2dJoint.SetMaxMotorTorque(torque); }
 
-    /** Get the max motor torque
+    /** Get the most torque the motor can apply, a magnitude
      *  @return {number} */
     getMaxMotorTorque() { return this.box2dJoint.GetMaxMotorTorque(); }
 
@@ -1432,6 +1515,8 @@ class Box2dRevoluteJoint extends Box2dJoint
  * Box2D Pin Joint
  * - Pins two objects together at a point, where they still turn freely, like a nail through two boards
  * - A revolute joint at that point, so it holds exactly and its limits and motor work too
+ * - new Box2dPinJoint(objectA, objectB, pos, collide): the point defaults to objectA's position, where a revolute
+ *   joint's anchor defaults to objectB's
  * @extends Box2dRevoluteJoint
  * @memberof Box2D
  */
@@ -1593,6 +1678,7 @@ class Box2dPrismaticJoint extends Box2dJoint
     setLimits(min, max)
     {
         ASSERT(min <= max, 'the lower limit must not be above the upper one');
+        min = box2dFinite(min, 0), max = box2dFinite(max, 0); // or on NaN, which passes the order check
         if (min > max) [min, max] = [max, min]; // Box2D stops on them reversed
         this.box2dJoint.SetLimits(min, max);
     }
@@ -1605,11 +1691,11 @@ class Box2dPrismaticJoint extends Box2dJoint
      *  @param {boolean} [enable] */
     enableMotor(enable=true) { this.box2dJoint.EnableMotor(enable); }
     
-    /** Set the motor speed
+    /** Set the speed the motor drives the bodies apart along the axis, in meters per second
      *  @param {number} speed */
     setMotorSpeed(speed) { this.box2dJoint.SetMotorSpeed(speed); }
     
-    /** Get the motor speed
+    /** Get the speed the motor drives the bodies apart along the axis, in meters per second
      *  @return {number} */
     getMotorSpeed() { return this.box2dJoint.GetMotorSpeed(); }
     
@@ -1701,7 +1787,7 @@ class Box2dWheelJoint extends Box2dJoint
      *  @param {number} torque */
     setMaxMotorTorque(torque) { this.box2dJoint.SetMaxMotorTorque(torque); }
 
-    /** Get the max motor torque
+    /** Get the most torque the wheel's motor can apply, a magnitude
      *  @return {number} */
     getMaxMotorTorque() { return this.box2dJoint.GetMaxMotorTorque(); }
 
@@ -1718,11 +1804,11 @@ class Box2dWheelJoint extends Box2dJoint
      *  @return {number} */
     getSpringFrequencyHz() { return this.box2dJoint.GetSpringFrequencyHz(); }
 
-    /** Set the spring damping ratio
+    /** Set how much the suspension spring is damped, 0 for none and 1 to stop it bouncing
      *  @param {number} ratio */
     setSpringDampingRatio(ratio) { this.box2dJoint.SetSpringDampingRatio(ratio); box2dWakeJoint(this.box2dJoint); }
 
-    /** Get the spring damping ratio
+    /** Get how much the suspension spring is damped, 0 for none and 1 to stop it bouncing
      *  @return {number} */
     getSpringDampingRatio() { return this.box2dJoint.GetSpringDampingRatio(); }
 }
@@ -1780,21 +1866,13 @@ class Box2dWeldJoint extends Box2dJoint
      *  @return {number} */
     getFrequency() { return this.box2dJoint.GetFrequency(); }
 
-    /** Set the damping ratio
+    /** Set how much the weld's spring is damped, 0 for none and 1 to stop it bouncing
      *  @param {number} ratio */
     setDampingRatio(ratio) { this.box2dJoint.SetDampingRatio(ratio); box2dWakeJoint(this.box2dJoint); }
 
-    /** Get the damping ratio
+    /** Get how much the weld's spring is damped, 0 for none and 1 to stop it bouncing
      *  @return {number} */
     getDampingRatio() { return this.box2dJoint.GetDampingRatio(); }
-
-    /** @deprecated since 1.20, use setDampingRatio
-     *  @param {number} ratio */
-    setSpringDampingRatio(ratio) { this.setDampingRatio(ratio); }
-
-    /** @deprecated since 1.20, use getDampingRatio
-     *  @return {number} */
-    getSpringDampingRatio() { return this.getDampingRatio(); }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1836,7 +1914,7 @@ class Box2dFrictionJoint extends Box2dJoint
 
     /** Set the maximum friction force
      *  @param {number} force */
-    setMaxForce(force) { this.box2dJoint.SetMaxForce(max(force, 0)); } // Box2D stops on a negative one
+    setMaxForce(force) { this.box2dJoint.SetMaxForce(max(box2dFinite(force, 0), 0)); } // Box2D stops on a negative one
 
     /** Get the maximum friction force
      *  @return {number} */
@@ -1844,7 +1922,7 @@ class Box2dFrictionJoint extends Box2dJoint
 
     /** Set the maximum friction torque
      *  @param {number} torque */
-    setMaxTorque(torque) { this.box2dJoint.SetMaxTorque(max(torque, 0)); } // Box2D stops on a negative one
+    setMaxTorque(torque) { this.box2dJoint.SetMaxTorque(max(box2dFinite(torque, 0), 0)); } // Box2D stops on a negative one
 
     /** Get the maximum friction torque
      *  @return {number} */
@@ -1885,7 +1963,7 @@ class Box2dPulleyJoint extends Box2dJoint
         jointDef.set_localAnchorA(box2dTemp(localAnchorA));
         jointDef.set_localAnchorB(box2dTemp(localAnchorB));
         ASSERT(ratio, 'a pulley ratio can not be 0');
-        jointDef.set_ratio(ratio);
+        jointDef.set_ratio(box2dFinite(ratio, 1) || 1); // Box2D stops for good on 0
         jointDef.set_lengthA(groundAnchorA.distance(anchorA));
         jointDef.set_lengthB(groundAnchorB.distance(anchorB));
         jointDef.set_collideConnected(collide);
@@ -1946,11 +2024,11 @@ class Box2dMotorJoint extends Box2dJoint
         super(jointDef);
     }
 
-    /** Set the target linear offset, in frame A, in meters.
+    /** Set the target linear offset, in frame A, in meters
      *  @param {Vector2} offset */
     setLinearOffset(offset) { this.box2dJoint.SetLinearOffset(box2dTemp(offset)); }
 
-    /** Get the target linear offset, in frame A, in meters.
+    /** Get the target linear offset, in frame A, in meters
      *  @return {Vector2} */
     getLinearOffset() { return box2d.vec2From(this.box2dJoint.GetLinearOffset()); }
 
@@ -1964,7 +2042,7 @@ class Box2dMotorJoint extends Box2dJoint
 
     /** Set the maximum force
      *  @param {number} force */
-    setMaxForce(force) { this.box2dJoint.SetMaxForce(max(force, 0)); box2dWakeJoint(this.box2dJoint); } // Box2D stops on a negative one
+    setMaxForce(force) { this.box2dJoint.SetMaxForce(max(box2dFinite(force, 0), 0)); box2dWakeJoint(this.box2dJoint); } // Box2D stops on a negative one
 
     /** Get the maximum force
      *  @return {number} */
@@ -1972,7 +2050,7 @@ class Box2dMotorJoint extends Box2dJoint
 
     /** Set the maximum torque
      *  @param {number} torque */
-    setMaxTorque(torque) { this.box2dJoint.SetMaxTorque(max(torque, 0)); box2dWakeJoint(this.box2dJoint); } // Box2D stops on a negative one
+    setMaxTorque(torque) { this.box2dJoint.SetMaxTorque(max(box2dFinite(torque, 0), 0)); box2dWakeJoint(this.box2dJoint); } // Box2D stops on a negative one
 
     /** Get the maximum torque
      *  @return {number} */
@@ -2322,15 +2400,17 @@ class Box2dPlugin
     // helper functions
 
     /** converts a box2d vec2 to a Vector2
-     *  @param {Object} v */
+     *  @param {Object} v
+     *  @return {Vector2} */
     vec2From(v)
     {
-        ASSERT(v instanceof box2d.instance.b2Vec2);
+        ASSERT(v instanceof box2d.instance.b2Vec2, 'vec2From: expected a b2Vec2', v);
         return new Vector2(v.get_x(), v.get_y()); 
     }
 
     /** converts a box2d vec2 pointer to a Vector2
-     *  @param {Object} vp */
+     *  @param {Object} vp
+     *  @return {Vector2} */
     vec2FromPointer(vp)
     {
         const v = box2d.instance.wrapPointer(vp, box2d.instance.b2Vec2);
@@ -2339,19 +2419,22 @@ class Box2dPlugin
 
     /** converts a Vector2 to a new box2d vec2, which stays until destroyed with box2d.instance.destroy;
      *  the plugin itself passes Box2D reused ones, since Box2D copies every vector it is given
-     *  @param {Vector2} v */
+     *  @param {Vector2} v
+     *  @return {Object} - A Box2D vector, its b2Vec2 */
     vec2dTo(v)
     {
-        ASSERT(isVector2(v));
+        ASSERT(isVector2(v), 'vec2dTo: expected a vec2', v);
         return new box2d.instance.b2Vec2(v.x, v.y);
     }
 
     /** checks if a box2d object is null
-     *  @param {Object} o */
+     *  @param {Object} o
+     *  @return {boolean} */
     isNull(o) { return !box2d.instance.getPointer(o); }
 
     /** casts a box2d object to a shape type
-     *  @param {Object} o */
+     *  @param {Object} o
+     *  @return {Object} - The shape as its own Box2D type */
     castShapeObject(o)
     {
         switch (o.GetType())
@@ -2370,7 +2453,8 @@ class Box2dPlugin
     }
 
     /** casts a box2d object to a joint type
-     *  @param {Object} o */
+     *  @param {Object} o
+     *  @return {Object} - The joint as its own Box2D type */
     castJointObject(o)
     {
         switch (o.GetType())
@@ -2436,6 +2520,7 @@ async function box2dInit()
         {
             if (o.body)
             {
+                debug && box2dCheckUnusedFields(o);
                 // moved in place, as the engine moves an EngineObject's pos, so what holds it follows the body;
                 // box2d uses reverse angle
                 const p = o.body.GetPosition();