@ludra/physics 0.9.0 → 0.91.0

package/dist/index.d.ts

@@ -5,6 +5,11 @@ import { type Entity, type PhysicsEngine, type PhysicsHost, type PhysicsSettings
  * `"physics": "rapier"` can be created. Safe to call more than once.
  */
 export declare function loadRapierPhysics(): Promise<void>;
+/**
+ * Loads Rapier 3D and registers the "rapier3d" engine, which scenes with `"dimensions": 3`
+ * run on. It is a separate module, so 2D games never download its WebAssembly.
+ */
+export declare function loadRapier3DPhysics(): Promise<void>;
 /**
  * Ludra's real physics engine: Rapier's deterministic build, so a simulation is
  * bit-for-bit identical on every machine and in the browser, and tests stay valid.

package/dist/index.js

@@ -44,6 +44,13 @@ export function loadRapierPhysics() {
     loading ??= RAPIER.init().then(() => registerPhysics("rapier", (settings) => new RapierPhysics(settings)));
     return loading;
 }
+/**
+ * Loads Rapier 3D and registers the "rapier3d" engine, which scenes with `"dimensions": 3`
+ * run on. It is a separate module, so 2D games never download its WebAssembly.
+ */
+export async function loadRapier3DPhysics() {
+    await (await import("./rapier3d.js")).loadRapier3DPhysics();
+}
 // Rapier's memory lives in WebAssembly; free it when a world is garbage collected.
 const cleanup = new FinalizationRegistry((world) => world.free());
 /**
@@ -156,8 +163,10 @@ export class RapierPhysics {
             const baseAnchor = localPoint(base, there);
             const ownAnchor = toRapier(spec.anchor.x, spec.anchor.y);
             const length = spec.length || Math.hypot(there.x - here.x, there.y - here.y);
+            // In 2D the axis is degrees (validation rejects a 3D vector here).
+            const axis = typeof spec.axis === "number" ? spec.axis : 0;
             const data = spec.type === "prismatic"
-                ? RAPIER.JointData.prismatic(baseAnchor, ownAnchor, rotateBack(base, toRapier(Math.cos(spec.axis * DEGREES), Math.sin(spec.axis * DEGREES))))
+                ? RAPIER.JointData.prismatic(baseAnchor, ownAnchor, rotateBack(base, toRapier(Math.cos(axis * DEGREES), Math.sin(axis * DEGREES))))
                 : spec.type === "fixed"
                     ? RAPIER.JointData.fixed(baseAnchor, 0, ownAnchor, base.rotation() - link.body.rotation())
                     : spec.type === "rope"

package/dist/rapier3d.d.ts

@@ -0,0 +1,83 @@
+import { type World as RapierWorld } from "@dimforge/rapier3d-deterministic-compat";
+import { type Entity, type PhysicsEngine, type PhysicsHost, type PhysicsSettings, type RayHit, type RayOptions } from "@ludra/core";
+/**
+ * Ludra's 3D worlds use Rapier's own conventions: metres, +y up, right-handed (+z toward
+ * the viewer). Nothing is mirrored, unlike 2D. Rotations are degrees in Ludra, applied
+ * y (turn), then x (tilt), then z (roll), and quaternions in Rapier.
+ */
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface Quat extends Vec3 {
+    w: number;
+}
+/**
+ * Loads Rapier 3D's WebAssembly and registers the "rapier3d" engine, which every scene with
+ * `"dimensions": 3` runs on. Safe to call more than once.
+ */
+export declare function loadRapier3DPhysics(): Promise<void>;
+/** Degrees (applied y, then x, then z) to a quaternion. */
+export declare function quaternionFromDegrees(x: number, y: number, z: number): Quat;
+/** A quaternion back to degrees (y, then x, then z), as three.js's "YXZ" order reads it. */
+export declare function degreesFromQuaternion(q: Quat): Vec3;
+/**
+ * Ludra's 3D physics engine: Rapier 3D's deterministic build, so a simulation is bit-for-bit
+ * the same on every machine and in the browser. Bodies rotate in 3D, can be boxes, spheres,
+ * capsules, cylinders or convex hulls, and have friction and mass; players walk through
+ * Rapier's character controller.
+ */
+export declare class Rapier3DPhysics implements PhysicsEngine {
+    readonly name = "rapier3d";
+    readonly world: RapierWorld;
+    private readonly events;
+    private readonly links;
+    private readonly byCollider;
+    private pendingJoints;
+    constructor(settings: PhysicsSettings);
+    add(entity: Entity): void;
+    remove(entity: Entity): void;
+    /** Creates the joints whose two ends now both exist. */
+    private connectJoints;
+    private createController;
+    step(host: PhysicsHost): void;
+    /**
+     * Moves a player by its velocity (plus gravity, and the platform it stands on) through the
+     * character controller, which resolves slopes, steps and walls.
+     */
+    private moveCharacter;
+    /** A body is grounded when a solid touches it from below; it then stands on that solid. */
+    private updateGround;
+    mass(e: Entity): number;
+    applyImpulse(e: Entity, x: number, y: number, at?: {
+        x: number;
+        y: number;
+        z?: number;
+    }, z?: number): void;
+    /** Spin around z, in degrees per second (the axis the screen faces). */
+    angularVelocity(e: Entity): number;
+    setAngularVelocity(e: Entity, value: number): void;
+    spin(e: Entity): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    setSpin(e: Entity, value: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    raycast(_host: PhysicsHost, from: {
+        x: number;
+        y: number;
+        z?: number;
+    }, to: {
+        x: number;
+        y: number;
+        z?: number;
+    }, options?: RayOptions): RayHit | undefined;
+    raw(resolve: (target: unknown) => Entity | undefined): unknown;
+    overlaps(a: Entity, b: Entity, margin?: number): boolean;
+}
+export {};