@perplexdotgg/bounce 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 9547-3732 Québec inc. / perplex.gg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+<div style="display: flex;">
+  <h1>Bounce - Premium 3D Physics for the Web</h1>
+</div>
+
+Bounce provides fast and determinstic 3D physics for Typescript and Javascript projects. Bounce is written in pure Typsescript (no WebAssembly). See the official website at [https://perplex.gg/bounce](https://perplex.gg/bounce) for demos, API and more info.
+
+## Credits and Acknowledgments
+
+Bounce was created by:
+- Durai Ziyaee - 95% of the code, physics R&D
+- Hamza Kubba - 5% of the code, funding, direction, project management, QA, website
+
+Although Bounce is mostly original code, it is heavily inspired by and draws heavily from:
+- Jolt
+- Rapier
+- Box2D
+- Godot
+- gl-matrix
+
+## Roadmap
+
+- Release example code (ETA Oct-Nov 2025)
+- Release the official character controller implementation (ETA Oct-Nov 2025)
+- Create a dedicated documentation site (ETA Nov 2025)
+- Fixing bugs. Please file an issue if you run into problems!
+- Want to see something here? Feel free to submit an issue!
+
+## How to contribute
+
+If you like this project and would like to support our work, please consider contributing code via pull requests, or donating via [open collective](https://opencollective.com/perplexgg). Contributions are greatly appreciated!

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@perplexdotgg/bounce",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Bounce",
+  "main": "./build/bounce.js",
+  "types": "./build/bounce.d.ts",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "watch": "tsc --watch",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "monomorph": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.0",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.11",
+    "vite-plugin-conditional-compiler": "^0.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/perplexdotgg/bounce"
+  }
+}

package/src/builders/ConvexHullBuilder.ts

@@ -0,0 +1,437 @@
+import { Mat3 } from "../math/mat3";
+import { Vec3 } from "../math/vec3";
+import { NumberValue } from "../math/NumberValue";
+import { Plane } from "../shape/Plane";
+import ConvexHull, {
+  ConvexHullFace,
+  ConvexHullNoConvex,
+  ConvexHullPoint,
+  ConvexHullWithConvex,
+  updateShape,
+} from "../shape/ConvexHull";
+import { ConvexHullBuilder3d, ConvexHullBuilderResult } from "./ConvexHullBuilder3d";
+import { degreesToRadians } from "../math/scalar";
+
+const covarianceCanonical = /*@__PURE__*/ Mat3.create();
+covarianceCanonical.fillDiagonal(1 / 60);
+covarianceCanonical.fillOffDiagonal(1 / 120);
+const covarianceAccumulated = /*@__PURE__*/ Mat3.create();
+const covarianceTransformed = /*@__PURE__*/ Mat3.create();
+const transform = /*@__PURE__*/ Mat3.create();
+const transposedTransform = /*@__PURE__*/ Mat3.create();
+const v1 = /*@__PURE__*/ Vec3.create();
+const v2 = /*@__PURE__*/ Vec3.create();
+const v3 = /*@__PURE__*/ Vec3.create();
+const zero = /*@__PURE__*/ Vec3.create({ x: 0, y: 0, z: 0 });
+const p = /*@__PURE__*/ Vec3.create();
+const faceCentroid = /*@__PURE__*/ Vec3.create();
+const faceNormal = /*@__PURE__*/ Vec3.create();
+const tempVector = /*@__PURE__*/ Vec3.create();
+const normal1 = /*@__PURE__*/ Vec3.create();
+const normal2 = /*@__PURE__*/ Vec3.create();
+const crossNormal1Normal2 = /*@__PURE__*/ Vec3.create();
+const normal3 = /*@__PURE__*/ Vec3.create();
+const p1 = /*@__PURE__*/ Plane.create();
+const p2 = /*@__PURE__*/ Plane.create();
+let p3 = /*@__PURE__*/ Plane.create();
+const offsetMask = /*@__PURE__*/ Vec3.create();
+const crossN1N2 = /*@__PURE__*/ Vec3.create();
+const n = /*@__PURE__*/ Mat3.create();
+const adj_n = /*@__PURE__*/ Mat3.create();
+const transformedOffset = /*@__PURE__*/ Vec3.create();
+
+export class ConvexHullBuilder {
+  buildFromPoints(
+    vertices: Float32Array,
+    convexRadius: number = 0.02,
+    hullTolerance: number = 1e-3,
+    convexHullPool: typeof ConvexHull.Pool = new ConvexHull.Pool(),
+    facePool: typeof ConvexHullFace.Pool = new ConvexHullFace.Pool(),
+    numberValuePool: typeof NumberValue.Pool = new NumberValue.Pool(),
+    planePool: typeof Plane.Pool = new Plane.Pool(),
+    pointPool: typeof ConvexHullPoint.Pool = new ConvexHullPoint.Pool(),
+    shapeNoConvexPointsPool: typeof Vec3.Pool = new Vec3.Pool(),
+  ): ConvexHull {
+    const maxPoints = 1000;
+    const maxVertexIndices = 1000;
+
+    // get counts from item buffers and use as max counts
+    const hull = ConvexHull.create({
+      convexRadius,
+      faces: { pool: facePool },
+      vertexIdx: { pool: numberValuePool },
+      planes: { pool: planePool },
+      points: { pool: pointPool },
+      shapeNoConvexPoints: { pool: shapeNoConvexPointsPool },
+    }, convexHullPool) as ConvexHull;
+    hull.shapeNoConvex = new ConvexHullNoConvex(hull, hull.shapeNoConvexPoints);
+    hull.shapeWithConvex = new ConvexHullWithConvex(hull);
+
+    // Check convex radius
+    if (hull.convexRadius < 0.0) {
+      throw new Error("Invalid convex radius");
+    }
+
+    // set vertex data on  polyhedron 3d
+    const polyhedron3d = new Vec3.Pool();
+    const polyhedron2d = new Vec3.Pool();
+    for (let i = 0; i < vertices.length; i += 3) {
+      Vec3.create({ x: vertices[i + 0], y: vertices[i + 1], z: vertices[i + 2] }, polyhedron3d);
+      Vec3.create({ x: vertices[i + 0], y: vertices[i + 1], z: vertices[i + 2] }, polyhedron2d);
+    }
+
+    // Build convex hull
+    const builder = new ConvexHullBuilder3d();
+    const result = builder.buildConvexHull(polyhedron3d, polyhedron2d, hullTolerance, maxPoints);
+    if (result !== ConvexHullBuilderResult.Success && result !== ConvexHullBuilderResult.MaxVerticesReached) {
+      throw new Error("Hull building failed");
+    }
+
+    const builder_faces = builder.faces;
+
+    // // Check the consistency of the resulting hull if we fully built it
+    // // TODO: revisit this error check because it seems to be failing even when the hull looks good visually
+    // if (result === ConvexHullBuilderResult.Success) {
+    //   const [max_error_face, max_error_distance, max_error_idx, coplaner_distance] = builder.determineMaxError();
+    //   if (max_error_distance > 4 * Math.max(coplaner_distance, hullTolerance)) {
+    //     // Coplanar distance could be bigger than the allowed tolerance if the points are far apart
+    //     throw new Error(
+    //       `Hull building failed, point ${max_error_idx} had an error of ${max_error_distance} (relative to tolerance: ${
+    //         max_error_distance / hullTolerance
+    //       })`
+    //     );
+    //   }
+    // }
+
+    // Calculate center of mass and volume
+    hull.computedVolume = builder.getCenterOfMassAndVolume(hull.computedCenterOfMass);
+    // make center of mass zero if it is close to zero
+    if (hull.computedCenterOfMass.isCloseToZero(1e-6)) {
+      hull.computedCenterOfMass.zero();
+    }
+
+    // Calculate covariance matrix
+    // See:
+    // - Why the inertia tensor is the inertia tensor - Jonathan Blow (http://number-none.com/blow/inertia/deriving_i.html)
+    // - How to find the inertia tensor (or other mass properties) of a 3D solid body represented by a triangle mesh (Draft) - Jonathan Blow, Atman J Binstock (http://number-none.com/blow/inertia/bb_inertia.doc)
+
+    // compute canonical covariance matrix
+    // this is the covariance matrix for a unit tetrahedron
+    // with vertices (0, 0, 0), (1, 0, 0), (0, 1, 0) and (0, 0, 1)
+    // with density 1 kg/m^3
+    // because of symmetry, we only need to "calculate". diagonal = 1 / 60, off-diagonal = 1 / 120
+
+    // start covariance actual at zero as it will be used for accumulation
+    covarianceAccumulated.fill(0);
+
+    for (const face of builder_faces) {
+      // Fourth point of the tetrahedron is at the center of mass, we subtract it from the other points so we get a tetrahedron with one vertex at zero
+      // The first point on the face will be used to form a triangle fan
+      let edge = face.firstEdge;
+      v1.subtractVectors(polyhedron3d.array[edge!.startIndex], hull.computedCenterOfMass);
+
+      // Get the 2nd point
+      edge = edge!.nextEdge;
+      v2.subtractVectors(polyhedron3d.array[edge!.startIndex], hull.computedCenterOfMass);
+
+      // Loop over the triangle fan
+      for (edge = edge!.nextEdge; edge !== face.firstEdge; edge = edge!.nextEdge) {
+        v3.subtractVectors(polyhedron3d.array[edge!.startIndex], hull.computedCenterOfMass);
+
+        // Affine transform that transforms a unit tetrahedon (with vertices (0, 0, 0), (1, 0, 0), (0, 1, 0) and (0, 0, 1) to this tetrahedron
+        transform.setColumns(v1, v2, v3);
+
+        // Calculate covariance matrix for this tetrahedron
+        const det_a = transform.computeDeterminant();
+
+        // C_transformed = det_a * (A * C_canonical * A^T)
+        transposedTransform.transposeMatrix(transform);
+        covarianceTransformed.multiplyMat3s(transform, covarianceCanonical);
+        covarianceTransformed.multiplyMat3s(covarianceTransformed, transposedTransform);
+        covarianceTransformed.multiplyByScalar(det_a);
+
+        // Add it
+        covarianceAccumulated.addMatrices(covarianceAccumulated, covarianceTransformed);
+
+        // Prepare for next triangle
+        v2.copy(v3);
+      }
+    }
+
+    // Calculate inertia matrix assuming density is 1
+    hull.inertia.identity();
+    hull.inertia.multiplyByScalar(covarianceAccumulated.e0 + covarianceAccumulated.e4 + covarianceAccumulated.e8);
+    hull.inertia.subtractMatrices(hull.inertia, covarianceAccumulated);
+
+    // Convert polygons from the builder to our internal representation
+    const vertexMap = new Map<number, number>();
+
+    for (const builder_face of builder_faces) {
+      // Determine where the vertices go
+      if (hull.vertexIdx.length > maxVertexIndices) {
+        throw new Error(`vertex index array too large: (${hull.vertexIdx.length}), max allowed ${maxVertexIndices}`);
+      }
+      let firstVertex = hull.vertexIdx.length;
+      let numVertices = 0;
+
+      // Loop over vertices in face
+      let edge = builder_face.firstEdge;
+      do {
+        // Remap to new index, not all points in the original input set are required to form the hull
+        // TODO: is it okay to set new_idx to 0 here?
+        let newIdx: number = 0;
+        const originalIdx = edge!.startIndex;
+        const m = vertexMap.get(originalIdx);
+        if (m !== undefined) {
+          // Found, reuse
+          newIdx = m;
+        } else {
+          // This is a new point
+          // Make relative to center of mass
+
+          p.subtractVectors(polyhedron3d.array[originalIdx], hull.computedCenterOfMass);
+
+          // TODO: Update local bounds
+
+          // Add to point list
+          if (hull.points.length <= maxPoints) {
+            newIdx = hull.points.length;
+            hull.points.create({ position: p, numFaces: 0, faces: zero });
+            vertexMap.set(originalIdx, newIdx);
+          }
+        }
+
+        // Append to vertex list
+        if (hull.vertexIdx.length >= maxVertexIndices) {
+          throw new Error(`vertex index array too large: (${hull.vertexIdx.length}), max allowed ${maxVertexIndices}`);
+        }
+
+        // TODO: should newIdx be initialized to some value?
+        hull.vertexIdx.create({ value: newIdx });
+        numVertices++;
+
+        edge = edge!.nextEdge;
+      } while (edge !== builder_face.firstEdge);
+
+      // Add face
+      hull.faces.create({ firstVertex: firstVertex, numVertices: numVertices });
+
+      // Add plane
+      faceCentroid.fromArray(builder_face.centroid);
+      faceNormal.fromArray(builder_face.normal);
+      tempVector.subtractVectors(faceCentroid, hull.computedCenterOfMass);
+      faceNormal.normalize();
+
+      const plane = hull.planes.create(undefined);
+      plane.fromPointAndNormal(tempVector, faceNormal);
+    }
+
+    // Test if GetSupportFunction can support this many points
+    if (hull.points.length > maxPoints) {
+      throw new Error(`Internal error: Too many points in hull (${hull.points.length}), max allowed ${maxPoints}`);
+    }
+
+    for (let p = 0; p < hull.points.length; ++p) {
+      // For each point, find faces that use the point
+      let faces: number[] = [];
+
+      for (let f = 0; f < hull.faces.length; ++f) {
+        const face = hull.faces.getAtIndex(f)!;
+
+        for (let v = 0; v < face.numVertices; ++v) {
+          const vertexIndex = hull.vertexIdx.getAtIndex(face.firstVertex + v)!;
+          if (vertexIndex.value === p) {
+            faces.push(f);
+            break;
+          }
+        }
+      }
+
+      if (faces.length < 2) {
+        throw new Error("A point must be connected to 2 or more faces!");
+      }
+
+      // Find the 3 normals that form the largest tetrahedron
+      // The largest tetrahedron we can get is ((1, 0, 0) x (0, 1, 0)) . (0, 0, 1) = 1, if the volume is only 5% of that,
+      // the three vectors are too coplanar and we fall back to using only 2 plane normals
+      let biggest_volume = 0.05;
+      const best3 = [-1, -1, -1];
+
+      // When using 2 normals, we get the two with the biggest angle between them with a minimal difference of 1 degree
+      // otherwise we fall back to just using 1 plane normal
+      let smallest_dot = Math.cos(degreesToRadians(1.0));
+      const best2 = [-1, -1];
+
+      for (let face1 = 0; face1 < faces.length; ++face1) {
+        const plane1 = hull.planes.getAtIndex(faces[face1])!;
+        normal1.copy(plane1.normal);
+
+        for (let face2 = face1 + 1; face2 < faces.length; ++face2) {
+          const plane2 = hull.planes.getAtIndex(faces[face2])!;
+          normal2.copy(plane2.normal);
+
+          crossNormal1Normal2.crossVectors(normal1, normal2);
+
+          // Determine the 2 face normals that are most apart
+          const dot = normal1.dot(normal2);
+          if (dot < smallest_dot) {
+            smallest_dot = dot;
+            best2[0] = faces[face1];
+            best2[1] = faces[face2];
+          }
+
+          // Determine the 3 face normals that form the largest tetrahedron
+          for (let face3 = face2 + 1; face3 < faces.length; ++face3) {
+            const plane3 = hull.planes.getAtIndex(faces[face3])!;
+            normal3.copy(plane3.normal);
+
+            const volume = Math.abs(crossNormal1Normal2.dot(normal3));
+            if (volume > biggest_volume) {
+              biggest_volume = volume;
+              best3[0] = faces[face1];
+              best3[1] = faces[face2];
+              best3[2] = faces[face3];
+            }
+          }
+        }
+      }
+
+      // If we didn't find 3 planes, use 2, if we didn't find 2 use 1
+      let pointFaces: [number, number, number];
+      if (best3[0] !== -1) {
+        faces = [best3[0], best3[1], best3[2]];
+        pointFaces = [best3[0], best3[1], best3[2]];
+      } else if (best2[0] !== -1) {
+        faces = [best2[0], best2[1]];
+        pointFaces = [best2[0], best2[1], -1];
+      } else {
+        faces = [faces[0], -1, -1];
+        pointFaces = [faces[0], -1, -1];
+      }
+
+      // Copy the faces to the points buffer
+      const point = hull.points.getAtIndex(p)!;
+      point.numFaces = faces.length;
+      point.faces.fromArray(pointFaces);
+    }
+
+    // If the convex radius is already zero, there's no point in further reducing it
+    if (hull.convexRadius > 0.0) {
+      // Find out how thin the hull is by walking over all planes and checking the thickness of the hull in that direction
+      let minSize = Number.MAX_VALUE;
+
+      for (let i = 0; i < hull.planes.length; i++) {
+        const plane = hull.planes.getAtIndex(i)!;
+
+        // Take the point that is furthest away from the plane as thickness of this hull
+        let maxDist = 0.0;
+
+        for (let j = 0; j < hull.points.length; j++) {
+          const point = hull.points.getAtIndex(j)!;
+
+          const dist = -plane.signedDistance(point.position); // Point is always behind plane, so we need to negate
+          if (dist > maxDist) {
+            maxDist = dist;
+          }
+        }
+        minSize = Math.min(minSize, maxDist);
+      }
+
+      // We need to fit in 2x the convex radius in min_size, so reduce the convex radius if it's bigger than that
+      hull.convexRadius = Math.min(hull.convexRadius, 0.5 * minSize);
+    }
+
+    // Now walk over all points and see if we have to further reduce the convex radius because of sharp edges
+    if (hull.convexRadius > 0.0) {
+      for (let i = 0; i < hull.points.length; i++) {
+        const point = hull.points.getAtIndex(i)!;
+
+        // If we have a single face, shifting back is easy and we don't need to reduce the convex radius
+        if (point.numFaces !== 1) {
+          // Get first two planes
+          p1.copy(hull.planes.getAtIndex(point.faces.x)!);
+          p2.copy(hull.planes.getAtIndex(point.faces.y)!);
+
+          if (point.numFaces === 3) {
+            // Get third plane
+            p3.copy(hull.planes.getAtIndex(point.faces.z)!);
+
+            // All 3 planes will be offset by the convex radius
+            offsetMask.replicate(1);
+          } else {
+            // Third plane has normal perpendicular to the other two planes and goes through the vertex position
+            if (point.numFaces !== 2) {
+              throw new Error("Invalid number of faces");
+            }
+
+            crossN1N2.crossVectors(p1.normal, p2.normal);
+            p3.fromPointAndNormal(point.position, crossN1N2);
+
+            // Only the first and 2nd plane will be offset, the 3rd plane is only there to guide the intersection point
+            offsetMask.set({ x: 1, y: 1, z: 0 });
+          }
+
+          // Plane equation: point . normal + constant = 0
+          // Offsetting the plane backwards with convex radius r: point . normal + constant + r = 0
+          // To find the intersection 'point' of 3 planes we solve:
+          // |n1x n1y n1z| |x|     | r + c1 |
+          // |n2x n2y n2z| |y| = - | r + c2 | <=> n point = -r (1, 1, 1) - (c1, c2, c3)
+          // |n3x n3y n3z| |z|     | r + c3 |
+          // Where point = (x, y, z), n1x is the x component of the first plane, c1 = plane constant of plane 1, etc.
+          // The relation between how much the intersection point shifts as a function of r is: -r * n^-1 (1, 1, 1) = r * offset
+          // Where offset = -n^-1 (1, 1, 1) or -n^-1 (1, 1, 0) in case only the first 2 planes are offset
+          // The error that is introduced by a convex radius r is: error = r * |offset| - r
+          // So the max convex radius given error is: r = error / (|offset| - 1)
+
+          // TODO: using a mat3 here instead of a mat4 because mat4.3x3 functions not implemented, as a result, not sure if this is correct
+
+          n.e0 = p1.normal.x;
+          n.e1 = p1.normal.y;
+          n.e2 = p1.normal.z;
+          n.e3 = p2.normal.x;
+          n.e4 = p2.normal.y;
+          n.e5 = p2.normal.z;
+          n.e6 = p3.normal.x;
+          n.e7 = p3.normal.y;
+          n.e8 = p3.normal.z;
+          n.transpose();
+
+          const det_n = n.computeDeterminant();
+          if (det_n === 0.0) {
+            // If the determinant is zero, the matrix is not invertible so no solution exists to move the point backwards and we have to choose a convex radius of zero
+            hull.convexRadius = 0.0;
+            break;
+          }
+
+          adj_n.adjointMatrix(n);
+
+          transformedOffset.transformVectorFromMat3(offsetMask, adj_n);
+          transformedOffset.scale(1 / det_n);
+          const offset = transformedOffset.length();
+          if (offset <= 1.0) {
+            throw new Error("Invalid offset");
+          }
+          const max_convex_radius = hullTolerance / (offset - 1.0);
+          hull.convexRadius = Math.min(hull.convexRadius, max_convex_radius);
+        }
+      }
+    }
+
+    // Calculate the inner radius by getting the minimum distance from the origin to the planes of the hull
+    hull.innerRadius = Number.MAX_VALUE;
+    for (let i = 0; i < hull.planes.length; i++) {
+      const plane = hull.planes.getAtIndex(i)!;
+      hull.innerRadius = Math.min(hull.innerRadius, -plane.constant);
+    }
+    // Clamp against zero, this should do nothing as the shape is centered around the
+    // center of mass but for flat convex hulls there may be numerical round off issues
+    hull.innerRadius = Math.max(0.0, hull.innerRadius);
+
+    for (let i = 0; i < hull.points.length; i++) {
+      hull.shapeNoConvexPoints.create();
+    }
+
+    updateShape(hull);
+    return hull;
+  }
+}