@jgengine/shell 0.9.0 → 0.11.0

package/dist/environment/EnvironmentScene.js

@@ -1,22 +1,48 @@
 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 { 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";
-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";
 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(() => {
-        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 +60,15 @@ 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 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(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];
@@ -56,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}`))) }));
@@ -110,5 +144,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/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

@@ -0,0 +1,30 @@
+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.
+ * @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 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.
+ * @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.
+ * @internal
+ */
+export declare function inputFramesEqual(a: InputFrame, b: InputFrame): boolean;

package/dist/inputSink.js

@@ -0,0 +1,85 @@
+import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
+/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself.
+ * @internal
+ */
+export function noopInputSink() {
+    return { send() { } };
+}
+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) {
+            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.
+ * @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.
+ * @internal
+ */
+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;
+}