@jgengine/core 0.8.0 → 0.10.0

package/dist/world/terrain.js

@@ -1,3 +1,4 @@
+import { nearestOnPath } from "./roads.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -13,6 +14,7 @@ function hash2(ix, iz, seed) {
     h ^= h >>> 12;
     return (h >>> 0) / 4294967295;
 }
+/** Smoothly interpolated 2D value noise in `[-1, 1]` for the given seed. */
 export function valueNoise(x, z, seed) {
     const x0 = Math.floor(x);
     const z0 = Math.floor(z);
@@ -28,6 +30,7 @@ export function valueNoise(x, z, seed) {
     const bottom = lerp(v01, v11, sx);
     return lerp(top, bottom, sz) * 2 - 1;
 }
+/** Layers `valueNoise` octaves per `config` into a single normalized noise sample. */
 export function fractalNoise(x, z, config) {
     let amplitude = 1;
     let frequency = config.frequency;
@@ -57,6 +60,7 @@ export function seedFrom(value, fallback) {
     }
     return fallback;
 }
+/** Derives a `TerrainField.sampleNormal` from a height sampler via finite-difference gradients. */
 export function withNormal(sampleHeight) {
     const epsilon = 0.75;
     return (x, z) => {
@@ -81,9 +85,11 @@ export const FLAT_FIELD = {
     sampleHeight: () => 0,
     sampleNormal: () => [0, 1, 0],
 };
+/** A flat, zero-height `TerrainField` for arenas with no elevation. */
 export function flatField() {
     return FLAT_FIELD;
 }
+/** Builds a `TerrainField` whose height is fractal noise shaped by `config`. */
 export function noiseField(config = {}) {
     const fractal = {
         seed: seedFrom(config.seed, 1337),
@@ -120,6 +126,7 @@ function smoothstep(edge0, edge1, value) {
     const t = clamp01((value - edge0) / (edge1 - edge0));
     return t * t * (3 - 2 * t);
 }
+/** Builds a `TerrainField` with a flat spawn plateau, rolling hills, and a basin, for combat arenas. */
 export function arenaField(config = {}) {
     const seed = seedFrom(config.seed ?? "arena", 7);
     const rolling = {
@@ -150,9 +157,86 @@ export function arenaField(config = {}) {
 }
 export function groundFieldFor(world) {
     if (world !== undefined && world.kind === "environment")
-        return resolveTerrainField(world.terrain);
+        return resolveEnvironmentField(world);
     return flatField();
 }
+/** Whether a world declares real terrain (base heightfield or islands) rather than a flat plane — gates terrain-floor sampling in the movement controllers. */
+export function hasEnvironmentTerrain(world) {
+    return world?.kind === "environment" && (world.terrain !== undefined || (world.islands?.length ?? 0) > 0);
+}
+/** Ground height between islands when no base terrain exists — deep enough to read as a fall into the void, finite so physics stays sane. */
+export const ISLAND_VOID_HEIGHT = -256;
+function islandContains(descriptor, x, z) {
+    return (Math.abs(x - descriptor.origin[0]) <= descriptor.bounds.w / 2 &&
+        Math.abs(z - descriptor.origin[1]) <= descriptor.bounds.d / 2);
+}
+/**
+ * Composes a base terrain and any number of bounded islands into one world field: inside an island's
+ * rect the island's own field (sampled in island-local coordinates) wins, elsewhere the base terrain
+ * answers, and with no base the gap is `ISLAND_VOID_HEIGHT` void. Later islands win overlaps.
+ */
+export function composeIslandFields(base, islands, voidHeight = ISLAND_VOID_HEIGHT) {
+    if (islands.length === 0)
+        return base ?? flatField();
+    const resolved = islands.map((descriptor) => ({
+        descriptor,
+        field: resolveTerrainField({ ...descriptor, kind: "terrain" }),
+    }));
+    function islandAt(x, z) {
+        for (let index = resolved.length - 1; index >= 0; index -= 1) {
+            if (islandContains(resolved[index].descriptor, x, z))
+                return resolved[index];
+        }
+        return null;
+    }
+    const sampleHeight = (x, z) => {
+        const island = islandAt(x, z);
+        if (island !== null) {
+            return island.field.sampleHeight(x - island.descriptor.origin[0], z - island.descriptor.origin[1]);
+        }
+        return base !== null ? base.sampleHeight(x, z) : voidHeight;
+    };
+    return {
+        sampleHeight,
+        sampleNormal(x, z) {
+            const island = islandAt(x, z);
+            if (island !== null) {
+                return island.field.sampleNormal(x - island.descriptor.origin[0], z - island.descriptor.origin[1]);
+            }
+            return base !== null ? base.sampleNormal(x, z) : [0, 1, 0];
+        },
+        ...(base?.bounds === undefined ? {} : { bounds: base.bounds }),
+        ...(base?.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
+    };
+}
+/** The full ground field for an environment world: base `terrain` composed with any `islands`. */
+export function resolveEnvironmentField(feature) {
+    const base = feature.terrain === undefined ? null : resolveTerrainField(feature.terrain);
+    if (feature.islands === undefined || feature.islands.length === 0)
+        return base ?? flatField();
+    return composeIslandFields(base, feature.islands);
+}
+/** Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6). */
+export function sampleSlope(field, x, z) {
+    const [nx, ny, nz] = field.sampleNormal(x, z);
+    const horizontal = Math.hypot(nx, nz);
+    if (horizontal < 1e-9)
+        return { downhill: [0, 0], steepness: 0 };
+    return {
+        downhill: [nx / horizontal, nz / horizontal],
+        steepness: horizontal / Math.max(ny, 1e-9),
+    };
+}
+/**
+ * Downhill force/acceleration from the local slope: direction × sin(slope angle) × `scale`.
+ * Add it to any integrator's XZ velocity each tick (`scale` ≈ gravity for a free-rolling body).
+ */
+export function slopeForce(field, x, z, scale = 9.8) {
+    const [nx, , nz] = field.sampleNormal(x, z);
+    if (Math.hypot(nx, nz) < 1e-9)
+        return [0, 0];
+    return [nx * scale, nz * scale];
+}
 export const DEFAULT_TERRAIN_MATERIAL = "grass";
 export const TERRAIN_MATERIAL_PALETTES = {
     grass: { low: "#30402c", high: "#7f8b50", waterline: "#1d4c6e" },
@@ -160,9 +244,41 @@ export const TERRAIN_MATERIAL_PALETTES = {
     snow: { low: "#c7d3dc", high: "#ffffff", waterline: "#3a6ea5" },
     rock: { low: "#3a3a3d", high: "#8a8a8d", waterline: "#1d4c6e" },
     ash: { low: "#2b2622", high: "#5c534a", waterline: "#3a3630" },
+    highland: { low: "#414f33", high: "#a3a86b", waterline: "#365f63" },
+    slate: { low: "#2f3540", high: "#7d8896", waterline: "#26404f" },
+};
+const DEFAULT_TERRAIN_DETAIL = {
+    rockColor: "#6f7175",
+    sandColor: "#c2b283",
+    snowColor: "#eef3f7",
+    rockSlopeStart: 0.42,
+    snowHeight: 26,
+    detailScale: 5,
+    macroScale: 45,
+    roughness: 0.9,
+    strength: 1,
 };
+/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level. */
+export function resolveTerrainDetail(config, terrainWaterLevel = 0) {
+    return {
+        rockColor: config.rockColor ?? DEFAULT_TERRAIN_DETAIL.rockColor,
+        sandColor: config.sandColor ?? DEFAULT_TERRAIN_DETAIL.sandColor,
+        snowColor: config.snowColor ?? DEFAULT_TERRAIN_DETAIL.snowColor,
+        rockSlopeStart: config.rockSlopeStart ?? DEFAULT_TERRAIN_DETAIL.rockSlopeStart,
+        snowHeight: config.snowHeight ?? DEFAULT_TERRAIN_DETAIL.snowHeight,
+        detailScale: config.detailScale ?? DEFAULT_TERRAIN_DETAIL.detailScale,
+        macroScale: config.macroScale ?? DEFAULT_TERRAIN_DETAIL.macroScale,
+        roughness: config.roughness ?? DEFAULT_TERRAIN_DETAIL.roughness,
+        strength: config.strength ?? DEFAULT_TERRAIN_DETAIL.strength,
+        waterLevel: config.waterLevel ?? terrainWaterLevel,
+    };
+}
 export function resolveTerrainPalette(descriptor = {}) {
-    const preset = TERRAIN_MATERIAL_PALETTES[descriptor.material ?? DEFAULT_TERRAIN_MATERIAL] ?? TERRAIN_MATERIAL_PALETTES[DEFAULT_TERRAIN_MATERIAL];
+    const material = descriptor.material ?? DEFAULT_TERRAIN_MATERIAL;
+    const preset = TERRAIN_MATERIAL_PALETTES[material];
+    if (preset === undefined) {
+        throw new Error(`Unknown terrain material "${material}". Valid materials: ${Object.keys(TERRAIN_MATERIAL_PALETTES).join(", ")}. Use colors: { low, high, waterline } for a custom look.`);
+    }
     const colors = descriptor.colors ?? {};
     return {
         low: colors.low ?? preset.low,
@@ -170,6 +286,137 @@ export function resolveTerrainPalette(descriptor = {}) {
         waterline: colors.waterline ?? preset.waterline,
     };
 }
+function hexToRgb(hex) {
+    const value = Number.parseInt(hex.slice(1), 16);
+    return [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff];
+}
+function rgbToHex(r, g, b) {
+    const value = ((Math.round(r) & 0xff) << 16) | ((Math.round(g) & 0xff) << 8) | (Math.round(b) & 0xff);
+    return `#${value.toString(16).padStart(6, "0")}`;
+}
+function mixHex(from, to, t) {
+    if (t <= 0)
+        return from;
+    if (t >= 1)
+        return to;
+    const [fr, fg, fb] = hexToRgb(from);
+    const [tr, tg, tb] = hexToRgb(to);
+    return rgbToHex(lerp(fr, tr, t), lerp(fg, tg, t), lerp(fb, tb, t));
+}
+function mixPalette(from, to, t) {
+    if (t <= 0)
+        return from;
+    if (t >= 1)
+        return to;
+    return {
+        low: mixHex(from.low, to.low, t),
+        high: mixHex(from.high, to.high, t),
+        waterline: mixHex(from.waterline, to.waterline, t),
+    };
+}
+/**
+ * Per-z palette sampler over a descriptor's `biomeBands` — ordered zones that cross-fade their
+ * ground palette across a `fade`-wide window centered on the midpoint z between adjacent centers.
+ * Below the first / above the last band clamps to that band's palette. Returns `fallback` when no
+ * bands are declared. Pure math, unit-testable independent of rendering.
+ */
+export function createBiomeBandSampler(bands, fallback) {
+    if (bands.length === 0)
+        return () => fallback;
+    const resolved = bands
+        .map((band) => ({ z: band.z, fade: band.fade ?? 64, palette: resolveTerrainPalette(band) }))
+        .sort((a, b) => a.z - b.z);
+    const first = resolved[0];
+    const last = resolved[resolved.length - 1];
+    return (z) => {
+        if (z <= first.z)
+            return first.palette;
+        if (z >= last.z)
+            return last.palette;
+        for (let i = 0; i < resolved.length - 1; i += 1) {
+            const lower = resolved[i];
+            const upper = resolved[i + 1];
+            if (z < lower.z || z > upper.z)
+                continue;
+            const boundary = (lower.z + upper.z) / 2;
+            const half = Math.min(lower.fade, upper.fade) / 2;
+            if (z <= boundary - half)
+                return lower.palette;
+            if (z >= boundary + half)
+                return upper.palette;
+            return mixPalette(lower.palette, upper.palette, smoothstep(boundary - half, boundary + half, z));
+        }
+        return fallback;
+    };
+}
+/**
+ * Per-position palette sampler over the descriptor's base `material`/`colors` plus its z-ordered
+ * `biomeBands` (painted first) and radial `materialRegions` (painted over) — the multi-biome coloring
+ * seam. Regions paint fully inside `radius` and blend back across `falloff`; later regions win overlaps.
+ */
+export function createTerrainPaletteSampler(descriptor) {
+    const base = resolveTerrainPalette(descriptor);
+    const bandSampler = descriptor.biomeBands === undefined || descriptor.biomeBands.length === 0
+        ? null
+        : createBiomeBandSampler(descriptor.biomeBands, base);
+    const regions = (descriptor.materialRegions ?? []).map((region) => ({
+        ...resolveRegionShape(region),
+        palette: resolveTerrainPalette(region),
+    }));
+    if (regions.length === 0 && bandSampler === null)
+        return () => base;
+    return (x, z) => {
+        let palette = bandSampler === null ? base : bandSampler(z);
+        for (const region of regions) {
+            const distance = region.coreDistance(x, z);
+            if (distance <= 0) {
+                palette = region.palette;
+            }
+            else if (distance <= region.falloff) {
+                const t = smoothstep(0, region.falloff, distance);
+                palette = mixPalette(region.palette, palette, t);
+            }
+        }
+        return palette;
+    };
+}
+/**
+ * Resolves a `TerrainMaterialRegion` of any shape to a `coreDistance(x, z)` — 0 inside the painted
+ * core, growing positive outward — plus its blend-ring `falloff`, so the palette sampler blends every
+ * shape through one shape-agnostic loop.
+ */
+function resolveRegionShape(region) {
+    if (region.shape === "polyline") {
+        const half = region.width * 0.5;
+        return {
+            falloff: region.falloff ?? half,
+            coreDistance: (x, z) => {
+                const sample = nearestOnPath(region.points, x, z);
+                return sample === null ? Number.POSITIVE_INFINITY : Math.max(0, sample.distance - half);
+            },
+        };
+    }
+    if (region.shape === "rect") {
+        const [hx, hz] = region.halfExtents;
+        const angle = region.rotationY ?? 0;
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        return {
+            falloff: region.falloff ?? Math.min(hx, hz) * 0.5,
+            coreDistance: (x, z) => {
+                const dx = x - region.center[0];
+                const dz = z - region.center[1];
+                const lx = dx * cos + dz * sin;
+                const lz = -dx * sin + dz * cos;
+                return Math.hypot(Math.max(0, Math.abs(lx) - hx), Math.max(0, Math.abs(lz) - hz));
+            },
+        };
+    }
+    return {
+        falloff: region.falloff ?? region.radius * 0.5,
+        coreDistance: (x, z) => Math.max(0, Math.hypot(x - region.center[0], z - region.center[1]) - region.radius),
+    };
+}
 function withFlattenMasks(sampleHeight, masks) {
     const resolved = masks.map((mask) => ({
         center: mask.center,
@@ -193,24 +440,69 @@ function withFlattenMasks(sampleHeight, masks) {
         return height;
     };
 }
+export function heightMapField(config) {
+    const { columns, rows, samples } = config;
+    if (columns <= 0 || rows <= 0)
+        throw new Error("heightMapField: columns/rows must be positive");
+    if (samples.length < columns * rows) {
+        throw new Error(`heightMapField: samples length ${samples.length} < columns*rows ${columns * rows}`);
+    }
+    const bounds = config.bounds ?? { w: columns, d: rows };
+    const heightScale = config.heightScale ?? 1;
+    const baseHeight = config.baseHeight ?? 0;
+    const halfW = bounds.w / 2;
+    const halfD = bounds.d / 2;
+    const sampleAt = (col, row) => {
+        const c = Math.max(0, Math.min(columns - 1, col));
+        const r = Math.max(0, Math.min(rows - 1, row));
+        return samples[r * columns + c];
+    };
+    return fieldFromHeight((x, z) => {
+        const u = columns <= 1 ? 0 : ((x + halfW) / bounds.w) * (columns - 1);
+        const v = rows <= 1 ? 0 : ((z + halfD) / bounds.d) * (rows - 1);
+        const c0 = Math.floor(u);
+        const r0 = Math.floor(v);
+        const fu = u - c0;
+        const fv = v - r0;
+        const h00 = sampleAt(c0, r0);
+        const h10 = sampleAt(c0 + 1, r0);
+        const h01 = sampleAt(c0, r0 + 1);
+        const h11 = sampleAt(c0 + 1, r0 + 1);
+        const top = lerp(h00, h10, fu);
+        const bottom = lerp(h01, h11, fu);
+        return baseHeight + heightScale * lerp(top, bottom, fv);
+    }, {
+        bounds,
+        ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
+    });
+}
+/** Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks. */
 export function resolveTerrainField(descriptor) {
     if (descriptor === undefined)
         return flatField();
-    const noise = noiseField({
-        seed: descriptor.seed,
-        amplitude: descriptor.height,
-        frequency: descriptor.frequency,
-        octaves: descriptor.octaves,
-        ridged: descriptor.ridged,
-        baseHeight: descriptor.baseHeight,
-        waterLevel: descriptor.waterLevel,
-        bounds: descriptor.bounds,
-    });
+    if (descriptor.heightField === undefined && descriptor.heightMap !== undefined) {
+        throw new Error(`terrain heightMap "${descriptor.heightMap}" is not auto-loaded. Decode elevation samples into heightMapField({ columns, rows, samples }) and pass heightField: field.sampleHeight (or omit heightMap and set heightField directly).`);
+    }
+    const base = descriptor.heightField !== undefined
+        ? fieldFromHeight(descriptor.heightField, {
+            bounds: descriptor.bounds,
+            ...(descriptor.waterLevel === undefined ? {} : { waterLevel: descriptor.waterLevel }),
+        })
+        : noiseField({
+            seed: descriptor.seed,
+            amplitude: descriptor.height,
+            frequency: descriptor.frequency,
+            octaves: descriptor.octaves,
+            ridged: descriptor.ridged,
+            baseHeight: descriptor.baseHeight,
+            waterLevel: descriptor.waterLevel,
+            bounds: descriptor.bounds,
+        });
     if (descriptor.flatten === undefined || descriptor.flatten.length === 0)
-        return noise;
-    return fieldFromHeight(withFlattenMasks(noise.sampleHeight, descriptor.flatten), {
-        bounds: noise.bounds,
-        waterLevel: noise.waterLevel,
+        return base;
+    return fieldFromHeight(withFlattenMasks(base.sampleHeight, descriptor.flatten), {
+        bounds: base.bounds,
+        waterLevel: base.waterLevel,
     });
 }
 /** Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`. */
@@ -226,6 +518,7 @@ export function snapEntityToGround(entities, id, field, offset = 0) {
     return entities.setPose(id, { position: snapToGround(field, entity.position, offset) });
 }
 export const DEFAULT_MAX_WALK_SLOPE = 0.6;
+/** Zeroes out a movement step's x or z component where it would climb steeper than `maxSlope`. */
 export function resolveGroundStep(field, x, z, stepX, stepZ, maxSlope = DEFAULT_MAX_WALK_SLOPE) {
     const baseHeight = field.sampleHeight(x, z);
     const tooSteep = (dx, dz) => {

package/dist/world/water.d.ts

@@ -9,6 +9,8 @@ export interface GerstnerWave {
 }
 export interface WaterSurfaceConfig {
     level?: number;
+    /** Scheduled base level as a function of time — tides, floods (#284.1). Wins over `level`/`setLevel` whenever set. */
+    levelAt?: (time: number) => number;
     waveHeight?: number;
     waveScale?: number;
     waveSpeed?: number;
@@ -16,11 +18,16 @@ export interface WaterSurfaceConfig {
     choppiness?: number;
 }
 export interface WaterSurface {
+    /** The current base level — the initial config value until `setLevel` replaces it. With a `levelAt` schedule, use `levelAtTime` instead. */
     readonly level: number;
     readonly waves: readonly GerstnerWave[];
     height(x: number, z: number, time: number): number;
     normal(x: number, z: number, time: number): WaterNormal;
     displace(x: number, z: number, time: number): readonly [number, number, number];
+    /** Raise or drain the water at runtime (#284.1) — every `height`/`displace` consumer (buoyancy included) sees it immediately. Ignored while a `levelAt` schedule is set. */
+    setLevel(level: number): void;
+    /** The effective base level at `time`: the `levelAt` schedule when set, else the current `level`. */
+    levelAtTime(time: number): number;
 }
 export declare function synthesizeWaves(config?: WaterSurfaceConfig): GerstnerWave[];
 export declare function waterSurface(config?: WaterSurfaceConfig): WaterSurface;

package/dist/world/water.js

@@ -41,11 +41,13 @@ export function synthesizeWaves(config = {}) {
 }
 export function waterSurface(config = {}) {
     const resolved = resolveConfig(config);
-    const level = resolved.level;
+    let currentLevel = resolved.level;
+    const levelAt = config.levelAt;
+    const levelAtTime = (time) => (levelAt !== undefined ? levelAt(time) : currentLevel);
     const choppiness = resolved.choppiness;
     const waves = synthesizeWaves(config);
     const height = (x, z, time) => {
-        let y = level;
+        let y = levelAtTime(time);
         for (const wave of waves) {
             const k = TWO_PI / wave.wavelength;
             const omega = wave.speed * k;
@@ -57,7 +59,7 @@ export function waterSurface(config = {}) {
     const displace = (x, z, time) => {
         let dx = x;
         let dz = z;
-        let dy = level;
+        let dy = levelAtTime(time);
         for (const wave of waves) {
             const k = TWO_PI / wave.wavelength;
             const omega = wave.speed * k;
@@ -112,11 +114,24 @@ export function waterSurface(config = {}) {
         }
         return [nx, ny, nz];
     };
-    return { level, waves, height, normal, displace };
+    return {
+        get level() {
+            return currentLevel;
+        },
+        waves,
+        height,
+        normal,
+        displace,
+        setLevel(nextLevel) {
+            currentLevel = nextLevel;
+        },
+        levelAtTime,
+    };
 }
 export function waterSurfaceFromDescriptor(descriptor, waves) {
     return waterSurface({
         level: descriptor.level,
+        ...(descriptor.levelAt === undefined ? {} : { levelAt: descriptor.levelAt }),
         waveHeight: descriptor.waveHeight,
         waveScale: descriptor.waveScale,
         waveSpeed: descriptor.waveSpeed,

package/dist/world/weather.d.ts

@@ -1,28 +1,20 @@
 import type { WindVector } from "./wind.js";
 export type WeatherKind = string;
 export interface WeatherState {
-    /** Game-defined kind: "clear", "rain", "storm", "snow", "fog", "sandstorm". */
     kind: WeatherKind;
-    /** 0..1 severity — scales every modifier. */
     intensity: number;
     wind?: WindVector;
 }
-/** Per-kind gameplay effect values at full intensity. Intensity interpolates from neutral. */
 export interface WeatherModifier {
-    /** Movement traction multiplier at full intensity — <1 = mud/ice slows, 1 = normal. */
     grip?: number;
-    /** View distance multiplier at full intensity — 0..1, 1 = clear. */
     visibility?: number;
-    /** Structure HP lost per game-second at full intensity (hail, storm). */
     structureDamage?: number;
-    /** Temperature delta at full intensity (a blizzard chills). */
     chill?: number;
-    /** Lightning ignition chance per game-second at full intensity. */
     ignition?: number;
-    /** Fire spread-rate multiplier at full intensity — rain suppresses (<1). Default neutral 1. */
     spread?: number;
 }
-export type WeatherModifierTable = Record<WeatherKind, WeatherModifier>;
+export type WeatherModifierTable<K extends string = string> = Record<K, WeatherModifier>;
+export type WeatherKindOf<TTable extends WeatherModifierTable> = Extract<keyof TTable, string>;
 export interface ResolvedWeather {
     grip: number;
     visibility: number;
@@ -31,14 +23,7 @@ export interface ResolvedWeather {
     ignition: number;
     spread: number;
 }
-/**
- * Resolve a weather state against a game-owned modifier table into concrete gameplay
- * numbers. Multiplier-style effects (grip, visibility, spread) interpolate from the
- * neutral 1 by intensity; rate-style effects (structureDamage, ignition, chill) scale
- * linearly. Games read `grip`/`visibility` in movement and AI, `structureDamage` on a
- * building tick, and `spread`/`ignition` feed the fire grid.
- */
-export declare function resolveWeather(state: WeatherState, table: WeatherModifierTable): ResolvedWeather;
+export declare function resolveWeather<TTable extends WeatherModifierTable>(state: WeatherState, table: TTable): ResolvedWeather;
 export type FireCellState = "unburnt" | "burning" | "burnt";
 export interface FireCell {
     fuel: number;

package/dist/world/weather.js

@@ -1,25 +1,12 @@
-const NEUTRAL = {
-    grip: 1,
-    visibility: 1,
-    structureDamage: 0,
-    chill: 0,
-    ignition: 0,
-    spread: 1,
-};
 function lerp(from, to, t) {
     return from + (to - from) * t;
 }
-/**
- * Resolve a weather state against a game-owned modifier table into concrete gameplay
- * numbers. Multiplier-style effects (grip, visibility, spread) interpolate from the
- * neutral 1 by intensity; rate-style effects (structureDamage, ignition, chill) scale
- * linearly. Games read `grip`/`visibility` in movement and AI, `structureDamage` on a
- * building tick, and `spread`/`ignition` feed the fire grid.
- */
 export function resolveWeather(state, table) {
     const entry = table[state.kind];
-    if (entry === undefined)
-        return { ...NEUTRAL };
+    if (entry === undefined) {
+        const known = Object.keys(table).sort().join(", ");
+        throw new Error(`Unknown weather kind "${state.kind}". Known kinds: ${known.length > 0 ? known : "(none)"}.`);
+    }
     const t = Math.max(0, Math.min(1, state.intensity));
     return {
         grip: lerp(1, entry.grip ?? 1, t),

package/dist/world/windZones.d.ts

@@ -0,0 +1,47 @@
+import { type SchedulePhase } from "../time/stateSchedule.js";
+import type { WindField, WindVector } from "./wind.js";
+export interface WindZoneState {
+    direction: WindVector;
+    speed: number;
+    /** Announcement label for HUD countdowns ("gale", "calm", "tailwind"). */
+    label?: string;
+}
+export interface WindZoneConfig {
+    id: string;
+    center: readonly [number, number];
+    radius: number;
+    /** The zone's scheduled wind states; a single phase makes a static zone. */
+    phases: readonly SchedulePhase<WindZoneState>[];
+    /** Staggers this zone's schedule against identical ones. */
+    offsetSeconds?: number;
+}
+export interface WindZonesConfig {
+    zones: readonly WindZoneConfig[];
+    /** Wind outside every zone; omit for dead air. */
+    ambient?: WindField;
+}
+export interface WindShiftForecast {
+    zoneId: string;
+    /** Absolute time the zone's next state begins. */
+    at: number;
+    /** Seconds from the queried time until the shift. */
+    inSeconds: number;
+    next: WindZoneState;
+}
+/**
+ * Named, discrete wind zones over an ambient field — each zone runs a deterministic
+ * `StateSchedule` of wind states, so games get scheduled shifts with advance announcement
+ * (`forecastShift` drives the "gale in 12s" countdown) instead of one continuous field.
+ */
+export interface WindZones {
+    zoneIds(): readonly string[];
+    /** Innermost zone containing the point (later declarations win ties); `null` in open air. */
+    zoneAt(x: number, z: number): string | null;
+    /** The wind vector at a point and time: the containing zone's scheduled state, else ambient. */
+    windAt(x: number, z: number, t: number): WindVector;
+    /** A zone's live state; `null` for an unknown zone. */
+    stateAt(zoneId: string, t: number): WindZoneState | null;
+    /** The zone's next scheduled shift after `t`; `null` for unknown or single-phase zones. */
+    forecastShift(zoneId: string, t: number): WindShiftForecast | null;
+}
+export declare function createWindZones(config: WindZonesConfig): WindZones;

package/dist/world/windZones.js

@@ -0,0 +1,59 @@
+import { createStateSchedule } from "../time/stateSchedule.js";
+function windVectorOf(state) {
+    const length = Math.hypot(state.direction[0], state.direction[1]);
+    if (length === 0 || state.speed === 0)
+        return [0, 0];
+    return [(state.direction[0] / length) * state.speed, (state.direction[1] / length) * state.speed];
+}
+export function createWindZones(config) {
+    const zones = new Map();
+    const order = [];
+    for (const zone of config.zones) {
+        if (zones.has(zone.id))
+            throw new Error(`duplicate wind zone: ${zone.id}`);
+        zones.set(zone.id, {
+            config: zone,
+            schedule: createStateSchedule({
+                phases: zone.phases,
+                ...(zone.offsetSeconds === undefined ? {} : { offsetSeconds: zone.offsetSeconds }),
+            }),
+        });
+        order.push(zone.id);
+    }
+    function zoneAt(x, z) {
+        let best = null;
+        let bestRadius = Number.POSITIVE_INFINITY;
+        for (const id of order) {
+            const zone = zones.get(id);
+            const distance = Math.hypot(x - zone.config.center[0], z - zone.config.center[1]);
+            if (distance <= zone.config.radius && zone.config.radius <= bestRadius) {
+                best = id;
+                bestRadius = zone.config.radius;
+            }
+        }
+        return best;
+    }
+    return {
+        zoneIds: () => order.slice(),
+        zoneAt,
+        windAt(x, z, t) {
+            const id = zoneAt(x, z);
+            if (id !== null)
+                return windVectorOf(zones.get(id).schedule.stateAt(t));
+            return config.ambient === undefined ? [0, 0] : config.ambient.atPoint(x, z, t);
+        },
+        stateAt(zoneId, t) {
+            const zone = zones.get(zoneId);
+            return zone === undefined ? null : zone.schedule.stateAt(t);
+        },
+        forecastShift(zoneId, t) {
+            const zone = zones.get(zoneId);
+            if (zone === undefined || zone.config.phases.length < 2)
+                return null;
+            const at = zone.schedule.nextTransitionAt(t);
+            if (!Number.isFinite(at))
+                return null;
+            return { zoneId, at, inSeconds: at - t, next: zone.schedule.stateAt(at) };
+        },
+    };
+}