@adobe/data-gpu 0.9.69

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

@@ -0,0 +1,182 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { True } from "@adobe/data/schema";
+import { Vec3, Quat, Mat4x4 } from "@adobe/data/math";
+import { physicsData } from "../../physics/physics-data-plugin.js";
+import { jointData } from "../../physics/joint/joint-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";
+
+/**
+ * boneColliders — fits a capsule to each bone of a skinned model and ragdolls it.
+ *
+ * **Alive:** once the skin loads, `fitBoneCapsules` gives a per-bone capsule
+ * (bone-local offset + dims); we spawn a **kinematic** capsule per bone and each
+ * frame drive it to `jointWorldMatrix · offset`, so the capsules track the
+ * animation and collide with the world.
+ *
+ * **Ragdoll** (`triggerRagdoll`): connect each capsule to its nearest
+ * capsule-bearing ancestor with a point joint (anchored at the shared joint), flip
+ * every capsule kinematic→dynamic, and stop the animation. Now physics drives the
+ * capsules; `reconcileRagdoll` writes each bone's pose *back* onto its skeleton
+ * joint (world → bone-local), so the skinned mesh goes limp and flops. (Anatomical
+ * cone limits + Jolt support are follow-ups; see physics/README.md.)
+ */
+
+/** Column-major rigid transform from a position + unit quaternion. */
+function compose(p: ArrayLike<number>, q: ArrayLike<number>): Mat4x4 {
+    return Mat4x4.multiply(Mat4x4.translation(p[0], p[1], p[2]), Quat.toMat4([q[0], q[1], q[2], q[3]]));
+}
+
+/** Orthonormalised rotation of a column-major matrix, as a 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];
+}
+
+interface SkinGeometry { _cpuSkin?: { positions: Float32Array; joints: Uint32Array; weights: Float32Array } | null; _skinInverseBindMatrices?: Float32Array | null }
+
+export const boneColliders = Database.Plugin.create({
+    extends: Database.Plugin.combine(physicsData, jointData, ragdollTrigger, pbrSkinning, modelLoader, transform),
+    components: {
+        _boneJoint: Entity.schema, // the skeleton joint this capsule tracks
+        _boneOffsetPos: Vec3.schema,     // capsule offset in the bone's bind-local frame
+        _boneOffsetRot: Quat.schema,
+        _ragdollBuilt: True.schema,      // tag: this skeleton's bone capsules have been generated
+    },
+    archetypes: {
+        // a kinematic capsule body bound to a skeleton joint (collisionGroup 1 ⇒ the
+        // ragdoll's bones never collide with each other, only the world)
+        BoneCapsule: ["bodyType", "colliderShape", "halfExtents", "material", "collisionGroup", "position", "rotation", "linearVelocity", "angularVelocity", "_boneJoint", "_boneOffsetPos", "_boneOffsetRot"],
+    },
+    systems: {
+        // Once a skeleton's skin has loaded, fit + spawn its bone capsules (one-time;
+        // tag + exclude). Tail→head since tagging the skeleton migrates its row.
+        generateBoneColliders: {
+            schedule: { during: ["postUpdate"] },
+            create: db => () => {
+                const material = (Object.values(db.store.resources.materials)[0] as Entity | undefined) ?? (0 as Entity);
+                for (const arch of db.store.queryArchetypes(["_skeletonJoints", "_skeletonGeometry"], { exclude: ["_ragdollBuilt"] })) {
+                    const ids = arch.columns.id, jc = arch.columns._skeletonJoints, gc = arch.columns._skeletonGeometry;
+                    for (let i = arch.rowCount - 1; i >= 0; i--) {
+                        const skeleton = ids.get(i), joints = jc.get(i), geo = gc.get(i);
+                        const g = db.store.read(geo) as SkinGeometry | null;
+                        if (!g?._cpuSkin || !g._skinInverseBindMatrices) continue; // skin not loaded yet
+                        for (const c of fitBoneCapsules({ jointCount: joints.length, inverseBindMatrices: g._skinInverseBindMatrices, skin: g._cpuSkin })) {
+                            db.store.archetypes.BoneCapsule.insert({
+                                bodyType: "kinematic", colliderShape: "capsule", halfExtents: [c.radius, c.halfHeight, 0], material, collisionGroup: 1,
+                                position: [0, 0, 0], rotation: [0, 0, 0, 1], linearVelocity: [0, 0, 0], angularVelocity: [0, 0, 0],
+                                _boneJoint: joints[c.jointIndex], _boneOffsetPos: c.offsetPosition, _boneOffsetRot: c.offsetRotation,
+                            });
+                        }
+                        db.store.update(skeleton, { _ragdollBuilt: true });
+                    }
+                }
+            },
+        },
+        // Alive: place every *kinematic* bone capsule at jointWorldMatrix · offset
+        // (the solver then kinematic-drives the engine body there). Dynamic capsules
+        // are ragdolling — physics owns them, so skip.
+        trackBoneColliders: {
+            schedule: { during: ["postUpdate"], after: ["generateBoneColliders", "transformSystem"] },
+            create: db => () => {
+                for (const arch of db.store.queryArchetypes(["_boneJoint", "_boneOffsetPos", "_boneOffsetRot", "bodyType", "position", "rotation"])) {
+                    const bj = arch.columns._boneJoint, op = arch.columns._boneOffsetPos, orot = arch.columns._boneOffsetRot, bt = arch.columns.bodyType;
+                    const posCol = arch.columns.position, rotCol = arch.columns.rotation;
+                    for (let i = 0; i < arch.rowCount; i++) {
+                        if (bt.get(i) === "dynamic") continue; // ragdolling — physics drives it
+                        const jw = db.store.get(bj.get(i), "_worldMatrix") as Mat4x4 | undefined;
+                        if (!jw) continue;
+                        posCol.set(i, Mat4x4.multiplyVec3(jw, op.get(i)));
+                        rotCol.set(i, Quat.multiply(rotationOf(jw), orot.get(i)));
+                    }
+                }
+            },
+        },
+        // On trigger: joint each capsule to its nearest capsule-bearing ancestor (at
+        // the shared joint point, anchors from the current pose), flip every capsule
+        // to dynamic, and stop the animation. The solver flips the engine bodies and
+        // mirrors the joints; the root capsule (no ancestor) falls free, dragging the rest.
+        ragdollOnTrigger: {
+            schedule: { during: ["postUpdate"], after: ["trackBoneColliders"] },
+            create: db => () => {
+                if (!db.store.resources._ragdollTrigger) return;
+                db.store.resources._ragdollTrigger = false;
+                // joint entity → its capsule + current world pose + rotation
+                const byJoint = new Map<Entity, { capsule: Entity; world: Mat4x4; rot: Quat }>();
+                for (const arch of db.store.queryArchetypes(["_boneJoint", "position", "rotation"])) {
+                    const ids = arch.columns.id, bj = arch.columns._boneJoint, pc = arch.columns.position, rc = arch.columns.rotation;
+                    for (let i = 0; i < arch.rowCount; i++) { const r = rc.get(i); byJoint.set(bj.get(i), { capsule: ids.get(i), world: compose(pc.get(i), r), rot: r }); }
+                }
+                for (const arch of db.store.queryArchetypes(["_boneJoint", "position", "rotation"])) {
+                    const ids = arch.columns.id, bj = arch.columns._boneJoint, pc = arch.columns.position, rc = arch.columns.rotation;
+                    for (let i = 0; i < arch.rowCount; i++) {
+                        const joint = bj.get(i);
+                        // nearest ancestor joint that has a capsule
+                        let pj = (db.store.get(joint, "parent") as Entity | undefined) ?? (0 as Entity);
+                        while (pj && !byJoint.has(pj)) pj = (db.store.get(pj, "parent") as Entity | undefined) ?? (0 as Entity);
+                        const parent = pj ? byJoint.get(pj) : undefined;
+                        if (!parent) continue; // root capsule: unconstrained
+                        const jw = db.store.get(joint, "_worldMatrix") as Mat4x4 | undefined;
+                        const origin: Vec3 = jw ? [jw[12], jw[13], jw[14]] : [pc.get(i)[0], pc.get(i)[1], pc.get(i)[2]];
+                        const childRot = rc.get(i);
+                        const childWorld = compose(pc.get(i), childRot);
+                        // cone reference = the child bone's current axis (its capsule +Y), in the
+                        // parent's frame; the swing-twist joint then limits how far the bone can
+                        // deviate from this rest pose — anatomical limits, not a free ball.
+                        const boneDirWorld = Quat.rotateVec3(childRot, [0, 1, 0]);
+                        const axis = Quat.rotateVec3(Quat.inverse(parent.rot), boneDirWorld);
+                        db.store.archetypes.Joint.insert({
+                            jointType: "cone", jointBodyA: parent.capsule, jointBodyB: ids.get(i),
+                            jointAnchorA: Mat4x4.multiplyVec3(Mat4x4.inverse(parent.world), origin),
+                            jointAnchorB: Mat4x4.multiplyVec3(Mat4x4.inverse(childWorld), origin),
+                            jointAxis: axis, jointMinLimit: -0.5, jointMaxLimit: 0.5, jointSwingLimit: 0.9, // ~±29° twist, ~52° swing cone
+                        });
+                    }
+                }
+                for (const arch of db.store.queryArchetypes(["_boneJoint", "bodyType"])) {
+                    const ids = arch.columns.id;
+                    for (let i = 0; i < arch.rowCount; i++) db.store.update(ids.get(i), { bodyType: "dynamic" });
+                }
+                for (const arch of db.store.queryArchetypes(["animationPlaying"])) {
+                    const ids = arch.columns.id;
+                    for (let i = 0; i < arch.rowCount; i++) db.store.update(ids.get(i), { animationPlaying: false });
+                }
+            },
+        },
+        // Ragdolling: write each dynamic bone capsule's pose back onto its skeleton
+        // joint as a local TRS (jointWorld = capsuleWorld · offset⁻¹, then relative to
+        // the parent's world), so the skinned mesh follows the physics. Two passes so
+        // a child uses its parent's *capsule-derived* world, keeping the chain consistent.
+        reconcileRagdoll: {
+            schedule: { during: ["preRender"], after: ["transformSystem"] },
+            create: db => () => {
+                const jointWorld = new Map<Entity, Mat4x4>();
+                for (const arch of db.store.queryArchetypes(["_boneJoint", "_boneOffsetPos", "_boneOffsetRot", "bodyType", "position", "rotation"])) {
+                    const bj = arch.columns._boneJoint, op = arch.columns._boneOffsetPos, orot = arch.columns._boneOffsetRot, bt = arch.columns.bodyType, pc = arch.columns.position, rc = arch.columns.rotation;
+                    for (let i = 0; i < arch.rowCount; i++) {
+                        if (bt.get(i) !== "dynamic") continue;
+                        jointWorld.set(bj.get(i), Mat4x4.multiply(compose(pc.get(i), rc.get(i)), Mat4x4.inverse(compose(op.get(i), orot.get(i)))));
+                    }
+                }
+                if (jointWorld.size === 0) return;
+                for (const [joint, jw] of jointWorld) {
+                    const parent = (db.store.get(joint, "parent") as Entity | undefined) ?? (0 as Entity);
+                    const parentW = jointWorld.get(parent) ?? (parent ? db.store.get(parent, "_worldMatrix") as Mat4x4 | undefined : undefined) ?? Mat4x4.identity;
+                    const local = Mat4x4.multiply(Mat4x4.inverse(parentW), jw);
+                    db.store.update(joint, { position: [local[12], local[13], local[14]], rotation: rotationOf(local) });
+                }
+            },
+        },
+    },
+});

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

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { Vec3, Quat } from "@adobe/data/math";
+
+/**
+ * The **display transform** seam — the pose a renderer should actually draw at,
+ * which may differ from the canonical `position`/`rotation` (the authoritative
+ * gameplay/sim state). When physics runs on a fixed clock faster or slower than
+ * the render rate, an interpolation pass writes the blended prev→current pose
+ * here each render frame so motion stays smooth; gameplay still reads the
+ * canonical pose.
+ *
+ * Both `_`-prefixed (derived, not authored). A renderer reads `_renderPosition`/
+ * `_renderRotation` *when present* and otherwise falls back to the canonical
+ * `position`/`rotation` — so this plugin is a pure, physics-free dependency:
+ * graphics-only scenes register the components (harmless, unused) and bodies that
+ * nothing interpolates simply never gain them. The producer is
+ * `interpolation-plugin` (physics → display); the consumer is any renderer.
+ */
+export const displayTransform = Database.Plugin.create({
+    components: {
+        _renderPosition: Vec3.schema, // derived: interpolated pose to render at (else use `position`)
+        _renderRotation: Quat.schema,
+    },
+});

package/src/graphics/rendering/ibl-render/brdf.wgsl.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+// Shared WGSL fragment: Cook-Torrance metallic-roughness BRDF building blocks.
+// Concatenated into the direct and (future) IBL shader modules so both paths
+// agree on the math.
+
+export default /* wgsl */ `
+const PI: f32 = 3.14159265359;
+const MIN_ROUGHNESS: f32 = 0.04;
+
+// Trowbridge-Reitz / GGX normal distribution.
+fn d_ggx(nDotH: f32, alpha: f32) -> f32 {
+    let a2 = alpha * alpha;
+    let denom = nDotH * nDotH * (a2 - 1.0) + 1.0;
+    return a2 / (PI * denom * denom);
+}
+
+// Smith G with Schlick-GGX.
+fn g_smith(nDotV: f32, nDotL: f32, alpha: f32) -> f32 {
+    let k = (alpha + 1.0) * (alpha + 1.0) / 8.0;
+    let gv = nDotV / (nDotV * (1.0 - k) + k);
+    let gl = nDotL / (nDotL * (1.0 - k) + k);
+    return gv * gl;
+}
+
+// Schlick Fresnel.
+fn f_schlick(vDotH: f32, f0: vec3f) -> vec3f {
+    let f = pow(clamp(1.0 - vDotH, 0.0, 1.0), 5.0);
+    return f0 + (vec3f(1.0) - f0) * f;
+}
+
+// Roughness-aware Schlick for IBL: avoids over-strong rim at high roughness.
+fn f_schlick_roughness(nDotV: f32, f0: vec3f, roughness: f32) -> vec3f {
+    let r = vec3f(1.0 - roughness);
+    return f0 + (max(r, f0) - f0) * pow(max(1.0 - nDotV, 0.0), 5.0);
+}
+
+// Narkowicz ACES filmic tonemap fit. Cheap, looks clearly filmic.
+fn tone_map_aces(x: vec3f) -> vec3f {
+    let a = 2.51; let b = 0.03; let c = 2.43; let d = 0.59; let e = 0.14;
+    return clamp((x * (a * x + b)) / (x * (c * x + d) + e), vec3f(0.0), vec3f(1.0));
+}
+`;

package/src/graphics/rendering/ibl-render/ibl/brdf-lut.ts

@@ -0,0 +1,101 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import iblMath from "./ibl-math.wgsl.js";
+import { FULLSCREEN_VS } from "./render-helpers.js";
+
+// Karis split-sum BRDF integration. Encodes the F0-independent part of the
+// specular IBL integral. Lookup is (NdotV, roughness) → (scale, bias) such
+// that specular_IBL = prefiltered * (F0 * scale + bias).
+const BRDF_LUT_FS = /* wgsl */ `
+struct Params { size: u32, _pad: u32, _pad2: u32, _pad3: u32 };
+@group(0) @binding(0) var<uniform> params: Params;
+
+const SAMPLES: u32 = 1024u;
+
+fn integrate(nDotV: f32, roughness: f32) -> vec2f {
+    let V = vec3f(sqrt(1.0 - nDotV * nDotV), 0.0, nDotV);
+    // N = (0,0,1): work directly in tangent space. importance_sample_ggx's
+    // TBN frame degenerates when N=(0,0,1), so we sample H inline here.
+    let a = roughness * roughness;
+
+    var A = 0.0;
+    var B = 0.0;
+    for (var i = 0u; i < SAMPLES; i = i + 1u) {
+        let xi = hammersley(i, SAMPLES);
+        let phi = 2.0 * PI * xi.x;
+        let cosTheta = sqrt((1.0 - xi.y) / (1.0 + (a * a - 1.0) * xi.y));
+        let sinTheta = sqrt(1.0 - cosTheta * cosTheta);
+        let H = vec3f(cos(phi) * sinTheta, sin(phi) * sinTheta, cosTheta);
+        let L = normalize(2.0 * dot(V, H) * H - V);
+        let nDotL = max(L.z, 0.0);
+        let nDotH = max(H.z, 0.0);
+        let vDotH = max(dot(V, H), 0.0);
+        if (nDotL > 0.0) {
+            let G = g_smith_ibl(nDotV, nDotL, roughness);
+            let g_vis = (G * vDotH) / max(nDotH * nDotV, 0.0001);
+            let fc = pow(1.0 - vDotH, 5.0);
+            A = A + (1.0 - fc) * g_vis;
+            B = B + fc * g_vis;
+        }
+    }
+    return vec2f(A, B) / f32(SAMPLES);
+}
+
+@fragment
+fn fs_main(@builtin(position) frag: vec4f) -> @location(0) vec4f {
+    let uv = frag.xy / f32(params.size);
+    let nDotV = max(uv.x, 0.001);
+    let roughness = max(uv.y, 0.04);
+    let r = integrate(nDotV, roughness);
+    return vec4f(r, 0.0, 1.0);
+}
+`;
+
+export function generateBrdfLut(
+    device: GPUDevice,
+    encoder: GPUCommandEncoder,
+    size = 256,
+): GPUTexture {
+    const format: GPUTextureFormat = "rgba16float";
+    const texture = device.createTexture({
+        size: [size, size, 1],
+        format,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
+    });
+
+    const module = device.createShaderModule({ code: FULLSCREEN_VS + iblMath + BRDF_LUT_FS });
+    const bindGroupLayout = device.createBindGroupLayout({
+        entries: [{ binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }],
+    });
+    const pipeline = device.createRenderPipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
+        vertex: { module, entryPoint: "vs_fullscreen" },
+        fragment: { module, entryPoint: "fs_main", targets: [{ format }] },
+        primitive: { topology: "triangle-list" },
+    });
+
+    const ub = device.createBuffer({
+        size: 16,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+    device.queue.writeBuffer(ub, 0, new Uint32Array([size, 0, 0, 0]));
+    const bindGroup = device.createBindGroup({
+        layout: bindGroupLayout,
+        entries: [{ binding: 0, resource: { buffer: ub } }],
+    });
+
+    const pass = encoder.beginRenderPass({
+        colorAttachments: [{
+            view: texture.createView(),
+            loadOp: "clear",
+            storeOp: "store",
+            clearValue: [0, 0, 0, 1],
+        }],
+    });
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.draw(3);
+    pass.end();
+
+    return texture;
+}

package/src/graphics/rendering/ibl-render/ibl/build-ibl-resources.ts

@@ -0,0 +1,57 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { generateBrdfLut } from "./brdf-lut.js";
+import { generateEnvironment } from "./environment.js";
+import { generateIrradiance } from "./irradiance.js";
+import type { ParsedHdr } from "./parse-hdr.js";
+import { generatePrefiltered } from "./prefilter.js";
+
+export interface IblResources {
+    environment: GPUTexture;
+    irradiance: GPUTexture;
+    prefiltered: GPUTexture;
+    prefilteredMipCount: number;
+    brdfLut: GPUTexture;
+}
+
+export interface IblOptions {
+    environmentSize?: number;
+    irradianceSize?: number;
+    prefilteredSize?: number;
+    prefilteredMipCount?: number;
+    brdfLutSize?: number;
+    /** Equirectangular HDR source. When omitted, a procedural studio is used. */
+    hdrSource?: ParsedHdr;
+}
+
+/**
+ * Computes the four IBL maps used by the prefiltered split-sum approximation:
+ * source environment, diffuse irradiance, specular prefiltered (mip chain by
+ * roughness), and the BRDF integration LUT. Everything runs in one command
+ * buffer; the GPU sequences the dependencies internally.
+ */
+export function buildIblResources(device: GPUDevice, options: IblOptions = {}): IblResources {
+    const envSize = options.environmentSize ?? 512;
+    const irradianceSize = options.irradianceSize ?? 32;
+    const prefilteredSize = options.prefilteredSize ?? 256;
+    const prefilteredMipCount = options.prefilteredMipCount ?? 7;
+    const brdfLutSize = options.brdfLutSize ?? 256;
+
+    const encoder = device.createCommandEncoder({ label: "ibl-precompute" });
+    const environment = generateEnvironment(device, encoder, envSize, options.hdrSource);
+    const irradiance = generateIrradiance(device, encoder, environment, irradianceSize);
+    const prefiltered = generatePrefiltered(device, encoder, environment, prefilteredSize, prefilteredMipCount);
+    device.queue.submit([encoder.finish()]);
+
+    const brdfEncoder = device.createCommandEncoder({ label: "ibl-brdf-lut" });
+    const brdfLut = generateBrdfLut(device, brdfEncoder, brdfLutSize);
+    device.queue.submit([brdfEncoder.finish()]);
+
+    return {
+        environment,
+        irradiance,
+        prefiltered: prefiltered.texture,
+        prefilteredMipCount: prefiltered.mipLevelCount,
+        brdfLut,
+    };
+}

package/src/graphics/rendering/ibl-render/ibl/create-cubemap.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export function createCubemap(
+    device: GPUDevice,
+    size: number,
+    format: GPUTextureFormat,
+    mipLevelCount = 1,
+): GPUTexture {
+    return device.createTexture({
+        size: [size, size, 6],
+        format,
+        mipLevelCount,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_DST,
+        dimension: "2d",
+        textureBindingViewDimension: "cube",
+    });
+}

package/src/graphics/rendering/ibl-render/ibl/cube-face-view.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export function cubeFaceView(texture: GPUTexture, face: number, mip = 0): GPUTextureView {
+    return texture.createView({
+        dimension: "2d",
+        baseArrayLayer: face,
+        arrayLayerCount: 1,
+        baseMipLevel: mip,
+        mipLevelCount: 1,
+    });
+}

package/src/graphics/rendering/ibl-render/ibl/cubemap-sample-view.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export function cubemapSampleView(texture: GPUTexture): GPUTextureView {
+    return texture.createView({
+        dimension: "cube",
+        baseArrayLayer: 0,
+        arrayLayerCount: 6,
+    });
+}

package/src/graphics/rendering/ibl-render/ibl/environment.ts

@@ -0,0 +1,190 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { floatArrayToHalf } from "./float-to-half.js";
+import iblMath from "./ibl-math.wgsl.js";
+import type { ParsedHdr } from "./parse-hdr.js";
+import { createCubemap, cubeFaceView, FULLSCREEN_VS } from "./render-helpers.js";
+
+const ENV_PROCEDURAL_FS = /* wgsl */ `
+struct Params { face: u32, size: u32 };
+@group(0) @binding(0) var<uniform> params: Params;
+
+fn env_color(dir: vec3f) -> vec3f {
+    let sky_top = vec3f(0.45, 0.55, 0.75);
+    let horizon = vec3f(0.18, 0.20, 0.24);
+    let ground  = vec3f(0.08, 0.08, 0.10);
+    var color = mix(horizon, sky_top, smoothstep(-0.05, 0.65, dir.y));
+    color = mix(ground, color, smoothstep(-0.3, 0.0, dir.y));
+
+    let warm = vec3f(9.0, 7.2, 5.0);
+    let cool = vec3f(5.0, 7.5, 10.0);
+    for (var i = 0u; i < 4u; i = i + 1u) {
+        let a = f32(i) * 1.5707963;
+        let ld = normalize(vec3f(sin(a) * 0.55, 0.85, cos(a) * 0.55));
+        let d = max(dot(dir, ld), 0.0);
+        let intensity = pow(d, 96.0);
+        let lc = select(warm, cool, i % 2u == 0u);
+        color = color + intensity * lc;
+    }
+    return color;
+}
+
+@fragment
+fn fs_main(@builtin(position) frag: vec4f) -> @location(0) vec4f {
+    let uv = frag.xy / f32(params.size);
+    let dir = cube_uv_to_dir(params.face, uv);
+    return vec4f(env_color(dir), 1.0);
+}
+`;
+
+const ENV_EQUIRECT_FS = /* wgsl */ `
+struct Params { face: u32, size: u32 };
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var equirect: texture_2d<f32>;
+@group(0) @binding(2) var equirectSampler: sampler;
+
+fn dir_to_equirect_uv(d: vec3f) -> vec2f {
+    let theta = atan2(d.z, d.x);
+    let phi = asin(clamp(d.y, -1.0, 1.0));
+    return vec2f((theta + PI) / (2.0 * PI), 0.5 - phi / PI);
+}
+
+@fragment
+fn fs_main(@builtin(position) frag: vec4f) -> @location(0) vec4f {
+    let uv = frag.xy / f32(params.size);
+    let dir = cube_uv_to_dir(params.face, uv);
+    let env_uv = dir_to_equirect_uv(dir);
+    return textureSampleLevel(equirect, equirectSampler, env_uv, 0.0);
+}
+`;
+
+function uploadHdrAsTexture(device: GPUDevice, hdr: ParsedHdr): GPUTexture {
+    const halfData = floatArrayToHalf(hdr.rgba);
+    const texture = device.createTexture({
+        size: [hdr.width, hdr.height, 1],
+        format: "rgba16float",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    });
+    device.queue.writeTexture(
+        { texture },
+        halfData.buffer,
+        { bytesPerRow: hdr.width * 8 },
+        [hdr.width, hdr.height, 1],
+    );
+    return texture;
+}
+
+function makeProceduralPipeline(device: GPUDevice, format: GPUTextureFormat) {
+    const module = device.createShaderModule({ code: FULLSCREEN_VS + iblMath + ENV_PROCEDURAL_FS });
+    const bindGroupLayout = device.createBindGroupLayout({
+        entries: [{ binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }],
+    });
+    const pipeline = device.createRenderPipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
+        vertex: { module, entryPoint: "vs_fullscreen" },
+        fragment: { module, entryPoint: "fs_main", targets: [{ format }] },
+        primitive: { topology: "triangle-list" },
+    });
+    return { pipeline, bindGroupLayout };
+}
+
+function makeEquirectPipeline(device: GPUDevice, format: GPUTextureFormat) {
+    const module = device.createShaderModule({ code: FULLSCREEN_VS + iblMath + ENV_EQUIRECT_FS });
+    const bindGroupLayout = device.createBindGroupLayout({
+        entries: [
+            { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+            { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
+            { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+        ],
+    });
+    const pipeline = device.createRenderPipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
+        vertex: { module, entryPoint: "vs_fullscreen" },
+        fragment: { module, entryPoint: "fs_main", targets: [{ format }] },
+        primitive: { topology: "triangle-list" },
+    });
+    return { pipeline, bindGroupLayout };
+}
+
+/**
+ * Renders an environment cubemap. With no `hdr` source it falls back to the
+ * built-in procedural studio. Pass a parsed Radiance HDR for a real photoreal
+ * environment — used by the IBL plugin to enable Babylon-style glossy
+ * reflections.
+ */
+export function generateEnvironment(
+    device: GPUDevice,
+    encoder: GPUCommandEncoder,
+    size: number,
+    hdr?: ParsedHdr,
+): GPUTexture {
+    const format: GPUTextureFormat = "rgba16float";
+    const texture = createCubemap(device, size, format, 1);
+
+    if (hdr) {
+        const equirectTexture = uploadHdrAsTexture(device, hdr);
+        const sampler = device.createSampler({
+            magFilter: "linear",
+            minFilter: "linear",
+            addressModeU: "repeat",
+            addressModeV: "clamp-to-edge",
+        });
+        const { pipeline, bindGroupLayout } = makeEquirectPipeline(device, format);
+        const equirectView = equirectTexture.createView();
+
+        for (let face = 0; face < 6; face++) {
+            const ub = device.createBuffer({
+                size: 16,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(ub, 0, new Uint32Array([face, size, 0, 0]));
+            const bindGroup = device.createBindGroup({
+                layout: bindGroupLayout,
+                entries: [
+                    { binding: 0, resource: { buffer: ub } },
+                    { binding: 1, resource: equirectView },
+                    { binding: 2, resource: sampler },
+                ],
+            });
+            const pass = encoder.beginRenderPass({
+                colorAttachments: [{
+                    view: cubeFaceView(texture, face, 0),
+                    loadOp: "clear",
+                    storeOp: "store",
+                    clearValue: [0, 0, 0, 1],
+                }],
+            });
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bindGroup);
+            pass.draw(3);
+            pass.end();
+        }
+        return texture;
+    }
+
+    const { pipeline, bindGroupLayout } = makeProceduralPipeline(device, format);
+    for (let face = 0; face < 6; face++) {
+        const ub = device.createBuffer({
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        device.queue.writeBuffer(ub, 0, new Uint32Array([face, size, 0, 0]));
+        const bindGroup = device.createBindGroup({
+            layout: bindGroupLayout,
+            entries: [{ binding: 0, resource: { buffer: ub } }],
+        });
+        const pass = encoder.beginRenderPass({
+            colorAttachments: [{
+                view: cubeFaceView(texture, face, 0),
+                loadOp: "clear",
+                storeOp: "store",
+                clearValue: [0, 0, 0, 1],
+            }],
+        });
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.draw(3);
+        pass.end();
+    }
+    return texture;
+}