@orillusion/physics-rapier 0.1.0

package/dist/query/PhysicsQuery.d.ts

@@ -0,0 +1,55 @@
+import { Vector3, Quaternion } from '@orillusion/core';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { Rigidbody } from '../rigidbody/Rigidbody';
+export interface QueryFilter {
+    /** Maximum hit distance / time-of-impact. Default Infinity-ish (1e6). */
+    maxDistance?: number;
+    /** Whether the ray treats colliders as solid (hits start-inside as t=0). */
+    solid?: boolean;
+    /** Skip a specific Rigidbody (e.g. the caster). */
+    excludeRigidbody?: Rigidbody;
+    /** Skip a specific Rapier collider. */
+    excludeCollider?: RAPIER.Collider;
+    /** Ignore sensors. */
+    excludeSensors?: boolean;
+}
+export interface RaycastHit {
+    rigidbody: Rigidbody | null;
+    collider: RAPIER.Collider;
+    /** World-space hit point. */
+    point: Vector3;
+    /** World-space surface normal at the hit. */
+    normal: Vector3;
+    /** Time-of-impact along the ray (= distance for unit-length direction). */
+    toi: number;
+}
+export interface ShapeHit {
+    rigidbody: Rigidbody | null;
+    collider: RAPIER.Collider;
+    point: Vector3;
+    normal1: Vector3;
+    normal2: Vector3;
+    toi: number;
+}
+/**
+ * Static physics queries — Rapier-backed.
+ *
+ * Replaces the missing public query API in `@orillusion/physics`.
+ */
+export declare class PhysicsQuery {
+    /** Cast a ray and return the closest hit, or `null`. */
+    static raycast(origin: Vector3, direction: Vector3, filter?: QueryFilter): RaycastHit | null;
+    /** Collect every collider intersected by the ray, up to `maxDistance`. */
+    static raycastAll(origin: Vector3, direction: Vector3, filter?: QueryFilter): RaycastHit[];
+    /** Sweep a shape along `velocity` for `maxDistance`, return first hit or null. */
+    static sweep(shape: RAPIER.ColliderDesc, position: Vector3, rotation: Quaternion, velocity: Vector3, filter?: QueryFilter): ShapeHit | null;
+    /** Return every collider whose AABB intersects the given shape's AABB. */
+    static overlap(shape: RAPIER.ColliderDesc, position: Vector3, rotation: Quaternion, filter?: QueryFilter): Rigidbody[];
+    /** Project a point onto the closest collider; returns `null` if none. */
+    static closestPoint(point: Vector3, filter?: QueryFilter): {
+        rigidbody: Rigidbody | null;
+        collider: RAPIER.Collider;
+        point: Vector3;
+        isInside: boolean;
+    } | null;
+}

package/dist/rigidbody/Rigidbody.d.ts

@@ -0,0 +1,118 @@
+import { ComponentBase, Vector3, Quaternion } from '@orillusion/core';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { BodyType } from './RigidbodyEnum';
+import { ChildShape } from '../shape/CollisionShapeUtil';
+export type ContactCallback = (other: Rigidbody) => void;
+/**
+ * Rigidbody Component (Rapier backend).
+ *
+ * Public API mirrors `@orillusion/physics`'s `Rigidbody` where semantics line
+ * up. Rapier-only switches (`lockTranslations`, `enableCcd`) replace ammo's
+ * matrix-style `setLinearFactor / setCcdMotionThreshold + sweptSphereRadius`.
+ *
+ * @group Components
+ */
+export declare class Rigidbody extends ComponentBase {
+    private _initResolve;
+    private _initializationPromise;
+    private _bodyInited;
+    private _body;
+    private _colliders;
+    private _shapes;
+    private _bodyType;
+    private _mass;
+    private _restitution;
+    private _friction;
+    private _linearDamping;
+    private _angularDamping;
+    private _gravityScale;
+    private _ccd;
+    private _userIndex;
+    /**
+     * Whether this body is a sensor (no contact response, fires triggerEnter/Exit).
+     * Must be set BEFORE `start()`.
+     */
+    isSensor: boolean;
+    /**
+     * Whether contact / trigger events are emitted. Must be set BEFORE
+     * `start()`. Off by default for performance.
+     */
+    enableEvents: boolean;
+    /** Fires once when contact between two non-sensor bodies begins. */
+    onContactBegin?: ContactCallback;
+    /** Fires every frame while contact persists (after `onContactBegin`). */
+    onContactStay?: ContactCallback;
+    /** Fires once when contact ends. */
+    onContactEnd?: ContactCallback;
+    /** Fires once when a non-sensor body enters this sensor. */
+    onTriggerEnter?: ContactCallback;
+    /** Fires once when a non-sensor body leaves this sensor. */
+    onTriggerExit?: ContactCallback;
+    /** @internal */
+    _activeContacts: Set<Rigidbody>;
+    start(): void;
+    /**
+     * Pull body pose into the owner Object3D. Called by `Physics.update` AFTER
+     * `world.step` so the transform reflects the post-step pose in the SAME
+     * frame's render. Doing this in `onUpdate` (which runs BEFORE the render-
+     * loop callback) would render the pre-step pose and lag visuals one frame
+     * behind physics — visible during kinematic drag where the body chases
+     * mouse-set `setNextKinematicTranslation` targets every frame.
+     */
+    _syncTransformFromBody(force?: boolean): void;
+    onUpdate(): void;
+    destroy(force?: boolean): void;
+    /**
+     * @internal Swap in fresh body/collider wrappers after `Physics.restore()`
+     * rebuilds the world. Handles are preserved across snapshots, so the new
+     * wrappers describe the same logical entities — only their JS proxies
+     * needed refreshing.
+     */
+    _rebind(body: RAPIER.RigidBody, colliders: RAPIER.Collider[]): void;
+    /** @internal Detach this component from the physics world (used when restore drops the body). */
+    _detach(): void;
+    wait(): Promise<RAPIER.RigidBody>;
+    get bodyInited(): boolean;
+    /** Escape hatch to the native Rapier RigidBody. Opts out of cross-backend portability. */
+    get native(): RAPIER.RigidBody;
+    get colliders(): RAPIER.Collider[];
+    /**
+     * Collider descriptor used to build the body. Accepts a single shape, a
+     * compound (`ChildShape[]`) or a flat array of `ColliderDesc`.
+     * Set BEFORE `start()`.
+     */
+    get shape(): RAPIER.ColliderDesc | RAPIER.ColliderDesc[];
+    set shape(value: RAPIER.ColliderDesc | RAPIER.ColliderDesc[] | ChildShape[]);
+    get bodyType(): BodyType;
+    set bodyType(value: BodyType);
+    get mass(): number;
+    set mass(value: number);
+    get restitution(): number;
+    set restitution(value: number);
+    get friction(): number;
+    set friction(value: number);
+    get linearDamping(): number;
+    set linearDamping(value: number);
+    get angularDamping(): number;
+    set angularDamping(value: number);
+    get gravityScale(): number;
+    set gravityScale(value: number);
+    get userIndex(): number;
+    set userIndex(value: number);
+    get linearVelocity(): Vector3;
+    set linearVelocity(value: Vector3);
+    get angularVelocity(): Vector3;
+    set angularVelocity(value: Vector3);
+    /** Continuous Collision Detection. Replaces ammo's two-knob CCD API. */
+    enableCcd(value: boolean): void;
+    /** Lock translation axes. `true` locks the axis. (Rapier-only) */
+    lockTranslations(x: boolean, y: boolean, z: boolean): void;
+    /** Lock rotation axes. `true` locks the axis. (Rapier-only) */
+    lockRotations(x: boolean, y: boolean, z: boolean): void;
+    applyImpulse(impulse: Vector3, point?: Vector3): void;
+    applyTorqueImpulse(torque: Vector3): void;
+    applyForce(force: Vector3, point?: Vector3): void;
+    clearForcesAndVelocities(): void;
+    /** Force pose; mirrors ammo plugin's `Rigidbody.updateTransform`. */
+    updateTransform(position?: Vector3, rotation?: Vector3 | Quaternion, clearFV?: boolean): void;
+}

package/dist/rigidbody/RigidbodyEnum.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Rigid body kind. Mirrors Rapier's RigidBodyType but exposes a simpler enum.
+ */
+export declare enum BodyType {
+    /** Affected by forces and collisions. */
+    Dynamic = 0,
+    /** Immovable. Equivalent to ammo plugin's `mass = 0`. */
+    Static = 1,
+    /** Driven by user-set transform; velocity is auto-computed from delta. */
+    KinematicPosition = 2,
+    /** Driven by user-set velocity. */
+    KinematicVelocity = 3
+}

package/dist/shape/CollisionShapeUtil.d.ts

@@ -0,0 +1,95 @@
+import { Object3D, Vector3, Quaternion } from '@orillusion/core';
+import RAPIER from '@dimforge/rapier3d-compat';
+/**
+ * One child entry of a "compound" shape. Rapier has no monolithic compound
+ * primitive — every entry becomes its own collider attached to the same body
+ * with the given offset.
+ */
+export interface ChildShape {
+    shape: RAPIER.ColliderDesc;
+    position: Vector3;
+    rotation: Quaternion;
+}
+/**
+ * Collider descriptor factories.
+ *
+ * Public method names mirror `@orillusion/physics`'s `CollisionShapeUtil`
+ * one-to-one where semantics line up. Some return types deviate where
+ * Rapier and Bullet model things differently:
+ *
+ * - `createCompoundShape*` returns `ChildShape[]` (Rapier has no monolithic
+ *   compound primitive — multiple colliders attach to one body).
+ * - `createConvexHullShape` may return `null` if the points are degenerate
+ *   (Rapier surfaces this; ammo silently constructs an invalid hull).
+ */
+export declare class CollisionShapeUtil {
+    /**
+     * Box shape. Falls back to mesh-bounds size when `size` omitted.
+     */
+    static createBoxShape(object3D: Object3D, size?: Vector3): RAPIER.ColliderDesc;
+    /**
+     * Sphere shape. Falls back to mesh-bounds extents.x for radius.
+     */
+    static createSphereShape(object3D: Object3D, radius?: number): RAPIER.ColliderDesc;
+    /**
+     * Capsule shape. NOTE: Rapier's capsule takes `halfHeight` (the half
+     * length of the cylindrical mid-section, NOT including the caps). The
+     * ammo plugin's `createCapsuleShape(obj, radius, height)` uses the full
+     * mid-section height; pass `height / 2` here.
+     */
+    static createCapsuleShape(object3D: Object3D, radius?: number, halfHeight?: number): RAPIER.ColliderDesc;
+    /**
+     * Cylinder shape. NOTE: takes `halfHeight`, not full height.
+     */
+    static createCylinderShape(object3D: Object3D, radius?: number, halfHeight?: number): RAPIER.ColliderDesc;
+    /**
+     * Cone shape. NOTE: takes `halfHeight`, not full height.
+     */
+    static createConeShape(object3D: Object3D, radius?: number, halfHeight?: number): RAPIER.ColliderDesc;
+    /**
+     * Static plane stand-in. Rapier has no `staticPlane`; uses a wide thin
+     * cuboid so behavior matches the ammo plugin's typical floor pattern.
+     */
+    static createPlaneShape(extent?: number, thickness?: number): RAPIER.ColliderDesc;
+    /**
+     * Compound shape. Returns an array of child descriptors — pass to
+     * `Rigidbody.shape = [...]` and each entry becomes its own collider.
+     */
+    static createCompoundShape(childShapes: ChildShape[]): ChildShape[];
+    /**
+     * Build a compound from an Object3D's mesh hierarchy. Each child
+     * MeshRenderer contributes one collider, transformed into the parent's
+     * local space.
+     */
+    static createCompoundShapeFromObject(object3D: Object3D, includeParent?: boolean): ChildShape[];
+    /**
+     * Pick the best primitive shape for a single Object3D, falling back to
+     * `convexHull` for arbitrary meshes. Mirrors the ammo plugin's
+     * `createShapeFromObject`.
+     */
+    static createShapeFromObject(object3D: Object3D): RAPIER.ColliderDesc | null;
+    /**
+     * Convex-hull shape from raw vertices or an Object3D's mesh.
+     */
+    static createConvexHullShape(object3D: Object3D, modelVertices?: Float32Array): RAPIER.ColliderDesc | null;
+    /**
+     * Triangle-mesh shape from Object3D's mesh. Suitable for static geometry.
+     * For dynamic bodies prefer `createConvexHullShape` or compounds.
+     */
+    static createTrimeshShape(object3D: Object3D, modelVertices?: Float32Array, modelIndices?: Uint32Array): RAPIER.ColliderDesc;
+    /**
+     * Heightfield from a `PlaneGeometry`'s vertex Y values. Mirrors the ammo
+     * plugin's `createHeightfieldTerrainShape`.
+     */
+    static createHeightfieldShape(object3D: Object3D): RAPIER.ColliderDesc;
+    /**
+     * Get a flat (verts, indices) representation of an Object3D's meshes.
+     * Mirrors the ammo plugin's helper, but widens indices to `Uint32Array`
+     * (Rapier requires u32; engine geometry uses u16 typically).
+     */
+    static getAllMeshVerticesAndIndices(object3D: Object3D, isTransformChildren?: boolean): {
+        vertices: Float32Array<ArrayBufferLike>;
+        indices: Uint32Array<ArrayBufferLike>;
+    };
+    private static calculateLocalBoundingBox;
+}

package/dist/utils/PhysicsDragger.d.ts

@@ -0,0 +1,33 @@
+import { View3D } from '@orillusion/core';
+/**
+ * Mouse-driven rigid-body dragger.
+ *
+ * Mirrors `@orillusion/physics`'s `PhysicsDragger`. Implementation differs
+ * from the ammo version: rather than juggling collision flags, it switches
+ * the body to KinematicPositionBased while dragging, then restores the
+ * original type on release.
+ */
+export declare class PhysicsDragger {
+    private _view;
+    private _enable;
+    private _interactionDepth;
+    private _hitPoint;
+    private _offset;
+    private _isDragging;
+    private _draggedBody;
+    private _originalBodyType;
+    private _registered;
+    filterStatic: boolean;
+    constructor(view: View3D);
+    set enable(value: boolean);
+    get enable(): boolean;
+    private get _input();
+    private _registerEvents;
+    private _unregisterEvents;
+    private _onMouseDown;
+    private _onMouseMove;
+    private _onMouseUp;
+    private _onMouseWheel;
+    private _updateBody;
+    private _resetState;
+}

package/dist/utils/TempPhyMath.d.ts

@@ -0,0 +1,65 @@
+import { Vector3, Quaternion } from '@orillusion/core';
+/**
+ * Rapier Vec3 (POJO) — does not require destroy.
+ */
+export interface RVec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Rapier Quat (POJO) — does not require destroy.
+ */
+export interface RQuat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+/**
+ * Math conversion helpers between engine `Vector3 / Quaternion` and Rapier
+ * plain `{x, y, z, [w]}` objects. Provides reusable scratch objects.
+ *
+ * Unlike the ammo plugin's `TempPhyMath`, Rapier values are POJOs and do
+ * NOT need to be destroyed manually.
+ */
+export declare class TempPhyMath {
+    static readonly tmpVecA: RVec3;
+    static readonly tmpVecB: RVec3;
+    static readonly tmpVecC: RVec3;
+    static readonly tmpVecD: RVec3;
+    static readonly tmpQuaA: RQuat;
+    static readonly tmpQuaB: RQuat;
+    /**
+     * Vector3 → Rapier Vec3.
+     */
+    static toRVec(vec: Vector3, target?: RVec3): RVec3;
+    /**
+     * Quaternion → Rapier Quat.
+     */
+    static toRQuat(qua: Quaternion, target?: RQuat): RQuat;
+    /**
+     * Set Rapier Vec3 from raw scalars.
+     */
+    static setRVec(x: number, y: number, z: number, target?: RVec3): RVec3;
+    /**
+     * Set Rapier Quat from raw scalars.
+     */
+    static setRQuat(x: number, y: number, z: number, w: number, target?: RQuat): RQuat;
+    /**
+     * Rapier Vec3 → Vector3.
+     */
+    static fromRVec(rv: RVec3, vec?: Vector3): Vector3;
+    /**
+     * Rapier Quat → Quaternion.
+     */
+    static fromRQuat(rq: RQuat, qua?: Quaternion): Quaternion;
+    /**
+     * Sets the given Rapier Vec3 to (0, 0, 0).
+     */
+    static zeroRVec(target?: RVec3): RVec3;
+    /**
+     * Sets the given Rapier Quat to (0, 0, 0, 1).
+     */
+    static resetRQuat(target?: RQuat): RQuat;
+}

package/dist/vehicle/VehicleController.d.ts

@@ -0,0 +1,60 @@
+import { ComponentBase, Vector3 } from '@orillusion/core';
+import RAPIER from '@dimforge/rapier3d-compat';
+export interface WheelOptions {
+    /** Wheel attach point on chassis (chassis-local). */
+    chassisConnection: Vector3;
+    /** Suspension direction in chassis-local space. Typically -Y (down). */
+    suspensionDirection?: Vector3;
+    /** Wheel rolling axle direction in chassis-local space. Typically +X. */
+    axleDirection?: Vector3;
+    /** Resting suspension length. */
+    suspensionRestLength: number;
+    /** Wheel radius. */
+    radius: number;
+    /** Suspension stiffness coefficient. Default 30. */
+    stiffness?: number;
+    /** Damping when compressing the suspension. Default 0.83. */
+    dampingCompression?: number;
+    /** Damping when relaxing the suspension. Default 0.88. */
+    dampingRelaxation?: number;
+    /** Tire friction coefficient (longitudinal). Default 1000. */
+    frictionSlip?: number;
+    /** Side-slip friction stiffness. Default 1. */
+    sideFrictionStiffness?: number;
+}
+/**
+ * Vehicle controller — Rapier-only. Replaces the bare `btRaycastVehicle`
+ * usage in the ammo plugin's car sample.
+ *
+ * This component must be added to the same Object3D as a `Rigidbody`
+ * (the chassis); it auto-discovers the chassis body via `wait()`.
+ *
+ * @group Components
+ */
+export declare class VehicleController extends ComponentBase {
+    private _initResolve;
+    private _initializationPromise;
+    private _controller;
+    private _vehicleInited;
+    private _pendingWheels;
+    /** Up axis index (0=X, 1=Y, 2=Z). Default 1 (+Y). */
+    indexUpAxis: number;
+    /** Forward axis index (0=X, 1=Y, 2=Z). Default 2 (+Z). */
+    indexForwardAxis: number;
+    start(): Promise<void>;
+    destroy(force?: boolean): void;
+    private _preStep;
+    /** Append a wheel. Can be called pre- or post-start. */
+    addWheel(opts: WheelOptions): void;
+    private _addWheelInternal;
+    setEngineForce(force: number, wheelIdx: number): void;
+    setBrake(brake: number, wheelIdx: number): void;
+    setSteering(angle: number, wheelIdx: number): void;
+    numWheels(): number;
+    wheelInContact(i: number): boolean;
+    wheelChassisConnectionPoint(i: number): Vector3 | null;
+    /** Current vehicle speed in km/h. Mirrors ammo's `getCurrentSpeedKmHour`. */
+    currentSpeedKmHour(): number;
+    wait(): Promise<void>;
+    get native(): RAPIER.DynamicRayCastVehicleController;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@orillusion/physics-rapier",
+    "version": "0.1.0",
+    "author": "Orillusion",
+    "description": "Orillusion Physics Plugin, Powered by Rapier (Rust → WASM).",
+    "main": "./dist/physics-rapier.umd.js",
+    "module": "./dist/physics-rapier.es.js",
+    "module:dev": "./index.ts",
+    "types": "./dist/index.d.ts",
+    "files": ["dist"],
+    "scripts": {
+        "build": "vite build && npm run build:types && npm run build:clean",
+        "build:types": "tsc --emitDeclarationOnly --experimentalDecorators -p tsconfig.json",
+        "build:clean": "mv dist/packages/physics-rapier/* dist && rm -rf dist/src && rm -rf dist/packages",
+        "docs": "npm run docs:typedoc ../../docs/physics-rapier index.ts",
+        "docs:typedoc": "npx typedoc --plugin typedoc-plugin-markdown --tsconfig tsconfig.json --gitRevision main --hideBreadcrumbs --router member --readme none --excludeInternal --excludePrivate --excludeProtected --excludeExternals --sort source-order --out"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Orillusion/orillusion.git"
+    },
+    "dependencies": {
+        "@dimforge/rapier3d-compat": "^0.14.0"
+    },
+    "peerDependencies": {
+        "@orillusion/core": ">=0.9.0"
+    }
+}