@adobe/data-gpu 0.9.69

package/src/graphics/scene/scene-uniforms/scene-uniforms-plugin.ts

@@ -0,0 +1,64 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { createStructBuffer, copyToGPUBuffer, getStructLayout, type TypedBuffer } from "@adobe/data/typed-buffer";
+import { Light } from "../light/light.js";
+import { Camera } from "../../camera/camera.js";
+import { SceneUniforms } from "./scene-uniforms.js";
+// Import the schema from its own module, not via the SceneUniforms namespace:
+// this runs at module load and the namespace barrel cycles back here, leaving
+// `SceneUniforms.schema` undefined under Node's load order (browsers tolerate it
+// via live bindings). The direct import has no cycle.
+import { schema as sceneUniformsSchema } from "./schema.js";
+
+const sceneUniformsStructLayout = getStructLayout(sceneUniformsSchema);
+
+/**
+ * sceneUniforms
+ *   query: —
+ *   read:
+ *     camera
+ *     light
+ *   write:
+ *     _sceneUniformsBuffer: GPUBuffer
+ */
+export const plugin = Database.Plugin.create({
+    extends: Database.Plugin.combine(Camera.plugin, Light.plugin),
+    resources: {
+        _sceneUniformsBuffer: { default: null as GPUBuffer | null, transient: true },
+    },
+    systems: {
+        sceneUniformsSystem: {
+            create: db => {
+                let structBuffer: TypedBuffer<SceneUniforms> | null = null;
+                return () => {
+                    const { device, light } = db.store.resources;
+                    const cam = db.store.resources.camera;
+                    if (!device || !cam) return;
+
+                    structBuffer ??= createStructBuffer(SceneUniforms.schema, sceneUniformsStructLayout.size);
+
+                    let gpuBuffer = db.store.resources._sceneUniformsBuffer;
+                    if (!gpuBuffer) {
+                        gpuBuffer = device.createBuffer({
+                            size: sceneUniformsStructLayout.size,
+                            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                        });
+                        db.store.resources._sceneUniformsBuffer = gpuBuffer;
+                    }
+
+                    structBuffer.set(0, {
+                        viewProjectionMatrix: Camera.toViewProjection(cam),
+                        lightDirection:  light.direction,
+                        ambientStrength: light.ambientStrength,
+                        lightColor:      light.color,
+                        cameraPosition:  cam.position,
+                    });
+
+                    db.store.resources._sceneUniformsBuffer = copyToGPUBuffer(structBuffer, device, gpuBuffer);
+                };
+            },
+            schedule: { during: ["preRender"] },
+        },
+    },
+});

package/src/graphics/scene/scene-uniforms/scene-uniforms.ts

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+/**
+ * Default scene uniform struct for a single-viewport, single-directional-light setup.
+ * Use `_sceneUniforms` plugin to have this written to a GPU buffer each frame.
+ *
+ * This is a starting point, not a required contract. Consumers that need different
+ * fields (multiple lights, fog, time, etc.) should define their own schema + plugin.
+ */
+export type SceneUniforms = Schema.ToType<typeof schema>;
+
+export * as SceneUniforms from "./public.js";

package/src/graphics/scene/scene-uniforms/schema.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { F32, Mat4x4, Vec3 } from "@adobe/data/math";
+import { Schema } from "@adobe/data/schema";
+
+export const schema = {
+    type: "object",
+    properties: {
+        viewProjectionMatrix: Mat4x4.schema,
+        lightDirection: Vec3.schema,
+        ambientStrength: F32.schema,
+        lightColor: Vec3.schema,
+        cameraPosition: Vec3.schema,
+    },
+    required: ["viewProjectionMatrix", "lightDirection", "ambientStrength", "lightColor", "cameraPosition"],
+    additionalProperties: false,
+} as const satisfies Schema;

package/src/index.ts

@@ -0,0 +1,72 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+// --- Scene model (declarative authored data, no camera, no systems) ----------
+export { scene } from "./graphics/scene/scene-plugin.js";
+
+// --- Authoring abstractions --------------------------------------------------
+export { animation } from "./graphics/animation/animation-plugin.js";
+export { AnimationTrack } from "./graphics/animation/animation-track/animation-track.js";
+export { InterpolationMode } from "./graphics/animation/interpolation-mode/interpolation-mode.js";
+
+// --- Infrastructure ----------------------------------------------------------
+export { core } from "./core/core-plugin.js";
+export { FrameTime } from "./core/frame-time/frame-time.js";
+export { graphics } from "./graphics/graphics-plugin.js";
+
+// --- Physics: shared rigid-body data model + pluggable solver seam -----------
+export { physicsData } from "./physics/physics-data-plugin.js";
+export { physicsClock } from "./physics/physics-clock-plugin.js";
+export type { PhysicsClock } from "./physics/physics-clock-plugin.js";
+export { jointData } from "./physics/joint/joint-plugin.js";
+export type { Joint } from "./physics/joint/joint.js";
+export { JointType } from "./physics/joint/joint-type/joint-type.js";
+export type { RigidBody } from "./physics/body/rigid-body.js";
+export type { StaticCollider } from "./physics/body/static-collider.js";
+export { BodyType } from "./physics/body/body-type/body-type.js";
+export { ColliderShape } from "./physics/body/collider-shape/collider-shape.js";
+export { rapierSolver } from "./physics/solvers/rapier-solver-plugin.js";
+export { joltSolver } from "./physics/solvers/jolt-solver-plugin.js";
+export { runSolverBenchmark } from "./physics/solvers/solver-benchmark.js";
+export type { SolverBenchmarkOptions, SolverBenchmarkResult } from "./physics/solvers/solver-benchmark.js";
+
+// --- Material registry (authored entities: physical + visible PBR props) ------
+export { Material } from "./material/material.js";
+
+// --- System plugins (consumed via aggregators) -------------------------------
+export { transform } from "./graphics/scene/node/transform-plugin.js";
+export { pbrCore } from "./graphics/rendering/pbr-core-plugin.js";
+export { modelLoader } from "./graphics/scene/model/model-loader-plugin.js";
+export { pbrSkinning } from "./graphics/rendering/skinning/skinning-plugin.js";
+export { picking } from "./graphics/picking/picking-plugin.js";
+export type { PickHit } from "./graphics/picking/pick-hit.js";
+
+// --- Rendering ---------------------------------------------------------------
+export { rendering } from "./graphics/rendering/rendering-plugin.js";
+export { pbrIblRender } from "./graphics/rendering/ibl-render/ibl-render-plugin.js";
+export { materialGpu } from "./graphics/rendering/material-gpu/material-gpu-plugin.js";
+export { pbrRender } from "./graphics/rendering/pbr-render/pbr-render-plugin.js";
+export { physicsRenderBridge } from "./graphics/rendering/pbr-render/physics-bridge-plugin.js";
+export { displayTransform } from "./graphics/rendering/display-transform-plugin.js";
+export { interpolation } from "./graphics/rendering/interpolation-plugin.js";
+export { modelCollider } from "./graphics/rendering/model-collider-plugin.js";
+export { boneColliders } from "./graphics/rendering/bone-collider-plugin.js";
+export { ragdollTrigger } from "./graphics/rendering/ragdoll-trigger-plugin.js";
+export { joltRagdoll } from "./graphics/rendering/jolt-ragdoll-plugin.js";
+export { fitBoneCapsules } from "./physics/ragdoll/fit-bone-capsules.js";
+export type { BoneCapsule } from "./physics/ragdoll/fit-bone-capsules.js";
+export { shapeGeometry } from "./graphics/scene/model/shape/shape-geometry-plugin.js";
+
+// --- Types (type + namespace, access .plugin for the ECS plugin) -------------
+export { Camera } from "./graphics/camera/camera.js";
+export { Light } from "./graphics/scene/light/light.js";
+export { Orbit } from "./graphics/camera/orbit/orbit.js";
+export { Node } from "./graphics/scene/node/node.js";
+export { Model } from "./graphics/scene/model/model.js";
+export { Geometry } from "./graphics/scene/model/geometry/geometry.js";
+export { SceneUniforms } from "./graphics/scene/scene-uniforms/scene-uniforms.js";
+export { StandardVertex } from "./graphics/rendering/standard-vertex/standard-vertex.js";
+export { VisibleMaterial } from "./graphics/rendering/visible-material/visible-material.js";
+
+// --- Utilities ---------------------------------------------------------------
+export { attachOrbitDrag } from "./graphics/camera/orbit/attach-orbit-drag.js";
+export type { OrbitDragService } from "./graphics/camera/orbit/attach-orbit-drag.js";

package/src/material/material-plugin.ts

@@ -0,0 +1,61 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { F32, Vec3, Vec4 } from "@adobe/data/math";
+import { standardMaterials } from "./standard-materials.js";
+
+/**
+ * The material registry — authored materials as ECS entities (an open set;
+ * added rarely, edited never). Each `Material` row carries physical props (read
+ * by any solver) and visible PBR factors + texture-source URLs (read by the
+ * renderer). A body / model references a material by `Entity` id; the
+ * render-side `materialGpu` plugin derives GPU textures + a palette from these
+ * rows and caches them, rebuilding only when a new material appears.
+ *
+ * `seedStandardMaterials` inserts the standard library and records a
+ * `name → Entity` lookup in the `materials` resource.
+ */
+export const plugin = Database.Plugin.create({
+    components: {
+        /** Reference (on a body, prop, or model) to a Material registry entity. */
+        material:             Entity.schema,
+        name:                 { type: "string" },
+        density:              F32.schema,
+        restitution:          F32.schema,
+        friction:             F32.schema,
+        compliance:           F32.schema,
+        heatCapacity:         F32.schema,
+        baseColorFactor:      Vec4.schema,
+        emissiveFactor:       Vec3.schema,
+        metallicFactor:       F32.schema,
+        roughnessFactor:      F32.schema,
+        normalScale:          F32.schema,
+        occlusionStrength:    F32.schema,
+        baseColorUrl:         { type: "string" },
+        metallicRoughnessUrl: { type: "string" },
+        normalUrl:            { type: "string" },
+        occlusionUrl:         { type: "string" },
+        emissiveUrl:          { type: "string" },
+    },
+    resources: {
+        /** name → Material entity, populated by `seedStandardMaterials`. */
+        materials: { default: {} as Record<string, Entity> },
+    },
+    archetypes: {
+        Material: [
+            "name",
+            "density", "restitution", "friction", "compliance", "heatCapacity",
+            "baseColorFactor", "emissiveFactor", "metallicFactor", "roughnessFactor", "normalScale", "occlusionStrength",
+            "baseColorUrl", "metallicRoughnessUrl", "normalUrl", "occlusionUrl", "emissiveUrl",
+        ],
+    },
+    transactions: {
+        seedStandardMaterials(t) {
+            const map: Record<string, Entity> = {};
+            for (const m of standardMaterials) {
+                map[m.name] = t.archetypes.Material.insert(m);
+            }
+            t.resources.materials = map;
+        },
+    },
+});

package/src/material/material.ts

@@ -0,0 +1,38 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Vec3, Vec4 } from "@adobe/data/math";
+
+/**
+ * One row of the `Material` archetype — an authored material carrying both its
+ * physical properties (read by any physics solver) and its visible PBR
+ * properties (read by the renderer / material-array builder). Materials are an
+ * open, data-driven registry, not a closed enum: add a row, never edit code.
+ *
+ * Texture maps are *sources* (URLs) fetched at runtime; `""` means "use the
+ * neutral fallback layer". `metallicRoughnessUrl` and `occlusionUrl` may point
+ * at the same ARM image (AO = R, Roughness = G, Metalness = B).
+ */
+export interface Material {
+    name: string;
+    // physical (read by any solver)
+    density: number;
+    restitution: number;
+    friction: number;
+    compliance: number;
+    heatCapacity: number;
+    // visible PBR factors (multipliers over the sampled maps)
+    baseColorFactor: Vec4;
+    emissiveFactor: Vec3;
+    metallicFactor: number;
+    roughnessFactor: number;
+    normalScale: number;
+    occlusionStrength: number;
+    // texture sources, fetched at runtime ("" = neutral fallback layer)
+    baseColorUrl: string;
+    metallicRoughnessUrl: string;
+    normalUrl: string;
+    occlusionUrl: string;
+    emissiveUrl: string;
+}
+
+export * as Material from "./public.js";

package/src/material/public.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { plugin } from "./material-plugin.js";
+export { standardMaterials } from "./standard-materials.js";

package/src/material/standard-materials.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// PBR texture maps © Poly Haven, CC0 (https://polyhaven.com). Fetched at
+// runtime by URL — never committed (see data-gpu-samples/CLAUDE.md). Poly
+// Haven's `arm` map packs AO(R) / Roughness(G) / Metalness(B), matching glTF's
+// occlusion + metallicRoughness channel conventions.
+
+import type { Material } from "./material.js";
+
+const tex = (slug: string, map: string): string =>
+    `https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/${slug}/${slug}_${map}_1k.jpg`;
+
+/**
+ * A standard material: physical constants (the old material table) plus neutral
+ * visible factors — the textures supply colour / roughness / metalness, so the
+ * factors are left at 1 and baseColor white.
+ */
+function standard(
+    name: string, slug: string,
+    density: number, restitution: number, friction: number, compliance: number, heatCapacity: number,
+): Material {
+    return {
+        name,
+        density, restitution, friction, compliance, heatCapacity,
+        baseColorFactor: [1, 1, 1, 1],
+        emissiveFactor: [0, 0, 0],
+        metallicFactor: 1, roughnessFactor: 1, normalScale: 1, occlusionStrength: 1,
+        baseColorUrl: tex(slug, "diff"),
+        metallicRoughnessUrl: tex(slug, "arm"),
+        normalUrl: tex(slug, "nor_gl"),
+        occlusionUrl: tex(slug, "arm"),
+        emissiveUrl: "",
+    };
+}
+
+/** The standard material library, seeded by `seedStandardMaterials`. */
+export const standardMaterials: readonly Material[] = [
+    standard("rubber", "rubber_tiles",         1.1,  0.80, 0.90, 1e-5, 2.0),
+    standard("wood",   "wood_table_001",       0.6,  0.35, 0.70, 5e-7, 1.7),
+    standard("stone",  "cobblestone_floor_08", 2.6,  0.20, 0.85, 1e-8, 0.8),
+    standard("steel",  "metal_plate",          7.8,  0.45, 0.50, 1e-9, 0.5),
+    standard("ice",    "snow_02",              0.92, 0.25, 0.05, 5e-9, 2.1),
+];

package/src/physics/README.md

@@ -0,0 +1,71 @@
+# Physics — feature roadmap
+
+A general-purpose, solver-agnostic physics layer for `@adobe/data-gpu`, suitable
+for games, visualisation, and film/animation. Bodies are authored as ECS data
+against a shared seam (`physicsData`); a pluggable **solver** (Jolt or Rapier)
+advances them each frame. See `solvers/README.md` for choosing a solver.
+
+This file is the running plan — check the box when a feature lands so we don't
+lose track. Keep it honest about approximations and limitations.
+
+## Done
+
+- [x] **Pluggable solver seam** — `physicsData` + interchangeable `joltSolver` /
+  `rapierSolver`; the same authored scene runs on either.
+- [x] **Body types** — `static`, `dynamic`, `kinematic` (kinematic driven to its
+  authored pose each step, pushing dynamics).
+- [x] **Collider shapes** — `sphere`, `box`, `capsule`, convex `hull` (authored
+  point cloud), static `mesh` (authored triangle soup).
+- [x] **Fixed-timestep clock** (`physicsClock`, default 60 Hz, configurable) —
+  sim rate decoupled from render rate, spiral-of-death capped.
+- [x] **Render-rate interpolation** — a pre-render pass blends prev→current into
+  the display pose (flat instances *and* the model `_worldMatrix` path).
+- [x] **Auto-generated colliders from render geometry** — `ModelBody` /
+  `StaticModelCollider` with `colliderShape: hull | mesh` and no collision data;
+  generated from `collisionGeometry ?? geometry` (scale baked, cached). Manual
+  colliders (authored `convexPoints` / `colliderMesh`) still work.
+- [x] **Efficient mirroring** — tag+exclude sync (O(new)), `getTypedArray`
+  write-back, reverse iteration on migrating loops.
+
+- [x] **Joints / constraints** — `fixed`, `point` (ball), `hinge` (revolute +
+  angle limits), `cone` (swing-twist: swing cone + twist range — anatomical
+  ragdoll limits). Demo: a hanging chain + a cone-limited arm. *`cone` limits are
+  full on Jolt; the Rapier compat binding has no cone constraint, so it
+  approximates `cone` as a free `point` — use `joltSolver` for ragdoll limits.*
+
+## Next
+
+- [ ] **Convex decomposition** (e.g. V-HACD) for concave *dynamic* colliders.
+  *Today a single auto-`hull` is a **convex approximation** — it fills
+  concavities (a chair's legs merge). Static concave geometry should use
+  `mesh`; concave dynamic bodies need decomposition into multiple hulls.*
+- [x] **Per-bone colliders for skinned meshes** — `fitBoneCapsules` fits one
+  capsule per bone from the skin (skinned meshes are excluded from the rigid
+  auto-collider on purpose; they deform); `boneColliders` spawns a kinematic
+  capsule per bone and tracks the animated skeleton (`jointWorldMatrix · offset`).
+  Demo: the `ragdoll` sample (CesiumMan walk). Flipping to dynamic is next.
+- [x] **Ragdoll controller + humanoid sample** — two backends behind the shared
+  `ragdollTrigger`, shown side by side in the `ragdoll` sample (CesiumMan walks,
+  then collapses onto the floor):
+  - **`joltRagdoll`** (Jolt-native) — Jolt's `Skeleton`/`RagdollSettings`/`Ragdoll`
+    with swing-twist limits + `DisableParentChildCollisions`; `DriveToPoseUsing-
+    Kinematics` while alive, falls + `GetPose` readback when limp. Built into the
+    solver's world via `_joltContext`. *Active ragdoll (`DriveToPoseUsingMotors`)
+    + velocity-seeding from the last animated motion are easy follow-ups.*
+  - **`boneColliders`** (generic) — our per-bone capsules + cone (Jolt) / free-ball
+    (Rapier) joints; `kinematic→dynamic` flip + `reconcileRagdoll` (world↔local)
+    so the skin flops. Runs on any solver. *Per-joint limit tuning is a follow-up.*
+- [ ] **Collision events + groups/masks + sensors** — contact callbacks drained
+  to ECS; per-body layer masks; overlap-only sensor colliders.
+- [ ] **Spatial queries** — raycast / shape-cast / overlap against the broadphase
+  (picking, line-of-sight, ground checks).
+- [ ] **`uint32`-indexed primitives** — flat-shaded collider/render meshes
+  currently emit `uint16` indices (fine for authored ramps/props, not dense
+  terrain).
+- [ ] **Deterministic headless joint tests** — the manual frame-stepping harness
+  (used by the solver benchmark) mis-times joint formation against async WASM
+  init, so joints are currently verified in-browser only. A proper harness
+  (await solver-ready before inserting bodies/joints) would let us assert e.g.
+  the cone clamp numerically.
+- [ ] **Active ragdoll** — motorised joints driving toward the animation pose
+  while dynamic (struck-but-recovers).

package/src/physics/body/body-type/body-type.ts

@@ -0,0 +1,14 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+/**
+ * How the solver treats a body:
+ *   static    — never integrated; an immovable collider (the bulk of a scene).
+ *   dynamic   — fully simulated.
+ *   kinematic — moved by external code; pushes dynamics but isn't pushed back.
+ */
+export type BodyType = Schema.ToType<typeof schema>;
+
+export * as BodyType from "./public.js";

package/src/physics/body/body-type/is-dynamic.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { BodyType } from "./body-type.js";
+
+/** True for bodies the solver integrates and writes back (vs static / kinematic). */
+export function isDynamic(t: BodyType): boolean {
+    return t === "dynamic";
+}

package/src/physics/body/body-type/public.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { schema } from "./schema.js";
+export { isDynamic } from "./is-dynamic.js";

package/src/physics/body/body-type/schema.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+
+export const schema = { type: "string", enum: ["static", "dynamic", "kinematic"] } as const satisfies Schema;

package/src/physics/body/collider-mesh.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * Authored triangle mesh for a **static** `mesh` collider (terrain, level
+ * geometry): flat vertex positions (xyz triples) + triangle indices. Static only
+ * — a triangle soup has no interior, so it can't be a moving body. Held as a
+ * runtime object component (`colliderMesh`); the solver reads it once to build
+ * the engine trimesh, the bridge once to build the render mesh.
+ */
+export interface ColliderMesh {
+    positions: Float32Array; // xyz triples
+    indices: Uint32Array;    // triangle list (3 indices per face)
+}

package/src/physics/body/collider-shape/collider-shape.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+/**
+ * Collider geometry. `halfExtents` carries the dimensions:
+ *   box     — all three axes (half-extents).
+ *   sphere  — `.x` is the radius.
+ *   capsule — `.x` is the radius, `.y` the cylinder's half-height; Y-aligned
+ *             (total height 2·(y + x)). `.z` unused.
+ *   hull    — convex hull of an authored `convexPoints` cloud; `halfExtents`
+ *             is unused (the geometry comes from the points).
+ *   mesh    — authored `colliderMesh` triangle soup; **static only** (no
+ *             interior). `halfExtents` unused. Terrain / level geometry.
+ */
+export type ColliderShape = Schema.ToType<typeof schema>;
+
+export * as ColliderShape from "./public.js";

package/src/physics/body/collider-shape/list.ts

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { ColliderShape } from "./collider-shape.js";
+import { schema } from "./schema.js";
+
+/** Stable shape order — the index is the solver's numeric shape id. */
+export const list: readonly ColliderShape[] = schema.enum;

package/src/physics/body/collider-shape/mass-properties.ts

@@ -0,0 +1,47 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { ColliderShape } from "./collider-shape.js";
+
+/**
+ * Mass + diagonal inverse inertia for a shape of the given half-extents and
+ * density. The per-shape formulas live here (with the type) rather than leaking
+ * the shape members into the solver. Allocation-free: the diagonal inverse
+ * inertia is written into `outInvInertia[o..o+2]` and the inverse mass returned
+ * (this runs per dynamic body per frame in the solver gather). Density comes
+ * from the body's material.
+ */
+export function massProperties(
+    shape: ColliderShape, hx: number, hy: number, hz: number, density: number,
+    outInvInertia: Float32Array, o: number,
+): number {
+    if (shape === "box") {
+        const mass = density * 8 * hx * hy * hz;
+        const ix = (mass / 3) * (hy * hy + hz * hz);
+        const iy = (mass / 3) * (hx * hx + hz * hz);
+        const iz = (mass / 3) * (hx * hx + hy * hy);
+        outInvInertia[o] = 1 / ix; outInvInertia[o + 1] = 1 / iy; outInvInertia[o + 2] = 1 / iz;
+        return 1 / mass;
+    }
+    if (shape === "capsule") {
+        // Y-aligned: radius r = hx, cylinder half-height = hy (length L = 2·hy).
+        // A cylinder plus two hemispheres (together one sphere of radius r).
+        const r = hx, L = 2 * hy;
+        const mc = density * Math.PI * r * r * L;          // cylinder
+        const ms = density * (4 / 3) * Math.PI * r * r * r; // two hemispheres = a sphere
+        const mass = mc + ms;
+        // axial (Y): cylinder ½mc r² + sphere ⅖ms r²
+        const iy = 0.5 * mc * r * r + 0.4 * ms * r * r;
+        // transverse (X = Z): cylinder about centre, plus each hemisphere's own
+        // inertia (83/320·mh r²) shifted by parallel axis to the capsule centre
+        // (COM offset L/2 + 3r/8). See standard capsule-inertia derivation.
+        const d = L / 2 + 3 * r / 8;
+        const ix = mc * (L * L / 12 + r * r / 4) + ms * ((83 / 320) * r * r + d * d);
+        outInvInertia[o] = 1 / ix; outInvInertia[o + 1] = 1 / iy; outInvInertia[o + 2] = 1 / ix;
+        return 1 / mass;
+    }
+    // sphere — radius in hx
+    const mass = density * (4 / 3) * Math.PI * hx * hx * hx;
+    const inv = 1 / (0.4 * mass * hx * hx);
+    outInvInertia[o] = inv; outInvInertia[o + 1] = inv; outInvInertia[o + 2] = inv;
+    return 1 / mass;
+}

package/src/physics/body/collider-shape/public.ts

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { schema } from "./schema.js";
+export { list } from "./list.js";
+export { toIndex } from "./to-index.js";
+export { massProperties } from "./mass-properties.js";

package/src/physics/body/collider-shape/schema.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+
+export const schema = { type: "string", enum: ["sphere", "box", "capsule", "hull", "mesh"] } as const satisfies Schema;

package/src/physics/body/collider-shape/to-index.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { ColliderShape } from "./collider-shape.js";
+
+/** The solver's numeric shape id (sphere 0, box 1, capsule 2, hull 3, mesh 4). */
+export function toIndex(shape: ColliderShape): number {
+    return shape === "box" ? 1 : shape === "capsule" ? 2 : shape === "hull" ? 3 : shape === "mesh" ? 4 : 0;
+}

package/src/physics/body/rigid-body.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Entity } from "@adobe/data/ecs";
+import type { Vec3, Quat } from "@adobe/data/math";
+import type { BodyType } from "./body-type/body-type.js";
+import type { ColliderShape } from "./collider-shape/collider-shape.js";
+
+/**
+ * One row of the `RigidBody` archetype — the authored surface every physics
+ * solver reads, and whose `position`/`rotation`/velocity it writes back each
+ * frame. Mass and inertia are *derived* from `colliderShape` + `halfExtents` +
+ * `material` (see ColliderShape.massProperties), so they aren't stored here.
+ */
+export interface RigidBody {
+    bodyType: BodyType;
+    colliderShape: ColliderShape;
+    /** Box extents on all axes; sphere radius in `.x`. */
+    halfExtents: Vec3;
+    /** Reference to a Material registry entity (physical + visible props). */
+    material: Entity;
+    position: Vec3;
+    /** Unified with Node.rotation so a body is directly renderable. */
+    rotation: Quat;
+    linearVelocity: Vec3;
+    angularVelocity: Vec3;
+}

package/src/physics/body/static-collider.ts

@@ -0,0 +1,28 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Entity } from "@adobe/data/ecs";
+import type { Vec3, Quat } from "@adobe/data/math";
+import type { ColliderShape } from "./collider-shape/collider-shape.js";
+
+/**
+ * One row of the `StaticCollider` archetype — an immovable collider (floor,
+ * wall, ramp, arbitrary scenery). Dynamic bodies collide with it, but the
+ * solver never integrates it, so it carries no velocity columns: a lean
+ * representation for the bulk-static workload (many static, few dynamic).
+ *
+ * It is the same authored surface as a `RigidBody` minus `bodyType` (the
+ * archetype *is* the "static" classification) and the velocity components.
+ * Friction / restitution / compliance come from its `material`, exactly as for
+ * a dynamic body. Like a RigidBody, its `position`/`rotation` double as the
+ * renderable transform (the render bridge gives it geometry).
+ */
+export interface StaticCollider {
+    colliderShape: ColliderShape;
+    /** Box extents on all axes; sphere radius in `.x`. */
+    halfExtents: Vec3;
+    /** Reference to a Material registry entity (physical + visible props). */
+    material: Entity;
+    position: Vec3;
+    /** Unified with Node.rotation so the collider is directly renderable. */
+    rotation: Quat;
+}

package/src/physics/joint/joint-plugin.ts

@@ -0,0 +1,33 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { F32 } from "@adobe/data/schema";
+import { Vec3 } from "@adobe/data/math";
+import { JointType } from "./joint-type/joint-type.js";
+
+/**
+ * jointData — the solver-agnostic constraint data model. A `Joint` connects two
+ * bodies (`jointBodyA`/`jointBodyB`, any solver's bodies) with anchors in each
+ * body's local frame; the active solver mirrors each joint into its engine once
+ * both bodies exist (tag + exclude, like body sync). Authored only — no systems.
+ *
+ * Independent of `physicsData` (it only references bodies by `Entity`), so a
+ * solver `combine`s both. See `joint.ts` for the row type and `README.md` for
+ * the roadmap (joints are the ragdoll prerequisite).
+ */
+export const jointData = Database.Plugin.create({
+    components: {
+        jointType:     JointType.schema,
+        jointBodyA:    Entity.schema,
+        jointBodyB:    Entity.schema,
+        jointAnchorA:  Vec3.schema,   // anchor on body A, A-local
+        jointAnchorB:  Vec3.schema,   // anchor on body B, B-local
+        jointAxis:     Vec3.schema,   // hinge/cone reference axis (A-local); unused for fixed/point
+        jointMinLimit: F32.schema,    // hinge angle / cone twist lower bound (rad); min >= max ⇒ no limit
+        jointMaxLimit: F32.schema,    // hinge angle / cone twist upper bound (rad)
+        jointSwingLimit: F32.schema,  // cone swing half-angle (rad); cone only
+    },
+    archetypes: {
+        Joint: ["jointType", "jointBodyA", "jointBodyB", "jointAnchorA", "jointAnchorB", "jointAxis", "jointMinLimit", "jointMaxLimit", "jointSwingLimit"],
+    },
+});