@jgengine/shell 0.7.0 → 0.9.0

package/dist/water/OceanConfig.js

@@ -1,5 +1,7 @@
 import * as THREE from "three";
 export const MAX_OCEAN_WAVES = 6;
+/** Shared with `@jgengine/core/world/water` — primary wavelength in world units. */
+export const DEFAULT_OCEAN_WAVE_SCALE = 18;
 export const OCEAN_QUALITY_PRESETS = {
     low: { size: 220, resolution: 80 },
     medium: { size: 360, resolution: 128 },
@@ -9,6 +11,7 @@ export const OCEAN_QUALITY_PRESETS = {
 export const DEFAULT_OCEAN_CONFIG = {
     quality: "medium",
     size: OCEAN_QUALITY_PRESETS.medium.size,
+    depth: OCEAN_QUALITY_PRESETS.medium.size,
     resolution: OCEAN_QUALITY_PRESETS.medium.resolution,
     amplitude: 1,
     speed: 1,
@@ -16,6 +19,7 @@ export const DEFAULT_OCEAN_CONFIG = {
     choppiness: 1,
     steepness: 0.72,
     timeScale: 1,
+    waveScale: DEFAULT_OCEAN_WAVE_SCALE,
     color: {
         shallow: "#2dc5d3",
         deep: "#064468",
@@ -33,14 +37,10 @@ export const DEFAULT_OCEAN_CONFIG = {
     },
     waves: [],
 };
-const DEFAULT_WAVE_SHAPE = [
-    { amplitude: 1.15, wavelength: 44, speed: 1, steepness: 0.68 },
-    { amplitude: 0.72, wavelength: 28, speed: 1.08, steepness: 0.58 },
-    { amplitude: 0.44, wavelength: 17, speed: 1.18, steepness: 0.48 },
-    { amplitude: 0.28, wavelength: 10, speed: 1.34, steepness: 0.38 },
-    { amplitude: 0.18, wavelength: 6.5, speed: 1.52, steepness: 0.28 },
-    { amplitude: 0.11, wavelength: 3.8, speed: 1.75, steepness: 0.18 },
-];
+const WAVE_WAVELENGTH_FALLOFF = 0.65;
+const WAVE_AMPLITUDE_SHAPE = [1.15, 0.72, 0.44, 0.28, 0.18, 0.11];
+const WAVE_SPEED_SHAPE = [1, 1.08, 1.18, 1.34, 1.52, 1.75];
+const WAVE_STEEPNESS_SHAPE = [0.68, 0.58, 0.48, 0.38, 0.28, 0.18];
 const DEFAULT_DIRECTION_OFFSETS = [-8, 7, 21, -31, 46, -58];
 function finiteOr(value, fallback) {
     return value === undefined || !Number.isFinite(value) ? fallback : value;
@@ -67,18 +67,21 @@ function normalizeDirection(direction, fallback) {
 }
 function createDefaultWaves(config) {
     const baseAngle = directionAngle(config.direction);
-    return DEFAULT_WAVE_SHAPE.map((wave, index) => ({
-        amplitude: wave.amplitude,
-        wavelength: wave.wavelength,
-        speed: wave.speed,
+    return WAVE_AMPLITUDE_SHAPE.map((amplitude, index) => ({
+        amplitude,
+        wavelength: Math.max(0.1, config.waveScale * WAVE_WAVELENGTH_FALLOFF ** index),
+        speed: WAVE_SPEED_SHAPE[index],
         direction: directionFromAngle(baseAngle + DEFAULT_DIRECTION_OFFSETS[index]),
-        steepness: wave.steepness,
+        steepness: WAVE_STEEPNESS_SHAPE[index],
     }));
 }
-function resolveWave(wave, fallback, config) {
+function resolveWave(wave, fallback, config, customWaves) {
+    const wavelength = customWaves && wave?.wavelength !== undefined
+        ? wave.wavelength * (config.waveScale / DEFAULT_OCEAN_WAVE_SCALE)
+        : finiteOr(wave?.wavelength, fallback.wavelength);
     return {
         amplitude: Math.max(0, finiteOr(wave?.amplitude, fallback.amplitude) * config.amplitude),
-        wavelength: Math.max(0.1, finiteOr(wave?.wavelength, fallback.wavelength)),
+        wavelength: Math.max(0.1, wavelength),
         speed: finiteOr(wave?.speed, fallback.speed) * config.speed,
         direction: normalizeDirection(wave?.direction, fallback.direction),
         steepness: clamp(finiteOr(wave?.steepness, fallback.steepness) * config.steepness, 0, 1.2),
@@ -87,9 +90,12 @@ function resolveWave(wave, fallback, config) {
 export function createOceanConfig(patch = {}) {
     const quality = patch.quality ?? DEFAULT_OCEAN_CONFIG.quality;
     const preset = OCEAN_QUALITY_PRESETS[quality];
+    const size = Math.max(1, finiteOr(patch.size, preset.size));
+    const depth = Math.max(1, finiteOr(patch.depth, size));
     const withoutWaves = {
         quality,
-        size: Math.max(1, Math.floor(finiteOr(patch.size, preset.size))),
+        size,
+        depth,
         resolution: Math.max(1, Math.floor(finiteOr(patch.resolution, preset.resolution))),
         amplitude: Math.max(0, finiteOr(patch.amplitude, DEFAULT_OCEAN_CONFIG.amplitude)),
         speed: finiteOr(patch.speed, DEFAULT_OCEAN_CONFIG.speed),
@@ -97,6 +103,7 @@ export function createOceanConfig(patch = {}) {
         choppiness: Math.max(0, finiteOr(patch.choppiness, DEFAULT_OCEAN_CONFIG.choppiness)),
         steepness: Math.max(0, finiteOr(patch.steepness, DEFAULT_OCEAN_CONFIG.steepness)),
         timeScale: finiteOr(patch.timeScale, DEFAULT_OCEAN_CONFIG.timeScale),
+        waveScale: Math.max(0.1, finiteOr(patch.waveScale, DEFAULT_OCEAN_CONFIG.waveScale)),
         color: {
             ...DEFAULT_OCEAN_CONFIG.color,
             ...patch.color,
@@ -114,8 +121,9 @@ export function createOceanConfig(patch = {}) {
         },
     };
     const defaultWaves = createDefaultWaves(withoutWaves);
+    const customWaves = patch.waves !== undefined;
     const inputWaves = patch.waves ?? defaultWaves;
-    const waves = Array.from({ length: MAX_OCEAN_WAVES }, (_, index) => resolveWave(inputWaves[index], defaultWaves[index], withoutWaves));
+    const waves = Array.from({ length: MAX_OCEAN_WAVES }, (_, index) => resolveWave(inputWaves[index], defaultWaves[index], withoutWaves, customWaves));
     return { ...withoutWaves, waves };
 }
 export function buildOceanWaveUniforms(config) {

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 common = horizontal * k * sine;\n    tangent += vec3(-common * direction.x * direction.x, amplitude * k * direction.x * cosine, -common * direction.x * direction.y);\n    bitangent += vec3(-common * direction.x * direction.y, amplitude * k * direction.y * cosine, -common * 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 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";

package/dist/water/OceanShader.js

@@ -32,9 +32,9 @@ void main() {
     displaced.x += horizontal * direction.x * cosine;
     displaced.z += horizontal * direction.y * cosine;
     displaced.y += amplitude * sine;
-    float common = horizontal * k * sine;
-    tangent += vec3(-common * direction.x * direction.x, amplitude * k * direction.x * cosine, -common * direction.x * direction.y);
-    bitangent += vec3(-common * direction.x * direction.y, amplitude * k * direction.y * cosine, -common * direction.y * direction.y);
+    float slopeTerm = horizontal * k * sine;
+    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);
+    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);
     crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));
   }
 

package/dist/water/index.d.ts

@@ -1,3 +1,3 @@
 export { Ocean, type OceanProps } from "./Ocean.js";
-export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, type OceanColorConfig, type OceanConfig, type OceanDirectionVector, type OceanFoamConfig, type OceanQualityPreset, type OceanWaveConfig, type OceanWaveDirection, type ResolvedOceanColorConfig, type ResolvedOceanConfig, type ResolvedOceanFoamConfig, type ResolvedOceanWaveConfig, } from "./OceanConfig.js";
+export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, DEFAULT_OCEAN_WAVE_SCALE, type OceanColorConfig, type OceanConfig, type OceanDirectionVector, type OceanFoamConfig, type OceanQualityPreset, type OceanWaveConfig, type OceanWaveDirection, type ResolvedOceanColorConfig, type ResolvedOceanConfig, type ResolvedOceanFoamConfig, type ResolvedOceanWaveConfig, } from "./OceanConfig.js";
 export { createOceanMaterial, syncOceanMaterial, type OceanMaterialUniforms, type OceanShaderMaterial, } from "./OceanMaterial.js";

package/dist/water/index.js

@@ -1,3 +1,3 @@
 export { Ocean } from "./Ocean.js";
-export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, } from "./OceanConfig.js";
+export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, DEFAULT_OCEAN_WAVE_SCALE, } from "./OceanConfig.js";
 export { createOceanMaterial, syncOceanMaterial, } from "./OceanMaterial.js";

package/dist/weather/FireSpreadLayer.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
+import { setBillboardQuaternion } from "./fireSpreadPose.js";
 const HIDDEN = new THREE.Matrix4().makeScale(0, 0, 0);
 export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, flameHeight = 1.6, burningColor = "#ff6a1a", emberColor = "#4a1206", }) {
     const flames = useRef(null);
@@ -24,6 +25,8 @@ export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, fla
     const matrix = useMemo(() => new THREE.Matrix4(), []);
     const position = useMemo(() => new THREE.Vector3(), []);
     const quaternion = useMemo(() => new THREE.Quaternion(), []);
+    const identityQuat = useMemo(() => new THREE.Quaternion(), []);
+    const euler = useMemo(() => new THREE.Euler(), []);
     const scale = useMemo(() => new THREE.Vector3(1, 1, 1), []);
     useFrame((state) => {
         const flameMesh = flames.current;
@@ -42,7 +45,7 @@ export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, fla
                 const groundY = heightAt?.(x, z) ?? 0;
                 if (cell.state === "burning") {
                     position.set(x, groundY + flameHeight * 0.5, z);
-                    quaternion.setFromEuler(new THREE.Euler(0, state.camera.rotation.y, 0));
+                    setBillboardQuaternion(quaternion, euler, state.camera.rotation.y);
                     scale.set(1, flicker, 1);
                     matrix.compose(position, quaternion, scale);
                     flameMesh.setMatrixAt(flameIndex, matrix);
@@ -50,7 +53,9 @@ export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, fla
                 }
                 else if (cell.state === "burnt") {
                     position.set(x, groundY + 0.05, z);
-                    scorchMesh.setMatrixAt(scorchIndex, matrix.compose(position, new THREE.Quaternion(), scale.set(1, 1, 1)));
+                    scale.set(1, 1, 1);
+                    matrix.compose(position, identityQuat, scale);
+                    scorchMesh.setMatrixAt(scorchIndex, matrix);
                     scorchIndex += 1;
                 }
             }

package/dist/weather/RainField.d.ts

@@ -3,6 +3,7 @@ import { type WeatherVector } from "./weatherUniforms.js";
 export interface RainFieldProps {
     count?: number;
     density?: number;
+    budget?: number;
     volume?: WeatherVector;
     wind?: WeatherVector;
     origin?: WeatherVector;
@@ -16,5 +17,6 @@ export interface RainFieldProps {
     timeScale?: number;
     seed?: number;
     renderOrder?: number;
+    frustumCulled?: boolean;
 }
-export declare function RainField({ count, density, volume, wind, origin, followCamera, speed, length, width, opacity, color, lightning, timeScale, seed, renderOrder, }: RainFieldProps): import("react").JSX.Element;
+export declare function RainField({ count, density, budget, volume, wind, origin, followCamera, speed, length, width, opacity, color, lightning, timeScale, seed, renderOrder, frustumCulled, }: RainFieldProps): import("react").JSX.Element;

package/dist/weather/RainField.js

@@ -3,12 +3,12 @@ import { useEffect, useMemo } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
 import { createWeatherQuadGeometry } from "./weatherGeometry.js";
-import { resolveWeatherInstanceCount } from "./weatherMath.js";
+import { DEFAULT_RAIN_COUNT, DEFAULT_RAIN_DENSITY, resolveWeatherInstanceCount } from "./weatherMath.js";
 import { useWeatherUniformSet } from "./weatherUniforms.js";
 const DEFAULT_VOLUME = [56, 42, 56];
 const DEFAULT_ORIGIN = [0, 0, 0];
 const DEFAULT_RAIN_COLOR = "#b8c4d8";
-export function RainField({ count = 8000, density = 0.45, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 22, length = 1.35, width = 0.018, opacity = 0.48, color = DEFAULT_RAIN_COLOR, lightning, timeScale, seed = 11939, renderOrder = 10, }) {
+export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 22, length = 1.35, width = 0.018, opacity = 0.48, color = DEFAULT_RAIN_COLOR, lightning, timeScale, seed = 11939, renderOrder = 10, frustumCulled, }) {
     const { camera } = useThree();
     const shared = useWeatherUniformSet({ wind, lightning, timeScale });
     const geometry = useMemo(() => createWeatherQuadGeometry(count, seed), [count, seed]);
@@ -97,11 +97,11 @@ export function RainField({ count = 8000, density = 0.45, volume = DEFAULT_VOLUM
         uniforms.uWidth.value = width;
         uniforms.uOpacity.value = opacity;
         uniforms.uColor.value.set(color);
-        geometry.instanceCount = resolveWeatherInstanceCount(count, density);
+        geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
     });
     useEffect(() => () => {
         geometry.dispose();
         material.dispose();
     }, [geometry, material]);
-    return _jsx("mesh", { geometry: geometry, material: material, frustumCulled: false, renderOrder: renderOrder });
+    return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
 }

package/dist/weather/SnowField.d.ts

@@ -3,6 +3,7 @@ import { type WeatherVector } from "./weatherUniforms.js";
 export interface SnowFieldProps {
     count?: number;
     density?: number;
+    budget?: number;
     volume?: WeatherVector;
     wind?: WeatherVector;
     origin?: WeatherVector;
@@ -15,5 +16,6 @@ export interface SnowFieldProps {
     timeScale?: number;
     seed?: number;
     renderOrder?: number;
+    frustumCulled?: boolean;
 }
-export declare function SnowField({ count, density, volume, wind, origin, followCamera, speed, size, sway, opacity, color, timeScale, seed, renderOrder, }: SnowFieldProps): import("react").JSX.Element;
+export declare function SnowField({ count, density, budget, volume, wind, origin, followCamera, speed, size, sway, opacity, color, timeScale, seed, renderOrder, frustumCulled, }: SnowFieldProps): import("react").JSX.Element;

package/dist/weather/SnowField.js

@@ -3,12 +3,12 @@ import { useEffect, useMemo } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
 import { createWeatherQuadGeometry } from "./weatherGeometry.js";
-import { resolveWeatherInstanceCount } from "./weatherMath.js";
+import { DEFAULT_SNOW_COUNT, DEFAULT_SNOW_DENSITY, resolveWeatherInstanceCount } from "./weatherMath.js";
 import { useWeatherUniformSet } from "./weatherUniforms.js";
 const DEFAULT_VOLUME = [52, 38, 52];
 const DEFAULT_ORIGIN = [0, 0, 0];
 const DEFAULT_SNOW_COLOR = "#ffffff";
-export function SnowField({ count = 6000, density = 0.5, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 3.2, size = 0.11, sway = 0.62, opacity = 0.86, color = DEFAULT_SNOW_COLOR, timeScale, seed = 72931, renderOrder = 11, }) {
+export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 3.2, size = 0.11, sway = 0.62, opacity = 0.86, color = DEFAULT_SNOW_COLOR, timeScale, seed = 72931, renderOrder = 11, frustumCulled, }) {
     const { camera } = useThree();
     const shared = useWeatherUniformSet({ wind, timeScale });
     const geometry = useMemo(() => createWeatherQuadGeometry(count, seed), [count, seed]);
@@ -98,11 +98,11 @@ export function SnowField({ count = 6000, density = 0.5, volume = DEFAULT_VOLUME
         uniforms.uSway.value = sway;
         uniforms.uOpacity.value = opacity;
         uniforms.uColor.value.set(color);
-        geometry.instanceCount = resolveWeatherInstanceCount(count, density);
+        geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
     });
     useEffect(() => () => {
         geometry.dispose();
         material.dispose();
     }, [geometry, material]);
-    return _jsx("mesh", { geometry: geometry, material: material, frustumCulled: false, renderOrder: renderOrder });
+    return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
 }

package/dist/weather/fireSpreadPose.d.ts

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

package/dist/weather/fireSpreadPose.js

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

package/dist/weather/weatherMath.d.ts

@@ -1,5 +1,9 @@
+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;
 export declare function clampWeatherRatio(value: number): number;
-export declare function resolveWeatherInstanceCount(maxCount: number, density: number): number;
+export declare function resolveWeatherInstanceCount(maxCount: number, density: number, budget?: number): number;
 export interface WeatherSeedAttributes {
     spawn: Float32Array;
     drift: Float32Array;

package/dist/weather/weatherMath.js

@@ -1,3 +1,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;
 export function clampWeatherRatio(value) {
     if (!Number.isFinite(value))
         return 0;
@@ -7,9 +11,10 @@ export function clampWeatherRatio(value) {
         return 1;
     return value;
 }
-export function resolveWeatherInstanceCount(maxCount, density) {
+export function resolveWeatherInstanceCount(maxCount, density, budget) {
     const safeMax = Math.max(0, Math.floor(maxCount));
-    return Math.floor(safeMax * clampWeatherRatio(density));
+    const capped = budget === undefined ? safeMax : Math.min(safeMax, Math.max(0, Math.floor(budget)));
+    return Math.floor(capped * clampWeatherRatio(density));
 }
 export function createWeatherSeedAttributes(maxCount, seed) {
     const count = Math.max(0, Math.floor(maxCount));

package/dist/world/DataObjects.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode } from "react";
+import * as THREE from "three";
+/**
+ * Renders one placed 3D object per data item — a 3D bar chart, a heatmap, a city
+ * of buildings, a crowd. By default each item is an extruded box (all boxes share
+ * one `InstancedMesh`, so hundreds cost one draw call), sized and colored from the
+ * item; `renderItem` swaps the box for arbitrary content (a sprite, a GLB, a full
+ * entity). Genre-agnostic: the caller owns the data `T`, this owns the placement.
+ */
+export interface DataObjectsProps<T> {
+    data: readonly T[];
+    /** World `[x, z]` for an item (placed on the ground plane). */
+    position: (item: T, index: number) => readonly [number, number];
+    /** Box height (Y-scale) for an item. */
+    height: (item: T, index: number) => number;
+    /** Box color for an item (any CSS/hex/THREE color). */
+    color: (item: T, index: number) => THREE.ColorRepresentation;
+    /** Footprint on X and Z. Default 0.28. */
+    cellSize?: number;
+    /** Index of the highlighted item, painted with `hoverColor`. */
+    hovered?: number | null;
+    hoverColor?: THREE.ColorRepresentation;
+    /** Called with the item index under the pointer, or null on exit. */
+    onHover?: (index: number | null) => void;
+    /** Staggered grow-in; restarts whenever `data` identity changes. */
+    grow?: {
+        duration?: number;
+        delay?: (item: T, index: number) => number;
+    };
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+    /**
+     * Render arbitrary content per item instead of an instanced box — a sprite, a
+     * GLB, a full entity. The layout positions each on the ground at its `[x, z]`
+     * and hands you the resolved `height` to size against (e.g. one walking figure
+     * per unit of value). When set, the instanced-box path is bypassed.
+     */
+    renderItem?: (item: T, index: number, info: {
+        x: number;
+        z: number;
+        height: number;
+    }) => ReactNode;
+}
+export declare function DataObjects<T>({ data, position, height, color, cellSize, hovered, hoverColor, onHover, grow, castShadow, receiveShadow, renderItem, }: DataObjectsProps<T>): import("react").JSX.Element | null;

package/dist/world/DataObjects.js

@@ -0,0 +1,77 @@
+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";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+export function DataObjects({ data, position, height, color, cellSize = 0.28, hovered = null, hoverColor = "#ffffff", onHover, grow, castShadow = true, receiveShadow = true, renderItem, }) {
+    const meshRef = useRef(null);
+    const dummy = useMemo(() => new THREE.Object3D(), []);
+    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.62, metalness: 0.04 }), []);
+    const hover = useMemo(() => new THREE.Color(hoverColor), [hoverColor]);
+    const startRef = useRef(null);
+    const capacity = data.length;
+    const layout = useMemo(() => {
+        const positions = new Float32Array(capacity * 2);
+        const targets = new Float32Array(capacity);
+        const delays = new Float32Array(capacity);
+        const colors = [];
+        data.forEach((item, i) => {
+            const [x, z] = position(item, i);
+            positions[i * 2] = x;
+            positions[i * 2 + 1] = z;
+            targets[i] = height(item, i);
+            delays[i] = grow?.delay?.(item, i) ?? 0;
+            colors.push(new THREE.Color(color(item, i)));
+        });
+        return { positions, targets, delays, colors };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [data]);
+    useEffect(() => {
+        startRef.current = null;
+    }, [data]);
+    useEffect(() => () => {
+        geometry.dispose();
+        material.dispose();
+    }, [geometry, material]);
+    const duration = grow?.duration ?? 0;
+    useFrame((state) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        if (startRef.current === null)
+            startRef.current = state.clock.elapsedTime;
+        const elapsed = state.clock.elapsedTime - startRef.current;
+        const { positions, targets, delays, colors } = layout;
+        for (let i = 0; i < capacity; i += 1) {
+            const grown = duration <= 0 ? 1 : clamp01((elapsed - delays[i]) / duration);
+            const eased = 1 - Math.pow(1 - grown, 3);
+            const h = Math.max(targets[i] * eased, 0.001);
+            dummy.position.set(positions[i * 2], h / 2, positions[i * 2 + 1]);
+            dummy.scale.set(cellSize, h, cellSize);
+            dummy.updateMatrix();
+            mesh.setMatrixAt(i, dummy.matrix);
+            mesh.setColorAt(i, i === hovered ? hover : colors[i]);
+        }
+        mesh.instanceMatrix.needsUpdate = true;
+        if (mesh.instanceColor !== null)
+            mesh.instanceColor.needsUpdate = true;
+    });
+    function handleMove(event) {
+        if (onHover === undefined)
+            return;
+        event.stopPropagation();
+        onHover(event.instanceId ?? null);
+    }
+    if (renderItem !== undefined) {
+        return (_jsx("group", { children: data.map((item, i) => {
+                const [x, z] = position(item, i);
+                return (_jsx("group", { position: [x, 0, z], children: renderItem(item, i, { x, z, height: height(item, i) }) }, i));
+            }) }));
+    }
+    if (capacity === 0)
+        return null;
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, capacity], castShadow: castShadow, receiveShadow: receiveShadow, frustumCulled: false, onPointerMove: onHover === undefined ? undefined : handleMove, onPointerOut: onHover === undefined ? undefined : () => onHover(null) }, capacity));
+}

package/dist/world/GridWorldScene.d.ts

@@ -0,0 +1,10 @@
+import type { WorldFeature } from "@jgengine/core/world/features";
+export interface GridWorldSceneProps {
+    feature: WorldFeature;
+}
+/**
+ * Data-driven renderer for the `biomes()`/`voxel()`/`plots()`/`tilemap()` world-feature kinds
+ * (#207.1): one `InstancedMesh` of extruded, colored boxes built from each feature's declared
+ * `cells`, following the same direct-buffer pattern as `InstancedBodies`.
+ */
+export declare function GridWorldScene({ feature }: GridWorldSceneProps): import("react").JSX.Element | null;

package/dist/world/GridWorldScene.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { resolveGridInstances } from "@jgengine/core/world/gridInstances";
+function isGridWorldFeature(feature) {
+    return (feature.kind === "biomes" || feature.kind === "voxel" || feature.kind === "plots" || feature.kind === "tilemap");
+}
+/**
+ * Data-driven renderer for the `biomes()`/`voxel()`/`plots()`/`tilemap()` world-feature kinds
+ * (#207.1): one `InstancedMesh` of extruded, colored boxes built from each feature's declared
+ * `cells`, following the same direct-buffer pattern as `InstancedBodies`.
+ */
+export function GridWorldScene({ feature }) {
+    const instances = useMemo(() => (isGridWorldFeature(feature) ? resolveGridInstances(feature) : []), [feature]);
+    const meshRef = useRef(null);
+    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.9, metalness: 0 }), []);
+    const instanceColor = useMemo(() => new THREE.InstancedBufferAttribute(new Float32Array(Math.max(instances.length, 1) * 3), 3), [instances.length]);
+    useEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        mesh.instanceColor = instanceColor;
+        mesh.count = instances.length;
+        const m = mesh.instanceMatrix.array;
+        const c = instanceColor.array;
+        const color = new THREE.Color();
+        for (let i = 0; i < instances.length; i += 1) {
+            const instance = instances[i];
+            const o = i * 16;
+            m[o] = instance.scale[0];
+            m[o + 5] = instance.scale[1];
+            m[o + 10] = instance.scale[2];
+            m[o + 12] = instance.position[0];
+            m[o + 13] = instance.position[1];
+            m[o + 14] = instance.position[2];
+            m[o + 15] = 1;
+            color.set(instance.color);
+            const co = i * 3;
+            c[co] = color.r;
+            c[co + 1] = color.g;
+            c[co + 2] = color.b;
+        }
+        mesh.instanceMatrix.needsUpdate = true;
+        instanceColor.needsUpdate = true;
+    }, [instances, instanceColor]);
+    useEffect(() => () => {
+        geometry.dispose();
+        material.dispose();
+    }, [geometry, material]);
+    if (instances.length === 0)
+        return null;
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, instances.length], castShadow: true, receiveShadow: true }));
+}

package/dist/world/SpriteBatch.d.ts

@@ -0,0 +1,44 @@
+export interface SpriteBatchInstance {
+    /** World X position. */
+    x: number;
+    /** World Y position. */
+    y: number;
+    /** World Z position. Defaults to 0. */
+    z?: number;
+    /** Atlas frame index, row-major from the sheet's top-left. Defaults to 0. */
+    frame?: number;
+    /** Uniform scale multiplier for the unit quad. Defaults to 1. */
+    scale?: number;
+    /** Rotation in radians about the plane's facing axis. Defaults to 0. */
+    rotation?: number;
+}
+export interface SpriteBatchProps {
+    /** Sprite sheet / atlas texture URL. */
+    url: string;
+    /** Atlas column count. Defaults to 1. */
+    columns?: number;
+    /** Atlas row count. Defaults to 1. */
+    rows?: number;
+    /** Max instances the InstancedMesh is allocated for. Defaults to 1024. */
+    capacity?: number;
+    /** Per-frame instance source, called once inside useFrame. */
+    instances: () => readonly SpriteBatchInstance[];
+    /** Facing plane when not billboarding: "xy" faces +Z (side-scroll/ortho), "xz" lies flat facing +Y. Defaults to "xy". */
+    plane?: "xy" | "xz";
+    /** When true, every instance orients to face the camera each frame, overriding `plane`. Defaults to false. */
+    billboard?: boolean;
+    /** Use nearest-neighbor filtering for crisp pixel art. Defaults to true. */
+    pixelated?: boolean;
+    /** Alpha test cutoff for transparent pixels. Defaults to 0.08. */
+    alphaTest?: number;
+    /** Material opacity. Defaults to 1. */
+    opacity?: number;
+}
+/**
+ * Renders a sprite sheet / tile atlas as a single InstancedMesh — one draw call for the whole
+ * batch. Each instance picks its atlas frame via a per-instance UV offset attribute patched into
+ * the material's vertex shader, so platformer/puzzle-grid presentation never needs one draw call
+ * per sprite. Transforms and UV offsets are written directly into the mesh's typed arrays each
+ * frame from a plain instance list (bodies never touch the per-entity React path).
+ */
+export declare function SpriteBatch({ url, columns, rows, capacity, instances, plane, billboard, pixelated, alphaTest, opacity, }: SpriteBatchProps): import("react").JSX.Element;