@adobe/data-gpu 0.9.69

package/src/graphics/rendering/model-collider-plugin.ts

@@ -0,0 +1,77 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { physicsData } from "../../physics/physics-data-plugin.js";
+import type { ColliderMesh } from "../../physics/body/collider-mesh.js";
+import { modelLoader } from "../scene/model/model-loader-plugin.js";
+import { hullVertices } from "../scene/model/shape/convex-hull.js";
+
+/**
+ * modelCollider — lets a rendered model double as a physics body whose collider is
+ * **auto-generated from its mesh**. A `ModelBody` (or `StaticModelCollider`) carries
+ * a `geometry` + a `colliderShape` of `"hull"` or `"mesh"` but *no* collision data;
+ * this fills it once the mesh has loaded:
+ *
+ *   hull → `convexPoints` = the simplified hull vertices of the mesh (the engine
+ *          rebuilds the hull) — a coarse, convex stand-in for a detailed model.
+ *   mesh → `colliderMesh` = the mesh triangles verbatim (static trimesh).
+ *
+ * The source defaults to the body's own `geometry` but can be overridden with
+ * `collisionGeometry` (point it at a low-poly mesh for a cheaper collider). The
+ * model's `scale` is baked into the collision geometry so it matches the render.
+ * Generated data is cached per (source geometry, shape, scale), so many instances
+ * of one model share it. Authoring the collider by hand (supplying `convexPoints`
+ * / `colliderMesh` directly, as `ConvexBody` / `MeshCollider` do) still works and
+ * simply skips generation.
+ *
+ * Because the body already has a `geometry`, the physics render bridge leaves it
+ * alone — it renders as the detailed model and collides as the generated shape.
+ */
+export const modelCollider = Database.Plugin.create({
+    extends: Database.Plugin.combine(physicsData, modelLoader),
+    components: {
+        collisionGeometry: Entity.schema, // optional override: generate the collider from this Geometry instead of `geometry`
+    },
+    archetypes: {
+        // A model that is also a dynamic/kinematic body; collider auto-generated.
+        ModelBody: ["geometry", "scale", "visible", "parent", "bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity"],
+        // A static model collider (immovable level geometry that renders as a model).
+        StaticModelCollider: ["geometry", "scale", "visible", "parent", "colliderShape", "halfExtents", "material", "position", "rotation"],
+    },
+    systems: {
+        generateModelColliders: {
+            schedule: { during: ["postUpdate"] },
+            create: db => {
+                // generated collider data, shared across instances of the same (source mesh, shape, scale)
+                const cache = new Map<string, { convexPoints: Float32Array } | { colliderMesh: ColliderMesh }>();
+                return () => {
+                    // model-bodies (geometry + scale) whose collider data isn't generated yet
+                    for (const arch of db.store.queryArchetypes(["colliderShape", "geometry", "scale"], { exclude: ["convexPoints", "colliderMesh"] })) {
+                        const ids = arch.columns.id, css = arch.columns.colliderShape, scl = arch.columns.scale;
+                        // tail→head: filling the data migrates the row out of this archetype
+                        for (let i = arch.rowCount - 1; i >= 0; i--) {
+                            const shape = css.get(i);
+                            if (shape !== "hull" && shape !== "mesh") continue; // primitive-shaped model-bodies need no generation
+                            const id = ids.get(i);
+                            const src = (db.store.read(id) as { collisionGeometry?: Entity }).collisionGeometry || arch.columns.geometry.get(i);
+                            const mesh = db.store.read(src) as { _cpuPositions?: Float32Array | null; _cpuIndices?: Uint32Array | null } | null;
+                            const positions = mesh?._cpuPositions;
+                            if (!positions) continue; // source mesh not loaded yet — retry next frame
+                            const s = scl.get(i), key = `${src}:${shape}:${s[0]}:${s[1]}:${s[2]}`;
+                            let data = cache.get(key);
+                            if (!data) {
+                                const scaled = new Float32Array(positions.length);
+                                for (let k = 0; k < positions.length; k += 3) { scaled[k] = positions[k] * s[0]; scaled[k + 1] = positions[k + 1] * s[1]; scaled[k + 2] = positions[k + 2] * s[2]; }
+                                data = shape === "hull"
+                                    ? { convexPoints: hullVertices(scaled) }
+                                    : { colliderMesh: { positions: scaled, indices: mesh!._cpuIndices ?? new Uint32Array(0) } };
+                                cache.set(key, data);
+                            }
+                            db.store.update(id, data);
+                        }
+                    }
+                };
+            },
+        },
+    },
+});

package/src/graphics/rendering/pbr-core-plugin.ts

@@ -0,0 +1,40 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { Mat4x4 } from "@adobe/data/math";
+import { U32 } from "@adobe/data/math";
+
+/**
+ * Shape declarations shared between asset producers (model loader, shape
+ * generators) and consumers (renderers). Every component and archetype is
+ * ephemeral — not part of the user's data model. Pair with an asset
+ * producer plus a renderer aggregator (`pbrIblRender`)
+ * to get drawable scenes.
+ */
+export const pbrCore = Database.Plugin.create({
+    components: {
+        _vertexBuffer:                  { default: null as GPUBuffer | null },
+        /** Secondary VBO with skinning attributes (joints u32×4, weights f32×4),
+         *  null for static primitives. Drives skinned-pipeline dispatch. */
+        _skinVertexBuffer:              { default: null as GPUBuffer | null },
+        _indexBuffer:                   { default: null as GPUBuffer | null },
+        _indexCount:                    U32.schema,
+        _indexFormat:                   { default: "uint16" as GPUIndexFormat },
+        _materialBindGroup:             { default: null as GPUBindGroup | null },
+        /** Back-reference from a _PbrPrimitive / _VisibleMaterial to the
+         *  authored Geometry that owns it. */
+        _geometry:                      Entity.schema,
+        _material:                      Entity.schema,
+        /** Node-local-to-model-root matrix baked at load time. The renderer
+         *  pre-multiplies it with the per-instance model-root world matrix. */
+        _nodeLocalMatrix:               Mat4x4.schema,
+        /** Skeleton-side back-references the renderer reads when dispatching
+         *  the skinned pipeline. Populated by `pbrSkinning`. */
+        _skeletonModelRef:              Entity.schema,
+        _skeletonJointMatrixBindGroup:  { default: null as GPUBindGroup | null },
+    },
+    archetypes: {
+        _VisibleMaterial: ["ephemeral", "_materialBindGroup", "_geometry"],
+        _PbrPrimitive: ["ephemeral", "_vertexBuffer", "_skinVertexBuffer", "_indexBuffer", "_indexCount", "_indexFormat", "_material", "_geometry", "_nodeLocalMatrix"],
+    },
+});

package/src/graphics/rendering/pbr-render/pbr-array-shader.wgsl.ts

@@ -0,0 +1,146 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { wgslStructFields } from "@adobe/data/typed-buffer";
+import { schema as sceneUniformsSchema } from "../../scene/scene-uniforms/schema.js";
+import brdf from "../ibl-render/brdf.wgsl.js";
+
+/**
+ * Unified PBR shader for instanced primitives (and, after convergence, glTF).
+ * Materials come from the shared `materialGpu` set — five `texture_2d_array`s +
+ * a palette of per-layer factors (group 1) — selected by a per-instance layer
+ * index (group 3, binding 1). Shading is identical Cook-Torrance + split-sum
+ * IBL to the per-material `ibl-shader`; only the material *source* differs.
+ */
+export function buildPbrArrayShader(options: { prefilteredMipCount: number }): string {
+    return /* wgsl */ `
+struct SceneUniforms {
+${wgslStructFields(sceneUniformsSchema)}
+}
+
+struct MaterialFactors {
+    baseColorFactor: vec4f,
+    emissiveMetallic: vec4f,   // emissive.rgb, metallicFactor
+    roughNormalOcc: vec4f,     // roughnessFactor, normalScale, occlusionStrength, _
+}
+
+@group(0) @binding(0) var<uniform> scene: SceneUniforms;
+
+@group(1) @binding(0) var<storage, read> palette: array<MaterialFactors>;
+@group(1) @binding(1) var baseColorArray: texture_2d_array<f32>;
+@group(1) @binding(2) var metallicRoughnessArray: texture_2d_array<f32>;
+@group(1) @binding(3) var normalArray: texture_2d_array<f32>;
+@group(1) @binding(4) var occlusionArray: texture_2d_array<f32>;
+@group(1) @binding(5) var emissiveArray: texture_2d_array<f32>;
+@group(1) @binding(6) var matSampler: sampler;
+
+@group(2) @binding(0) var iblIrradiance: texture_cube<f32>;
+@group(2) @binding(1) var iblPrefiltered: texture_cube<f32>;
+@group(2) @binding(2) var iblBrdfLut: texture_2d<f32>;
+@group(2) @binding(3) var iblSampler: sampler;
+
+@group(3) @binding(0) var<storage, read> instances: array<mat4x4<f32>>;
+@group(3) @binding(1) var<storage, read> layers: array<u32>;
+
+const PREFILTERED_MIP_COUNT: f32 = ${options.prefilteredMipCount.toFixed(1)};
+
+struct VertexInput {
+    @location(0) position: vec3f,
+    @location(1) normal: vec3f,
+    @location(2) tangent: vec4f,
+    @location(3) uv: vec2f,
+}
+
+struct VertexOutput {
+    @builtin(position) clipPosition: vec4f,
+    @location(0) worldPosition: vec3f,
+    @location(1) normal: vec3f,
+    @location(2) tangent: vec3f,
+    @location(3) bitangent: vec3f,
+    @location(4) uv: vec2f,
+    @location(5) @interpolate(flat) layer: u32,
+}
+
+@vertex
+fn vs_main(@builtin(instance_index) instanceIndex: u32, in: VertexInput) -> VertexOutput {
+    let m = instances[instanceIndex];
+    let m3 = mat3x3<f32>(m[0].xyz, m[1].xyz, m[2].xyz);
+    let normalMat = mat3x3<f32>(
+        cross(m3[1], m3[2]),
+        cross(m3[2], m3[0]),
+        cross(m3[0], m3[1]),
+    );
+    let worldPos = m * vec4f(in.position, 1.0);
+    var out: VertexOutput;
+    out.clipPosition = scene.viewProjectionMatrix * worldPos;
+    out.worldPosition = worldPos.xyz;
+    out.normal = normalize(normalMat * in.normal);
+    out.tangent = normalize(m3 * in.tangent.xyz);
+    out.bitangent = normalize(cross(out.normal, out.tangent) * in.tangent.w);
+    out.uv = in.uv;
+    out.layer = layers[instanceIndex];
+    return out;
+}
+
+${brdf}
+
+@fragment
+fn fs_main(in: VertexOutput) -> @location(0) vec4f {
+    let f = palette[in.layer];
+    let li = i32(in.layer);
+
+    let baseColor = textureSample(baseColorArray, matSampler, in.uv, li) * f.baseColorFactor;
+
+    let mr = textureSample(metallicRoughnessArray, matSampler, in.uv, li);
+    let metallic = mr.b * f.emissiveMetallic.w;
+    var roughness = mr.g * f.roughNormalOcc.x;
+    roughness = max(roughness, MIN_ROUGHNESS);
+    let alpha = roughness * roughness;
+
+    let occlusion = textureSample(occlusionArray, matSampler, in.uv, li).r;
+    let emissive = textureSample(emissiveArray, matSampler, in.uv, li).rgb * f.emissiveMetallic.xyz;
+
+    let nSampled = textureSample(normalArray, matSampler, in.uv, li).rgb * 2.0 - vec3f(1.0);
+    let nScaled = vec3f(nSampled.xy * f.roughNormalOcc.y, nSampled.z);
+    let tbn = mat3x3<f32>(in.tangent, in.bitangent, in.normal);
+    let N = normalize(tbn * nScaled);
+
+    let V = normalize(scene.cameraPosition - in.worldPosition);
+    let nDotV = max(dot(N, V), 0.001);
+    let R = reflect(-V, N);
+
+    let f0 = mix(vec3f(0.04), baseColor.rgb, metallic);
+
+    // --- IBL contribution (split-sum) ---
+    let F_ibl = f_schlick_roughness(nDotV, f0, roughness);
+    let kD_ibl = (vec3f(1.0) - F_ibl) * (1.0 - metallic);
+
+    let irradiance = textureSampleLevel(iblIrradiance, iblSampler, N, 0.0).rgb;
+    let diffuseIbl = kD_ibl * irradiance * baseColor.rgb;
+
+    let mipLevel = roughness * (PREFILTERED_MIP_COUNT - 1.0);
+    let prefiltered = textureSampleLevel(iblPrefiltered, iblSampler, R, mipLevel).rgb;
+    let envBrdf = textureSampleLevel(iblBrdfLut, iblSampler, vec2f(nDotV, roughness), 0.0).rg;
+    let specularIbl = prefiltered * (F_ibl * envBrdf.x + envBrdf.y);
+
+    let ambient = (diffuseIbl + specularIbl) * mix(1.0, occlusion, f.roughNormalOcc.z);
+
+    // --- Direct light (parity with the single scene light) ---
+    let L = normalize(-scene.lightDirection);
+    let H = normalize(V + L);
+    let nDotL = max(dot(N, L), 0.0);
+    let nDotH = max(dot(N, H), 0.0);
+    let vDotH = max(dot(V, H), 0.0);
+    let D_d = d_ggx(nDotH, alpha);
+    let G_d = g_smith(nDotV, nDotL, alpha);
+    let F_d = f_schlick(vDotH, f0);
+    let spec_d = (D_d * G_d * F_d) / (4.0 * nDotV * nDotL + 0.0001);
+    let kD_d = (vec3f(1.0) - F_d) * (1.0 - metallic);
+    let direct = (kD_d * baseColor.rgb / PI + spec_d) * scene.lightColor * nDotL;
+
+    let color = direct + ambient + emissive;
+    let mapped = tone_map_aces(color);
+    let gamma = pow(mapped, vec3f(1.0 / 2.2));
+    return vec4f(gamma, baseColor.a);
+}
+`;
+}

package/src/graphics/rendering/pbr-render/pbr-render-plugin.ts

@@ -0,0 +1,247 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, type Entity } from "@adobe/data/ecs";
+import { pbrIblRender } from "../ibl-render/ibl-render-plugin.js";
+import { materialGpu } from "../material-gpu/material-gpu-plugin.js";
+import { displayTransform } from "../display-transform-plugin.js";
+import { SceneUniforms } from "../../scene/scene-uniforms/scene-uniforms.js";
+import { StandardVertex } from "../standard-vertex/standard-vertex.js";
+import { createMaterialBindGroupLayout } from "../material-gpu/material-bind-group.js";
+import { buildPbrArrayShader } from "./pbr-array-shader.wgsl.js";
+
+// Must match pbrIblRender's bake so the array shader's prefiltered-mip math agrees.
+const PREFILTERED_MIP_COUNT = 7;
+
+/** Drawable: any visible entity with a geometry ref, a transform, and a material. */
+const DRAWABLE = ["geometry", "visible", "position", "rotation", "scale", "material"] as const;
+// Bodies carrying a derived display pose (interpolation-plugin) draw at it instead
+// of the canonical pose; everything else (statics, props, non-physics instances)
+// draws straight from position/rotation. Splitting the gather by archetype shape
+// avoids a per-row "has display pose?" branch.
+const DRAWABLE_INTERP = [...DRAWABLE, "_renderPosition", "_renderRotation"] as const;
+const DRAWABLE_DIRECT = { exclude: ["_renderPosition"] } as const;
+const PRIMITIVE = ["_vertexBuffer", "_indexBuffer", "_indexCount", "_indexFormat", "_geometry", "_nodeLocalMatrix"] as const;
+
+/** Minimal column shape the gather reads — satisfied by either query's columns. */
+interface Col<T> { get(i: number): T }
+
+function createIblBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+    return device.createBindGroupLayout({
+        entries: [
+            { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "cube" } },
+            { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "cube" } },
+            { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
+            { binding: 3, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+        ],
+    });
+}
+
+/**
+ * Compose a column-major TRS matrix directly into `out[o..o+15]` — no
+ * allocation, reading position/rotation/scale straight from their column typed
+ * arrays. Matches `translation · Quat.toMat4 · scaling`. Runs once per visible
+ * drawable per frame, so the array churn of the math-helper form matters.
+ */
+function composeTrs(
+    out: Float32Array, o: number,
+    p: ArrayLike<number>, pi: number, q: ArrayLike<number>, qi: number, s: ArrayLike<number>, si: number,
+): void {
+    const qx = q[qi], qy = q[qi + 1], qz = q[qi + 2], qw = q[qi + 3];
+    const sx = s[si], sy = s[si + 1], sz = s[si + 2];
+    const xx = qx * qx, yy = qy * qy, zz = qz * qz;
+    const xy = qx * qy, xz = qx * qz, yz = qy * qz;
+    const wx = qw * qx, wy = qw * qy, wz = qw * qz;
+    out[o] = (1 - 2 * (yy + zz)) * sx; out[o + 1] = (2 * (xy + wz)) * sx; out[o + 2] = (2 * (xz - wy)) * sx; out[o + 3] = 0;
+    out[o + 4] = (2 * (xy - wz)) * sy; out[o + 5] = (1 - 2 * (xx + zz)) * sy; out[o + 6] = (2 * (yz + wx)) * sy; out[o + 7] = 0;
+    out[o + 8] = (2 * (xz + wy)) * sz; out[o + 9] = (2 * (yz - wx)) * sz; out[o + 10] = (1 - 2 * (xx + yy)) * sz; out[o + 11] = 0;
+    out[o + 12] = p[pi]; out[o + 13] = p[pi + 1]; out[o + 14] = p[pi + 2]; out[o + 15] = 1;
+}
+
+/**
+ * pbrRender — the single PBR + IBL renderer. It extends `pbrIblRender`, reusing
+ * its IBL bake, skybox, scene/material bind groups and glTF draw path verbatim,
+ * and adds one extra draw query for **instanced primitives** whose material
+ * comes from the shared `materialGpu` arrays (selected per instance by the
+ * material entity's `_layerIndex`). Two efficient queries, one render plugin:
+ *
+ *   - glTF models  → per-material bind group, native-resolution textures (pbrIblRender)
+ *   - primitives   → shared texture_2d_array + per-instance layer (this system)
+ *
+ * The primitive system runs after `pbrIblRenderSystem` so the skybox is drawn
+ * first. World matrices are computed directly from `position`/`rotation`/`scale`
+ * (primitives are flat — no hierarchy), so it's independent of `transform`.
+ */
+export const pbrRender = Database.Plugin.create({
+    extends: Database.Plugin.combine(pbrIblRender, materialGpu, displayTransform),
+    systems: {
+        pbrPrimitiveRenderSystem: {
+            schedule: { during: ["render"], after: ["beginRenderPass", "pbrIblRenderSystem"], before: ["endRenderPass"] },
+            create: db => {
+                let pipeline: GPURenderPipeline | null = null;
+                let sceneLayout: GPUBindGroupLayout | null = null;
+                let iblLayout: GPUBindGroupLayout | null = null;
+                let instanceLayout: GPUBindGroupLayout | null = null;
+                let iblSampler: GPUSampler | null = null;
+                let sceneBindGroup: GPUBindGroup | null = null;
+                let iblBindGroup: GPUBindGroup | null = null;
+                let cachedSceneBuffer: GPUBuffer | null = null;
+                let cachedIrradiance: GPUTexture | null = null;
+
+                let matLayer = new Map<Entity, number>();
+                let matCount = -1;
+
+                interface Inst { buffer: GPUBuffer; layerBuffer: GPUBuffer; bindGroup: GPUBindGroup; capacity: number }
+                const instCache = new Map<Entity, Inst>();
+                let matScratch = new Float32Array(16);
+                let layerScratch = new Uint32Array(1);
+                // Per-frame matrix arena (composed TRS, one mat4 per drawable) + per-geometry
+                // draw lists (matrix offset + layer). All pooled and reused across frames —
+                // the gather runs over every visible body each frame, so zero allocation here.
+                let mats = new Float32Array(64 * 16);
+                const batches = new Map<Entity, { off: number[]; layer: number[] }>();
+
+                return () => {
+                    const {
+                        device, renderPassEncoder, canvasFormat, depthFormat, _sceneUniformsBuffer,
+                        _materialBindGroup, _iblIrradiance, _iblPrefiltered, _iblBrdfLut,
+                    } = db.store.resources;
+                    if (!device || !renderPassEncoder || !_sceneUniformsBuffer || !_materialBindGroup) return;
+                    if (!_iblIrradiance || !_iblPrefiltered || !_iblBrdfLut) return;
+
+                    if (!sceneLayout) sceneLayout = SceneUniforms.createBindGroupLayout(device);
+                    if (!iblLayout) iblLayout = createIblBindGroupLayout(device);
+                    if (!instanceLayout) instanceLayout = device.createBindGroupLayout({
+                        entries: [
+                            { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                            { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                        ],
+                    });
+                    if (!iblSampler) iblSampler = device.createSampler({
+                        magFilter: "linear", minFilter: "linear", mipmapFilter: "linear",
+                        addressModeU: "clamp-to-edge", addressModeV: "clamp-to-edge", addressModeW: "clamp-to-edge",
+                    });
+                    if (!pipeline) {
+                        const module = device.createShaderModule({ code: buildPbrArrayShader({ prefilteredMipCount: PREFILTERED_MIP_COUNT }) });
+                        pipeline = device.createRenderPipeline({
+                            layout: device.createPipelineLayout({ bindGroupLayouts: [sceneLayout, createMaterialBindGroupLayout(device), iblLayout, instanceLayout] }),
+                            vertex: { module, entryPoint: "vs_main", buffers: [StandardVertex.layout] },
+                            fragment: { module, entryPoint: "fs_main", targets: [{ format: canvasFormat }] },
+                            primitive: { topology: "triangle-list", cullMode: "back" },
+                            depthStencil: { format: depthFormat, depthWriteEnabled: true, depthCompare: "less" },
+                        });
+                    }
+
+                    if (_sceneUniformsBuffer !== cachedSceneBuffer || !sceneBindGroup) {
+                        sceneBindGroup = device.createBindGroup({ layout: sceneLayout, entries: [{ binding: 0, resource: { buffer: _sceneUniformsBuffer } }] });
+                        cachedSceneBuffer = _sceneUniformsBuffer;
+                    }
+                    if (_iblIrradiance !== cachedIrradiance || !iblBindGroup) {
+                        iblBindGroup = device.createBindGroup({
+                            layout: iblLayout,
+                            entries: [
+                                { binding: 0, resource: _iblIrradiance.createView({ dimension: "cube" }) },
+                                { binding: 1, resource: _iblPrefiltered.createView({ dimension: "cube" }) },
+                                { binding: 2, resource: _iblBrdfLut.createView() },
+                                { binding: 3, resource: iblSampler },
+                            ],
+                        });
+                        cachedIrradiance = _iblIrradiance;
+                    }
+
+                    // material → layer, refreshed only when the material set grows
+                    let mc = 0;
+                    for (const arch of db.store.queryArchetypes(["_layerIndex"])) mc += arch.rowCount;
+                    if (mc !== matCount) {
+                        matLayer = new Map();
+                        for (const arch of db.store.queryArchetypes(["_layerIndex"])) {
+                            const id = arch.columns.id, li = arch.columns._layerIndex;
+                            for (let i = 0; i < arch.rowCount; i++) matLayer.set(id.get(i), li.get(i));
+                        }
+                        matCount = mc;
+                    }
+
+                    // Gather visible primitive drawables grouped by geometry. Compose each
+                    // world matrix straight from the chosen pose/scale column typed arrays
+                    // into the pooled `mats` arena — no per-row array allocation. Two passes:
+                    // bodies with a display pose use it; everything else uses position/rotation.
+                    for (const b of batches.values()) { b.off.length = 0; b.layer.length = 0; }
+                    let drawCount = 0;
+                    const gather = (
+                        rowCount: number, vis: Col<boolean>, geo: Col<Entity>, mat: Col<Entity>,
+                        posArr: ArrayLike<number>, rotArr: ArrayLike<number>, sclArr: ArrayLike<number>,
+                    ): void => {
+                        for (let i = 0; i < rowCount; i++) {
+                            if (!vis.get(i)) continue;
+                            const layer = matLayer.get(mat.get(i));
+                            if (layer === undefined) continue;
+                            if ((drawCount + 1) * 16 > mats.length) { const grown = new Float32Array(mats.length * 2); grown.set(mats); mats = grown; }
+                            composeTrs(mats, drawCount * 16, posArr, i * 3, rotArr, i * 4, sclArr, i * 3);
+                            const g = geo.get(i);
+                            let b = batches.get(g);
+                            if (!b) { b = { off: [], layer: [] }; batches.set(g, b); }
+                            b.off.push(drawCount); b.layer.push(layer);
+                            drawCount++;
+                        }
+                    };
+                    for (const arch of db.store.queryArchetypes(DRAWABLE_INTERP)) {
+                        gather(arch.rowCount, arch.columns.visible, arch.columns.geometry, arch.columns.material,
+                            arch.columns._renderPosition.getTypedArray(), arch.columns._renderRotation.getTypedArray(), arch.columns.scale.getTypedArray());
+                    }
+                    for (const arch of db.store.queryArchetypes(DRAWABLE, DRAWABLE_DIRECT)) {
+                        gather(arch.rowCount, arch.columns.visible, arch.columns.geometry, arch.columns.material,
+                            arch.columns.position.getTypedArray(), arch.columns.rotation.getTypedArray(), arch.columns.scale.getTypedArray());
+                    }
+                    if (drawCount === 0) return;
+
+                    renderPassEncoder.setPipeline(pipeline);
+                    renderPassEncoder.setBindGroup(0, sceneBindGroup);
+                    renderPassEncoder.setBindGroup(1, _materialBindGroup);
+                    renderPassEncoder.setBindGroup(2, iblBindGroup);
+
+                    for (const arch of db.store.queryArchetypes(PRIMITIVE)) {
+                        const vbs = arch.columns._vertexBuffer, ibs = arch.columns._indexBuffer;
+                        const counts = arch.columns._indexCount, formats = arch.columns._indexFormat;
+                        const geoRefs = arch.columns._geometry, primIds = arch.columns.id;
+                        for (let i = 0; i < arch.rowCount; i++) {
+                            const b = batches.get(geoRefs.get(i));
+                            if (!b || b.off.length === 0) continue;
+                            const n = b.off.length;
+                            const primId = primIds.get(i);
+
+                            let entry = instCache.get(primId);
+                            if (!entry || entry.capacity < n) {
+                                entry?.buffer.destroy();
+                                entry?.layerBuffer.destroy();
+                                const buffer = device.createBuffer({ size: Math.max(n * 64, 64), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+                                const layerBuffer = device.createBuffer({ size: Math.max(n * 4, 4), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+                                const bindGroup = device.createBindGroup({
+                                    layout: instanceLayout,
+                                    entries: [{ binding: 0, resource: { buffer } }, { binding: 1, resource: { buffer: layerBuffer } }],
+                                });
+                                entry = { buffer, layerBuffer, bindGroup, capacity: n };
+                                instCache.set(primId, entry);
+                            }
+                            if (matScratch.length < n * 16) matScratch = new Float32Array(n * 16);
+                            if (layerScratch.length < n) layerScratch = new Uint32Array(n);
+                            // Copy this geometry's matrices out of the arena into a contiguous
+                            // upload buffer. Primitive node matrices are identity (flat shapes;
+                            // glTF hierarchy goes through pbrIblRender), so no extra multiply.
+                            for (let j = 0; j < n; j++) {
+                                const src = b.off[j] * 16, dst = j * 16;
+                                for (let k = 0; k < 16; k++) matScratch[dst + k] = mats[src + k];
+                                layerScratch[j] = b.layer[j];
+                            }
+                            device.queue.writeBuffer(entry.buffer, 0, matScratch, 0, n * 16);
+                            device.queue.writeBuffer(entry.layerBuffer, 0, layerScratch, 0, n);
+
+                            renderPassEncoder.setBindGroup(3, entry.bindGroup);
+                            renderPassEncoder.setVertexBuffer(0, vbs.get(i)!); // _PbrPrimitive guarantees non-null
+                            renderPassEncoder.setIndexBuffer(ibs.get(i)!, formats.get(i)); // _PbrPrimitive guarantees non-null
+                            renderPassEncoder.drawIndexed(counts.get(i), n);
+                        }
+                    }
+                };
+            },
+        },
+    },
+});

package/src/graphics/rendering/pbr-render/physics-bridge-plugin.ts

@@ -0,0 +1,106 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, type Entity } from "@adobe/data/ecs";
+import { physicsData } from "../../../physics/physics-data-plugin.js";
+import { model } from "../../scene/model/model-plugin.js";
+import { shapeGeometry } from "../../scene/model/shape/shape-geometry-plugin.js";
+import { capsuleMesh, flatShadedMesh } from "../../scene/model/shape/shape-mesh.js";
+import { convexHullMesh } from "../../scene/model/shape/convex-hull.js";
+import { uploadShapeMesh } from "../../scene/model/shape/upload-shape-mesh.js";
+import type { ColliderMesh } from "../../../physics/body/collider-mesh.js";
+import { interpolation } from "../interpolation-plugin.js";
+
+/**
+ * physicsRenderBridge — makes colliders renderable by `pbrRender`. Once the
+ * shape geometries exist, every body with a collider shape (dynamic RigidBody
+ * or immovable StaticCollider alike) gains a `geometry` ref (sphere / cube by
+ * collider shape), a `scale` (its half-extents — the unit shapes are size-1),
+ * and `visible`. Because physics `rotation`/`position` are the same components
+ * the renderer reads, there is no per-frame sync: this only migrates new bodies.
+ *
+ * It also folds in `interpolation`, so dynamic bodies render at the smooth,
+ * render-rate display pose for free (the solver steps on a fixed clock that need
+ * not match the render rate) — bridging physics to the renderer is exactly when
+ * you want that. Use `interpolation` directly only with a custom (non-bridge) path.
+ *
+ * Also declares `Prop` — a render-only placed geometry with a material that is
+ * not a physics body at all (decorative scenery with no collider).
+ */
+export const physicsRenderBridge = Database.Plugin.create({
+    extends: Database.Plugin.combine(physicsData, model, shapeGeometry, interpolation),
+    archetypes: {
+        Prop: ["geometry", "position", "rotation", "scale", "visible", "material"],
+    },
+    systems: {
+        physicsBridge: {
+            schedule: { during: ["postUpdate"] },
+            create: db => {
+                // Sphere/cube are unit meshes scaled by half-extents. A capsule can't
+                // be non-uniformly scaled (its caps would distort), so it's built at its
+                // real size and drawn at unit scale — one mesh per distinct (radius,
+                // half-height), cached here (scenes use very few capsule sizes).
+                const capsuleGeometry = new Map<string, Entity>();
+                const ensureCapsule = (device: GPUDevice, r: number, hy: number): Entity => {
+                    const key = `${r}:${hy}`;
+                    let geo = capsuleGeometry.get(key);
+                    if (geo === undefined) {
+                        const m = uploadShapeMesh(device, capsuleMesh(r, hy));
+                        geo = db.transactions.insertShapePrimitive({ vertexBuffer: m.vb, indexBuffer: m.ib, indexCount: m.count });
+                        capsuleGeometry.set(key, geo);
+                    }
+                    return geo;
+                };
+                // Hull render mesh = triangulated convex hull of the point cloud, cached
+                // by the point-array reference (bodies sharing a cloud share one mesh + draw).
+                const hullGeometry = new Map<Float32Array, Entity>();
+                const ensureHull = (device: GPUDevice, points: Float32Array): Entity => {
+                    let geo = hullGeometry.get(points);
+                    if (geo === undefined) {
+                        const m = uploadShapeMesh(device, convexHullMesh(points));
+                        geo = db.transactions.insertShapePrimitive({ vertexBuffer: m.vb, indexBuffer: m.ib, indexCount: m.count });
+                        hullGeometry.set(points, geo);
+                    }
+                    return geo;
+                };
+                // Static-mesh render = flat-shaded triangle soup, cached by the colliderMesh ref.
+                const meshGeometry = new Map<ColliderMesh, Entity>();
+                const ensureMesh = (device: GPUDevice, cm: ColliderMesh): Entity => {
+                    let geo = meshGeometry.get(cm);
+                    if (geo === undefined) {
+                        const m = uploadShapeMesh(device, flatShadedMesh(cm.positions, cm.indices));
+                        geo = db.transactions.insertShapePrimitive({ vertexBuffer: m.vb, indexBuffer: m.ib, indexCount: m.count });
+                        meshGeometry.set(cm, geo);
+                    }
+                    return geo;
+                };
+                return () => {
+                    const shapes = db.store.resources._shapeGeometry;
+                    const device = db.store.resources.device;
+                    if (!shapes || !device) return;
+                    for (const arch of db.store.queryArchetypes(["colliderShape", "halfExtents"], { exclude: ["geometry"] })) {
+                        const ids = arch.columns.id, css = arch.columns.colliderShape, hes = arch.columns.halfExtents;
+                        // Tail→head: every visited body migrates out (gains geometry).
+                        for (let i = arch.rowCount - 1; i >= 0; i--) {
+                            const id = ids.get(i), shape = css.get(i), he = hes.get(i);
+                            // capsule + hull render at unit scale (their meshes are real-size);
+                            // sphere/cube are unit meshes scaled by half-extents.
+                            let geometry: Entity, scale: [number, number, number];
+                            if (shape === "box") { geometry = shapes.cube; scale = [he[0], he[1], he[2]]; }
+                            else if (shape === "capsule") { geometry = ensureCapsule(device, he[0], he[1]); scale = [1, 1, 1]; }
+                            else if (shape === "hull") {
+                                const pts = (db.store.read(id) as { convexPoints?: Float32Array | null }).convexPoints;
+                                geometry = pts ? ensureHull(device, pts) : shapes.sphere;
+                                scale = [1, 1, 1];
+                            } else if (shape === "mesh") {
+                                const cm = (db.store.read(id) as { colliderMesh?: ColliderMesh | null }).colliderMesh;
+                                geometry = cm ? ensureMesh(device, cm) : shapes.cube;
+                                scale = [1, 1, 1];
+                            } else { geometry = shapes.sphere; scale = [he[0], he[0], he[0]]; }
+                            db.store.update(id, { geometry, scale, visible: true });
+                        }
+                    }
+                };
+            },
+        },
+    },
+});

package/src/graphics/rendering/ragdoll-trigger-plugin.ts

@@ -0,0 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+
+/**
+ * ragdollTrigger — the backend-agnostic "go limp" signal. A scene calls
+ * `triggerRagdoll()`; whichever ragdoll backend is combined in (our generic
+ * `boneColliders`, or the Jolt-native `joltRagdoll`) consumes `_ragdollTrigger`
+ * once and switches its bones to dynamic. Sharing the flag lets the same scene
+ * drive either backend, so a sample can run our ragdoll on one solver and Jolt's
+ * on another, side by side.
+ */
+export const ragdollTrigger = Database.Plugin.create({
+    resources: {
+        _ragdollTrigger: { default: false as boolean, transient: true },
+    },
+    transactions: {
+        /** Go limp: the active ragdoll backend flips its bones to dynamic. */
+        triggerRagdoll(t) { t.resources._ragdollTrigger = true; },
+    },
+});

package/src/graphics/rendering/rendering-plugin.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { pbrIblRender as rendering } from "./ibl-render/ibl-render-plugin.js";