@jgengine/core 0.6.0 → 0.8.0

package/dist/world/realm.js

@@ -0,0 +1,66 @@
+import { createEnvironmentField } from "./envField.js";
+export const DEFAULT_REALM_ENVIRONMENT = {
+    baseTemperature: 20,
+    nightDrop: 12,
+    altitudeLapse: 0,
+    dayLength: 24 * 3600,
+    rain: 0,
+    ambientFloor: 0.05,
+};
+function applySpawn(table, override) {
+    if (override === undefined)
+        return;
+    if (override.set !== undefined)
+        for (const [id, weight] of Object.entries(override.set))
+            table[id] = weight;
+    if (override.add !== undefined)
+        for (const [id, weight] of Object.entries(override.add))
+            table[id] = (table[id] ?? 0) + weight;
+    if (override.scale !== undefined)
+        for (const [id, factor] of Object.entries(override.scale))
+            table[id] = (table[id] ?? 0) * factor;
+    if (override.remove !== undefined)
+        for (const id of override.remove)
+            delete table[id];
+}
+/**
+ * Assemble a played realm instance at runtime from a deck of modifier cards — the
+ * Nightingale "realm card" model. A major card is the biome base; minor cards layer
+ * weather, day length, and spawn edits. The result recomposes both the environment
+ * (into a sampleable field via `environmentField()`) and the spawn table, and it depends
+ * on the weather hooks in this group (#92) to turn its `weather` into gameplay modifiers.
+ * Cards apply in array order; sort your deck (majors first) before composing.
+ */
+export function composeRealm(base, cards) {
+    const params = { ...DEFAULT_REALM_ENVIRONMENT, ...base.environment };
+    let weather = base.weather ?? { kind: "clear", intensity: 0 };
+    const spawnTable = { ...base.spawn };
+    const aesthetics = [];
+    for (const card of cards) {
+        if (card.environment !== undefined)
+            Object.assign(params, card.environment);
+        if (card.weather !== undefined)
+            weather = { ...weather, ...card.weather };
+        applySpawn(spawnTable, card.spawn);
+        if (card.aesthetic !== undefined)
+            aesthetics.push(card.aesthetic);
+    }
+    return {
+        params,
+        weather,
+        spawnTable,
+        aesthetics,
+        cards,
+        environmentField(extra) {
+            return createEnvironmentField({
+                ...extra,
+                baseTemperature: params.baseTemperature,
+                nightDrop: params.nightDrop,
+                altitudeLapse: params.altitudeLapse,
+                dayLength: params.dayLength,
+                rain: weather.kind === "clear" ? 0 : params.rain,
+                ambientFloor: params.ambientFloor,
+            });
+        },
+    };
+}

package/dist/world/support.d.ts

@@ -0,0 +1,27 @@
+import type { AddBodyOptions } from "../physics/physicsWorld.js";
+import type { ConnectorVec3 } from "./connectors.js";
+export interface SupportPiece {
+    id: string;
+    grounded?: boolean;
+    position?: ConnectorVec3;
+    halfExtents?: ConnectorVec3;
+    mass?: number;
+}
+export interface SupportLink {
+    a: string;
+    b: string;
+}
+export interface SupportConfig {
+    maxDistance?: number;
+}
+export interface SupportResult {
+    supported: readonly string[];
+    unsupported: readonly string[];
+    distance: Readonly<Record<string, number>>;
+}
+export declare function solveSupport(pieces: readonly SupportPiece[], links: readonly SupportLink[], config?: SupportConfig): SupportResult;
+export interface DebrisOptions {
+    scatter?: number;
+    seed?: number;
+}
+export declare function toDebrisBodies(pieces: readonly SupportPiece[], collapsedIds: readonly string[], options?: DebrisOptions): AddBodyOptions[];

package/dist/world/support.js

@@ -0,0 +1,75 @@
+export function solveSupport(pieces, links, config = {}) {
+    const maxDistance = config.maxDistance ?? Infinity;
+    const ids = new Set(pieces.map((piece) => piece.id));
+    const adjacency = new Map();
+    for (const id of ids)
+        adjacency.set(id, []);
+    for (const link of links) {
+        if (!ids.has(link.a) || !ids.has(link.b))
+            continue;
+        adjacency.get(link.a).push(link.b);
+        adjacency.get(link.b).push(link.a);
+    }
+    const distance = {};
+    const queue = [];
+    for (const piece of pieces) {
+        if (piece.grounded === true) {
+            distance[piece.id] = 0;
+            queue.push(piece.id);
+        }
+    }
+    let head = 0;
+    while (head < queue.length) {
+        const current = queue[head];
+        head += 1;
+        const currentDistance = distance[current];
+        if (currentDistance >= maxDistance)
+            continue;
+        for (const neighbor of adjacency.get(current) ?? []) {
+            const next = currentDistance + 1;
+            if (distance[neighbor] === undefined || next < distance[neighbor]) {
+                distance[neighbor] = next;
+                queue.push(neighbor);
+            }
+        }
+    }
+    const supported = [];
+    const unsupported = [];
+    for (const piece of pieces) {
+        const d = distance[piece.id];
+        if (d !== undefined && d <= maxDistance)
+            supported.push(piece.id);
+        else
+            unsupported.push(piece.id);
+    }
+    return { supported, unsupported, distance };
+}
+function scatterHash(seed, index) {
+    let h = (seed ^ Math.imul(index + 1, 0x9e3779b1)) >>> 0;
+    h = Math.imul(h ^ (h >>> 15), 0x85ebca6b);
+    h ^= h >>> 13;
+    return ((h >>> 0) / 4294967295) * 2 - 1;
+}
+export function toDebrisBodies(pieces, collapsedIds, options = {}) {
+    const scatter = options.scatter ?? 1.5;
+    const seed = options.seed ?? 1;
+    const collapse = new Set(collapsedIds);
+    const bodies = [];
+    let index = 0;
+    for (const piece of pieces) {
+        if (!collapse.has(piece.id))
+            continue;
+        const position = piece.position ?? [0, 0, 0];
+        const halfExtents = piece.halfExtents ?? [0.5, 0.5, 0.5];
+        const vx = scatterHash(seed, index) * scatter;
+        const vz = scatterHash(seed, index + 977) * scatter;
+        bodies.push({
+            position,
+            halfExtents,
+            velocity: [vx, 0, vz],
+            ...(piece.mass === undefined ? {} : { mass: piece.mass }),
+        });
+        index += 1;
+    }
+    return bodies;
+}

package/dist/world/terraform.d.ts

@@ -0,0 +1,54 @@
+import type { Aabb, Vec2 } from "./geometry.js";
+import { type TerrainField } from "./terrain.js";
+export type TerraformMode = "raise" | "lower" | "flatten" | "paint";
+export type TerraformFalloff = "smooth" | "linear" | "none";
+export interface TerraformEdit {
+    mode: TerraformMode;
+    center: Vec2;
+    radius: number;
+    strength?: number;
+    target?: number;
+    surface?: string;
+    falloff?: TerraformFalloff;
+}
+export interface EditableTerrainConfig {
+    bounds: Aabb;
+    base?: TerrainField;
+    cellSize?: number;
+}
+export interface TerraformSnapshot {
+    bounds: Aabb;
+    cellSize: number;
+    cols: number;
+    rows: number;
+    offsets: readonly number[];
+    surfaces: readonly (string | null)[];
+}
+export interface EditableTerrain extends TerrainField {
+    apply(edit: TerraformEdit): number;
+    heightOffsetAt(x: number, z: number): number;
+    surfaceAt(x: number, z: number): string | null;
+    reset(): void;
+    snapshot(): TerraformSnapshot;
+    restore(snapshot: TerraformSnapshot): void;
+}
+export declare function brushWeight(distance: number, radius: number, falloff: TerraformFalloff): number;
+export declare function createEditableTerrain(config: EditableTerrainConfig): EditableTerrain;
+export interface TerraformBrushConfig {
+    radius?: number;
+    strength?: number;
+    falloff?: TerraformFalloff;
+    surface?: string;
+}
+export interface TerraformBrush {
+    raise(center: Vec2): number;
+    lower(center: Vec2): number;
+    flatten(center: Vec2, target?: number): number;
+    paint(center: Vec2, surface?: string): number;
+    setRadius(radius: number): void;
+    setStrength(strength: number): void;
+    config(): Required<Omit<TerraformBrushConfig, "surface">> & {
+        surface: string | undefined;
+    };
+}
+export declare function createTerraformBrush(terrain: Pick<EditableTerrain, "apply">, config?: TerraformBrushConfig): TerraformBrush;

package/dist/world/terraform.js

@@ -0,0 +1,186 @@
+import { FLAT_FIELD, withNormal } from "./terrain.js";
+export function brushWeight(distance, radius, falloff) {
+    if (radius <= 0)
+        return distance <= 0 ? 1 : 0;
+    const t = distance / radius;
+    if (t >= 1)
+        return 0;
+    if (falloff === "none")
+        return 1;
+    if (falloff === "linear")
+        return 1 - t;
+    const s = 1 - t;
+    return s * s * (3 - 2 * s);
+}
+function clampIndex(value, max) {
+    return value < 0 ? 0 : value > max ? max : value;
+}
+export function createEditableTerrain(config) {
+    const base = config.base ?? FLAT_FIELD;
+    const bounds = config.bounds;
+    const cellSize = config.cellSize && config.cellSize > 0 ? config.cellSize : 1;
+    const spanX = Math.max(bounds.maxX - bounds.minX, cellSize);
+    const spanZ = Math.max(bounds.maxZ - bounds.minZ, cellSize);
+    const cols = Math.max(1, Math.round(spanX / cellSize));
+    const rows = Math.max(1, Math.round(spanZ / cellSize));
+    const vertsX = cols + 1;
+    const vertsZ = rows + 1;
+    const offsets = new Float32Array(vertsX * vertsZ);
+    const surfaces = new Array(cols * rows).fill(null);
+    function gridX(x) {
+        return ((x - bounds.minX) / spanX) * cols;
+    }
+    function gridZ(z) {
+        return ((z - bounds.minZ) / spanZ) * rows;
+    }
+    function heightOffsetAt(x, z) {
+        const fx = gridX(x);
+        const fz = gridZ(z);
+        const x0 = clampIndex(Math.floor(fx), cols);
+        const z0 = clampIndex(Math.floor(fz), rows);
+        const x1 = clampIndex(x0 + 1, cols);
+        const z1 = clampIndex(z0 + 1, rows);
+        const tx = fx - x0 < 0 ? 0 : fx - x0 > 1 ? 1 : fx - x0;
+        const tz = fz - z0 < 0 ? 0 : fz - z0 > 1 ? 1 : fz - z0;
+        const v00 = offsets[z0 * vertsX + x0];
+        const v10 = offsets[z0 * vertsX + x1];
+        const v01 = offsets[z1 * vertsX + x0];
+        const v11 = offsets[z1 * vertsX + x1];
+        const top = v00 + (v10 - v00) * tx;
+        const bottom = v01 + (v11 - v01) * tx;
+        return top + (bottom - top) * tz;
+    }
+    const sampleHeight = (x, z) => base.sampleHeight(x, z) + heightOffsetAt(x, z);
+    const sampleNormal = withNormal(sampleHeight);
+    function editHeight(edit) {
+        const falloff = edit.falloff ?? "smooth";
+        const strength = edit.strength ?? 1;
+        const target = edit.mode === "flatten" ? edit.target ?? sampleHeight(edit.center[0], edit.center[1]) : 0;
+        const rCells = Math.ceil(edit.radius / cellSize) + 1;
+        const cx = gridX(edit.center[0]);
+        const cz = gridZ(edit.center[1]);
+        let changed = 0;
+        for (let iz = -rCells; iz <= rCells; iz += 1) {
+            const gz = Math.round(cz) + iz;
+            if (gz < 0 || gz >= vertsZ)
+                continue;
+            for (let ix = -rCells; ix <= rCells; ix += 1) {
+                const gx = Math.round(cx) + ix;
+                if (gx < 0 || gx >= vertsX)
+                    continue;
+                const wx = bounds.minX + (gx / cols) * spanX;
+                const wz = bounds.minZ + (gz / rows) * spanZ;
+                const dist = Math.hypot(wx - edit.center[0], wz - edit.center[1]);
+                const weight = brushWeight(dist, edit.radius, falloff);
+                if (weight <= 0)
+                    continue;
+                const index = gz * vertsX + gx;
+                if (edit.mode === "raise")
+                    offsets[index] += strength * weight;
+                else if (edit.mode === "lower")
+                    offsets[index] -= strength * weight;
+                else {
+                    const current = base.sampleHeight(wx, wz) + offsets[index];
+                    offsets[index] += (target - current) * weight * strength;
+                }
+                changed += 1;
+            }
+        }
+        return changed;
+    }
+    function paintSurface(edit) {
+        const surface = edit.surface ?? null;
+        const rCells = Math.ceil(edit.radius / cellSize) + 1;
+        const cx = gridX(edit.center[0]);
+        const cz = gridZ(edit.center[1]);
+        let painted = 0;
+        for (let iz = -rCells; iz <= rCells; iz += 1) {
+            const gz = Math.floor(cz) + iz;
+            if (gz < 0 || gz >= rows)
+                continue;
+            for (let ix = -rCells; ix <= rCells; ix += 1) {
+                const gx = Math.floor(cx) + ix;
+                if (gx < 0 || gx >= cols)
+                    continue;
+                const wx = bounds.minX + ((gx + 0.5) / cols) * spanX;
+                const wz = bounds.minZ + ((gz + 0.5) / rows) * spanZ;
+                if (Math.hypot(wx - edit.center[0], wz - edit.center[1]) > edit.radius)
+                    continue;
+                surfaces[gz * cols + gx] = surface;
+                painted += 1;
+            }
+        }
+        return painted;
+    }
+    function surfaceAt(x, z) {
+        const gx = Math.floor(gridX(x));
+        const gz = Math.floor(gridZ(z));
+        if (gx < 0 || gx >= cols || gz < 0 || gz >= rows)
+            return null;
+        return surfaces[gz * cols + gx] ?? null;
+    }
+    const field = {
+        sampleHeight,
+        sampleNormal,
+        ...(base.bounds === undefined ? {} : { bounds: base.bounds }),
+        ...(base.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
+        apply(edit) {
+            return edit.mode === "paint" ? paintSurface(edit) : editHeight(edit);
+        },
+        heightOffsetAt,
+        surfaceAt,
+        reset() {
+            offsets.fill(0);
+            surfaces.fill(null);
+        },
+        snapshot() {
+            return {
+                bounds: { ...bounds },
+                cellSize,
+                cols,
+                rows,
+                offsets: Array.from(offsets),
+                surfaces: surfaces.slice(),
+            };
+        },
+        restore(snapshot) {
+            const count = Math.min(offsets.length, snapshot.offsets.length);
+            for (let index = 0; index < count; index += 1)
+                offsets[index] = snapshot.offsets[index];
+            const surfaceCount = Math.min(surfaces.length, snapshot.surfaces.length);
+            for (let index = 0; index < surfaceCount; index += 1)
+                surfaces[index] = snapshot.surfaces[index] ?? null;
+        },
+    };
+    return field;
+}
+export function createTerraformBrush(terrain, config = {}) {
+    let radius = config.radius ?? 3;
+    let strength = config.strength ?? 0.5;
+    const falloff = config.falloff ?? "smooth";
+    const surface = config.surface;
+    return {
+        raise(center) {
+            return terrain.apply({ mode: "raise", center, radius, strength, falloff });
+        },
+        lower(center) {
+            return terrain.apply({ mode: "lower", center, radius, strength, falloff });
+        },
+        flatten(center, target) {
+            return terrain.apply({ mode: "flatten", center, radius, strength, falloff, ...(target === undefined ? {} : { target }) });
+        },
+        paint(center, paintSurface) {
+            const chosen = paintSurface ?? surface;
+            return terrain.apply({ mode: "paint", center, radius, ...(chosen === undefined ? {} : { surface: chosen }) });
+        },
+        setRadius(next) {
+            radius = next;
+        },
+        setStrength(next) {
+            strength = next;
+        },
+        config() {
+            return { radius, strength, falloff, surface };
+        },
+    };
+}

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>;