littlejsengine 1.24.2 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.24.2",
+  "version": "1.25.0",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",

package/plugins/box2d.js

@@ -303,7 +303,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 +333,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');
@@ -357,7 +359,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 +407,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 +428,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,7 +448,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 */
     addCircle(diameter=1, offset=vec2(), density, friction, restitution, isSensor)
     {
         ASSERT(isNumber(diameter) && diameter>0, 'diameter must be a positive number');
@@ -463,7 +469,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 +488,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 +522,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');
@@ -627,7 +636,7 @@ class Box2dObject extends EngineObject
      *  @param {number} angle */
     setTransform(pos, angle)
     {
-        this.pos = pos.copy();
+        this.pos.set(pos.x, pos.y); // its own pos kept, as an EngineObject's is
         this.angle = angle;
         // box2d uses reverse angle
         const x = pos.x, y = pos.y;
@@ -643,7 +652,7 @@ class Box2dObject extends EngineObject
      *  @param {Vector2} pos */
     setPosition(pos)
     {
-        this.pos = pos.copy();
+        this.pos.set(pos.x, pos.y); // its own pos kept, as an EngineObject's is
         const x = pos.x, y = pos.y;
         box2dWhenUnlocked(()=>
         {
@@ -1432,6 +1441,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
  */
@@ -1787,14 +1798,6 @@ class Box2dWeldJoint extends Box2dJoint
     /** Get the damping ratio
      *  @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(); }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2144,7 +2147,8 @@ class Box2dPlugin
         return box2d.raycastAll(start, end, includeSensors)[0];
     }
 
-    /** box aabb cast and return all the objects
+    /** Every object whose shapes' bounding boxes overlap a box, not the shapes themselves, so near the corner of a
+     *  turned box or a circle it finds one the box does not touch; use pointCast or a raycast for exact
      *  @param {Vector2} pos
      *  @param {Vector2} size
      *  @param {boolean} [includeSensors] - Also find sensors, trigger zones are passed through by default
@@ -2174,7 +2178,8 @@ class Box2dPlugin
         return queryObjects;
     }
 
-    /** box aabb cast and return the first object
+    /** The first object whose shapes' bounding boxes overlap a box, not the shapes themselves, so near the corner of
+     *  a turned box or a circle it finds one the box does not touch; use pointCast or a raycast for exact
      *  @param {Vector2} pos
      *  @param {Vector2} size
      *  @param {boolean} [includeSensors] - Also find sensors, trigger zones are passed through by default
@@ -2320,7 +2325,8 @@ 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);
@@ -2328,7 +2334,8 @@ class Box2dPlugin
     }
 
     /** 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);
@@ -2337,7 +2344,8 @@ 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));
@@ -2345,11 +2353,13 @@ class Box2dPlugin
     }
 
     /** 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())
@@ -2368,7 +2378,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())
@@ -2434,8 +2445,10 @@ async function box2dInit()
         {
             if (o.body)
             {
+                // moved in place, as the engine moves an EngineObject's pos, so what holds it follows the body;
                 // box2d uses reverse angle
-                o.pos = box2d.vec2From(o.body.GetPosition());
+                const p = o.body.GetPosition();
+                o.pos.set(p.get_x(), p.get_y());
                 o.angle = -o.body.GetAngle();
             }
         }