@jgengine/shell 0.5.0 → 0.6.0

package/dist/terrain/grassGeometry.js

@@ -0,0 +1,77 @@
+import * as THREE from "three";
+import { createSeededRandom } from "./random.js";
+import { resolveTerrainSize } from "./terrainMath.js";
+export function resolveGrassRange(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    return typeof value === "number" ? [value, value] : value;
+}
+export function resolveGrassBladeGeometryOptions(options = {}) {
+    return {
+        count: Math.max(0, Math.floor(options.count ?? 6000)),
+        area: options.area ?? 40,
+        seed: options.seed ?? 1,
+        segments: Math.max(1, Math.floor(options.segments ?? 4)),
+        height: resolveGrassRange(options.height, [0.55, 1.1]),
+        width: resolveGrassRange(options.width, [0.035, 0.075]),
+        bend: resolveGrassRange(options.bend, [0.08, 0.32]),
+        heightAt: options.heightAt ?? (() => 0),
+    };
+}
+function randomRange(random, range) {
+    return THREE.MathUtils.lerp(range[0], range[1], random());
+}
+export function createGrassBladeGeometry(options = {}) {
+    const resolved = resolveGrassBladeGeometryOptions(options);
+    const size = resolveTerrainSize(resolved.area);
+    const positions = [];
+    const normals = [];
+    const uvs = [];
+    const indices = [];
+    for (let segment = 0; segment <= resolved.segments; segment += 1) {
+        const t = segment / resolved.segments;
+        positions.push(-0.5, t, 0, 0.5, t, 0);
+        normals.push(0, 0, 1, 0, 0, 1);
+        uvs.push(0, t, 1, t);
+        if (segment < resolved.segments) {
+            const base = segment * 2;
+            indices.push(base, base + 1, base + 3, base, base + 3, base + 2);
+        }
+    }
+    const geometry = new THREE.InstancedBufferGeometry();
+    geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+    geometry.setAttribute("normal", new THREE.Float32BufferAttribute(normals, 3));
+    geometry.setAttribute("uv", new THREE.Float32BufferAttribute(uvs, 2));
+    geometry.setIndex(indices);
+    const random = createSeededRandom(resolved.seed);
+    const offsets = new Float32Array(resolved.count * 3);
+    const yaw = new Float32Array(resolved.count);
+    const heights = new Float32Array(resolved.count);
+    const widths = new Float32Array(resolved.count);
+    const bend = new Float32Array(resolved.count);
+    const phase = new Float32Array(resolved.count);
+    const colorMix = new Float32Array(resolved.count);
+    for (let index = 0; index < resolved.count; index += 1) {
+        const x = (random() - 0.5) * size.width;
+        const z = (random() - 0.5) * size.depth;
+        offsets[index * 3] = x;
+        offsets[index * 3 + 1] = resolved.heightAt(x, z);
+        offsets[index * 3 + 2] = z;
+        yaw[index] = random() * Math.PI * 2;
+        heights[index] = randomRange(random, resolved.height);
+        widths[index] = randomRange(random, resolved.width);
+        bend[index] = randomRange(random, resolved.bend);
+        phase[index] = random() * Math.PI * 2;
+        colorMix[index] = random();
+    }
+    geometry.setAttribute("instanceOffset", new THREE.InstancedBufferAttribute(offsets, 3));
+    geometry.setAttribute("instanceYaw", new THREE.InstancedBufferAttribute(yaw, 1));
+    geometry.setAttribute("instanceHeight", new THREE.InstancedBufferAttribute(heights, 1));
+    geometry.setAttribute("instanceWidth", new THREE.InstancedBufferAttribute(widths, 1));
+    geometry.setAttribute("instanceBend", new THREE.InstancedBufferAttribute(bend, 1));
+    geometry.setAttribute("instancePhase", new THREE.InstancedBufferAttribute(phase, 1));
+    geometry.setAttribute("instanceColorMix", new THREE.InstancedBufferAttribute(colorMix, 1));
+    geometry.instanceCount = resolved.count;
+    geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0, 0), Math.max(size.width, size.depth) * 0.75 + resolved.height[1]);
+    return geometry;
+}

package/dist/terrain/grassMaterial.d.ts

@@ -0,0 +1,33 @@
+import * as THREE from "three";
+export interface GrassWindOptions {
+    direction?: readonly [x: number, z: number];
+    strength?: number;
+    speed?: number;
+    gustScale?: number;
+    flutter?: number;
+}
+export interface GrassMaterialOptions {
+    colorBase?: THREE.ColorRepresentation;
+    colorTip?: THREE.ColorRepresentation;
+    colorVariation?: number;
+    wind?: GrassWindOptions | false;
+    roughness?: number;
+}
+export interface GrassShaderUniforms {
+    uTime: THREE.IUniform<number>;
+    uWindDirection: THREE.IUniform<THREE.Vector2>;
+    uWindStrength: THREE.IUniform<number>;
+    uWindSpeed: THREE.IUniform<number>;
+    uWindGustScale: THREE.IUniform<number>;
+    uWindFlutter: THREE.IUniform<number>;
+    uColorBase: THREE.IUniform<THREE.Color>;
+    uColorTip: THREE.IUniform<THREE.Color>;
+    uColorVariation: THREE.IUniform<number>;
+}
+export interface GrassMaterialHandle {
+    material: THREE.MeshStandardMaterial;
+    uniforms: GrassShaderUniforms;
+}
+export declare const DEFAULT_GRASS_WIND: Required<GrassWindOptions>;
+export declare function resolveGrassWind(wind: GrassWindOptions | false | undefined): Required<GrassWindOptions>;
+export declare function createGrassMaterial(options?: GrassMaterialOptions): GrassMaterialHandle;

package/dist/terrain/grassMaterial.js

@@ -0,0 +1,108 @@
+import * as THREE from "three";
+export const DEFAULT_GRASS_WIND = {
+    direction: [1, 0.35],
+    strength: 0.22,
+    speed: 1.6,
+    gustScale: 0.16,
+    flutter: 0.08,
+};
+function normalizeWindDirection(direction) {
+    const vector = new THREE.Vector2(direction[0], direction[1]);
+    return vector.lengthSq() === 0 ? new THREE.Vector2(1, 0) : vector.normalize();
+}
+export function resolveGrassWind(wind) {
+    if (wind === false)
+        return { ...DEFAULT_GRASS_WIND, strength: 0, flutter: 0 };
+    return {
+        direction: wind?.direction ?? DEFAULT_GRASS_WIND.direction,
+        strength: wind?.strength ?? DEFAULT_GRASS_WIND.strength,
+        speed: wind?.speed ?? DEFAULT_GRASS_WIND.speed,
+        gustScale: wind?.gustScale ?? DEFAULT_GRASS_WIND.gustScale,
+        flutter: wind?.flutter ?? DEFAULT_GRASS_WIND.flutter,
+    };
+}
+export function createGrassMaterial(options = {}) {
+    const wind = resolveGrassWind(options.wind);
+    const uniforms = {
+        uTime: { value: 0 },
+        uWindDirection: { value: normalizeWindDirection(wind.direction) },
+        uWindStrength: { value: wind.strength },
+        uWindSpeed: { value: wind.speed },
+        uWindGustScale: { value: wind.gustScale },
+        uWindFlutter: { value: wind.flutter },
+        uColorBase: { value: new THREE.Color(options.colorBase ?? "#2d431f") },
+        uColorTip: { value: new THREE.Color(options.colorTip ?? "#a6cc58") },
+        uColorVariation: { value: options.colorVariation ?? 0.28 },
+    };
+    const material = new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        side: THREE.DoubleSide,
+        roughness: options.roughness ?? 0.82,
+        metalness: 0,
+    });
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `
+#include <common>
+attribute vec3 instanceOffset;
+attribute float instanceYaw;
+attribute float instanceHeight;
+attribute float instanceWidth;
+attribute float instanceBend;
+attribute float instancePhase;
+attribute float instanceColorMix;
+uniform float uTime;
+uniform vec2 uWindDirection;
+uniform float uWindStrength;
+uniform float uWindSpeed;
+uniform float uWindGustScale;
+uniform float uWindFlutter;
+varying float vGrassBladeT;
+varying float vGrassColorMix;
+vec3 jgGrassPosition;
+vec3 jgGrassNormal;
+void jgComputeGrassBlade() {
+  float t = position.y;
+  float side = position.x;
+  float taper = (1.0 - t) * (0.72 + 0.28 * (1.0 - t));
+  float width = instanceWidth * taper;
+  float arc = instanceBend * t * t;
+  vec3 localPosition = vec3(side * width, instanceHeight * t - arc * instanceHeight * 0.18, arc * instanceHeight);
+  vec3 localNormal = normalize(vec3(0.0, -instanceBend * t, 1.0));
+  float cy = cos(instanceYaw);
+  float sy = sin(instanceYaw);
+  vec3 yawedPosition = vec3(localPosition.x * cy + localPosition.z * sy, localPosition.y, -localPosition.x * sy + localPosition.z * cy);
+  vec3 yawedNormal = normalize(vec3(localNormal.x * cy + localNormal.z * sy, localNormal.y, -localNormal.x * sy + localNormal.z * cy));
+  float gustPhase = dot(instanceOffset.xz, uWindDirection) * uWindGustScale + uTime * uWindSpeed + instancePhase;
+  float gust = sin(gustPhase) * 0.7 + sin(gustPhase * 0.43 + 2.4) * 0.3;
+  float flutter = sin(uTime * 7.5 + instancePhase * 2.7) * uWindFlutter;
+  vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t;
+  jgGrassPosition = instanceOffset + yawedPosition + vec3(windOffset.x, 0.0, windOffset.y);
+  jgGrassNormal = yawedNormal;
+  vGrassBladeT = t;
+  vGrassColorMix = instanceColorMix;
+}
+`)
+            .replace("#include <beginnormal_vertex>", "jgComputeGrassBlade();\nvec3 objectNormal = jgGrassNormal;")
+            .replace("#include <begin_vertex>", "vec3 transformed = jgGrassPosition;");
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `
+#include <common>
+uniform vec3 uColorBase;
+uniform vec3 uColorTip;
+uniform float uColorVariation;
+varying float vGrassBladeT;
+varying float vGrassColorMix;
+`)
+            .replace("#include <color_fragment>", `
+#include <color_fragment>
+vec3 grassColor = mix(uColorBase, uColorTip, smoothstep(0.0, 1.0, vGrassBladeT));
+grassColor *= mix(1.0 - uColorVariation, 1.0 + uColorVariation, vGrassColorMix);
+grassColor *= mix(0.58, 1.0, smoothstep(0.05, 0.45, vGrassBladeT));
+diffuseColor.rgb = grassColor;
+`);
+    };
+    material.customProgramCacheKey = () => `jgengine-grass-${wind.strength}-${wind.flutter}`;
+    return { material, uniforms };
+}

package/dist/terrain/index.d.ts

@@ -0,0 +1,7 @@
+export { GrassField, type GrassFieldProps } from "./GrassField.js";
+export { ProceduralGround, type ProceduralGroundProps } from "./ProceduralGround.js";
+export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, type GrassBladeGeometryOptions, type GrassRange, type ResolvedGrassBladeGeometryOptions, } from "./grassGeometry.js";
+export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMaterialHandle, type GrassMaterialOptions, type GrassShaderUniforms, type GrassWindOptions, } from "./grassMaterial.js";
+export { createSeededRandom, hashNoise2, seedToUint32, type TerrainSeed } from "./random.js";
+export { createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainVertexColorOptions, } from "./terrainMath.js";
+export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, type FractalNoiseConfig, type NoiseFieldConfig, type TerrainField, type TerrainNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/index.js

@@ -0,0 +1,7 @@
+export { GrassField } from "./GrassField.js";
+export { ProceduralGround } from "./ProceduralGround.js";
+export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, } from "./grassGeometry.js";
+export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./grassMaterial.js";
+export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
+export { createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
+export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/random.d.ts

@@ -0,0 +1,4 @@
+export type TerrainSeed = number | string;
+export declare function seedToUint32(seed?: TerrainSeed): number;
+export declare function createSeededRandom(seed?: TerrainSeed): () => number;
+export declare function hashNoise2(x: number, z: number, seed?: TerrainSeed): number;

package/dist/terrain/random.js

@@ -0,0 +1,27 @@
+export function seedToUint32(seed = 1) {
+    if (typeof seed === "number")
+        return seed >>> 0;
+    let hash = 2166136261;
+    for (let index = 0; index < seed.length; index += 1) {
+        hash ^= seed.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}
+export function createSeededRandom(seed = 1) {
+    let state = seedToUint32(seed);
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let value = state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function hashNoise2(x, z, seed = 1) {
+    let hash = seedToUint32(seed);
+    hash ^= Math.imul(x | 0, 374761393);
+    hash ^= Math.imul(z | 0, 668265263);
+    hash = Math.imul(hash ^ (hash >>> 13), 1274126177);
+    return ((hash ^ (hash >>> 16)) >>> 0) / 4294967295;
+}

package/dist/terrain/terrainMath.d.ts

@@ -0,0 +1,34 @@
+import { type NoiseFieldConfig } from "@jgengine/core/world/terrain";
+import * as THREE from "three";
+import { type TerrainSeed } from "./random.js";
+export type TerrainArea = number | readonly [width: number, depth: number];
+export type TerrainHeightSampler = (x: number, z: number) => number;
+export interface ProceduralTerrainConfig {
+    size?: TerrainArea;
+    segments?: number | readonly [x: number, z: number];
+    seed?: TerrainSeed;
+    height?: number;
+    moundScale?: number;
+    octaves?: number;
+    ridged?: boolean;
+    baseOffset?: number;
+}
+export interface ResolvedTerrainSize {
+    width: number;
+    depth: number;
+}
+export interface ResolvedTerrainSegments {
+    x: number;
+    z: number;
+}
+export interface TerrainVertexColorOptions {
+    low?: THREE.ColorRepresentation;
+    high?: THREE.ColorRepresentation;
+    waterline?: THREE.ColorRepresentation;
+    waterlineHeight?: number;
+}
+export declare function resolveTerrainSize(size?: TerrainArea): ResolvedTerrainSize;
+export declare function resolveTerrainSegments(segments?: ProceduralTerrainConfig["segments"]): ResolvedTerrainSegments;
+export declare function toNoiseFieldConfig(config?: ProceduralTerrainConfig): NoiseFieldConfig;
+export declare function createProceduralTerrainSampler(config?: ProceduralTerrainConfig): TerrainHeightSampler;
+export declare function createProceduralGroundGeometry(config?: ProceduralTerrainConfig, colors?: TerrainVertexColorOptions): THREE.BufferGeometry;

package/dist/terrain/terrainMath.js

@@ -0,0 +1,92 @@
+import { noiseField } from "@jgengine/core/world/terrain";
+import * as THREE from "three";
+import {} from "./random.js";
+export function resolveTerrainSize(size = 40) {
+    return typeof size === "number" ? { width: size, depth: size } : { width: size[0], depth: size[1] };
+}
+export function resolveTerrainSegments(segments = 96) {
+    if (typeof segments !== "number")
+        return { x: Math.max(1, Math.floor(segments[0])), z: Math.max(1, Math.floor(segments[1])) };
+    const resolved = Math.max(1, Math.floor(segments));
+    return { x: resolved, z: resolved };
+}
+export function toNoiseFieldConfig(config = {}) {
+    return {
+        seed: config.seed,
+        amplitude: config.height ?? 1.4,
+        frequency: config.moundScale ?? 0.075,
+        octaves: config.octaves ?? 4,
+        ridged: config.ridged ?? false,
+        baseHeight: config.baseOffset ?? 0,
+    };
+}
+export function createProceduralTerrainSampler(config = {}) {
+    return noiseField(toNoiseFieldConfig(config)).sampleHeight;
+}
+export function createProceduralGroundGeometry(config = {}, colors = {}) {
+    const size = resolveTerrainSize(config.size);
+    const segments = resolveTerrainSegments(config.segments);
+    const sampler = createProceduralTerrainSampler(config);
+    const vertexCountX = segments.x + 1;
+    const vertexCountZ = segments.z + 1;
+    const positions = new Float32Array(vertexCountX * vertexCountZ * 3);
+    const uvs = new Float32Array(vertexCountX * vertexCountZ * 2);
+    const colorValues = new Float32Array(vertexCountX * vertexCountZ * 3);
+    const indices = new Uint32Array(segments.x * segments.z * 6);
+    const low = new THREE.Color(colors.low ?? "#30402c");
+    const high = new THREE.Color(colors.high ?? "#7f8b50");
+    const waterline = colors.waterline === undefined ? null : new THREE.Color(colors.waterline);
+    const minHeight = (config.baseOffset ?? 0) - (config.height ?? 1.4) * 1.2;
+    const maxHeight = (config.baseOffset ?? 0) + (config.height ?? 1.4) * 1.2;
+    let index = 0;
+    let uvIndex = 0;
+    let colorIndex = 0;
+    for (let zIndex = 0; zIndex < vertexCountZ; zIndex += 1) {
+        const v = zIndex / segments.z;
+        const z = (v - 0.5) * size.depth;
+        for (let xIndex = 0; xIndex < vertexCountX; xIndex += 1) {
+            const u = xIndex / segments.x;
+            const x = (u - 0.5) * size.width;
+            const y = sampler(x, z);
+            positions[index] = x;
+            positions[index + 1] = y;
+            positions[index + 2] = z;
+            uvs[uvIndex] = u;
+            uvs[uvIndex + 1] = v;
+            const blend = THREE.MathUtils.clamp((y - minHeight) / (maxHeight - minHeight), 0, 1);
+            const color = low.clone().lerp(high, blend);
+            if (waterline !== null && y <= (colors.waterlineHeight ?? 0))
+                color.lerp(waterline, 0.65);
+            colorValues[colorIndex] = color.r;
+            colorValues[colorIndex + 1] = color.g;
+            colorValues[colorIndex + 2] = color.b;
+            index += 3;
+            uvIndex += 2;
+            colorIndex += 3;
+        }
+    }
+    let triangleIndex = 0;
+    for (let zIndex = 0; zIndex < segments.z; zIndex += 1) {
+        for (let xIndex = 0; xIndex < segments.x; xIndex += 1) {
+            const a = zIndex * vertexCountX + xIndex;
+            const b = a + 1;
+            const c = a + vertexCountX;
+            const d = c + 1;
+            indices[triangleIndex] = a;
+            indices[triangleIndex + 1] = c;
+            indices[triangleIndex + 2] = b;
+            indices[triangleIndex + 3] = b;
+            indices[triangleIndex + 4] = c;
+            indices[triangleIndex + 5] = d;
+            triangleIndex += 6;
+        }
+    }
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+    geometry.setAttribute("uv", new THREE.BufferAttribute(uvs, 2));
+    geometry.setAttribute("color", new THREE.BufferAttribute(colorValues, 3));
+    geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+    geometry.computeVertexNormals();
+    geometry.computeBoundingSphere();
+    return geometry;
+}

package/dist/terrain.d.ts

@@ -0,0 +1 @@
+export * from "./terrain/index.js";

package/dist/terrain.js

@@ -0,0 +1 @@
+export * from "./terrain/index.js";

package/dist/water/Ocean.d.ts

@@ -0,0 +1,6 @@
+import { type ThreeElements } from "@react-three/fiber";
+import { type OceanConfig } from "./OceanConfig.js";
+export interface OceanProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
+    config?: OceanConfig;
+}
+export declare function Ocean({ config, ...meshProps }: OceanProps): import("react").JSX.Element;

package/dist/water/Ocean.js

@@ -0,0 +1,30 @@
+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";
+import { createOceanConfig } from "./OceanConfig.js";
+import { createOceanMaterial, syncOceanMaterial } from "./OceanMaterial.js";
+function createOceanGeometry(config) {
+    const geometry = new THREE.PlaneGeometry(config.size, config.size, config.resolution, config.resolution);
+    geometry.rotateX(-Math.PI / 2);
+    geometry.computeBoundingSphere();
+    return geometry;
+}
+export function Ocean({ config, ...meshProps }) {
+    const resolved = useMemo(() => createOceanConfig(config), [config]);
+    const elapsedRef = useRef(0);
+    const geometry = useMemo(() => createOceanGeometry(resolved), [resolved]);
+    const material = useMemo(() => createOceanMaterial(resolved), [resolved]);
+    useEffect(() => {
+        return () => geometry.dispose();
+    }, [geometry]);
+    useEffect(() => {
+        elapsedRef.current = 0;
+        return () => material.dispose();
+    }, [material]);
+    useFrame((_, delta) => {
+        elapsedRef.current += delta * resolved.timeScale;
+        syncOceanMaterial(material, resolved, elapsedRef.current);
+    });
+    return _jsx("mesh", { ...meshProps, geometry: geometry, material: material });
+}

package/dist/water/OceanConfig.d.ts

@@ -0,0 +1,90 @@
+import * as THREE from "three";
+export declare const MAX_OCEAN_WAVES = 6;
+export type OceanQualityPreset = "low" | "medium" | "high" | "ultra";
+export interface OceanDirectionVector {
+    x: number;
+    z: number;
+}
+export type OceanWaveDirection = number | OceanDirectionVector;
+export interface OceanWaveConfig {
+    amplitude?: number;
+    wavelength?: number;
+    speed?: number;
+    direction?: OceanWaveDirection;
+    steepness?: number;
+}
+export interface OceanColorConfig {
+    shallow?: THREE.ColorRepresentation;
+    deep?: THREE.ColorRepresentation;
+    crest?: THREE.ColorRepresentation;
+    foam?: THREE.ColorRepresentation;
+    opacity?: number;
+    fresnelStrength?: number;
+    horizonBlend?: number;
+}
+export interface OceanFoamConfig {
+    crestThreshold?: number;
+    softness?: number;
+    intensity?: number;
+    coverage?: number;
+}
+export interface OceanConfig {
+    quality?: OceanQualityPreset;
+    size?: number;
+    resolution?: number;
+    amplitude?: number;
+    speed?: number;
+    direction?: OceanWaveDirection;
+    choppiness?: number;
+    steepness?: number;
+    timeScale?: number;
+    color?: OceanColorConfig;
+    foam?: OceanFoamConfig;
+    waves?: readonly OceanWaveConfig[];
+}
+export interface ResolvedOceanColorConfig {
+    shallow: THREE.ColorRepresentation;
+    deep: THREE.ColorRepresentation;
+    crest: THREE.ColorRepresentation;
+    foam: THREE.ColorRepresentation;
+    opacity: number;
+    fresnelStrength: number;
+    horizonBlend: number;
+}
+export interface ResolvedOceanFoamConfig {
+    crestThreshold: number;
+    softness: number;
+    intensity: number;
+    coverage: number;
+}
+export interface ResolvedOceanWaveConfig {
+    amplitude: number;
+    wavelength: number;
+    speed: number;
+    direction: OceanDirectionVector;
+    steepness: number;
+}
+export interface ResolvedOceanConfig {
+    quality: OceanQualityPreset;
+    size: number;
+    resolution: number;
+    amplitude: number;
+    speed: number;
+    direction: OceanDirectionVector;
+    choppiness: number;
+    steepness: number;
+    timeScale: number;
+    color: ResolvedOceanColorConfig;
+    foam: ResolvedOceanFoamConfig;
+    waves: readonly ResolvedOceanWaveConfig[];
+}
+export declare const OCEAN_QUALITY_PRESETS: Record<OceanQualityPreset, {
+    size: number;
+    resolution: number;
+}>;
+export declare const DEFAULT_OCEAN_CONFIG: ResolvedOceanConfig;
+export declare function createOceanConfig(patch?: OceanConfig): ResolvedOceanConfig;
+export declare function buildOceanWaveUniforms(config: ResolvedOceanConfig): {
+    directions: THREE.Vector2[];
+    params: THREE.Vector4[];
+};

package/dist/water/OceanConfig.js

@@ -0,0 +1,131 @@
+import * as THREE from "three";
+export const MAX_OCEAN_WAVES = 6;
+export const OCEAN_QUALITY_PRESETS = {
+    low: { size: 220, resolution: 80 },
+    medium: { size: 360, resolution: 128 },
+    high: { size: 520, resolution: 192 },
+    ultra: { size: 720, resolution: 256 },
+};
+export const DEFAULT_OCEAN_CONFIG = {
+    quality: "medium",
+    size: OCEAN_QUALITY_PRESETS.medium.size,
+    resolution: OCEAN_QUALITY_PRESETS.medium.resolution,
+    amplitude: 1,
+    speed: 1,
+    direction: { x: 0.78, z: 0.62 },
+    choppiness: 1,
+    steepness: 0.72,
+    timeScale: 1,
+    color: {
+        shallow: "#2dc5d3",
+        deep: "#064468",
+        crest: "#8be9ff",
+        foam: "#f4fbff",
+        opacity: 0.88,
+        fresnelStrength: 0.7,
+        horizonBlend: 0.38,
+    },
+    foam: {
+        crestThreshold: 0.64,
+        softness: 0.22,
+        intensity: 0.8,
+        coverage: 0.45,
+    },
+    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 DEFAULT_DIRECTION_OFFSETS = [-8, 7, 21, -31, 46, -58];
+function finiteOr(value, fallback) {
+    return value === undefined || !Number.isFinite(value) ? fallback : value;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function directionFromAngle(degrees) {
+    const radians = THREE.MathUtils.degToRad(degrees);
+    return { x: Math.cos(radians), z: Math.sin(radians) };
+}
+function directionAngle(direction) {
+    return THREE.MathUtils.radToDeg(Math.atan2(direction.z, direction.x));
+}
+function normalizeDirection(direction, fallback) {
+    if (direction === undefined)
+        return fallback;
+    if (typeof direction === "number")
+        return directionFromAngle(direction);
+    const length = Math.hypot(direction.x, direction.z);
+    if (length <= 0.0001 || !Number.isFinite(length))
+        return fallback;
+    return { x: direction.x / length, z: direction.z / length };
+}
+function createDefaultWaves(config) {
+    const baseAngle = directionAngle(config.direction);
+    return DEFAULT_WAVE_SHAPE.map((wave, index) => ({
+        amplitude: wave.amplitude,
+        wavelength: wave.wavelength,
+        speed: wave.speed,
+        direction: directionFromAngle(baseAngle + DEFAULT_DIRECTION_OFFSETS[index]),
+        steepness: wave.steepness,
+    }));
+}
+function resolveWave(wave, fallback, config) {
+    return {
+        amplitude: Math.max(0, finiteOr(wave?.amplitude, fallback.amplitude) * config.amplitude),
+        wavelength: Math.max(0.1, finiteOr(wave?.wavelength, fallback.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),
+    };
+}
+export function createOceanConfig(patch = {}) {
+    const quality = patch.quality ?? DEFAULT_OCEAN_CONFIG.quality;
+    const preset = OCEAN_QUALITY_PRESETS[quality];
+    const withoutWaves = {
+        quality,
+        size: Math.max(1, Math.floor(finiteOr(patch.size, preset.size))),
+        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),
+        direction: normalizeDirection(patch.direction, DEFAULT_OCEAN_CONFIG.direction),
+        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),
+        color: {
+            ...DEFAULT_OCEAN_CONFIG.color,
+            ...patch.color,
+            opacity: clamp(finiteOr(patch.color?.opacity, DEFAULT_OCEAN_CONFIG.color.opacity), 0, 1),
+            fresnelStrength: Math.max(0, finiteOr(patch.color?.fresnelStrength, DEFAULT_OCEAN_CONFIG.color.fresnelStrength)),
+            horizonBlend: clamp(finiteOr(patch.color?.horizonBlend, DEFAULT_OCEAN_CONFIG.color.horizonBlend), 0, 1),
+        },
+        foam: {
+            ...DEFAULT_OCEAN_CONFIG.foam,
+            ...patch.foam,
+            crestThreshold: clamp(finiteOr(patch.foam?.crestThreshold, DEFAULT_OCEAN_CONFIG.foam.crestThreshold), 0, 1),
+            softness: clamp(finiteOr(patch.foam?.softness, DEFAULT_OCEAN_CONFIG.foam.softness), 0.001, 1),
+            intensity: Math.max(0, finiteOr(patch.foam?.intensity, DEFAULT_OCEAN_CONFIG.foam.intensity)),
+            coverage: clamp(finiteOr(patch.foam?.coverage, DEFAULT_OCEAN_CONFIG.foam.coverage), 0, 1),
+        },
+    };
+    const defaultWaves = createDefaultWaves(withoutWaves);
+    const inputWaves = patch.waves ?? defaultWaves;
+    const waves = Array.from({ length: MAX_OCEAN_WAVES }, (_, index) => resolveWave(inputWaves[index], defaultWaves[index], withoutWaves));
+    return { ...withoutWaves, waves };
+}
+export function buildOceanWaveUniforms(config) {
+    const directions = [];
+    const params = [];
+    for (const wave of config.waves) {
+        const waveNumber = (Math.PI * 2) / wave.wavelength;
+        const omega = Math.sqrt(9.81 * waveNumber) * wave.speed;
+        directions.push(new THREE.Vector2(wave.direction.x, wave.direction.z));
+        params.push(new THREE.Vector4(waveNumber, wave.amplitude, wave.steepness, omega));
+    }
+    return { directions, params };
+}