@jgengine/core 0.10.0 → 0.12.0

package/dist/world/placementController.d.ts

@@ -65,5 +65,11 @@ export interface PlacementController {
     commit(): PlacementCommit | null;
     reset(): void;
 }
+/** Maps 0–3 quarter turns onto radians for ghost/commit rotation. */
 export declare function quarterTurnsToRotationY(quarterTurns: number): number;
+/**
+ * Headless placement ghost: hover → valid/invalid preview, rotate, grid/free/surface snap, commit.
+ * Pair with `@jgengine/shell/structures` `PlacementGhost` and {@link placeAssetFromCommit}.
+ * @capability placement-controller interactive build-mode ghost preview and commit
+ */
 export declare function createPlacementController(config: PlacementControllerConfig): PlacementController;

package/dist/world/placementController.js

@@ -5,10 +5,16 @@ const DEFAULT_SLOT_RADIUS = 1.5;
 function distanceVec3(a, b) {
     return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 }
+/** Maps 0–3 quarter turns onto radians for ghost/commit rotation. */
 export function quarterTurnsToRotationY(quarterTurns) {
     const turns = ((quarterTurns % 4) + 4) % 4;
     return turns === 0 ? 0 : -turns * (Math.PI / 2);
 }
+/**
+ * Headless placement ghost: hover → valid/invalid preview, rotate, grid/free/surface snap, commit.
+ * Pair with `@jgengine/shell/structures` `PlacementGhost` and {@link placeAssetFromCommit}.
+ * @capability placement-controller interactive build-mode ghost preview and commit
+ */
 export function createPlacementController(config) {
     let footprint = config.footprint;
     let rules = config.rules ?? {};

package/dist/world/poleLineKind.d.ts

@@ -0,0 +1,40 @@
+import { type Vec3 } from "./catenary.js";
+import { type ParamSchema, type ParsedParams, type SceneKindObject, type SceneKindResolveContext } from "../scene/sceneKinds.js";
+/**
+ * The editor path kind marking a polyline as a pole/cable run.
+ * @capability pole-line editor-authorable poles + sagging cables along a path
+ */
+export declare const POLE_LINE_KIND = "pole_line";
+/** One placed pole: grounded base position plus facing yaw along the run. */
+export interface Pole {
+    id: string;
+    position: Vec3;
+    yaw: number;
+}
+/** One resolved cable span: a point string to loft into a tube, plus its radius. */
+export interface Cable {
+    id: string;
+    points: Vec3[];
+    radius: number;
+}
+/** The renderable payload the resolver returns and the shell renderer consumes. */
+export interface ResolvedPoleLine {
+    poles: Pole[];
+    cables: Cable[];
+    poleHeight: number;
+    poleAsset: string;
+    /** Wires per span — drives the renderer's crossarm width and insulator count. */
+    wireCount: number;
+    /** Lateral spread between adjacent wires, meters — the renderer hangs insulators at these offsets. */
+    wireSpacing: number;
+}
+/** The pole-line parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export declare const POLE_LINE_SCHEMA: ParamSchema;
+/**
+ * Resolve poles + cables from a document object's points and parsed params. Poles come from the
+ * generic `placeAlongPath` sampler; between each consecutive pair, `wireCount` parallel cables are
+ * strung with lateral offset and quadratic-Bézier `sag` (deeper on longer spans). Pure data.
+ */
+export declare function resolvePoleLine(object: SceneKindObject, params: ParsedParams, context?: SceneKindResolveContext): ResolvedPoleLine;
+/** Registers the pole-line scene kind (schema + resolver + inspector note). Called by `registerBuiltinSceneKinds`. @internal */
+export declare function registerPoleLineKind(): void;

package/dist/world/poleLineKind.js

@@ -0,0 +1,97 @@
+/**
+ * `pole_line` studio: poles + sagging cables strung along an editor-drawn path — power lines, fences,
+ * streetlight runs, ziplines. Pure config here (spacing/height/wire params + a resolver built from the
+ * generic `placeAlongPath` and `sagCurve` primitives); the instanced pole/cable meshes live in the
+ * `shell` renderer. An engine environment kind (like water/grass_field/soil) so wire runs are
+ * drawable and slider-authorable in every editor session and persisted in `editor.scene.json` —
+ * promoted from `examples/studios` for studio/editor parity (#1101).
+ */
+import { placeAlongPath } from "./pathInstances.js";
+import { sagCurve } from "./catenary.js";
+import { registerSceneKind, } from "../scene/sceneKinds.js";
+/**
+ * The editor path kind marking a polyline as a pole/cable run.
+ * @capability pole-line editor-authorable poles + sagging cables along a path
+ */
+export const POLE_LINE_KIND = "pole_line";
+/** The pole-line parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export const POLE_LINE_SCHEMA = {
+    fields: [
+        { type: "text", key: "poleAsset", label: "pole asset", default: "", group: "poles" },
+        { type: "range", key: "spacing", label: "spacing", min: 2, max: 40, step: 0.5, default: 8, unit: "m", group: "poles" },
+        { type: "range", key: "poleHeight", label: "pole height", min: 1, max: 20, step: 0.25, default: 6, unit: "m", group: "poles" },
+        { type: "bool", key: "snapToTerrain", label: "snap to ground", default: true, group: "poles" },
+        { type: "action", key: "randomizePoles", label: "randomize poles", action: "randomize", group: "poles" },
+        { type: "range", key: "wireCount", label: "wires", min: 0, max: 8, step: 1, default: 3, group: "cables" },
+        { type: "range", key: "wireSpacing", label: "wire spread", min: 0, max: 3, step: 0.05, default: 0.5, unit: "m", group: "cables" },
+        { type: "range", key: "cableRadius", label: "cable radius", min: 0.01, max: 0.5, step: 0.01, default: 0.05, unit: "m", group: "cables" },
+        { type: "range", key: "sag", label: "sag", min: 0, max: 6, step: 0.1, default: 0.8, unit: "m", group: "cables" },
+        { type: "range", key: "sagPerMeter", label: "sag / m", min: 0, max: 0.3, step: 0.005, default: 0.04, group: "cables" },
+        { type: "range", key: "cableSegments", label: "cable smoothness", min: 2, max: 48, step: 1, default: 12, group: "cables" },
+        { type: "seed", key: "seed", label: "seed", default: "", group: "cables" },
+        { type: "action", key: "randomizeCables", label: "randomize cables", action: "randomize", group: "cables" },
+    ],
+    groups: [
+        { id: "poles", label: "Poles" },
+        { id: "cables", label: "Cables" },
+    ],
+};
+/**
+ * Resolve poles + cables from a document object's points and parsed params. Poles come from the
+ * generic `placeAlongPath` sampler; between each consecutive pair, `wireCount` parallel cables are
+ * strung with lateral offset and quadratic-Bézier `sag` (deeper on longer spans). Pure data.
+ */
+export function resolvePoleLine(object, params, context) {
+    const spacing = params["spacing"];
+    const poleHeight = params["poleHeight"];
+    const wireCount = Math.round(params["wireCount"]);
+    const wireSpacing = params["wireSpacing"];
+    const cableRadius = params["cableRadius"];
+    const sag = params["sag"];
+    const sagPerMeter = params["sagPerMeter"];
+    const cableSegments = Math.round(params["cableSegments"]);
+    const snap = params["snapToTerrain"];
+    const placed = placeAlongPath(object.points ?? [], {
+        spacing,
+        ...(snap && context?.sampleHeight !== undefined ? { sampleHeight: context.sampleHeight } : {}),
+    });
+    const poles = placed.map((instance) => ({ id: `${object.id}/pole/${instance.index}`, position: instance.position, yaw: instance.yaw }));
+    const cables = [];
+    if (wireCount > 0) {
+        for (let i = 0; i + 1 < poles.length; i += 1) {
+            const a = poles[i];
+            const b = poles[i + 1];
+            const dx = b.position[0] - a.position[0];
+            const dz = b.position[2] - a.position[2];
+            const span = Math.hypot(dx, dz) || 1;
+            const perpX = -dz / span;
+            const perpZ = dx / span;
+            const drop = sag + sagPerMeter * span;
+            const half = (wireCount - 1) / 2;
+            for (let w = 0; w < wireCount; w += 1) {
+                const offset = (w - half) * wireSpacing;
+                const topA = [a.position[0] + perpX * offset, a.position[1] + poleHeight, a.position[2] + perpZ * offset];
+                const topB = [b.position[0] + perpX * offset, b.position[1] + poleHeight, b.position[2] + perpZ * offset];
+                cables.push({ id: `${object.id}/cable/${i}/${w}`, points: sagCurve(topA, topB, drop, cableSegments), radius: cableRadius });
+            }
+        }
+    }
+    return { poles, cables, poleHeight, poleAsset: params["poleAsset"], wireCount, wireSpacing };
+}
+/** Registers the pole-line scene kind (schema + resolver + inspector note). Called by `registerBuiltinSceneKinds`. @internal */
+export function registerPoleLineKind() {
+    registerSceneKind({
+        kind: POLE_LINE_KIND,
+        target: "path",
+        label: "Pole line / cables",
+        pathShape: "line",
+        addCategory: "Studios",
+        accent: "#fbbf24",
+        schema: POLE_LINE_SCHEMA,
+        resolve: (object, params, context) => resolvePoleLine(object, params, context),
+        note: (object, params) => {
+            const resolved = resolvePoleLine(object, params);
+            return `${resolved.poles.length} poles · ${resolved.cables.length} cables`;
+        },
+    });
+}

package/dist/world/polyline.d.ts

@@ -0,0 +1,34 @@
+import type { Vec2 } from "./geometry.js";
+/** A polyline prepared for repeated distance/fraction sampling, with cumulative arc-length precomputed. */
+export interface Polyline {
+    readonly points: readonly Vec2[];
+    readonly cumulative: readonly number[];
+    readonly length: number;
+}
+/** The closest point on a polyline to a query point, with where it lands along the line. */
+export interface PolylineHit {
+    readonly point: Vec2;
+    readonly distanceAlong: number;
+    readonly segment: number;
+    readonly lateral: number;
+}
+/** Prepare a polyline from ordered points, computing cumulative arc-length once for O(log n) sampling.
+ * @internal
+ */
+export declare function polyline(points: readonly Vec2[]): Polyline;
+/** Point at an absolute arc-length distance along the line, clamped to the endpoints.
+ * @internal
+ */
+export declare function pointAtDistance(line: Polyline, dist: number): Vec2;
+/** Point at a `[0, 1]` fraction of the line's total length.
+ * @internal
+ */
+export declare function pointAtFraction(line: Polyline, fraction: number): Vec2;
+/** Unit tangent (direction of travel) at an absolute distance along the line.
+ * @internal
+ */
+export declare function tangentAtDistance(line: Polyline, dist: number): Vec2;
+/** Closest point on the line to `query`, reporting arc-length position, segment index, and signed lateral offset.
+ * @internal
+ */
+export declare function closestPoint(line: Polyline, query: Vec2): PolylineHit;

package/dist/world/polyline.js

@@ -0,0 +1,88 @@
+import { distance, lerp, normalize, perp, sub } from "./vec2.js";
+/** Prepare a polyline from ordered points, computing cumulative arc-length once for O(log n) sampling.
+ * @internal
+ */
+export function polyline(points) {
+    const cumulative = [0];
+    for (let i = 1; i < points.length; i += 1) {
+        cumulative.push(cumulative[i - 1] + distance(points[i - 1], points[i]));
+    }
+    return { points, cumulative, length: cumulative[cumulative.length - 1] ?? 0 };
+}
+function segmentAt(line, dist) {
+    const { cumulative } = line;
+    const clamped = dist < 0 ? 0 : dist > line.length ? line.length : dist;
+    let lo = 1;
+    let hi = cumulative.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (cumulative[mid] < clamped)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const start = cumulative[lo - 1];
+    const span = cumulative[lo] - start;
+    return { index: lo, t: span <= 0 ? 0 : (clamped - start) / span };
+}
+/** Point at an absolute arc-length distance along the line, clamped to the endpoints.
+ * @internal
+ */
+export function pointAtDistance(line, dist) {
+    if (line.points.length === 0)
+        return [0, 0];
+    if (line.points.length === 1)
+        return line.points[0];
+    const { index, t } = segmentAt(line, dist);
+    return lerp(line.points[index - 1], line.points[index], t);
+}
+/** Point at a `[0, 1]` fraction of the line's total length.
+ * @internal
+ */
+export function pointAtFraction(line, fraction) {
+    return pointAtDistance(line, fraction * line.length);
+}
+/** Unit tangent (direction of travel) at an absolute distance along the line.
+ * @internal
+ */
+export function tangentAtDistance(line, dist) {
+    if (line.points.length < 2)
+        return [0, 1];
+    const { index } = segmentAt(line, dist);
+    return normalize(sub(line.points[index], line.points[index - 1]));
+}
+/** Closest point on the line to `query`, reporting arc-length position, segment index, and signed lateral offset.
+ * @internal
+ */
+export function closestPoint(line, query) {
+    const { points, cumulative } = line;
+    if (points.length === 0)
+        return { point: [0, 0], distanceAlong: 0, segment: 0, lateral: 0 };
+    if (points.length === 1) {
+        return { point: points[0], distanceAlong: 0, segment: 0, lateral: distance(points[0], query) };
+    }
+    let best = { point: points[0], distanceAlong: 0, segment: 0, lateral: Infinity };
+    // Track the unsigned nearest distance separately: `best.lateral` carries a *signed* offset for
+    // the caller, so comparing the next candidate's unsigned distance against it would freeze the
+    // search the moment a negative-side segment lands (unsigned >= 0 never beats a stored negative).
+    let bestDistance = Infinity;
+    for (let i = 1; i < points.length; i += 1) {
+        const a = points[i - 1];
+        const b = points[i];
+        const abx = b[0] - a[0];
+        const aby = b[1] - a[1];
+        const segLenSq = abx * abx + aby * aby;
+        const t = segLenSq <= 0 ? 0 : Math.max(0, Math.min(1, ((query[0] - a[0]) * abx + (query[1] - a[1]) * aby) / segLenSq));
+        const point = [a[0] + abx * t, a[1] + aby * t];
+        const lateral = distance(point, query);
+        if (lateral < bestDistance) {
+            bestDistance = lateral;
+            const along = cumulative[i - 1] + t * Math.sqrt(segLenSq);
+            const unit = normalize([abx, aby]);
+            const normal = perp(unit);
+            const side = Math.sign(normal[0] * (query[0] - point[0]) + normal[1] * (query[1] - point[1]));
+            best = { point, distanceAlong: along, segment: i - 1, lateral: lateral * (side === 0 ? 1 : side) };
+        }
+    }
+    return best;
+}

package/dist/world/resourceNode.d.ts

@@ -0,0 +1,109 @@
+/** A quantity that is either fixed or a uniformly sampled `[min, max]` range resolved by the field rng. */
+export type Quantity = number | readonly [number, number];
+/** One resource kind a node can yield and its base per-harvest amount (before tool bias and harvester multiplier). */
+export interface ResourceYield {
+    /** Generic resource kind id — "wood", "ore", "fiber", "hide". The field never interprets it. */
+    kind: string;
+    /** Base amount granted per harvest hit; a `[min, max]` range samples deterministic variance from the field rng. */
+    amount: Quantity;
+}
+/** A harvestable node definition: a finite budget, the resources it yields, and how it respawns. */
+export interface ResourceNodeDef {
+    id: string;
+    /** Total harvestable budget (hit points / finite quantity). Each harvest consumes the tool's `power`. */
+    budget: number;
+    /** Resource kinds this node can yield; a tool's bias selects and scales among them. */
+    resources: readonly ResourceYield[];
+    /** Seconds to refill after depletion. Omit for a node that never respawns (a one-shot deposit). */
+    respawn?: number;
+    /** Budget restored on respawn; defaults to `budget`. */
+    respawnBudget?: number;
+}
+/**
+ * How a tool extracts from a node — its per-hit power and per-resource yield bias. Two profiles over the
+ * same multi-resource node return different resources and amounts: the generic pick-vs-hatchet mechanic.
+ */
+export interface ToolProfile {
+    /** Budget consumed per harvest hit; defaults to 1. Clamped to the node's remaining budget. */
+    power?: number;
+    /** Per-resource-kind yield multiplier. A kind absent here falls back to `defaultBias`. */
+    biases?: Readonly<Record<string, number>>;
+    /** Multiplier for resource kinds not listed in `biases`; defaults to 1 (set 0 for a tool that only extracts listed kinds). */
+    defaultBias?: number;
+}
+/** Options for a single harvest. */
+export interface HarvestOptions {
+    /** Scalar applied to every granted amount — a stronger creature/harvester yields more; defaults to 1. */
+    multiplier?: number;
+}
+/** One resource kind granted by a harvest and its resolved amount. */
+export interface ResourceGrant {
+    kind: string;
+    amount: number;
+}
+/** Outcome of one harvest attempt. */
+export interface HarvestResult {
+    nodeId: string;
+    /** Resources granted this harvest; empty when the node was already depleted or the tool extracted nothing. */
+    granted: readonly ResourceGrant[];
+    /** Budget actually consumed (0 when the node was already depleted). */
+    spent: number;
+    /** Whether the node still had budget and produced a harvest. */
+    harvested: boolean;
+    /** Whether this harvest reduced the node to empty. */
+    depleted: boolean;
+}
+/** Serializable per-node runtime state — round-trips through save/load and multiplayer sync. */
+export interface ResourceNodeState {
+    id: string;
+    /** Remaining budget. */
+    budget: number;
+    /** Budget the node refills to on respawn — the nominal "full" value for `fraction`. */
+    maxBudget: number;
+    depleted: boolean;
+    /** Seconds remaining until respawn; 0 when full or when the node never respawns. */
+    respawnTimer: number;
+    /** Explicit respawn-block flag (a structure claimed the spot); OR-ed with the field's suppression predicate. */
+    respawnBlocked: boolean;
+    /** 0..1 remaining fraction of `maxBudget`. */
+    fraction: number;
+}
+/** Construction options for {@link createResourceNodeField}: node definitions and an optional RNG/suppression hook. */
+export interface ResourceNodeFieldConfig {
+    nodes: readonly ResourceNodeDef[];
+    /** Injected [0,1) generator for deterministic yield variance; defaults to `Math.random`. */
+    rng?: () => number;
+    /**
+     * Freeze respawn for a node while this returns true — a structure within radius, a nearby occupant.
+     * Consulted every tick alongside the per-node `respawnBlocked` flag (either one suppresses).
+     */
+    respawnSuppressed?: (state: ResourceNodeState) => boolean;
+}
+/** A set of harvestable nodes: harvest with tool profiles, tick respawn timers, snapshot/hydrate for save-load. */
+export interface ResourceNodeField {
+    /** Apply one harvest hit with `tool`; returns the granted resources and decrements the node's budget. */
+    harvest(nodeId: string, tool: ToolProfile, options?: HarvestOptions): HarvestResult;
+    /** Count down respawn timers by `dt`; refill any node whose timer elapses and is not suppressed. */
+    tick(dt: number): void;
+    state(nodeId: string): ResourceNodeState;
+    isDepleted(nodeId: string): boolean;
+    /** Set the explicit respawn-block flag; persisted in state and honored by `tick`. */
+    setRespawnBlocked(nodeId: string, blocked: boolean): void;
+    ids(): readonly string[];
+    snapshot(): Record<string, ResourceNodeState>;
+    /** Restore mutable per-node state (budget, depletion, timers, block flag) from a {@link snapshot}. */
+    hydrate(snapshot: Record<string, ResourceNodeState>): void;
+}
+/**
+ * A field of depletable, respawning harvest nodes with tool-dependent yields — the generic rock / tree /
+ * bush / vein / corpse. Each node holds a finite budget across one or more resource kinds. A harvest applies
+ * a {@link ToolProfile} whose per-resource biases decide *which* resources and *how much* the same node
+ * returns (pick favors ore, hatchet favors wood), scaled by a creature/harvester multiplier and optional
+ * deterministic rng variance; the budget drops by the tool's power. When a node empties it starts a respawn
+ * timer that `tick(dt)` counts down and refills — unless respawn is suppressed by the per-node flag or the
+ * injected predicate (a structure claimed the spot). All state is plain and serializable for save-load and
+ * multiplayer sync via {@link snapshot}/{@link hydrate}.
+ *
+ * @capability resource-node depletable, respawning harvest nodes with tool-dependent yields
+ */
+export declare function createResourceNodeField(config: ResourceNodeFieldConfig): ResourceNodeField;

package/dist/world/resourceNode.js

@@ -0,0 +1,140 @@
+import { clamp } from "../math/scalar.js";
+function resolveQuantity(quantity, rng) {
+    if (typeof quantity === "number")
+        return quantity;
+    const [lo, hi] = quantity;
+    return lo + rng() * (hi - lo);
+}
+function toState(node) {
+    return {
+        id: node.def.id,
+        budget: node.budget,
+        maxBudget: node.maxBudget,
+        depleted: node.depleted,
+        respawnTimer: node.respawnTimer,
+        respawnBlocked: node.respawnBlocked,
+        fraction: node.maxBudget > 0 ? clamp(node.budget / node.maxBudget, 0, 1) : 0,
+    };
+}
+/**
+ * A field of depletable, respawning harvest nodes with tool-dependent yields — the generic rock / tree /
+ * bush / vein / corpse. Each node holds a finite budget across one or more resource kinds. A harvest applies
+ * a {@link ToolProfile} whose per-resource biases decide *which* resources and *how much* the same node
+ * returns (pick favors ore, hatchet favors wood), scaled by a creature/harvester multiplier and optional
+ * deterministic rng variance; the budget drops by the tool's power. When a node empties it starts a respawn
+ * timer that `tick(dt)` counts down and refills — unless respawn is suppressed by the per-node flag or the
+ * injected predicate (a structure claimed the spot). All state is plain and serializable for save-load and
+ * multiplayer sync via {@link snapshot}/{@link hydrate}.
+ *
+ * @capability resource-node depletable, respawning harvest nodes with tool-dependent yields
+ */
+export function createResourceNodeField(config) {
+    const rng = config.rng ?? Math.random;
+    const nodes = new Map();
+    const order = [];
+    for (const def of config.nodes) {
+        if (nodes.has(def.id))
+            throw new Error(`duplicate resource node "${def.id}"`);
+        const respawnBudget = def.respawnBudget ?? def.budget;
+        nodes.set(def.id, {
+            def,
+            budget: def.budget,
+            maxBudget: def.budget,
+            respawnBudget,
+            depleted: def.budget <= 0,
+            respawnTimer: 0,
+            respawnBlocked: false,
+        });
+        order.push(def.id);
+    }
+    const getNode = (id) => {
+        const node = nodes.get(id);
+        if (node === undefined)
+            throw new Error(`unknown resource node "${id}"`);
+        return node;
+    };
+    const isSuppressed = (node) => {
+        if (node.respawnBlocked)
+            return true;
+        if (config.respawnSuppressed === undefined)
+            return false;
+        return config.respawnSuppressed(toState(node));
+    };
+    return {
+        harvest(nodeId, tool, options = {}) {
+            const node = getNode(nodeId);
+            if (node.depleted || node.budget <= 0) {
+                return { nodeId, granted: [], spent: 0, harvested: false, depleted: node.depleted };
+            }
+            const power = tool.power !== undefined && tool.power > 0 ? tool.power : 1;
+            const spent = Math.min(power, node.budget);
+            const multiplier = options.multiplier ?? 1;
+            const defaultBias = tool.defaultBias ?? 1;
+            const granted = [];
+            for (const resource of node.def.resources) {
+                // Resolve variance for every resource so the rng stream stays independent of tool choice.
+                const base = resolveQuantity(resource.amount, rng);
+                const bias = tool.biases?.[resource.kind] ?? defaultBias;
+                const amount = base * bias * multiplier;
+                if (amount > 0)
+                    granted.push({ kind: resource.kind, amount });
+            }
+            node.budget -= spent;
+            let depleted = false;
+            if (node.budget <= 0) {
+                node.budget = 0;
+                node.depleted = true;
+                depleted = true;
+                node.respawnTimer = node.def.respawn ?? 0;
+            }
+            return { nodeId, granted, spent, harvested: true, depleted };
+        },
+        tick(dt) {
+            if (dt <= 0)
+                return;
+            for (const id of order) {
+                const node = nodes.get(id);
+                if (!node.depleted || node.def.respawn === undefined)
+                    continue;
+                if (isSuppressed(node))
+                    continue;
+                node.respawnTimer -= dt;
+                if (node.respawnTimer <= 0) {
+                    node.budget = node.respawnBudget;
+                    node.depleted = false;
+                    node.respawnTimer = 0;
+                }
+            }
+        },
+        state(nodeId) {
+            return toState(getNode(nodeId));
+        },
+        isDepleted(nodeId) {
+            return getNode(nodeId).depleted;
+        },
+        setRespawnBlocked(nodeId, blocked) {
+            getNode(nodeId).respawnBlocked = blocked;
+        },
+        ids() {
+            return order;
+        },
+        snapshot() {
+            const out = {};
+            for (const id of order)
+                out[id] = toState(nodes.get(id));
+            return out;
+        },
+        hydrate(snapshot) {
+            for (const id of order) {
+                const saved = snapshot[id];
+                if (saved === undefined)
+                    continue;
+                const node = nodes.get(id);
+                node.budget = saved.budget;
+                node.depleted = saved.depleted;
+                node.respawnTimer = saved.respawnTimer;
+                node.respawnBlocked = saved.respawnBlocked;
+            }
+        },
+    };
+}

package/dist/world/roads.d.ts

@@ -7,6 +7,14 @@ export interface RoadRibbon {
     /** Triangle indices into `positions`. */
     indices: Uint32Array;
 }
+/**
+ * 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 declare function roundPathCorners(points: readonly RoadPoint[], radius: number, cornerSegments?: number): RoadPoint[];
 /** Options for {@link buildRoadRibbon}. */
 export interface RoadRibbonOptions {
     /** Lift above the sampled ground so the ribbon never z-fights the terrain. Default 0.08. */

package/dist/world/roads.js

@@ -1,3 +1,41 @@
+/**
+ * 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) {

package/dist/world/scatter.js

@@ -1,4 +1,5 @@
 import { expandAabb, pointInAabb } from "./geometry.js";
+import { seededRng } from "../random/rng.js";
 function isAabb(area) {
     return (typeof area.minX === "number" &&
         typeof area.minZ === "number" &&
@@ -15,25 +16,6 @@ export function scatterAabb(area) {
     const halfD = area.d / 2;
     return { minX: cx - halfW, minZ: cz - halfD, maxX: cx + halfW, maxZ: cz + halfD };
 }
-function hashSeed(seed) {
-    const text = typeof seed === "number" ? seed.toString() : seed;
-    let h = 2166136261 >>> 0;
-    for (let i = 0; i < text.length; i++) {
-        h ^= text.charCodeAt(i);
-        h = Math.imul(h, 16777619);
-    }
-    return h >>> 0;
-}
-function mulberry32(state) {
-    let a = state >>> 0;
-    return () => {
-        a = (a + 0x6d2b79f5) >>> 0;
-        let t = a;
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    };
-}
 export function scatter(config) {
     const aabb = scatterAabb(config.area);
     const width = aabb.maxX - aabb.minX;
@@ -47,7 +29,7 @@ export function scatter(config) {
     const jitter = config.jitter ?? 1;
     const maxAttempts = config.maxAttempts ?? target * 30;
     const avoid = (config.avoid ?? []).map((a) => (avoidMargin !== 0 ? expandAabb(a, avoidMargin) : a));
-    const rng = mulberry32(hashSeed(config.seed ?? "scatter"));
+    const rng = seededRng(config.seed ?? "scatter");
     const useDistance = minDistance > 0;
     const buckets = new Map();
     const bucketKey = (x, z) => `${Math.floor(x / minDistance)}:${Math.floor(z / minDistance)}`;