littlejsengine 1.19.3 → 1.21.0

package/plugins/math3d.js

@@ -288,6 +288,7 @@ class Vector3
 
 // scratch for multiply, nothing keeps a reference to it
 const matrix4Scratch = new Float32Array(16);
+const matrix4Identity = new Float32Array([1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]);
 
 /**
  * 4x4 transform matrix for moving, rotating and scaling points in 3D
@@ -330,22 +331,23 @@ class Matrix4
         return r;
     }
 
-    /** Returns a new rotation matrix, rolled first, then pitched, then yawed
+    /** Returns a rotation matrix, rolled first, then pitched, then yawed
      *  @param {Vector3} euler - vec3(pitch, yaw, roll) in radians
+     *  @param {Matrix4} [matrix] - Written into instead of a new one, for a loop that builds many
      *  @return {Matrix4} */
-    static rotation(euler)
+    static rotation(euler, matrix=new Matrix4)
     {
         ASSERT_VECTOR3_VALID(euler);
         const cx = cos(euler.x), sx = sin(euler.x);
         const cy = cos(euler.y), sy = sin(euler.y);
         const cz = cos(euler.z), sz = sin(euler.z);
-        const r = new Matrix4;
-        const m = r.m;
-        // R = Ry * Rx * Rz written out, column major
-        m[0] = cy*cz + sy*sx*sz;  m[1] = cx*sz;  m[2]  = -sy*cz + cy*sx*sz;
-        m[4] = -cy*sz + sy*sx*cz; m[5] = cx*cz;  m[6]  = sy*sz + cy*sx*cz;
-        m[8] = sy*cx;             m[9] = -sx;    m[10] = cy*cx;
-        return r;
+        const m = matrix.m;
+        // R = Ry * Rx * Rz written out, column major, every element set so a reused matrix comes out clean
+        m[0] = cy*cz + sy*sx*sz;  m[1] = cx*sz;  m[2]  = -sy*cz + cy*sx*sz; m[3] = 0;
+        m[4] = -cy*sz + sy*sx*cz; m[5] = cx*cz;  m[6]  = sy*sz + cy*sx*cz;  m[7] = 0;
+        m[8] = sy*cx;             m[9] = -sx;    m[10] = cy*cx;             m[11] = 0;
+        m[12] = m[13] = m[14] = 0; m[15] = 1;
+        return matrix;
     }
 
     /** Returns a new scale matrix
@@ -416,8 +418,10 @@ class Matrix4
         if (!z.lengthSquared())
             z = vec3(0, 0, 1); // eye is on the target, face -Z
         let x = up.cross(z).normalize();
-        if (!x.lengthSquared()) // up is along the view direction, pick another
-            x = (abs(z.y) > .99 ? vec3(0, 0, 1) : vec3(0, 1, 0)).cross(z).normalize();
+        // up is along the view direction, pick another; looking straight down or up keeps +X as the right axis,
+        // as three.js does and as a view tilting there from the +Z side ends up
+        if (!x.lengthSquared())
+            x = (abs(z.y) > .99 ? vec3(0, 0, z.y > 0 ? -1 : 1) : vec3(0, 1, 0)).cross(z).normalize();
         const y = z.cross(x);
         return new Matrix4([x.x, x.y, x.z, 0,  y.x, y.y, y.z, 0,  z.x, z.y, z.z, 0,  eye.x, eye.y, eye.z, 1]);
     }
@@ -530,6 +534,41 @@ class Matrix4
      *  @return {Vector3} */
     getTranslation() { return new Vector3(this.m[12], this.m[13], this.m[14]); }
 
+    /** Returns the determinant of the rotation and scale part: negative when the matrix mirrors, 0 when it flattens a
+     *  shape and has no inverse
+     *  @return {number} */
+    determinant()
+    {
+        const m = this.m;
+        return m[0]*(m[5]*m[10] - m[6]*m[9]) - m[4]*(m[1]*m[10] - m[2]*m[9]) + m[8]*(m[1]*m[6] - m[2]*m[5]);
+    }
+
+    /** Returns the scale part of this matrix, the length of each axis; a mirroring matrix shows as a negative x
+     *  @return {Vector3} */
+    getScale()
+    {
+        const m = this.m;
+        const x = hypot(m[0], m[1], m[2]), y = hypot(m[4], m[5], m[6]), z = hypot(m[8], m[9], m[10]);
+        return new Vector3(this.determinant() < 0 ? -x : x, y, z);
+    }
+
+    /** Returns the rotation part of this matrix as vec3(pitch, yaw, roll), the angles Matrix4.rotation builds it from
+     *  - The scale is divided out first, so it works on a full transform
+     *  - A matrix with shear, from a scaled parent with a turned child, has no exact answer and gets the nearest
+     *  @return {Vector3} */
+    getRotation()
+    {
+        // the axes at unit length, see Matrix4.rotation for which element is which
+        const m = this.m, s = this.getScale();
+        const sx = s.x || 1, sy = s.y || 1, sz = s.z || 1;
+        const m1 = m[1] / sx, m5 = m[5] / sy, m8 = m[8] / sz, m9 = m[9] / sz, m10 = m[10] / sz;
+        const pitch = Math.asin(clamp(-m9, -1, 1));
+        if (abs(m9) < 1 - 1e-6)
+            return new Vector3(pitch, atan2(m8, m10), atan2(m1, m5));
+        // straight up or down: yaw and roll turn about the same axis, so the roll is zero and yaw takes it all
+        return new Vector3(pitch, atan2(m[4] / sy * -m9, m[0] / sx), 0);
+    }
+
     /** Returns a string representation of this matrix for debugging
      *  @return {string} */
     toString()
@@ -550,18 +589,20 @@ class Matrix4
  * @param {Vector3} [pos]
  * @param {Vector3} [rotation] - vec3(pitch, yaw, roll) in radians
  * @param {Vector3} [scale]
+ * @param {Matrix4} [matrix] - Written into instead of a new one, for a loop that builds many
  * @return {Matrix4}
  * @memberof Math3D
  */
-function buildMatrix(pos, rotation, scale)
+function buildMatrix(pos, rotation, scale, matrix=new Matrix4)
 {
     ASSERT(!pos || isVector3(pos), 'pos must be a Vector3', pos);
     ASSERT(!scale || isVector3(scale), 'scale must be a Vector3', scale);
+    ASSERT(matrix instanceof Matrix4, 'the matrix to write into must be a Matrix4');
     // scale the rotation columns and drop the position in, instead of multiplying three matrices
     // an object that is not turned at all is most of a big scene, and identity is what the six
     // trig calls would have worked out to anyway
-    const turned = rotation && (rotation.x || rotation.y || rotation.z);
-    const matrix = turned ? Matrix4.rotation(rotation) : new Matrix4, m = matrix.m;
+    const turned = rotation && (rotation.x || rotation.y || rotation.z), m = matrix.m;
+    turned ? Matrix4.rotation(rotation, matrix) : m.set(matrix4Identity);
     if (scale)
     {
         m[0] *= scale.x; m[1] *= scale.x; m[2]  *= scale.x;
@@ -611,36 +652,62 @@ class Ray3D
 
 ///////////////////////////////////////////////////////////////////////////////
 // 3D collision helpers, none of them change anything that is passed in
-// Boxes sit centered on pos and take a full size, like drawRect
+// Boxes sit centered on pos and take a full size, like drawRect, upright unless given a rotation, an Euler vec3 like
+// rotation3D, which turns them about their center
 // Cylinders stand up the Y axis, centered on pos, with a full height
 // Names that could be mistaken for 2D functions get a 3D suffix
 
+// whether a rotation turns anything, a missing one does not
+const isTurned3D = (rotation)=> !!rotation && !!(rotation.x || rotation.y || rotation.z);
+
+// a turned box's three unit axes, the columns of its rotation
+function boxAxes3D(rotation)
+{
+    const m = buildMatrix(undefined, rotation).m;
+    return [vec3(m[0], m[1], m[2]), vec3(m[4], m[5], m[6]), vec3(m[8], m[9], m[10])];
+}
+
+// a point in a turned box's own space, from its center, and a vector from that space back to the world's
+function boxLocal3D(point, pos, axes)
+{
+    const d = point.subtract(pos);
+    return vec3(d.dot(axes[0]), d.dot(axes[1]), d.dot(axes[2]));
+}
+const boxWorld3D = (v, axes)=> axes[0].scale(v.x).add(axes[1].scale(v.y)).add(axes[2].scale(v.z));
+
 /**
- * Check if a point is inside an axis aligned box, boundary is inclusive
+ * Check if a point is inside a box, boundary is inclusive
  * @param {Vector3} point
  * @param {Vector3} pos - Center of the box
  * @param {Vector3} size - Full size of the box
+ * @param {Vector3} [rotation] - How the box is turned, upright when left out
  * @return {boolean}
  * @memberof Math3D
  */
-function isPointInBox3D(point, pos, size)
+function isPointInBox3D(point, pos, size, rotation)
 {
+    if (isTurned3D(rotation))
+        return isPointInBox3D(boxLocal3D(point, pos, boxAxes3D(rotation)), vec3(), size);
     return abs(point.x - pos.x) <= size.x/2 &&
         abs(point.y - pos.y) <= size.y/2 &&
         abs(point.z - pos.z) <= size.z/2;
 }
 
 /**
- * Check if two axis aligned boxes are overlapping, touching edges do not overlap
+ * Check if two boxes are overlapping, touching edges do not overlap
  * @param {Vector3} posA
  * @param {Vector3} sizeA - Full size of box A
  * @param {Vector3} posB
  * @param {Vector3} [sizeB] - Full size of box B, zero for a point
+ * @param {Vector3} [rotationA] - How box A is turned, upright when left out
+ * @param {Vector3} [rotationB] - How box B is turned
  * @return {boolean}
  * @memberof Math3D
  */
-function isOverlapping3D(posA, sizeA, posB, sizeB=vec3())
+function isOverlapping3D(posA, sizeA, posB, sizeB=vec3(), rotationA, rotationB)
 {
+    if (isTurned3D(rotationA) || isTurned3D(rotationB))
+        return !!collideBoxBox3D(posA, sizeA, posB, sizeB, rotationA, rotationB);
     const d = posA.subtract(posB);
     return abs(d.x) < (sizeA.x + sizeB.x)/2 &&
         abs(d.y) < (sizeA.y + sizeB.y)/2 &&
@@ -669,16 +736,19 @@ function collideSphereSphere(posA, radiusA, posB, radiusB)
 }
 
 /**
- * Returns the vector to move a sphere out of an axis aligned box, or undefined
+ * Returns the vector to move a sphere out of a box, or undefined
  * @param {Vector3} pos - Sphere center
  * @param {number} radius
  * @param {Vector3} boxPos
  * @param {Vector3} boxSize - Full size of the box
+ * @param {Vector3} [boxRotation] - How the box is turned, upright when left out
  * @return {Vector3|undefined}
  * @memberof Math3D
  */
-function collideSphereBox(pos, radius, boxPos, boxSize)
+function collideSphereBox(pos, radius, boxPos, boxSize, boxRotation)
 {
+    if (isTurned3D(boxRotation))
+        return collideSphereOrientedBox3D(pos, radius, boxPos, boxSize, boxAxes3D(boxRotation));
     const h = boxSize.scale(.5);
     const closest = vec3(
         clamp(pos.x, boxPos.x - h.x, boxPos.x + h.x),
@@ -766,15 +836,20 @@ function collideSphereCylinder(pos, radius, cylinderPos, cylinderRadius, cylinde
 /**
  * Returns the vector to move box A by so it no longer overlaps box B, the shortest way out, or undefined
  * - The 3D twin of collideBoxBox
+ * - Turned boxes are tested by the separating axis test, the push is along the direction they overlap least on
  * @param {Vector3} posA
  * @param {Vector3} sizeA - Full size of box A
  * @param {Vector3} posB
  * @param {Vector3} sizeB - Full size of box B
+ * @param {Vector3} [rotationA] - How box A is turned, upright when left out
+ * @param {Vector3} [rotationB] - How box B is turned
  * @return {Vector3|undefined}
  * @memberof Math3D
  */
-function collideBoxBox3D(posA, sizeA, posB, sizeB)
+function collideBoxBox3D(posA, sizeA, posB, sizeB, rotationA, rotationB)
 {
+    if (isTurned3D(rotationA) || isTurned3D(rotationB))
+        return collideOrientedBoxes3D(posA, sizeA, boxAxes3D(rotationA), posB, sizeB, boxAxes3D(rotationB));
     const d = posA.subtract(posB);
     const overlapX = (sizeA.x + sizeB.x)/2 - abs(d.x);
     const overlapY = (sizeA.y + sizeB.y)/2 - abs(d.y);
@@ -784,6 +859,44 @@ function collideBoxBox3D(posA, sizeA, posB, sizeB)
     return pushOutAxis3D(d, overlapX, overlapY, overlapZ);
 }
 
+// the push to move a sphere out of a box turned to these axes: in the box's own space it is upright, and the push
+// goes back out turned
+function collideSphereOrientedBox3D(pos, radius, boxPos, boxSize, axes)
+{
+    const push = collideSphereBox(boxLocal3D(pos, boxPos, axes), radius, vec3(), boxSize);
+    return push && boxWorld3D(push, axes);
+}
+
+// the world's axes, for an upright box among turned ones
+const BOX_WORLD_AXES = Object.freeze([vec3(1, 0, 0), vec3(0, 1, 0), vec3(0, 0, 1)]);
+
+// the shortest push to move box A out of box B by the separating axis test: each box's three face directions and
+// the nine across an edge of each; a gap on any of them is no touch, and the push is along the least overlap, from
+// B to A; an edge direction has to overlap clearly less to win, so a box lying on another leaves by the face
+function collideOrientedBoxes3D(posA, sizeA, axesA, posB, sizeB, axesB)
+{
+    const d = posA.subtract(posB), ha = sizeA.scale(.5), hb = sizeB.scale(.5);
+    const reach = (h, axes, n)=> h.x * abs(axes[0].dot(n)) + h.y * abs(axes[1].dot(n)) + h.z * abs(axes[2].dot(n));
+    let push, least = Infinity;
+    const separated = (axis, weight)=>
+    {
+        const lengthSquared = axis.lengthSquared();
+        if (lengthSquared < 1e-12) return false; // parallel edges give no direction to test
+        const n = axis.scale(lengthSquared ** -.5), along = d.dot(n);
+        const overlap = reach(ha, axesA, n) + reach(hb, axesB, n) - abs(along);
+        if (overlap <= 0) return true;
+        if (overlap * weight < least)
+            least = overlap * weight, push = n.scale(along < 0 ? -overlap : overlap);
+        return false;
+    };
+    for (const axis of [...axesA, ...axesB])
+        if (separated(axis, 1)) return;
+    for (const a of axesA)
+    for (const b of axesB)
+        if (separated(a.cross(b), 1.05)) return;
+    return push;
+}
+
 /**
  * Returns the distance along the ray to the first intersection with a sphere, or undefined
  * - The hit is ray.getPosition(distance), a direction that is not unit length scales the distance
@@ -798,12 +911,12 @@ function raycastSphere(ray, pos, radius)
 {
     const {origin, direction} = ray;
     const oc = origin.subtract(pos);
+    const c = oc.dot(oc) - radius*radius;
+    if (c < 0)
+        return 0; // origin is inside the sphere, even for a ray of no length, as raycastBox gives
     const a = direction.dot(direction);
     if (!a)
         return undefined;
-    const c = oc.dot(oc) - radius*radius;
-    if (c < 0)
-        return 0; // origin is inside the sphere
     const b = 2*oc.dot(direction);
     const discriminant = b*b - 4*a*c;
     if (discriminant < 0)
@@ -832,17 +945,25 @@ function raycastPlane(ray, planePos, planeNormal)
 }
 
 /**
- * Returns the distance along the ray to the first intersection with an axis aligned box, or undefined
+ * Returns the distance along the ray to the first intersection with a box, or undefined
  * - The hit is ray.getPosition(distance), a direction that is not unit length scales the distance
  * - A ray starting inside the box is already there, so it gets back 0
  * @param {Ray3D} ray
  * @param {Vector3} pos - Center of the box
  * @param {Vector3} size - Full size of the box
+ * @param {Vector3} [rotation] - How the box is turned, upright when left out
  * @return {number|undefined}
  * @memberof Math3D
  */
-function raycastBox(ray, pos, size)
+function raycastBox(ray, pos, size, rotation)
 {
+    if (isTurned3D(rotation))
+    {
+        // the ray in the box's own space, where the box is upright; turning keeps the distances
+        const axes = boxAxes3D(rotation), d = ray.direction;
+        const direction = vec3(d.dot(axes[0]), d.dot(axes[1]), d.dot(axes[2]));
+        return raycastBox(new Ray3D(boxLocal3D(ray.origin, pos, axes), direction), vec3(), size);
+    }
     const {origin, direction} = ray;
     const h = size.scale(.5);
     const boxMin = pos.subtract(h), boxMax = pos.add(h);