@scenoco-three/rapier 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SceNoCo contributors
+
+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,32 @@
+# @scenoco-three/rapier
+
+Optional [Rapier](https://rapier.rs) physics for [SceNoCo](https://github.com/): a
+`<Physics>` scene setting plus `<RigidBody>` / `<Collider>` components, built entirely on the
+public `System` seam in `@scenoco-three/core`. Import it to get physics; don't, and no
+physics (or Rapier WASM) ships.
+
+```ts
+import { initRapier } from '@scenoco-three/rapier'; // registers the tags + system
+await initRapier();        // load the WASM once, before loadScene
+engine.loadScene(bundle);  // a scene that declares <Physics>/<RigidBody>/<Collider>
+```
+
+```xml
+<Scene>
+  <Physics gravity="0 -9.81 0" />
+  <Mesh position="0 5 0"><BoxGeometry /><MeshStandardMaterial />
+    <Components><RigidBody /><Collider /></Components>
+  </Mesh>
+</Scene>
+```
+
+This package is the reference example that the framework's add-on seams work: a
+`@system(RigidBody)` reconciles a Rapier world from the live component set, with
+`@dimforge/rapier3d-compat` isolated here and core staying physics-free.
+
+`three` is a peer dependency. See the [repository](../../README.md) and
+[docs/physics-plan.md](../../docs/physics-plan.md).
+
+## License
+
+[MIT](./LICENSE)

package/dist/Collider.d.ts

@@ -0,0 +1,22 @@
+import RAPIER from '@dimforge/rapier3d-compat';
+import { Component } from '@scenoco-three/core';
+/**
+ * A collision shape on the node. The `PhysicsSystem` attaches it to the node's
+ * `<RigidBody>` when it builds that body (no manual registration). `shape="auto"`
+ * reads the host mesh's geometry parameters — a `<Mesh><SphereGeometry radius=
+ * "0.5"/></Mesh>` gets a 0.5 ball for free.
+ */
+export declare class Collider extends Component {
+    shape: string;
+    halfExtents: number[];
+    radius: number;
+    halfHeight: number;
+    restitution: number;
+    friction: number;
+    density: number;
+    /** @internal Build the Rapier collider descriptor with material properties. */
+    toDesc(): RAPIER.ColliderDesc;
+    private shapeDesc;
+    /** Derive a collider from the host mesh's geometry parameters. */
+    private autoDesc;
+}

package/dist/Collider.js

@@ -0,0 +1,88 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import RAPIER from '@dimforge/rapier3d-compat';
+import { Component, component, property } from '@scenoco-three/core';
+/**
+ * A collision shape on the node. The `PhysicsSystem` attaches it to the node's
+ * `<RigidBody>` when it builds that body (no manual registration). `shape="auto"`
+ * reads the host mesh's geometry parameters — a `<Mesh><SphereGeometry radius=
+ * "0.5"/></Mesh>` gets a 0.5 ball for free.
+ */
+let Collider = class Collider extends Component {
+    shape = 'auto';
+    halfExtents = [0.5, 0.5, 0.5];
+    radius = 0.5;
+    halfHeight = 0.5;
+    restitution = 0;
+    friction = 0.5;
+    density = 1;
+    /** @internal Build the Rapier collider descriptor with material properties. */
+    toDesc() {
+        return this.shapeDesc()
+            .setRestitution(this.restitution)
+            .setFriction(this.friction)
+            .setDensity(this.density);
+    }
+    shapeDesc() {
+        const [hx, hy, hz] = this.halfExtents;
+        switch (this.shape) {
+            case 'box':
+                return RAPIER.ColliderDesc.cuboid(hx, hy, hz);
+            case 'sphere':
+                return RAPIER.ColliderDesc.ball(this.radius);
+            case 'capsule':
+                return RAPIER.ColliderDesc.capsule(this.halfHeight, this.radius);
+            case 'cylinder':
+                return RAPIER.ColliderDesc.cylinder(this.halfHeight, this.radius);
+            default:
+                return this.autoDesc();
+        }
+    }
+    /** Derive a collider from the host mesh's geometry parameters. */
+    autoDesc() {
+        const geom = this.node.geometry;
+        const p = geom?.parameters;
+        if (geom && p) {
+            switch (geom.type) {
+                case 'BoxGeometry':
+                    return RAPIER.ColliderDesc.cuboid((p.width ?? 1) / 2, (p.height ?? 1) / 2, (p.depth ?? 1) / 2);
+                case 'SphereGeometry':
+                    return RAPIER.ColliderDesc.ball(p.radius ?? 0.5);
+                case 'CylinderGeometry':
+                    return RAPIER.ColliderDesc.cylinder((p.height ?? 1) / 2, p.radiusTop ?? p.radius ?? 0.5);
+                case 'PlaneGeometry':
+                    return RAPIER.ColliderDesc.cuboid((p.width ?? 1) / 2, (p.height ?? 1) / 2, 0.01);
+            }
+        }
+        return RAPIER.ColliderDesc.cuboid(0.5, 0.5, 0.5); // fallback: unit box
+    }
+};
+__decorate([
+    property({ type: 'string', default: 'auto', description: 'auto | box | sphere | capsule | cylinder' })
+], Collider.prototype, "shape", void 0);
+__decorate([
+    property({ type: 'vec3', default: [0.5, 0.5, 0.5], description: 'Box half-extents (shape="box")' })
+], Collider.prototype, "halfExtents", void 0);
+__decorate([
+    property({ type: 'float', default: 0.5, description: 'Radius (sphere/capsule/cylinder)' })
+], Collider.prototype, "radius", void 0);
+__decorate([
+    property({ type: 'float', default: 0.5, description: 'Half-height (capsule/cylinder)' })
+], Collider.prototype, "halfHeight", void 0);
+__decorate([
+    property({ type: 'float', default: 0, description: 'Bounciness 0..1' })
+], Collider.prototype, "restitution", void 0);
+__decorate([
+    property({ type: 'float', default: 0.5 })
+], Collider.prototype, "friction", void 0);
+__decorate([
+    property({ type: 'float', default: 1 })
+], Collider.prototype, "density", void 0);
+Collider = __decorate([
+    component({ name: 'Collider', description: 'A Rapier collision shape; the PhysicsSystem attaches it to the node’s RigidBody' })
+], Collider);
+export { Collider };

package/dist/Physics.d.ts

@@ -0,0 +1,11 @@
+import { Attachment } from '@scenoco-three/core';
+/**
+ * Scene-level physics config: `<Physics gravity="0 -9.81 0" />` inside `<Scene>`.
+ * It's a pure config attachment — the `PhysicsSystem` (auto-run while the scene
+ * has rigid bodies) reads its `gravity` via `engine.findAttachment(Physics)`.
+ * Requires `await initRapier()` before `engine.loadScene()`.
+ */
+export declare class Physics extends Attachment {
+    gravity: number[];
+    attach(): void;
+}

package/dist/Physics.js

@@ -0,0 +1,25 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Attachment, attachment, property } from '@scenoco-three/core';
+/**
+ * Scene-level physics config: `<Physics gravity="0 -9.81 0" />` inside `<Scene>`.
+ * It's a pure config attachment — the `PhysicsSystem` (auto-run while the scene
+ * has rigid bodies) reads its `gravity` via `engine.findAttachment(Physics)`.
+ * Requires `await initRapier()` before `engine.loadScene()`.
+ */
+let Physics = class Physics extends Attachment {
+    gravity = [0, -9.81, 0];
+    // Config only: the value is read by PhysicsSystem.onAttach; nothing to apply.
+    attach() { }
+};
+__decorate([
+    property({ type: 'vec3', default: [0, -9.81, 0], description: 'Gravity vector' })
+], Physics.prototype, "gravity", void 0);
+Physics = __decorate([
+    attachment({ name: 'Physics', target: 'Scene', group: 'physics', description: 'Scene physics config (gravity)' })
+], Physics);
+export { Physics };

package/dist/PhysicsSystem.d.ts

@@ -0,0 +1,25 @@
+import RAPIER from '@dimforge/rapier3d-compat';
+import { System } from '@scenoco-three/core';
+import { RigidBody } from './RigidBody.js';
+/**
+ * ECS-hybrid physics: registered for `RigidBody`, the engine auto-runs it while
+ * the scene contains rigid bodies and keeps `this.components` in sync. Each fixed
+ * step it reconciles the Rapier world with the live component set (creating a
+ * body for each new `RigidBody`, removing one whose component left), steps the
+ * world, then writes every body's pose back to its `Object3D`. Gravity comes from
+ * the `<Physics>` config attachment, read on attach.
+ *
+ * Requires `await initRapier()` before `loadScene`.
+ */
+export declare class PhysicsSystem extends System<RigidBody> {
+    world?: RAPIER.World;
+    private readonly bodies;
+    private readonly v;
+    private readonly q;
+    onAttach(): void;
+    fixedStep(dt: number): void;
+    onDetach(): void;
+    /** The live Rapier body for a RigidBody, once built (for RigidBody.applyImpulse, etc.). */
+    bodyFor(rb: RigidBody): RAPIER.RigidBody | undefined;
+    private createBody;
+}

package/dist/PhysicsSystem.js

@@ -0,0 +1,100 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import RAPIER from '@dimforge/rapier3d-compat';
+import { Quaternion, Vector3 } from 'three';
+import { System, system } from '@scenoco-three/core';
+import { RigidBody } from './RigidBody.js';
+import { Collider } from './Collider.js';
+import { Physics } from './Physics.js';
+/**
+ * ECS-hybrid physics: registered for `RigidBody`, the engine auto-runs it while
+ * the scene contains rigid bodies and keeps `this.components` in sync. Each fixed
+ * step it reconciles the Rapier world with the live component set (creating a
+ * body for each new `RigidBody`, removing one whose component left), steps the
+ * world, then writes every body's pose back to its `Object3D`. Gravity comes from
+ * the `<Physics>` config attachment, read on attach.
+ *
+ * Requires `await initRapier()` before `loadScene`.
+ */
+let PhysicsSystem = class PhysicsSystem extends System {
+    world;
+    bodies = new Map();
+    v = new Vector3();
+    q = new Quaternion();
+    onAttach() {
+        if (typeof RAPIER.World !== 'function') {
+            throw new Error('Rapier is not initialized — call `await initRapier()` before loadScene().');
+        }
+        const g = this.engine.findAttachment(Physics)?.gravity ?? [0, -9.81, 0];
+        this.world = new RAPIER.World({ x: g[0] ?? 0, y: g[1] ?? -9.81, z: g[2] ?? 0 });
+    }
+    fixedStep(dt) {
+        const world = this.world;
+        if (!world)
+            return;
+        // Reconcile bodies ↔ live components: create for new, remove for gone.
+        for (const rb of this.components)
+            if (!this.bodies.has(rb))
+                this.createBody(world, rb);
+        for (const [rb, body] of this.bodies) {
+            if (!this.components.includes(rb)) {
+                world.removeRigidBody(body);
+                this.bodies.delete(rb);
+                rb.body = undefined;
+            }
+        }
+        world.timestep = dt;
+        world.step();
+        // World → scene graph.
+        for (const [rb, body] of this.bodies) {
+            const t = body.translation();
+            const r = body.rotation();
+            rb.node.position.set(t.x, t.y, t.z);
+            rb.node.quaternion.set(r.x, r.y, r.z, r.w);
+        }
+    }
+    onDetach() {
+        for (const rb of this.bodies.keys())
+            rb.body = undefined;
+        this.world?.free();
+        this.world = undefined;
+        this.bodies.clear();
+    }
+    /** The live Rapier body for a RigidBody, once built (for RigidBody.applyImpulse, etc.). */
+    bodyFor(rb) {
+        return this.bodies.get(rb);
+    }
+    createBody(world, rb) {
+        rb.node.getWorldPosition(this.v);
+        rb.node.getWorldQuaternion(this.q);
+        const desc = descForKind(rb.kind)
+            .setTranslation(this.v.x, this.v.y, this.v.z)
+            .setRotation({ x: this.q.x, y: this.q.y, z: this.q.z, w: this.q.w })
+            .setLinearDamping(rb.linearDamping)
+            .setAngularDamping(rb.angularDamping)
+            .setGravityScale(rb.gravityScale);
+        const body = world.createRigidBody(desc);
+        this.bodies.set(rb, body);
+        rb.body = body;
+        // Attach the colliders declared on the same node.
+        for (const c of rb.engine.getComponents(rb.node)) {
+            if (c instanceof Collider)
+                world.createCollider(c.toDesc(), body);
+        }
+    }
+};
+PhysicsSystem = __decorate([
+    system(RigidBody)
+], PhysicsSystem);
+export { PhysicsSystem };
+function descForKind(kind) {
+    if (kind === 'fixed')
+        return RAPIER.RigidBodyDesc.fixed();
+    if (kind === 'kinematic')
+        return RAPIER.RigidBodyDesc.kinematicPositionBased();
+    return RAPIER.RigidBodyDesc.dynamic();
+}

package/dist/RigidBody.d.ts

@@ -0,0 +1,20 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import { Component } from '@scenoco-three/core';
+/**
+ * Marks the host node as a Rapier rigid body — plain data the `PhysicsSystem`
+ * reconciles into the world (no manual registration). Pair it with one or more
+ * `<Collider>` on the same node to give it shape. The system stamps the live
+ * `body` onto this component once it's built.
+ */
+export declare class RigidBody extends Component {
+    kind: string;
+    linearDamping: number;
+    angularDamping: number;
+    gravityScale: number;
+    /** The live Rapier body, set by the PhysicsSystem after it builds it. */
+    body?: RAPIER.RigidBody;
+    /** Apply an instantaneous impulse (world space), waking the body. */
+    applyImpulse(x: number, y: number, z: number): void;
+    /** Set the linear velocity (world space), waking the body. */
+    setLinvel(x: number, y: number, z: number): void;
+}

package/dist/RigidBody.js

@@ -0,0 +1,45 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Component, component, property } from '@scenoco-three/core';
+/**
+ * Marks the host node as a Rapier rigid body — plain data the `PhysicsSystem`
+ * reconciles into the world (no manual registration). Pair it with one or more
+ * `<Collider>` on the same node to give it shape. The system stamps the live
+ * `body` onto this component once it's built.
+ */
+let RigidBody = class RigidBody extends Component {
+    kind = 'dynamic';
+    linearDamping = 0;
+    angularDamping = 0;
+    gravityScale = 1;
+    /** The live Rapier body, set by the PhysicsSystem after it builds it. */
+    body;
+    /** Apply an instantaneous impulse (world space), waking the body. */
+    applyImpulse(x, y, z) {
+        this.body?.applyImpulse({ x, y, z }, true);
+    }
+    /** Set the linear velocity (world space), waking the body. */
+    setLinvel(x, y, z) {
+        this.body?.setLinvel({ x, y, z }, true);
+    }
+};
+__decorate([
+    property({ type: 'string', default: 'dynamic', description: 'dynamic | fixed | kinematic' })
+], RigidBody.prototype, "kind", void 0);
+__decorate([
+    property({ type: 'float', default: 0 })
+], RigidBody.prototype, "linearDamping", void 0);
+__decorate([
+    property({ type: 'float', default: 0 })
+], RigidBody.prototype, "angularDamping", void 0);
+__decorate([
+    property({ type: 'float', default: 1, description: 'Multiplier on world gravity for this body' })
+], RigidBody.prototype, "gravityScale", void 0);
+RigidBody = __decorate([
+    component({ name: 'RigidBody', description: 'A physics body driven by the Rapier world (needs a <Physics> scene)' })
+], RigidBody);
+export { RigidBody };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { PhysicsSystem } from './PhysicsSystem.js';
+export { RigidBody } from './RigidBody.js';
+export { Collider } from './Collider.js';
+export { Physics } from './Physics.js';
+/**
+ * The XML tags this package registers — read by the compiler/Vite plugin
+ * (`registerPackages`) so a scene that uses them validates and imports the
+ * package. The convention for any SceNoCo tag package.
+ */
+export declare const sceneTags: readonly ["RigidBody", "Collider", "Physics"];
+/**
+ * Load the Rapier WASM once. Await it before `engine.loadScene()` of any scene
+ * that uses `<Physics>` (a `World` cannot be built until the WASM is ready).
+ * Idempotent — repeated calls share one initialization.
+ */
+export declare function initRapier(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,27 @@
+// `@scenoco-three/rapier` — Rapier physics for SceNoCo, built entirely on the
+// public seams: a `PhysicsSystem extends System`, `@component` `RigidBody`/
+// `Collider`, and a `<Physics>` `@setting`. Core has no physics dependency; an
+// app that doesn't import this package ships no physics (and no Rapier WASM).
+//
+// Importing this module registers the `RigidBody`, `Collider`, and `Physics`
+// tags (decorator side effects) — that's why the package is marked `sideEffects`.
+import RAPIER from '@dimforge/rapier3d-compat';
+export { PhysicsSystem } from './PhysicsSystem.js';
+export { RigidBody } from './RigidBody.js';
+export { Collider } from './Collider.js';
+export { Physics } from './Physics.js';
+/**
+ * The XML tags this package registers — read by the compiler/Vite plugin
+ * (`registerPackages`) so a scene that uses them validates and imports the
+ * package. The convention for any SceNoCo tag package.
+ */
+export const sceneTags = ['RigidBody', 'Collider', 'Physics'];
+let initPromise;
+/**
+ * Load the Rapier WASM once. Await it before `engine.loadScene()` of any scene
+ * that uses `<Physics>` (a `World` cannot be built until the WASM is ready).
+ * Idempotent — repeated calls share one initialization.
+ */
+export function initRapier() {
+    return (initPromise ??= RAPIER.init());
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@scenoco-three/rapier",
+  "version": "0.1.0",
+  "description": "Rapier physics for SceNoCo: <Physics> setting + RigidBody/Collider components on the EngineSystem seam",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": ["three", "threejs", "physics", "rapier", "scene", "components", "gamedev"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "//sideEffects": "Importing the package registers its @component/@setting tags (decorator side effects), so it must not be tree-shaken away when imported for registration.",
+  "sideEffects": true,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "npm --prefix ../core run build && tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@scenoco-three/core": "^0.1.0",
+    "@dimforge/rapier3d-compat": "^0.19.0"
+  },
+  "peerDependencies": {
+    "three": ">=0.160.0"
+  }
+}