@equinor/videx-3d 2.0.0 → 3.0.0

package/dist/types/components/Ocean/Ocean.d.ts

@@ -0,0 +1,333 @@
+import { ReactNode } from 'react';
+import { BufferGeometry, Group } from 'three';
+import { CommonComponentProps, CustomMaterialProps } from '../../common/types';
+import { Vec2, Vec3 } from '../../sdk/types/common';
+/**
+ * Ocean props
+ * @expand
+ */
+export type OceanProps = CommonComponentProps & CustomMaterialProps & {
+    /**
+     * Geometry to render as the ocean surface. Typically a large plane lying in
+     * the world X/Z plane at sea level (e.g. `createOceanBox(...).surface`). All
+     * wave/foam animation is evaluated in world coordinates, so tiled/patched
+     * geometry aligns seamlessly.
+     */
+    geometry: BufferGeometry;
+    /**
+     * Optional water-body (side walls) geometry, e.g.
+     * `createOceanBox(...).body`. When provided, it is rendered as a separate,
+     * double-sided, transparent-blue volume mesh so the water reads as a body.
+     */
+    bodyGeometry?: BufferGeometry;
+    /**
+     * Optional sea-bed geometry, e.g. `createOceanBox(...).bed`. When provided,
+     * it is rendered as a separate sun-shaded mesh below the surface.
+     */
+    bedGeometry?: BufferGeometry;
+    /** Wind direction in world X/Z (drives wave + foam direction). */
+    windDirection?: Vec2;
+    /**
+     * Wind speed in m/s (U10). Primary driver of the sea state: wave height,
+     * wavelength and foam all follow North-Sea JONSWAP/Pierson-Moskowitz
+     * relations (e.g. ~10 m/s ⇒ Hs ~ 2.1 m, peak wavelength ~ 88 m).
+     */
+    windSpeed?: number;
+    /** Wave height multiplier on top of the spectrum's physical Hs. */
+    amplitude?: number;
+    /** Angular spread (radians) of the wave directions around the wind. */
+    directionalSpread?: number;
+    /** Apparent surface choppiness (normal exaggeration / Gerstner sharpness). */
+    steepness?: number;
+    /**
+     * Enables vertex displacement (`false` = off / flat, per-pixel normals
+     * only). Off by default; at oilfield scale real displacement is
+     * imperceptible except very close to the surface, where only the longest
+     * swells displace. Mainly useful to let floating objects follow the surface
+     * height.
+     */
+    displacement?: boolean;
+    /** Number of summed spectral wave components (compile-time). */
+    waveCount?: number;
+    /** Number of FBM micro-ripple octaves (compile-time). */
+    detailOctaves?: number;
+    /** Deep water colour (seen looking straight down). */
+    deepColor?: string;
+    /** Shallow/scatter water colour (seen at grazing angles). */
+    shallowColor?: string;
+    /** Base body opacity looking straight down (0 = clear, 1 = opaque). */
+    waterOpacity?: number;
+    /** Strength of the large-scale tonal variation (currents / slicks), 0 = off. */
+    tonalVariation?: number;
+    /** Approximate size of the tonal variation patches, in kilometers. */
+    tonalScale?: number;
+    /** Crispness of the tonal variation patch edges (0 = soft, 1 = hard). */
+    tonalSharpness?: number;
+    /** Colour the water drifts toward in the tonal variation (current / algae / pollution tint). */
+    tonalColor?: string;
+    /** Zenith sky colour used for the procedural reflection. */
+    skyColor?: string;
+    /** Horizon sky colour used for the procedural reflection. */
+    horizonColor?: string;
+    /** Reflection intensity multiplier. */
+    reflectionIntensity?: number;
+    /** Sun direction in world space (specular highlight + reflected glow). */
+    sunDirection?: Vec3;
+    /** Sun colour. */
+    sunColor?: string;
+    /** Sun specular shininess exponent. */
+    sunShininess?: number;
+    /** Foam colour. */
+    foamColor?: string;
+    /** Foam amount, 0 = none. */
+    foamAmount?: number;
+    /** Fresnel exponent (higher = reflections concentrated near the horizon). */
+    fresnelPower?: number;
+    /** Micro-ripple frequency (waves per world unit) for close-up detail. */
+    detailScale?: number;
+    /** Micro-ripple normal strength. */
+    detailStrength?: number;
+    /**
+     * Sea-bed base (sandy/yellowish) colour. Only used when `bedGeometry` is
+     * provided. Default `#b8a06a`.
+     */
+    seaBedColor?: string;
+    /**
+     * Strength of the water-colour tint applied to the water-facing (top) side
+     * of the sea bed (0..1). Only used when `bedGeometry` is provided.
+     */
+    seaBedWaterTint?: number;
+    /**
+     * Sea-bed opacity (0..1). Only used when `bedGeometry` is provided. The sea
+     * bed is OIT-routed, so values below 1 let the subsurface geometry below it
+     * show through; 1 (default) makes it a solid occluder.
+     */
+    seaBedOpacity?: number;
+    /**
+     * Sea-bed sand-dune relief strength (0 = off). Only used when `bedGeometry`
+     * is provided. Perturbs the bed's shading normal by a procedural,
+     * footprint-anti-aliased dune height field, adding a subtle sense of depth
+     * and scale that resolves up close and fades to flat far out. Default 0.15.
+     */
+    seaBedDuneStrength?: number;
+    /**
+     * Base sand-dune crest spacing in meters. Only used when `bedGeometry` is
+     * provided. Default 180.
+     */
+    seaBedDuneWavelength?: number;
+    /**
+     * Sand-dune ridge direction in world X/Z. Only used when `bedGeometry` is
+     * provided. Default `[1, 0.6]`.
+     */
+    seaBedDuneDirection?: Vec2;
+    /**
+     * Extra sand-dune crest/trough albedo banding (0 = off). Only used when
+     * `bedGeometry` is provided. Lightens the dune crests and darkens the
+     * troughs on top of the relief shading for a stronger depth cue; fades out
+     * far away like the rest of the dune detail. Default 0.
+     */
+    seaBedDuneSharpness?: number;
+    /**
+     * Per-meter tint build-up of the water body. Only used when `bodyGeometry`
+     * is provided.
+     */
+    bodyFogDensity?: number;
+    /** Densest water-body tint reached far through the water (0..1). */
+    bodyMaxOpacity?: number;
+    /** Animated shimmer amount of the water body, 0 = off. */
+    bodyShimmer?: number;
+    /** Master opacity multiplier (also drives OIT routing). */
+    opacity?: number;
+    /** Toggles visibility of the water-surface mesh. Default `true`. */
+    surfaceVisible?: boolean;
+    /**
+     * Toggles visibility of the water-body (side walls) mesh. Only has an effect
+     * when `bodyGeometry` is provided. Default `true`.
+     */
+    bodyVisible?: boolean;
+    /**
+     * Toggles visibility of the sea-bed mesh. Only has an effect when
+     * `bedGeometry` is provided. Default `true`.
+     */
+    bedVisible?: boolean;
+    /** Debug: render all ocean materials (surface, body, sea bed) as wireframe. */
+    wireframe?: boolean;
+    /**
+     * Children rendered inside the ocean's group, in its local frame. They
+     * receive an {@link OceanSampler} via context (see `useOceanSampler` /
+     * `useBuoyancy`) so floating objects (e.g. a vessel) can follow the waves.
+     */
+    children?: ReactNode;
+};
+/**
+ * Stylized animated ocean surface.
+ *
+ * Renders the provided geometry as a procedurally animated, OIT-compatible
+ * water surface. The wave field is sampled from a North-Sea JONSWAP spectrum
+ * driven by the wind speed (m/s); the visible waves are reconstructed per-pixel
+ * as surface normals (plus a fine micro-ripple layer up close), all evaluated
+ * in world X/Z space so the pattern is continuous across tiled patches with no
+ * repeating texture assets. Level-of-detail uses per-wave footprint
+ * anti-aliasing, so there is no visible LOD ring. Transparency is Fresnel-driven
+ * (see-through looking down, reflective at grazing angles) and composites
+ * correctly with the other transparent subsurface geometry through the
+ * OITRenderPass.
+ *
+ * @example
+ * <Ocean geometry={planeGeometry} windDirection={[1, 0.3]} windSpeed={10} />
+ *
+ * @group Components
+ */
+export declare const Ocean: import('react').ForwardRefExoticComponent<CommonComponentProps & CustomMaterialProps & {
+    /**
+     * Geometry to render as the ocean surface. Typically a large plane lying in
+     * the world X/Z plane at sea level (e.g. `createOceanBox(...).surface`). All
+     * wave/foam animation is evaluated in world coordinates, so tiled/patched
+     * geometry aligns seamlessly.
+     */
+    geometry: BufferGeometry;
+    /**
+     * Optional water-body (side walls) geometry, e.g.
+     * `createOceanBox(...).body`. When provided, it is rendered as a separate,
+     * double-sided, transparent-blue volume mesh so the water reads as a body.
+     */
+    bodyGeometry?: BufferGeometry;
+    /**
+     * Optional sea-bed geometry, e.g. `createOceanBox(...).bed`. When provided,
+     * it is rendered as a separate sun-shaded mesh below the surface.
+     */
+    bedGeometry?: BufferGeometry;
+    /** Wind direction in world X/Z (drives wave + foam direction). */
+    windDirection?: Vec2;
+    /**
+     * Wind speed in m/s (U10). Primary driver of the sea state: wave height,
+     * wavelength and foam all follow North-Sea JONSWAP/Pierson-Moskowitz
+     * relations (e.g. ~10 m/s ⇒ Hs ~ 2.1 m, peak wavelength ~ 88 m).
+     */
+    windSpeed?: number;
+    /** Wave height multiplier on top of the spectrum's physical Hs. */
+    amplitude?: number;
+    /** Angular spread (radians) of the wave directions around the wind. */
+    directionalSpread?: number;
+    /** Apparent surface choppiness (normal exaggeration / Gerstner sharpness). */
+    steepness?: number;
+    /**
+     * Enables vertex displacement (`false` = off / flat, per-pixel normals
+     * only). Off by default; at oilfield scale real displacement is
+     * imperceptible except very close to the surface, where only the longest
+     * swells displace. Mainly useful to let floating objects follow the surface
+     * height.
+     */
+    displacement?: boolean;
+    /** Number of summed spectral wave components (compile-time). */
+    waveCount?: number;
+    /** Number of FBM micro-ripple octaves (compile-time). */
+    detailOctaves?: number;
+    /** Deep water colour (seen looking straight down). */
+    deepColor?: string;
+    /** Shallow/scatter water colour (seen at grazing angles). */
+    shallowColor?: string;
+    /** Base body opacity looking straight down (0 = clear, 1 = opaque). */
+    waterOpacity?: number;
+    /** Strength of the large-scale tonal variation (currents / slicks), 0 = off. */
+    tonalVariation?: number;
+    /** Approximate size of the tonal variation patches, in kilometers. */
+    tonalScale?: number;
+    /** Crispness of the tonal variation patch edges (0 = soft, 1 = hard). */
+    tonalSharpness?: number;
+    /** Colour the water drifts toward in the tonal variation (current / algae / pollution tint). */
+    tonalColor?: string;
+    /** Zenith sky colour used for the procedural reflection. */
+    skyColor?: string;
+    /** Horizon sky colour used for the procedural reflection. */
+    horizonColor?: string;
+    /** Reflection intensity multiplier. */
+    reflectionIntensity?: number;
+    /** Sun direction in world space (specular highlight + reflected glow). */
+    sunDirection?: Vec3;
+    /** Sun colour. */
+    sunColor?: string;
+    /** Sun specular shininess exponent. */
+    sunShininess?: number;
+    /** Foam colour. */
+    foamColor?: string;
+    /** Foam amount, 0 = none. */
+    foamAmount?: number;
+    /** Fresnel exponent (higher = reflections concentrated near the horizon). */
+    fresnelPower?: number;
+    /** Micro-ripple frequency (waves per world unit) for close-up detail. */
+    detailScale?: number;
+    /** Micro-ripple normal strength. */
+    detailStrength?: number;
+    /**
+     * Sea-bed base (sandy/yellowish) colour. Only used when `bedGeometry` is
+     * provided. Default `#b8a06a`.
+     */
+    seaBedColor?: string;
+    /**
+     * Strength of the water-colour tint applied to the water-facing (top) side
+     * of the sea bed (0..1). Only used when `bedGeometry` is provided.
+     */
+    seaBedWaterTint?: number;
+    /**
+     * Sea-bed opacity (0..1). Only used when `bedGeometry` is provided. The sea
+     * bed is OIT-routed, so values below 1 let the subsurface geometry below it
+     * show through; 1 (default) makes it a solid occluder.
+     */
+    seaBedOpacity?: number;
+    /**
+     * Sea-bed sand-dune relief strength (0 = off). Only used when `bedGeometry`
+     * is provided. Perturbs the bed's shading normal by a procedural,
+     * footprint-anti-aliased dune height field, adding a subtle sense of depth
+     * and scale that resolves up close and fades to flat far out. Default 0.15.
+     */
+    seaBedDuneStrength?: number;
+    /**
+     * Base sand-dune crest spacing in meters. Only used when `bedGeometry` is
+     * provided. Default 180.
+     */
+    seaBedDuneWavelength?: number;
+    /**
+     * Sand-dune ridge direction in world X/Z. Only used when `bedGeometry` is
+     * provided. Default `[1, 0.6]`.
+     */
+    seaBedDuneDirection?: Vec2;
+    /**
+     * Extra sand-dune crest/trough albedo banding (0 = off). Only used when
+     * `bedGeometry` is provided. Lightens the dune crests and darkens the
+     * troughs on top of the relief shading for a stronger depth cue; fades out
+     * far away like the rest of the dune detail. Default 0.
+     */
+    seaBedDuneSharpness?: number;
+    /**
+     * Per-meter tint build-up of the water body. Only used when `bodyGeometry`
+     * is provided.
+     */
+    bodyFogDensity?: number;
+    /** Densest water-body tint reached far through the water (0..1). */
+    bodyMaxOpacity?: number;
+    /** Animated shimmer amount of the water body, 0 = off. */
+    bodyShimmer?: number;
+    /** Master opacity multiplier (also drives OIT routing). */
+    opacity?: number;
+    /** Toggles visibility of the water-surface mesh. Default `true`. */
+    surfaceVisible?: boolean;
+    /**
+     * Toggles visibility of the water-body (side walls) mesh. Only has an effect
+     * when `bodyGeometry` is provided. Default `true`.
+     */
+    bodyVisible?: boolean;
+    /**
+     * Toggles visibility of the sea-bed mesh. Only has an effect when
+     * `bedGeometry` is provided. Default `true`.
+     */
+    bedVisible?: boolean;
+    /** Debug: render all ocean materials (surface, body, sea bed) as wireframe. */
+    wireframe?: boolean;
+    /**
+     * Children rendered inside the ocean's group, in its local frame. They
+     * receive an {@link OceanSampler} via context (see `useOceanSampler` /
+     * `useBuoyancy`) so floating objects (e.g. a vessel) can follow the waves.
+     */
+    children?: ReactNode;
+} & import('react').RefAttributes<Group<import('three').Object3DEventMap>>>;

package/dist/types/components/Ocean/index.d.ts

@@ -0,0 +1,6 @@
+export * from './Ocean';
+export * from './ocean-bed-material';
+export * from './ocean-contact';
+export * from './ocean-material';
+export * from './ocean-sampler';
+export * from './ocean-volume-material';

package/dist/types/components/Ocean/ocean-bed-material.d.ts

@@ -0,0 +1,60 @@
+import { Color, ShaderMaterial, ShaderMaterialParameters, Vector2, Vector3 } from 'three';
+export type OceanBedMaterialParameters = ShaderMaterialParameters;
+/**
+ * OIT-compatible sea-bed material for the bottom face of an ocean box. Applies
+ * simple sun-direction diffuse shading so the procedural bed relief is visible,
+ * tints the water-facing (top) side toward the water colour, and keeps the
+ * underside a light sandy/yellowish colour. Rendered double-sided.
+ *
+ * At opacity 1 the OITRenderPass routes it through the opaque pass (writing
+ * depth), so it occludes geometry below it; lower opacity keeps it in the
+ * transparency passes so subsurface geometry shows through. Because the material
+ * has no `opacity` uniform, callers must mirror the alpha onto `material.opacity`
+ * to drive that routing.
+ *
+ * Wired for the OITRenderPass via {@link attachOitVariants} (variants share this
+ * material's `uniforms` by reference, so animated uniforms stay live).
+ */
+export declare class OceanBedMaterial extends ShaderMaterial {
+    isOceanBedMaterial: boolean;
+    constructor(parameters?: OceanBedMaterialParameters);
+    get color(): Color;
+    set color(value: Color | string | number);
+    get waterColor(): Color;
+    set waterColor(value: Color | string | number);
+    /** Strength of the water tint on the water-facing side (0..1). */
+    get waterTint(): number;
+    set waterTint(value: number);
+    get sunDirection(): Vector3;
+    set sunDirection(value: Vector3);
+    get sunColor(): Color;
+    set sunColor(value: Color | string | number);
+    /** Ambient light floor (0..1). */
+    get ambient(): number;
+    set ambient(value: number);
+    /** Bed opacity (also mirror onto `material.opacity` for OIT routing). */
+    get bedOpacity(): number;
+    set bedOpacity(value: number);
+    get masterOpacity(): number;
+    set masterOpacity(value: number);
+    /**
+     * Sand-dune relief strength (0 = off). Perturbs the shading normal by the
+     * analytic slope of a procedural, footprint-anti-aliased dune height field, so
+     * the bed reads with subtle relief up close and fades to flat far out.
+     */
+    get duneStrength(): number;
+    set duneStrength(value: number);
+    /** Base dune crest spacing in meters. */
+    get duneWavelength(): number;
+    set duneWavelength(value: number);
+    /** Dune ridge propagation direction in world X/Z. */
+    get duneDirection(): Vector2;
+    set duneDirection(value: Vector2);
+    /**
+     * Extra crest/trough albedo banding (0 = off). Lightens the dune crests and
+     * darkens the troughs on top of the normal-based shading for a stronger sense
+     * of relief; follows the same footprint fade so it also vanishes far out.
+     */
+    get duneSharpness(): number;
+    set duneSharpness(value: number);
+}

package/dist/types/components/Ocean/ocean-contact.d.ts

@@ -0,0 +1,39 @@
+import { OceanContact } from './ocean-material';
+/**
+ * A function returning a floating object's current contact footprint (in the
+ * ocean's local frame), or `null` when it is temporarily not touching the water
+ * (so it can be skipped). Read every frame by the enclosing `<Ocean>`, so it
+ * should reflect the object's live position/heading.
+ */
+export type OceanContactSource = () => OceanContact | null;
+/**
+ * Registry provided by an `<Ocean>` so its floating children can contribute
+ * contact-foam footprints. Floating components register a source and are
+ * unregistered automatically on unmount.
+ */
+export interface OceanContactRegistry {
+    /** Register a footprint source; returns a function that unregisters it. */
+    register(source: OceanContactSource): () => void;
+}
+/**
+ * Context carrying the enclosing `<Ocean>`'s {@link OceanContactRegistry}, or
+ * `null` when the component is not rendered inside an `<Ocean>`.
+ */
+export declare const OceanContactContext: import('react').Context<OceanContactRegistry | null>;
+/**
+ * Register a floating object's contact footprint with the enclosing `<Ocean>`
+ * so it spreads foam where it meets the water. Reusable by any floating
+ * component: pass a function that returns the object's current footprint (centre,
+ * heading and half-extents) each frame.
+ *
+ * No-op when there is no enclosing `<Ocean>` or when `enabled` is `false`. The
+ * source function is read through a ref, so it can close over changing values
+ * without re-registering every render.
+ *
+ * @example
+ * useOceanContact(
+ *   () => ({ x, z, heading, halfLength, halfWidth, foamWidth }),
+ *   enabled,
+ * );
+ */
+export declare function useOceanContact(getContact: OceanContactSource, enabled?: boolean): void;

package/dist/types/components/Ocean/ocean-material.d.ts

@@ -0,0 +1,145 @@
+import { Color, ShaderMaterial, ShaderMaterialParameters, Vector2, Vector3 } from 'three';
+export type OceanMaterialParameters = ShaderMaterialParameters & {
+    waveCount?: number;
+    detailOctaves?: number;
+    contactCount?: number;
+};
+/**
+ * An oriented footprint of a floating object resting on the ocean surface, used
+ * to spread contact foam around it. All values are in the ocean's local frame
+ * (sea level = local y 0).
+ */
+export type OceanContact = {
+    /** Footprint centre X (local). */
+    x: number;
+    /** Footprint centre Z (local). */
+    z: number;
+    /** Heading in radians (rotation about +Y). */
+    heading: number;
+    /** Half-extent along the heading (e.g. half the hull length). */
+    halfLength: number;
+    /** Half-extent across the heading (e.g. half the beam). */
+    halfWidth: number;
+    /** Width (m) of the foam band straddling the footprint edge. */
+    foamWidth: number;
+    /**
+     * Foam strength multiplier (0 = none, 1 = full). Contact foam is independent
+     * of the wind-driven `foamAmount`, so this controls how much foam the object
+     * generates. Default `1`.
+     */
+    intensity?: number;
+    /**
+     * How much the foam is reduced toward the bow/stern (the forward axis), 0..1.
+     * 0 = an even collar all around; 1 = foam only along the sides (where a hull
+     * pushes the most water). Default `0`.
+     */
+    endFalloff?: number;
+};
+/**
+ * Stylized, OIT-compatible ocean surface material.
+ *
+ * The wave field is a discrete set of directional components sampled from a
+ * JONSWAP spectrum tuned for the North Sea (gamma = 3.3), driven by a single
+ * physical input: the wind speed (m/s, U10). Peak frequency, wavelength and
+ * significant wave height follow the standard Pierson-Moskowitz/JONSWAP
+ * relations, so the wave sizes and spacing are physically plausible (e.g.
+ * U = 10 m/s gives Hs ~ 2.1 m and a peak wavelength ~ 88 m). The spectrum is
+ * sampled on the CPU whenever the wind changes and uploaded as uniform arrays;
+ * the shaders just sum the components.
+ *
+ * All wave/foam animation is evaluated in world X/Z space so it tiles
+ * seamlessly across patched geometry. The material is wired for the
+ * OITRenderPass via {@link attachOitVariants}; because its OIT variants share
+ * this material's `uniforms` object by reference, animated uniforms (time,
+ * wind, colours) stay live through every transparency pass.
+ */
+export declare class OceanMaterial extends ShaderMaterial {
+    isOceanMaterial: boolean;
+    private _waveCount;
+    private _waveHeightScale;
+    private _directionalSpread;
+    private _contactCount;
+    constructor(parameters?: OceanMaterialParameters);
+    /**
+     * (Re)sample the JONSWAP spectrum into the wave-component uniform arrays from
+     * the current wind speed/direction. Cheap (a few iterations) and only called
+     * when the wind/height inputs change, never per frame.
+     */
+    private updateWaves;
+    get time(): number;
+    set time(value: number);
+    get windDirection(): Vector2;
+    set windDirection(value: Vector2);
+    get windSpeed(): number;
+    set windSpeed(value: number);
+    /** Wave height multiplier applied on top of the spectrum's physical Hs. */
+    get amplitude(): number;
+    set amplitude(value: number);
+    /** Angular spread (radians) of the wave directions around the wind. */
+    get directionalSpread(): number;
+    set directionalSpread(value: number);
+    /** Significant wave height (m) derived from the current wind/height scale. */
+    get significantHeight(): number;
+    get steepness(): number;
+    set steepness(value: number);
+    get displacement(): number;
+    set displacement(value: number);
+    get deepColor(): Color;
+    set deepColor(value: Color | string | number);
+    get shallowColor(): Color;
+    set shallowColor(value: Color | string | number);
+    get waterOpacity(): number;
+    set waterOpacity(value: number);
+    /** Strength of the large-scale tonal variation (currents / slicks). */
+    get tonalVariation(): number;
+    set tonalVariation(value: number);
+    /**
+     * Approximate size of the large-scale tonal variation patches, in kilometers.
+     * Larger values give broader, slower-changing current/slick fields; smaller
+     * values break the water up into finer patches.
+     */
+    get tonalScale(): number;
+    set tonalScale(value: number);
+    /**
+     * Crispness of the tonal variation patch boundaries. 0 keeps the soft FBM
+     * gradient; higher values (up to 1) narrow the transition band so the
+     * currents/slicks read as distinct, well-defined regions.
+     */
+    get tonalSharpness(): number;
+    set tonalSharpness(value: number);
+    /** Colour the water drifts toward in the tonal variation (current / algae / pollution tint). */
+    get tonalColor(): Color;
+    set tonalColor(value: Color | string | number);
+    get skyColor(): Color;
+    set skyColor(value: Color | string | number);
+    get horizonColor(): Color;
+    set horizonColor(value: Color | string | number);
+    get reflectionIntensity(): number;
+    set reflectionIntensity(value: number);
+    get sunDirection(): Vector3;
+    set sunDirection(value: Vector3);
+    get sunColor(): Color;
+    set sunColor(value: Color | string | number);
+    get sunShininess(): number;
+    set sunShininess(value: number);
+    get foamColor(): Color;
+    set foamColor(value: Color | string | number);
+    get foamAmount(): number;
+    set foamAmount(value: number);
+    get fresnelPower(): number;
+    set fresnelPower(value: number);
+    get detailScale(): number;
+    set detailScale(value: number);
+    get detailStrength(): number;
+    set detailStrength(value: number);
+    /** Maximum number of contact footprints this material can render at once. */
+    get contactCount(): number;
+    /**
+     * Upload the current set of floating-object contact footprints. Excess
+     * entries beyond {@link contactCount} are ignored. Cheap: it only copies into
+     * the preallocated uniform vectors, so it is safe to call every frame.
+     */
+    setContacts(contacts: OceanContact[]): void;
+    /** Clear all contact footprints (no contact foam). */
+    clearContacts(): void;
+}

package/dist/types/components/Ocean/ocean-sampler.d.ts

@@ -0,0 +1,93 @@
+import { RefObject } from 'react';
+import { Object3D } from 'three';
+import { OceanMaterial } from './ocean-material';
+/**
+ * Read-only sampler for the live ocean surface. Lets non-rendering code (e.g.
+ * floating objects) query the water height at any world X/Z, in sync with the
+ * animated wave field shown on screen.
+ *
+ * The height is summed from the same spectral wave components the shader uses
+ * (`uWaveA`/`uWaveB` + `uTime`, read by reference from the material), so it
+ * always matches the current sea state, wind and animation time. The optional
+ * Gerstner horizontal displacement and the render-time footprint LOD fade are
+ * intentionally ignored — they are visual-only refinements, not needed for a
+ * plausible floating response, and skipping them keeps sampling cheap.
+ *
+ * Coordinates are in the Ocean group's local frame (sea level = local y 0),
+ * which equals world space for the typical flat, unrotated planar ocean.
+ */
+export interface OceanSampler {
+    /** Water surface height (local y) at the given local X/Z. */
+    getHeightAt(x: number, z: number): number;
+    /** Significant wave height (m) of the current sea state. */
+    readonly significantHeight: number;
+}
+/**
+ * Create an {@link OceanSampler} bound to an {@link OceanMaterial}. The sampler
+ * reads the material's wave uniforms by reference, so it reflects sea-state and
+ * time changes without any extra wiring.
+ */
+export declare function createOceanSampler(material: OceanMaterial): OceanSampler;
+/**
+ * Context carrying the current {@link OceanSampler}. An `<Ocean>` provides this
+ * to its children; floating components read it (directly or via
+ * {@link useBuoyancy}) to follow the waves. `null` when the component is not
+ * rendered inside an `<Ocean>` (so consumers can fall back to a static pose).
+ */
+export declare const OceanSamplerContext: import('react').Context<OceanSampler | null>;
+/**
+ * Access the {@link OceanSampler} provided by an enclosing `<Ocean>`, or `null`
+ * when there is none.
+ */
+export declare function useOceanSampler(): OceanSampler | null;
+/** A body-frame sample point `[x, z]` taken at the object's waterline (y 0). */
+export type BuoyancyPoint = [x: number, z: number];
+/**
+ * Options for {@link useBuoyancy}.
+ */
+export type BuoyancyOptions = {
+    /**
+     * Sample points in the object's local X/Z (at its waterline). Required.
+     *
+     * Place them at the true hull extents (e.g. bow / stern / port / starboard):
+     * this is how the object's length and width feed into the motion. Waves
+     * shorter than the span between points decorrelate, so the fitted plane
+     * yields little pitch/roll (a long ship barely reacts to short chop), while
+     * swells longer than the object move it as a whole.
+     */
+    points: BuoyancyPoint[];
+    /** Master switch; when `false` the object is left untouched. Default `true`. */
+    enabled?: boolean;
+    /**
+     * Response rate (per second) of the heave/pitch/roll smoothing. Higher snaps
+     * to the waves faster; lower is more sluggish. Default `3`.
+     */
+    damping?: number;
+    /**
+     * Relative mass / inertia of the object (default `1`). Models how heavy the
+     * object is: the effective response rate is divided by this, so a heavier
+     * object follows the surface more slowly and its motion amplitude shrinks for
+     * fast waves it cannot keep up with. Use a value relative to a "typical"
+     * object of its kind (e.g. `weight / referenceWeight`).
+     */
+    mass?: number;
+};
+/**
+ * Make an object float on the ocean by following the wave field provided by an
+ * enclosing `<Ocean>`. Reusable for any floating component: pass a ref to the
+ * object's group and a few body-frame sample points (e.g. bow / stern / port /
+ * starboard at the waterline).
+ *
+ * Each frame the water height is sampled at those points (accounting for the
+ * object's current heading and X/Z position) and a plane is fitted to them to
+ * drive:
+ *  - heave  → `position.y` (mean surface height),
+ *  - pitch  → `rotation.z` (fore/aft slope),
+ *  - roll   → `rotation.x` (port/starboard slope),
+ * each critically-damped toward its target so the motion stays smooth and
+ * frame-rate independent. The object's heading (`rotation.y`) is left untouched.
+ *
+ * No-op when there is no enclosing `<Ocean>` (the object keeps its static pose).
+ * Allocation-free and only a handful of cheap samples per frame.
+ */
+export declare function useBuoyancy(ref: RefObject<Object3D | null>, options: BuoyancyOptions): void;