@jgengine/shell 0.10.0 → 0.11.0

package/dist/environment/EnvironmentScene.js

@@ -1,6 +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 * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
 import { resolveStructureBuildings } from "@jgengine/core/world/environmentSummary";
@@ -15,6 +17,26 @@ 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({
+        color: maps.color,
+        normal: maps.normal,
+        roughness: maps.roughness,
+        ao: maps.ao,
+    });
+    useEffect(() => {
+        textures.color.colorSpace = THREE.SRGBColorSpace;
+        for (const texture of Object.values(textures)) {
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.needsUpdate = true;
+        }
+    }, [textures]);
+    const material = useMemo(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
+    useEffect(() => () => material.dispose(), [material]);
+    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 }));
+}
 function TerrainGround({ terrain, field, center, }) {
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
     const paletteAt = useMemo(() => {
@@ -38,11 +60,15 @@ function TerrainGround({ terrain, field, center, }) {
         const swing = terrain.height * 1.2;
         return [base - swing, base + swing];
     }, [terrain.baseHeight, terrain.height]);
-    const detailMaterial = useMemo(() => terrain.detail === undefined
+    const resolvedDetail = useMemo(() => (terrain.detail === undefined ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
+    const proceduralMaterial = useMemo(() => resolvedDetail === undefined || resolvedDetail.material !== 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 }));
+        : 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(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
 function areaCenter(area) {
     return area.position ?? [0, 0];
@@ -64,9 +90,9 @@ function weatherVolume(area) {
 function Precipitation({ weather }) {
     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, 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, 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, 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) }) }));
 }
 function Weather({ weather }) {
     return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));

package/dist/environment/VolumetricClouds.d.ts

@@ -0,0 +1,17 @@
+import type { VolumetricCloudsRules } from "@jgengine/core/world/volumetricClouds";
+/** Props for {@link VolumetricClouds} — fully-resolved cloud rules plus the shared sun direction. */
+export interface VolumetricCloudsProps {
+    rules: VolumetricCloudsRules;
+    /** Direction toward the sun (same vector `SkyDome`/`Daylight` use for the sun disc). */
+    sunDirection: readonly [number, number, number];
+}
+/**
+ * A raymarched volumetric cloud slab: a large horizontal box straddling `[height, height+thickness]`,
+ * following the camera in XZ (like `SkyDome`), whose fragment shader raymarches 3D FBM noise inside
+ * the slab and accumulates density-weighted color with a sun-facing forward-scatter term. Mounted
+ * from `Daylight`/`SkyDaylight`/`TimeOfDayDaylight` whenever a sky descriptor carries
+ * `volumetricClouds`; off by default (the component itself is simply not rendered). A game never
+ * mounts this directly — author clouds via `sky({ volumetricClouds })`.
+ * @internal
+ */
+export declare function VolumetricClouds({ rules, sunDirection }: VolumetricCloudsProps): import("react").JSX.Element;

package/dist/environment/VolumetricClouds.js

@@ -0,0 +1,202 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+/**
+ * Camera-centered proxy dome radius. Must sit inside the default camera far plane
+ * (`CAMERA_FRUSTUM_DEFAULTS.far` = 300) — a bigger sphere is clipped whole and renders nothing. The
+ * raymarch works in world space against the absolute cloud slab, so this size only has to cover the
+ * screen (camera is always at the dome center), never bound the clouds.
+ */
+const INSIDE_FRUSTUM_DOME_RADIUS = 240;
+function hashSeed(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) % 100000;
+}
+function normalizeVec3(v) {
+    const out = new THREE.Vector3(v[0], v[1], v[2]);
+    return out.lengthSq() === 0 ? new THREE.Vector3(0, 1, 0) : out.normalize();
+}
+const CLOUD_VERTEX_SHADER = /* glsl */ `
+varying vec3 vJgCloudWorldPos;
+void main() {
+  vJgCloudWorldPos = (modelMatrix * vec4(position, 1.0)).xyz;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+const CLOUD_FRAGMENT_SHADER = /* glsl */ `
+uniform vec3 uCameraPos;
+uniform vec3 uColor;
+uniform vec3 uSunColor;
+uniform vec3 uSunDirection;
+uniform float uSunScatter;
+uniform float uCoverage;
+uniform float uDensity;
+uniform float uBaseHeight;
+uniform float uThickness;
+uniform float uScale;
+uniform float uSpeed;
+uniform float uTime;
+uniform float uSeedOffset;
+varying vec3 vJgCloudWorldPos;
+
+float jgCloudHash13(vec3 p){
+  p = fract(p * 0.1031 + uSeedOffset * 0.0007);
+  p += dot(p, p.yzx + 33.33);
+  return fract((p.x + p.y) * p.z);
+}
+
+float jgCloudNoise(vec3 p){
+  vec3 i = floor(p);
+  vec3 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  float n000 = jgCloudHash13(i + vec3(0.0, 0.0, 0.0));
+  float n100 = jgCloudHash13(i + vec3(1.0, 0.0, 0.0));
+  float n010 = jgCloudHash13(i + vec3(0.0, 1.0, 0.0));
+  float n110 = jgCloudHash13(i + vec3(1.0, 1.0, 0.0));
+  float n001 = jgCloudHash13(i + vec3(0.0, 0.0, 1.0));
+  float n101 = jgCloudHash13(i + vec3(1.0, 0.0, 1.0));
+  float n011 = jgCloudHash13(i + vec3(0.0, 1.0, 1.0));
+  float n111 = jgCloudHash13(i + vec3(1.0, 1.0, 1.0));
+  return mix(
+    mix(mix(n000, n100, f.x), mix(n010, n110, f.x), f.y),
+    mix(mix(n001, n101, f.x), mix(n011, n111, f.x), f.y),
+    f.z
+  );
+}
+
+float jgCloudFbm(vec3 p){
+  float v = 0.0;
+  float a = 0.5;
+  for (int i = 0; i < 5; i++) {
+    v += a * jgCloudNoise(p);
+    p = p * 2.03 + vec3(11.3, 7.1, 5.7);
+    a *= 0.5;
+  }
+  return v;
+}
+
+// Density of the cloud slab at a world point: a 3D-FBM puff field carved by a coverage threshold and
+// shaped by a cumulus vertical profile (rounded base, eroded anvil top). 0 outside the slab.
+float jgCloudDensity(vec3 pos){
+  float heightFrac = (pos.y - uBaseHeight) / uThickness;
+  if (heightFrac < 0.0 || heightFrac > 1.0) return 0.0;
+  float profile = smoothstep(0.0, 0.2, heightFrac) * smoothstep(1.0, 0.5, heightFrac);
+  vec3 wind = vec3(uTime * uSpeed, 0.0, uTime * uSpeed * 0.6);
+  vec3 sp = (pos + wind) / uScale;
+  float shape = jgCloudFbm(sp);
+  float threshold = mix(0.62, 0.2, uCoverage);
+  float d = smoothstep(threshold, threshold + 0.3, shape * profile + profile * 0.12);
+  return d * profile * uDensity;
+}
+
+// March a few steps toward the sun and turn the accumulated density into transmittance (Beer's law) —
+// the self-shadowing that gives the clouds volume instead of a flat wash.
+float jgCloudLight(vec3 pos){
+  vec3 ldir = normalize(uSunDirection);
+  float stepL = uThickness * 0.2;
+  float dens = 0.0;
+  vec3 p = pos;
+  for (int i = 0; i < 4; i++) {
+    p += ldir * stepL;
+    dens += jgCloudDensity(p);
+  }
+  return exp(-dens * stepL * 1.6);
+}
+
+void main() {
+  vec3 rayOrigin = uCameraPos;
+  vec3 rayDir = normalize(vJgCloudWorldPos - uCameraPos);
+  if (rayDir.y < 0.015) discard;
+
+  float tBottom = (uBaseHeight - rayOrigin.y) / rayDir.y;
+  float tTop = (uBaseHeight + uThickness - rayOrigin.y) / rayDir.y;
+  float tNear = max(min(tBottom, tTop), 0.0);
+  float tFar = max(tBottom, tTop);
+  if (tFar <= tNear) discard;
+  tFar = min(tFar, tNear + uThickness * 6.0);
+
+  const int STEPS = 32;
+  float stepLen = (tFar - tNear) / float(STEPS);
+  float t = tNear + stepLen * 0.5;
+  float transmittance = 1.0;
+  vec3 color = vec3(0.0);
+  float sunDot = max(dot(rayDir, normalize(uSunDirection)), 0.0);
+  float silver = pow(sunDot, 5.0) * uSunScatter;
+
+  for (int i = 0; i < STEPS; i++) {
+    vec3 pos = rayOrigin + rayDir * t;
+    float dens = jgCloudDensity(pos);
+    if (dens > 0.002) {
+      float light = jgCloudLight(pos);
+      float powder = 1.0 - exp(-dens * 3.0);
+      vec3 lit = mix(uColor, uSunColor, light) * (0.55 + 0.45 * powder) + uSunColor * silver * 0.5;
+      float dt = dens * stepLen * 1.3;
+      float a = 1.0 - exp(-dt);
+      color += transmittance * a * lit;
+      transmittance *= 1.0 - a;
+      if (transmittance < 0.02) break;
+    }
+    t += stepLen;
+  }
+
+  float alpha = (1.0 - transmittance) * smoothstep(0.015, 0.22, rayDir.y);
+  if (alpha < 0.01) discard;
+  gl_FragColor = vec4(color, alpha);
+}
+`;
+/**
+ * A raymarched volumetric cloud slab: a large horizontal box straddling `[height, height+thickness]`,
+ * following the camera in XZ (like `SkyDome`), whose fragment shader raymarches 3D FBM noise inside
+ * the slab and accumulates density-weighted color with a sun-facing forward-scatter term. Mounted
+ * from `Daylight`/`SkyDaylight`/`TimeOfDayDaylight` whenever a sky descriptor carries
+ * `volumetricClouds`; off by default (the component itself is simply not rendered). A game never
+ * mounts this directly — author clouds via `sky({ volumetricClouds })`.
+ * @internal
+ */
+export function VolumetricClouds({ rules, sunDirection }) {
+    const meshRef = useRef(null);
+    const timeRef = useRef(0);
+    const material = useMemo(() => {
+        return new THREE.ShaderMaterial({
+            uniforms: {
+                uCameraPos: { value: new THREE.Vector3() },
+                uColor: { value: new THREE.Color(rules.color) },
+                uSunColor: { value: new THREE.Color(rules.sunColor) },
+                uSunDirection: { value: normalizeVec3(sunDirection) },
+                uSunScatter: { value: rules.sunScatter },
+                uCoverage: { value: rules.coverage },
+                uDensity: { value: rules.density },
+                uBaseHeight: { value: rules.height },
+                uThickness: { value: rules.thickness },
+                uScale: { value: rules.scale },
+                uSpeed: { value: rules.speed },
+                uTime: { value: 0 },
+                uSeedOffset: { value: hashSeed(rules.seed) },
+            },
+            vertexShader: CLOUD_VERTEX_SHADER,
+            fragmentShader: CLOUD_FRAGMENT_SHADER,
+            transparent: true,
+            depthWrite: false,
+            side: THREE.BackSide,
+            fog: false,
+        });
+    }, [rules, sunDirection]);
+    useEffect(() => () => material.dispose(), [material]);
+    useFrame((state, delta) => {
+        timeRef.current += delta;
+        const mesh = meshRef.current;
+        if (mesh !== null) {
+            mesh.position.x = state.camera.position.x;
+            mesh.position.z = state.camera.position.z;
+        }
+        const uniforms = material.uniforms;
+        uniforms.uCameraPos.value.copy(state.camera.position);
+        uniforms.uTime.value = timeRef.current;
+    });
+    return (_jsx("mesh", { ref: meshRef, material: material, renderOrder: -0.5, frustumCulled: false, children: _jsx("sphereGeometry", { args: [INSIDE_FRUSTUM_DOME_RADIUS, 32, 16] }) }));
+}

package/dist/environment/daylightCycle.d.ts

@@ -17,10 +17,12 @@ export declare const DEFAULT_DAY_AMBIENT_INTENSITY = 0.6;
 export declare const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
 export declare const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
 export declare const SKY_PRESET_DAY_FRACTION: Record<"day" | "dusk" | "night", number>;
+/** @internal */
 export declare function lerpHexColor(a: string, b: string, t: number): string;
 /**
  * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
  * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
  * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
- */
+  * @internal
+  */
 export declare function daylightStateAt(dayFraction: number, config?: DaylightCycleConfig): DaylightState;

package/dist/environment/daylightCycle.js

@@ -38,6 +38,7 @@ function clampByte(value) {
 function rgbToHex(rgb) {
     return `#${rgb.map((channel) => clampByte(channel).toString(16).padStart(2, "0")).join("")}`;
 }
+/** @internal */
 export function lerpHexColor(a, b, t) {
     const [ar, ag, ab] = hexToRgb(a);
     const [br, bg, bb] = hexToRgb(b);
@@ -95,7 +96,8 @@ function segmentAt(wrapped, keyframes) {
  * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
  * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
  * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
- */
+  * @internal
+  */
 export function daylightStateAt(dayFraction, config = {}) {
     const wrapped = wrapFraction(dayFraction);
     const keyframes = buildKeyframes(config);

package/dist/environment/groundPadMath.d.ts

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

package/dist/environment/groundPadMath.js

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

package/dist/environment/index.d.ts

@@ -1,4 +1,5 @@
 export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDaylightProps, type SkyDomeProps, type TimeOfDayDaylightProps, } from "./Daylight.js";
 export { EnvironmentScene, type EnvironmentSceneProps } from "./EnvironmentScene.js";
+export { VolumetricClouds, type VolumetricCloudsProps } from "./VolumetricClouds.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,4 +1,5 @@
 export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, } from "./Daylight.js";
 export { EnvironmentScene } from "./EnvironmentScene.js";
+export { VolumetricClouds } from "./VolumetricClouds.js";
 export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, } from "./daylightCycle.js";
 export { resolveSkyLightOwnership, skyEmitsLights, } from "./skyLightingPolicy.js";

package/dist/environment/skyLightingPolicy.d.ts

@@ -6,5 +6,7 @@
  * sky-owned lights when the game did not author lighting).
  */
 export type SkyLightOwnership = "authored" | "sky-default";
+/** @internal */
 export declare function resolveSkyLightOwnership(hasAuthoredLighting: boolean): SkyLightOwnership;
+/** @internal */
 export declare function skyEmitsLights(ownership: SkyLightOwnership): boolean;

package/dist/environment/skyLightingPolicy.js

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

package/dist/hotbarActions.d.ts

@@ -0,0 +1,26 @@
+import { type ActionCodesMap } from "@jgengine/core/input/actionBindings";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+type Inventories = Record<string, {
+    hud?: string;
+}>;
+/** Minimal playable slice — avoids coupling to shell vs core PlayableGame generics. @internal */
+export type HotbarPlayable = {
+    game: {
+        inventories?: Inventories;
+        input?: ActionCodesMap;
+    };
+};
+/** @internal Map bound action names to hotbar slot indices. */
+export declare function findHotbarSlotActions(input: ActionCodesMap | undefined): {
+    action: string;
+    slot: number;
+}[];
+/** @internal Resolve the inventory id used as the hotbar HUD binding. */
+export declare function hotbarIdFor(playable: HotbarPlayable): string | null;
+/** @internal Activate an item from a hotbar slot via `ctx.item.use`. */
+export declare function executeHotbarSlot(ctx: GameContext, fromId: string, hotbarId: string, slot: number, yaw: number, pitch: number, aimOverride?: Aim): {
+    ok: boolean;
+    error?: string;
+};
+export {};

package/dist/hotbarActions.js

@@ -0,0 +1,27 @@
+import { hotbarSlotActionIndex } from "@jgengine/core/input/actionBindings";
+/** @internal Map bound action names to hotbar slot indices. */
+export function findHotbarSlotActions(input) {
+    return Object.keys(input ?? {}).flatMap((action) => {
+        const slot = hotbarSlotActionIndex(action);
+        return slot === null ? [] : [{ action, slot }];
+    });
+}
+/** @internal Resolve the inventory id used as the hotbar HUD binding. */
+export function hotbarIdFor(playable) {
+    const declarations = Object.entries(playable.game.inventories ?? {});
+    const hud = declarations.find(([, declaration]) => declaration.hud === "hotbar");
+    return (hud ?? declarations[0])?.[0] ?? null;
+}
+/** @internal Activate an item from a hotbar slot via `ctx.item.use`. */
+export function executeHotbarSlot(ctx, fromId, hotbarId, slot, yaw, pitch, aimOverride) {
+    const stack = ctx.player.inventory.state(hotbarId).slots[slot];
+    if (stack === undefined || stack === null)
+        return { ok: false, error: `Hotbar slot ${slot + 1} is empty` };
+    const result = ctx.item.use.use({
+        from: fromId,
+        itemId: stack.itemId,
+        inventoryId: hotbarId,
+        aim: aimOverride ?? { yaw, pitch },
+    });
+    return result.error === undefined ? { ok: true } : { ok: false, error: result.error };
+}

package/dist/inputSink.d.ts

@@ -4,15 +4,27 @@ import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
 export interface InputSink {
     send(frame: InputFrame): void;
 }
-/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself. */
+/** 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 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.
+ * @internal
+ */
 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. */
+/** 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.
+ * @internal
+ */
 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. */
+/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing.
+ * @internal
+ */
 export declare function inputFramesEqual(a: InputFrame, b: InputFrame): boolean;

package/dist/inputSink.js

@@ -1,26 +1,76 @@
 import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
-/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself. */
+/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself.
+ * @internal
+ */
 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}. */
+const remoteInputSources = new Map();
+function remoteInputSourceFor(serverId) {
+    let source = remoteInputSources.get(serverId);
+    if (source === undefined) {
+        source = { pending: null, inFlight: false };
+        remoteInputSources.set(serverId, source);
+    }
+    return source;
+}
+function monotonicInputSeq() {
+    return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function pumpRemoteInput(backend, serverId, source) {
+    if (source.inFlight)
+        return;
+    const frame = source.pending;
+    if (frame === null) {
+        remoteInputSources.delete(serverId);
+        return;
+    }
+    source.pending = null;
+    source.inFlight = true;
+    const seq = monotonicInputSeq();
+    void backend.transport
+        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...frame, seq } })
+        .then((result) => {
+        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;
+        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.
+ * @internal
+ */
 export function remoteInputSink(backend, serverId) {
     return {
         send(frame) {
-            void backend.transport
-                .runCommand({ serverId, command: INPUT_COMMAND, input: frame })
-                .catch(() => undefined);
+            const source = remoteInputSourceFor(serverId);
+            source.pending = frame;
+            pumpRemoteInput(backend, serverId, source);
         },
     };
 }
-/** 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. */
+/** 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.
+ * @internal
+ */
 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. */
+/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing.
+ * @internal
+ */
 export function inputFramesEqual(a, b) {
     if (a.held.length !== b.held.length)
         return false;

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

@@ -29,16 +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") {
         const url = args.url ?? adapter.url;
-        if (url === undefined && isServerAuthoritative(args.game.multiplayer))
+        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) {