@jgengine/core 0.7.0 → 0.8.0

package/dist/world/terrain.d.ts

@@ -1,4 +1,4 @@
-import type { TerrainEnvironmentDescriptor, WorldBounds } from "./features.js";
+import type { TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, WorldBounds, WorldFeature } from "./features.js";
 export type TerrainNormal = readonly [number, number, number];
 export interface TerrainField {
     sampleHeight(x: number, z: number): number;
@@ -46,7 +46,29 @@ export interface ArenaFieldConfig {
 }
 export declare const ARENA_WATER_LEVEL = -0.9;
 export declare function arenaField(config?: ArenaFieldConfig): TerrainField;
+export declare function groundFieldFor(world?: WorldFeature): TerrainField;
+export interface TerrainPalette {
+    low: string;
+    high: string;
+    waterline: string;
+}
+export declare const DEFAULT_TERRAIN_MATERIAL = "grass";
+export declare const TERRAIN_MATERIAL_PALETTES: Record<string, TerrainPalette>;
+export declare function resolveTerrainPalette(descriptor?: Pick<TerrainEnvironmentConfig, "material" | "colors">): TerrainPalette;
 export declare function resolveTerrainField(descriptor?: TerrainEnvironmentDescriptor): TerrainField;
+/** Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`. */
+export declare function snapToGround(field: TerrainField, position: readonly [number, number, number], offset?: number): [number, number, number];
+export interface GroundSnapTarget {
+    position: readonly [number, number, number];
+}
+export interface GroundSnapEntityStore {
+    get(id: string): GroundSnapTarget | null;
+    setPose(id: string, pose: {
+        position?: readonly [number, number, number];
+    }): boolean;
+}
+/** Ground-snaps an already-spawned entity in place; returns false when `id` is unknown. */
+export declare function snapEntityToGround(entities: GroundSnapEntityStore, id: string, field: TerrainField, offset?: number): boolean;
 export declare const DEFAULT_MAX_WALK_SLOPE = 0.6;
 export declare function resolveGroundStep(field: TerrainField, x: number, z: number, stepX: number, stepZ: number, maxSlope?: number): {
     stepX: number;

package/dist/world/terrain.js

@@ -148,10 +148,55 @@ export function arenaField(config = {}) {
     };
     return fieldFromHeight(sampleHeight, { bounds: config.bounds, waterLevel: ARENA_WATER_LEVEL });
 }
+export function groundFieldFor(world) {
+    if (world !== undefined && world.kind === "environment")
+        return resolveTerrainField(world.terrain);
+    return flatField();
+}
+export const DEFAULT_TERRAIN_MATERIAL = "grass";
+export const TERRAIN_MATERIAL_PALETTES = {
+    grass: { low: "#30402c", high: "#7f8b50", waterline: "#1d4c6e" },
+    sand: { low: "#9c8354", high: "#e0c98a", waterline: "#2f6f8f" },
+    snow: { low: "#c7d3dc", high: "#ffffff", waterline: "#3a6ea5" },
+    rock: { low: "#3a3a3d", high: "#8a8a8d", waterline: "#1d4c6e" },
+    ash: { low: "#2b2622", high: "#5c534a", waterline: "#3a3630" },
+};
+export function resolveTerrainPalette(descriptor = {}) {
+    const preset = TERRAIN_MATERIAL_PALETTES[descriptor.material ?? DEFAULT_TERRAIN_MATERIAL] ?? TERRAIN_MATERIAL_PALETTES[DEFAULT_TERRAIN_MATERIAL];
+    const colors = descriptor.colors ?? {};
+    return {
+        low: colors.low ?? preset.low,
+        high: colors.high ?? preset.high,
+        waterline: colors.waterline ?? preset.waterline,
+    };
+}
+function withFlattenMasks(sampleHeight, masks) {
+    const resolved = masks.map((mask) => ({
+        center: mask.center,
+        radius: mask.radius,
+        target: mask.height ?? sampleHeight(mask.center[0], mask.center[1]),
+        falloff: mask.falloff ?? mask.radius * 0.5,
+    }));
+    return (x, z) => {
+        const base = sampleHeight(x, z);
+        let height = base;
+        for (const mask of resolved) {
+            const distance = Math.hypot(x - mask.center[0], z - mask.center[1]);
+            if (distance <= mask.radius) {
+                height = mask.target;
+            }
+            else if (distance <= mask.radius + mask.falloff) {
+                const t = smoothstep(mask.radius, mask.radius + mask.falloff, distance);
+                height = lerp(mask.target, base, t);
+            }
+        }
+        return height;
+    };
+}
 export function resolveTerrainField(descriptor) {
     if (descriptor === undefined)
         return flatField();
-    return noiseField({
+    const noise = noiseField({
         seed: descriptor.seed,
         amplitude: descriptor.height,
         frequency: descriptor.frequency,
@@ -161,6 +206,24 @@ export function resolveTerrainField(descriptor) {
         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,
+    });
+}
+/** Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`. */
+export function snapToGround(field, position, offset = 0) {
+    const [x, , z] = position;
+    return [x, field.sampleHeight(x, z) + offset, z];
+}
+/** Ground-snaps an already-spawned entity in place; returns false when `id` is unknown. */
+export function snapEntityToGround(entities, id, field, offset = 0) {
+    const entity = entities.get(id);
+    if (entity === null)
+        return false;
+    return entities.setPose(id, { position: snapToGround(field, entity.position, offset) });
 }
 export const DEFAULT_MAX_WALK_SLOPE = 0.6;
 export function resolveGroundStep(field, x, z, stepX, stepZ, maxSlope = DEFAULT_MAX_WALK_SLOPE) {

package/dist/world/voxelField.d.ts

@@ -0,0 +1,54 @@
+export type VoxelCoord = readonly [number, number, number];
+export type VoxelFace = "px" | "nx" | "py" | "ny" | "pz" | "nz";
+export interface VoxelFieldConfig {
+    chunkSize?: number;
+}
+export interface VoxelCell<T extends string = string> {
+    x: number;
+    y: number;
+    z: number;
+    type: T;
+}
+export interface VoxelHit<T extends string = string> {
+    x: number;
+    y: number;
+    z: number;
+    type: T;
+    face: VoxelFace;
+    adjacent: VoxelCoord;
+    distance: number;
+}
+export interface VoxelBounds {
+    min: VoxelCoord;
+    max: VoxelCoord;
+}
+export interface VoxelFieldSummary<T extends string = string> {
+    blocks: number;
+    types: Record<T, number>;
+    bounds: VoxelBounds | null;
+}
+export interface VoxelField<T extends string = string> {
+    set(x: number, y: number, z: number, type: T): boolean;
+    remove(x: number, y: number, z: number): boolean;
+    get(x: number, y: number, z: number): T | null;
+    has(x: number, y: number, z: number): boolean;
+    fill(min: VoxelCoord, max: VoxelCoord, type: T): number;
+    clear(): void;
+    count(): number;
+    cells(): IterableIterator<VoxelCell<T>>;
+    bounds(): VoxelBounds | null;
+    neighbors(x: number, y: number, z: number): VoxelCell<T>[];
+    exposedFaces(x: number, y: number, z: number): readonly VoxelFace[];
+    raycast(origin: VoxelCoord, direction: VoxelCoord, maxDistance: number): VoxelHit<T> | null;
+    chunkOf(x: number, y: number, z: number): {
+        cx: number;
+        cy: number;
+        cz: number;
+    };
+    chunkVersion(cx: number, cy: number, cz: number): number;
+    subscribe(listener: () => void): () => void;
+    summary(): VoxelFieldSummary<T>;
+}
+export declare const VOXEL_FACES: readonly VoxelFace[];
+export declare const VOXEL_FACE_NORMALS: Record<VoxelFace, VoxelCoord>;
+export declare function createVoxelField<T extends string = string>(config?: VoxelFieldConfig): VoxelField<T>;

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