@jgengine/core 0.7.0 → 0.9.0

package/dist/world/voxelField.js

@@ -0,0 +1,241 @@
+export const VOXEL_FACES = ["px", "nx", "py", "ny", "pz", "nz"];
+export const VOXEL_FACE_NORMALS = {
+    px: [1, 0, 0],
+    nx: [-1, 0, 0],
+    py: [0, 1, 0],
+    ny: [0, -1, 0],
+    pz: [0, 0, 1],
+    nz: [0, 0, -1],
+};
+function cellKey(x, y, z) {
+    return `${x},${y},${z}`;
+}
+function entryFace(dx, dy, dz) {
+    const ax = Math.abs(dx);
+    const ay = Math.abs(dy);
+    const az = Math.abs(dz);
+    if (ax >= ay && ax >= az && ax > 0)
+        return dx > 0 ? "nx" : "px";
+    if (az >= ay && az > 0)
+        return dz > 0 ? "nz" : "pz";
+    return dy > 0 ? "ny" : "py";
+}
+export function createVoxelField(config) {
+    const chunkSize = config?.chunkSize ?? 16;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
+        throw new Error("createVoxelField: chunkSize must be a positive integer");
+    }
+    const cells = new Map();
+    const chunkVersions = new Map();
+    const listeners = new Set();
+    function chunkOf(x, y, z) {
+        return {
+            cx: Math.floor(x / chunkSize),
+            cy: Math.floor(y / chunkSize),
+            cz: Math.floor(z / chunkSize),
+        };
+    }
+    function bumpChunk(x, y, z) {
+        const { cx, cy, cz } = chunkOf(x, y, z);
+        const key = cellKey(cx, cy, cz);
+        chunkVersions.set(key, (chunkVersions.get(key) ?? 0) + 1);
+    }
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function setCell(x, y, z, type) {
+        const key = cellKey(x, y, z);
+        const existing = cells.get(key);
+        if (existing !== undefined && existing.type === type)
+            return false;
+        cells.set(key, { x, y, z, type });
+        bumpChunk(x, y, z);
+        return true;
+    }
+    function getCell(x, y, z) {
+        return cells.get(cellKey(x, y, z));
+    }
+    function computeBounds() {
+        if (cells.size === 0)
+            return null;
+        let minX = Number.POSITIVE_INFINITY;
+        let minY = Number.POSITIVE_INFINITY;
+        let minZ = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxY = Number.NEGATIVE_INFINITY;
+        let maxZ = Number.NEGATIVE_INFINITY;
+        for (const cell of cells.values()) {
+            if (cell.x < minX)
+                minX = cell.x;
+            if (cell.y < minY)
+                minY = cell.y;
+            if (cell.z < minZ)
+                minZ = cell.z;
+            if (cell.x > maxX)
+                maxX = cell.x;
+            if (cell.y > maxY)
+                maxY = cell.y;
+            if (cell.z > maxZ)
+                maxZ = cell.z;
+        }
+        return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+    }
+    return {
+        set(x, y, z, type) {
+            const changed = setCell(x, y, z, type);
+            if (changed)
+                notify();
+            return changed;
+        },
+        remove(x, y, z) {
+            const removed = cells.delete(cellKey(x, y, z));
+            if (removed) {
+                bumpChunk(x, y, z);
+                notify();
+            }
+            return removed;
+        },
+        get(x, y, z) {
+            return getCell(x, y, z)?.type ?? null;
+        },
+        has(x, y, z) {
+            return cells.has(cellKey(x, y, z));
+        },
+        fill(min, max, type) {
+            let changed = 0;
+            for (let x = min[0]; x <= max[0]; x += 1) {
+                for (let y = min[1]; y <= max[1]; y += 1) {
+                    for (let z = min[2]; z <= max[2]; z += 1) {
+                        if (setCell(x, y, z, type))
+                            changed += 1;
+                    }
+                }
+            }
+            if (changed > 0)
+                notify();
+            return changed;
+        },
+        clear() {
+            if (cells.size === 0)
+                return;
+            for (const cell of cells.values())
+                bumpChunk(cell.x, cell.y, cell.z);
+            cells.clear();
+            notify();
+        },
+        count() {
+            return cells.size;
+        },
+        cells() {
+            return cells.values();
+        },
+        bounds() {
+            return computeBounds();
+        },
+        neighbors(x, y, z) {
+            const out = [];
+            for (const face of VOXEL_FACES) {
+                const [nx, ny, nz] = VOXEL_FACE_NORMALS[face];
+                const cell = getCell(x + nx, y + ny, z + nz);
+                if (cell !== undefined)
+                    out.push(cell);
+            }
+            return out;
+        },
+        exposedFaces(x, y, z) {
+            if (!cells.has(cellKey(x, y, z)))
+                return [];
+            return VOXEL_FACES.filter((face) => {
+                const [nx, ny, nz] = VOXEL_FACE_NORMALS[face];
+                return !cells.has(cellKey(x + nx, y + ny, z + nz));
+            });
+        },
+        raycast(origin, direction, maxDistance) {
+            const [ox, oy, oz] = origin;
+            const [dx, dy, dz] = direction;
+            let ix = Math.floor(ox);
+            let iy = Math.floor(oy);
+            let iz = Math.floor(oz);
+            const startCell = getCell(ix, iy, iz);
+            if (startCell !== undefined) {
+                return {
+                    x: ix,
+                    y: iy,
+                    z: iz,
+                    type: startCell.type,
+                    face: entryFace(dx, dy, dz),
+                    adjacent: [ix, iy, iz],
+                    distance: 0,
+                };
+            }
+            const stepX = dx > 0 ? 1 : dx < 0 ? -1 : 0;
+            const stepY = dy > 0 ? 1 : dy < 0 ? -1 : 0;
+            const stepZ = dz > 0 ? 1 : dz < 0 ? -1 : 0;
+            const tDeltaX = dx !== 0 ? Math.abs(1 / dx) : Number.POSITIVE_INFINITY;
+            const tDeltaY = dy !== 0 ? Math.abs(1 / dy) : Number.POSITIVE_INFINITY;
+            const tDeltaZ = dz !== 0 ? Math.abs(1 / dz) : Number.POSITIVE_INFINITY;
+            const boundary = (i, o, step) => (step > 0 ? i + 1 - o : o - i);
+            let tMaxX = dx !== 0 ? boundary(ix, ox, stepX) * tDeltaX : Number.POSITIVE_INFINITY;
+            let tMaxY = dy !== 0 ? boundary(iy, oy, stepY) * tDeltaY : Number.POSITIVE_INFINITY;
+            let tMaxZ = dz !== 0 ? boundary(iz, oz, stepZ) * tDeltaZ : Number.POSITIVE_INFINITY;
+            let face = "py";
+            let travelled = 0;
+            while (travelled <= maxDistance) {
+                let px = ix;
+                let py = iy;
+                let pz = iz;
+                if (tMaxX < tMaxY && tMaxX < tMaxZ) {
+                    ix += stepX;
+                    travelled = tMaxX;
+                    tMaxX += tDeltaX;
+                    face = stepX > 0 ? "nx" : "px";
+                }
+                else if (tMaxY < tMaxZ) {
+                    iy += stepY;
+                    travelled = tMaxY;
+                    tMaxY += tDeltaY;
+                    face = stepY > 0 ? "ny" : "py";
+                }
+                else {
+                    iz += stepZ;
+                    travelled = tMaxZ;
+                    tMaxZ += tDeltaZ;
+                    face = stepZ > 0 ? "nz" : "pz";
+                }
+                if (travelled > maxDistance)
+                    break;
+                const cell = getCell(ix, iy, iz);
+                if (cell !== undefined) {
+                    return {
+                        x: ix,
+                        y: iy,
+                        z: iz,
+                        type: cell.type,
+                        face,
+                        adjacent: [px, py, pz],
+                        distance: travelled,
+                    };
+                }
+            }
+            return null;
+        },
+        chunkOf,
+        chunkVersion(cx, cy, cz) {
+            return chunkVersions.get(cellKey(cx, cy, cz)) ?? 0;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        summary() {
+            const types = {};
+            for (const cell of cells.values()) {
+                types[cell.type] = (types[cell.type] ?? 0) + 1;
+            }
+            return { blocks: cells.size, types, bounds: computeBounds() };
+        },
+    };
+}

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) };
+        },
+    };
+}