@jgengine/core 0.9.0 → 0.11.0

package/dist/world/roads.js

@@ -0,0 +1,184 @@
+/**
+ * Fillets sharp corners of a centerline into short arcs so a ribbon built from it reads as a smooth
+ * road instead of overlapping/notching rectangles at each bend. Each interior vertex is replaced by a
+ * quadratic-bezier arc of `radius` (clamped to half the shorter adjacent segment) sampled at
+ * `cornerSegments` steps; endpoints and near-straight vertices pass through unchanged.
+ * @internal — the corner-smoothing behind `<AuthoredPaths>`; games get it for free through the render.
+ */
+export function roundPathCorners(points, radius, cornerSegments = 5) {
+    if (points.length < 3 || radius <= 0)
+        return points.map((point) => [point[0], point[1]]);
+    const out = [[points[0][0], points[0][1]]];
+    for (let i = 1; i < points.length - 1; i += 1) {
+        const a = points[i - 1];
+        const v = points[i];
+        const b = points[i + 1];
+        const ax = a[0] - v[0];
+        const az = a[1] - v[1];
+        const bx = b[0] - v[0];
+        const bz = b[1] - v[1];
+        const la = Math.hypot(ax, az) || 1;
+        const lb = Math.hypot(bx, bz) || 1;
+        const r = Math.min(radius, la / 2, lb / 2);
+        const p0 = [v[0] + (ax / la) * r, v[1] + (az / la) * r];
+        const p1 = [v[0] + (bx / lb) * r, v[1] + (bz / lb) * r];
+        out.push(p0);
+        for (let s = 1; s < cornerSegments; s += 1) {
+            const t = s / cornerSegments;
+            const u = 1 - t;
+            out.push([
+                u * u * p0[0] + 2 * u * t * v[0] + t * t * p1[0],
+                u * u * p0[1] + 2 * u * t * v[1] + t * t * p1[1],
+            ]);
+        }
+        out.push(p1);
+    }
+    out.push([points[points.length - 1][0], points[points.length - 1][1]]);
+    return out;
+}
+function subdividePath(path, maxLength) {
+    const out = [];
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        const steps = Math.max(1, Math.ceil(length / maxLength));
+        for (let s = 0; s < steps; s += 1) {
+            const t = s / steps;
+            out.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t]);
+        }
+    }
+    const last = path[path.length - 1];
+    if (last !== undefined)
+        out.push(last);
+    return out;
+}
+function normalAt(points, index) {
+    const prev = points[Math.max(0, index - 1)];
+    const next = points[Math.min(points.length - 1, index + 1)];
+    const dx = next[0] - prev[0];
+    const dz = next[1] - prev[1];
+    const length = Math.hypot(dx, dz) || 1;
+    return [-dz / length, dx / length];
+}
+/**
+ * Triangulate a road centerline into a ground-draped ribbon mesh: the polyline is subdivided,
+ * each vertex is offset half a `width` along the local perpendicular, and every vertex sits at
+ * `sampleHeight(x, z) + elevation`. Pure geometry — the shell (or any renderer) turns the result
+ * into a mesh, and tests can assert on it directly.
+ */
+export function buildRoadRibbon(path, width, sampleHeight, options = {}) {
+    const elevation = options.elevation ?? 0.08;
+    const maxSegmentLength = options.maxSegmentLength ?? 4;
+    if (path.length < 2 || width <= 0) {
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    }
+    const points = subdividePath(path, maxSegmentLength);
+    const half = width / 2;
+    const positions = new Float32Array(points.length * 6);
+    for (let i = 0; i < points.length; i += 1) {
+        const [x, z] = points[i];
+        const [nx, nz] = normalAt(points, i);
+        const lx = x + nx * half;
+        const lz = z + nz * half;
+        const rx = x - nx * half;
+        const rz = z - nz * half;
+        positions[i * 6] = lx;
+        positions[i * 6 + 1] = sampleHeight(lx, lz) + elevation;
+        positions[i * 6 + 2] = lz;
+        positions[i * 6 + 3] = rx;
+        positions[i * 6 + 4] = sampleHeight(rx, rz) + elevation;
+        positions[i * 6 + 5] = rz;
+    }
+    const indices = new Uint32Array((points.length - 1) * 6);
+    for (let i = 0; i < points.length - 1; i += 1) {
+        const a = i * 2;
+        indices[i * 6] = a;
+        indices[i * 6 + 1] = a + 1;
+        indices[i * 6 + 2] = a + 2;
+        indices[i * 6 + 3] = a + 1;
+        indices[i * 6 + 4] = a + 3;
+        indices[i * 6 + 5] = a + 2;
+    }
+    return { positions, indices };
+}
+/**
+ * Split a centerline into dash sub-polylines for lane markings: `dashLength` of painted line,
+ * `gapLength` of asphalt, repeated along the path's arc length. Feed each returned sub-path back
+ * through {@link buildRoadRibbon} with a thin width to mesh the dashes.
+ */
+export function dashSegments(path, dashLength = 3, gapLength = 3) {
+    if (path.length < 2 || dashLength <= 0 || gapLength < 0)
+        return [];
+    const cumulative = [0];
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        cumulative.push(cumulative[i] + Math.hypot(b[0] - a[0], b[1] - a[1]));
+    }
+    const total = cumulative[cumulative.length - 1];
+    if (total <= 0)
+        return [];
+    const pointAt = (s) => {
+        const clamped = Math.max(0, Math.min(total, s));
+        let index = 0;
+        while (index < cumulative.length - 2 && cumulative[index + 1] < clamped)
+            index += 1;
+        const a = path[index];
+        const b = path[index + 1];
+        const segLength = cumulative[index + 1] - cumulative[index];
+        const t = segLength <= 0 ? 0 : (clamped - cumulative[index]) / segLength;
+        return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+    };
+    const period = dashLength + gapLength;
+    const dashes = [];
+    for (let start = 0; start < total; start += period) {
+        const end = Math.min(total, start + dashLength);
+        if (end - start < 1e-6)
+            break;
+        dashes.push([pointAt(start), pointAt(end)]);
+        if (period <= 0)
+            break;
+    }
+    return dashes;
+}
+/**
+ * Closest-point query against a road centerline — the seam traffic AI, spawn placement, and
+ * "am I on the road" checks share. Returns null for a degenerate path.
+ */
+export function nearestOnPath(path, x, z) {
+    if (path.length < 2)
+        return null;
+    let best = null;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const abx = b[0] - a[0];
+        const abz = b[1] - a[1];
+        const lengthSq = abx * abx + abz * abz;
+        const t = lengthSq === 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / lengthSq));
+        const px = a[0] + abx * t;
+        const pz = a[1] + abz * t;
+        const distance = Math.hypot(x - px, z - pz);
+        if (best === null || distance < best.distance) {
+            const length = Math.sqrt(lengthSq) || 1;
+            best = { point: [px, pz], distance, tangent: [abx / length, abz / length] };
+        }
+    }
+    return best;
+}
+/** True when the query point lies within half the road `width` of the centerline. */
+export function isOnRoad(path, width, x, z) {
+    const sample = nearestOnPath(path, x, z);
+    return sample !== null && sample.distance <= width / 2;
+}
+/** Total arc length of a centerline in world units. */
+export function pathLength(path) {
+    let total = 0;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        total += Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    return total;
+}

package/dist/world/scatterRegion.d.ts

@@ -0,0 +1,164 @@
+import { type Aabb, type AvoidMasks, type AvoidZone, type Vec2 } from "./geometry.js";
+import type { SceneDocumentLike, ScenePathLike } from "./sceneShapes.js";
+import type { TerrainNormal } from "./terrain.js";
+/** The editor path kind that marks a closed polyline as a foliage/scatter region. */
+export declare const SCATTER_PATH_KIND = "scatter";
+/** One species/prop in a scatter region's palette, with a relative spawn weight. */
+export interface ScatterPaletteEntry {
+    item: string;
+    weight: number;
+}
+/** How a scatter region fills its polygon: density, spacing, variation, and masking rules. */
+export interface ScatterRegionRules {
+    /** Items per square meter across the region's footprint. */
+    density: number;
+    /** Minimum spacing between placements in meters; 0 allows clumping. */
+    minSpacing: number;
+    /** Seed string — same seed reproduces the same field. */
+    seed: string;
+    minScale: number;
+    maxScale: number;
+    /** Yaw range in radians applied per placement. */
+    minYaw: number;
+    maxYaw: number;
+    /** Lift every instance by this many meters off the ground. */
+    verticalOffset: number;
+    /** Orient instances to the terrain normal instead of straight up. */
+    alignToNormal: boolean;
+    /** Reject placements on ground steeper than this slope (rise/run); 0 disables. */
+    maxSlope: number;
+    minHeight: number;
+    maxHeight: number;
+    /** Thin placements out within this many meters of the region edge; 0 disables. */
+    edgeFalloff: number;
+    /** Grid jitter 0..1 — 0 is a rigid lattice, 1 fully scattered. */
+    jitter: number;
+    /** Weighted species palette; falls back to a single `grass` entry. */
+    palette: readonly ScatterPaletteEntry[];
+    /** Explicit no-scatter clearance discs this region always honors (manual exclusion). */
+    avoid: readonly AvoidZone[];
+    /** Honor document-wide clearance zones (tagged markers/paths) too; false = manual `avoid` only. */
+    autoAvoid: boolean;
+}
+/** Defaults a bare scatter region fills with: sparse grass, lightly spaced. */
+export declare const SCATTER_DEFAULTS: ScatterRegionRules;
+/** Default clearance radius (m) for an auto-avoided gameplay marker with no explicit `meta.clearance`. */
+export declare const DEFAULT_MARKER_CLEARANCE = 3.5;
+/** Marker/volume kinds that repel scatter and flatten terrain by default (spawns, objectives, vendors). */
+export declare const DEFAULT_CLEARANCE_KINDS: readonly string[];
+/** A resolvable scatter region: a closed polygon footprint plus its fill rules. */
+export interface ScatterRegion {
+    id: string;
+    polygon: readonly Vec2[];
+    rules: ScatterRegionRules;
+}
+/** A single placed scatter instance — grounded world position plus per-instance variation. */
+export interface ScatterInstance {
+    id: string;
+    regionId: string;
+    item: string;
+    x: number;
+    y: number;
+    z: number;
+    rotationY: number;
+    scale: number;
+    normal?: TerrainNormal;
+}
+/** Ground sampler a scatter resolve reads height/normal from (the sculpt terrain or the game's ground). */
+export interface ScatterTerrain {
+    sampleHeight(x: number, z: number): number;
+    sampleNormal(x: number, z: number): TerrainNormal;
+}
+/** Ray-casting point-in-polygon test on the XZ plane. */
+export declare function pointInPolygon(point: Vec2, polygon: readonly Vec2[]): boolean;
+/** Shortest distance from a point to a polygon's boundary. */
+export declare function distanceToPolygonEdge(point: Vec2, polygon: readonly Vec2[]): number;
+/** Axis-aligned bounds of a polygon, or null if it has no points. */
+export declare function polygonBounds(polygon: readonly Vec2[]): Aabb | null;
+/** Shoelace area of a polygon (always non-negative), in square meters. */
+export declare function polygonArea(polygon: readonly Vec2[]): number;
+/**
+ * Deterministic placements for one scatter region: scatter its polygon footprint at `density`
+ * items/m² (respecting `minSpacing`), clip to the polygon, thin near the edge, drop placements
+ * outside the slope/height mask, and derive item/scale/yaw from the region id + seed — so the same
+ * saved region always grows the same field. Grounds each instance on `terrain` when provided.
+ */
+export declare function resolveScatterRegion(region: ScatterRegion, terrain?: ScatterTerrain, avoid?: AvoidMasks): ScatterInstance[];
+/** Parses a scatter region's palette from meta: a weighted `palette` array, else a single `item`. */
+export declare function readScatterPalette(meta: Record<string, unknown> | undefined): ScatterPaletteEntry[];
+/** True when an editor path is a foliage/scatter region. */
+export declare function isScatterPath(path: ScenePathLike): boolean;
+/** The path's scatter rules with defaults filled in; null for non-scatter paths. */
+export declare function readScatterRules(path: ScenePathLike): ScatterRegionRules | null;
+/**
+ * Parses a region's manual clearance discs from `meta.avoid` (array of {x,z,radius,feather?}).
+ * @internal — used by `readScatterRules`; games author `avoid` through the region inspector.
+ */
+export declare function readAvoidZones(meta: Record<string, unknown> | undefined): AvoidZone[];
+/** Builds a resolvable {@link ScatterRegion} from a scatter path (XZ polygon + rules), or null. */
+export declare function scatterRegionFromPath(path: ScenePathLike): ScatterRegion | null;
+/** Estimated placement count for a scatter path — density × polygon area, for a live UI readout. */
+export declare function scatterRegionEstimate(path: ScenePathLike): {
+    area: number;
+    count: number;
+};
+/** Controls which gameplay objects auto-repel scatter (and, for markers, flatten terrain). */
+export interface ClearanceOptions {
+    /** Marker/volume/path kinds that auto-clear even without a `meta.clearance` tag. Default {@link DEFAULT_CLEARANCE_KINDS}. */
+    kinds?: readonly string[];
+    /** Restrict auto-clearing to these object ids only (any kind); overrides `kinds` when set. */
+    ids?: readonly string[];
+    /** Clearance radius (m) for a kind-matched object with no explicit tag. Default {@link DEFAULT_MARKER_CLEARANCE}. */
+    defaultClearance?: number;
+    /** Soft outer band (m) on every derived zone/corridor. Default 2. */
+    feather?: number;
+    /** Include a corridor along non-scatter paths (roads/routes) in {@link clearanceMasksFrom}. Default true. */
+    includePaths?: boolean;
+}
+/**
+ * Point-pad clearance **discs** from a document's markers/volumes — the terrain-flatten set (spawns,
+ * plots, POIs get a level pad). A marker/volume contributes a disc when it carries `meta.clearance`
+ * or its kind is in `kinds`. Paths are *not* included (they render draped, never flattened — see
+ * {@link clearanceMasksFrom} for their foliage corridor). Pass `ids`/`kinds` to scope it.
+ */
+export declare function clearanceZonesFrom(doc: SceneDocumentLike, options?: ClearanceOptions): AvoidZone[];
+/**
+ * The full clearance region for scatter avoidance: point-pad {@link clearanceZonesFrom} **discs**
+ * plus clean-edged **corridors** along non-scatter paths (each `halfWidth` = `path.width/2 +
+ * clearance`). Corridors give a straight tree-line along a road instead of a scalloped disc chain —
+ * this is what `resolveScatter` auto-avoids. Set `includePaths: false` to drop the path corridors.
+ * @internal — `resolveScatter` builds these automatically; games rarely call it directly.
+ */
+export declare function clearanceMasksFrom(doc: SceneDocumentLike, options?: ClearanceOptions): AvoidMasks;
+/** Extra inputs for {@link resolveScatter}: manual discs plus the auto-clearance toggle/scoping. */
+export interface ResolveScatterOptions extends ClearanceOptions {
+    /** Additional clearance discs applied to every region regardless of per-region `autoAvoid`. */
+    avoid?: readonly AvoidZone[];
+    /** Master switch for document-derived auto-clearance; false = per-region `avoid` (and `options.avoid`) only. */
+    autoAvoid?: boolean;
+}
+/**
+ * Every scatter region's placements across a document, grounded on `terrain` when provided. Regions
+ * honor clearance masks: their own manual `avoid` discs, plus (when the region's `autoAvoid` is on and
+ * `options.autoAvoid !== false`) the document-wide discs + path corridors from {@link clearanceMasksFrom}
+ * — so foliage auto-clears spawns, plots, and paths without hand-carving the polygon.
+ */
+export declare function resolveScatter(doc: SceneDocumentLike, terrain?: ScatterTerrain, options?: ResolveScatterOptions): ScatterInstance[];
+/** A spatial bucket of scatter instances — one draw unit the renderer can frustum-cull as a whole. */
+export interface ScatterChunk {
+    /** `gx:gz` grid key of the chunk. */
+    key: string;
+    /** Chunk minimum XZ corner in world space. */
+    min: Vec2;
+    /** Chunk edge length in meters. */
+    size: number;
+    instances: ScatterInstance[];
+}
+/**
+ * Buckets scatter instances into a uniform XZ grid of `chunkSize`-meter cells, so a dense region
+ * renders as many small draw units instead of one huge mesh — each chunk carries its own bounds and
+ * is frustum-culled independently, and offscreen chunks cost nothing. Empty chunks are omitted;
+ * order is deterministic (row-major by grid coordinate).
+ * @internal — the chunking behind the `InstancedScatter` renderer; not called directly by games.
+ */
+export declare function chunkScatterInstances(instances: readonly ScatterInstance[], chunkSize: number): ScatterChunk[];