@adobe/data-gpu 0.9.69

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

@@ -0,0 +1,97 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { Mat4x4, Quat } from "@adobe/data/math";
+import { physicsData } from "../../physics/physics-data-plugin.js";
+import { physicsClock } from "../../physics/physics-clock-plugin.js";
+import { transform } from "../scene/node/transform-plugin.js";
+import { displayTransform } from "./display-transform-plugin.js";
+
+/**
+ * interpolation — the single pre-render pass that turns the fixed-step physics
+ * state into a smooth display pose. Because the solver steps on `physicsClock`
+ * (0..N steps/frame), the canonical `position`/`rotation` jump in fixed
+ * increments; rendering them raw judders when the render rate ≠ the sim rate.
+ *
+ * Each render frame this blends `_prevPosition`→`position` (and the rotations)
+ * by `physicsClock.alpha` into `_renderPosition`/`_renderRotation`, which the
+ * renderer draws. Doing it once here (not in each renderer) keeps render systems
+ * free of physics knowledge — they only read the display transform.
+ *
+ * Bodies gain `_renderPosition`/`_renderRotation` the first frame after the
+ * solver has mirrored them (i.e. once `_prevPosition` exists); the tag-exclude
+ * query means steady state never re-scans already-equipped bodies.
+ */
+
+// Dynamic bodies that have been mirrored (so `_prevPosition` exists) but don't
+// yet carry the display-pose columns — give them those columns once.
+const NEEDS_RENDER_POSE = ["position", "rotation", "_prevPosition"] as const;
+const WITHOUT_RENDER_POSE = { exclude: ["_renderPosition"] } as const;
+// Fully-equipped bodies: blend prev→current into the display pose every frame.
+const INTERPOLATED = ["position", "rotation", "_prevPosition", "_prevRotation", "_renderPosition", "_renderRotation"] as const;
+// Interpolated bodies that render through the world-matrix path (models, which have
+// a `parent`/`_worldMatrix`) rather than the flat instanced path.
+const INTERPOLATED_MODEL = ["_renderPosition", "_renderRotation", "scale", "parent", "_worldMatrix"] as const;
+
+export const interpolation = Database.Plugin.create({
+    extends: Database.Plugin.combine(physicsData, physicsClock, displayTransform, transform),
+    systems: {
+        interpolateDisplayPose: {
+            schedule: { during: ["preRender"] },
+            create: db => () => {
+                // 1) Equip newly-mirrored bodies with display-pose columns (seed = current
+                //    pose). Tail→head: every visited row migrates out on gaining the columns.
+                for (const arch of db.store.queryArchetypes(NEEDS_RENDER_POSE, WITHOUT_RENDER_POSE)) {
+                    const ids = arch.columns.id, pos = arch.columns.position, ori = arch.columns.rotation;
+                    for (let r = arch.rowCount - 1; r >= 0; r--) {
+                        db.store.update(ids.get(r), { _renderPosition: pos.get(r), _renderRotation: ori.get(r) });
+                    }
+                }
+
+                // 2) Blend prev→current by alpha into the display pose — every frame, in
+                //    place (no migration), straight on the backing typed arrays.
+                const alpha = db.store.resources.physicsClock.alpha;
+                for (const arch of db.store.queryArchetypes(INTERPOLATED)) {
+                    const pos = arch.columns.position.getTypedArray(), ori = arch.columns.rotation.getTypedArray();
+                    const pp = arch.columns._prevPosition.getTypedArray(), pr = arch.columns._prevRotation.getTypedArray();
+                    const rp = arch.columns._renderPosition.getTypedArray(), rr = arch.columns._renderRotation.getTypedArray();
+                    for (let r = 0; r < arch.rowCount; r++) {
+                        const r3 = r * 3, r4 = r * 4;
+                        rp[r3] = pp[r3] + (pos[r3] - pp[r3]) * alpha;
+                        rp[r3 + 1] = pp[r3 + 1] + (pos[r3 + 1] - pp[r3 + 1]) * alpha;
+                        rp[r3 + 2] = pp[r3 + 2] + (pos[r3 + 2] - pp[r3 + 2]) * alpha;
+                        // nlerp with shortest-path sign flip — cheap, allocation-free, and
+                        // visually exact for the small per-step rotations of interpolation.
+                        let ax = pr[r4], ay = pr[r4 + 1], az = pr[r4 + 2], aw = pr[r4 + 3];
+                        const bx = ori[r4], by = ori[r4 + 1], bz = ori[r4 + 2], bw = ori[r4 + 3];
+                        if (ax * bx + ay * by + az * bz + aw * bw < 0) { ax = -ax; ay = -ay; az = -az; aw = -aw; }
+                        const x = ax + (bx - ax) * alpha, y = ay + (by - ay) * alpha, z = az + (bz - az) * alpha, w = aw + (bw - aw) * alpha;
+                        const inv = 1 / Math.hypot(x, y, z, w);
+                        rr[r4] = x * inv; rr[r4 + 1] = y * inv; rr[r4 + 2] = z * inv; rr[r4 + 3] = w * inv;
+                    }
+                }
+            },
+        },
+        // Models render from `_worldMatrix` (the transform path), not the flat display
+        // pose — so recompose their world matrix from the interpolated pose, after the
+        // blend above and after `transformSystem` (which wrote the raw, juddering pose).
+        interpolateWorldMatrix: {
+            schedule: { during: ["preRender"], after: ["interpolateDisplayPose", "transformSystem"] },
+            create: db => () => {
+                for (const arch of db.store.queryArchetypes(INTERPOLATED_MODEL)) {
+                    const rp = arch.columns._renderPosition.getTypedArray(), rr = arch.columns._renderRotation.getTypedArray();
+                    const scl = arch.columns.scale, parents = arch.columns.parent, world = arch.columns._worldMatrix;
+                    for (let i = 0; i < arch.rowCount; i++) {
+                        const r3 = i * 3, r4 = i * 4, s = scl.get(i), parentId = parents.get(i);
+                        const local = Mat4x4.multiply(
+                            Mat4x4.translation(rp[r3], rp[r3 + 1], rp[r3 + 2]),
+                            Mat4x4.multiply(Quat.toMat4([rr[r4], rr[r4 + 1], rr[r4 + 2], rr[r4 + 3]]), Mat4x4.scaling(s[0], s[1], s[2])),
+                        );
+                        const parentWorld = parentId === 0 ? Mat4x4.identity : db.store.get(parentId, "_worldMatrix") ?? Mat4x4.identity;
+                        world.set(i, parentId === 0 ? local : Mat4x4.multiply(parentWorld, local));
+                    }
+                }
+            },
+        },
+    },
+});

package/src/graphics/rendering/interpolation.test.ts

@@ -0,0 +1,52 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { Database } from "@adobe/data/ecs";
+import { interpolation } from "./interpolation-plugin.js";
+import type { PhysicsClock } from "../../physics/physics-clock-plugin.js";
+
+/**
+ * The interpolation pass turns the fixed-step sim state into a smooth render pose.
+ * No solver here — we hand-seed the prev snapshot a solver would write, then assert
+ * the display pose is the alpha-blend of prev → current. Pure + deterministic
+ * (no WASM, no GPU), so it runs headless.
+ */
+describe("interpolation", () => {
+    // A created database carries a writable `store` (runtime invariant; not on the
+    // public type — the same loose access the solver benchmark uses).
+    interface InterpStore {
+        resources: { physicsClock: PhysicsClock };
+        archetypes: { RigidBody: { insert(v: object): number } };
+        read(id: number): { _renderPosition: readonly number[] };
+        update(id: number, v: object): void;
+    }
+
+    const make = () => {
+        const db = Database.create(interpolation);
+        const store = (db as unknown as { store: InterpStore }).store;
+        // a body the solver has already mirrored (so it carries a prev snapshot)
+        const id = store.archetypes.RigidBody.insert({
+            bodyType: "dynamic", colliderShape: "box", halfExtents: [0.5, 0.5, 0.5], material: 0,
+            position: [0, 10, 0], rotation: [0, 0, 0, 1], linearVelocity: [0, 0, 0], angularVelocity: [0, 0, 0],
+        });
+        store.update(id, { _prevPosition: [0, 10, 0], _prevRotation: [0, 0, 0, 1] });
+        store.update(id, { position: [0, 6, 0] }); // a step landed: prev y=10, current y=6
+
+        const interpolateAt = (alpha: number): number => {
+            store.resources.physicsClock = { ...store.resources.physicsClock, alpha, steps: 0 };
+            db.system.functions.interpolateDisplayPose?.();
+            return store.read(id)._renderPosition[1];
+        };
+        return { interpolateAt };
+    };
+
+    it("blends prev → current by the clock's alpha into the display pose", () => {
+        expect(make().interpolateAt(0.25)).toBeCloseTo(9); // 10 + (6 - 10) * 0.25
+    });
+
+    it("at alpha→0 the display pose equals prev; at alpha→1 it equals current", () => {
+        const { interpolateAt } = make();
+        expect(interpolateAt(0)).toBeCloseTo(10); // prev
+        expect(interpolateAt(1)).toBeCloseTo(6);  // current
+    });
+});

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

@@ -0,0 +1,174 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, type Entity } from "@adobe/data/ecs";
+import { Mat4x4, Quat } from "@adobe/data/math";
+import { joltSolver, type JoltContext } from "../../physics/solvers/jolt-solver-plugin.js";
+import { fitBoneCapsules } from "../../physics/ragdoll/fit-bone-capsules.js";
+import { ragdollTrigger } from "./ragdoll-trigger-plugin.js";
+import { pbrSkinning } from "./skinning/skinning-plugin.js";
+import { modelLoader } from "../scene/model/model-loader-plugin.js";
+import { transform } from "../scene/node/transform-plugin.js";
+import type { JointTemplate } from "../scene/model/gltf/parse-skin.js";
+
+/**
+ * joltRagdoll — a **Jolt-native** ragdoll backend (the alternative to our generic
+ * `boneColliders`), using Jolt's `Skeleton` / `RagdollSettings` / `Ragdoll`.
+ *
+ * Once the skin loads, it builds a `Ragdoll` in the *solver's* physics system: one
+ * dynamic body per bone (capsule fitted by `fitBoneCapsules`, tiny sphere for
+ * capsule-less joints), a swing-twist constraint to each parent, and
+ * `DisableParentChildCollisions`. While alive it `DriveToPoseUsingKinematics`
+ * toward the animated pose each frame; on `triggerRagdoll` it stops driving (the
+ * bodies fall) and reads the pose back onto the skeleton so the skin flops.
+ *
+ * Jolt-only by construction — it needs the solver's `PhysicsSystem` (exposed as
+ * `_joltContext`). Pair it with `joltSolver`; use `boneColliders` for other solvers.
+ */
+
+type Jolt = JoltContext["jolt"];
+interface SkinGeo { _cpuSkin?: { positions: Float32Array; joints: Uint32Array; weights: Float32Array } | null; _skinInverseBindMatrices?: Float32Array | null; _skinJointTemplate?: JointTemplate[] }
+
+/** Column-major rigid transform from a position + unit quaternion. */
+const compose = (px: number, py: number, pz: number, q: ArrayLike<number>): Mat4x4 =>
+    Mat4x4.multiply(Mat4x4.translation(px, py, pz), Quat.toMat4([q[0], q[1], q[2], q[3]]));
+
+/** Orthonormalised rotation of a column-major matrix → quaternion. */
+function rotationOf(m: Mat4x4): Quat {
+    let m00 = m[0], m10 = m[1], m20 = m[2], m01 = m[4], m11 = m[5], m21 = m[6], m02 = m[8], m12 = m[9], m22 = m[10];
+    const sx = Math.hypot(m00, m10, m20) || 1, sy = Math.hypot(m01, m11, m21) || 1, sz = Math.hypot(m02, m12, m22) || 1;
+    m00 /= sx; m10 /= sx; m20 /= sx; m01 /= sy; m11 /= sy; m21 /= sy; m02 /= sz; m12 /= sz; m22 /= sz;
+    const tr = m00 + m11 + m22;
+    if (tr > 0) { const s = Math.sqrt(tr + 1) * 2; return [(m21 - m12) / s, (m02 - m20) / s, (m10 - m01) / s, 0.25 * s]; }
+    if (m00 > m11 && m00 > m22) { const s = Math.sqrt(1 + m00 - m11 - m22) * 2; return [0.25 * s, (m01 + m10) / s, (m02 + m20) / s, (m21 - m12) / s]; }
+    if (m11 > m22) { const s = Math.sqrt(1 + m11 - m00 - m22) * 2; return [(m01 + m10) / s, 0.25 * s, (m12 + m21) / s, (m02 - m20) / s]; }
+    const s = Math.sqrt(1 + m22 - m00 - m11) * 2; return [(m02 + m20) / s, (m12 + m21) / s, 0.25 * s, (m10 - m01) / s];
+}
+
+const SWING = 0.9, TWIST = 0.5; // ~52° swing cone, ~±29° twist
+
+export const joltRagdoll = Database.Plugin.create({
+    extends: Database.Plugin.combine(joltSolver, ragdollTrigger, pbrSkinning, modelLoader, transform),
+    systems: {
+        joltRagdollSystem: {
+            schedule: { during: ["postUpdate"], after: ["transformSystem"] },
+            create: db => {
+                let built = false, dead = false;
+                // Jolt objects (created at build): the ragdoll, a reusable pose, scratch.
+                let ragdoll: InstanceType<Jolt["Ragdoll"]> | null = null;
+                let pose: InstanceType<Jolt["SkeletonPose"]> | null = null;
+                let joints: readonly Entity[] = [];
+                let modelEntity: Entity = 0 as Entity; // the skeleton's root parent (the Model); moved to follow the ragdoll root when limp
+                let tv: InstanceType<Jolt["Vec3"]> | null = null, tq: InstanceType<Jolt["Quat"]> | null = null, troot: InstanceType<Jolt["RVec3"]> | null = null;
+
+                const jointWorld = (j: Entity): Mat4x4 => (db.store.get(j, "_worldMatrix") as Mat4x4 | undefined) ?? Mat4x4.identity;
+
+                const build = (ctx: JoltContext, jointIds: readonly Entity[], g: SkinGeo): void => {
+                    const jolt = ctx.jolt, template = g._skinJointTemplate!;
+                    const caps = new Map<number, { radius: number; halfHeight: number; offPos: readonly number[]; offRot: readonly number[] }>();
+                    for (const c of fitBoneCapsules({ jointCount: jointIds.length, inverseBindMatrices: g._skinInverseBindMatrices!, skin: g._cpuSkin! }))
+                        caps.set(c.jointIndex, { radius: c.radius, halfHeight: c.halfHeight, offPos: c.offsetPosition, offRot: c.offsetRotation });
+
+                    const skel = new jolt.Skeleton();
+                    for (let i = 0; i < jointIds.length; i++) { const s = new jolt.JPHString(template[i]?.name ?? `j${i}`, (template[i]?.name ?? `j${i}`).length); skel.AddJoint(s, template[i]?.parentJointIndex ?? -1); jolt.destroy(s); }
+
+                    const settings = new jolt.RagdollSettings();
+                    settings.mSkeleton = skel;
+                    // RagdollPart has no constructor in the IDL — resize the parts vector and
+                    // configure each element in place, then write the vector back.
+                    const parts = settings.mParts;
+                    parts.resize(jointIds.length);
+                    for (let i = 0; i < jointIds.length; i++) {
+                        const jw = jointWorld(jointIds[i]), cap = caps.get(i);
+                        const part = parts.at(i);
+                        // body bind pose: capsule sits at jointWorld · offset; sphere at the joint
+                        const bodyW = cap ? Mat4x4.multiply(jw, compose(cap.offPos[0], cap.offPos[1], cap.offPos[2], cap.offRot)) : jw;
+                        const shp = cap ? new jolt.CapsuleShape(Math.max(cap.halfHeight, 1e-3), cap.radius) : new jolt.SphereShape(0.03);
+                        part.SetShape(shp);
+                        const bp = new jolt.RVec3(bodyW[12], bodyW[13], bodyW[14]); const br = rotationOf(bodyW); const bq = new jolt.Quat(br[0], br[1], br[2], br[3]);
+                        part.set_mPosition(bp); part.set_mRotation(bq);
+                        part.set_mMotionType(jolt.EMotionType_Dynamic); part.set_mObjectLayer(ctx.ragdollLayer);
+                        const pj = template[i]?.parentJointIndex ?? -1;
+                        if (pj >= 0) {
+                            // swing-twist to the parent, anchored at this joint, bone axis = parent→this
+                            const pw = jointWorld(jointIds[pj]);
+                            let ax = jw[12] - pw[12], ay = jw[13] - pw[13], az = jw[14] - pw[14];
+                            const al = Math.hypot(ax, ay, az) || 1; ax /= al; ay /= al; az /= al;
+                            let nx = 0, ny = 0, nz = 0; if (Math.abs(ax) <= Math.abs(ay) && Math.abs(ax) <= Math.abs(az)) { ny = az; nz = -ay; } else { nx = -az; nz = ax; }
+                            const nl = Math.hypot(nx, ny, nz) || 1; nx /= nl; ny /= nl; nz /= nl;
+                            const st = new jolt.SwingTwistConstraintSettings();
+                            st.mSpace = jolt.EConstraintSpace_WorldSpace;
+                            const p1 = new jolt.RVec3(jw[12], jw[13], jw[14]), p2 = new jolt.RVec3(jw[12], jw[13], jw[14]);
+                            const t1 = new jolt.Vec3(ax, ay, az), t2 = new jolt.Vec3(ax, ay, az), n1 = new jolt.Vec3(nx, ny, nz), n2 = new jolt.Vec3(nx, ny, nz);
+                            st.mPosition1 = p1; st.mPosition2 = p2; st.mTwistAxis1 = t1; st.mTwistAxis2 = t2; st.mPlaneAxis1 = n1; st.mPlaneAxis2 = n2;
+                            st.mSwingType = jolt.ESwingType_Cone; st.mNormalHalfConeAngle = SWING; st.mPlaneHalfConeAngle = SWING; st.mTwistMinAngle = -TWIST; st.mTwistMaxAngle = TWIST;
+                            part.set_mToParent(st);
+                            jolt.destroy(p1); jolt.destroy(p2); jolt.destroy(t1); jolt.destroy(t2); jolt.destroy(n1); jolt.destroy(n2);
+                        }
+                        jolt.destroy(bp); jolt.destroy(bq);
+                    }
+                    settings.mParts = parts;
+                    settings.DisableParentChildCollisions();
+                    settings.Stabilize();
+                    ragdoll = settings.CreateRagdoll(0, 0, ctx.physicsSystem) as typeof ragdoll;
+                    ragdoll!.AddToPhysicsSystem(jolt.EActivation_Activate);
+                    pose = new jolt.SkeletonPose(); pose.SetSkeleton(skel);
+                    tv = new jolt.Vec3(0, 0, 0); tq = new jolt.Quat(0, 0, 0, 1); troot = new jolt.RVec3(0, 0, 0);
+                    joints = jointIds;
+                    let rootIdx = template.findIndex(t => (t.parentJointIndex ?? -1) < 0); if (rootIdx < 0) rootIdx = 0;
+                    modelEntity = (db.store.get(jointIds[rootIdx], "parent") as Entity | undefined) ?? (0 as Entity);
+                    jolt.destroy(settings);
+                };
+
+                return () => {
+                    const ctx = db.store.resources._joltContext;
+                    if (!ctx) return;
+                    if (!built) {
+                        for (const arch of db.store.queryArchetypes(["_skeletonJoints", "_skeletonGeometry"])) {
+                            const jc = arch.columns._skeletonJoints, gc = arch.columns._skeletonGeometry;
+                            for (let i = 0; i < arch.rowCount; i++) {
+                                const g = db.store.read(gc.get(i)) as SkinGeo | null;
+                                if (!g?._cpuSkin || !g._skinInverseBindMatrices || !g._skinJointTemplate?.length) continue;
+                                build(ctx, jc.get(i), g); built = true; break;
+                            }
+                            if (built) break;
+                        }
+                        if (!built) return;
+                    }
+                    const jolt = ctx.jolt, rd = ragdoll!, p = pose!;
+                    if (!dead && db.store.resources._ragdollTrigger) {
+                        dead = true;
+                        for (const a of db.store.queryArchetypes(["animationPlaying"])) for (let i = 0; i < a.rowCount; i++) db.store.update(a.columns.id.get(i), { animationPlaying: false });
+                    }
+                    if (!dead) {
+                        // alive: drive the ragdoll toward the animated pose. Root offset =
+                        // the model's world translation; joint states = the animated locals.
+                        const rm = jointWorld(modelEntity);
+                        troot!.Set(rm[12], rm[13], rm[14]); p.SetRootOffset(troot!);
+                        for (let i = 0; i < joints.length; i++) {
+                            const pos = db.store.get(joints[i], "position") as readonly number[] | undefined;
+                            const rot = db.store.get(joints[i], "rotation") as readonly number[] | undefined;
+                            if (!pos || !rot) continue;
+                            const st = p.GetJoint(i);
+                            tv!.Set(pos[0], pos[1], pos[2]); tq!.Set(rot[0], rot[1], rot[2], rot[3]);
+                            st.set_mTranslation(tv!); st.set_mRotation(tq!);
+                        }
+                        p.CalculateJointMatrices();
+                        rd.DriveToPoseUsingKinematics(p, db.store.resources.physicsClock.fixedDt * Math.max(1, db.store.resources.physicsClock.steps));
+                    } else {
+                        // limp: read the physics pose back. The ragdoll's root has fallen, so move
+                        // the model to the pose's root offset and apply the local joint states —
+                        // the whole skin follows the fall, the limbs flop.
+                        rd.GetPose(p, false);
+                        p.CalculateJointStates();
+                        const ro = p.GetRootOffset();
+                        db.store.update(modelEntity, { position: [ro.GetX(), ro.GetY(), ro.GetZ()] });
+                        for (let i = 0; i < joints.length; i++) {
+                            const st = p.GetJoint(i), t = st.get_mTranslation(), r = st.get_mRotation();
+                            db.store.update(joints[i], { position: [t.GetX(), t.GetY(), t.GetZ()], rotation: [r.GetX(), r.GetY(), r.GetZ(), r.GetW()] });
+                        }
+                    }
+                };
+            },
+        },
+    },
+});

package/src/graphics/rendering/material-gpu/material-arrays.ts

@@ -0,0 +1,113 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * The shared GPU material set: five `texture_2d_array`s (one per PBR map) plus
+ * a palette storage buffer of per-layer factors. Every material occupies one
+ * layer across all five arrays; a drawable selects its material with a single
+ * per-instance layer index. Built once and grown by layer — materials are
+ * added rarely and edited never, so nothing here is rebuilt per frame.
+ */
+export interface MaterialArrays {
+    baseColor: GPUTexture;          // rgba8unorm-srgb
+    metallicRoughness: GPUTexture;  // rgba8unorm (G = roughness, B = metalness)
+    normal: GPUTexture;             // rgba8unorm
+    occlusion: GPUTexture;          // rgba8unorm (R = AO)
+    emissive: GPUTexture;           // rgba8unorm-srgb
+}
+
+/** Fixed layer size every material map is resampled to. */
+export const MATERIAL_TEXTURE_SIZE = 512;
+/** Maximum distinct materials (array layers). 16 × 512² × 5 maps ≈ 80 MB. */
+export const MAX_MATERIAL_LAYERS = 16;
+/** Bytes per palette entry: baseColor(vec4) + emissive/metallic(vec4) + rough/normal/occlusion(vec4). */
+export const PALETTE_STRIDE = 48;
+
+export function createMaterialArrays(device: GPUDevice): MaterialArrays {
+    const make = (format: GPUTextureFormat): GPUTexture =>
+        device.createTexture({
+            size: [MATERIAL_TEXTURE_SIZE, MATERIAL_TEXTURE_SIZE, MAX_MATERIAL_LAYERS],
+            dimension: "2d",
+            format,
+            // RENDER_ATTACHMENT is required by copyExternalImageToTexture.
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+    return {
+        baseColor:         make("rgba8unorm-srgb"),
+        metallicRoughness: make("rgba8unorm"),
+        normal:            make("rgba8unorm"),
+        occlusion:         make("rgba8unorm"),
+        emissive:          make("rgba8unorm-srgb"),
+    };
+}
+
+/** Per-material visible factors written into one palette layer. */
+export interface MaterialFactors {
+    baseColorFactor: readonly number[];
+    emissiveFactor: readonly number[];
+    metallicFactor: number;
+    roughnessFactor: number;
+    normalScale: number;
+    occlusionStrength: number;
+}
+
+const _palette = new Float32Array(PALETTE_STRIDE / 4);
+
+export function writePaletteLayer(device: GPUDevice, palette: GPUBuffer, layer: number, f: MaterialFactors): void {
+    _palette[0] = f.baseColorFactor[0]; _palette[1] = f.baseColorFactor[1]; _palette[2] = f.baseColorFactor[2]; _palette[3] = f.baseColorFactor[3];
+    _palette[4] = f.emissiveFactor[0]; _palette[5] = f.emissiveFactor[1]; _palette[6] = f.emissiveFactor[2]; _palette[7] = f.metallicFactor;
+    _palette[8] = f.roughnessFactor; _palette[9] = f.normalScale; _palette[10] = f.occlusionStrength; _palette[11] = 0;
+    device.queue.writeBuffer(palette, layer * PALETTE_STRIDE, _palette);
+}
+
+/** The five map source URLs for one material ("" = leave the neutral layer). */
+export interface MaterialMapUrls {
+    baseColorUrl: string;
+    metallicRoughnessUrl: string;
+    normalUrl: string;
+    occlusionUrl: string;
+    emissiveUrl: string;
+}
+
+/**
+ * Fetches a material's maps and blits them (resampled to the layer size) into
+ * its array layer. Fire-and-forget: each map resolves independently, so a body
+ * renders (neutral) immediately and sharpens as textures arrive. URLs shared
+ * across maps (e.g. an ARM image used for both metallicRoughness and occlusion)
+ * are fetched once and copied to each target.
+ */
+export function loadMaterialMaps(device: GPUDevice, arrays: MaterialArrays, layer: number, urls: MaterialMapUrls): void {
+    const targets: { url: string; tex: GPUTexture }[] = [
+        { url: urls.baseColorUrl,         tex: arrays.baseColor },
+        { url: urls.metallicRoughnessUrl, tex: arrays.metallicRoughness },
+        { url: urls.normalUrl,            tex: arrays.normal },
+        { url: urls.occlusionUrl,         tex: arrays.occlusion },
+        { url: urls.emissiveUrl,          tex: arrays.emissive },
+    ];
+    const byUrl = new Map<string, GPUTexture[]>();
+    for (const t of targets) {
+        if (!t.url) continue;
+        const list = byUrl.get(t.url);
+        if (list) list.push(t.tex);
+        else byUrl.set(t.url, [t.tex]);
+    }
+    for (const [url, texes] of byUrl) {
+        fetch(url)
+            .then(r => { if (!r.ok) throw new Error(`material map ${r.status}: ${url}`); return r.blob(); })
+            .then(blob => createImageBitmap(blob, {
+                resizeWidth: MATERIAL_TEXTURE_SIZE,
+                resizeHeight: MATERIAL_TEXTURE_SIZE,
+                colorSpaceConversion: "none",
+            }))
+            .then(bitmap => {
+                for (const tex of texes) {
+                    device.queue.copyExternalImageToTexture(
+                        { source: bitmap },
+                        { texture: tex, origin: [0, 0, layer] },
+                        [MATERIAL_TEXTURE_SIZE, MATERIAL_TEXTURE_SIZE, 1],
+                    );
+                }
+                bitmap.close();
+            })
+            .catch(err => console.warn("[materialGpu] map load failed", err));
+    }
+}

package/src/graphics/rendering/material-gpu/material-bind-group.ts

@@ -0,0 +1,61 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { MaterialArrays } from "./material-arrays.js";
+
+interface DeviceCache {
+    layout: GPUBindGroupLayout;
+    sampler: GPUSampler;
+}
+const cacheByDevice = new WeakMap<GPUDevice, DeviceCache>();
+
+function deviceCache(device: GPUDevice): DeviceCache {
+    let c = cacheByDevice.get(device);
+    if (!c) {
+        const tex = (binding: number): GPUBindGroupLayoutEntry => ({
+            binding, visibility: GPUShaderStage.FRAGMENT,
+            texture: { sampleType: "float", viewDimension: "2d-array" },
+        });
+        c = {
+            layout: device.createBindGroupLayout({
+                entries: [
+                    { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "read-only-storage" } },
+                    tex(1), tex(2), tex(3), tex(4), tex(5),
+                    { binding: 6, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+                ],
+            }),
+            sampler: device.createSampler({
+                magFilter: "linear", minFilter: "linear", mipmapFilter: "linear",
+                addressModeU: "repeat", addressModeV: "repeat",
+            }),
+        };
+        cacheByDevice.set(device, c);
+    }
+    return c;
+}
+
+/**
+ * Bind-group layout for the shared material set: palette storage buffer +
+ * five `texture_2d_array`s + a filtering sampler. The renderer's primitive
+ * pipeline builds its pipeline layout from this; `createMaterialBindGroup`
+ * builds the matching bind group. Cached per device.
+ */
+export function createMaterialBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+    return deviceCache(device).layout;
+}
+
+export function createMaterialBindGroup(device: GPUDevice, arrays: MaterialArrays, palette: GPUBuffer): GPUBindGroup {
+    const { layout, sampler } = deviceCache(device);
+    const view = (t: GPUTexture): GPUTextureView => t.createView({ dimension: "2d-array" });
+    return device.createBindGroup({
+        layout,
+        entries: [
+            { binding: 0, resource: { buffer: palette } },
+            { binding: 1, resource: view(arrays.baseColor) },
+            { binding: 2, resource: view(arrays.metallicRoughness) },
+            { binding: 3, resource: view(arrays.normal) },
+            { binding: 4, resource: view(arrays.occlusion) },
+            { binding: 5, resource: view(arrays.emissive) },
+            { binding: 6, resource: sampler },
+        ],
+    });
+}

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

@@ -0,0 +1,95 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { U32 } from "@adobe/data/math";
+import { core } from "../../../core/core-plugin.js";
+import { Material } from "../../../material/material.js";
+import {
+    type MaterialArrays,
+    MAX_MATERIAL_LAYERS, PALETTE_STRIDE,
+    createMaterialArrays, writePaletteLayer, loadMaterialMaps,
+} from "./material-arrays.js";
+import { createMaterialBindGroup } from "./material-bind-group.js";
+
+/** Material rows the builder reads to fill a layer (factors + map URLs). */
+const MATERIAL_COMPONENTS = [
+    "baseColorFactor", "emissiveFactor", "metallicFactor", "roughnessFactor", "normalScale", "occlusionStrength",
+    "baseColorUrl", "metallicRoughnessUrl", "normalUrl", "occlusionUrl", "emissiveUrl",
+] as const;
+
+/**
+ * materialGpu — derives the shared GPU material set from the `Material`
+ * registry. Each authored material is assigned one array layer; its factors go
+ * into the palette buffer and its maps are fetched + blitted into that layer.
+ *
+ * Incremental and cached: the arrays / palette / bind group are built once, and
+ * a layer is assigned only to a material that doesn't have one yet (`_layerIndex`
+ * excluded). Materials are added rarely and edited never, so steady state does
+ * no work. The renderer (P3) binds `_materialBindGroup` once and selects a
+ * material per instance by `_layerIndex`.
+ */
+export const materialGpu = Database.Plugin.create({
+    extends: Database.Plugin.combine(Material.plugin, core),
+    components: {
+        _layerIndex: U32.schema,
+    },
+    resources: {
+        _materialArrays:    { default: null as MaterialArrays | null, transient: true },
+        _materialPalette:   { default: null as GPUBuffer | null, transient: true },
+        _materialBindGroup: { default: null as GPUBindGroup | null, transient: true },
+    },
+    systems: {
+        materialGpuBuilder: {
+            schedule: { during: ["preRender"] },
+            create: db => {
+                let arrays: MaterialArrays | null = null;
+                let palette: GPUBuffer | null = null;
+                let nextLayer = 0;
+                return () => {
+                    const { device } = db.store.resources;
+                    if (!device) return;
+
+                    // Assign a layer to each material that lacks one. Tail→head:
+                    // every visited row migrates out (gains _layerIndex), so the
+                    // removal is always from the tail — no hole-fill shift. The GPU
+                    // arrays are created lazily on the first material, so glTF-only
+                    // scenes (no materials) allocate nothing.
+                    for (const arch of db.store.queryArchetypes(["name", ...MATERIAL_COMPONENTS], { exclude: ["_layerIndex"] })) {
+                        const c = arch.columns;
+                        for (let i = arch.rowCount - 1; i >= 0; i--) {
+                            if (nextLayer >= MAX_MATERIAL_LAYERS) break;
+                            if (!arrays || !palette) {
+                                arrays = createMaterialArrays(device);
+                                palette = device.createBuffer({
+                                    size: MAX_MATERIAL_LAYERS * PALETTE_STRIDE,
+                                    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+                                });
+                                db.store.resources._materialArrays = arrays;
+                                db.store.resources._materialPalette = palette;
+                                db.store.resources._materialBindGroup = createMaterialBindGroup(device, arrays, palette);
+                            }
+                            const id = c.id.get(i);
+                            const layer = nextLayer++;
+                            writePaletteLayer(device, palette, layer, {
+                                baseColorFactor: c.baseColorFactor.get(i),
+                                emissiveFactor: c.emissiveFactor.get(i),
+                                metallicFactor: c.metallicFactor.get(i),
+                                roughnessFactor: c.roughnessFactor.get(i),
+                                normalScale: c.normalScale.get(i),
+                                occlusionStrength: c.occlusionStrength.get(i),
+                            });
+                            loadMaterialMaps(device, arrays, layer, {
+                                baseColorUrl: c.baseColorUrl.get(i),
+                                metallicRoughnessUrl: c.metallicRoughnessUrl.get(i),
+                                normalUrl: c.normalUrl.get(i),
+                                occlusionUrl: c.occlusionUrl.get(i),
+                                emissiveUrl: c.emissiveUrl.get(i),
+                            });
+                            db.store.update(id, { _layerIndex: layer });
+                        }
+                    }
+                };
+            },
+        },
+    },
+});