@jgengine/core 0.4.0 → 0.6.0

package/dist/world/features.d.ts

@@ -2,6 +2,103 @@ export interface WorldBounds {
     w: number;
     d: number;
 }
+export type EnvironmentVec2 = readonly [number, number];
+export interface EnvironmentArea extends WorldBounds {
+    h?: number;
+}
+export interface TerrainEnvironmentConfig {
+    bounds?: WorldBounds;
+    height?: number;
+    heightMap?: string;
+    material?: string;
+    seed?: string;
+    frequency?: number;
+    octaves?: number;
+    ridged?: boolean;
+    baseHeight?: number;
+    waterLevel?: number;
+}
+export interface RainEnvironmentConfig {
+    area?: EnvironmentArea;
+    density?: number;
+    speed?: number;
+    dropLength?: number;
+    wind?: EnvironmentVec2;
+    color?: string;
+}
+export interface SnowEnvironmentConfig {
+    area?: EnvironmentArea;
+    density?: number;
+    speed?: number;
+    flakeSize?: number;
+    drift?: number;
+    wind?: EnvironmentVec2;
+    color?: string;
+}
+export interface GrassEnvironmentConfig {
+    area?: WorldBounds;
+    density?: number;
+    bladeHeight?: readonly [number, number];
+    bladeWidth?: number;
+    windStrength?: number;
+    colors?: readonly string[];
+    seed?: string;
+}
+export interface OceanEnvironmentConfig {
+    bounds?: WorldBounds;
+    level?: number;
+    waveHeight?: number;
+    waveScale?: number;
+    waveSpeed?: number;
+    color?: string;
+}
+export interface BuildingEnvironmentConfig {
+    count?: number;
+    footprint?: WorldBounds;
+    stories?: readonly [number, number];
+    storyHeight?: number;
+    spacing?: number;
+    style?: string;
+    seed?: string;
+}
+export type TerrainEnvironmentDescriptor = {
+    kind: "terrain";
+} & Required<Pick<TerrainEnvironmentConfig, "bounds" | "height">> & Omit<TerrainEnvironmentConfig, "bounds" | "height">;
+export type RainEnvironmentDescriptor = {
+    kind: "rain";
+} & Required<Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color">>;
+export type SnowEnvironmentDescriptor = {
+    kind: "snow";
+} & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color">>;
+export type GrassEnvironmentDescriptor = {
+    kind: "grass";
+} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed">;
+export type OceanEnvironmentDescriptor = {
+    kind: "ocean";
+} & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">>;
+export type BuildingEnvironmentDescriptor = {
+    kind: "building";
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed">;
+export type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor;
+export type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor;
+export type WaterEnvironmentDescriptor = OceanEnvironmentDescriptor;
+export type StructureEnvironmentDescriptor = BuildingEnvironmentDescriptor;
+export type EnvironmentDescriptorList<T> = T | readonly T[];
+export interface EnvironmentWorldConfig {
+    terrain?: TerrainEnvironmentDescriptor;
+    weather?: EnvironmentDescriptorList<WeatherEnvironmentDescriptor>;
+    vegetation?: EnvironmentDescriptorList<VegetationEnvironmentDescriptor>;
+    water?: EnvironmentDescriptorList<WaterEnvironmentDescriptor>;
+    structures?: EnvironmentDescriptorList<StructureEnvironmentDescriptor>;
+}
+export interface EnvironmentWorldFeature {
+    kind: "environment";
+    terrain?: TerrainEnvironmentDescriptor;
+    weather?: readonly WeatherEnvironmentDescriptor[];
+    vegetation?: readonly VegetationEnvironmentDescriptor[];
+    water?: readonly WaterEnvironmentDescriptor[];
+    structures?: readonly StructureEnvironmentDescriptor[];
+}
 export interface BiomesWorldConfig {
     map: string;
     zones: string;
@@ -29,9 +126,16 @@ export type WorldFeature = ({
     kind: "plots";
 } & PlotsWorldConfig) | ({
     kind: "tilemap";
-} & TilemapWorldConfig) | {
+} & TilemapWorldConfig) | EnvironmentWorldFeature | {
     kind: "flat";
 };
+export declare function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature;
+export declare function terrain(config?: TerrainEnvironmentConfig): TerrainEnvironmentDescriptor;
+export declare function rain(config?: RainEnvironmentConfig): RainEnvironmentDescriptor;
+export declare function snow(config?: SnowEnvironmentConfig): SnowEnvironmentDescriptor;
+export declare function grass(config?: GrassEnvironmentConfig): GrassEnvironmentDescriptor;
+export declare function ocean(config?: OceanEnvironmentConfig): OceanEnvironmentDescriptor;
+export declare function building(config?: BuildingEnvironmentConfig): BuildingEnvironmentDescriptor;
 export declare function biomes(config: BiomesWorldConfig): WorldFeature;
 export declare function voxel(config: VoxelWorldConfig): WorldFeature;
 export declare function plots(config?: PlotsWorldConfig): WorldFeature;

package/dist/world/features.js

@@ -1,3 +1,98 @@
+function list(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return Array.isArray(value) ? value : [value];
+}
+function withOptional(base, optional) {
+    return optional === undefined ? base : { ...base, ...optional };
+}
+export function environment(config = {}) {
+    const weather = list(config.weather);
+    const vegetation = list(config.vegetation);
+    const water = list(config.water);
+    const structures = list(config.structures);
+    return {
+        kind: "environment",
+        ...(config.terrain === undefined ? {} : { terrain: config.terrain }),
+        ...(weather === undefined ? {} : { weather }),
+        ...(vegetation === undefined ? {} : { vegetation }),
+        ...(water === undefined ? {} : { water }),
+        ...(structures === undefined ? {} : { structures }),
+    };
+}
+export function terrain(config = {}) {
+    return withOptional({
+        kind: "terrain",
+        bounds: config.bounds ?? { w: 512, d: 512 },
+        height: config.height ?? 0,
+    }, {
+        ...(config.heightMap === undefined ? {} : { heightMap: config.heightMap }),
+        ...(config.material === undefined ? {} : { material: config.material }),
+        ...(config.seed === undefined ? {} : { seed: config.seed }),
+        ...(config.frequency === undefined ? {} : { frequency: config.frequency }),
+        ...(config.octaves === undefined ? {} : { octaves: config.octaves }),
+        ...(config.ridged === undefined ? {} : { ridged: config.ridged }),
+        ...(config.baseHeight === undefined ? {} : { baseHeight: config.baseHeight }),
+        ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
+    });
+}
+export function rain(config = {}) {
+    return {
+        kind: "rain",
+        area: config.area ?? { w: 256, d: 256, h: 80 },
+        density: config.density ?? 0.65,
+        speed: config.speed ?? 18,
+        dropLength: config.dropLength ?? 0.8,
+        wind: config.wind ?? [0, 0],
+        color: config.color ?? "#9ec8ff",
+    };
+}
+export function snow(config = {}) {
+    return {
+        kind: "snow",
+        area: config.area ?? { w: 256, d: 256, h: 80 },
+        density: config.density ?? 0.35,
+        speed: config.speed ?? 2.4,
+        flakeSize: config.flakeSize ?? 0.08,
+        drift: config.drift ?? 0.4,
+        wind: config.wind ?? [0, 0],
+        color: config.color ?? "#ffffff",
+    };
+}
+export function grass(config = {}) {
+    return withOptional({
+        kind: "grass",
+        area: config.area ?? { w: 128, d: 128 },
+        density: config.density ?? 4,
+        bladeHeight: config.bladeHeight ?? [0.25, 0.9],
+        bladeWidth: config.bladeWidth ?? 0.035,
+        windStrength: config.windStrength ?? 0.35,
+        colors: config.colors ?? ["#3f7d2d", "#66a83f"],
+    }, config.seed === undefined ? undefined : { seed: config.seed });
+}
+export function ocean(config = {}) {
+    return {
+        kind: "ocean",
+        bounds: config.bounds ?? { w: 1024, d: 1024 },
+        level: config.level ?? 0,
+        waveHeight: config.waveHeight ?? 1.2,
+        waveScale: config.waveScale ?? 18,
+        waveSpeed: config.waveSpeed ?? 0.55,
+        color: config.color ?? "#1d7fa3",
+    };
+}
+export function building(config = {}) {
+    return withOptional({
+        kind: "building",
+        count: config.count ?? 1,
+        footprint: config.footprint ?? { w: 8, d: 8 },
+        stories: config.stories ?? [1, 4],
+        storyHeight: config.storyHeight ?? 3,
+        spacing: config.spacing ?? 2,
+        style: config.style ?? "generic",
+    }, config.seed === undefined ? undefined : { seed: config.seed });
+}
 export function biomes(config) {
     return { kind: "biomes", ...config };
 }

package/dist/world/geometry.d.ts

@@ -0,0 +1,23 @@
+export type Vec2 = readonly [number, number];
+export interface Footprint {
+    w: number;
+    d: number;
+}
+export interface Aabb {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+export interface MoveOptions {
+    bounds?: Aabb;
+    radius?: number;
+}
+export declare function snapToGrid(point: Vec2, size: number): Vec2;
+export declare function footprintAabb(center: Vec2, footprint: Footprint, quarterTurns?: number): Aabb;
+export declare function expandAabb(aabb: Aabb, margin: number): Aabb;
+export declare function aabbOverlap(a: Aabb, b: Aabb): boolean;
+export declare function aabbContains(outer: Aabb, inner: Aabb): boolean;
+export declare function pointInAabb(point: Vec2, aabb: Aabb): boolean;
+export declare function clampToAabb(point: Vec2, aabb: Aabb): Vec2;
+export declare function resolveMove(from: Vec2, delta: Vec2, blockers: readonly Aabb[], options?: MoveOptions): Vec2;

package/dist/world/geometry.js

@@ -0,0 +1,75 @@
+export function snapToGrid(point, size) {
+    if (!(size > 0))
+        return point;
+    return [Math.round(point[0] / size) * size, Math.round(point[1] / size) * size];
+}
+export function footprintAabb(center, footprint, quarterTurns = 0) {
+    const turned = ((quarterTurns % 2) + 2) % 2 === 1;
+    const halfW = (turned ? footprint.d : footprint.w) / 2;
+    const halfD = (turned ? footprint.w : footprint.d) / 2;
+    return {
+        minX: center[0] - halfW,
+        maxX: center[0] + halfW,
+        minZ: center[1] - halfD,
+        maxZ: center[1] + halfD,
+    };
+}
+export function expandAabb(aabb, margin) {
+    return {
+        minX: aabb.minX - margin,
+        maxX: aabb.maxX + margin,
+        minZ: aabb.minZ - margin,
+        maxZ: aabb.maxZ + margin,
+    };
+}
+export function aabbOverlap(a, b) {
+    return a.minX < b.maxX && a.maxX > b.minX && a.minZ < b.maxZ && a.maxZ > b.minZ;
+}
+export function aabbContains(outer, inner) {
+    return (inner.minX >= outer.minX &&
+        inner.maxX <= outer.maxX &&
+        inner.minZ >= outer.minZ &&
+        inner.maxZ <= outer.maxZ);
+}
+export function pointInAabb(point, aabb) {
+    return point[0] >= aabb.minX && point[0] <= aabb.maxX && point[1] >= aabb.minZ && point[1] <= aabb.maxZ;
+}
+export function clampToAabb(point, aabb) {
+    return [
+        Math.min(Math.max(point[0], aabb.minX), aabb.maxX),
+        Math.min(Math.max(point[1], aabb.minZ), aabb.maxZ),
+    ];
+}
+function resolveAxis(main, cross, delta, blockers, axisX) {
+    let next = main + delta;
+    if (delta === 0)
+        return next;
+    for (const blocker of blockers) {
+        const minMain = axisX ? blocker.minX : blocker.minZ;
+        const maxMain = axisX ? blocker.maxX : blocker.maxZ;
+        const minCross = axisX ? blocker.minZ : blocker.minX;
+        const maxCross = axisX ? blocker.maxZ : blocker.maxX;
+        if (cross <= minCross || cross >= maxCross)
+            continue;
+        if (delta > 0) {
+            if (main <= minMain && next > minMain)
+                next = minMain;
+        }
+        else {
+            if (main >= maxMain && next < maxMain)
+                next = maxMain;
+        }
+    }
+    return next;
+}
+export function resolveMove(from, delta, blockers, options = {}) {
+    const radius = options.radius ?? 0;
+    const expanded = radius === 0 ? blockers : blockers.map((blocker) => expandAabb(blocker, radius));
+    let x = resolveAxis(from[0], from[1], delta[0], expanded, true);
+    if (options.bounds)
+        x = Math.min(Math.max(x, options.bounds.minX + radius), options.bounds.maxX - radius);
+    let z = resolveAxis(from[1], x, delta[1], expanded, false);
+    if (options.bounds)
+        z = Math.min(Math.max(z, options.bounds.minZ + radius), options.bounds.maxZ - radius);
+    return [x, z];
+}

package/dist/world/interiors.d.ts

@@ -0,0 +1,35 @@
+import { type Aabb, type Vec2 } from "./geometry.js";
+export type SpaceRef = {
+    kind: "exterior";
+} | {
+    kind: "interior";
+    id: string;
+};
+export interface EntityLocation {
+    space: SpaceRef;
+    position: Vec2;
+}
+export interface Interior {
+    id: string;
+    origin: Vec2;
+    rotation?: number;
+    bounds: Aabb;
+    obstacles?: readonly Aabb[];
+}
+export interface Exterior {
+    bounds?: Aabb;
+    obstacles?: readonly Aabb[];
+}
+export interface InteriorsConfig {
+    exterior?: Exterior;
+    interiors?: readonly Interior[];
+    radius?: number;
+}
+export interface Interiors {
+    move(location: EntityLocation, delta: Vec2): EntityLocation;
+    enter(location: EntityLocation, id: string): EntityLocation | null;
+    leave(location: EntityLocation): EntityLocation | null;
+    toInterior(id: string, exterior: Vec2): Vec2 | null;
+    toExterior(id: string, interior: Vec2): Vec2 | null;
+}
+export declare function createInteriors(config?: InteriorsConfig): Interiors;

package/dist/world/interiors.js

@@ -0,0 +1,66 @@
+import { resolveMove } from "./geometry.js";
+function rotate(point, angle) {
+    if (angle === 0)
+        return point;
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    return [point[0] * cos - point[1] * sin, point[0] * sin + point[1] * cos];
+}
+function toInteriorFrame(interior, exterior) {
+    const local = [exterior[0] - interior.origin[0], exterior[1] - interior.origin[1]];
+    return rotate(local, -(interior.rotation ?? 0));
+}
+function toExteriorFrame(interior, local) {
+    const rotated = rotate(local, interior.rotation ?? 0);
+    return [rotated[0] + interior.origin[0], rotated[1] + interior.origin[1]];
+}
+export function createInteriors(config = {}) {
+    const radius = config.radius ?? 0;
+    const exterior = config.exterior ?? {};
+    const byId = new Map();
+    for (const interior of config.interiors ?? [])
+        byId.set(interior.id, interior);
+    return {
+        move(location, delta) {
+            if (location.space.kind === "exterior") {
+                const position = resolveMove(location.position, delta, exterior.obstacles ?? [], {
+                    bounds: exterior.bounds,
+                    radius,
+                });
+                return { space: { kind: "exterior" }, position };
+            }
+            const interior = byId.get(location.space.id);
+            if (interior === undefined)
+                return location;
+            const position = resolveMove(location.position, delta, interior.obstacles ?? [], {
+                bounds: interior.bounds,
+                radius,
+            });
+            return { space: { kind: "interior", id: interior.id }, position };
+        },
+        enter(location, id) {
+            if (location.space.kind !== "exterior")
+                return null;
+            const interior = byId.get(id);
+            if (interior === undefined)
+                return null;
+            return { space: { kind: "interior", id }, position: toInteriorFrame(interior, location.position) };
+        },
+        leave(location) {
+            if (location.space.kind !== "interior")
+                return null;
+            const interior = byId.get(location.space.id);
+            if (interior === undefined)
+                return null;
+            return { space: { kind: "exterior" }, position: toExteriorFrame(interior, location.position) };
+        },
+        toInterior(id, exterior) {
+            const interior = byId.get(id);
+            return interior === undefined ? null : toInteriorFrame(interior, exterior);
+        },
+        toExterior(id, interior) {
+            const frame = byId.get(id);
+            return frame === undefined ? null : toExteriorFrame(frame, interior);
+        },
+    };
+}

package/dist/world/placement.d.ts

@@ -0,0 +1,30 @@
+import { type Aabb, type Footprint, type Vec2 } from "./geometry.js";
+export interface PlacementObstacle {
+    aabb: Aabb;
+    id?: string;
+}
+export interface PlacementRequest {
+    center: Vec2;
+    footprint: Footprint;
+    quarterTurns?: number;
+}
+export interface PlacementRules {
+    bounds?: Aabb;
+    obstacles?: readonly PlacementObstacle[];
+    snap?: number;
+}
+export type PlacementResult = {
+    status: "ok";
+    center: Vec2;
+    aabb: Aabb;
+} | {
+    status: "rejected";
+    reason: "out-of-bounds";
+} | {
+    status: "rejected";
+    reason: "overlap";
+    obstacle: PlacementObstacle;
+    index: number;
+};
+export declare function validatePlacement(request: PlacementRequest, rules?: PlacementRules): PlacementResult;
+export declare function footprintObstacle(request: PlacementRequest, id?: string): PlacementObstacle;

package/dist/world/placement.js

@@ -0,0 +1,20 @@
+import { aabbContains, aabbOverlap, footprintAabb, snapToGrid, } from "./geometry.js";
+export function validatePlacement(request, rules = {}) {
+    const center = rules.snap === undefined ? request.center : snapToGrid(request.center, rules.snap);
+    const aabb = footprintAabb(center, request.footprint, request.quarterTurns ?? 0);
+    if (rules.bounds !== undefined && !aabbContains(rules.bounds, aabb)) {
+        return { status: "rejected", reason: "out-of-bounds" };
+    }
+    const obstacles = rules.obstacles ?? [];
+    for (let index = 0; index < obstacles.length; index++) {
+        const obstacle = obstacles[index];
+        if (aabbOverlap(aabb, obstacle.aabb)) {
+            return { status: "rejected", reason: "overlap", obstacle, index };
+        }
+    }
+    return { status: "ok", center, aabb };
+}
+export function footprintObstacle(request, id) {
+    const aabb = footprintAabb(request.center, request.footprint, request.quarterTurns ?? 0);
+    return id === undefined ? { aabb } : { aabb, id };
+}

package/dist/world/regions.d.ts

@@ -0,0 +1,66 @@
+import type { WorldBounds } from "./features.js";
+import { type TerrainField } from "./terrain.js";
+export type Rgb = readonly [number, number, number];
+export type ColorInput = string | Rgb;
+export interface RegionHeight {
+    baseHeight: number;
+    amplitude: number;
+    frequency: number;
+    octaves?: number;
+    lacunarity?: number;
+    persistence?: number;
+    ridged?: boolean;
+}
+/**
+ * A content-agnostic region. The engine blends `height` and the visual/physical
+ * knobs (`tint`, `water`, `fog`, `speedMultiplier`, …) across region borders and
+ * selects the dominant region by nearest center in `selector` space. `data` is an
+ * opaque payload the engine never inspects — games hang their own content off it
+ * (spawn tables, prop palettes, structure ids, names, …).
+ */
+export interface RegionDef<T = unknown> {
+    id: string;
+    selector: readonly number[];
+    height: RegionHeight;
+    tint?: ColorInput;
+    steepTint?: ColorInput;
+    water?: ColorInput;
+    fog?: ColorInput;
+    fogDensity?: number;
+    speedMultiplier?: number;
+    data?: T;
+}
+export interface RegionSample<T = unknown> {
+    region: RegionDef<T>;
+    weight: number;
+    selector: readonly number[];
+    tint: Rgb;
+    steepTint: Rgb;
+    water: Rgb | null;
+    fog: Rgb | null;
+    fogDensity: number;
+    speedMultiplier: number;
+    data: T | undefined;
+}
+export interface RegionField<T = unknown> extends TerrainField {
+    sampleRegion(x: number, z: number): RegionSample<T>;
+    readonly regions: readonly RegionDef<T>[];
+    readonly seaLevel: number;
+    readonly seed: number;
+}
+export interface RegionFieldConfig<T = unknown> {
+    regions: readonly RegionDef<T>[];
+    seed?: number;
+    bounds?: WorldBounds;
+    seaLevel?: number;
+    /** Noise frequency per selector axis (defaults to 0.004 for every axis). */
+    selectorFrequencies?: readonly number[];
+    /** Per-axis distance weight when picking the nearest region (defaults to 1). */
+    axisWeights?: readonly number[];
+    /** Border sharpness; higher = tighter blends. */
+    sharpness?: number;
+    /** Domain-warp distance applied to selector sampling (0 disables). */
+    warp?: number;
+}
+export declare function createRegionField<T = unknown>(config: RegionFieldConfig<T>): RegionField<T>;
+export declare function isRegionField(field: TerrainField): field is RegionField;