@jgengine/shell 0.9.0 → 0.11.0

package/dist/materialOverride.d.ts

@@ -2,5 +2,15 @@ import * as THREE from "three";
 import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
 export interface MaterialOverrideOptions {
     clone?: boolean;
+    /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each `MeshStandardMaterial` alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
+    textures?: MaterialOverrideTextures;
 }
+/** Loaded PBR textures for `applyMaterialOverride`'s `textures` option — matches `ModelMaterialMaps`' roles. */
+export interface MaterialOverrideTextures {
+    color?: THREE.Texture;
+    normal?: THREE.Texture;
+    roughness?: THREE.Texture;
+    ao?: THREE.Texture;
+}
+/** @internal */
 export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;

package/dist/materialOverride.js

@@ -1,16 +1,18 @@
 import * as THREE from "three";
+/** @internal */
 export function applyMaterialOverride(root, override, options) {
     const clone = options?.clone !== false;
+    const textures = options?.textures;
     root.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
         mesh.material = Array.isArray(mesh.material)
-            ? mesh.material.map((material) => overrideOne(material, override, clone))
-            : overrideOne(mesh.material, override, clone);
+            ? mesh.material.map((material) => overrideOne(material, override, clone, textures))
+            : overrideOne(mesh.material, override, clone, textures);
     });
 }
-function overrideOne(material, override, clone) {
+function overrideOne(material, override, clone, textures) {
     if (!(material instanceof THREE.MeshStandardMaterial))
         return material;
     const target = clone ? material.clone() : material;
@@ -24,5 +26,15 @@ function overrideOne(material, override, clone) {
         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 !== undefined)
+        target.needsUpdate = true;
     return target;
 }

package/dist/multiplayer.js

@@ -1,4 +1,4 @@
-import { adapterOf } from "@jgengine/core/runtime/adapter";
+import { adapterOf, isServerAuthoritative } from "@jgengine/core/runtime/adapter";
 import { createWsBackend } from "@jgengine/ws/createWsBackend";
 import { announcePeerHost, broadcastChannelSignaling, createPeerGuest, createPeerHost, joinPeerSession, } from "@jgengine/ws/peer";
 export const DEFAULT_FEED_ACTIONS = ["entity.died"];
@@ -29,12 +29,22 @@ export function resolveShellMultiplayer(args) {
     if (args.force === true)
         return build(args.url ?? DEFAULT_WS_URL);
     const adapter = adapterOf(args.game.multiplayer);
-    if (adapter === null)
+    if (adapter === null || adapter.kind === "offline")
         return null;
-    if (adapter.kind === "ws")
-        return build(args.url ?? adapter.url ?? DEFAULT_WS_URL);
+    if (adapter.kind === "ws") {
+        const url = args.url ?? adapter.url;
+        if (url === undefined && isServerAuthoritative(args.game.multiplayer)) {
+            console.warn(`[jgengine:multiplayer] ${args.gameId}: ws({ authority: "server" }) has no url; falling back to single-player. ` +
+                `Pass a url (or set adapter.url) so the shell can reach the host.`);
+            return null;
+        }
+        return build(url ?? DEFAULT_WS_URL);
+    }
     if (adapter.kind === "lan")
         return build(args.url ?? lanUrl(adapter));
+    console.warn(`[jgengine:multiplayer] ${args.gameId}: multiplayer adapter "${adapter.kind}" needs its own session bootstrap ` +
+        `(e.g. resolvePeerShellMultiplayer for p2p()); resolveShellMultiplayer cannot build a ws backend for it, ` +
+        `so the game shipped single-player. Wire up the ${adapter.kind} transport or switch to ws()/lan().`);
     return null;
 }
 export async function resolvePeerShellMultiplayer(args) {

package/dist/postfx/PostProcessing.d.ts

@@ -0,0 +1,10 @@
+import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
+/**
+ * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
+ * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
+ * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
+ * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
+ */
+export declare function PostProcessing({ config }: {
+    config: PostProcessingConfig;
+}): null;

package/dist/postfx/PostProcessing.js

@@ -0,0 +1,120 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+import * as THREE from "three";
+import { EffectComposer, RenderPass, UnrealBloomPass } from "three-stdlib";
+import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
+import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
+import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
+import { createGradePass } from "./gradeShader.js";
+const TONE_MAPPING = {
+    aces: THREE.ACESFilmicToneMapping,
+    agx: THREE.AgXToneMapping,
+    reinhard: THREE.ReinhardToneMapping,
+    cineon: THREE.CineonToneMapping,
+    linear: THREE.LinearToneMapping,
+    none: THREE.NoToneMapping,
+};
+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) {
+    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
+ * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
+ * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
+ * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
+ */
+export function PostProcessing({ config }) {
+    const gl = useThree((s) => s.gl);
+    const scene = useThree((s) => s.scene);
+    const camera = useThree((s) => s.camera);
+    const size = useThree((s) => s.size);
+    const builtRef = useRef(null);
+    useEffect(() => {
+        const width = Math.max(1, size.width);
+        const height = Math.max(1, size.height);
+        const target = new THREE.WebGLRenderTarget(width, height, {
+            type: THREE.HalfFloatType,
+            samples: 2,
+        });
+        const composer = new EffectComposer(gl, target);
+        composer.addPass(new RenderPass(scene, camera));
+        if (config.ao !== undefined && config.ao !== false) {
+            const ao = new GTAOPass(scene, camera, width, height);
+            ao.blendIntensity = config.ao.blend ?? 1;
+            ao.updateGtaoMaterial({
+                radius: config.ao.radius ?? 1.8,
+                distanceExponent: 1,
+                thickness: config.ao.distanceFalloff ?? 3.6,
+                scale: config.ao.intensity ?? 2.4,
+                samples: 16,
+            });
+            composer.addPass(ao);
+        }
+        if (config.bloom !== false) {
+            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 (config.dof !== undefined && config.dof !== false) {
+            const d = config.dof;
+            dof = new BokehPass(scene, camera, {
+                focus: d.focus ?? 18,
+                aperture: d.aperture ?? 0.00025,
+                maxblur: d.maxBlur ?? 0.01,
+            });
+            composer.addPass(dof);
+        }
+        composer.addPass(new OutputPass());
+        let grade = null;
+        if (config.grade !== false) {
+            grade = createGradePass(config.grade ?? {});
+            composer.addPass(grade);
+        }
+        const graph = { composer, grade, dof };
+        syncSize(graph, width, height, gl.getPixelRatio());
+        builtRef.current = graph;
+        return () => {
+            disposeGraph(graph);
+            builtRef.current = null;
+        };
+    }, [gl, scene, camera, config]);
+    useEffect(() => {
+        const prevTone = gl.toneMapping;
+        const prevExposure = gl.toneMappingExposure;
+        gl.toneMapping = TONE_MAPPING[config.toneMapping ?? "aces"];
+        gl.toneMappingExposure = config.exposure ?? 1;
+        return () => {
+            gl.toneMapping = prevTone;
+            gl.toneMappingExposure = prevExposure;
+        };
+    }, [gl, config.toneMapping, config.exposure]);
+    useEffect(() => {
+        const built = builtRef.current;
+        if (built === null)
+            return;
+        syncSize(built, Math.max(1, size.width), Math.max(1, size.height), gl.getPixelRatio());
+    }, [gl, size.width, size.height]);
+    useFrame((_, delta) => {
+        const built = builtRef.current;
+        if (built === null)
+            return;
+        if (built.grade !== null)
+            built.grade.uniforms.uTime.value += delta;
+        built.composer.render(delta);
+    }, 1);
+    return null;
+}

package/dist/postfx/gradeShader.d.ts

@@ -0,0 +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. */
+export declare function createGradePass(config?: GradeConfig): ShaderPass;

package/dist/postfx/gradeShader.js

@@ -0,0 +1,72 @@
+import * as THREE from "three";
+import { ShaderPass } from "three-stdlib";
+const DEFAULT_LIFT = [0.012, 0.01, 0.018];
+const DEFAULT_GAIN = [1.05, 1.02, 0.98];
+const DEFAULT_GAMMA = 0.96;
+const DEFAULT_SATURATION = 1.12;
+const DEFAULT_VIGNETTE = 0.2;
+const DEFAULT_GRAIN = 0.012;
+const DEFAULT_CHROMA = 0;
+const fragmentShader = /* glsl */ `
+  uniform sampler2D tDiffuse;
+  uniform vec3 uLift;
+  uniform vec3 uGain;
+  uniform float uGamma;
+  uniform float uSaturation;
+  uniform float uVignette;
+  uniform float uGrain;
+  uniform float uChroma;
+  uniform float uTime;
+  varying vec2 vUv;
+
+  float hash(vec2 p) {
+    return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
+  }
+
+  void main() {
+    vec2 dir = vUv - 0.5;
+    // Chromatic aberration: split RGB along the radial direction, growing toward the edges.
+    vec2 shift = uChroma > 0.0 ? dir * uChroma * dot(dir, dir) * 4.0 : vec2(0.0);
+    vec3 c = uChroma > 0.0
+      ? vec3(texture2D(tDiffuse, vUv + shift).r, texture2D(tDiffuse, vUv).g, texture2D(tDiffuse, vUv - shift).b)
+      : texture2D(tDiffuse, vUv).rgb;
+    c = c + uLift;
+    c = c * uGain;
+    c = pow(max(c, 0.0), vec3(uGamma));
+    float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+    c = mix(vec3(luma), c, uSaturation);
+    vec2 d = vUv - 0.5;
+    float vig = 1.0 - uVignette * smoothstep(0.6, 0.95, dot(d, d) * 2.2);
+    c *= vig;
+    float g = (hash(vUv + fract(uTime)) - 0.5) * uGrain * 2.0;
+    c += g;
+    gl_FragColor = vec4(clamp(c, 0.0, 1.0), 1.0);
+  }
+`;
+const vertexShader = /* glsl */ `
+  varying vec2 vUv;
+  void main() {
+    vUv = uv;
+    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. */
+export function createGradePass(config = {}) {
+    const lift = config.lift ?? DEFAULT_LIFT;
+    const gain = config.gain ?? DEFAULT_GAIN;
+    return new ShaderPass({
+        uniforms: {
+            tDiffuse: { value: null },
+            uLift: { value: new THREE.Vector3(lift[0], lift[1], lift[2]) },
+            uGain: { value: new THREE.Vector3(gain[0], gain[1], gain[2]) },
+            uGamma: { value: config.gamma ?? DEFAULT_GAMMA },
+            uSaturation: { value: config.saturation ?? DEFAULT_SATURATION },
+            uVignette: { value: config.vignette ?? DEFAULT_VIGNETTE },
+            uGrain: { value: config.grain ?? DEFAULT_GRAIN },
+            uChroma: { value: config.chromaticAberration ?? DEFAULT_CHROMA },
+            uTime: { value: 0 },
+        },
+        vertexShader,
+        fragmentShader,
+    });
+}

package/dist/registry.d.ts

@@ -1,9 +1,10 @@
 import type { ComponentType, ReactNode } from "react";
-import type { PlayableGame as EnginePlayableGame } from "@jgengine/core/game/playableGame";
+import type { PlayableGame as EnginePlayableGame, WorldOverlayProps } from "@jgengine/core/game/playableGame";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { ViewmodelProps } from "./camera/GameFirstPersonCamera.js";
 export type RenderEntity = (entity: SceneEntity) => ReactNode;
 export type RenderObject = (object: SceneObject) => ReactNode;
-export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject>;
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps>>;
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;
 export declare function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined;

package/dist/render/EnvironmentLighting.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sets a neutral, network-free image-based-lighting environment on the scene so every
+ * `MeshStandardMaterial` — models and un-modeled primitive fallbacks alike — picks up soft
+ * reflections and fill instead of rendering dead-flat. A game's own sky/lighting still layers on
+ * top; this only supplies the reflective ambient the shell never had. Opt out with `look: "flat"`.
+ * @internal shell-internal default lighting; games never import it.
+ */
+export declare function EnvironmentLighting({ intensity }: {
+    intensity?: number;
+}): null;

package/dist/render/EnvironmentLighting.js

@@ -0,0 +1,34 @@
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+import * as THREE from "three";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+/**
+ * Sets a neutral, network-free image-based-lighting environment on the scene so every
+ * `MeshStandardMaterial` — models and un-modeled primitive fallbacks alike — picks up soft
+ * reflections and fill instead of rendering dead-flat. A game's own sky/lighting still layers on
+ * top; this only supplies the reflective ambient the shell never had. Opt out with `look: "flat"`.
+ * @internal shell-internal default lighting; games never import it.
+ */
+export function EnvironmentLighting({ intensity = 0.28 }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    useEffect(() => {
+        const pmrem = new THREE.PMREMGenerator(gl);
+        const room = new RoomEnvironment();
+        const target = pmrem.fromScene(room, 0.04);
+        const previous = scene.environment;
+        scene.environment = target.texture;
+        const sceneWithIntensity = scene;
+        const previousIntensity = sceneWithIntensity.environmentIntensity;
+        sceneWithIntensity.environmentIntensity = intensity;
+        room.dispose?.();
+        pmrem.dispose();
+        return () => {
+            target.dispose();
+            scene.environment = previous;
+            if (previousIntensity !== undefined)
+                sceneWithIntensity.environmentIntensity = previousIntensity;
+        };
+    }, [gl, scene, intensity]);
+    return null;
+}

package/dist/render/SceneLighting.d.ts

@@ -0,0 +1,7 @@
+import type { BackdropConfig, LightingConfig } from "@jgengine/core/game/playableGame";
+export declare function ConfiguredLighting({ lighting }: {
+    lighting: LightingConfig;
+}): import("react").JSX.Element;
+export declare function BackdropFog({ fog }: {
+    fog: BackdropConfig["fog"];
+}): import("react").JSX.Element | null;

package/dist/render/SceneLighting.js

@@ -0,0 +1,18 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
+function DirectionalShadowLight({ entry }) {
+    const size = entry.shadowCameraSize ?? 40;
+    return (_jsx("directionalLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": entry.shadowMapSize ?? 1024, "shadow-mapSize-height": entry.shadowMapSize ?? 1024, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": Math.max(200, size * 6), "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02 }));
+}
+export function ConfiguredLighting({ lighting }) {
+    return (_jsxs(_Fragment, { children: [lighting.ambient !== undefined ? (_jsx("ambientLight", { color: lighting.ambient.color, intensity: lighting.ambient.intensity ?? 0.55 })) : null, lighting.hemisphere !== undefined ? (_jsx("hemisphereLight", { args: [
+                    lighting.hemisphere.skyColor ?? "#bfe3ff",
+                    lighting.hemisphere.groundColor ?? "#4c6b34",
+                    lighting.hemisphere.intensity ?? 0.55,
+                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry }, index)))] }));
+}
+export function BackdropFog({ fog }) {
+    if (fog === undefined)
+        return null;
+    return fog.density !== undefined ? (_jsx("fogExp2", { attach: "fog", args: [fog.color ?? DEFAULT_BACKDROP_FOG_COLOR, fog.density] })) : (_jsx("fog", { attach: "fog", args: [fog.color ?? DEFAULT_BACKDROP_FOG_COLOR, fog.near ?? 10, fog.far ?? 200] }));
+}

package/dist/render/SceneModels.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import type { EntitySpriteConfig, ModelConfig } from "@jgengine/core/game/playableGame";
+export declare function EntitySprite({ sprite }: {
+    sprite: EntitySpriteConfig;
+}): import("react").JSX.Element;
+export declare function IsolatedEntityModel({ model, instanceId, fallback, }: {
+    model: ModelConfig;
+    instanceId?: string;
+    fallback?: ReactNode;
+}): import("react").JSX.Element;
+export declare function EntityModel({ model, instanceId }: {
+    model: ModelConfig;
+    instanceId?: string;
+}): import("react").JSX.Element;