@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/types/oceanConfigs.js

@@ -0,0 +1,380 @@
+/**
+ * Config shapes for the ocean that lives in this package.
+ *
+ * Declared locally rather than in `@3driseai/3drise-core`, alongside
+ * `terrainConfigs.ts` and `cloudConfigs.ts`, because the material and the
+ * renderer are here and nothing outside the viewer needs to construct these by
+ * hand.
+ *
+ * Core's `OceanSettings` is the retired shape — a flat plane with a
+ * `materialSettings` block picked out of the water material registry — and is
+ * deliberately left alone: a saved project still carries one. Unlike terrain,
+ * where a legacy blob normalises to NOTHING, a legacy ocean normalises to a real
+ * ocean: a project saved before this system existed very possibly had water, and
+ * dropping it would delete it. See `normalizeOcean` at the bottom.
+ *
+ * An ocean is ONE wave model in two containers, not two renderers — the same way
+ * three of the four cloud types share one marcher and all four landforms share
+ * one height field. `waterType` shapes the spectrum; `host` chooses the mesh.
+ */
+// -----------------------------------------------------------------------------
+// Defaults
+// -----------------------------------------------------------------------------
+const surfaceBase = {
+    host: 'world',
+    waveModel: 'gerstner',
+    seaLevel: 0,
+    size: [40, 40],
+    segments: 128,
+    edgeFade: 0.15,
+    windSpeed: 9,
+    windBearing: 210,
+    fetch: 300,
+    directionalSpread: 32,
+    waveComponents: 20,
+    amplitudeScale: 1,
+    choppiness: 0.85,
+    swell: 0.35,
+    steepness: 0.6,
+    foamAmount: 0.8,
+    foamDecay: 0.5,
+    foamSize: 6,
+    deepColor: '#052539',
+    shallowColor: '#1b7f8c',
+    foamColor: '#eef6f8',
+    absorption: 0.06,
+    clarity: 0.25,
+    roughness: 0.09,
+    specular: 1,
+    sssStrength: 0.7,
+    sssColor: '#2f8f74',
+    detailStrength: 0.55,
+    detailSize: 2.2,
+    reflection: 'planar',
+    refraction: 1,
+    ambient: 1,
+    aerialPerspective: 0.00009,
+    exposure: 1,
+    terrainInteraction: 'auto',
+    terrainShadow: 1,
+    shoreDepth: 3,
+    shoreFoam: 1,
+};
+/** Open ocean. The reference case: long swell under a wind sea, deep colour. */
+export const defaultSeaConfig = {
+    ...surfaceBase,
+    type: 'ocean',
+    waterType: 'sea',
+    preset: '',
+    enabled: true,
+};
+/**
+ * Inland water. Short fetch is doing all the work here — a lake in a gale still
+ * has small, short, steep waves, because there is no room upwind to build
+ * anything longer. Greener and murkier, because inland water is.
+ */
+export const defaultLakeConfig = {
+    ...surfaceBase,
+    type: 'ocean',
+    waterType: 'lake',
+    preset: '',
+    enabled: true,
+    windSpeed: 3.5,
+    fetch: 2,
+    directionalSpread: 22,
+    waveComponents: 12,
+    choppiness: 0.5,
+    swell: 0.05,
+    foamAmount: 0.2,
+    deepColor: '#0d2c2a',
+    shallowColor: '#2c7d6b',
+    absorption: 0.14,
+    clarity: 0.45,
+    detailStrength: 0.7,
+    detailSize: 1.2,
+    aerialPerspective: 0.00006,
+};
+/** Storm sea. Steep, broken, and mostly foam at the top of the range. */
+export const defaultStormConfig = {
+    ...surfaceBase,
+    type: 'ocean',
+    waterType: 'storm',
+    preset: '',
+    enabled: true,
+    windSpeed: 22,
+    fetch: 600,
+    directionalSpread: 45,
+    waveComponents: 28,
+    choppiness: 1.1,
+    swell: 0.5,
+    steepness: 0.8,
+    foamAmount: 1.5,
+    foamDecay: 0.75,
+    foamSize: 12,
+    deepColor: '#0a1c26',
+    shallowColor: '#2b5f66',
+    clarity: 0.6,
+    roughness: 0.16,
+    sssStrength: 0.35,
+    aerialPerspective: 0.00016,
+};
+/**
+ * Coastal water. Narrow spread, because waves refract into alignment with the
+ * beach as they shoal, and a much stronger shoreline because that is the whole
+ * point of the type.
+ */
+export const defaultShoreConfig = {
+    ...surfaceBase,
+    type: 'ocean',
+    waterType: 'shore',
+    preset: '',
+    enabled: true,
+    windSpeed: 7,
+    fetch: 80,
+    directionalSpread: 14,
+    waveComponents: 16,
+    choppiness: 0.95,
+    swell: 0.8,
+    foamAmount: 1,
+    foamDecay: 0.8,
+    deepColor: '#0a3a4a',
+    shallowColor: '#3fb5b0',
+    absorption: 0.09,
+    clarity: 0.35,
+    shoreDepth: 6,
+    shoreFoam: 1.4,
+};
+export const defaultOceanQuality = {
+    levels: 8,
+    segments: 96,
+    cellSize: 1.5,
+    curvature: 1 / (2 * 6371000),
+    reflectionScale: 0.5,
+    refractionScale: 0.5,
+    terrainShadowSteps: 10,
+    terrainShadowDistance: 4000,
+    detailFadeDistance: 900,
+    receiveShadows: true,
+    wireframe: false,
+};
+/** Per-type defaults, for the controller's type switcher. */
+export const OCEAN_DEFAULTS = {
+    sea: defaultSeaConfig,
+    lake: defaultLakeConfig,
+    storm: defaultStormConfig,
+    shore: defaultShoreConfig,
+};
+/** Object-host bodies are small, still and shallow by default — a pool, not a
+ *  shrunken sea. Applied on top of the type when the host is switched. */
+export const OBJECT_HOST_OVERRIDES = {
+    host: 'object',
+    windSpeed: 2,
+    fetch: 0.05,
+    waveComponents: 10,
+    directionalSpread: 40,
+    choppiness: 0.35,
+    swell: 0,
+    foamAmount: 0.05,
+    detailStrength: 0.85,
+    detailSize: 0.4,
+    absorption: 0.25,
+    shoreDepth: 0.6,
+};
+export const OCEAN_SCHEMA = [
+    { key: 'seaLevel', label: 'Sea level', group: 'form', min: -2000, max: 2000, step: 0.5, unit: 'm', hosts: ['world'], description: 'World height of the surface. Independent of the terrain sea level — the shoreline is computed from the difference, so two water bodies at different heights in one scene are fine.' },
+    { key: 'size', label: 'Size', group: 'form', kind: 'vector2', hosts: ['object'], advanced: true, description: 'Extent of this body of water, in world units.' },
+    { key: 'segments', label: 'Resolution', group: 'form', min: 16, max: 512, step: 8, hosts: ['object'], description: 'Grid resolution of this body. A wave shorter than two cells cannot be drawn, so this is what limits how fine the ripples can be.' },
+    { key: 'edgeFade', label: 'Edge fade', group: 'form', min: 0, max: 0.5, step: 0.005, hosts: ['object'], description: 'Fraction of the half-extent over which the waves taper to nothing at the rim. Without it the boundary is a sawn-off cliff of water.' },
+    { key: 'windSpeed', label: 'Wind speed', group: 'waves', min: 0, max: 40, step: 0.1, unit: 'm/s', description: 'Wind at 10 m. The whole sea state comes off this: peak wavelength and wave height both go as the square of it.' },
+    { key: 'windBearing', label: 'Wind bearing', group: 'waves', min: 0, max: 360, step: 1, unit: 'deg', description: 'Direction the wind blows toward. The waves travel with it.' },
+    { key: 'fetch', label: 'Fetch', group: 'waves', min: 0.01, max: 2000, step: 0.5, unit: 'km', description: 'Open water upwind. Short fetch means small, short, steep waves however hard it blows — which is why a lake in a gale looks nothing like an ocean in one.' },
+    { key: 'directionalSpread', label: 'Spread', group: 'waves', min: 0, max: 90, step: 0.5, unit: 'deg', description: 'Angular spread of the wave train about the wind. At 0 the sea is corduroy; real seas run 25-40.' },
+    { key: 'waveComponents', label: 'Wave count', group: 'waves', min: 4, max: 32, step: 1, description: 'Trochoids summed per vertex. Cost is linear in it. Past ~24 the extra components are shorter than the finest cell can carry and are faded out anyway.' },
+    { key: 'amplitudeScale', label: 'Wave height', group: 'waves', min: 0, max: 3, step: 0.01, description: 'Multiplier over the physically derived height. 1 is the Pierson-Moskowitz fit for this wind and fetch.' },
+    { key: 'choppiness', label: 'Choppiness', group: 'waves', min: 0, max: 1.5, step: 0.005, description: 'Horizontal displacement. Peaked crests and flat troughs instead of sine waves — and the source of the Jacobian that whitecaps are found from, so at 0 there is no foam to find.' },
+    { key: 'swell', label: 'Swell', group: 'waves', min: 0, max: 1, step: 0.005, description: 'Energy pushed toward the long, low, narrow-band end. Swell is what has travelled out of the weather that made it.' },
+    { key: 'steepness', label: 'Steepness', group: 'waves', min: 0, max: 1, step: 0.005, description: 'Extra steepening of the shorter components. Clamped below the point where a trochoid folds through itself.' },
+    { key: 'foamAmount', label: 'Whitecaps', group: 'waves', min: 0, max: 2, step: 0.01, description: 'How much of the compressing surface reads as foam. Needs choppiness above zero.' },
+    { key: 'foamDecay', label: 'Foam persistence', group: 'waves', min: 0, max: 1, step: 0.01, description: 'How far foam trails behind the crest that made it. At 0 it flickers on and off with the crest and reads as sparkle rather than foam.' },
+    { key: 'foamSize', label: 'Foam texture', group: 'waves', min: 0.2, max: 40, step: 0.1, unit: 'm', advanced: true, description: 'Size of the break-up noise in the foam.' },
+    { key: 'deepColor', label: 'Deep colour', group: 'surface', kind: 'color', description: 'The body colour of the water — what you see where there is nothing behind it.' },
+    { key: 'shallowColor', label: 'Shallow colour', group: 'surface', kind: 'color', description: 'Water over something close behind it. The grazing tint, and the shallow end of the shoreline ramp.' },
+    { key: 'foamColor', label: 'Foam colour', group: 'surface', kind: 'color', description: 'Whitecaps and shore foam.' },
+    { key: 'absorption', label: 'Absorption', group: 'surface', min: 0, max: 1, step: 0.005, unit: '1/m', description: 'Beer-Lambert absorption per metre. Higher swallows the bottom sooner.' },
+    { key: 'clarity', label: 'Turbidity', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Suspended matter. Lifts the shallow colour and softens what is seen through the surface.' },
+    { key: 'roughness', label: 'Roughness', group: 'surface', min: 0.01, max: 0.6, step: 0.005, description: 'Widens the specular lobe. This is sub-mesh ripple, not surface finish — water itself is smooth.' },
+    { key: 'specular', label: 'Glitter', group: 'surface', min: 0, max: 3, step: 0.01, description: 'Specular strength. The sun path from horizon to camera is most of what says "water" at distance.' },
+    { key: 'sssStrength', label: 'Subsurface', group: 'surface', min: 0, max: 2, step: 0.01, description: 'Sun scattering through the body of a wave — crests glowing when the sun is behind them.' },
+    { key: 'sssColor', label: 'Subsurface colour', group: 'surface', kind: 'color', advanced: true, description: 'Colour of that glow. Green in coastal water, blue offshore.' },
+    { key: 'detailStrength', label: 'Ripple detail', group: 'surface', min: 0, max: 2, step: 0.01, description: 'Per-fragment normal detail below mesh resolution. This is where the energy lost to the per-ring wave LOD goes.' },
+    { key: 'detailSize', label: 'Ripple size', group: 'surface', min: 0.1, max: 20, step: 0.05, unit: 'm', description: 'Size of that detail.' },
+    { key: 'ambient', label: 'Ambient', group: 'surface', min: 0, max: 3, step: 0.01, advanced: true, description: 'Sky-dome fill, from the same atmosphere the sky and clouds use.' },
+    { key: 'aerialPerspective', label: 'Aerial perspective', group: 'surface', min: 0, max: 0.0006, step: 0.000002, unit: '1/m', description: 'Rate distant water fades into the sky behind it. Water needs more of this than ground, because most of what you see looking at the sea is the sky.' },
+    { key: 'exposure', label: 'Exposure', group: 'surface', min: 0.2, max: 4, step: 0.01, advanced: true, description: 'Radiance scale, so water matches sky, clouds and terrain whether or not the cloud composite tonemaps the frame.' },
+    { key: 'terrainShadow', label: 'Terrain shadow', group: 'shore', min: 0, max: 1, step: 0.01, description: 'Strength of the shadow marched down the sun vector against the terrain height field. Terrain does not write into the scene shadow map, so this is the only way a headland shadows the water beside it.' },
+    { key: 'shoreDepth', label: 'Shore depth', group: 'shore', min: 0.05, max: 60, step: 0.05, unit: 'm', description: 'Depth over which the shallow colour and the shore foam ramp in.' },
+    { key: 'shoreFoam', label: 'Shore foam', group: 'shore', min: 0, max: 2, step: 0.01, description: 'Foam where the ground comes up through the surface.' },
+];
+export const OCEAN_QUALITY_SCHEMA = [
+    { key: 'levels', label: 'Clipmap levels', group: 'quality', min: 2, max: 12, step: 1, description: 'Each ring doubles its cell size, so visible radius is roughly cellSize x segments x 2^(levels-1). Levels only buy reach; there is no point past where haze has dissolved the surface.' },
+    { key: 'segments', label: 'Ring resolution', group: 'quality', min: 32, max: 320, step: 8, description: 'Grid resolution per ring side. Vertex cost is levels x segments^2 x 0.75, since every ring above the first is hollow.' },
+    { key: 'cellSize', label: 'Cell size', group: 'quality', min: 0.1, max: 32, step: 0.1, unit: 'm', description: 'Finest cell, at the camera, and the shortest wave that can be drawn anywhere. Waves are metres, not kilometres, so on water this matters more than reach does.' },
+    { key: 'curvature', label: 'Planetary curvature', group: 'quality', min: 0, max: 0.0000012, step: 0.00000001, advanced: true, description: '1/(2R). Drops the surface with the square of distance so it meets a real horizon.' },
+    { key: 'detailFadeDistance', label: 'Detail fade distance', group: 'quality', min: 50, max: 8000, step: 25, unit: 'm', description: 'Distance over which the fragment-stage ripple fades out. Removes far-field shimmer and buys back most of its own cost.' },
+    { key: 'terrainShadowSteps', label: 'Terrain shadow steps', group: 'quality', min: 0, max: 32, step: 1, description: 'Steps in the terrain shadow march, nearest the camera. 0 turns it off entirely — the biggest single saving when the scene has terrain.' },
+    { key: 'terrainShadowDistance', label: 'Terrain shadow distance', group: 'quality', min: 0, max: 40000, step: 100, unit: 'm', description: 'Range over which that march fades out. It runs per vertex, so lowering this drops whole rings out of it.' },
+    { key: 'reflectionScale', label: 'Reflection resolution', group: 'quality', min: 0, max: 1, step: 0.05, description: 'Planar reflection target size, as a fraction of the frame. 0 disables the pass and falls back to the environment map.' },
+    { key: 'refractionScale', label: 'Refraction resolution', group: 'quality', min: 0, max: 1, step: 0.05, description: 'Refraction and depth grab size, as a fraction of the frame. The shoreline reads its depth from this.' },
+];
+export const defaultOceanWaterSettings = {
+    id: '3drise-water',
+    type: 'ocean',
+    config: { ...defaultSeaConfig, enabled: false },
+    quality: { ...defaultOceanQuality },
+};
+// =============================================================================
+// Normalisation
+// =============================================================================
+//
+// A published scene loads whatever was in the database the day it was saved.
+//
+// **This is where the ocean deliberately differs from the terrain.**
+// `normalizeTerrain` returns null for a legacy blob, because a project saved
+// before terrain existed never had ground and defaulting one in would give it a
+// landscape it was never authored with. A project saved before THIS system very
+// possibly had water — the old ocean is a visible flat plane with a water
+// material — so returning null would DELETE it. A legacy blob is therefore
+// mapped, not dropped.
+//
+// Each block still merges over its own defaults separately, so editing quality
+// does not hand the surface a new config object and rebuild the clipmap.
+const WATER_TYPES = ['sea', 'lake', 'storm', 'shore'];
+const WATER_HOSTS = ['world', 'object'];
+const isRecord = (v) => typeof v === 'object' && v !== null;
+/**
+ * The five water material variants the old ocean shipped with, onto the closest
+ * new type and the numbers that make it read the same way. This is why the
+ * preset list is seeded from the same five names: they were already the
+ * vocabulary.
+ */
+const LEGACY_VARIANTS = {
+    Lake: { waterType: 'lake', settings: {} },
+    Ocean: { waterType: 'sea', settings: {} },
+    Storm: { waterType: 'storm', settings: {} },
+    Tropical: {
+        waterType: 'sea',
+        settings: {
+            windSpeed: 5,
+            fetch: 120,
+            deepColor: '#0a5a7a',
+            shallowColor: '#4fd6c8',
+            absorption: 0.04,
+            clarity: 0.12,
+            sssColor: '#39c8b0',
+        },
+    },
+    Arctic: {
+        waterType: 'sea',
+        settings: {
+            windSpeed: 13,
+            deepColor: '#0b2436',
+            shallowColor: '#7fb6c9',
+            sssColor: '#8fd0e0',
+            clarity: 0.15,
+            foamAmount: 1.1,
+        },
+    },
+};
+/**
+ * A blob in the retired shape: `meshSettings` + `materialSettings` + a
+ * `config` of `{ planeSize, planeSegments }`. Recognised by the absence of
+ * `waveModel`, which every new config has.
+ *
+ * The plane it was authored with decides the host. The default was 10 000, so
+ * every existing scene becomes the world ocean — which is what those scenes
+ * look like today. A small plane was somebody placing a pond, and becomes one.
+ */
+function fromLegacy(raw) {
+    const mesh = isRecord(raw.meshSettings) ? raw.meshSettings : {};
+    const material = isRecord(raw.materialSettings) ? raw.materialSettings : {};
+    const legacyConfig = isRecord(raw.config) ? raw.config : {};
+    const variantName = typeof material.materialVariant === 'string' ? material.materialVariant : 'Ocean';
+    const variant = LEGACY_VARIANTS[variantName] ?? LEGACY_VARIANTS.Ocean;
+    const planeSize = Array.isArray(legacyConfig.planeSize) ? Number(legacyConfig.planeSize[0]) : 10000;
+    const host = Number.isFinite(planeSize) && planeSize < 2000 ? 'object' : 'world';
+    const position = Array.isArray(mesh.position) ? mesh.position : [0, 0, 0];
+    const level = Number(position[1]);
+    const base = OCEAN_DEFAULTS[variant.waterType];
+    return {
+        ...base,
+        ...(host === 'object' ? OBJECT_HOST_OVERRIDES : {}),
+        ...variant.settings,
+        type: 'ocean',
+        waterType: variant.waterType,
+        host,
+        enabled: mesh.visible !== false,
+        seaLevel: Number.isFinite(level) ? level : 0,
+        size: host === 'object' && Number.isFinite(planeSize) ? [planeSize, planeSize] : base.size,
+        preset: variantName in LEGACY_VARIANTS ? variantName : '',
+    };
+}
+/**
+ * Surface block merged over its type's defaults, or null when there is nothing
+ * to render. Unlike the terrain, a legacy blob is mapped rather than dropped —
+ * see the note above.
+ */
+export function normalizeOcean(raw, whole) {
+    if (!isRecord(raw)) {
+        // No config block. If the surrounding blob is the retired shape, it is a
+        // real ocean that predates this system; map it.
+        if (isRecord(whole) && (isRecord(whole.materialSettings) || isRecord(whole.meshSettings))) {
+            return fromLegacy(whole);
+        }
+        return null;
+    }
+    if (typeof raw.waveModel !== 'string' && isRecord(whole) && isRecord(whole.materialSettings)) {
+        return fromLegacy(whole);
+    }
+    const waterType = WATER_TYPES.includes(raw.waterType)
+        ? raw.waterType
+        : 'sea';
+    const host = WATER_HOSTS.includes(raw.host)
+        ? raw.host
+        : 'world';
+    return {
+        ...OCEAN_DEFAULTS[waterType],
+        ...(host === 'object' ? OBJECT_HOST_OVERRIDES : {}),
+        ...raw,
+        type: 'ocean',
+        waterType,
+        host,
+    };
+}
+export function normalizeOceanQuality(raw) {
+    return { ...defaultOceanQuality, ...(isRecord(raw) ? raw : {}) };
+}
+/** A whole settings blob, from a project of any age. */
+export function normalizeOceanSettings(raw) {
+    const source = isRecord(raw) ? raw : {};
+    const config = normalizeOcean(source.config, source);
+    const settings = {
+        id: typeof source.id === 'string' ? source.id : defaultOceanWaterSettings.id,
+        type: 'ocean',
+        config: config ?? { ...defaultSeaConfig, enabled: false },
+        quality: normalizeOceanQuality(source.quality),
+    };
+    if (settings.config.host === 'object') {
+        const mesh = isRecord(source.meshSettings) ? source.meshSettings : {};
+        settings.meshSettings = {
+            visible: mesh.visible !== false,
+            position: (Array.isArray(mesh.position) ? mesh.position : [0, settings.config.seaLevel, 0]),
+            rotation: (Array.isArray(mesh.rotation) ? mesh.rotation : [0, 0, 0]),
+            scale: (Array.isArray(mesh.scale) ? mesh.scale : [1, 1, 1]),
+        };
+    }
+    if (source.animations)
+        settings.animations = source.animations;
+    if (source.mouseMove)
+        settings.mouseMove = source.mouseMove;
+    return settings;
+}

package/dist/types/terrainConfigs.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Config shapes for the procedural terrain system that lives in this package.
+ *
+ * Declared locally rather than in `@3driseai/3drise-core`, alongside
+ * `cloudConfigs.ts` and `gridConfigs.ts`, because the material and the renderer
+ * are here and nothing outside the viewer needs to construct these by hand.
+ *
+ * Core's `TerrainSettings` is the retired flat shape (`visible` +
+ * `displacementScale`) and is deliberately left alone: a saved project still
+ * carries it, and `normalizeTerrain` below is what turns one into nothing rather
+ * than into a mountain range the scene was never authored with.
+ *
+ * A terrain is ONE landform model with per-type shaping, not four renderers —
+ * the same way three of the four cloud types share one marcher. What separates
+ * mountains from dunes is the operator applied to the fBm and the numbers around
+ * it, so the type is a config field the shader branches on.
+ */
+/** The four landforms the height function shapes. */
+export type TerrainType = 'mountains' | 'dunes' | 'hills' | 'canyon';
+/** Fields every terrain shares, whatever its landform. */
+export interface TerrainSurfaceConfig {
+    enabled: boolean;
+    /** Peak height above `seaLevel`, in world units. Also the denominator for
+     *  every height-keyed splat threshold, so raising it does not re-shuffle the
+     *  snow line. */
+    elevation: number;
+    /** World Y the terrain is built around. The clipmap sits here when the height
+     *  field returns zero, so this is where a placed object meets flat ground. */
+    seaLevel: number;
+    /** Horizontal size of the primary landform, in world units. The single knob
+     *  that decides whether this reads as a mountain range or a gravel pile. */
+    featureSize: number;
+    /** fBm octave count. Each one doubles frequency, so 8 spans a 256:1 range of
+     *  detail; past ~10 the extra octaves are below the finest clipmap cell and
+     *  only cost. Distant rings drop octaves automatically. */
+    octaves: number;
+    /** Frequency multiplier per octave. 2.0 is the textbook value; slightly above
+     *  it (2.02-2.15) breaks the grid alignment that otherwise shows as a faint
+     *  square lattice on large flat areas. */
+    lacunarity: number;
+    /** Amplitude multiplier per octave. Below 0.5 the terrain goes smooth and
+     *  rolling; above it, jagged and fractal-looking. */
+    gain: number;
+    /** 0 gives rounded billow hills, 1 gives knife ridges. The single strongest
+     *  cue for "mountain" versus "dune field". */
+    ridgeSharpness: number;
+    /** Domain warp amount, as a fraction of `featureSize`. This is what stops fBm
+     *  looking like fBm: it bends ridge lines into the curved, branching shapes
+     *  real drainage produces. Zero gives the obvious noise-blob silhouette. */
+    warpStrength: number;
+    /** Scale of the warp field relative to `featureSize`. Above ~1 the warp is
+     *  slower than the terrain and it drifts rather than bends. */
+    warpSize: number;
+    /** Derivative damping. Octaves are attenuated where the accumulated slope is
+     *  already steep, which flattens valley floors and sharpens flanks — the
+     *  cheapest approximation of erosion there is, and the difference between
+     *  "noise" and "landscape". */
+    erosion: number;
+    /** Number of strata steps. 0 is off. Canyon country is sedimentary, and the
+     *  horizontal banding is most of what makes a mesa read as a mesa. */
+    terraces: number;
+    /** How hard a terrace edge is. 0 is a smooth ramp, 1 a near-vertical riser. */
+    terraceSharpness: number;
+    /** Orientation of the dune crests and the prevailing ridge grain, in degrees.
+     *  Dunes are transverse to the wind, so this is a wind bearing. */
+    bearing: number;
+    /** Crest-to-crest distance of the dune train, in world units. */
+    duneWavelength: number;
+    /** Lee-slope steepening. Real dunes are asymmetric — a long windward ramp and
+     *  a short slip face at the angle of repose. At 0 they are sine waves. */
+    duneAsymmetry: number;
+    /** Fraction of the height range flattened into mesa tops. */
+    plateau: number;
+    /** Depth of the incised channel network, as a fraction of `elevation`. */
+    valleyDepth: number;
+    /** Width of the incision. Narrow cuts slot canyons; wide ones cut broad washes. */
+    valleyWidth: number;
+    /** Ground at the bottom of the height range. */
+    lowColor: string;
+    /** Ground at mid height. */
+    midColor: string;
+    /** Exposed rock, splatted by slope rather than by height — which is the whole
+     *  trick: rock appears wherever the surface is too steep to hold anything,
+     *  at any altitude, so cliffs read as cliffs. */
+    rockColor: string;
+    /** Snow, salt or bleached stone at the top of the range. */
+    peakColor: string;
+    /** Slope (0 flat, 1 vertical) at which rock starts showing through. */
+    slopeRockStart: number;
+    /** Slope at which the surface is bare rock. */
+    slopeRockEnd: number;
+    /** Height fraction where the peak layer begins. */
+    peakLevel: number;
+    /** Width of the peak transition, in height fractions. A hard snow line is
+     *  physically right for temperature but reads as a decal; ~0.1 is convincing. */
+    peakBlend: number;
+    /** Peak coverage lost per unit slope. Snow does not sit on a vertical face,
+     *  and this is what keeps a summit from looking dipped in paint. */
+    peakSlopeFalloff: number;
+    /** Large-scale albedo break-up. Without it a splat layer is one flat colour
+     *  across kilometres and the eye reads it as untextured. */
+    macroVariation: number;
+    /** Size of that variation, in world units. */
+    macroSize: number;
+    /** Strength of the high-frequency normal detail added in the fragment stage —
+     *  bumps far below the mesh resolution. */
+    detailStrength: number;
+    /** Size of that detail, in world units. */
+    detailSize: number;
+    roughness: number;
+    /** Specular strength. Rock is nearly matte; wet sand and snow are not. */
+    specular: number;
+    /** Sky fill. Terrain is lit by the whole dome, not only the sun, and freezing
+     *  this is what makes a night landscape glow. */
+    ambient: number;
+    /** Ground-bounce fill on downward-facing surfaces, tinted by the low colour. */
+    bounce: number;
+    /** Strength of the analytic self-shadow marched down the sun vector. This is
+     *  what puts a mountain's shadow in its own valley, at any scale, with no
+     *  shadow-map resolution to run out of. */
+    sunShadow: number;
+    /** Penumbra width of that shadow. Larger reads as a hazy day. */
+    shadowSoftness: number;
+    /** Rate distant terrain fades into the sky it is seen through. The main cue
+     *  for how large the landscape reads, and the reason a horizon looks like a
+     *  horizon rather than a cut-out. */
+    aerialPerspective: number;
+}
+/**
+ * The terrain, as stored.
+ *
+ * `type` is 'terrain' — the OBJECT type — with the landform kept separately in
+ * `terrainType`, exactly as the clouds keep `deckType` apart from `type`.
+ * Collapsing the two would make the terrain invisible to anything that routes on
+ * object type.
+ */
+export type TerrainConfig = TerrainSurfaceConfig & {
+    type: 'terrain';
+    terrainType: TerrainType;
+    /** Name of the preset the numbers came from, or '' once any of them is edited.
+     *  Purely a UI bookmark — the renderer never reads it. */
+    preset?: string;
+};
+/** Cost and extent knobs. */
+export interface TerrainQualityConfig {
+    /** Clipmap ring count. Each ring doubles its cell size, so the visible radius
+     *  is roughly `cellSize * segments * 2^(levels-1)`: 9 levels of 192 segments at
+     *  2 m reaches ~98 km, which is past where haze has dissolved the ground.
+     *
+     *  There is no adaptive scaling of the pyramid, deliberately. Tying the cell
+     *  size to camera altitude sounds right and is not: a clipmap triangle already
+     *  subtends a constant angle whatever the scale, so scaling buys nothing in
+     *  detail, and scaling by height above SEA LEVEL — the only height available
+     *  without reading the field back off the GPU — coarsens a camera that is
+     *  standing on a mountain rather than flying over one. Extra levels are cheap;
+     *  a wrong guess about altitude is not. */
+    levels: number;
+    /** Grid resolution per ring side. Vertex cost is `levels * segments^2 * 0.75`,
+     *  since every ring above the first is hollow. */
+    segments: number;
+    /** Finest cell, in world units, at the camera. */
+    cellSize: number;
+    /** 1/(2R). Drops the surface away with the square of distance so the terrain
+     *  meets a real horizon instead of running flat to the far plane. Zero gives a
+     *  flat world, which at these extents looks wrong long before it looks flat. */
+    curvature: number;
+    /** Steps in the analytic sun-shadow march, at the camera. Falls to four as the
+     *  shadow fades out with distance. */
+    shadowSteps: number;
+    /** Distance over which the analytic self-shadow fades to nothing.
+     *
+     *  The march is the most expensive thing the renderer does and past a few
+     *  kilometres it buys nothing — haze has already taken the contrast out of the
+     *  ground and a ridge shadow is a couple of pixels wide. Cutting it here drops
+     *  the outer clipmap rings, two thirds of all vertices, out of the march
+     *  entirely. */
+    shadowDistance: number;
+    /** Distance over which fragment-stage detail fades out. Beyond it the surface
+     *  is shaded from the mesh normal alone, which removes far-field shimmer and
+     *  buys back most of its own cost. */
+    detailFadeDistance: number;
+    /** Receive the scene's directional shadow map, so objects cast onto terrain.
+     *  Terrain-on-terrain shadowing is analytic and unaffected by this. */
+    receiveShadows: boolean;
+    /** Radiance scale, so terrain sits at the same exposure as the sky and clouds
+     *  whether or not the cloud composite is the thing tonemapping the frame. */
+    exposure: number;
+    wireframe: boolean;
+}
+export declare const defaultMountainsConfig: TerrainConfig;
+export declare const defaultHillsConfig: TerrainConfig;
+export declare const defaultDunesConfig: TerrainConfig;
+export declare const defaultCanyonConfig: TerrainConfig;
+export declare const defaultTerrainQuality: TerrainQualityConfig;
+/** Per-type defaults, for the controller's type switcher. */
+export declare const TERRAIN_DEFAULTS: Record<TerrainType, TerrainConfig>;
+export type TerrainPropertyGroup = 'form' | 'surface' | 'lighting' | 'quality';
+/** Everything the controller needs to build a row and everything the AI context
+ *  builder needs to know what a knob does and where it is safe. The runtime never
+ *  reads this — defaults live in the config objects above. */
+export interface TerrainPropertySchema {
+    key: string;
+    label: string;
+    group: TerrainPropertyGroup;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    description: string;
+    advanced?: boolean;
+    /** Only show for these terrain types. Absent means all. */
+    types?: TerrainType[];
+}
+export declare const TERRAIN_SCHEMA: TerrainPropertySchema[];
+export declare const TERRAIN_QUALITY_SCHEMA: TerrainPropertySchema[];
+/**
+ * A terrain, as stored.
+ *
+ * Named `ProceduralTerrainSettings` because core already exports a
+ * `TerrainSettings` — the retired flat shape — and a saved project may still
+ * carry one. Same reason `VolumetricCloudsSettings` is not `CloudsSettings`.
+ *
+ * There is deliberately no `meshSettings` and no `materialSettings`: the clipmap
+ * follows the camera so it has no transform to edit, and the material is not
+ * swappable, so the Transform and Material tabs do not apply.
+ */
+export interface ProceduralTerrainSettings {
+    id: string;
+    type: 'terrain';
+    /** The landform. Named `config` to match the house shape for an object's
+     *  editable block. */
+    config: TerrainConfig;
+    quality: TerrainQualityConfig;
+}
+export declare const defaultProceduralTerrainSettings: ProceduralTerrainSettings;
+/**
+ * Surface block merged over its type's defaults, or null when there is nothing to
+ * render — including the retired flat shape, which has no `config` and must draw
+ * nothing rather than a landscape the project was never authored with.
+ *
+ * An unknown or missing `terrainType` falls back to hills rather than rendering
+ * nothing: a scene that says `enabled: true` should show ground.
+ */
+export declare function normalizeTerrain(raw: unknown): TerrainConfig | null;
+export declare function normalizeTerrainQuality(raw: unknown): TerrainQualityConfig;
+/**
+ * A whole settings blob, from a project of any age. The flat legacy shape has no
+ * `config`, so it normalises to a disabled terrain rather than to a default one.
+ */
+export declare function normalizeTerrainSettings(raw: unknown): ProceduralTerrainSettings;
+//# sourceMappingURL=terrainConfigs.d.ts.map

package/dist/types/terrainConfigs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrainConfigs.d.ts","sourceRoot":"","sources":["../../src/types/terrainConfigs.ts"],"names":[],"mappings":"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"}