@adobe/data-gpu 0.9.69

package/dist/physics/physics-clock-plugin.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Fixed-timestep physics clock — decouples the simulation rate from the render
+ * rate (Fiedler "fix your timestep"). Each render frame the accumulator absorbs
+ * the variable `frameTime.dt`; the solver then runs a whole number of fixed
+ * `fixedDt` steps (0, 1, or several), and `alpha` is the leftover fraction used
+ * to interpolate the rendered pose between the last two simulated states.
+ *
+ * Default 60 Hz; set another rate at init with `setFixedTimestep(hz)`.
+ */
+export interface PhysicsClock {
+    /** Fixed simulation step length, seconds (default 1/60). */
+    readonly fixedDt: number;
+    /** Unsimulated time carried to the next frame, seconds (< fixedDt). */
+    readonly accumulator: number;
+    /** accumulator / fixedDt ∈ [0,1): render interpolation fraction prev→current. */
+    readonly alpha: number;
+    /** Whole steps the solver should run this frame (0..maxSubSteps). */
+    readonly steps: number;
+    /** Cap on steps/frame — prevents the "spiral of death" after a long stall. */
+    readonly maxSubSteps: number;
+}
+/**
+ * Provides the `physicsClock` resource and advances it once per render frame.
+ * Solver plugins extend this and run `physicsClock.steps` fixed steps; the
+ * interpolation system reads `physicsClock.alpha`. The advance runs first in the
+ * `physics` phase so solvers (scheduled `after: ["advancePhysicsClock"]`) see it.
+ */
+export declare const physicsClock: {
+    readonly components: {};
+    readonly resources: {
+        readonly frameTime: {
+            readonly default: import("../core/frame-time/public.js");
+            readonly transient: true;
+        };
+    } & {
+        readonly schedulerState: {
+            readonly default: import("@adobe/data/ecs").SchedulerState;
+        };
+    } & {
+        readonly device: {
+            readonly default: GPUDevice | null;
+            readonly transient: true;
+        };
+        readonly commandEncoder: {
+            readonly default: GPUCommandEncoder | null;
+            readonly transient: true;
+        };
+    } & {
+        readonly physicsClock: {
+            readonly default: PhysicsClock;
+            readonly transient: true;
+        };
+    };
+    readonly archetypes: {};
+    readonly transactions: {} & {} & {
+        readonly setFixedTimestep: (t: import("@adobe/data/ecs").TransactionContext<import("@adobe/data/schema").FromSchemas<{}>, import("@adobe/data/schema").FromSchemas<{
+            readonly physicsClock: {
+                readonly default: PhysicsClock;
+                readonly transient: true;
+            };
+        } & {
+            readonly frameTime: {
+                readonly default: import("../core/frame-time/public.js");
+                readonly transient: true;
+            };
+        } & {
+            readonly schedulerState: {
+                readonly default: import("@adobe/data/ecs").SchedulerState;
+            };
+        } & {
+            readonly device: {
+                readonly default: GPUDevice | null;
+                readonly transient: true;
+            };
+            readonly commandEncoder: {
+                readonly default: GPUCommandEncoder | null;
+                readonly transient: true;
+            };
+        }>, {}, {}>, hz: number) => void;
+    };
+    readonly systems: import("@adobe/data/ecs").SystemDeclarations<"update" | "_frameTime" | "schedulerSystem" | "input" | "preUpdate" | "postUpdate" | "physics" | "preRender" | "render" | "postRender" | "advancePhysicsClock">;
+    readonly actions: {};
+    readonly services: {};
+    readonly computed: {};
+    readonly indexes: {};
+};

package/dist/physics/physics-clock-plugin.js

@@ -0,0 +1,37 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { core } from "../core/core-plugin.js";
+const DEFAULT = { fixedDt: 1 / 60, accumulator: 0, alpha: 0, steps: 0, maxSubSteps: 8 };
+/**
+ * Provides the `physicsClock` resource and advances it once per render frame.
+ * Solver plugins extend this and run `physicsClock.steps` fixed steps; the
+ * interpolation system reads `physicsClock.alpha`. The advance runs first in the
+ * `physics` phase so solvers (scheduled `after: ["advancePhysicsClock"]`) see it.
+ */
+export const physicsClock = Database.Plugin.create({
+    extends: core,
+    resources: {
+        physicsClock: { default: DEFAULT, transient: true },
+    },
+    transactions: {
+        /** Set the simulation rate (Hz). Call once at init; default is 60. */
+        setFixedTimestep(t, hz) {
+            t.resources.physicsClock = { ...t.resources.physicsClock, fixedDt: 1 / hz };
+        },
+    },
+    systems: {
+        advancePhysicsClock: {
+            schedule: { during: ["physics"] },
+            create: db => () => {
+                const c = db.store.resources.physicsClock;
+                const h = c.fixedDt;
+                // clamp the absorbed time to the step budget so a long stall (tab
+                // backgrounded, GC) can't queue hundreds of steps (spiral of death)
+                const acc = c.accumulator + Math.min(db.store.resources.frameTime.dt, h * c.maxSubSteps);
+                const steps = Math.min(Math.floor(acc / h), c.maxSubSteps);
+                db.store.resources.physicsClock = { ...c, accumulator: acc - steps * h, alpha: (acc - steps * h) / h, steps };
+            },
+        },
+    },
+});
+//# sourceMappingURL=physics-clock-plugin.js.map

package/dist/physics/physics-clock-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-clock-plugin.js","sourceRoot":"","sources":["../../src/physics/physics-clock-plugin.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAwB9C,MAAM,OAAO,GAAiB,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAEtG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IAC/C,OAAO,EAAE,IAAI;IACb,SAAS,EAAE;QACP,YAAY,EAAE,EAAE,OAAO,EAAE,OAAuB,EAAE,SAAS,EAAE,IAAI,EAAE;KACtE;IACD,YAAY,EAAE;QACV,sEAAsE;QACtE,gBAAgB,CAAC,CAAC,EAAE,EAAU;YAC1B,CAAC,CAAC,SAAS,CAAC,YAAY,GAAG,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,YAAY,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;QAChF,CAAC;KACJ;IACD,OAAO,EAAE;QACL,mBAAmB,EAAE;YACjB,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE;YACjC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE;gBACf,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,YAAY,CAAC;gBAC1C,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;gBACpB,kEAAkE;gBAClE,oEAAoE;gBACpE,MAAM,GAAG,GAAG,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;gBACzF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;gBAC3D,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,YAAY,GAAG,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,GAAG,GAAG,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;YAClH,CAAC;SACJ;KACJ;CACJ,CAAC,CAAC"}

package/dist/physics/physics-clock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/physics/physics-clock.test.js

@@ -0,0 +1,45 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect } from "vitest";
+import { Database } from "@adobe/data/ecs";
+import { physicsClock } from "./physics-clock-plugin.js";
+/** The accumulator turns a variable render dt into a whole number of fixed steps
+ *  plus a leftover interpolation `alpha`, capped against the spiral of death. */
+describe("physicsClock", () => {
+    const make = () => {
+        const db = Database.create(physicsClock); // 60 Hz default
+        const store = db.store;
+        const advance = (dt) => {
+            store.resources.frameTime = { now: 0, dt, elapsed: 0 };
+            db.system.functions.advancePhysicsClock?.();
+            return store.resources.physicsClock;
+        };
+        return { db, advance };
+    };
+    it("matched render rate → exactly one step per frame, alpha ≈ 0", () => {
+        const c = make().advance(1 / 60);
+        expect(c.steps).toBe(1);
+        expect(c.alpha).toBeCloseTo(0);
+    });
+    it("render slower than sim → multiple steps per frame", () => {
+        expect(make().advance(1 / 30).steps).toBe(2); // two 1/60 steps fit one 1/30 frame
+    });
+    it("render faster than sim → 0-step frames that accumulate, alpha rising then resetting", () => {
+        const { advance } = make();
+        const a = advance(1 / 120); // half a step accrued
+        expect(a.steps).toBe(0);
+        expect(a.alpha).toBeCloseTo(0.5);
+        const b = advance(1 / 120); // now a full step is due
+        expect(b.steps).toBe(1);
+        expect(b.alpha).toBeCloseTo(0);
+    });
+    it("a long stall is capped at maxSubSteps (no spiral of death)", () => {
+        const c = make().advance(10); // 600 steps' worth of time
+        expect(c.steps).toBe(c.maxSubSteps);
+    });
+    it("setFixedTimestep changes the rate", () => {
+        const { db, advance } = make();
+        db.transactions.setFixedTimestep(30);
+        expect(advance(1 / 30).steps).toBe(1); // one 1/30 step per 1/30 frame
+    });
+});
+//# sourceMappingURL=physics-clock.test.js.map

package/dist/physics/physics-clock.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-clock.test.js","sourceRoot":"","sources":["../../src/physics/physics-clock.test.ts"],"names":[],"mappings":"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"}

package/dist/physics/physics-data-plugin.d.ts

@@ -0,0 +1,348 @@
+import type { ColliderMesh } from "./body/collider-mesh.js";
+/**
+ * The shared, solver-agnostic rigid-body data model — the seam every physics
+ * solver plugs into. It declares *only* authored/canonical state (no systems):
+ *
+ *   bodyType, colliderShape, halfExtents, material  — authored shape + role
+ *   position, rotation, linearVelocity, angularVelocity — canonical live state
+ *
+ * A **solver plugin** `extends` this, may keep its own private `_`-prefixed
+ * internal state (broadphase, caches, GPU buffers), and each frame reads the
+ * authored state and writes back `position`/`rotation`/velocity for dynamic
+ * bodies. A renderer reads the canonical transforms, decoupled from which
+ * solver produced them — so solvers (`joltSolver`, `rapierSolver`; the GPU XPBD
+ * solver is shelved) are interchangeable over identical authored scenes.
+ *
+ * Two archetypes share these components:
+ *   - **RigidBody** — `dynamic` or `kinematic` bodies that move; carries
+ *     velocities and a `bodyType` discriminator.
+ *   - **StaticCollider** — immovable colliders (floor, wall, ramp, scenery).
+ *     No velocities (never integrated) and no `bodyType` (the archetype *is*
+ *     the static classification) — a lean row for the bulk-static workload.
+ *
+ * `_prevPosition`/`_prevRotation` are derived (`_`-prefixed): the solver snapshots
+ * the pose *before* its final fixed step into them, so a render-rate interpolation
+ * pass can smoothly blend the previous → current simulated pose (see
+ * `physics-clock-plugin` + `interpolation-plugin`). Like `_worldMatrix`, they are
+ * *not* in the authored archetype — the solver migrates them onto each dynamic
+ * body the first time it mirrors it, so authors never supply derived state.
+ *
+ * Mass + inertia are derived per solver from shape + material (not stored here).
+ */
+export declare const physicsData: {
+    readonly components: {
+        readonly material: {
+            readonly type: "integer";
+            readonly minimum: -2147483648;
+            readonly maximum: 2147483647;
+            readonly default: number;
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly density: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly restitution: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly friction: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly compliance: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly heatCapacity: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly baseColorFactor: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 4;
+            readonly maxItems: 4;
+            readonly default: readonly [0, 0, 0, 0];
+        };
+        readonly emissiveFactor: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly metallicFactor: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly roughnessFactor: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly normalScale: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly occlusionStrength: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly baseColorUrl: {
+            readonly type: "string";
+        };
+        readonly metallicRoughnessUrl: {
+            readonly type: "string";
+        };
+        readonly normalUrl: {
+            readonly type: "string";
+        };
+        readonly occlusionUrl: {
+            readonly type: "string";
+        };
+        readonly emissiveUrl: {
+            readonly type: "string";
+        };
+    } & {
+        readonly bodyType: {
+            readonly type: "string";
+            readonly enum: readonly ["static", "dynamic", "kinematic"];
+        };
+        readonly colliderShape: {
+            readonly type: "string";
+            readonly enum: readonly ["sphere", "box", "capsule", "hull", "mesh"];
+        };
+        readonly halfExtents: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly position: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly rotation: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 4;
+            readonly maxItems: 4;
+            readonly default: readonly [0, 0, 0, 1];
+            readonly interpolators: {
+                readonly linear: (q1: any, q2: any, t: number) => any;
+            };
+        };
+        readonly linearVelocity: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly angularVelocity: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly _prevPosition: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly _prevRotation: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly minItems: 4;
+            readonly maxItems: 4;
+            readonly default: readonly [0, 0, 0, 1];
+            readonly interpolators: {
+                readonly linear: (q1: any, q2: any, t: number) => any;
+            };
+        };
+        readonly collisionGroup: {
+            readonly type: "number";
+            readonly precision: 1;
+            readonly default: number;
+        };
+        readonly convexPoints: {
+            readonly default: Float32Array | null;
+        };
+        readonly colliderMesh: {
+            readonly default: ColliderMesh | null;
+        };
+    };
+    readonly resources: {
+        readonly materials: {
+            readonly default: Record<string, number>;
+        };
+    } & {};
+    readonly archetypes: {
+        readonly Material: readonly ["name", "density", "restitution", "friction", "compliance", "heatCapacity", "baseColorFactor", "emissiveFactor", "metallicFactor", "roughnessFactor", "normalScale", "occlusionStrength", "baseColorUrl", "metallicRoughnessUrl", "normalUrl", "occlusionUrl", "emissiveUrl"];
+    } & {
+        readonly RigidBody: readonly ["bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity"];
+        readonly StaticCollider: readonly ["colliderShape", "halfExtents", "material", "position", "rotation"];
+        readonly ConvexBody: readonly ["bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity", "convexPoints"];
+        readonly MeshCollider: readonly ["colliderShape", "halfExtents", "material", "position", "rotation", "colliderMesh"];
+    };
+    readonly transactions: {
+        readonly seedStandardMaterials: (t: import("@adobe/data/ecs").TransactionContext<import("@adobe/data/schema").FromSchemas<{
+            readonly material: {
+                readonly type: "integer";
+                readonly minimum: -2147483648;
+                readonly maximum: 2147483647;
+                readonly default: number;
+            };
+            readonly name: {
+                readonly type: "string";
+            };
+            readonly density: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly restitution: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly friction: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly compliance: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly heatCapacity: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly baseColorFactor: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "number";
+                    readonly precision: 1;
+                    readonly default: number;
+                };
+                readonly minItems: 4;
+                readonly maxItems: 4;
+                readonly default: readonly [0, 0, 0, 0];
+            };
+            readonly emissiveFactor: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "number";
+                    readonly precision: 1;
+                    readonly default: number;
+                };
+                readonly minItems: 3;
+                readonly maxItems: 3;
+                readonly default: readonly [0, 0, 0];
+            };
+            readonly metallicFactor: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly roughnessFactor: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly normalScale: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly occlusionStrength: {
+                readonly type: "number";
+                readonly precision: 1;
+                readonly default: number;
+            };
+            readonly baseColorUrl: {
+                readonly type: "string";
+            };
+            readonly metallicRoughnessUrl: {
+                readonly type: "string";
+            };
+            readonly normalUrl: {
+                readonly type: "string";
+            };
+            readonly occlusionUrl: {
+                readonly type: "string";
+            };
+            readonly emissiveUrl: {
+                readonly type: "string";
+            };
+        }>, import("@adobe/data/schema").FromSchemas<{
+            readonly materials: {
+                readonly default: Record<string, number>;
+            };
+        }>, {
+            readonly Material: readonly ["name", "density", "restitution", "friction", "compliance", "heatCapacity", "baseColorFactor", "emissiveFactor", "metallicFactor", "roughnessFactor", "normalScale", "occlusionStrength", "baseColorUrl", "metallicRoughnessUrl", "normalUrl", "occlusionUrl", "emissiveUrl"];
+        }, {}>) => void;
+    } & {};
+    readonly systems: import("@adobe/data/ecs").SystemDeclarations<never>;
+    readonly actions: {};
+    readonly services: {};
+    readonly computed: {};
+    readonly indexes: {} & {};
+};

package/dist/physics/physics-data-plugin.js

@@ -0,0 +1,71 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { F32 } from "@adobe/data/schema";
+import { Vec3, Quat } from "@adobe/data/math";
+import { BodyType } from "./body/body-type/body-type.js";
+import { ColliderShape } from "./body/collider-shape/collider-shape.js";
+import { Material } from "../material/material.js";
+/**
+ * The shared, solver-agnostic rigid-body data model — the seam every physics
+ * solver plugs into. It declares *only* authored/canonical state (no systems):
+ *
+ *   bodyType, colliderShape, halfExtents, material  — authored shape + role
+ *   position, rotation, linearVelocity, angularVelocity — canonical live state
+ *
+ * A **solver plugin** `extends` this, may keep its own private `_`-prefixed
+ * internal state (broadphase, caches, GPU buffers), and each frame reads the
+ * authored state and writes back `position`/`rotation`/velocity for dynamic
+ * bodies. A renderer reads the canonical transforms, decoupled from which
+ * solver produced them — so solvers (`joltSolver`, `rapierSolver`; the GPU XPBD
+ * solver is shelved) are interchangeable over identical authored scenes.
+ *
+ * Two archetypes share these components:
+ *   - **RigidBody** — `dynamic` or `kinematic` bodies that move; carries
+ *     velocities and a `bodyType` discriminator.
+ *   - **StaticCollider** — immovable colliders (floor, wall, ramp, scenery).
+ *     No velocities (never integrated) and no `bodyType` (the archetype *is*
+ *     the static classification) — a lean row for the bulk-static workload.
+ *
+ * `_prevPosition`/`_prevRotation` are derived (`_`-prefixed): the solver snapshots
+ * the pose *before* its final fixed step into them, so a render-rate interpolation
+ * pass can smoothly blend the previous → current simulated pose (see
+ * `physics-clock-plugin` + `interpolation-plugin`). Like `_worldMatrix`, they are
+ * *not* in the authored archetype — the solver migrates them onto each dynamic
+ * body the first time it mirrors it, so authors never supply derived state.
+ *
+ * Mass + inertia are derived per solver from shape + material (not stored here).
+ */
+export const physicsData = Database.Plugin.create({
+    extends: Material.plugin, // brings the `material` reference component
+    components: {
+        bodyType: BodyType.schema,
+        colliderShape: ColliderShape.schema,
+        halfExtents: Vec3.schema, // box extents; sphere radius in .x
+        position: Vec3.schema,
+        rotation: Quat.schema, // unified with Node.rotation so a body renders directly
+        linearVelocity: Vec3.schema,
+        angularVelocity: Vec3.schema,
+        _prevPosition: Vec3.schema, // derived: pose before the last fixed step (render interpolation)
+        _prevRotation: Quat.schema,
+        // Bodies sharing the same non-zero collisionGroup do not collide with each
+        // other (they still collide with group 0 / the world) — e.g. a ragdoll's
+        // bones. 0 = default (collide with everything). Honored by both solvers
+        // (Rapier per-collider groups; Jolt a no-self-collide object layer). Note:
+        // it's currently binary (group 0 vs "some non-zero group"), not per-id masks.
+        collisionGroup: F32.schema,
+        // Authored collision geometry for shapes `halfExtents` can't describe.
+        // Runtime objects (variable length, no schema): the solver reads them once
+        // when it mirrors the body, the bridge once to build the render mesh.
+        convexPoints: { default: null }, // colliderShape "hull": point cloud → convex hull
+        colliderMesh: { default: null }, // colliderShape "mesh": static triangle soup
+    },
+    archetypes: {
+        RigidBody: ["bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity"],
+        StaticCollider: ["colliderShape", "halfExtents", "material", "position", "rotation"],
+        // A convex-hull body (dynamic / kinematic): authored as a point cloud.
+        ConvexBody: ["bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity", "convexPoints"],
+        // A static triangle-mesh collider (terrain / level geometry).
+        MeshCollider: ["colliderShape", "halfExtents", "material", "position", "rotation", "colliderMesh"],
+    },
+});
+//# sourceMappingURL=physics-data-plugin.js.map

package/dist/physics/physics-data-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-data-plugin.js","sourceRoot":"","sources":["../../src/physics/physics-data-plugin.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAExE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAI,4CAA4C;IACxE,UAAU,EAAE;QACR,QAAQ,EAAS,QAAQ,CAAC,MAAM;QAChC,aAAa,EAAI,aAAa,CAAC,MAAM;QACrC,WAAW,EAAM,IAAI,CAAC,MAAM,EAAI,mCAAmC;QACnE,QAAQ,EAAS,IAAI,CAAC,MAAM;QAC5B,QAAQ,EAAS,IAAI,CAAC,MAAM,EAAE,wDAAwD;QACtF,cAAc,EAAG,IAAI,CAAC,MAAM;QAC5B,eAAe,EAAE,IAAI,CAAC,MAAM;QAC5B,aAAa,EAAI,IAAI,CAAC,MAAM,EAAE,kEAAkE;QAChG,aAAa,EAAI,IAAI,CAAC,MAAM;QAC5B,2EAA2E;QAC3E,yEAAyE;QACzE,wEAAwE;QACxE,2EAA2E;QAC3E,8EAA8E;QAC9E,cAAc,EAAG,GAAG,CAAC,MAAM;QAC3B,uEAAuE;QACvE,2EAA2E;QAC3E,sEAAsE;QACtE,YAAY,EAAK,EAAE,OAAO,EAAE,IAA2B,EAAE,EAAE,kDAAkD;QAC7G,YAAY,EAAK,EAAE,OAAO,EAAE,IAA2B,EAAE,EAAE,6CAA6C;KAC3G;IACD,UAAU,EAAE;QACR,SAAS,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,CAAC;QAChI,cAAc,EAAE,CAAC,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC;QACpF,uEAAuE;QACvE,UAAU,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,CAAC;QACjJ,8DAA8D;QAC9D,YAAY,EAAE,CAAC,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,CAAC;KACrG;CACJ,CAAC,CAAC"}

package/dist/physics/ragdoll/fit-bone-capsules.d.ts

@@ -0,0 +1,39 @@
+import type { Vec3, Quat } from "@adobe/data/math";
+/**
+ * Fits one capsule collider to each significant bone of a skinned mesh — the
+ * per-bone colliders a ragdoll needs (you can't trimesh a deforming skin). Each
+ * vertex is assigned to the bone it's *most* weighted to; that bone's vertices
+ * are pushed into the bone's bind-local frame (via the joint's inverse-bind
+ * matrix) and a capsule is fitted to them: the longest local axis becomes the
+ * capsule axis, the perpendicular spread its radius.
+ *
+ * The result is expressed as a bone-local offset (`offsetPosition` /
+ * `offsetRotation`, which orients the Y-aligned capsule onto the fitted axis)
+ * plus dimensions — so the capsule's world pose each frame is just
+ * `jointWorldMatrix · offset`, tracking the animated skeleton.
+ */
+/** Skinned vertices in mesh (bind) space: `positions` (xyz triples), `joints`
+ *  (4 joint indices/vertex), `weights` (4 weights/vertex). */
+export interface SkinVertices {
+    positions: Float32Array;
+    joints: Uint32Array;
+    weights: Float32Array;
+}
+export interface FitBoneCapsulesInput {
+    jointCount: number;
+    /** glTF inverse-bind matrices, column-major, `jointCount × 16`. */
+    inverseBindMatrices: Float32Array;
+    skin: SkinVertices;
+    /** A vertex joins a bone only if its dominant weight ≥ this (default 0.5). */
+    minWeight?: number;
+    /** Bones with fewer assigned vertices than this get no capsule (default 6). */
+    minVertices?: number;
+}
+export interface BoneCapsule {
+    jointIndex: number;
+    offsetPosition: Vec3;
+    offsetRotation: Quat;
+    radius: number;
+    halfHeight: number;
+}
+export declare function fitBoneCapsules(input: FitBoneCapsulesInput): BoneCapsule[];