@jgengine/shell 0.19.0 → 0.21.0

package/dist/drivers/HudOnlyDriver.js

@@ -3,12 +3,17 @@ import { dispatchBoundAction, heldActionsFor, shouldFireBoundAction } from "../b
 import { advanceBehaviors } from "@jgengine/core/scene/behaviorRuntime";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { devtools } from "@jgengine/core/devtools/devtools";
+import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { resolveCommandSink } from "../commandSink.js";
+import { inputFramesEqual, resolveInputSink } from "../inputSink.js";
 import { EMPTY_RESERVED, NO_ACTIONS } from "../shellConstants.js";
-export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }) {
+export function HudOnlyDriver({ ctx, multiplayer, serverIdRef, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }) {
     const hasReportedTickError = useRef(false);
     const repeatFiredAtRef = useRef(new Map());
     const lastFrameRef = useRef(null);
     const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
+    const lastSentInputRef = useRef(null);
+    const serverAuthoritative = isServerAuthoritative(playable.game.multiplayer) && multiplayer !== null;
     useEffect(() => {
         let frameId;
         const tick = (now) => {
@@ -17,8 +22,19 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
             lastFrameRef.current = now;
             if (last === null)
                 return;
+            const sendInput = () => {
+                if (!serverAuthoritative || serverIdRef.current === null)
+                    return;
+                const frame = { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() };
+                if (lastSentInputRef.current !== null && inputFramesEqual(lastSentInputRef.current, frame))
+                    return;
+                lastSentInputRef.current = frame;
+                resolveInputSink({ serverAuthoritative, backend: multiplayer?.backend ?? null, serverId: serverIdRef.current }).send(frame);
+            };
             if (gateRef.current || !playControlsActive(ctx)) {
-                ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS));
+                ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS), { reset: true });
+                ctx.input.publishAnalog(null);
+                sendInput();
                 return;
             }
             const rawDt = (now - last) / 1000;
@@ -26,26 +42,28 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
             try {
                 let endPhase = devtools.profile.begin("time+input");
                 const dt = Math.min(rawDt, 0.05);
-                ctx.input.publish(heldActionsFor(tracker, tracker.actions()));
+                ctx.input.publish(heldActionsFor(tracker, tracker.actions()), {});
                 ctx.input.publishPointer(pointerAxisRef.current);
+                sendInput();
                 endPhase();
-                ctx.sim.advance(dt, (stepDt) => {
-                    const gameDt = ctx.time.advance(stepDt);
-                    ctx.sim.runStages("beforeMovement", stepDt);
-                    ctx.sim.runStages("afterMovement", stepDt);
-                    devtools.profile.measure("onTick", () => {
-                        playable.loop.onTick(ctx, gameDt);
+                if (!serverAuthoritative)
+                    ctx.sim.advance(dt, (stepDt, _tick, gameDt) => {
+                        ctx.input.beginStep();
+                        ctx.sim.runStages("beforeMovement", stepDt);
+                        ctx.sim.runStages("afterMovement", stepDt);
+                        devtools.profile.measure("onTick", () => {
+                            playable.loop.onTick(ctx, gameDt);
+                        });
+                        advanceBehaviors(ctx, gameDt);
+                        ctx.sim.runStages("afterTick", stepDt);
                     });
-                    advanceBehaviors(ctx, gameDt);
-                    ctx.sim.runStages("afterTick", stepDt);
-                });
                 endPhase = devtools.profile.begin("actions");
                 const nowMs = performance.now();
                 for (const action of inputActions) {
                     if (!shouldFireBoundAction(tracker, action, playable.game.input, repeatFiredAtRef.current, nowMs))
                         continue;
                     repeatFiredAtRef.current.set(action, nowMs);
-                    dispatchBoundAction(ctx, action, 0, 0, { yaw: 0, pitch: 0 }, EMPTY_RESERVED);
+                    dispatchBoundAction(ctx, action, 0, 0, { yaw: 0, pitch: 0 }, EMPTY_RESERVED, resolveCommandSink(ctx, { serverAuthoritative, backend: multiplayer?.backend ?? null, serverId: serverIdRef.current }));
                 }
                 tracker.endFrame();
                 endPhase();
@@ -60,6 +78,6 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
         };
         frameId = requestAnimationFrame(tick);
         return () => cancelAnimationFrame(frameId);
-    }, [ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, inputActions]);
+    }, [ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, inputActions, multiplayer, serverIdRef, serverAuthoritative]);
     return null;
 }

package/dist/environment/EnvironmentScene.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
-import { useTexture } from "@react-three/drei";
+import { PresentationAssetBoundary } from "../presentationRecovery.js";
+import { PresentationRecoveredDraw, useRecoverableTexture } from "../presentationRecovery3d.js";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
@@ -20,14 +21,13 @@ import { createTerrainDetailMaterial } from "../terrain/terrainDetailMaterial.js
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
-import { WeatherUniformProvider } from "../weather/weatherUniforms.js";
 function TexturedTerrainGround({ detail, layout, }) {
     const maps = detail.material.maps;
-    const textures = useTexture({
+    const textures = useRecoverableTexture({
         color: maps.color,
         normal: maps.normal,
-        roughness: maps.roughness,
-        ao: maps.ao,
+        ...(maps.roughness !== undefined ? { roughness: maps.roughness } : {}),
+        ...(maps.ao !== undefined ? { ao: maps.ao } : {}),
     });
     useEffect(() => {
         textures.color.colorSpace = THREE.SRGBColorSpace;
@@ -38,7 +38,7 @@ function TexturedTerrainGround({ detail, layout, }) {
         }
     }, [textures]);
     const material = useDisposable(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
-    return (_jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material }));
+    return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
 }
 function TerrainGround({ terrain, field, center, }) {
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
@@ -69,7 +69,7 @@ function TerrainGround({ terrain, field, center, }) {
         : createTerrainDetailMaterial(resolvedDetail).material, [resolvedDetail]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, center } }));
+        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, center } }) }));
     }
     return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
@@ -99,14 +99,15 @@ function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
 }
 function Precipitation({ weather }) {
+    const ctx = useGameContext();
     const [cx, cz] = areaCenter(weather.area);
     if (weather.kind === "rain") {
-        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, width: weather.width, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { timeSeconds: ctx.time.now, density: weather.density, speed: weather.speed, length: weather.dropLength, width: weather.width, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
     }
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { timeSeconds: ctx.time.now, density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
 }
 function Weather({ weather }) {
-    return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
+    return (_jsx(_Fragment, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
 }
 function oceanConfig(ocean) {
     return {

package/dist/inputSink.d.ts

@@ -2,17 +2,17 @@ import { type InputFrame } from "@jgengine/core/runtime/hostedGameRunner";
 import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
 /** Where the local player's per-frame input goes: discarded in single-player, sent to the authoritative host under `authority: "server"`. */
 export interface InputSink {
-    send(frame: InputFrame): void;
+    send(frame: InputFrame, options?: {
+        urgent?: boolean;
+        reset?: boolean;
+    }): void;
 }
 /** Discards input — the single-player / client-authoritative default, where the client integrates movement itself.
  * @internal
  */
 export declare function noopInputSink(): InputSink;
-/**
- * Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via
- * {@link INPUT_COMMAND}. Sends are sequenced one-in-flight-at-a-time per `serverId` and stamped with a monotonic
- * seq: a frame sent while one is already in flight replaces the pending frame rather than racing it, so the
- * latest intent always wins and a stale frame can never resolve after (and overwrite) a newer one.
+/** Coalesces continuous frames. Discrete release/reset intents bypass a pending ACK;
+ * the host's monotonic sequence admission rejects any older input arriving afterwards.
  * @internal
  */
 export declare function remoteInputSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): InputSink;

package/dist/inputSink.js

@@ -5,56 +5,91 @@ import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
 export function noopInputSink() {
     return { send() { } };
 }
-const remoteInputSources = new Map();
-function remoteInputSourceFor(serverId) {
-    let source = remoteInputSources.get(serverId);
+const remoteInputSources = new WeakMap();
+let lastInputSeq = 0;
+function remoteInputSourceFor(backend, serverId) {
+    let sources = remoteInputSources.get(backend.transport);
+    if (sources === undefined) {
+        sources = new Map();
+        remoteInputSources.set(backend.transport, sources);
+    }
+    let source = sources.get(serverId);
     if (source === undefined) {
-        source = { pending: null, inFlight: false };
-        remoteInputSources.set(serverId, source);
+        source = { pending: null, inFlight: null, latest: null, presses: new Map() };
+        sources.set(serverId, source);
     }
     return source;
 }
+// Use the browser time origin so a full reload stays ahead of the previous client.
+// The local high-water mark also preserves release ordering if its clock regresses.
 function monotonicInputSeq() {
-    return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+    const now = typeof performance !== "undefined" ? performance.timeOrigin + performance.now() : Date.now();
+    return lastInputSeq = Math.max(now, lastInputSeq + 0.001);
 }
 function pumpRemoteInput(backend, serverId, source) {
-    if (source.inFlight)
+    if (source.inFlight !== null)
         return;
     const frame = source.pending;
     if (frame === null) {
-        remoteInputSources.delete(serverId);
+        if (source.presses.size === 0)
+            remoteInputSources.get(backend.transport)?.delete(serverId);
         return;
     }
     source.pending = null;
-    source.inFlight = true;
+    const owner = {};
+    source.inFlight = owner;
+    const presses = [...source.presses.values()].map(press => ({ ...press }));
     const seq = monotonicInputSeq();
+    // Live clients and the joined host have independent simulation clocks. The host
+    // stamps receipt on its next tick; explicit ticks remain supported by replay.
+    const { tick: _clientTick, presses: _framePresses, ...intent } = frame;
     void backend.transport
-        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...frame, seq } })
+        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...intent, ...(presses.length > 0 ? { presses } : {}), seq } })
         .then((result) => {
-        if (!result.ok) {
+        if (result.ok)
+            for (const press of presses)
+                source.presses.delete(press.seq);
+        if (!result.ok)
             console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" rejected: ${result.reason}`);
-        }
     })
         .catch((error) => {
         console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" failed to send`, error);
     })
         .finally(() => {
-        source.inFlight = false;
+        // An urgent discrete intent supersedes this flight. Its old completion must not
+        // release the replacement's ACK gate or replay the superseded pending frame.
+        if (source.inFlight !== owner)
+            return;
+        source.inFlight = null;
         pumpRemoteInput(backend, serverId, source);
     });
 }
-/**
- * Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via
- * {@link INPUT_COMMAND}. Sends are sequenced one-in-flight-at-a-time per `serverId` and stamped with a monotonic
- * seq: a frame sent while one is already in flight replaces the pending frame rather than racing it, so the
- * latest intent always wins and a stale frame can never resolve after (and overwrite) a newer one.
+/** Coalesces continuous frames. Discrete release/reset intents bypass a pending ACK;
+ * the host's monotonic sequence admission rejects any older input arriving afterwards.
  * @internal
  */
 export function remoteInputSink(backend, serverId) {
     return {
-        send(frame) {
-            const source = remoteInputSourceFor(serverId);
-            source.pending = frame;
+        send(frame, options) {
+            const source = remoteInputSourceFor(backend, serverId);
+            if (options?.reset)
+                source.presses.clear();
+            for (const press of frame.presses ?? [])
+                source.presses.set(press.seq, { ...press });
+            // A reset must overtake an identical neutral release that still carries an
+            // unacknowledged press. Intent equality alone does not describe that flight.
+            if (!options?.reset && source.latest !== null && inputFramesEqual(source.latest, frame) && source.presses.size === 0)
+                return;
+            const snapshot = {
+                ...frame, held: [...frame.held],
+                ...(frame.presses === undefined ? {} : { presses: frame.presses.map(press => ({ ...press })) }),
+                pointer: frame.pointer === null ? null : { ...frame.pointer },
+                ...(frame.analog === undefined ? {} : { analog: frame.analog === null ? null : { ...frame.analog } }),
+            };
+            source.latest = snapshot;
+            source.pending = snapshot;
+            if (options?.urgent)
+                source.inFlight = null;
             pumpRemoteInput(backend, serverId, source);
         },
     };
@@ -72,6 +107,10 @@ export function resolveInputSink(opts) {
  * @internal
  */
 export function inputFramesEqual(a, b) {
+    const ap = a.presses ?? [];
+    const bp = b.presses ?? [];
+    if (ap.length !== bp.length || ap.some((press, index) => press.seq !== bp[index].seq || press.action !== bp[index].action))
+        return false;
     if (a.held.length !== b.held.length)
         return false;
     for (let i = 0; i < a.held.length; i++)

package/dist/lazyShell3dPresentation.d.ts

@@ -0,0 +1,9 @@
+import { type ComponentProps } from "react";
+import type { Shell3dPresentation } from "./Shell3dPresentation.js";
+type Presentation = typeof Shell3dPresentation;
+type Props = ComponentProps<Presentation> & {
+    onPresentationReveal?: () => void;
+};
+/** Loads the normal 3D implementation only for a 3D presentation. @internal */
+export declare function LazyShell3dPresentation({ onPresentationReveal, ...props }: Props): import("react").JSX.Element;
+export {};

package/dist/lazyShell3dPresentation.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useLayoutEffect, useState } from "react";
+import { suspendPlayControls } from "@jgengine/core/game/controlGate";
+import { markPresentationCodeLoadFailure } from "./presentationRecovery.js";
+let loadedPresentation;
+function getPresentation() {
+    return loadedPresentation ??= lazy(() => import("./Shell3dPresentation.js").then((module) => ({ default: module.Shell3dPresentation }), (error) => {
+        throw markPresentationCodeLoadFailure(error);
+    }));
+}
+function LoadingPresentation({ ctx }) {
+    useLayoutEffect(() => suspendPlayControls(ctx), [ctx]);
+    return (_jsx("div", { role: "status", "aria-live": "polite", "data-shell-code-loading": true, style: { display: "grid", placeItems: "center", width: "100%", height: "100%", minHeight: 160, background: "#0f172a", color: "#e2e8f0", fontFamily: "ui-sans-serif, system-ui, sans-serif" }, children: "Loading game view\u2026" }));
+}
+function PresentationReveal({ onReveal }) {
+    // React repeats layout effects when a suspended tree becomes visible again.
+    useLayoutEffect(() => { onReveal?.(); });
+    return null;
+}
+/** Loads the normal 3D implementation only for a 3D presentation. @internal */
+export function LazyShell3dPresentation({ onPresentationReveal, ...props }) {
+    const [Presentation] = useState(getPresentation);
+    return (_jsxs(Suspense, { fallback: _jsx(LoadingPresentation, { ctx: props.ctx }), children: [_jsx(Presentation, { ...props }), _jsx(PresentationReveal, { onReveal: onPresentationReveal })] }));
+}

package/dist/materialOverride.d.ts

@@ -4,6 +4,8 @@ export interface MaterialOverrideOptions {
     clone?: boolean;
     /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each standard or physical material alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
     textures?: MaterialOverrideTextures;
+    /** Records material replacements for the caller's resource owner. */
+    ownMaterial?: (material: THREE.Material) => void;
 }
 /** Loaded PBR textures for `applyMaterialOverride`'s `textures` option — matches `ModelMaterialMaps`' roles. */
 export interface MaterialOverrideTextures {
@@ -14,6 +16,46 @@ export interface MaterialOverrideTextures {
     metalness?: THREE.Texture;
     emissive?: THREE.Texture;
     height?: THREE.Texture;
+    alpha?: THREE.Texture;
+    sheenColor?: THREE.Texture;
+    sheenRoughness?: THREE.Texture;
+    anisotropy?: THREE.Texture;
+    clearcoat?: THREE.Texture;
+    clearcoatRoughness?: THREE.Texture;
+    clearcoatNormal?: THREE.Texture;
+    specularIntensity?: THREE.Texture;
+    specularColor?: THREE.Texture;
+    transmission?: THREE.Texture;
+    thickness?: THREE.Texture;
+    iridescence?: THREE.Texture;
+    iridescenceThickness?: THREE.Texture;
 }
+/** Physical texture roles mapped to the pinned Three renderer's native properties. @internal */
+export declare const MATERIAL_TEXTURE_PROPERTIES: {
+    readonly color: "map";
+    readonly normal: "normalMap";
+    readonly roughness: "roughnessMap";
+    readonly ao: "aoMap";
+    readonly metalness: "metalnessMap";
+    readonly emissive: "emissiveMap";
+    readonly height: "displacementMap";
+    readonly alpha: "alphaMap";
+    readonly sheenColor: "sheenColorMap";
+    readonly sheenRoughness: "sheenRoughnessMap";
+    readonly anisotropy: "anisotropyMap";
+    readonly clearcoat: "clearcoatMap";
+    readonly clearcoatRoughness: "clearcoatRoughnessMap";
+    readonly clearcoatNormal: "clearcoatNormalMap";
+    readonly specularIntensity: "specularIntensityMap";
+    readonly specularColor: "specularColorMap";
+    readonly transmission: "transmissionMap";
+    readonly thickness: "thicknessMap";
+    readonly iridescence: "iridescenceMap";
+    readonly iridescenceThickness: "iridescenceThicknessMap";
+};
+/** Whether authored settings require a physical shader; ordinary PBR stays standard. @internal */
+export declare function requiresPhysicalMaterial(override: ModelMaterialOverride, textures?: MaterialOverrideTextures): boolean;
 /** @internal */
 export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;
+/** Apply the shared override contract to one material. @internal */
+export declare function applyMaterialOverrideToMaterial(material: THREE.Material, override: ModelMaterialOverride, clone: boolean, textures: MaterialOverrideTextures | undefined): THREE.Material;

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>;
 }>;