@jgengine/shell 0.8.0 → 0.10.0

package/dist/environment/EnvironmentScene.js

@@ -1,67 +1,123 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import { useGameContext } from "@jgengine/react/provider";
+import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
 import { resolveStructureBuildings } from "@jgengine/core/world/environmentSummary";
-import { resolveTerrainField, resolveTerrainPalette } from "@jgengine/core/world/terrain";
-import { SkyDaylight } from "./Daylight.js";
+import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { GroundPad } from "./GroundPad.js";
-import { GeneratedBuilding } from "../structures/GeneratedBuilding.js";
+import { RoadRibbons } from "./RoadRibbons.js";
+import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
-import { ProceduralGround } from "../terrain/ProceduralGround.js";
+import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
+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";
-const DEFAULT_TERRAIN_FREQUENCY = 0.03;
-function TerrainGround({ terrain }) {
-    const palette = resolveTerrainPalette(terrain);
-    return (_jsx(ProceduralGround, { terrain: {
-            size: [terrain.bounds.w, terrain.bounds.d],
-            segments: terrain.segments,
-            height: terrain.height,
-            seed: terrain.seed,
-            moundScale: terrain.frequency ?? DEFAULT_TERRAIN_FREQUENCY,
-            octaves: terrain.octaves,
-            ridged: terrain.ridged,
-            baseOffset: terrain.baseHeight,
-        }, colors: {
-            low: palette.low,
-            high: palette.high,
-            ...(terrain.waterLevel === undefined ? {} : { waterline: palette.waterline, waterlineHeight: terrain.waterLevel }),
-        } }));
+function TerrainGround({ terrain, field, center, }) {
+    const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
+    const paletteAt = useMemo(() => {
+        const hasRegions = terrain.materialRegions !== undefined && terrain.materialRegions.length > 0;
+        const hasBands = terrain.biomeBands !== undefined && terrain.biomeBands.length > 0;
+        if (!hasRegions && !hasBands)
+            return undefined;
+        const sampler = createTerrainPaletteSampler(terrain);
+        if (center === undefined)
+            return sampler;
+        return (x, z) => sampler(x - center[0], z - center[1]);
+    }, [terrain, center]);
+    const colors = useMemo(() => ({
+        low: palette.low,
+        high: palette.high,
+        ...(terrain.waterLevel === undefined ? {} : { waterline: palette.waterline, waterlineHeight: terrain.waterLevel }),
+    }), [palette, terrain.waterLevel]);
+    const size = useMemo(() => [terrain.bounds.w, terrain.bounds.d], [terrain.bounds]);
+    const heightRange = useMemo(() => {
+        const base = terrain.baseHeight ?? 0;
+        const swing = terrain.height * 1.2;
+        return [base - swing, base + swing];
+    }, [terrain.baseHeight, terrain.height]);
+    const detailMaterial = useMemo(() => terrain.detail === undefined
+        ? undefined
+        : createTerrainDetailMaterial(resolveTerrainDetail(terrain.detail, terrain.waterLevel)).material, [terrain.detail, terrain.waterLevel]);
+    useEffect(() => () => detailMaterial?.dispose(), [detailMaterial]);
+    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: detailMaterial }));
+}
+function areaCenter(area) {
+    return area.position ?? [0, 0];
 }
 function Vegetation({ grass, field }) {
-    return (_jsx(GrassField, { area: [grass.area.w, grass.area.d], density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: field.sampleHeight, colorBase: grass.colors[0], colorTip: grass.colors[grass.colors.length - 1], wind: { strength: grass.windStrength } }));
+    const [cx, cz] = areaCenter(grass.area);
+    const heightAt = useMemo(() => cx === 0 && cz === 0
+        ? field.sampleHeight
+        : (x, z) => field.sampleHeight(x + cx, z + cz), [cx, cz, field]);
+    const area = useMemo(() => [grass.area.w, grass.area.d], [grass.area.w, grass.area.d]);
+    const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
+    const colorBase = grass.colors[0];
+    const colorTip = grass.colors[grass.colors.length - 1];
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, wind: wind, frustumCulled: true }) }));
 }
 function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
 }
 function Precipitation({ weather }) {
+    const [cx, cz] = areaCenter(weather.area);
     if (weather.kind === "rain") {
-        return (_jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, 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, { density: weather.density, speed: weather.speed, length: weather.dropLength, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
     }
-    return (_jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, 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, 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}`))) }));
 }
+function oceanConfig(ocean) {
+    return {
+        size: ocean.bounds.w,
+        depth: ocean.bounds.d,
+        amplitude: ocean.waveHeight,
+        speed: ocean.waveSpeed,
+        waveScale: ocean.waveScale,
+        color: { shallow: ocean.color },
+    };
+}
+function useOceanConfig(ocean) {
+    return useMemo(() => oceanConfig(ocean), [ocean.bounds.w, ocean.bounds.d, ocean.waveHeight, ocean.waveSpeed, ocean.color]);
+}
+function DynamicWater({ ocean }) {
+    const ctx = useGameContext();
+    const groupRef = useRef(null);
+    const [x, z] = ocean.position ?? [0, 0];
+    const config = useOceanConfig(ocean);
+    useFrame(() => {
+        if (groupRef.current !== null)
+            groupRef.current.position.y = ocean.levelAt(ctx.time.now());
+    });
+    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config }) }));
+}
 function Water({ ocean }) {
     const [x, z] = ocean.position ?? [0, 0];
-    return (_jsx(Ocean, { position: [x, ocean.level, z], config: {
-            size: Math.max(ocean.bounds.w, ocean.bounds.d),
-            amplitude: ocean.waveHeight,
-            speed: ocean.waveSpeed,
-            color: { shallow: ocean.color },
-        } }));
+    const config = useOceanConfig(ocean);
+    if (ocean.levelAt !== undefined) {
+        return _jsx(DynamicWater, { ocean: ocean });
+    }
+    return _jsx(Ocean, { position: [x, ocean.level, z], config: config });
 }
 function Structures({ structures, field }) {
-    const buildings = useMemo(() => resolveStructureBuildings(structures), [structures]);
-    return (_jsx(_Fragment, { children: buildings.map((building) => (_jsx("group", { "position-y": field.sampleHeight(building.center[0], building.center[1]), children: _jsx(GeneratedBuilding, { building: building }) }, building.id))) }));
+    const placements = useMemo(() => resolveStructureBuildings(structures).map((building) => ({
+        building,
+        position: [0, field.sampleHeight(building.center[0], building.center[1]), 0],
+    })), [structures, field]);
+    const palette = useMemo(() => resolveBuildingPalette(structures.style, structures.palette), [structures.style, structures.palette]);
+    return _jsx(InstancedBuildings, { buildings: placements, palette: palette });
 }
 export function EnvironmentScene({ feature }) {
-    const field = useMemo(() => resolveTerrainField(feature.terrain), [feature.terrain]);
+    const field = useMemo(() => resolveEnvironmentField(feature), [feature]);
     const vegetation = feature.vegetation ?? [];
     const water = feature.water ?? [];
     const structures = feature.structures ?? [];
     const pads = feature.pads ?? [];
-    return (_jsxs(_Fragment, { children: [feature.sky !== undefined && !feature.sky.timeOfDay ? _jsx(SkyDaylight, { sky: feature.sky }) : null, feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain }) : null, water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    const islands = feature.islands ?? [];
+    const roads = feature.roads ?? [];
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field }, `road-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/RoadRibbons.d.ts

@@ -0,0 +1,7 @@
+import type { RoadEnvironmentDescriptor } from "@jgengine/core/world/features";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+/** Renders one `road()` descriptor: an asphalt ribbon plus optional dashed centerline, draped on the terrain. */
+export declare function RoadRibbons({ road, field }: {
+    road: RoadEnvironmentDescriptor;
+    field: TerrainField;
+}): import("react").JSX.Element | null;

package/dist/environment/RoadRibbons.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { BufferAttribute, BufferGeometry, DoubleSide } from "three";
+import { buildRoadRibbon, dashSegments } from "@jgengine/core/world/roads";
+import { offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+function toGeometry(positions, indices) {
+    if (positions.length === 0)
+        return null;
+    const geometry = new BufferGeometry();
+    geometry.setAttribute("position", new BufferAttribute(positions, 3));
+    geometry.setIndex(new BufferAttribute(indices, 1));
+    geometry.computeVertexNormals();
+    return geometry;
+}
+function ribbonGeometry(path, width, field, elevation) {
+    const ribbon = buildRoadRibbon(path, width, (x, z) => field.sampleHeight(x, z), { elevation });
+    return toGeometry(ribbon.positions, ribbon.indices);
+}
+function mergedDashGeometry(road, field) {
+    const width = Math.max(0.25, road.width * 0.035);
+    const ribbons = dashSegments(road.path, 3.2, 4).map((dash) => buildRoadRibbon(dash, width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + 0.04 }));
+    const vertexCount = ribbons.reduce((sum, r) => sum + r.positions.length, 0);
+    const indexCount = ribbons.reduce((sum, r) => sum + r.indices.length, 0);
+    if (vertexCount === 0)
+        return null;
+    const positions = new Float32Array(vertexCount);
+    const indices = new Uint32Array(indexCount);
+    let vertexOffset = 0;
+    let indexOffset = 0;
+    for (const ribbon of ribbons) {
+        positions.set(ribbon.positions, vertexOffset);
+        const base = vertexOffset / 3;
+        for (let i = 0; i < ribbon.indices.length; i += 1) {
+            indices[indexOffset + i] = ribbon.indices[i] + base;
+        }
+        vertexOffset += ribbon.positions.length;
+        indexOffset += ribbon.indices.length;
+    }
+    return toGeometry(positions, indices);
+}
+/** Renders one `road()` descriptor: an asphalt ribbon plus optional dashed centerline, draped on the terrain. */
+export function RoadRibbons({ road, field }) {
+    const asphalt = useMemo(() => ribbonGeometry(road.path, road.width, field, road.elevation), [road, field]);
+    const dashes = useMemo(() => (road.markings ? mergedDashGeometry(road, field) : null), [road, field]);
+    const sidewalks = useMemo(() => {
+        const width = sidewalkWidthOf(road);
+        if (width <= 0)
+            return [];
+        const offset = road.width / 2 + width / 2;
+        return [offsetPath(road.path, offset), offsetPath(road.path, -offset)]
+            .map((path) => ribbonGeometry(path, width, field, road.elevation + 0.06))
+            .filter((geometry) => geometry !== null);
+    }, [road, field]);
+    if (asphalt === null)
+        return null;
+    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }), dashes !== null ? (_jsx("mesh", { geometry: dashes, children: _jsx("meshStandardMaterial", { color: road.markingColor, roughness: 0.8, metalness: 0, side: DoubleSide }) })) : null, sidewalks.map((geometry, index) => (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.sidewalk === false ? "#a7adb8" : road.sidewalk.color, roughness: 0.9, metalness: 0, side: DoubleSide }) }, `walk-${index}`)))] }));
+}

package/dist/environment/groundPadMath.d.ts

@@ -9,5 +9,5 @@ export type PadShape = {
     depth: number;
 };
 export declare function resolvePadShape(size: PadSize): PadShape;
-export declare function resolvePadSurfaceY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height">): number;
-export declare function resolvePadMeshY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height">): number;
+export declare function resolvePadSurfaceY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height" | "elevation">): number;
+export declare function resolvePadMeshY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height" | "elevation">): number;

package/dist/environment/groundPadMath.js

@@ -3,7 +3,7 @@ export function resolvePadShape(size) {
     return "radius" in size ? { circular: true, radius: size.radius } : { circular: false, width: size[0], depth: size[1] };
 }
 export function resolvePadSurfaceY(groundHeight, pad) {
-    return groundHeight + pad.height;
+    return pad.elevation ?? groundHeight + pad.height;
 }
 export function resolvePadMeshY(groundHeight, pad) {
     return resolvePadSurfaceY(groundHeight, pad) - PAD_THICKNESS / 2;

package/dist/environment/index.d.ts

@@ -1,3 +1,4 @@
-export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDomeProps, type TimeOfDayDaylightProps, } from "./Daylight.js";
+export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDaylightProps, type SkyDomeProps, type TimeOfDayDaylightProps, } from "./Daylight.js";
 export { EnvironmentScene, type EnvironmentSceneProps } from "./EnvironmentScene.js";
 export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, type DaylightCycleConfig, type DaylightState, } from "./daylightCycle.js";
+export { resolveSkyLightOwnership, skyEmitsLights, type SkyLightOwnership, } from "./skyLightingPolicy.js";

package/dist/environment/index.js

@@ -1,3 +1,4 @@
 export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, } from "./Daylight.js";
 export { EnvironmentScene } from "./EnvironmentScene.js";
 export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, } from "./daylightCycle.js";
+export { resolveSkyLightOwnership, skyEmitsLights, } from "./skyLightingPolicy.js";

package/dist/environment/skyLightingPolicy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Policy for composing sky backdrops with `PlayableGame.lighting`:
+ * - authored lighting present → sky renders dome + fog only; lights stay game-owned
+ * - no authored lighting → sky may emit its default sun/hemisphere with the dome
+ * Time-of-day never rewrites configured lights; it only drives sky colors/fog (and
+ * sky-owned lights when the game did not author lighting).
+ */
+export type SkyLightOwnership = "authored" | "sky-default";
+export declare function resolveSkyLightOwnership(hasAuthoredLighting: boolean): SkyLightOwnership;
+export declare function skyEmitsLights(ownership: SkyLightOwnership): boolean;

package/dist/environment/skyLightingPolicy.js

@@ -0,0 +1,6 @@
+export function resolveSkyLightOwnership(hasAuthoredLighting) {
+    return hasAuthoredLighting ? "authored" : "sky-default";
+}
+export function skyEmitsLights(ownership) {
+    return ownership === "sky-default";
+}

package/dist/input/mouseLook.d.ts

@@ -0,0 +1,27 @@
+export interface MouseLookOptions {
+    /** Radians of look per pixel of mouse movement; default `0.0024`. */
+    sensitivity?: number;
+    /** Pitch clamp in radians; default `1.15`. */
+    maxPitch?: number;
+    /** Request pointer lock on click (skipped on coarse-pointer/touch devices); default `true`. */
+    pointerLock?: boolean;
+    initialYaw?: number;
+    initialPitch?: number;
+}
+export interface MouseLookAim {
+    yaw: number;
+    pitch: number;
+}
+/**
+ * The analog mouse-look service chase/orbit-cam games hand-rolled (#282.8) — pointer-lock
+ * lifecycle plus delta accumulation into a yaw/pitch aim, decoupled from the first-person rig.
+ * Attach it to the canvas, read `aim()` from `onTick`/`useFrame`, dispose on unmount.
+ */
+export interface MouseLookTracker {
+    aim(): MouseLookAim;
+    setAim(yaw: number, pitch: number): void;
+    /** True while pointer lock is held on the tracked element. */
+    locked(): boolean;
+    dispose(): void;
+}
+export declare function createMouseLookTracker(element: HTMLElement, options?: MouseLookOptions): MouseLookTracker;

package/dist/input/mouseLook.js

@@ -0,0 +1,35 @@
+export function createMouseLookTracker(element, options = {}) {
+    const sensitivity = options.sensitivity ?? 0.0024;
+    const maxPitch = options.maxPitch ?? 1.15;
+    const pointerLock = options.pointerLock ?? true;
+    let yaw = options.initialYaw ?? 0;
+    let pitch = options.initialPitch ?? 0;
+    const requestLock = () => {
+        if (!pointerLock)
+            return;
+        if (window.matchMedia?.("(pointer: coarse)").matches)
+            return;
+        if (document.pointerLockElement !== element)
+            void element.requestPointerLock?.();
+    };
+    const onMove = (event) => {
+        if (pointerLock && document.pointerLockElement !== element)
+            return;
+        yaw -= event.movementX * sensitivity;
+        pitch = Math.max(-maxPitch, Math.min(maxPitch, pitch - event.movementY * sensitivity));
+    };
+    element.addEventListener("click", requestLock);
+    window.addEventListener("mousemove", onMove);
+    return {
+        aim: () => ({ yaw, pitch }),
+        setAim(nextYaw, nextPitch) {
+            yaw = nextYaw;
+            pitch = Math.max(-maxPitch, Math.min(maxPitch, nextPitch));
+        },
+        locked: () => document.pointerLockElement === element,
+        dispose() {
+            element.removeEventListener("click", requestLock);
+            window.removeEventListener("mousemove", onMove);
+        },
+    };
+}

package/dist/inputSink.d.ts

@@ -0,0 +1,18 @@
+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;
+}
+/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself. */
+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}. */
+export declare function remoteInputSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): InputSink;
+/** The sink a server-authoritative shell sends its per-frame input through: remote when `authority: "server"` and a server is joined, a no-op otherwise. */
+export declare function resolveInputSink(opts: {
+    serverAuthoritative: boolean;
+    backend: Pick<LiveGameBackend, "transport"> | null;
+    serverId: string | null;
+}): InputSink;
+/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing. */
+export declare function inputFramesEqual(a: InputFrame, b: InputFrame): boolean;

package/dist/inputSink.js

@@ -0,0 +1,35 @@
+import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
+/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself. */
+export function noopInputSink() {
+    return { send() { } };
+}
+/** Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via {@link INPUT_COMMAND}. */
+export function remoteInputSink(backend, serverId) {
+    return {
+        send(frame) {
+            void backend.transport
+                .runCommand({ serverId, command: INPUT_COMMAND, input: frame })
+                .catch(() => undefined);
+        },
+    };
+}
+/** The sink a server-authoritative shell sends its per-frame input through: remote when `authority: "server"` and a server is joined, a no-op otherwise. */
+export function resolveInputSink(opts) {
+    if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
+        return remoteInputSink(opts.backend, opts.serverId);
+    }
+    return noopInputSink();
+}
+/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing. */
+export function inputFramesEqual(a, b) {
+    if (a.held.length !== b.held.length)
+        return false;
+    for (let i = 0; i < a.held.length; i++)
+        if (a.held[i] !== b.held[i])
+            return false;
+    const pa = a.pointer;
+    const pb = b.pointer;
+    if (pa === null || pb === null)
+        return pa === pb;
+    return pa.x === pb.x && pa.y === pb.y && pa.active === pb.active;
+}

package/dist/materialOverride.d.ts

@@ -1,8 +1,6 @@
 import * as THREE from "three";
 import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
-/**
- * Clones each `MeshStandardMaterial` under `root` and applies `override`'s
- * color/finish onto the clone, so shared GLTF-cache scenes are never mutated
- * in place (#151.3).
- */
-export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride): void;
+export interface MaterialOverrideOptions {
+    clone?: boolean;
+}
+export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;

package/dist/materialOverride.js

@@ -1,32 +1,28 @@
 import * as THREE from "three";
-/**
- * Clones each `MeshStandardMaterial` under `root` and applies `override`'s
- * color/finish onto the clone, so shared GLTF-cache scenes are never mutated
- * in place (#151.3).
- */
-export function applyMaterialOverride(root, override) {
+export function applyMaterialOverride(root, override, options) {
+    const clone = options?.clone !== false;
     root.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
         mesh.material = Array.isArray(mesh.material)
-            ? mesh.material.map((material) => overrideOne(material, override))
-            : overrideOne(mesh.material, override);
+            ? mesh.material.map((material) => overrideOne(material, override, clone))
+            : overrideOne(mesh.material, override, clone);
     });
 }
-function overrideOne(material, override) {
+function overrideOne(material, override, clone) {
     if (!(material instanceof THREE.MeshStandardMaterial))
         return material;
-    const clone = material.clone();
+    const target = clone ? material.clone() : material;
     if (override.color !== undefined)
-        clone.color.set(override.color);
+        target.color.set(override.color);
     if (override.metalness !== undefined)
-        clone.metalness = override.metalness;
+        target.metalness = override.metalness;
     if (override.roughness !== undefined)
-        clone.roughness = override.roughness;
+        target.roughness = override.roughness;
     if (override.emissive !== undefined)
-        clone.emissive.set(override.emissive);
+        target.emissive.set(override.emissive);
     if (override.emissiveIntensity !== undefined)
-        clone.emissiveIntensity = override.emissiveIntensity;
-    return clone;
+        target.emissiveIntensity = override.emissiveIntensity;
+    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"];
@@ -31,8 +31,12 @@ export function resolveShellMultiplayer(args) {
     const adapter = adapterOf(args.game.multiplayer);
     if (adapter === null)
         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))
+            return null;
+        return build(url ?? DEFAULT_WS_URL);
+    }
     if (adapter.kind === "lan")
         return build(args.url ?? lanUrl(adapter));
     return null;

package/dist/pointer/PointerProbe.js

@@ -5,7 +5,12 @@ export function PointerProbe({ service }) {
     const scene = useThree((state) => state.scene);
     const gl = useThree((state) => state.gl);
     const size = useThree((state) => state.size);
-    service.bind({ camera, scene, width: size.width, height: size.height });
+    useEffect(() => {
+        service.bind({ camera, scene, width: size.width, height: size.height });
+        return () => {
+            service.bind(null);
+        };
+    }, [service, camera, scene, size.width, size.height]);
     useEffect(() => {
         const el = gl.domElement;
         let locked = false;
@@ -33,7 +38,6 @@ export function PointerProbe({ service }) {
             el.removeEventListener("pointermove", onMove);
             el.removeEventListener("pointerleave", onLeave);
             document.removeEventListener("pointerlockchange", onLockChange);
-            service.bind(null);
         };
     }, [gl, service]);
     return null;

package/dist/pointer/pointerService.d.ts

@@ -2,11 +2,14 @@ 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";
+export type PointerHitFilter = (object: THREE.Object3D) => boolean;
 interface PointerDeps {
     camera: THREE.Camera;
     scene: THREE.Scene;
     width: number;
     height: number;
+    layers?: THREE.Layers;
+    filter?: PointerHitFilter;
 }
 export interface PointerService {
     /** Cast the current cursor into the world; null when the cursor is off-canvas. */

package/dist/pointer/pointerService.js

@@ -30,9 +30,15 @@ export function createPointerService() {
     function hitAtNdc(target) {
         if (deps === null)
             return null;
+        if (deps.layers !== undefined)
+            raycaster.layers.mask = deps.layers.mask;
+        else
+            raycaster.layers.enableAll();
         raycaster.setFromCamera(target, deps.camera);
         const intersects = raycaster.intersectObjects(deps.scene.children, true);
         for (const hit of intersects) {
+            if (deps.filter !== undefined && !deps.filter(hit.object))
+                continue;
             const mesh = hit.object;
             if (!mesh.isMesh)
                 continue;

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,82 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo } 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 { 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,
+};
+/**
+ * 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 built = useMemo(() => {
+        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));
+        }
+        composer.addPass(new OutputPass());
+        let grade = null;
+        if (config.grade !== false) {
+            grade = createGradePass(config.grade ?? {});
+            composer.addPass(grade);
+        }
+        return { composer, grade };
+    }, [gl, scene, camera, config, size.width, size.height]);
+    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 { composer } = built;
+        composer.setPixelRatio(gl.getPixelRatio());
+        composer.setSize(size.width, size.height);
+        return () => composer.dispose();
+    }, [built, gl, size.width, size.height]);
+    useFrame((_, delta) => {
+        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;