@jgengine/shell 0.19.0 → 0.21.0

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

package/dist/presentationRecovery.d.ts

@@ -0,0 +1,75 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+/** Marks only a rejected presentation import for page reload; browser module failures are cached. @internal */
+export declare function markPresentationCodeLoadFailure(error: unknown): Error;
+/** @internal Distinguishes module loading from recoverable assets without guessing from error text. */
+export declare function presentationRecoveryAction(error: unknown): "reload" | "retry";
+/** @internal Classifies a reported React error after its owning boundary commits. */
+export declare function deferUnhandledPresentationError(error: unknown, report: () => void): void;
+/** @internal Exact pending texture groups owned by one presentation, including uncommitted Suspense. */
+export declare function createPresentationRetryRegistry(defaultClear?: (inputs: string[]) => void): {
+    register(inputs: readonly string[], clear?: ((inputs: string[]) => void) | undefined): () => void;
+    retry(): void;
+};
+type RetryRegistry = ReturnType<typeof createPresentationRetryRegistry>;
+type PresentationRetryScope = {
+    registry: RetryRegistry;
+    fail: (error: unknown, stack?: string) => void;
+    recoveredDraw: () => void;
+};
+/** Renderer-only loader adapters share the DOM owner without importing their libraries here. @internal */
+export declare function usePresentationRetryScope(): PresentationRetryScope | null;
+/** @internal Forwards renderer-local loader errors to the owning DOM presentation. */
+export declare function PresentationAssetBoundary({ children }: {
+    children: ReactNode;
+}): ReactNode;
+/** @internal Retires only diagnostics belonging to this exact handled presentation error. */
+export declare function createPresentationDiagnosticOwnership(): {
+    register(error: unknown, id: number, phase: string): void;
+    recovered(error: unknown): ReadonlySet<number>;
+};
+/** Restores an owned recovered surface only after Suspense has attached and revealed it. @internal */
+export declare function createPlaySurfaceFocusOwnership<Owner>(): {
+    request(owner: Owner): void;
+    reveal(owner: Owner, surface: HTMLElement | null, active: Element | null, body: HTMLElement): boolean;
+};
+/** Reports the owning presentation attempt and recovery lifecycle. @internal */
+export type PresentationRecoveryEvent = {
+    phase: string;
+    attempt: number;
+    scope: number;
+    sameOwner: boolean;
+    pending: boolean;
+    failed: boolean;
+};
+type RecoveryProps = {
+    ctx: GameContext;
+    children: ReactNode;
+    onRuntimeError: (error: unknown, phase: string, componentStack?: string) => void;
+    onRetryCommitted?: () => void;
+    onRecoveredDraw?: (error: unknown) => void;
+    onRecoveryEvent?: (event: PresentationRecoveryEvent) => void;
+};
+type RecoveryState = {
+    owner: GameContext;
+    failed: boolean;
+    error: unknown;
+    registry: RetryRegistry;
+};
+/** @internal Retains the live context for asset Retry; failed browser modules require page reload. */
+export declare class PresentationRecovery extends Component<RecoveryProps, RecoveryState> {
+    state: RecoveryState;
+    static getDerivedStateFromProps(props: RecoveryProps, state: RecoveryState): Partial<RecoveryState> | null;
+    static getDerivedStateFromError(error: unknown): Partial<RecoveryState>;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    componentDidUpdate(previousProps: RecoveryProps, previousState: RecoveryState): void;
+    componentWillUnmount(): void;
+    private attempt;
+    private scopeId;
+    private trace;
+    private scope;
+    private pendingRecovery;
+    private retry;
+    render(): ReactNode;
+}
+export {};