@jgengine/shell 0.9.0 → 0.10.0

package/dist/camera/GameFirstPersonCamera.js

@@ -2,13 +2,25 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import * as THREE from "three";
+import { DEFAULT_EYE_HEIGHT } from "@jgengine/core/combat/shotOrigin";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
 import { usePlayerFov } from "./PlayerFov.js";
 import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
-const DEFAULT_EYE_HEIGHT = 1.6;
 const DEFAULT_SENSITIVITY = 0.0025;
 const DEFAULT_MAX_PITCH = 1.45;
+const VIEWMODEL_ORIGIN = new THREE.Vector3(0.34, -0.26, -0.72);
+const MUZZLE_TIP_LOCAL = new THREE.Vector3(0, 0.03, -0.61);
+const MUZZLE_OFFSET = VIEWMODEL_ORIGIN.clone().add(MUZZLE_TIP_LOCAL);
+const muzzleWorld = new THREE.Vector3();
+let muzzleTracked = false;
+/** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
+export function readFirstPersonMuzzle(target) {
+    if (!muzzleTracked)
+        return false;
+    target.copy(muzzleWorld);
+    return true;
+}
 export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }) {
     const eyeHeight = config?.eyeHeight ?? DEFAULT_EYE_HEIGHT;
     const sensitivity = config?.sensitivity ?? DEFAULT_SENSITIVITY;
@@ -65,15 +77,20 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
 }
 function FirstPersonViewmodel({ camera }) {
     const groupRef = useRef(null);
+    useEffect(() => () => {
+        muzzleTracked = false;
+    }, []);
     useFrame(() => {
         const group = groupRef.current;
         if (group === null)
             return;
         group.position.copy(camera.position);
         group.quaternion.copy(camera.quaternion);
-        group.translateX(0.34);
-        group.translateY(-0.26);
-        group.translateZ(-0.72);
+        group.translateX(VIEWMODEL_ORIGIN.x);
+        group.translateY(VIEWMODEL_ORIGIN.y);
+        group.translateZ(VIEWMODEL_ORIGIN.z);
+        muzzleWorld.copy(MUZZLE_OFFSET).applyQuaternion(camera.quaternion).add(camera.position);
+        muzzleTracked = true;
     }, GAME_SIM_FRAME_PRIORITY);
     return (_jsxs("group", { ref: groupRef, children: [_jsxs("mesh", { position: [0, 0, -0.22], children: [_jsx("boxGeometry", { args: [0.09, 0.11, 0.55] }), _jsx("meshStandardMaterial", { color: "#22262d", metalness: 0.6, roughness: 0.35 })] }), _jsxs("mesh", { position: [0, -0.13, 0.04], rotation: [0.35, 0, 0], children: [_jsx("boxGeometry", { args: [0.08, 0.18, 0.11] }), _jsx("meshStandardMaterial", { color: "#33373f", metalness: 0.4, roughness: 0.5 })] }), _jsxs("mesh", { position: [0, 0.03, -0.52], rotation: [Math.PI / 2, 0, 0], children: [_jsx("cylinderGeometry", { args: [0.022, 0.022, 0.18, 10] }), _jsx("meshStandardMaterial", { color: "#0e0f12", metalness: 0.7, roughness: 0.3 })] })] }));
 }

package/dist/camera/GameInspectionCamera.js

@@ -20,5 +20,16 @@ export function GameInspectionCamera({ config: configPatch }) {
         controlsRef.current?.update();
         seededRef.current = true;
     }, [camera, config]);
-    return (_jsx(OrbitControls, { ref: controlsRef, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, zoomToCursor: resolveInspectionZoomToCursor(config.anchor), enablePan: config.pan, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, minPolarAngle: config.minPolarAngle, maxPolarAngle: config.maxPolarAngle, screenSpacePanning: true, mouseButtons: { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.PAN, RIGHT: MOUSE.PAN } }));
+    useEffect(() => {
+        if (!seededRef.current)
+            return;
+        const controls = controlsRef.current;
+        if (controls === null)
+            return;
+        const previous = controls.target.clone();
+        controls.target.set(config.target.x, config.target.y, config.target.z);
+        camera.position.add(controls.target.clone().sub(previous));
+        controls.update();
+    }, [camera, config.target.x, config.target.y, config.target.z]);
+    return (_jsx(OrbitControls, { ref: controlsRef, makeDefault: true, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, zoomToCursor: resolveInspectionZoomToCursor(config.anchor), enablePan: config.pan, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, minPolarAngle: config.minPolarAngle, maxPolarAngle: config.maxPolarAngle, screenSpacePanning: true, mouseButtons: { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.PAN, RIGHT: MOUSE.PAN } }));
 }

package/dist/camera/GameOrbitCamera.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { OrbitControls } from "@react-three/drei";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
-import { MOUSE, PerspectiveCamera, Vector3 } from "three";
+import { MOUSE, PerspectiveCamera, Raycaster, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
 import { cameraLookPitch, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
@@ -16,6 +16,10 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
     const ctx = useGameContext();
     const playerFov = usePlayerFov();
     const camera = useThree((state) => state.camera);
+    const scene = useThree((state) => state.scene);
+    const raycasterRef = useRef(new Raycaster());
+    const collisionDirRef = useRef(new Vector3());
+    const collisionOriginRef = useRef(new Vector3());
     const followId = followEntityId ?? userId;
     useEffect(() => {
         const entity = ctx.scene.entity.get(followId);
@@ -56,6 +60,36 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
             camera.position.set(stepped.camera.x, stepped.camera.y, stepped.camera.z);
         }
         controls.update();
+        if (config.collision.enabled) {
+            const t = stepped.target;
+            const dx = camera.position.x - t.x;
+            const dy = camera.position.y - t.y;
+            const dz = camera.position.z - t.z;
+            const dist = Math.hypot(dx, dy, dz);
+            if (dist > config.collision.minTargetDistance) {
+                const dir = collisionDirRef.current.set(dx / dist, dy / dist, dz / dist);
+                const ray = raycasterRef.current;
+                ray.set(collisionOriginRef.current.set(t.x, t.y, t.z), dir);
+                ray.near = config.collision.minTargetDistance;
+                ray.far = dist;
+                let blocked = 0;
+                for (const hit of ray.intersectObjects(scene.children, true)) {
+                    const obj = hit.object;
+                    if (!obj.visible)
+                        continue;
+                    if (obj.isSprite === true)
+                        continue;
+                    if (obj.userData.jgCameraTransparent === true)
+                        continue;
+                    blocked = hit.distance;
+                    break;
+                }
+                if (blocked > 0) {
+                    const pulled = Math.max(config.collision.minTargetDistance, blocked - config.collision.padding);
+                    camera.position.set(t.x + dir.x * pulled, t.y + dir.y * pulled, t.z + dir.z * pulled);
+                }
+            }
+        }
         runtimeRef.current = {
             target: stepped.target,
             camera: { x: camera.position.x, y: camera.position.y, z: camera.position.z },

package/dist/camera/orbitCameraMath.d.ts

@@ -39,6 +39,23 @@ export interface OrbitCameraConfig {
     /** Vertical clamp (three.js polar angle, radians): 0 = top-down over the head, PI/2 = level, >PI/2 = look up from below the target. Widen to allow top-down or vertical aim; leave unset for the standard chase feel. */
     minPolarAngle?: number;
     maxPolarAngle?: number;
+    /** Spring-arm collision: raycast target→camera each frame and pull the boom in past occluders (walls, terrain) so the camera never clips inside geometry. */
+    collision?: OrbitCollisionConfig;
+}
+/** Spring-arm occlusion config for the orbit rig. */
+export interface OrbitCollisionConfig {
+    /** Enable the pull-in raycast. Default false (unchanged chase camera). */
+    enabled?: boolean;
+    /** Gap kept between the camera and the hit surface, world units. Default 0.35. */
+    padding?: number;
+    /** Ignore hits closer than this to the target — the player's own body. Default 1.2. */
+    minTargetDistance?: number;
+}
+/** An {@link OrbitCollisionConfig} with every field resolved to a concrete value. */
+export interface ResolvedOrbitCollision {
+    enabled: boolean;
+    padding: number;
+    minTargetDistance: number;
 }
 /** Fully resolved shell config after merging with DEFAULT_ORBIT_CAMERA. */
 export interface ResolvedOrbitCameraConfig {
@@ -58,6 +75,7 @@ export interface ResolvedOrbitCameraConfig {
     distanceSmoothing: number;
     minPolarAngle: number;
     maxPolarAngle: number;
+    collision: ResolvedOrbitCollision;
 }
 export declare const DEFAULT_ORBIT_CAMERA: ResolvedOrbitCameraConfig;
 /** Run simulation/movement before orbit follow so poses are current. */

package/dist/camera/orbitCameraMath.js

@@ -25,6 +25,7 @@ export const DEFAULT_ORBIT_CAMERA = {
     distanceSmoothing: 5,
     minPolarAngle: 0.12,
     maxPolarAngle: Math.PI / 2.05,
+    collision: { enabled: false, padding: 0.35, minTargetDistance: 1.2 },
 };
 /** Run simulation/movement before orbit follow so poses are current. */
 export const GAME_SIM_FRAME_PRIORITY = 0;
@@ -35,7 +36,11 @@ export function smoothBlend(deltaSeconds, speed) {
     return 1 - Math.exp(-speed * deltaSeconds);
 }
 export function resolveOrbitCameraConfig(patch) {
-    return { ...DEFAULT_ORBIT_CAMERA, ...patch };
+    return {
+        ...DEFAULT_ORBIT_CAMERA,
+        ...patch,
+        collision: { ...DEFAULT_ORBIT_CAMERA.collision, ...patch?.collision },
+    };
 }
 export function resolveTargetSmoothing(config, dragging) {
     if (dragging) {

package/dist/cartridge.js

@@ -229,6 +229,7 @@ export function cartridge(config) {
     return defineGame({
         name: config.name,
         assets: config.assets,
+        features: { leaderboard: config.rules.killLeaderboardStat !== undefined },
         world: config.world,
         physics: config.physics,
         input: config.input ?? WASD_KEYBINDS,

package/dist/commandSink.d.ts

@@ -0,0 +1,20 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
+/** Where a gameplay command goes when the shell dispatches it — run locally, or sent to the authoritative host. */
+export interface CommandSink {
+    run(name: string, input: unknown): void;
+}
+/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+export declare function localCommandSink(ctx: GameContext): CommandSink;
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+export declare function remoteCommandSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): CommandSink;
+/**
+ * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
+ * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
+ * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ */
+export declare function resolveCommandSink(ctx: GameContext, opts: {
+    serverAuthoritative: boolean;
+    backend: Pick<LiveGameBackend, "transport"> | null;
+    serverId: string | null;
+}): CommandSink;

package/dist/commandSink.js

@@ -0,0 +1,27 @@
+/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+export function localCommandSink(ctx) {
+    return {
+        run(name, input) {
+            ctx.game.commands.run(name, input);
+        },
+    };
+}
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+export function remoteCommandSink(backend, serverId) {
+    return {
+        run(name, input) {
+            void backend.transport.runCommand({ serverId, command: name, input }).catch(() => undefined);
+        },
+    };
+}
+/**
+ * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
+ * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
+ * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ */
+export function resolveCommandSink(ctx, opts) {
+    if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
+        return remoteCommandSink(opts.backend, opts.serverId);
+    }
+    return localCommandSink(ctx);
+}

package/dist/defineGame.js

@@ -10,7 +10,7 @@ function worldBackdrop(feature) {
 }
 const emptyUi = () => null;
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, shadows, presentation, objectStyles, devtools, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, ...engineFields } = config;
     const game = defineEngineGame({ ...engineFields, multiplayer: multiplayer ?? offline() });
     return {
         game,
@@ -19,6 +19,7 @@ export function defineGame(config) {
             onInit: loop?.onInit ?? noop,
             onNewPlayer: loop?.onNewPlayer ?? noop,
             onTick: loop?.onTick ?? noop,
+            onPlayerLeave: loop?.onPlayerLeave ?? noop,
         },
         GameUI: GameUI ?? emptyUi,
         environment: environment ??
@@ -44,6 +45,7 @@ export function defineGame(config) {
         movement,
         lighting,
         backdrop,
+        postProcessing,
         shadows,
         presentation,
         objectStyles,

package/dist/devtools/CollisionDebugWorld.js

@@ -136,6 +136,7 @@ export function CollisionDebugWorld() {
                     },
                     positionOf: (id) => ctx.scene.entity.get(id)?.position,
                     rotationYOf: (id) => ctx.scene.entity.get(id)?.rotationY,
+                    collidersOf: (id) => ctx.scene.entity.collidersOf(id),
                     from: probe.from,
                     aim: probe.aim,
                     originPolicy: probe.originPolicy,

package/dist/devtools/collisionDebugMath.d.ts

@@ -75,6 +75,7 @@ export interface ComputeAimLaserInput {
     sceneRaycast: SceneRaycastApi;
     positionOf(instanceId: string): EntityPosition | undefined;
     rotationYOf?(instanceId: string): number | undefined;
+    collidersOf?(instanceId: string): EntityColliderSet | null | undefined;
     from: string;
     aim: Aim;
     originPolicy?: ShotOriginPolicy;

package/dist/devtools/collisionDebugMath.js

@@ -91,7 +91,8 @@ export function computeAimLaser(input) {
     const resolved = resolveShot({
         positionOf: input.positionOf,
         rotationYOf: input.rotationYOf,
-    }, input.from, input.aim, input.originPolicy ?? { kind: "legacy" });
+        collidersOf: input.collidersOf,
+    }, input.from, input.aim, input.originPolicy ?? { kind: "eye" });
     if (resolved === null)
         return null;
     input.counters !== undefined && (input.counters.queries += 1);

package/dist/environment/Daylight.d.ts

@@ -7,10 +7,16 @@ export interface SkyDomeProps {
     radius?: number;
     offset?: number;
     exponent?: number;
+    /** Direction toward the sun; a bright HDR sun disc + warm glow is drawn there (blooms through the post chain). Omit to skip the sun. */
+    sunDirection?: readonly [number, number, number];
+    /** Sun disc/glow colour. Default warm white. */
+    sunColor?: string;
+    /** Sun disc/glow intensity multiplier. Default 1. */
+    sunIntensity?: number;
     /** Exposes the created shader material so a time-of-day driver can mutate its uniforms per frame without recreating it. */
     materialRef?: MutableRefObject<THREE.ShaderMaterial | null>;
 }
-export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
+export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
 export interface DaylightProps {
     sky?: SkyDomeProps | false;
     fog?: {

package/dist/environment/Daylight.js

@@ -3,13 +3,36 @@ import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { daylightStateAt, SKY_PRESET_DAY_FRACTION } from "./daylightCycle.js";
+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 SKY_TOP = "#3fa4f2";
 const SKY_HORIZON = "#e3f4ff";
 const FOG_COLOR = "#e9f6ff";
 const SUN_COLOR = "#fff1c9";
 const HEMI_SKY = "#bfe3ff";
 const HEMI_GROUND = "#4c6b34";
-export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, materialRef, } = {}) {
+/**
+ * Sun directional light whose high-resolution shadow camera follows the view each
+ * frame, so grounded shadows stay crisp under the player anywhere in a large world
+ * instead of only near the origin.
+ */
+function ShadowCastingSun({ position, intensity, color, }) {
+    const ref = useRef(null);
+    useFrame((state) => {
+        const light = ref.current;
+        if (light === null)
+            return;
+        const cx = state.camera.position.x;
+        const cz = state.camera.position.z;
+        light.position.set(cx + position[0], position[1], cz + position[2]);
+        light.target.position.set(cx, 0, cz);
+        light.target.updateMatrixWorld();
+    });
+    return (_jsx("directionalLight", { ref: ref, position: [position[0], position[1], position[2]], intensity: intensity, color: color, castShadow: true, "shadow-mapSize-width": 2048, "shadow-mapSize-height": 2048, "shadow-camera-left": -90, "shadow-camera-right": 90, "shadow-camera-top": 90, "shadow-camera-bottom": -90, "shadow-camera-near": 10, "shadow-camera-far": 520, "shadow-bias": -0.0004, "shadow-normalBias": 0.02 }));
+}
+export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, sunDirection, sunColor = "#fff4d6", sunIntensity = 1, materialRef, } = {}) {
     const material = useMemo(() => {
         return new THREE.ShaderMaterial({
             uniforms: {
@@ -17,6 +40,9 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                 bottomColor: { value: new THREE.Color(horizonColor) },
                 offset: { value: offset },
                 exponent: { value: exponent },
+                uSunColor: { value: new THREE.Color(sunColor) },
+                uSunDirection: { value: sunDirection === undefined ? new THREE.Vector3(0, 1, 0) : normalizeVec3(sunDirection) },
+                uSunIntensity: { value: sunDirection === undefined ? 0 : sunIntensity },
             },
             vertexShader: `
         varying vec3 vWorldPosition;
@@ -29,19 +55,40 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
             fragmentShader: `
         uniform vec3 topColor;
         uniform vec3 bottomColor;
+        uniform vec3 uSunColor;
+        uniform vec3 uSunDirection;
+        uniform float uSunIntensity;
         uniform float offset;
         uniform float exponent;
         varying vec3 vWorldPosition;
+        float sHash(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+        float sNoise(vec2 p){
+          vec2 i = floor(p); vec2 f = fract(p); vec2 u = f * f * (3.0 - 2.0 * f);
+          return mix(mix(sHash(i), sHash(i + vec2(1.0, 0.0)), u.x),
+                     mix(sHash(i + vec2(0.0, 1.0)), sHash(i + vec2(1.0, 1.0)), u.x), u.y);
+        }
+        float sFbm(vec2 p){ float v = 0.0; float a = 0.5; for (int i = 0; i < 5; i++){ v += a * sNoise(p); p *= 2.0; a *= 0.5; } return v; }
         void main() {
-          float h = normalize(vWorldPosition + vec3(0.0, offset, 0.0)).y;
-          gl_FragColor = vec4(mix(bottomColor, topColor, max(pow(max(h, 0.0), exponent), 0.0)), 1.0);
+          vec3 dir = normalize(vWorldPosition + vec3(0.0, offset, 0.0));
+          float h = max(dir.y, 0.0);
+          vec3 col = mix(bottomColor, topColor, pow(h, exponent));
+          col = mix(col, bottomColor * 1.12, pow(1.0 - h, 6.0) * 0.5);
+          vec3 vd = normalize(vWorldPosition);
+          vec2 cuv = vd.xz / (max(vd.y, 0.06) + 0.15) * 1.2;
+          float clouds = smoothstep(0.52, 0.82, sFbm(cuv));
+          float band = smoothstep(0.08, 0.35, dir.y) * smoothstep(1.0, 0.35, dir.y);
+          col = mix(col, mix(topColor, vec3(1.0), 0.6), clouds * band * 0.35);
+          float sd = max(dot(vd, normalize(uSunDirection)), 0.0);
+          float glow = pow(sd, 8.0) * 0.35 + pow(sd, 128.0) * 2.6;
+          col += uSunColor * glow * uSunIntensity;
+          gl_FragColor = vec4(col, 1.0);
         }
       `,
             side: THREE.BackSide,
             depthWrite: false,
             fog: false,
         });
-    }, [topColor, horizonColor, offset, exponent]);
+    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity]);
     useEffect(() => {
         if (materialRef !== undefined)
             materialRef.current = material;
@@ -55,7 +102,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
 }
 export function Daylight({ sky, fog, sun, ambient, lights = true } = {}) {
     const sunPosition = sun?.position ?? [120, 160, 70];
-    return (_jsxs(_Fragment, { children: [sky === false ? null : _jsx(SkyDome, { ...(sky ?? {}) }), fog === false ? null : (_jsx("fog", { attach: "fog", args: [fog?.color ?? FOG_COLOR, fog?.near ?? 70, fog?.far ?? 260] })), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx("directionalLight", { position: [sunPosition[0], sunPosition[1], sunPosition[2]], intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR, castShadow: true })] })) : null] }));
+    return (_jsxs(_Fragment, { children: [sky === false ? null : (_jsx(SkyDome, { ...(sky ?? {}), sunDirection: sunPosition, sunColor: sun?.color ?? SUN_COLOR, sunIntensity: sun?.intensity ?? 1 })), fog === false ? null : (_jsx("fog", { attach: "fog", args: [fog?.color ?? FOG_COLOR, fog?.near ?? 70, fog?.far ?? 260] })), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx(ShadowCastingSun, { position: sunPosition, intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR })] })) : null] }));
 }
 /** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
 export function SkyDaylight({ sky, lights = true }) {

package/dist/environment/EnvironmentScene.js

@@ -1,14 +1,16 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef } 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 { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
+import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { GroundPad } from "./GroundPad.js";
+import { RoadRibbons } from "./RoadRibbons.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.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";
@@ -16,7 +18,9 @@ import { WeatherUniformProvider } from "../weather/weatherUniforms.js";
 function TerrainGround({ terrain, field, center, }) {
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
     const paletteAt = useMemo(() => {
-        if (terrain.materialRegions === undefined || terrain.materialRegions.length === 0)
+        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)
@@ -34,7 +38,11 @@ function TerrainGround({ terrain, field, center, }) {
         const swing = terrain.height * 1.2;
         return [base - swing, base + swing];
     }, [terrain.baseHeight, terrain.height]);
-    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94 }));
+    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];
@@ -110,5 +118,6 @@ export function EnvironmentScene({ feature }) {
     const structures = feature.structures ?? [];
     const pads = feature.pads ?? [];
     const islands = feature.islands ?? [];
-    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}`))), 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 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/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/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/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;