@jgengine/core 0.11.0 → 0.12.0

package/dist/world/place.d.ts

@@ -0,0 +1,166 @@
+import type { PhysicsConfig } from "../game/defineGame.js";
+/**
+ * The place model: a world is the place you play in — substrate (ground) plus laws (physics,
+ * surface) — never a dressed diorama. Sky look, foliage scatter, props, and sculpt are content:
+ * they are authored in the editor (or by a content preset that writes into the scene document)
+ * and consumed through the authored-scene seams, not declared on the world.
+ *
+ * Hard rules the API enforces:
+ * - No `seed` anywhere in a world definition. Determinism comes from the runtime: the engine
+ *   derives generator/scatter seeds from the world `id` plus the save/run seed (see
+ *   {@link seedForPlace}), so the same place replays identically without the author owning RNG.
+ * - No sky, vegetation, or theme fields. A world with no authored sky renders the engine
+ *   default sky; "void"/"space" is content, not a world knob.
+ * - No genre or franchise presets. `generator` carries algorithm parameters only.
+ */
+/**
+ * Matter/feel laws of a place's ground that systems, physics, and audio read — restitution for a
+ * metal chamber the pieces ping off, stickiness for a slime pit, a soft felt mat. The same rule
+ * systems play on any surface; swapping the surface (plus content audio) changes the feel without
+ * forking the rules. This is place law, not a theme kit: visual/audio dressing stays in content.
+ */
+export interface SurfaceLaws {
+    /** Named matter of the ground ("metal", "slime", "felt", …) — a label systems and audio cues key off. */
+    matter?: string;
+    /** Sliding friction scalar, 0 (ice) … 1+ (grippy). Interpreted by movement/physics systems. */
+    friction?: number;
+    /** Bounce energy retention, 0 (dead stop) … 1 (perfect bounce). Interpreted by physics/board systems. */
+    restitution?: number;
+    /** Free-form serializable place-law traits game systems read (e.g. `{ stuckTurns: 1 }` for slime). */
+    traits?: Readonly<Record<string, number | string | boolean>>;
+}
+/** Serializable algorithm parameters for a procedural ground generator. Never a genre kit. */
+export interface GroundGenerator {
+    /** Algorithm identifier the game's generation system resolves (e.g. "fbm", "caves", "layers"). */
+    algorithm: string;
+    /**
+     * Algorithm tuning only — amplitudes, frequencies, thresholds, palettes of ids. Never a `seed`
+     * (the engine injects one from world id + save/run) and never a genre/franchise preset name.
+     */
+    params?: Readonly<Record<string, number | string | boolean>>;
+}
+/**
+ * Size of a `flat` ground: extents in world units. `Infinity` on an axis means unbounded — an
+ * endless plain needs no bounds number invented for it. `y` optionally bounds vertical play space.
+ */
+export interface FlatGroundSize {
+    x: number;
+    /** Optional vertical bound of the play volume; omit for open sky. */
+    y?: number;
+    z: number;
+    radius?: never;
+}
+/** Size of a `round` ground: the planet/sphere radius in world units. Nothing else. */
+export interface RoundGroundSize {
+    radius: number;
+    x?: never;
+    y?: never;
+    z?: never;
+}
+/** Size of a `voxel` ground: the generator's domain per axis; axes may be `Infinity` for streaming volumes. */
+export interface VoxelGroundSize {
+    x: number;
+    y: number;
+    z: number;
+    radius?: never;
+}
+/** Size of a `board` ground: a 2D surface you look at, in cells or layout units. */
+export interface BoardGroundSize {
+    x: number;
+    y: number;
+    z?: never;
+    radius?: never;
+}
+/** A 3D walkable plane/slab. `Infinity` axes are unbounded; no separate "infinite" mode exists. */
+export interface FlatGround {
+    mode: "flat";
+    size: FlatGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/** A planet/sphere you play on the outside of. Sized by `radius` only. */
+export interface RoundGround {
+    mode: "round";
+    size: RoundGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/** A procedural volume of blocks. `size` is the generator domain; `generator` is algorithm params only. */
+export interface VoxelGround {
+    mode: "voxel";
+    size: VoxelGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/**
+ * A 2D surface you look at — grid games, solitaire, tabletop. Physics is often zero-gravity or
+ * omitted; the game owns the face it draws on the board.
+ */
+export interface BoardGround {
+    /** `"stage"` is accepted as an alias and normalized to `"board"`. */
+    mode: "board" | "stage";
+    size: BoardGroundSize;
+    surface?: SurfaceLaws;
+}
+/** The substrate of a place, discriminated by `mode` — TS rejects a `radius` on `flat` and `x`/`z` on `round`. */
+export type GroundConfig = FlatGround | RoundGround | VoxelGround | BoardGround;
+/** Canonical ground modes after normalization (`stage` → `board`). */
+export type GroundMode = "flat" | "round" | "voxel" | "board";
+/** {@link BoardGround} with the `stage` alias resolved away. */
+export type ResolvedBoardGround = Omit<BoardGround, "mode"> & {
+    mode: "board";
+};
+/** A place's ground after `world()` normalization. */
+export type ResolvedGround = FlatGround | RoundGround | VoxelGround | ResolvedBoardGround;
+/** Input to {@link world}: place identity, substrate, and the laws of this place. */
+export interface PlaceConfig {
+    /** Place identity — names the world for saves, seeds, and world switching. */
+    id: string;
+    /** The substrate: what you stand on / look at, discriminated by `mode`. */
+    ground: GroundConfig;
+    /**
+     * Laws of THIS place (gravity, jump). Each world carries its own physics, so a game with several
+     * places (a station and a moon) gives each different laws; `defineGameDefinition` resolves the
+     * active world's physics over the game-level default. The engine owns simulation.
+     */
+    physics?: PhysicsConfig;
+}
+/** A declared place — the `world()` result carried on `GameDefinition.world`. */
+export interface PlaceWorldFeature {
+    kind: "place";
+    id: string;
+    ground: ResolvedGround;
+    physics?: PhysicsConfig;
+}
+/**
+ * Declares the place a game is played in: substrate (`ground`) + laws (`physics`, `ground.surface`).
+ * The thin default start — `flat` with `Infinity` axes and default physics, `board` for 2D — is a
+ * complete world; dressing it (sky, foliage, props, sculpt) is editor-authored scene content.
+ * Multiple worlds per game are first-class: declare one `world()` per place, each with its own id,
+ * ground, and physics. Games that are not a spatial place (pure UI/rules) omit `world` entirely.
+ *
+ * @capability world-place declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
+ */
+export declare function world(config: PlaceConfig): PlaceWorldFeature;
+/**
+ * The engine-side seed derivation for a place: a stable string from the world `id` plus the
+ * save/run seed. Generators and scatter receive this — never a `seed` field in the world
+ * definition — so a save replays its world deterministically and a fresh run can vary by
+ * `runSeed` alone.
+ *
+ * @capability world-seed derive a deterministic generator/scatter seed from world id + save/run seed
+ */
+export declare function seedForPlace(worldId: string, runSeed?: string): string;
+/**
+ * Resolves the physics laws in effect for the active world: a place world's own `physics` wins
+ * field-by-field over the game-level default. Non-place worlds (and games with no world) keep the
+ * game-level config unchanged.
+ */
+export declare function resolveWorldPhysics(worldFeature: {
+    kind: string;
+    physics?: PhysicsConfig;
+} | undefined, base: PhysicsConfig | undefined): PhysicsConfig | undefined;
+/** Type guard for the place-model world feature. */
+export declare function isPlaceWorld(worldFeature: {
+    kind: string;
+} | undefined): worldFeature is PlaceWorldFeature;

package/dist/world/place.js

@@ -0,0 +1,96 @@
+const BANNED_WORLD_KEYS = ["sky", "vegetation", "terrain", "environment", "weather", "seed"];
+function assertNoDressing(config) {
+    const record = config;
+    for (const key of BANNED_WORLD_KEYS) {
+        if (record[key] !== undefined) {
+            throw new Error(key === "seed"
+                ? "world: seed does not belong in a world definition — the engine derives seeds from the world id and the save/run seed (seedForPlace)."
+                : `world: "${key}" does not belong in a world definition — a world is substrate + laws. Author sky, foliage, and dressing in the editor (or a content preset that writes scene data).`);
+        }
+    }
+}
+function assertAxis(mode, axis, value, allowInfinite) {
+    const ok = value > 0 && (allowInfinite ? true : Number.isFinite(value));
+    if (!ok) {
+        throw new Error(`world: ground.size.${axis} for mode "${mode}" must be a positive${allowInfinite ? "" : " finite"} number, got ${value}`);
+    }
+}
+function resolveGround(ground) {
+    if (ground["seed"] !== undefined) {
+        throw new Error("world: seed does not belong on ground — the engine injects seeds into generators (seedForPlace).");
+    }
+    if ("generator" in ground && ground.generator?.params !== undefined && "seed" in ground.generator.params) {
+        throw new Error("world: generator.params.seed is not allowed — the engine injects the seed from world id + save/run (seedForPlace).");
+    }
+    switch (ground.mode) {
+        case "flat": {
+            assertAxis("flat", "x", ground.size.x, true);
+            assertAxis("flat", "z", ground.size.z, true);
+            if (ground.size.y !== undefined)
+                assertAxis("flat", "y", ground.size.y, true);
+            return ground;
+        }
+        case "round": {
+            assertAxis("round", "radius", ground.size.radius, false);
+            return ground;
+        }
+        case "voxel": {
+            assertAxis("voxel", "x", ground.size.x, true);
+            assertAxis("voxel", "y", ground.size.y, true);
+            assertAxis("voxel", "z", ground.size.z, true);
+            return ground;
+        }
+        case "board":
+        case "stage": {
+            assertAxis("board", "x", ground.size.x, false);
+            assertAxis("board", "y", ground.size.y, false);
+            return ground.mode === "board" ? ground : { ...ground, mode: "board" };
+        }
+    }
+}
+/**
+ * Declares the place a game is played in: substrate (`ground`) + laws (`physics`, `ground.surface`).
+ * The thin default start — `flat` with `Infinity` axes and default physics, `board` for 2D — is a
+ * complete world; dressing it (sky, foliage, props, sculpt) is editor-authored scene content.
+ * Multiple worlds per game are first-class: declare one `world()` per place, each with its own id,
+ * ground, and physics. Games that are not a spatial place (pure UI/rules) omit `world` entirely.
+ *
+ * @capability world-place declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
+ */
+export function world(config) {
+    if (config.id.trim().length === 0) {
+        throw new Error("world: id must be non-empty — it names the place for saves, seeds, and world switching");
+    }
+    assertNoDressing(config);
+    return {
+        kind: "place",
+        id: config.id,
+        ground: resolveGround(config.ground),
+        ...(config.physics === undefined ? {} : { physics: config.physics }),
+    };
+}
+/**
+ * The engine-side seed derivation for a place: a stable string from the world `id` plus the
+ * save/run seed. Generators and scatter receive this — never a `seed` field in the world
+ * definition — so a save replays its world deterministically and a fresh run can vary by
+ * `runSeed` alone.
+ *
+ * @capability world-seed derive a deterministic generator/scatter seed from world id + save/run seed
+ */
+export function seedForPlace(worldId, runSeed = "") {
+    return runSeed.length === 0 ? worldId : `${worldId}:${runSeed}`;
+}
+/**
+ * Resolves the physics laws in effect for the active world: a place world's own `physics` wins
+ * field-by-field over the game-level default. Non-place worlds (and games with no world) keep the
+ * game-level config unchanged.
+ */
+export function resolveWorldPhysics(worldFeature, base) {
+    if (worldFeature === undefined || worldFeature.kind !== "place" || worldFeature.physics === undefined)
+        return base;
+    return base === undefined ? worldFeature.physics : { ...base, ...worldFeature.physics };
+}
+/** Type guard for the place-model world feature. */
+export function isPlaceWorld(worldFeature) {
+    return worldFeature?.kind === "place";
+}

package/dist/world/placeAsset.js

@@ -7,10 +7,12 @@ function normalizePosition(position) {
     const t = position;
     return { x: t[0], y: t[1], z: t[2] };
 }
+let placementSequence = 0;
 function placementId(assetId, explicit) {
     if (explicit !== undefined && explicit.length > 0)
         return explicit;
-    return `placed_${assetId}_${Date.now().toString(36)}`;
+    placementSequence += 1;
+    return `placed_${assetId}_${Date.now().toString(36)}_${placementSequence.toString(36)}`;
 }
 /**
  * Resolve a place-asset intent into a shared payload (editor + games, one verb).

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.js

@@ -62,6 +62,10 @@ export function closestPoint(line, query) {
         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];
@@ -71,9 +75,12 @@ export function closestPoint(line, query) {
         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 < best.lateral) {
+        if (lateral < bestDistance) {
+            bestDistance = lateral;
             const along = cumulative[i - 1] + t * Math.sqrt(segLenSq);
-            const side = Math.sign(perp(normalize([abx, aby]))[0] * (query[0] - point[0]) + perp(normalize([abx, aby]))[1] * (query[1] - point[1]));
+            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) };
         }
     }

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;