@jgengine/core 0.5.0 → 0.6.0

package/dist/world/scatterItems.js

@@ -0,0 +1,85 @@
+function hash(ix, iz, salt) {
+    let h = salt | 0;
+    h = Math.imul(h ^ (ix | 0), 0x27d4eb2d);
+    h = Math.imul(h ^ (iz | 0), 0x85ebca6b);
+    h ^= h >>> 15;
+    h = Math.imul(h, 0x2c1b3c6d);
+    h ^= h >>> 12;
+    return (h >>> 0) / 4294967295;
+}
+const DEFAULT_MAX_SLOPE = 0.55;
+/**
+ * Deterministically place opaque items across `area`, grounded on a region field.
+ * For each grid cell it asks `layersFor` which items may appear in that region and
+ * rolls one against their densities. The engine never interprets `item` — a game
+ * maps it to a mesh or entity. Content scatter (region-driven density) as opposed to
+ * `scatter` in `./scatter`, which is renderer-free geometric point distribution.
+ */
+export function scatterItems(field, area, layersFor, options = {}) {
+    const cell = options.cell ?? 5;
+    const max = options.max ?? 1400;
+    const salt = field.seed ^ (options.saltKey ?? 0x5f3a);
+    const out = [];
+    for (let gx = Math.floor(area.minX / cell); gx <= Math.ceil(area.maxX / cell); gx += 1) {
+        for (let gz = Math.floor(area.minZ / cell); gz <= Math.ceil(area.maxZ / cell); gz += 1) {
+            const roll = hash(gx, gz, salt);
+            const x = (gx + hash(gx, gz, salt ^ 0x11)) * cell;
+            const z = (gz + hash(gx, gz, salt ^ 0x22)) * cell;
+            const y = field.sampleHeight(x, z);
+            const sample = field.sampleRegion(x, z);
+            const layers = layersFor(sample);
+            if (layers.length === 0)
+                continue;
+            let total = 0;
+            for (const layer of layers)
+                total += layer.density;
+            if (roll > total)
+                continue;
+            let acc = 0;
+            let chosen = layers[0];
+            for (const layer of layers) {
+                acc += layer.density;
+                if (roll <= acc) {
+                    chosen = layer;
+                    break;
+                }
+            }
+            if ((chosen.aboveWaterOnly ?? true) && y < field.seaLevel + 0.1)
+                continue;
+            if (1 - field.sampleNormal(x, z)[1] > (chosen.maxSlope ?? DEFAULT_MAX_SLOPE))
+                continue;
+            const scaleRoll = hash(gx, gz, salt ^ 0x99);
+            const min = chosen.minScale ?? 0.8;
+            const maxScale = chosen.maxScale ?? 1.2;
+            out.push({
+                id: `${gx}:${gz}`,
+                item: chosen.item,
+                x,
+                z,
+                y,
+                scale: min + scaleRoll * (maxScale - min),
+                rotation: hash(gx, gz, salt ^ 0xabcd) * Math.PI * 2,
+                regionId: sample.region.id,
+            });
+            if (out.length >= max)
+                return out;
+        }
+    }
+    return out;
+}
+/** Weighted pick from opaque entries; `roll` in [0, 1). Returns null when empty. */
+export function pickWeighted(entries, roll) {
+    if (entries.length === 0)
+        return null;
+    let total = 0;
+    for (const entry of entries)
+        total += entry.weight;
+    const pick = roll * total;
+    let acc = 0;
+    for (const entry of entries) {
+        acc += entry.weight;
+        if (pick <= acc)
+            return entry.value;
+    }
+    return entries[entries.length - 1].value;
+}

package/dist/world/terrain.d.ts

@@ -0,0 +1,54 @@
+import type { TerrainEnvironmentDescriptor, WorldBounds } from "./features.js";
+export type TerrainNormal = readonly [number, number, number];
+export interface TerrainField {
+    sampleHeight(x: number, z: number): number;
+    sampleNormal(x: number, z: number): TerrainNormal;
+    readonly bounds?: WorldBounds;
+    readonly waterLevel?: number;
+}
+export declare function valueNoise(x: number, z: number, seed: number): number;
+export interface FractalNoiseConfig {
+    seed: number;
+    frequency: number;
+    octaves: number;
+    lacunarity: number;
+    persistence: number;
+    ridged: boolean;
+}
+export declare function fractalNoise(x: number, z: number, config: FractalNoiseConfig): number;
+export declare function seedFrom(value: string | number | undefined, fallback: number): number;
+export declare function withNormal(sampleHeight: (x: number, z: number) => number): TerrainField["sampleNormal"];
+export declare const FLAT_FIELD: TerrainField;
+export declare function flatField(): TerrainField;
+export interface NoiseFieldConfig {
+    seed?: string | number;
+    amplitude?: number;
+    frequency?: number;
+    octaves?: number;
+    lacunarity?: number;
+    persistence?: number;
+    baseHeight?: number;
+    ridged?: boolean;
+    bounds?: WorldBounds;
+    waterLevel?: number;
+}
+export declare function noiseField(config?: NoiseFieldConfig): TerrainField;
+export interface RollingFieldConfig {
+    seed?: string | number;
+    amplitude?: number;
+    frequency?: number;
+    bounds?: WorldBounds;
+}
+export declare function rollingField(config?: RollingFieldConfig): TerrainField;
+export interface ArenaFieldConfig {
+    seed?: string | number;
+    bounds?: WorldBounds;
+}
+export declare const ARENA_WATER_LEVEL = -0.9;
+export declare function arenaField(config?: ArenaFieldConfig): TerrainField;
+export declare function resolveTerrainField(descriptor?: TerrainEnvironmentDescriptor): TerrainField;
+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;
+    stepZ: number;
+};

package/dist/world/terrain.js

@@ -0,0 +1,181 @@
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+function hash2(ix, iz, seed) {
+    let h = seed | 0;
+    h = Math.imul(h ^ (ix | 0), 0x27d4eb2d);
+    h = Math.imul(h ^ (iz | 0), 0x85ebca6b);
+    h ^= h >>> 15;
+    h = Math.imul(h, 0x2c1b3c6d);
+    h ^= h >>> 12;
+    return (h >>> 0) / 4294967295;
+}
+export function valueNoise(x, z, seed) {
+    const x0 = Math.floor(x);
+    const z0 = Math.floor(z);
+    const fx = x - x0;
+    const fz = z - z0;
+    const v00 = hash2(x0, z0, seed);
+    const v10 = hash2(x0 + 1, z0, seed);
+    const v01 = hash2(x0, z0 + 1, seed);
+    const v11 = hash2(x0 + 1, z0 + 1, seed);
+    const sx = fx * fx * (3 - 2 * fx);
+    const sz = fz * fz * (3 - 2 * fz);
+    const top = lerp(v00, v10, sx);
+    const bottom = lerp(v01, v11, sx);
+    return lerp(top, bottom, sz) * 2 - 1;
+}
+export function fractalNoise(x, z, config) {
+    let amplitude = 1;
+    let frequency = config.frequency;
+    let sum = 0;
+    let norm = 0;
+    for (let octave = 0; octave < config.octaves; octave += 1) {
+        let sample = valueNoise(x * frequency, z * frequency, config.seed + octave * 1013);
+        if (config.ridged)
+            sample = 1 - 2 * Math.abs(sample);
+        sum += sample * amplitude;
+        norm += amplitude;
+        amplitude *= config.persistence;
+        frequency *= config.lacunarity;
+    }
+    return norm === 0 ? 0 : sum / norm;
+}
+export function seedFrom(value, fallback) {
+    if (typeof value === "number")
+        return value | 0;
+    if (typeof value === "string") {
+        let hash = 2166136261;
+        for (let index = 0; index < value.length; index += 1) {
+            hash ^= value.charCodeAt(index);
+            hash = Math.imul(hash, 16777619);
+        }
+        return hash | 0;
+    }
+    return fallback;
+}
+export function withNormal(sampleHeight) {
+    const epsilon = 0.75;
+    return (x, z) => {
+        const hx = sampleHeight(x + epsilon, z) - sampleHeight(x - epsilon, z);
+        const hz = sampleHeight(x, z + epsilon) - sampleHeight(x, z - epsilon);
+        const nx = -hx;
+        const nz = -hz;
+        const ny = 2 * epsilon;
+        const length = Math.hypot(nx, ny, nz) || 1;
+        return [nx / length, ny / length, nz / length];
+    };
+}
+function fieldFromHeight(sampleHeight, extra) {
+    return {
+        sampleHeight,
+        sampleNormal: withNormal(sampleHeight),
+        ...(extra?.bounds === undefined ? {} : { bounds: extra.bounds }),
+        ...(extra?.waterLevel === undefined ? {} : { waterLevel: extra.waterLevel }),
+    };
+}
+export const FLAT_FIELD = {
+    sampleHeight: () => 0,
+    sampleNormal: () => [0, 1, 0],
+};
+export function flatField() {
+    return FLAT_FIELD;
+}
+export function noiseField(config = {}) {
+    const fractal = {
+        seed: seedFrom(config.seed, 1337),
+        frequency: config.frequency ?? 0.03,
+        octaves: config.octaves ?? 4,
+        lacunarity: config.lacunarity ?? 2,
+        persistence: config.persistence ?? 0.5,
+        ridged: config.ridged ?? false,
+    };
+    const amplitude = config.amplitude ?? 1;
+    const baseHeight = config.baseHeight ?? 0;
+    return fieldFromHeight((x, z) => baseHeight + amplitude * fractalNoise(x, z, fractal), {
+        bounds: config.bounds,
+        waterLevel: config.waterLevel,
+    });
+}
+export function rollingField(config = {}) {
+    return noiseField({
+        seed: config.seed ?? "rolling",
+        amplitude: config.amplitude ?? 0.55,
+        frequency: config.frequency ?? 0.03,
+        octaves: 3,
+        persistence: 0.55,
+        bounds: config.bounds,
+    });
+}
+const ARENA_PLATEAU_HEIGHT = 6;
+const ARENA_HILL_HEIGHT = 4.2;
+const ARENA_BASIN_DEPTH = 2.6;
+export const ARENA_WATER_LEVEL = -0.9;
+function smoothstep(edge0, edge1, value) {
+    if (edge0 === edge1)
+        return value < edge0 ? 0 : 1;
+    const t = clamp01((value - edge0) / (edge1 - edge0));
+    return t * t * (3 - 2 * t);
+}
+export function arenaField(config = {}) {
+    const seed = seedFrom(config.seed ?? "arena", 7);
+    const rolling = {
+        seed,
+        frequency: 0.03,
+        octaves: 3,
+        lacunarity: 2,
+        persistence: 0.5,
+        ridged: false,
+    };
+    const sampleHeight = (x, z) => {
+        const distToSpawn = Math.hypot(x, z);
+        const spawn = 1 - smoothstep(14, 24, distToSpawn);
+        const undulation = 0.55 * fractalNoise(x, z, rolling);
+        const cliff = smoothstep(20, 27, z);
+        const ramp = smoothstep(16, 46, z);
+        const inRamp = 1 - clamp01(Math.abs(x) / 6);
+        const plateauExtent = 1 - smoothstep(30, 42, Math.abs(x));
+        const mesa = ARENA_PLATEAU_HEIGHT * plateauExtent * lerp(cliff, ramp, inRamp);
+        const hillDist = Math.hypot(x - 34, z + 8) / 18;
+        const hillFalloff = smoothstep(0, 1, 1 - hillDist);
+        const hill = ARENA_HILL_HEIGHT * hillFalloff;
+        const basinDist = Math.hypot(x + 40, z + 20) / 20;
+        const basin = -ARENA_BASIN_DEPTH * smoothstep(0, 1, 1 - basinDist);
+        return (undulation + mesa + hill + basin) * (1 - spawn);
+    };
+    return fieldFromHeight(sampleHeight, { bounds: config.bounds, waterLevel: ARENA_WATER_LEVEL });
+}
+export function resolveTerrainField(descriptor) {
+    if (descriptor === undefined)
+        return flatField();
+    return 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,
+    });
+}
+export const DEFAULT_MAX_WALK_SLOPE = 0.6;
+export function resolveGroundStep(field, x, z, stepX, stepZ, maxSlope = DEFAULT_MAX_WALK_SLOPE) {
+    const baseHeight = field.sampleHeight(x, z);
+    const tooSteep = (dx, dz) => {
+        const distance = Math.hypot(dx, dz);
+        if (distance < 1e-6)
+            return false;
+        const rise = field.sampleHeight(x + dx, z + dz) - baseHeight;
+        return rise / distance > maxSlope;
+    };
+    if (!tooSteep(stepX, stepZ))
+        return { stepX, stepZ };
+    return {
+        stepX: tooSteep(stepX, 0) ? 0 : stepX,
+        stepZ: tooSteep(0, stepZ) ? 0 : stepZ,
+    };
+}

package/dist/world/water.d.ts

@@ -0,0 +1,27 @@
+import type { OceanEnvironmentDescriptor } from "./features.js";
+export type WaterNormal = readonly [number, number, number];
+export interface GerstnerWave {
+    direction: readonly [number, number];
+    wavelength: number;
+    amplitude: number;
+    steepness: number;
+    speed: number;
+}
+export interface WaterSurfaceConfig {
+    level?: number;
+    waveHeight?: number;
+    waveScale?: number;
+    waveSpeed?: number;
+    waves?: number;
+    choppiness?: number;
+}
+export interface WaterSurface {
+    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];
+}
+export declare function synthesizeWaves(config?: WaterSurfaceConfig): GerstnerWave[];
+export declare function waterSurface(config?: WaterSurfaceConfig): WaterSurface;
+export declare function waterSurfaceFromDescriptor(descriptor: OceanEnvironmentDescriptor, waves?: number): WaterSurface;

package/dist/world/water.js

@@ -0,0 +1,125 @@
+const GRAVITY = 9.81;
+const TWO_PI = Math.PI * 2;
+const AMPLITUDE_FALLOFF = 0.65;
+const WAVELENGTH_FALLOFF = 0.65;
+const DIRECTION_SPREAD = 0.62;
+function resolveConfig(config) {
+    return {
+        level: config.level ?? 0,
+        waveHeight: config.waveHeight ?? 1.2,
+        waveScale: config.waveScale ?? 18,
+        waveSpeed: config.waveSpeed ?? 0.55,
+        waves: config.waves ?? 4,
+        choppiness: config.choppiness ?? 1,
+    };
+}
+export function synthesizeWaves(config = {}) {
+    const resolved = resolveConfig(config);
+    const count = Math.max(0, Math.floor(resolved.waves));
+    if (count === 0 || resolved.waveHeight <= 0) {
+        return [];
+    }
+    let amplitudeSum = 0;
+    for (let i = 0; i < count; i += 1) {
+        amplitudeSum += AMPLITUDE_FALLOFF ** i;
+    }
+    const amplitudeUnit = resolved.waveHeight / amplitudeSum;
+    const waves = [];
+    for (let i = 0; i < count; i += 1) {
+        const amplitude = amplitudeUnit * AMPLITUDE_FALLOFF ** i;
+        const wavelength = resolved.waveScale * WAVELENGTH_FALLOFF ** i;
+        const k = TWO_PI / wavelength;
+        const angle = DIRECTION_SPREAD * (i % 2 === 0 ? 1 : -1) * Math.ceil(i / 2);
+        const direction = [Math.cos(angle), Math.sin(angle)];
+        const omega = Math.sqrt(GRAVITY * k) * resolved.waveSpeed;
+        const speed = omega / k;
+        const steepnessLimit = 1 / (k * amplitude * count);
+        const steepness = Math.min(1, Math.max(0, 0.4 * steepnessLimit));
+        waves.push({ direction, wavelength, amplitude, steepness, speed });
+    }
+    return waves;
+}
+export function waterSurface(config = {}) {
+    const resolved = resolveConfig(config);
+    const level = resolved.level;
+    const choppiness = resolved.choppiness;
+    const waves = synthesizeWaves(config);
+    const height = (x, z, time) => {
+        let y = level;
+        for (const wave of waves) {
+            const k = TWO_PI / wave.wavelength;
+            const omega = wave.speed * k;
+            const phase = k * (wave.direction[0] * x + wave.direction[1] * z) - omega * time;
+            y += wave.amplitude * Math.sin(phase);
+        }
+        return y;
+    };
+    const displace = (x, z, time) => {
+        let dx = x;
+        let dz = z;
+        let dy = level;
+        for (const wave of waves) {
+            const k = TWO_PI / wave.wavelength;
+            const omega = wave.speed * k;
+            const phase = k * (wave.direction[0] * x + wave.direction[1] * z) - omega * time;
+            const cosPhase = Math.cos(phase);
+            const q = wave.steepness;
+            dx += q * wave.amplitude * choppiness * wave.direction[0] * cosPhase;
+            dz += q * wave.amplitude * choppiness * wave.direction[1] * cosPhase;
+            dy += wave.amplitude * Math.sin(phase);
+        }
+        return [dx, dy, dz];
+    };
+    const normal = (x, z, time) => {
+        let tx = 1;
+        let ty = 0;
+        let tz = 0;
+        let bx = 0;
+        let by = 0;
+        let bz = 1;
+        for (const wave of waves) {
+            const k = TWO_PI / wave.wavelength;
+            const omega = wave.speed * k;
+            const phase = k * (wave.direction[0] * x + wave.direction[1] * z) - omega * time;
+            const cosPhase = Math.cos(phase);
+            const sinPhase = Math.sin(phase);
+            const wa = k * wave.amplitude;
+            const q = wave.steepness;
+            const dxWave = wave.direction[0];
+            const dzWave = wave.direction[1];
+            tx += -q * dxWave * dxWave * wa * choppiness * sinPhase;
+            ty += dxWave * wa * cosPhase;
+            tz += -q * dxWave * dzWave * wa * choppiness * sinPhase;
+            bx += -q * dxWave * dzWave * wa * choppiness * sinPhase;
+            by += dzWave * wa * cosPhase;
+            bz += -q * dzWave * dzWave * wa * choppiness * sinPhase;
+        }
+        let nx = by * tz - bz * ty;
+        let ny = bz * tx - bx * tz;
+        let nz = bx * ty - by * tx;
+        const lengthSq = nx * nx + ny * ny + nz * nz;
+        if (lengthSq === 0) {
+            return [0, 1, 0];
+        }
+        const inv = 1 / Math.sqrt(lengthSq);
+        nx *= inv;
+        ny *= inv;
+        nz *= inv;
+        if (ny < 0) {
+            nx = -nx;
+            ny = -ny;
+            nz = -nz;
+        }
+        return [nx, ny, nz];
+    };
+    return { level, waves, height, normal, displace };
+}
+export function waterSurfaceFromDescriptor(descriptor, waves) {
+    return waterSurface({
+        level: descriptor.level,
+        waveHeight: descriptor.waveHeight,
+        waveScale: descriptor.waveScale,
+        waveSpeed: descriptor.waveSpeed,
+        ...(waves === undefined ? {} : { waves }),
+    });
+}

package/dist/world/wind.d.ts

@@ -0,0 +1,17 @@
+export type WindVector = readonly [number, number];
+export interface WindFieldConfig {
+    direction?: WindVector;
+    speed?: number;
+    gust?: number;
+    gustFrequency?: number;
+    turbulence?: number;
+    seed?: string | number;
+}
+export interface WindField {
+    readonly direction: WindVector;
+    readonly speed: number;
+    at(time: number): WindVector;
+    atPoint(x: number, z: number, time: number): WindVector;
+    strengthAt(x: number, z: number, time: number): number;
+}
+export declare function windField(config?: WindFieldConfig): WindField;

package/dist/world/wind.js

@@ -0,0 +1,40 @@
+import { fractalNoise, seedFrom, valueNoise } from "./terrain.js";
+const WIND_SEED_FALLBACK = 0x77696e64;
+function normalizeDirection(direction) {
+    const length = Math.hypot(direction[0], direction[1]);
+    if (length === 0)
+        return [1, 0];
+    return [direction[0] / length, direction[1] / length];
+}
+export function windField(config = {}) {
+    const direction = normalizeDirection(config.direction ?? [1, 0]);
+    const speed = config.speed ?? 1;
+    const gust = config.gust ?? 0;
+    const gustFrequency = config.gustFrequency ?? 0.15;
+    const turbulence = config.turbulence ?? 0;
+    const seed = seedFrom(config.seed, WIND_SEED_FALLBACK);
+    const at = (time) => {
+        const gustAmt = gust *
+            fractalNoise(time * gustFrequency, 0, {
+                seed,
+                frequency: 1,
+                octaves: 3,
+                lacunarity: 2,
+                persistence: 0.5,
+                ridged: false,
+            });
+        const magnitude = speed + gustAmt;
+        return [direction[0] * magnitude, direction[1] * magnitude];
+    };
+    const atPoint = (x, z, time) => {
+        const base = at(time);
+        const tx = valueNoise(x * 0.05 + time * 0.1, z * 0.05, seed);
+        const tz = valueNoise(z * 0.05, x * 0.05 - time * 0.1, seed + 101);
+        return [base[0] + turbulence * tx, base[1] + turbulence * tz];
+    };
+    const strengthAt = (x, z, time) => {
+        const [wx, wz] = atPoint(x, z, time);
+        return Math.hypot(wx, wz);
+    };
+    return { direction, speed, at, atPoint, strengthAt };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Genre-agnostic TypeScript game engine SDK: game runtime, state store, entity scene, combat, movement, inventory, economy, quests, multiplayer primitives.",
   "license": "AGPL-3.0-only",
   "type": "module",