@jgengine/core 0.10.0 → 0.12.0

package/dist/world/minimapBake.js

@@ -0,0 +1,208 @@
+import { pointInPolygon } from "./scatterRegion.js";
+/** The built-in height→color ramp and water color a bake uses when no palette override is given. */
+export const DEFAULT_MINIMAP_PALETTE = {
+    low: "#3f5d34",
+    high: "#cdbb93",
+    water: "#2f5d78",
+};
+function parseHex(hex) {
+    let value = hex.trim().replace(/^#/, "");
+    if (value.length === 3)
+        value = value.split("").map((c) => c + c).join("");
+    const int = Number.parseInt(value, 16);
+    if (!Number.isFinite(int) || value.length !== 6)
+        return { r: 0, g: 0, b: 0 };
+    return { r: (int >> 16) & 0xff, g: (int >> 8) & 0xff, b: int & 0xff };
+}
+function mix(a, b, t) {
+    const k = Math.max(0, Math.min(1, t));
+    return {
+        r: Math.round(a.r + (b.r - a.r) * k),
+        g: Math.round(a.g + (b.g - a.g) * k),
+        b: Math.round(a.b + (b.b - a.b) * k),
+    };
+}
+/**
+ * Rasterizes a top-down terrain image: height maps onto a low→high color ramp (normalized over the
+ * sampled height range), slope darkens the shade, water fills below `waterLevel`, and each zone
+ * polygon tints the ground it covers. Deterministic for a fixed source. The bounds are preserved so
+ * a player-centered minimap pans the image correctly.
+ * @capability minimap-bake rasterize authored terrain + zones into a top-down minimap image
+ */
+export function bakeMinimapImage(source, options = {}) {
+    const resolution = Math.max(8, Math.floor(options.resolution ?? 128));
+    const palette = { ...DEFAULT_MINIMAP_PALETTE, ...options.palette };
+    const low = parseHex(palette.low);
+    const high = parseHex(palette.high);
+    const water = parseHex(palette.water);
+    const { minX, minZ, maxX, maxZ } = source.bounds;
+    const spanX = Math.max(1e-6, maxX - minX);
+    const spanZ = Math.max(1e-6, maxZ - minZ);
+    // Longer world axis gets `resolution` pixels; the other keeps aspect.
+    const width = spanX >= spanZ ? resolution : Math.max(8, Math.round((spanX / spanZ) * resolution));
+    const height = spanZ >= spanX ? resolution : Math.max(8, Math.round((spanZ / spanX) * resolution));
+    const worldX = (px) => minX + ((px + 0.5) / width) * spanX;
+    const worldZ = (py) => minZ + ((py + 0.5) / height) * spanZ;
+    // First pass: height range for a stable ramp.
+    let hMin = Infinity;
+    let hMax = -Infinity;
+    const heights = new Float64Array(width * height);
+    for (let py = 0; py < height; py += 1) {
+        for (let px = 0; px < width; px += 1) {
+            const h = source.sampleHeight(worldX(px), worldZ(py));
+            heights[py * width + px] = h;
+            if (h < hMin)
+                hMin = h;
+            if (h > hMax)
+                hMax = h;
+        }
+    }
+    const hSpan = Math.max(1e-6, hMax - hMin);
+    const pixels = new Uint8ClampedArray(width * height * 4);
+    const zones = source.zones ?? [];
+    for (let py = 0; py < height; py += 1) {
+        for (let px = 0; px < width; px += 1) {
+            const wx = worldX(px);
+            const wz = worldZ(py);
+            const h = heights[py * width + px];
+            let color;
+            if (source.waterLevel !== undefined && h <= source.waterLevel) {
+                color = water;
+            }
+            else {
+                color = mix(low, high, (h - hMin) / hSpan);
+                if (source.sampleNormal !== undefined) {
+                    const n = source.sampleNormal(wx, wz);
+                    const shade = 0.62 + 0.38 * Math.max(0, Math.min(1, n[1]));
+                    color = { r: Math.round(color.r * shade), g: Math.round(color.g * shade), b: Math.round(color.b * shade) };
+                }
+            }
+            for (const zone of zones) {
+                if (pointInPolygon([wx, wz], zone.polygon)) {
+                    color = mix(color, parseHex(zone.color), zone.alpha ?? 0.5);
+                }
+            }
+            const index = (py * width + px) * 4;
+            pixels[index] = color.r;
+            pixels[index + 1] = color.g;
+            pixels[index + 2] = color.b;
+            pixels[index + 3] = 255;
+        }
+    }
+    return { width, height, pixels, bounds: { minX, minZ, maxX, maxZ } };
+}
+// --- Minimal pure PNG encoder (RGBA, stored/uncompressed DEFLATE) ------------------------------
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i += 1)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function adler32(bytes) {
+    let a = 1;
+    let b = 0;
+    for (let i = 0; i < bytes.length; i += 1) {
+        a = (a + bytes[i]) % 65521;
+        b = (b + a) % 65521;
+    }
+    return ((b << 16) | a) >>> 0;
+}
+/** Wraps raw bytes in a zlib stream using only stored (uncompressed) DEFLATE blocks. */
+function zlibStore(data) {
+    const blocks = [0x78, 0x01]; // zlib header (no compression)
+    let offset = 0;
+    while (offset < data.length) {
+        const chunk = Math.min(0xffff, data.length - offset);
+        const final = offset + chunk >= data.length ? 1 : 0;
+        blocks.push(final, chunk & 0xff, (chunk >> 8) & 0xff, ~chunk & 0xff, (~chunk >> 8) & 0xff);
+        for (let i = 0; i < chunk; i += 1)
+            blocks.push(data[offset + i]);
+        offset += chunk;
+    }
+    const checksum = adler32(data);
+    blocks.push((checksum >>> 24) & 0xff, (checksum >>> 16) & 0xff, (checksum >>> 8) & 0xff, checksum & 0xff);
+    return Uint8Array.from(blocks);
+}
+function chunk(type, data) {
+    const typeBytes = Uint8Array.from([...type].map((c) => c.charCodeAt(0)));
+    const body = new Uint8Array(typeBytes.length + data.length);
+    body.set(typeBytes, 0);
+    body.set(data, typeBytes.length);
+    const crc = crc32(body);
+    const out = new Uint8Array(4 + body.length + 4);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, data.length);
+    out.set(body, 4);
+    view.setUint32(4 + body.length, crc);
+    return out;
+}
+function base64(bytes) {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        out += chars[b0 >> 2];
+        out += chars[((b0 & 3) << 4) | (b1 >> 4)];
+        out += i + 1 < bytes.length ? chars[((b1 & 15) << 2) | (b2 >> 6)] : "=";
+        out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
+    }
+    return out;
+}
+/** Encodes an RGBA bake to raw PNG bytes (pure; stored DEFLATE, valid for any decoder). */
+export function encodeBakePng(bake) {
+    const { width, height, pixels } = bake;
+    const ihdr = new Uint8Array(13);
+    const ihdrView = new DataView(ihdr.buffer);
+    ihdrView.setUint32(0, width);
+    ihdrView.setUint32(4, height);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 6; // color type RGBA
+    // 10,11,12 = compression/filter/interlace = 0
+    // Filtered scanlines: filter byte 0 (none) per row.
+    const raw = new Uint8Array(height * (1 + width * 4));
+    for (let y = 0; y < height; y += 1) {
+        const rowStart = y * (1 + width * 4);
+        raw[rowStart] = 0;
+        raw.set(pixels.subarray(y * width * 4, (y + 1) * width * 4), rowStart + 1);
+    }
+    const signature = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const parts = [
+        signature,
+        chunk("IHDR", ihdr),
+        chunk("IDAT", zlibStore(raw)),
+        chunk("IEND", new Uint8Array(0)),
+    ];
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/**
+ * Encodes a bake as a `data:image/png;base64,...` URI — the exact string the `Minimap` /
+ * `WorldMap` `background` prop takes. Deterministic for a fixed bake.
+ * @capability minimap-bake encode a baked minimap as a PNG data URI for the Minimap background
+ */
+export function minimapBakeToPngDataUri(bake) {
+    return `data:image/png;base64,${base64(encodeBakePng(bake))}`;
+}
+/** One-call convenience: rasterize a source and return `{ background, mapBounds }` for a minimap. */
+export function bakeMinimapBackground(source, options = {}) {
+    const bake = bakeMinimapImage(source, options);
+    return { background: minimapBakeToPngDataUri(bake), mapBounds: bake.bounds };
+}

package/dist/world/minimapTrack.d.ts

@@ -0,0 +1,17 @@
+import type { WorldXZ } from "./minimap.js";
+/** A world-space segment defining a linear "track" minimap — points are projected onto the `from`→`to` axis. */
+export interface TrackAxis {
+    from: WorldXZ;
+    to: WorldXZ;
+}
+/**
+ * Project a world point onto the `from`→`to` segment of `axis` and return the
+ * clamped 0..1 fraction of how far along the track it lies (0 at `from`, 1 at
+ * `to`). The linear analogue of `projectToMinimap` — feeds a horizontal
+ * corridor/route progress rail. Accepts XZ (`[x, z]`) or XYZ (`[x, y, z]`)
+ * points (index 0 = x, index 2 when length 3 else index 1 = z). A zero-length
+ * axis returns 0.
+ *
+ * @capability minimap-track project a world point to a 0..1 fraction along a linear track axis
+ */
+export declare function trackFraction(point: WorldXZ | readonly [number, number, number], axis: TrackAxis): number;

package/dist/world/minimapTrack.js

@@ -0,0 +1,22 @@
+/**
+ * Project a world point onto the `from`→`to` segment of `axis` and return the
+ * clamped 0..1 fraction of how far along the track it lies (0 at `from`, 1 at
+ * `to`). The linear analogue of `projectToMinimap` — feeds a horizontal
+ * corridor/route progress rail. Accepts XZ (`[x, z]`) or XYZ (`[x, y, z]`)
+ * points (index 0 = x, index 2 when length 3 else index 1 = z). A zero-length
+ * axis returns 0.
+ *
+ * @capability minimap-track project a world point to a 0..1 fraction along a linear track axis
+ */
+export function trackFraction(point, axis) {
+    const px = point[0];
+    const pz = point.length === 3 ? point[2] : point[1];
+    const ax = axis.to[0] - axis.from[0];
+    const az = axis.to[1] - axis.from[1];
+    const lengthSq = ax * ax + az * az;
+    if (lengthSq === 0)
+        return 0;
+    const dot = (px - axis.from[0]) * ax + (pz - axis.from[1]) * az;
+    const fraction = dot / lengthSq;
+    return fraction < 0 ? 0 : fraction > 1 ? 1 : fraction;
+}

package/dist/world/pathInstances.d.ts

@@ -0,0 +1,27 @@
+/** One placed transform along a path: grounded position, facing yaw, and its ordinal + arc distance. */
+export interface PathInstance {
+    index: number;
+    /** Arc-length distance from the path start, meters. */
+    distance: number;
+    position: readonly [number, number, number];
+    /** Yaw (radians) facing along the direction of travel. */
+    yaw: number;
+}
+/** Options for {@link placeAlongPath}. */
+export interface PlaceAlongPathOptions {
+    /** Target meters between instances. The run is divided into equal spans nearest this spacing. */
+    spacing: number;
+    /** Ground each instance to this height sampler (else y = 0). */
+    sampleHeight?: (x: number, z: number) => number;
+    /** Force at least this many instances regardless of length. Default 1 (endpoints only when short). */
+    minCount?: number;
+}
+/**
+ * Evenly place transforms along `points` (XZ polyline). The run length is divided into the whole
+ * number of equal spans closest to `spacing`, so instances always land on both endpoints and stay
+ * evenly distributed. Returns `spans + 1` instances. Empty for fewer than 2 points.
+ */
+export declare function placeAlongPath(points: readonly {
+    x: number;
+    z: number;
+}[], options: PlaceAlongPathOptions): PathInstance[];

package/dist/world/pathInstances.js

@@ -0,0 +1,27 @@
+import { pointAtDistance, polyline, tangentAtDistance } from "./polyline.js";
+/**
+ * Evenly place transforms along `points` (XZ polyline). The run length is divided into the whole
+ * number of equal spans closest to `spacing`, so instances always land on both endpoints and stay
+ * evenly distributed. Returns `spans + 1` instances. Empty for fewer than 2 points.
+ */
+export function placeAlongPath(points, options) {
+    if (points.length < 2)
+        return [];
+    const line = polyline(points.map((point) => [point.x, point.z]));
+    const total = line.length;
+    if (total <= 0)
+        return [];
+    const spacing = Math.max(0.01, options.spacing);
+    const minSpans = Math.max(1, (options.minCount ?? 1) - 1);
+    const spans = Math.max(minSpans, Math.round(total / spacing), 1);
+    const step = total / spans;
+    const out = [];
+    for (let i = 0; i <= spans; i += 1) {
+        const distance = i * step;
+        const [x, z] = pointAtDistance(line, distance);
+        const [tx, tz] = tangentAtDistance(line, Math.min(distance, total - 1e-4));
+        const y = options.sampleHeight?.(x, z) ?? 0;
+        out.push({ index: i, distance, position: [x, y, z], yaw: Math.atan2(tx, tz) });
+    }
+    return out;
+}

package/dist/world/pathNetwork.d.ts

@@ -0,0 +1,159 @@
+/** A path vertex in the volume-local XZ frame. */
+export type PathVec2 = readonly [number, number];
+/** Road hierarchy, widest to narrowest — shared by the city fabric and the renderer. */
+export type PathLevel = "boulevard" | "avenue" | "street" | "lane";
+/** A path feature spanning part of an edge/street: a bridge deck over a gap or a tunnel bore under a ridge. */
+export type PathFeatureKind = "bridge" | "tunnel";
+/** The generator's chosen topology family: an open street `net`, or a closed `circuit` loop. */
+export type PathNetworkMode = "net" | "circuit";
+/** One graph node: a junction, a dead end, or a mid-street bend, with its connection count. */
+export interface PathNode {
+    id: number;
+    x: number;
+    z: number;
+    degree: number;
+}
+/** One atomic node-to-node edge — the fabric graph consumes these (welds at shared node coords). */
+export interface PathEdge {
+    id: number;
+    /** Endpoint node ids. */
+    a: number;
+    b: number;
+    /** Sampled centerline; `points[0]` sits exactly on node `a`, the last on node `b`. */
+    points: PathVec2[];
+    width: number;
+    level: PathLevel;
+    /** True when this edge belongs to the main closed loop (circuit mode). */
+    loop: boolean;
+}
+/** A feature span carried by a street: a `[from, to]` index window into the street's `points`. */
+export interface PathFeatureSpan {
+    kind: PathFeatureKind;
+    from: number;
+    to: number;
+    /** Ground height at each bank/portal — the deck/floor reference the renderer drapes to. */
+    bankHeight: number;
+}
+/** One chained through-street: a maximal run of edges through degree-2 nodes, for rendering + furniture. */
+export interface PathStreet {
+    id: number;
+    /** Ordered node ids the chain visits; first === last when `loop`. */
+    nodes: number[];
+    /** Smoothed, turn-clamped centerline. */
+    points: PathVec2[];
+    width: number;
+    level: PathLevel;
+    /** Closed chain (a circuit lap or an inner ring). */
+    loop: boolean;
+    /** Cul-de-sac turning bulb when the street ends at a dangling node. */
+    bulb?: PathVec2;
+    /** Bridge/tunnel spans along this street, if any. */
+    features: PathFeatureSpan[];
+}
+/** One crossing of three or more streets: patch center/radius plus outgoing arm directions. */
+export interface PathJunction {
+    x: number;
+    z: number;
+    radius: number;
+    level: PathLevel;
+    /** Outgoing arm directions (radians) with the crossing street width, for crosswalks/patches. */
+    arms: {
+        angle: number;
+        width: number;
+    }[];
+}
+/** One dangling street end kept as a cul-de-sac: node position plus the heading pointing off the road. */
+export interface PathDeadEnd {
+    node: number;
+    x: number;
+    z: number;
+    /** Yaw (radians) facing outward, away from the network. */
+    heading: number;
+    width: number;
+}
+/** A resolved path feature in world-of-the-volume space: a bridge deck or tunnel bore centerline. */
+export interface PathFeature {
+    kind: PathFeatureKind;
+    points: PathVec2[];
+    width: number;
+    bankHeight: number;
+}
+/** The fully-resolved network in volume-local coords. */
+export interface PathNetwork {
+    mode: PathNetworkMode;
+    nodes: PathNode[];
+    /** Atomic edges — feed to the block/parcel fabric. */
+    edges: PathEdge[];
+    /** Chained through-streets — feed to the renderer, furniture, and analysis. */
+    streets: PathStreet[];
+    junctions: PathJunction[];
+    deadEnds: PathDeadEnd[];
+    bridges: PathFeature[];
+    tunnels: PathFeature[];
+    /** Independent cycle count (E − V + components): 0 = pure tree, ≥1 = has loops. */
+    loops: number;
+}
+/** Fully-defaulted slider set the generator reads. */
+export interface PathNetworkRules {
+    seed: string;
+    /** 1 = regular lattice nodes; 0 = organic scatter. */
+    gridness: number;
+    /** 0 = tree (dead-ends); 1 = a single closed circuit. */
+    loopiness: number;
+    /** Extra chord edges between neighbors → mesh density. */
+    connectivity: number;
+    /** Spur-lane density forking off the mains. */
+    branching: number;
+    /** Fraction of dangling ends kept as cul-de-sacs (vs reconnected). */
+    deadEnds: number;
+    /** Target node spacing / block size, world units. */
+    segmentLength: number;
+    /** Cross-axis spacing multiplier (≥1 = long skinny Manhattan blocks). */
+    aspect: number;
+    /** Sideways wander amplitude, 0..1. */
+    winding: number;
+    /** Minimum curve radius (m) — caps wander curvature and corner tightness. */
+    minCurveRadius: number;
+    /** Shallowest corner (degrees) a street keeps — gentler bends are straightened. */
+    minTurnAngle: number;
+    /** Sharpest corner (degrees) a street may take — tighter ones are beveled away. */
+    maxTurnAngle: number;
+    /** Base street width; the hierarchy scales off it. */
+    width: number;
+    /** Share of avenues upgraded to boulevards, 0..1. */
+    boulevards: number;
+}
+/** Ground sampler + feature toggles enabling bridges/tunnels; omit for a flat, feature-free network. */
+export interface PathNetworkContext {
+    /** Volume-local ground height sampler. */
+    heightAt?: (x: number, z: number) => number;
+    /** Ground below this (local) height is a gap streets bridge over. */
+    minElevation?: number;
+    /** Emit bridge decks over sub-`minElevation` gaps. */
+    bridges?: boolean;
+    /** Emit tunnel bores where the ground rises this far above a span's banks. */
+    tunnels?: boolean;
+    /** Ridge height above the banks that triggers a tunnel. Default 6. */
+    tunnelClearance?: number;
+}
+/**
+ * Hard turn-angle clamp on a polyline with fixed endpoints: interior corners gentler than `minRad`
+ * are straightened away (deliberate winding only, no micro-wiggle) and corners sharper than `maxRad`
+ * are beveled — the corner vertex is replaced by two points pulled back along each leg, which
+ * strictly reduces the angle. Endpoints never move, so a graph node stays welded.
+ * @internal
+ */
+export declare function clampTurns(points: readonly PathVec2[], minRad: number, maxRad: number): PathVec2[];
+/** Decide which topology family the sliders call for. Circuit wins when loops dominate and both
+ *  branching and mesh connectivity are low — exactly the "race track" corner of the slider space.
+ *  @internal */
+export declare function pathNetworkMode(rules: PathNetworkRules): PathNetworkMode;
+/**
+ * Resolve a full path network from its rules inside a volume of half-extents `hx`×`hz`. Deterministic
+ * per `(rules.seed, hx, hz, context)`. Pass a {@link PathNetworkContext} with a ground sampler to turn
+ * water gaps into bridges and ridges into tunnels. Coordinates are volume-local; the caller maps to
+ * world space.
+ *
+ * @capability path-network build a deterministic road/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+ */
+export declare function buildPathNetwork(rules: PathNetworkRules, hx: number, hz: number, context?: PathNetworkContext): PathNetwork;