@jgengine/shell 0.10.0 → 0.12.0

package/dist/water/OceanMaterial.js

@@ -1,6 +1,8 @@
 import * as THREE from "three";
 import { buildOceanWaveUniforms } from "./OceanConfig.js";
 import { oceanFragmentShader, oceanVertexShader } from "./OceanShader.js";
+/** Matches the day-sky sun heading closely enough for stylized glints — not a lighting contract. */
+const OCEAN_SUN_DIRECTION = new THREE.Vector3(0.45, 0.78, 0.35).normalize();
 export function createOceanMaterial(config) {
     const material = new THREE.ShaderMaterial({
         vertexShader: oceanVertexShader,
@@ -24,6 +26,10 @@ export function createOceanMaterial(config) {
             uFoamSoftness: { value: config.foam.softness },
             uFoamIntensity: { value: config.foam.intensity },
             uFoamCoverage: { value: config.foam.coverage },
+            uDepthRange: { value: config.color.depthRange },
+            uShoreFoamWidth: { value: config.foam.shoreWidth },
+            uSparkle: { value: config.color.sparkle },
+            uSunDirection: { value: OCEAN_SUN_DIRECTION.clone() },
         },
     });
     syncOceanMaterial(material, config, 0);
@@ -46,6 +52,9 @@ export function syncOceanMaterial(material, config, elapsedSeconds) {
     material.uniforms.uFoamSoftness.value = config.foam.softness;
     material.uniforms.uFoamIntensity.value = config.foam.intensity;
     material.uniforms.uFoamCoverage.value = config.foam.coverage;
+    material.uniforms.uDepthRange.value = config.color.depthRange;
+    material.uniforms.uShoreFoamWidth.value = config.foam.shoreWidth;
+    material.uniforms.uSparkle.value = config.color.sparkle;
     material.transparent = config.color.opacity < 1;
     material.depthWrite = config.color.opacity >= 0.98;
 }

package/dist/water/OceanShader.d.ts

@@ -1,2 +1,2 @@
-export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float slopeTerm = horizontal * k * sine;\n    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);\n    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
-export declare const oceanFragmentShader = "\nuniform vec3 uShallowColor;\nuniform vec3 uDeepColor;\nuniform vec3 uCrestColor;\nuniform vec3 uFoamColor;\nuniform float uOpacity;\nuniform float uFresnelStrength;\nuniform float uHorizonBlend;\nuniform float uFoamIntensity;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 normal = normalize(vNormal);\n  vec3 viewDirection = normalize(cameraPosition - vWorldPosition);\n  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.5);\n  float depthMix = smoothstep(-1.8, 1.6, vWaveHeight);\n  vec3 waterColor = mix(uDeepColor, uShallowColor, depthMix);\n  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.28);\n  waterColor = mix(waterColor, vec3(0.86, 0.95, 1.0), fresnel * uFresnelStrength);\n  float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));\n  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend);\n  float foam = clamp(vCrest * uFoamIntensity, 0.0, 1.0);\n  vec3 color = mix(waterColor, uFoamColor, foam);\n  gl_FragColor = vec4(color, uOpacity);\n}\n";
+export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nattribute float aDepth;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\nvarying float vDepth;\nvarying vec2 vOceanUv;\n\nvoid main() {\n  vOceanUv = uv;\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n  // Waves flatten as the bed shoals so swells die at the shoreline instead of clipping it.\n  float depthDamp = smoothstep(0.05, 1.4, aDepth);\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y * depthDamp;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float slopeTerm = horizontal * k * sine;\n    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);\n    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vDepth = aDepth;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
+export declare const oceanFragmentShader = "\nuniform float uTime;\nuniform vec3 uShallowColor;\nuniform vec3 uDeepColor;\nuniform vec3 uCrestColor;\nuniform vec3 uFoamColor;\nuniform float uOpacity;\nuniform float uFresnelStrength;\nuniform float uHorizonBlend;\nuniform float uFoamIntensity;\nuniform float uDepthRange;\nuniform float uShoreFoamWidth;\nuniform float uSparkle;\nuniform vec3 uSunDirection;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\nvarying float vDepth;\nvarying vec2 vOceanUv;\n\nfloat jgWaterHash(vec2 p) {\n  uvec2 q = uvec2(ivec2(floor(p)));\n  uint x = q.x * 1664525u + q.y * 1013904223u;\n  x = (x ^ (x >> 16u)) * 2246822519u;\n  x = (x ^ (x >> 13u)) * 3266489917u;\n  return float(x ^ (x >> 16u)) * (1.0 / 4294967296.0);\n}\n\nfloat jgWaterNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float a = jgWaterHash(i);\n  float b = jgWaterHash(i + vec2(1.0, 0.0));\n  float c = jgWaterHash(i + vec2(0.0, 1.0));\n  float d = jgWaterHash(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\n\nvoid main() {\n  vec3 viewDirection = normalize(cameraPosition - vWorldPosition);\n\n  // Fine scrolling normal perturbation: two counter-drifting noise layers ripple the surface\n  // between the big Gerstner swells.\n  vec2 wp = vWorldPosition.xz;\n  float ripple1 = jgWaterNoise(wp * 1.7 + vec2(uTime * 0.22, uTime * 0.15));\n  float ripple2 = jgWaterNoise(wp * 3.1 - vec2(uTime * 0.17, uTime * 0.26));\n  vec3 normal = normalize(normalize(vNormal) + vec3(ripple1 - 0.5, 0.0, ripple2 - 0.5) * 0.14);\n\n  // Depth-based body color: warm shallows at the shore ramp falling to the deep tone.\n  float depthMix = smoothstep(0.0, max(uDepthRange, 0.001), vDepth);\n  vec3 waterColor = mix(uShallowColor, uDeepColor, depthMix);\n  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.22);\n\n  // Restrained fresnel: a soft sky tint at grazing angles, never a white-out.\n  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 5.0);\n  waterColor = mix(waterColor, vec3(0.62, 0.78, 0.85), min(fresnel * uFresnelStrength, 0.45));\n  float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));\n  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend * 0.6);\n\n  // Sun glints: sparkle where the perturbed normal mirrors the sun, gated by noise so it\n  // twinkles in cells instead of sheening uniformly.\n  vec3 halfway = normalize(viewDirection + normalize(uSunDirection));\n  float glint = pow(max(dot(normal, halfway), 0.0), 150.0);\n  float glintMask = smoothstep(0.68, 0.92, jgWaterNoise(wp * 2.3 + vec2(uTime * 0.4, -uTime * 0.31)));\n  waterColor += vec3(1.0, 0.98, 0.9) * glint * glintMask * uSparkle;\n\n  // Foam: a noise-eaten shoreline lick plus crest foam. A second, larger noise gates whole\n  // stretches of shoreline so foam laps in patches instead of outlining the bank uniformly.\n  float foamNoise = jgWaterNoise(wp * 2.6 + vec2(uTime * 0.28, uTime * 0.2));\n  float foamStretch = smoothstep(0.3, 0.8, jgWaterNoise(wp * 0.33 + vec2(3.7, 9.2) + vec2(uTime * 0.05, 0.0)));\n  float shoreFoam = (1.0 - smoothstep(0.0, max(uShoreFoamWidth, 0.001), vDepth - foamNoise * uShoreFoamWidth * 0.9))\n    * smoothstep(0.25, 0.75, foamNoise) * (0.2 + 0.6 * foamStretch);\n  float crestFoam = clamp(vCrest * uFoamIntensity, 0.0, 1.0) * smoothstep(0.35, 0.75, foamNoise);\n  float foam = clamp(shoreFoam + crestFoam, 0.0, 1.0);\n  vec3 color = mix(waterColor, uFoamColor, foam);\n\n  // Soft shore: the sheet turns glass-clear over the last stretch of shoaling bed, so the\n  // waterline is a blend into the terrain, not a hard tarp edge.\n  float shoreAlpha = smoothstep(0.0, 0.55, vDepth);\n  float alpha = uOpacity * mix(0.35, 1.0, shoreAlpha) + foam * 0.3;\n  // The sheet's own border always dissolves \u2014 a bounded water plane must never end in a\n  // visible straight cut, whatever the bed underneath is doing.\n  float borderDist = min(min(vOceanUv.x, 1.0 - vOceanUv.x), min(vOceanUv.y, 1.0 - vOceanUv.y));\n  alpha *= smoothstep(0.0, 0.045, borderDist);\n  gl_FragColor = vec4(color, clamp(alpha, 0.0, 1.0));\n}\n";

package/dist/water/OceanShader.js

@@ -7,22 +7,29 @@ uniform float uFoamThreshold;
 uniform float uFoamSoftness;
 uniform float uFoamCoverage;
 
+attribute float aDepth;
+
 varying vec3 vWorldPosition;
 varying vec3 vNormal;
 varying float vCrest;
 varying float vWaveHeight;
+varying float vDepth;
+varying vec2 vOceanUv;
 
 void main() {
+  vOceanUv = uv;
   vec3 displaced = position;
   vec3 tangent = vec3(1.0, 0.0, 0.0);
   vec3 bitangent = vec3(0.0, 0.0, 1.0);
   float crest = 0.0;
+  // Waves flatten as the bed shoals so swells die at the shoreline instead of clipping it.
+  float depthDamp = smoothstep(0.05, 1.4, aDepth);
 
   for (int i = 0; i < 6; i++) {
     vec2 direction = normalize(uWaveDirections[i]);
     vec4 wave = uWaveParams[i];
     float k = wave.x;
-    float amplitude = wave.y;
+    float amplitude = wave.y * depthDamp;
     float steepness = wave.z;
     float omega = wave.w;
     float phase = k * dot(direction, position.xz) - omega * uTime;
@@ -41,12 +48,14 @@ void main() {
   vNormal = normalize(cross(bitangent, tangent));
   vCrest = crest;
   vWaveHeight = displaced.y;
+  vDepth = aDepth;
   vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);
   vWorldPosition = worldPosition.xyz;
   gl_Position = projectionMatrix * viewMatrix * worldPosition;
 }
 `;
 export const oceanFragmentShader = `
+uniform float uTime;
 uniform vec3 uShallowColor;
 uniform vec3 uDeepColor;
 uniform vec3 uCrestColor;
@@ -55,24 +64,83 @@ uniform float uOpacity;
 uniform float uFresnelStrength;
 uniform float uHorizonBlend;
 uniform float uFoamIntensity;
+uniform float uDepthRange;
+uniform float uShoreFoamWidth;
+uniform float uSparkle;
+uniform vec3 uSunDirection;
 
 varying vec3 vWorldPosition;
 varying vec3 vNormal;
 varying float vCrest;
 varying float vWaveHeight;
+varying float vDepth;
+varying vec2 vOceanUv;
+
+float jgWaterHash(vec2 p) {
+  uvec2 q = uvec2(ivec2(floor(p)));
+  uint x = q.x * 1664525u + q.y * 1013904223u;
+  x = (x ^ (x >> 16u)) * 2246822519u;
+  x = (x ^ (x >> 13u)) * 3266489917u;
+  return float(x ^ (x >> 16u)) * (1.0 / 4294967296.0);
+}
+
+float jgWaterNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgWaterHash(i);
+  float b = jgWaterHash(i + vec2(1.0, 0.0));
+  float c = jgWaterHash(i + vec2(0.0, 1.0));
+  float d = jgWaterHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
 
 void main() {
-  vec3 normal = normalize(vNormal);
   vec3 viewDirection = normalize(cameraPosition - vWorldPosition);
-  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.5);
-  float depthMix = smoothstep(-1.8, 1.6, vWaveHeight);
-  vec3 waterColor = mix(uDeepColor, uShallowColor, depthMix);
-  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.28);
-  waterColor = mix(waterColor, vec3(0.86, 0.95, 1.0), fresnel * uFresnelStrength);
+
+  // Fine scrolling normal perturbation: two counter-drifting noise layers ripple the surface
+  // between the big Gerstner swells.
+  vec2 wp = vWorldPosition.xz;
+  float ripple1 = jgWaterNoise(wp * 1.7 + vec2(uTime * 0.22, uTime * 0.15));
+  float ripple2 = jgWaterNoise(wp * 3.1 - vec2(uTime * 0.17, uTime * 0.26));
+  vec3 normal = normalize(normalize(vNormal) + vec3(ripple1 - 0.5, 0.0, ripple2 - 0.5) * 0.14);
+
+  // Depth-based body color: warm shallows at the shore ramp falling to the deep tone.
+  float depthMix = smoothstep(0.0, max(uDepthRange, 0.001), vDepth);
+  vec3 waterColor = mix(uShallowColor, uDeepColor, depthMix);
+  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.22);
+
+  // Restrained fresnel: a soft sky tint at grazing angles, never a white-out.
+  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 5.0);
+  waterColor = mix(waterColor, vec3(0.62, 0.78, 0.85), min(fresnel * uFresnelStrength, 0.45));
   float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));
-  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend);
-  float foam = clamp(vCrest * uFoamIntensity, 0.0, 1.0);
+  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend * 0.6);
+
+  // Sun glints: sparkle where the perturbed normal mirrors the sun, gated by noise so it
+  // twinkles in cells instead of sheening uniformly.
+  vec3 halfway = normalize(viewDirection + normalize(uSunDirection));
+  float glint = pow(max(dot(normal, halfway), 0.0), 150.0);
+  float glintMask = smoothstep(0.68, 0.92, jgWaterNoise(wp * 2.3 + vec2(uTime * 0.4, -uTime * 0.31)));
+  waterColor += vec3(1.0, 0.98, 0.9) * glint * glintMask * uSparkle;
+
+  // Foam: a noise-eaten shoreline lick plus crest foam. A second, larger noise gates whole
+  // stretches of shoreline so foam laps in patches instead of outlining the bank uniformly.
+  float foamNoise = jgWaterNoise(wp * 2.6 + vec2(uTime * 0.28, uTime * 0.2));
+  float foamStretch = smoothstep(0.3, 0.8, jgWaterNoise(wp * 0.33 + vec2(3.7, 9.2) + vec2(uTime * 0.05, 0.0)));
+  float shoreFoam = (1.0 - smoothstep(0.0, max(uShoreFoamWidth, 0.001), vDepth - foamNoise * uShoreFoamWidth * 0.9))
+    * smoothstep(0.25, 0.75, foamNoise) * (0.2 + 0.6 * foamStretch);
+  float crestFoam = clamp(vCrest * uFoamIntensity, 0.0, 1.0) * smoothstep(0.35, 0.75, foamNoise);
+  float foam = clamp(shoreFoam + crestFoam, 0.0, 1.0);
   vec3 color = mix(waterColor, uFoamColor, foam);
-  gl_FragColor = vec4(color, uOpacity);
+
+  // Soft shore: the sheet turns glass-clear over the last stretch of shoaling bed, so the
+  // waterline is a blend into the terrain, not a hard tarp edge.
+  float shoreAlpha = smoothstep(0.0, 0.55, vDepth);
+  float alpha = uOpacity * mix(0.35, 1.0, shoreAlpha) + foam * 0.3;
+  // The sheet's own border always dissolves — a bounded water plane must never end in a
+  // visible straight cut, whatever the bed underneath is doing.
+  float borderDist = min(min(vOceanUv.x, 1.0 - vOceanUv.x), min(vOceanUv.y, 1.0 - vOceanUv.y));
+  alpha *= smoothstep(0.0, 0.045, borderDist);
+  gl_FragColor = vec4(color, clamp(alpha, 0.0, 1.0));
 }
 `;

package/dist/weather/fireSpreadPose.d.ts

@@ -1,2 +1,3 @@
 import type { Euler, Quaternion } from "three";
+/** @internal */
 export declare function setBillboardQuaternion(quaternion: Quaternion, euler: Euler, yaw: number): void;

package/dist/weather/fireSpreadPose.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function setBillboardQuaternion(quaternion, euler, yaw) {
     euler.set(0, yaw, 0);
     quaternion.setFromEuler(euler);

package/dist/weather/weatherGeometry.d.ts

@@ -1,2 +1,3 @@
 import * as THREE from "three";
+/** @internal */
 export declare function createWeatherQuadGeometry(maxCount: number, seed: number): THREE.InstancedBufferGeometry;

package/dist/weather/weatherGeometry.js

@@ -1,5 +1,6 @@
 import * as THREE from "three";
 import { createWeatherSeedAttributes } from "./weatherMath.js";
+/** @internal */
 export function createWeatherQuadGeometry(maxCount, seed) {
     const count = Math.max(0, Math.floor(maxCount));
     const geometry = new THREE.InstancedBufferGeometry();

package/dist/weather/weatherMath.d.ts

@@ -2,10 +2,13 @@ export declare const DEFAULT_RAIN_COUNT = 2000;
 export declare const DEFAULT_SNOW_COUNT = 1500;
 export declare const DEFAULT_RAIN_DENSITY = 0.45;
 export declare const DEFAULT_SNOW_DENSITY = 0.5;
+/** @internal */
 export declare function clampWeatherRatio(value: number): number;
+/** @internal */
 export declare function resolveWeatherInstanceCount(maxCount: number, density: number, budget?: number): number;
 export interface WeatherSeedAttributes {
     spawn: Float32Array;
     drift: Float32Array;
 }
+/** @internal */
 export declare function createWeatherSeedAttributes(maxCount: number, seed: number): WeatherSeedAttributes;

package/dist/weather/weatherMath.js

@@ -2,6 +2,7 @@ export const DEFAULT_RAIN_COUNT = 2000;
 export const DEFAULT_SNOW_COUNT = 1500;
 export const DEFAULT_RAIN_DENSITY = 0.45;
 export const DEFAULT_SNOW_DENSITY = 0.5;
+/** @internal */
 export function clampWeatherRatio(value) {
     if (!Number.isFinite(value))
         return 0;
@@ -11,11 +12,13 @@ export function clampWeatherRatio(value) {
         return 1;
     return value;
 }
+/** @internal */
 export function resolveWeatherInstanceCount(maxCount, density, budget) {
     const safeMax = Math.max(0, Math.floor(maxCount));
     const capped = budget === undefined ? safeMax : Math.min(safeMax, Math.max(0, Math.floor(budget)));
     return Math.floor(capped * clampWeatherRatio(density));
 }
+/** @internal */
 export function createWeatherSeedAttributes(maxCount, seed) {
     const count = Math.max(0, Math.floor(maxCount));
     const spawn = new Float32Array(count * 3);

package/dist/weather/weatherUniforms.d.ts

@@ -11,8 +11,11 @@ export interface WeatherUniformOptions {
     lightning?: number;
     timeScale?: number;
 }
+/** @internal */
 export declare function createWeatherUniformSet(options?: WeatherUniformOptions): WeatherUniformSet;
+/** @internal */
 export declare function WeatherUniformProvider({ children, ...options }: WeatherUniformOptions & {
     children: ReactNode;
 }): import("react").JSX.Element;
+/** @internal */
 export declare function useWeatherUniformSet(options?: WeatherUniformOptions): WeatherUniformSet;

package/dist/weather/weatherUniforms.js

@@ -3,6 +3,7 @@ import { createContext, useContext, useMemo } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 const WeatherUniformContext = createContext(null);
+/** @internal */
 export function createWeatherUniformSet(options = {}) {
     const wind = options.wind ?? [0, 0, 0];
     return {
@@ -21,11 +22,13 @@ function useUniformTicker(uniforms, options, enabled = true) {
         uniforms.lightning.value = options.lightning ?? 0;
     });
 }
+/** @internal */
 export function WeatherUniformProvider({ children, ...options }) {
     const uniforms = useMemo(() => createWeatherUniformSet(options), []);
     useUniformTicker(uniforms, options);
     return _jsx(WeatherUniformContext.Provider, { value: uniforms, children: children });
 }
+/** @internal */
 export function useWeatherUniformSet(options = {}) {
     const shared = useContext(WeatherUniformContext);
     const local = useMemo(() => createWeatherUniformSet(options), []);

package/dist/world/PlaceScene.d.ts

@@ -0,0 +1,11 @@
+import type { PlaceWorldFeature } from "@jgengine/core/world/place";
+/**
+ * The substrate of a place world, rendered plainly: a flat slab or a round planet under the engine
+ * default sky. This is deliberately not a diorama — sky look, foliage, props, and sculpt are scene
+ * content the editor authors; `voxel` grounds are realized by the game's generation systems and
+ * `board` grounds by the game's own 2D face, so both mount nothing here.
+ * @internal
+ */
+export declare function PlaceScene({ feature }: {
+    feature: PlaceWorldFeature;
+}): import("react").JSX.Element | null;

package/dist/world/PlaceScene.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { DefaultSurface } from "../render/defaultSurface.js";
+/** Render extent (m) standing in for an `Infinity` flat-ground axis — far past the default fog. */
+const UNBOUNDED_RENDER_EXTENT = 2048;
+const GROUND_COLOR = "#5c6b52";
+function clampExtent(value) {
+    return Number.isFinite(value) ? value : UNBOUNDED_RENDER_EXTENT;
+}
+/**
+ * The substrate of a place world, rendered plainly: a flat slab or a round planet under the engine
+ * default sky. This is deliberately not a diorama — sky look, foliage, props, and sculpt are scene
+ * content the editor authors; `voxel` grounds are realized by the game's generation systems and
+ * `board` grounds by the game's own 2D face, so both mount nothing here.
+ * @internal
+ */
+export function PlaceScene({ feature }) {
+    const ground = feature.ground;
+    const size = useMemo(() => ground.mode === "flat" ? [clampExtent(ground.size.x), clampExtent(ground.size.z)] : undefined, [ground]);
+    if (ground.mode === "flat" && size !== undefined) {
+        return (_jsxs("mesh", { "rotation-x": -Math.PI / 2, receiveShadow: true, children: [_jsx("planeGeometry", { args: [size[0], size[1]] }), _jsx(DefaultSurface, { color: GROUND_COLOR, roughness: 0.95 })] }));
+    }
+    if (ground.mode === "round") {
+        return (_jsxs("mesh", { position: [0, -ground.size.radius, 0], receiveShadow: true, children: [_jsx("sphereGeometry", { args: [ground.size.radius, 64, 48] }), _jsx(DefaultSurface, { color: GROUND_COLOR, roughness: 0.95 })] }));
+    }
+    return null;
+}

package/dist/world/RetainedVfx.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Renders retained VFX instances (`combat.vfxInstance` ops from {@link GameContext}'s `scene.entity.vfxInstance`
+ * store) as long-lived beams whose endpoints follow live entity poses. Auto-mounted by the player shell alongside
+ * the one-shot {@link WorldSpellVfx} overlay. `upsert`/`update` mutate render resources imperatively (no per-frame
+ * React allocation); only create/stop change the mounted set, and `stop` fades out over its requested duration.
+ * Beam is the first shipped retained renderer; other kinds are ignored here for a future renderer to claim.
+ *
+ * @internal
+ */
+export declare function RetainedVfx(): import("react").JSX.Element;

package/dist/world/RetainedVfx.js

@@ -0,0 +1,136 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+const UP = new THREE.Vector3(0, 1, 0);
+/**
+ * Resolve an endpoint into `out`. A world point is used literally; an entity id resolves to its live pose lifted
+ * by `lift` (so a beam meets an entity near chest height, not its feet). Returns false when an entity ref is
+ * missing, letting the caller hide the effect until the target exists again.
+ */
+function resolveRef(ctx, ref, lift, out) {
+    if (ref === undefined)
+        return false;
+    if (typeof ref === "string") {
+        const entity = ctx.scene.entity.get(ref);
+        if (entity === null)
+            return false;
+        out.set(entity.position[0], entity.position[1] + lift, entity.position[2]);
+        return true;
+    }
+    out.set(ref[0], ref[1], ref[2]);
+    return true;
+}
+/**
+ * One retained beam mesh. It reads its authoritative state from the shared live map every frame and resolves
+ * `from`/`to` refs against the entity store, so an endpoint bound to a moving entity follows it with no per-frame
+ * command traffic or React re-render — parameter updates mutate the render resources imperatively.
+ */
+function RetainedBeam({ id, live, onFadeComplete, }) {
+    const ctx = useGameContext();
+    const meshRef = useRef(null);
+    const matRef = useRef(null);
+    const from = useRef(new THREE.Vector3());
+    const to = useRef(new THREE.Vector3());
+    const delta = useRef(new THREE.Vector3());
+    const quat = useRef(new THREE.Quaternion());
+    useFrame(() => {
+        const entry = live.get(id);
+        const mesh = meshRef.current;
+        const mat = matRef.current;
+        if (entry === undefined || mesh === null || mat === null)
+            return;
+        const lift = entry.state.params?.lift ?? 1;
+        const hasFrom = resolveRef(ctx, entry.state.from, lift, from.current);
+        const hasTo = resolveRef(ctx, entry.state.to, lift, to.current);
+        if (!hasFrom || !hasTo) {
+            mesh.visible = false;
+            return;
+        }
+        delta.current.subVectors(to.current, from.current);
+        const length = Math.max(0.001, delta.current.length());
+        mesh.visible = true;
+        mesh.position.set((from.current.x + to.current.x) / 2, (from.current.y + to.current.y) / 2, (from.current.z + to.current.z) / 2);
+        quat.current.setFromUnitVectors(UP, delta.current.normalize());
+        mesh.quaternion.copy(quat.current);
+        const thickness = entry.state.radius ?? 0.12;
+        mesh.scale.set(thickness, length, thickness);
+        mat.color.set(entry.state.color);
+        const baseOpacity = entry.state.params?.opacity ?? 0.85;
+        if (entry.fade === null) {
+            mat.opacity = baseOpacity;
+        }
+        else {
+            const p = (performance.now() - entry.fade.startedAt) / Math.max(1, entry.fade.ms);
+            if (p >= 1) {
+                onFadeComplete(id);
+                return;
+            }
+            mat.opacity = baseOpacity * (1 - p);
+        }
+    });
+    return (_jsxs("mesh", { ref: meshRef, renderOrder: 998, visible: false, children: [_jsx("cylinderGeometry", { args: [1, 1, 1, 8, 1, true] }), _jsx("meshBasicMaterial", { ref: matRef, transparent: true, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 })] }));
+}
+/**
+ * Renders retained VFX instances (`combat.vfxInstance` ops from {@link GameContext}'s `scene.entity.vfxInstance`
+ * store) as long-lived beams whose endpoints follow live entity poses. Auto-mounted by the player shell alongside
+ * the one-shot {@link WorldSpellVfx} overlay. `upsert`/`update` mutate render resources imperatively (no per-frame
+ * React allocation); only create/stop change the mounted set, and `stop` fades out over its requested duration.
+ * Beam is the first shipped retained renderer; other kinds are ignored here for a future renderer to claim.
+ *
+ * @internal
+ */
+export function RetainedVfx() {
+    const ctx = useGameContext();
+    const live = useRef(new Map()).current;
+    const [ids, setIds] = useState([]);
+    useEffect(() => {
+        // Seed from any instances created before this overlay mounted.
+        for (const state of ctx.scene.entity.vfxInstance.list()) {
+            if (state.kind !== "beam")
+                continue;
+            live.set(state.id, { state, fade: null });
+        }
+        if (live.size > 0)
+            setIds([...live.keys()]);
+        const off = ctx.game.events.on("combat.vfxInstance", (op) => {
+            if (op.op === "stop") {
+                const entry = live.get(op.id);
+                if (entry === undefined)
+                    return;
+                if (op.fadeMs !== undefined && op.fadeMs > 0) {
+                    entry.fade = { ms: op.fadeMs, startedAt: performance.now() };
+                }
+                else {
+                    live.delete(op.id);
+                    setIds([...live.keys()]);
+                }
+                return;
+            }
+            const state = op.instance;
+            if (state === undefined || state.kind !== "beam")
+                return;
+            const existing = live.get(op.id);
+            if (existing === undefined) {
+                live.set(op.id, { state, fade: null });
+                setIds([...live.keys()]);
+            }
+            else {
+                // Update: mutate state in place; RetainedBeam reads it next frame (no React re-render).
+                existing.state = state;
+                existing.fade = null;
+            }
+        });
+        return () => {
+            off();
+            live.clear();
+            setIds([]);
+        };
+    }, [ctx, live]);
+    function removeId(id) {
+        live.delete(id);
+        setIds((current) => current.filter((entry) => entry !== id));
+    }
+    return (_jsx(_Fragment, { children: ids.map((id) => (_jsx(RetainedBeam, { id: id, live: live, onFadeComplete: removeId }, id))) }));
+}

package/dist/world/WorldHud.d.ts

@@ -1,7 +1,9 @@
+import { type ReactNode } from "react";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
-export type { WorldBarSample } from "./worldBarSamples.js";
-export { collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
+import { type NameplateSample } from "./worldBarSamples.js";
+export type { NameplateSample, WorldBarSample } from "./worldBarSamples.js";
+export { collectNameplateSamples, collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
 export { telegraphPulseOpacity } from "./telegraphPulse.js";
 export declare function WorldEntityBars({ statId, height, roles, resolveRole, maxDistance, }: {
     statId: string;
@@ -11,6 +13,51 @@ export declare function WorldEntityBars({ statId, height, roles, resolveRole, ma
     /** Hide bars for entities farther than this from the player (world units). Default 60. */
     maxDistance?: number;
 }): import("react").JSX.Element;
+/** Props for `WorldNameplates` — entity filter, refresh rate, and headless className/render hooks. */
+export interface WorldNameplatesProps {
+    statId?: string;
+    height?: number;
+    roles?: readonly CatalogEntityRole[];
+    resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
+    /** Hide nameplates for entities farther than this from the player (world units). Default 40. */
+    maxDistance?: number;
+    /** Minimum ms between position/health refreshes — trades smoothness for fewer re-renders at scale. Default 120. */
+    tickMs?: number;
+    className?: string;
+    nameplateClassName?: string;
+    nameClassName?: string;
+    barClassName?: string;
+    fillClassName?: string;
+    /** Full override for one nameplate's markup; receives the raw sample (name, percent, screen x/y). */
+    renderNameplate?: (sample: NameplateSample) => ReactNode;
+}
+/**
+ * Billboarded name + 78×6px HP bar over every nearby non-local entity that
+ * passes `roles`/`maxDistance` — headless (className/data-* slots on every
+ * part, `renderNameplate` for a full swap), turned on declaratively via
+ * `defineGame({ nameplates })` rather than mounted by hand.
+ *
+ * @capability nameplates billboarded name + HP bar over nearby entities
+ */
+export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, tickMs, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
+/** Props for {@link WorldObjectHighlights}. */
+export interface WorldObjectHighlightsProps {
+    /** Ring tint. Default a construction-select amber. */
+    color?: string;
+    /** Fixed ring radius; omitted derives one from the object's catalog `halfExtents` (falls back to 1.2). */
+    radius?: number;
+    /** Ground offset so the ring doesn't z-fight the object's base. Default 0.05. */
+    y?: number;
+}
+/**
+ * Ground ring over every `ctx.scene.object.selection`-ed placed object — the object-layer counterpart
+ * to `WorldEntityBars`/`WorldNameplates`. Mount it once in the game's scene (headless: no defaults are
+ * imposed beyond a visible ring) instead of hand-rolling a selection highlight through `WorldOverlay`
+ * against external state.
+ *
+ * @capability world-object-highlights ground-ring highlight over every selected placed object
+ */
+export declare function WorldObjectHighlights({ color, radius, y }: WorldObjectHighlightsProps): import("react").JSX.Element;
 export declare function WorldFloatText({ height, lifeMs }: {
     height?: number;
     lifeMs?: number;