@jgengine/shell 0.19.0 → 0.22.0

package/dist/materialOverride.js

@@ -1,50 +1,106 @@
 import * as THREE from "three";
+/** Physical texture roles mapped to the pinned Three renderer's native properties. @internal */
+export const MATERIAL_TEXTURE_PROPERTIES = {
+    color: "map", normal: "normalMap", roughness: "roughnessMap", ao: "aoMap", metalness: "metalnessMap", emissive: "emissiveMap", height: "displacementMap", alpha: "alphaMap",
+    sheenColor: "sheenColorMap", sheenRoughness: "sheenRoughnessMap", anisotropy: "anisotropyMap", clearcoat: "clearcoatMap", clearcoatRoughness: "clearcoatRoughnessMap", clearcoatNormal: "clearcoatNormalMap", specularIntensity: "specularIntensityMap", specularColor: "specularColorMap", transmission: "transmissionMap", thickness: "thicknessMap", iridescence: "iridescenceMap", iridescenceThickness: "iridescenceThicknessMap",
+};
+const physicalNumbers = ["sheen", "sheenRoughness", "anisotropy", "anisotropyRotation", "clearcoat", "clearcoatRoughness", "ior", "specularIntensity", "transmission", "thickness", "attenuationDistance", "iridescence", "iridescenceIOR"];
+const physicalColors = ["sheenColor", "specularColor", "attenuationColor"];
+/** Whether authored settings require a physical shader; ordinary PBR stays standard. @internal */
+export function requiresPhysicalMaterial(override, textures) {
+    return [...physicalNumbers, ...physicalColors, "iridescenceThicknessRange"].some(key => override[key] !== undefined) || Object.keys(textures ?? {}).some(key => ["sheenColor", "sheenRoughness", "anisotropy", "clearcoat", "clearcoatRoughness", "clearcoatNormal", "specularIntensity", "specularColor", "transmission", "thickness", "iridescence", "iridescenceThickness"].includes(key));
+}
 /** @internal */
 export function applyMaterialOverride(root, override, options) {
     const clone = options?.clone !== false;
     const textures = options?.textures;
+    const applied = new Map();
+    const apply = (material) => {
+        const cached = applied.get(material);
+        if (cached !== undefined)
+            return cached;
+        const target = applyMaterialOverrideToMaterial(material, override, clone, textures);
+        applied.set(material, target);
+        if (target !== material)
+            options?.ownMaterial?.(target);
+        return target;
+    };
     root.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
-        mesh.material = Array.isArray(mesh.material)
-            ? mesh.material.map((material) => overrideOne(material, override, clone, textures))
-            : overrideOne(mesh.material, override, clone, textures);
+        mesh.material = Array.isArray(mesh.material) ? mesh.material.map(apply) : apply(mesh.material);
     });
 }
-function overrideOne(material, override, clone, textures) {
+/** Apply the shared override contract to one material. @internal */
+export function applyMaterialOverrideToMaterial(material, override, clone, textures) {
     if (!isStandardOrPhysicalMaterial(material))
         return material;
-    const target = clone ? material.clone() : material;
-    if (override.color !== undefined)
-        target.color.set(override.color);
-    if (override.metalness !== undefined)
-        target.metalness = override.metalness;
-    if (override.roughness !== undefined)
-        target.roughness = override.roughness;
-    if (override.emissive !== undefined)
-        target.emissive.set(override.emissive);
-    if (override.emissiveIntensity !== undefined)
-        target.emissiveIntensity = override.emissiveIntensity;
-    if (textures?.color !== undefined)
-        target.map = textures.color;
-    if (textures?.normal !== undefined)
-        target.normalMap = textures.normal;
-    if (textures?.roughness !== undefined)
-        target.roughnessMap = textures.roughness;
-    if (textures?.ao !== undefined)
-        target.aoMap = textures.ao;
-    if (textures?.metalness !== undefined)
-        target.metalnessMap = textures.metalness;
-    if (textures?.emissive !== undefined)
-        target.emissiveMap = textures.emissive;
-    if (textures?.height !== undefined)
-        target.displacementMap = textures.height;
-    if (textures !== undefined)
-        target.needsUpdate = true;
-    if (override.rim !== undefined)
-        applyRimLight(target, override.rim);
-    return target;
+    const promote = requiresPhysicalMaterial(override, textures) && !material.isMeshPhysicalMaterial;
+    const target = promote ? new THREE.MeshPhysicalMaterial() : clone ? material.clone() : material;
+    try {
+        if (promote)
+            THREE.MeshStandardMaterial.prototype.copy.call(target, material);
+        if (clone || promote) {
+            target.onBeforeCompile = material.onBeforeCompile;
+            target.customProgramCacheKey = material.customProgramCacheKey;
+        }
+        if (override.color !== undefined)
+            target.color.set(override.color);
+        if (override.metalness !== undefined)
+            target.metalness = override.metalness;
+        if (override.roughness !== undefined)
+            target.roughness = override.roughness;
+        if (override.emissive !== undefined)
+            target.emissive.set(override.emissive);
+        if (override.emissiveIntensity !== undefined)
+            target.emissiveIntensity = override.emissiveIntensity;
+        if (override.normalScale !== undefined)
+            target.normalScale.set(...override.normalScale);
+        const physical = target;
+        for (const key of physicalNumbers)
+            if (override[key] !== undefined)
+                physical[key] = override[key];
+        for (const key of physicalColors)
+            if (override[key] !== undefined)
+                physical[key].set(override[key]);
+        if (override.iridescenceThicknessRange !== undefined)
+            physical.iridescenceThicknessRange = [...override.iridescenceThicknessRange];
+        if (override.alphaMode !== undefined) {
+            target.transparent = override.alphaMode === "blend";
+            target.alphaTest = override.alphaMode === "mask" ? override.alphaCutoff ?? 0.5 : 0;
+            target.depthWrite = override.alphaMode !== "blend";
+        }
+        else if (override.alphaCutoff !== undefined)
+            target.alphaTest = override.alphaCutoff;
+        if (override.opacity !== undefined)
+            target.opacity = override.opacity;
+        if (override.doubleSided !== undefined)
+            target.side = override.doubleSided ? THREE.DoubleSide : THREE.FrontSide;
+        for (const [role, texture] of Object.entries(textures ?? {})) {
+            const property = MATERIAL_TEXTURE_PROPERTIES[role];
+            if (property !== undefined)
+                target[property] = texture;
+        }
+        if (textures !== undefined)
+            target.needsUpdate = true;
+        if (override.rim !== undefined)
+            applyRimLight(target, override.rim);
+        if (override.alphaMode !== undefined || override.doubleSided !== undefined)
+            target.needsUpdate = true;
+        return target;
+    }
+    catch (error) {
+        if (target !== material) {
+            try {
+                target.dispose();
+            }
+            finally {
+                throw error;
+            }
+        }
+        throw error;
+    }
 }
 function isStandardOrPhysicalMaterial(material) {
     return material.isMeshStandardMaterial === true;
@@ -60,7 +116,10 @@ function applyRimLight(target, rim) {
     const power = rim.power ?? 2.5;
     if (strength <= 0)
         return;
-    target.onBeforeCompile = (shader) => {
+    const previousCompile = target.onBeforeCompile;
+    const previousKey = target.customProgramCacheKey();
+    target.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(target, shader, renderer);
         shader.uniforms.uJgRimColor = { value: color };
         shader.uniforms.uJgRimStrength = { value: strength };
         shader.uniforms.uJgRimPower = { value: power };
@@ -74,6 +133,6 @@ outgoingLight += uJgRimColor * jgRim * uJgRimStrength;
 #include <opaque_fragment>`);
     };
     // Two materials differing only in rim tuning must not share a compiled program.
-    target.customProgramCacheKey = () => `jgengine-rim-${rim.color ?? "#ffffff"}-${strength}-${power}`;
+    target.customProgramCacheKey = () => `${previousKey}|jgengine-rim-${rim.color ?? "#ffffff"}-${strength}-${power}`;
     target.needsUpdate = true;
 }

package/dist/multiplayer.d.ts

@@ -1,5 +1,8 @@
 import type { GameDefinition } from "@jgengine/core/game/defineGame";
 import type { MultiplayerSession } from "@jgengine/core/runtime/transport";
+import { type HostedWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
+import type { PlayableGame } from "./registry.js";
+import { type PeerHost, type PeerHostOptions, type PeerGuest, type PeerGuestOptions, type PeerSignaling } from "@jgengine/ws/peer";
 export type ShellMultiplayer = MultiplayerSession;
 export declare const DEFAULT_FEED_ACTIONS: string[];
 export declare function randomPlayerId(): string;
@@ -12,12 +15,39 @@ export type ResolveShellMultiplayerArgs = {
     feedActions?: string[];
 };
 export declare function resolveShellMultiplayer(args: ResolveShellMultiplayerArgs): ShellMultiplayer | null;
-export declare function resolvePeerShellMultiplayer(args: {
+/** Alternate peer factories for hosts that provide their own WebRTC implementation or transport pipe. */
+export interface PeerShellFactories {
+    host(options: PeerHostOptions): PeerHost;
+    guest(options: PeerGuestOptions): PeerGuest;
+}
+/** Peer bootstrap options; passing a playable hosts its authoritative GameContext world. */
+export interface ResolvePeerShellMultiplayerArgs {
     gameId: string;
     role: "host" | "join";
     room?: string;
     userId?: string;
     feedActions?: string[];
-}): Promise<ShellMultiplayer & {
-    close: () => void;
+    /** Requires an adapter with `authority: "server"`; joiners mount the same playable. */
+    playable?: PlayableGame;
+    /** Maximum active players in the authoritative world, including the host player. */
+    slotsPerServer?: number;
+    /** Authoritative tick interval in milliseconds; defaults to 1000 / 30. */
+    tickMs?: number;
+    /** Minimum automatic save interval; joins, commands and close still save immediately. Defaults to 1000 ms. */
+    saveIntervalMs?: number;
+    /** Persistence for the authoritative host world; defaults to an in-memory store. */
+    store?: HostedWorldStore;
+    /** Signaling ownership transfers to the returned session, which closes it on teardown. */
+    signaling?: PeerSignaling;
+    peers?: PeerShellFactories;
+    /** Inject host scheduling; the returned cancellation is called before transport teardown. */
+    scheduleTicks?: (tick: () => void, intervalMs: number) => () => void;
+}
+/**
+ * Opens a peer session. With `playable`, one host runs the game loop and guests mirror its shared world.
+ * Await `close()` to finish authoritative persistence. Same-origin rooms use BroadcastChannel signaling.
+ * @capability multiplayer-p2p bootstrap a playable authoritative world for browser peer co-op
+ */
+export declare function resolvePeerShellMultiplayer(args: ResolvePeerShellMultiplayerArgs): Promise<ShellMultiplayer & {
+    close: () => Promise<void>;
 }>;

package/dist/multiplayer.js

@@ -1,4 +1,6 @@
 import { adapterOf, isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { createHostedWorldSession, createHostedWorldSessionAsync } from "@jgengine/core/runtime/hostedWorldSession";
+import { createWorldGameHost } from "@jgengine/ws/worldHost";
 import { createWsBackend } from "@jgengine/ws/createWsBackend";
 import { announcePeerHost, broadcastChannelSignaling, createPeerGuest, createPeerHost, joinPeerSession, } from "@jgengine/ws/peer";
 export const DEFAULT_FEED_ACTIONS = ["entity.died"];
@@ -47,35 +49,116 @@ export function resolveShellMultiplayer(args) {
         `so the game shipped single-player. Wire up the ${adapter.kind} transport or switch to ws()/lan().`);
     return null;
 }
+/**
+ * Opens a peer session. With `playable`, one host runs the game loop and guests mirror its shared world.
+ * Await `close()` to finish authoritative persistence. Same-origin rooms use BroadcastChannel signaling.
+ * @capability multiplayer-p2p bootstrap a playable authoritative world for browser peer co-op
+ */
 export async function resolvePeerShellMultiplayer(args) {
+    if (args.playable !== undefined && !isServerAuthoritative(args.playable.game.multiplayer)) {
+        throw new Error("playable peer worlds require authority: server");
+    }
+    const tickMs = args.tickMs ?? 1000 / 30;
+    if (!Number.isFinite(tickMs) || tickMs <= 0 || tickMs > 1000)
+        throw new Error("tickMs must be greater than zero and at most 1000");
+    const saveIntervalMs = args.saveIntervalMs ?? 1000;
+    if (!Number.isFinite(saveIntervalMs) || saveIntervalMs < 0)
+        throw new Error("saveIntervalMs must be nonnegative and finite");
     const userId = args.userId ?? randomPlayerId();
     const feedActions = args.feedActions ?? DEFAULT_FEED_ACTIONS;
-    const signaling = broadcastChannelSignaling(args.room ?? `jg-p2p-${args.gameId}`);
+    const signaling = args.signaling ?? broadcastChannelSignaling(args.room ?? `jg-p2p-${args.gameId}`);
+    const peers = args.peers ?? { host: createPeerHost, guest: createPeerGuest };
     if (args.role === "host") {
-        const peerHost = createPeerHost({ userId });
-        const stopAnnouncing = announcePeerHost(peerHost, signaling);
+        let closed = false;
+        let activeSession = null;
+        let host;
+        let cancelTicks = () => { };
+        let stopAnnouncing = () => { };
+        let peerHost;
+        let closing = null;
+        try {
+            if (args.playable !== undefined) {
+                const playable = args.playable;
+                let loading = null;
+                host = createWorldGameHost({
+                    slotsPerServer: args.slotsPerServer,
+                    session({ gameId, serverId }) {
+                        if (closed || gameId !== args.gameId || serverId !== args.gameId)
+                            return null;
+                        if (loading === null) {
+                            const attempt = args.store === undefined
+                                ? Promise.resolve(createHostedWorldSession({ definition: playable.game, content: playable.content, host: { userId, isNew: true }, saveIntervalMs }))
+                                : createHostedWorldSessionAsync({ definition: playable.game, content: playable.content, host: { userId, isNew: true }, store: args.store, saveIntervalMs });
+                            loading = attempt;
+                            void attempt.catch(() => { if (loading === attempt)
+                                loading = null; });
+                        }
+                        return loading.then(session => { activeSession = session; return session; });
+                    },
+                });
+            }
+            peerHost = peers.host({ userId, ...(host === undefined ? {} : { host }) });
+            stopAnnouncing = announcePeerHost(peerHost, signaling);
+            if (host !== undefined) {
+                const worldHost = host;
+                const tick = () => { if (!closed && activeSession !== null && activeSession.members().length > 0)
+                    worldHost.tick(tickMs / 1000); };
+                cancelTicks = args.scheduleTicks?.(tick, tickMs) ?? (() => {
+                    const timer = setInterval(tick, tickMs);
+                    return () => clearInterval(timer);
+                })();
+            }
+            const resolvedPeerHost = peerHost;
+            return {
+                gameId: args.gameId, userId, backend: resolvedPeerHost.backend, feedActions,
+                close() {
+                    if (closing !== null)
+                        return closing;
+                    closed = true;
+                    cancelTicks();
+                    stopAnnouncing();
+                    signaling.close();
+                    resolvedPeerHost.close();
+                    closing = resolvedPeerHost.router.drain().then(async () => {
+                        if (host !== undefined)
+                            await host.stop();
+                    });
+                    return closing;
+                },
+            };
+        }
+        catch (error) {
+            closed = true;
+            cancelTicks();
+            stopAnnouncing();
+            signaling.close();
+            peerHost?.close();
+            await peerHost?.router.drain();
+            if (host !== undefined)
+                await host.stop();
+            throw error;
+        }
+    }
+    let guest;
+    try {
+        guest = peers.guest({ userId });
+        const backend = await joinPeerSession(guest, signaling);
+        const resolvedGuest = guest;
+        let closed = false;
         return {
-            gameId: args.gameId,
-            userId,
-            backend: peerHost.backend,
-            feedActions,
-            close: () => {
-                stopAnnouncing();
+            gameId: args.gameId, userId, backend, feedActions,
+            async close() {
+                if (closed)
+                    return;
+                closed = true;
                 signaling.close();
-                peerHost.close();
+                resolvedGuest.close();
             },
         };
     }
-    const guest = createPeerGuest({ userId });
-    const backend = await joinPeerSession(guest, signaling);
-    return {
-        gameId: args.gameId,
-        userId,
-        backend,
-        feedActions,
-        close: () => {
-            signaling.close();
-            guest.close();
-        },
-    };
+    catch (error) {
+        signaling.close();
+        guest?.close();
+        throw error;
+    }
 }

package/dist/pointer/pointerService.d.ts

@@ -2,6 +2,8 @@ import * as THREE from "three";
 import type { PointerHit, PointerVec3 } from "@jgengine/core/input/pointer";
 export declare const POINTER_ENTITY_KEY = "jgEntityId";
 export declare const POINTER_OBJECT_KEY = "jgObjectId";
+/** Object-store identities indexed by the current compacted GPU instance slot. @internal */
+export declare const POINTER_OBJECT_INSTANCES_KEY = "jgObjectInstances";
 export type PointerHitFilter = (object: THREE.Object3D) => boolean;
 interface PointerDeps {
     camera: THREE.Camera;

package/dist/pointer/pointerService.js

@@ -1,6 +1,8 @@
 import * as THREE from "three";
 export const POINTER_ENTITY_KEY = "jgEntityId";
 export const POINTER_OBJECT_KEY = "jgObjectId";
+/** Object-store identities indexed by the current compacted GPU instance slot. @internal */
+export const POINTER_OBJECT_INSTANCES_KEY = "jgObjectInstances";
 function tagOf(object, key) {
     let cursor = object;
     while (cursor !== null) {
@@ -24,6 +26,8 @@ export function createPointerService() {
     const centerNdc = new THREE.Vector2(0, 0);
     const scratch = new THREE.Vector3();
     const normalMatrix = new THREE.Matrix3();
+    const instanceMatrix = new THREE.Matrix4();
+    const hitMatrix = new THREE.Matrix4();
     const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
     let deps = null;
     let cursorPresent = false;
@@ -45,7 +49,12 @@ export function createPointerService() {
             const point = [hit.point.x, hit.point.y, hit.point.z];
             let normal = [0, 1, 0];
             if (hit.face !== null && hit.face !== undefined) {
-                normalMatrix.getNormalMatrix(hit.object.matrixWorld);
+                hitMatrix.copy(hit.object.matrixWorld);
+                if (mesh.isInstancedMesh && hit.instanceId !== undefined) {
+                    mesh.getMatrixAt(hit.instanceId, instanceMatrix);
+                    hitMatrix.multiply(instanceMatrix);
+                }
+                normalMatrix.getNormalMatrix(hitMatrix);
                 scratch.copy(hit.face.normal).applyMatrix3(normalMatrix).normalize();
                 normal = [scratch.x, scratch.y, scratch.z];
             }
@@ -54,7 +63,8 @@ export function createPointerService() {
                 point,
                 normal,
                 entity: tagOf(hit.object, POINTER_ENTITY_KEY),
-                object: tagOf(hit.object, POINTER_OBJECT_KEY),
+                object: hit.instanceId === undefined ? tagOf(hit.object, POINTER_OBJECT_KEY) :
+                    hit.object.userData[POINTER_OBJECT_INSTANCES_KEY]?.[hit.instanceId] ?? tagOf(hit.object, POINTER_OBJECT_KEY),
                 ...(uv !== undefined ? { uv } : {}),
                 material: standardMaterialSample(mesh.material),
                 ...(hit.instanceId !== undefined ? { instanceId: hit.instanceId } : {}),

package/dist/postfx/PostProcessing.d.ts

@@ -1,5 +1,14 @@
+import { EffectComposer, type ShaderPass } from "three-stdlib";
 import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
 import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+interface BuiltGraph {
+    composer: EffectComposer;
+    grade: ShaderPass | null;
+}
+/** Release each pass and the composer's owned targets. @internal */
+export declare function disposeGraph(built: BuiltGraph): void;
+/** Resize the composer and its passes at the renderer's pixel ratio. @internal */
+export declare function syncSize(built: BuiltGraph, width: number, height: number, pixelRatio: number): void;
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
@@ -20,3 +29,4 @@ export declare function PostProcessing({ config, quality, stages }: {
         smaa: boolean;
     };
 }): null;
+export {};

package/dist/postfx/PostProcessing.js

@@ -8,7 +8,7 @@ import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
 import { createGradePass } from "./gradeShader.js";
 import { StylizePass } from "./stylizePass.js";
-import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
+import { renderShadowlessPrepass } from "./shadowPrepass.js";
 /**
  * GTAO renders the scene with an `overrideMaterial` normal/depth prepass, which stamps
  * transparent overlay quads (additive VFX sprites, telegraphs, debug gizmos) into the AO
@@ -19,18 +19,14 @@ import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
 class OverlayAwareGTAOPass extends GTAOPass {
     hiddenOverlays = [];
     render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
-        hidePostfxOverlays(this.scene, this.hiddenOverlays);
-        super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
-        restorePostfxOverlays(this.hiddenOverlays);
+        renderShadowlessPrepass(renderer, this.scene, this.hiddenOverlays, () => super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive));
     }
 }
 /** DOF's depth prepass has the same `overrideMaterial` overlay-stamping problem as GTAO. */
 class OverlayAwareBokehPass extends BokehPass {
     hiddenOverlays = [];
     render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
-        hidePostfxOverlays(this.scene, this.hiddenOverlays);
-        super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
-        restorePostfxOverlays(this.hiddenOverlays);
+        renderShadowlessPrepass(renderer, this.scene, this.hiddenOverlays, () => super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive));
     }
 }
 const TONE_MAPPING = {
@@ -41,22 +37,16 @@ const TONE_MAPPING = {
     linear: THREE.LinearToneMapping,
     none: THREE.NoToneMapping,
 };
-function disposeGraph(built) {
+/** Release each pass and the composer's owned targets. @internal */
+export function disposeGraph(built) {
     for (const pass of built.composer.passes)
         pass.dispose();
-    if (built.dof !== null) {
-        built.dof.renderTargetDepth.dispose();
-        built.dof.materialDepth.dispose();
-        built.dof.materialBokeh.dispose();
-        built.dof.fsQuad.dispose();
-    }
     built.composer.dispose();
 }
-function syncSize(built, width, height, pixelRatio) {
+/** Resize the composer and its passes at the renderer's pixel ratio. @internal */
+export function syncSize(built, width, height, pixelRatio) {
     built.composer.setPixelRatio(pixelRatio);
     built.composer.setSize(width, height);
-    if (built.dof !== null)
-        built.dof.renderTargetDepth.setSize(width * pixelRatio, height * pixelRatio);
 }
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
@@ -102,10 +92,9 @@ export function PostProcessing({ config, quality = "high", stages }) {
             const b = config.bloom ?? {};
             composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
         }
-        let dof = null;
         if (resolvedStages.dof && config.dof !== undefined && config.dof !== false) {
             const d = config.dof;
-            dof = new OverlayAwareBokehPass(scene, camera, {
+            const dof = new OverlayAwareBokehPass(scene, camera, {
                 focus: d.focus ?? 18,
                 aperture: d.aperture ?? (quality === "high" ? 0.00025 : 0.00012),
                 maxblur: d.maxBlur ?? 0.01,
@@ -125,7 +114,7 @@ export function PostProcessing({ config, quality = "high", stages }) {
             grade = createGradePass(config.grade ?? {});
             composer.addPass(grade);
         }
-        const graph = { composer, grade, dof };
+        const graph = { composer, grade };
         syncSize(graph, width, height, gl.getPixelRatio());
         builtRef.current = graph;
         return () => {
@@ -133,27 +122,6 @@ export function PostProcessing({ config, quality = "high", stages }) {
             builtRef.current = null;
         };
     }, [gl, scene, camera, config, quality, stages]);
-    useEffect(() => {
-        const lut = config.grade !== undefined && config.grade !== false ? config.grade.lut : undefined;
-        const grade = builtRef.current?.grade;
-        if (lut === undefined || grade === null || grade === undefined)
-            return;
-        let cancelled = false;
-        const loader = new THREE.TextureLoader();
-        loader.loadAsync(lut.url).then((texture) => {
-            if (cancelled) {
-                texture.dispose();
-                return;
-            }
-            texture.colorSpace = THREE.SRGBColorSpace;
-            texture.minFilter = THREE.NearestFilter;
-            texture.magFilter = THREE.NearestFilter;
-            texture.generateMipmaps = false;
-            grade.uniforms.uLut.value = texture;
-            grade.uniforms.uLutSize.value = lut.size ?? 32;
-        }).catch(() => undefined);
-        return () => { cancelled = true; };
-    }, [config.grade]);
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;

package/dist/postfx/gradeShader.d.ts

@@ -1,4 +1,4 @@
 import { ShaderPass } from "three-stdlib";
 import type { GradeConfig } from "@jgengine/core/render/postProcessing";
-/** Build the display-space colour-grade pass (lift/gain/gamma, saturation, vignette, grain). Advance `uniforms.uTime.value` each frame to animate the grain. */
+/** Build the display-space colour-grade pass and load its optional LUT. Dispose the pass to release its LUT; advance `uniforms.uTime.value` each frame to animate grain. */
 export declare function createGradePass(config?: GradeConfig): ShaderPass;

package/dist/postfx/gradeShader.js

@@ -61,11 +61,11 @@ const vertexShader = /* glsl */ `
     gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
   }
 `;
-/** Build the display-space colour-grade pass (lift/gain/gamma, saturation, vignette, grain). Advance `uniforms.uTime.value` each frame to animate the grain. */
+/** Build the display-space colour-grade pass and load its optional LUT. Dispose the pass to release its LUT; advance `uniforms.uTime.value` each frame to animate grain. */
 export function createGradePass(config = {}) {
     const lift = config.lift ?? DEFAULT_LIFT;
     const gain = config.gain ?? DEFAULT_GAIN;
-    return new ShaderPass({
+    const pass = new ShaderPass({
         uniforms: {
             tDiffuse: { value: null },
             uLift: { value: new THREE.Vector3(lift[0], lift[1], lift[2]) },
@@ -82,4 +82,32 @@ export function createGradePass(config = {}) {
         vertexShader,
         fragmentShader,
     });
+    let disposed = false;
+    let lutTexture = null;
+    const dispose = pass.dispose.bind(pass);
+    pass.dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        lutTexture?.dispose();
+        lutTexture = null;
+        dispose();
+    };
+    if (config.lut !== undefined) {
+        const lut = config.lut;
+        void new THREE.TextureLoader().loadAsync(lut.url).then((texture) => {
+            if (disposed) {
+                texture.dispose();
+                return;
+            }
+            lutTexture = texture;
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.minFilter = THREE.NearestFilter;
+            texture.magFilter = THREE.NearestFilter;
+            texture.generateMipmaps = false;
+            pass.uniforms.uLut.value = texture;
+            pass.uniforms.uLutSize.value = lut.size ?? 32;
+        }).catch(() => undefined);
+    }
+    return pass;
 }

package/dist/postfx/shadowPrepass.d.ts

@@ -0,0 +1,3 @@
+import type * as THREE from "three";
+/** Reuse the beauty pass's shadow maps while drawing a scene prepass. @internal */
+export declare function renderShadowlessPrepass<T>(renderer: Pick<THREE.WebGLRenderer, "shadowMap">, scene: THREE.Object3D, hiddenOverlays: THREE.Object3D[], render: () => T): T;

package/dist/postfx/shadowPrepass.js

@@ -0,0 +1,18 @@
+import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
+/** Reuse the beauty pass's shadow maps while drawing a scene prepass. @internal */
+export function renderShadowlessPrepass(renderer, scene, hiddenOverlays, render) {
+    const shadowMap = renderer.shadowMap;
+    const autoUpdate = shadowMap.autoUpdate;
+    const needsUpdate = shadowMap.needsUpdate;
+    hidePostfxOverlays(scene, hiddenOverlays);
+    shadowMap.autoUpdate = false;
+    shadowMap.needsUpdate = false;
+    try {
+        return render();
+    }
+    finally {
+        shadowMap.autoUpdate = autoUpdate;
+        shadowMap.needsUpdate = needsUpdate;
+        restorePostfxOverlays(hiddenOverlays);
+    }
+}