@jgengine/core 0.10.0 → 0.12.0

package/dist/editor/world.js

@@ -0,0 +1,303 @@
+import { applyEditorDocumentOverlay, createEmptyEditorDocument, editorDocumentExtras, extractEditorFragment, mergeEditorDocuments, } from "./document.js";
+/**
+ * A sharded **world**: a scene that is no longer one monolithic `editor.scene.json` but a manifest
+ * plus spatially-partitioned shard documents. A single-file game is the degenerate one-shard case,
+ * so nothing pays for scale it does not have. The shard/overlay documents are the exact
+ * {@link EditorDocument} format loaders already consume — this module is composition over
+ * `mergeEditorDocuments` / `extractEditorFragment` / `editorDocumentBounds`, not a new format.
+ */
+/** The manifest `kind` discriminator — a world folder's `world.json`. */
+export const WORLD_MANIFEST_KIND = "world";
+/** True when a shard is resident regardless of any spatial query (unbounded or explicitly `"always"`). */
+function isAlwaysResident(shard) {
+    return shard.residency === "always" || shard.bounds === undefined;
+}
+/** Closest-point disc↔AABB overlap test on the XZ plane. */
+function discIntersectsBounds(cx, cz, radius, bounds) {
+    const qx = Math.max(bounds.min[0], Math.min(cx, bounds.max[0]));
+    const qz = Math.max(bounds.min[1], Math.min(cz, bounds.max[1]));
+    const dx = cx - qx;
+    const dz = cz - qz;
+    return dx * dx + dz * dz <= radius * radius;
+}
+/**
+ * True when a shard should be resident for a query: always-resident shards always, bounded shards
+ * only when the query disc (`center` ± `radius`) overlaps their footprint.
+ * @capability world-shards select shards for a neighborhood by spatial query
+ */
+export function shardMatchesQuery(shard, query) {
+    if (isAlwaysResident(shard))
+        return true;
+    return discIntersectsBounds(query.center.x, query.center.z, query.radius ?? 0, shard.bounds);
+}
+/**
+ * The shards a query needs — always-resident shards plus every bounded shard whose footprint the
+ * query disc overlaps, in manifest order. With no query every shard is selected (load the planet),
+ * so a one-shard game and an unqueried load behave exactly as a monolithic document does today.
+ * @capability world-shards select shards for a neighborhood by spatial query
+ */
+export function selectWorldShards(manifest, query) {
+    if (query === undefined)
+        return [...manifest.shards];
+    return manifest.shards.filter((shard) => shardMatchesQuery(shard, query));
+}
+/**
+ * Loads the live neighborhood document for a query: reads each selected shard through `resolve`,
+ * applies its overlay (if any) on top, then merges them into one {@link EditorDocument} downstream
+ * consumers (`placeAuthoredObjects`, `collectAuthoredTriggers`, scatter, …) read unchanged. The
+ * monolith becomes an internal detail of the loader; a one-shard world yields exactly that shard.
+ * @capability world-shards merge the shards for a neighborhood into one live document
+ */
+export function loadWorldDocument(manifest, resolve, query) {
+    const shards = selectWorldShards(manifest, query);
+    const docs = [];
+    for (const shard of shards) {
+        const base = resolve(shard.file);
+        if (base === null)
+            continue;
+        if (shard.overlay === undefined) {
+            docs.push(base);
+            continue;
+        }
+        const overlay = resolve(shard.overlay);
+        docs.push(overlay === null ? base : applyEditorDocumentOverlay(base, overlay));
+    }
+    if (docs.length === 0)
+        return createEmptyEditorDocument();
+    return mergeEditorDocuments(...docs);
+}
+/** The always-resident base shard id used by {@link splitEditorDocumentIntoShards}. */
+export const WORLD_BASE_SHARD_ID = "base";
+/** Representative XZ point for an object, used to assign it to a grid cell. */
+function objectCell(x, z, cellSize) {
+    return { gx: Math.floor(x / cellSize), gz: Math.floor(z / cellSize) };
+}
+function pathCentroid(points) {
+    if (points.length === 0)
+        return { x: 0, z: 0 };
+    let x = 0;
+    let z = 0;
+    for (const point of points) {
+        x += point.x;
+        z += point.z;
+    }
+    return { x: x / points.length, z: z / points.length };
+}
+/**
+ * Splits a monolithic document into a sharded world: placeable objects (markers, volumes, paths,
+ * notes) are bucketed into `cellSize`-meter grid cells by a representative point and extracted into
+ * per-cell shard documents; the non-placeable extras (terrain, catalogs, prefabs, collections,
+ * grids, HUD layout) go into one always-resident `base` shard. Round-trips through
+ * {@link loadWorldDocument} to the same object set — the reverse of monolith authoring, so a large
+ * scene can be sharded once and streamed thereafter. Cell shards carry their exact object footprint
+ * as bounds; empty cells are omitted; order is deterministic (row-major by grid coordinate).
+ * @capability world-shards split a monolithic scene document into spatial shards
+ */
+export function splitEditorDocumentIntoShards(doc, options = {}) {
+    const cellSize = options.cellSize !== undefined && options.cellSize > 0 ? options.cellSize : 256;
+    const shardDir = options.shardDir ?? "shards";
+    // Bucket every placeable object id by the grid cell containing its representative point.
+    const cellIds = new Map();
+    const addToCell = (gx, gz, id) => {
+        const key = `${gx}:${gz}`;
+        const bucket = cellIds.get(key);
+        if (bucket === undefined)
+            cellIds.set(key, [id]);
+        else
+            bucket.push(id);
+    };
+    for (const marker of doc.markers) {
+        const { gx, gz } = objectCell(marker.position.x, marker.position.z, cellSize);
+        addToCell(gx, gz, marker.id);
+    }
+    for (const volume of doc.volumes) {
+        const { gx, gz } = objectCell(volume.center.x, volume.center.z, cellSize);
+        addToCell(gx, gz, volume.id);
+    }
+    for (const path of doc.paths) {
+        const c = pathCentroid(path.points);
+        const { gx, gz } = objectCell(c.x, c.z, cellSize);
+        addToCell(gx, gz, path.id);
+    }
+    for (const note of doc.annotations) {
+        const { gx, gz } = objectCell(note.position.x, note.position.z, cellSize);
+        addToCell(gx, gz, note.id);
+    }
+    // Always-resident base shard carries the non-placeable extras verbatim.
+    const baseFile = `${shardDir}/${WORLD_BASE_SHARD_ID}.json`;
+    const baseDoc = {
+        ...createEmptyEditorDocument(),
+        ...editorDocumentExtras(doc),
+    };
+    const shards = { [baseFile]: baseDoc };
+    const manifestShards = [
+        { id: WORLD_BASE_SHARD_ID, file: baseFile, residency: "always" },
+    ];
+    const sortedKeys = [...cellIds.keys()].sort((a, b) => {
+        const [ax, az] = a.split(":").map(Number);
+        const [bx, bz] = b.split(":").map(Number);
+        return az === bz ? ax - bx : az - bz;
+    });
+    for (const key of sortedKeys) {
+        const [gx, gz] = key.split(":").map(Number);
+        const ids = cellIds.get(key);
+        const shardDoc = extractEditorFragment(doc, ids);
+        const id = `cell_${gx}_${gz}`;
+        const file = `${shardDir}/${id}.json`;
+        shards[file] = shardDoc;
+        manifestShards.push({
+            id,
+            file,
+            residency: "streamed",
+            bounds: {
+                min: [gx * cellSize, gz * cellSize],
+                max: [(gx + 1) * cellSize, (gz + 1) * cellSize],
+            },
+        });
+    }
+    return {
+        manifest: {
+            kind: WORLD_MANIFEST_KIND,
+            version: 1,
+            grid: { cellSize },
+            shards: manifestShards,
+        },
+        shards,
+    };
+}
+/**
+ * The backward-compatible degenerate manifest: one always-resident shard pointing at a single scene
+ * document file. `loadWorldDocument(singleShardWorldManifest(file), resolve)` returns exactly that
+ * document — the migration path for a game that has one `editor.scene.json` and wants the world API
+ * without sharding yet.
+ * @capability world-shards wrap a single scene document as a one-shard world
+ */
+export function singleShardWorldManifest(file, shardId = WORLD_BASE_SHARD_ID) {
+    return {
+        kind: WORLD_MANIFEST_KIND,
+        version: 1,
+        shards: [{ id: shardId, file, residency: "always" }],
+    };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeBounds(value, path, errors) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value)) {
+        errors.push({ path, message: "expected an object" });
+        return undefined;
+    }
+    const pair = (v, p) => {
+        if (!Array.isArray(v) || v.length !== 2 || typeof v[0] !== "number" || typeof v[1] !== "number") {
+            errors.push({ path: p, message: "expected [number, number]" });
+            return null;
+        }
+        return [v[0], v[1]];
+    };
+    const min = pair(value.min, `${path}.min`);
+    const max = pair(value.max, `${path}.max`);
+    if (min === null || max === null)
+        return undefined;
+    return { min, max };
+}
+function decodeShard(value, path, errors) {
+    if (!isPlainObject(value)) {
+        errors.push({ path, message: "expected an object" });
+        return null;
+    }
+    if (typeof value.id !== "string")
+        errors.push({ path: `${path}.id`, message: "expected a string" });
+    if (typeof value.file !== "string")
+        errors.push({ path: `${path}.file`, message: "expected a string" });
+    const bounds = decodeBounds(value.bounds, `${path}.bounds`, errors);
+    let residency;
+    if (value.residency !== undefined) {
+        if (value.residency === "always" || value.residency === "streamed")
+            residency = value.residency;
+        else
+            errors.push({ path: `${path}.residency`, message: "expected \"always\" | \"streamed\"" });
+    }
+    if (value.overlay !== undefined && typeof value.overlay !== "string") {
+        errors.push({ path: `${path}.overlay`, message: "expected a string" });
+    }
+    if (typeof value.id !== "string" || typeof value.file !== "string")
+        return null;
+    const shard = { id: value.id, file: value.file };
+    if (bounds !== undefined)
+        shard.bounds = bounds;
+    if (residency !== undefined)
+        shard.residency = residency;
+    if (typeof value.overlay === "string")
+        shard.overlay = value.overlay;
+    return shard;
+}
+/**
+ * The authoritative decoder for a `world.json` manifest arriving from disk or an agent: validates
+ * `kind`, the shard list, and each shard's fields with a path-specific diagnostic on failure, so a
+ * malformed manifest fails loudly at the boundary instead of streaming a broken world.
+ * @capability world-shards decode an untrusted world manifest with per-field diagnostics
+ */
+export function decodeWorldManifest(raw) {
+    if (!isPlainObject(raw)) {
+        return { ok: false, errors: [{ path: "$", message: "world manifest must be an object" }] };
+    }
+    const errors = [];
+    if (raw.kind !== WORLD_MANIFEST_KIND) {
+        errors.push({ path: "$.kind", message: `expected "${WORLD_MANIFEST_KIND}"` });
+    }
+    if (raw.version !== undefined && typeof raw.version !== "number") {
+        errors.push({ path: "$.version", message: "expected a number" });
+    }
+    let grid;
+    if (raw.grid !== undefined) {
+        if (isPlainObject(raw.grid) && typeof raw.grid.cellSize === "number")
+            grid = { cellSize: raw.grid.cellSize };
+        else
+            errors.push({ path: "$.grid", message: "expected { cellSize: number }" });
+    }
+    let streaming;
+    if (raw.streaming !== undefined) {
+        if (isPlainObject(raw.streaming) &&
+            typeof raw.streaming.loadRadius === "number" &&
+            typeof raw.streaming.keepRadius === "number") {
+            streaming = { loadRadius: raw.streaming.loadRadius, keepRadius: raw.streaming.keepRadius };
+        }
+        else {
+            errors.push({ path: "$.streaming", message: "expected { loadRadius: number, keepRadius: number }" });
+        }
+    }
+    const shards = [];
+    if (!Array.isArray(raw.shards)) {
+        errors.push({ path: "$.shards", message: "expected an array" });
+    }
+    else {
+        raw.shards.forEach((item, index) => {
+            const shard = decodeShard(item, `$.shards[${index}]`, errors);
+            if (shard !== null)
+                shards.push(shard);
+        });
+        const seen = new Set();
+        shards.forEach((shard, index) => {
+            if (seen.has(shard.id))
+                errors.push({ path: `$.shards[${index}].id`, message: `duplicate shard id "${shard.id}"` });
+            else
+                seen.add(shard.id);
+        });
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const manifest = { kind: WORLD_MANIFEST_KIND, shards };
+    if (typeof raw.version === "number")
+        manifest.version = raw.version;
+    if (grid !== undefined)
+        manifest.grid = grid;
+    if (streaming !== undefined)
+        manifest.streaming = streaming;
+    return { ok: true, manifest };
+}
+/** Serializes a world manifest to pretty JSON for writing `world.json`. */
+export function exportWorldManifestJson(manifest, pretty = true) {
+    return JSON.stringify(manifest, null, pretty ? 2 : undefined);
+}

package/dist/faction/reputation.d.ts

@@ -5,6 +5,11 @@ export interface ReputationTier {
     relation: FactionRelation;
 }
 export declare const DEFAULT_REPUTATION_TIERS: readonly ReputationTier[];
+/**
+ * Map a faction standing value to its named reputation tier.
+ *
+ * @capability reputation faction standing that crosses named reputation tiers
+ */
 export declare function tierForStanding(tiers: readonly ReputationTier[], standing: number): ReputationTier;
 export interface ReputationLedgerConfig {
     tiers?: readonly ReputationTier[];

package/dist/faction/reputation.js

@@ -8,6 +8,11 @@ export const DEFAULT_REPUTATION_TIERS = [
     { id: "revered", min: 21000, relation: "friendly" },
     { id: "exalted", min: 42000, relation: "friendly" },
 ];
+/**
+ * Map a faction standing value to its named reputation tier.
+ *
+ * @capability reputation faction standing that crosses named reputation tiers
+ */
 export function tierForStanding(tiers, standing) {
     let match = tiers[0];
     for (const tier of tiers) {

package/dist/format/distance.d.ts

@@ -0,0 +1,17 @@
+/** Target unit for {@link formatDistance}: meters, kilometers, or `"auto"` (km past 1000m). */
+export type DistanceUnit = "m" | "km" | "auto";
+/** Options for {@link formatDistance}. */
+export interface DistanceFormat {
+    /** Target unit. `"auto"` switches to km at 1000m and above. Defaults to `"m"`. */
+    unit?: DistanceUnit;
+    /** Fractional digits to show. Defaults to 0 for meters, 1 for kilometers. */
+    decimals?: 0 | 1 | 2;
+    /** Append the unit label. Defaults to true; set false to compose custom unit styling. */
+    showUnit?: boolean;
+}
+/**
+ * Format a distance given in meters as a HUD-ready string, switching to km automatically past 1000m when `unit: "auto"`.
+ *
+ * @capability distance-format render meters as m or km for HUD stats, telemetry, and range readouts
+ */
+export declare function formatDistance(meters: number, options?: DistanceFormat): string;

package/dist/format/distance.js

@@ -0,0 +1,18 @@
+const AUTO_KM_THRESHOLD = 1000;
+/**
+ * Format a distance given in meters as a HUD-ready string, switching to km automatically past 1000m when `unit: "auto"`.
+ *
+ * @capability distance-format render meters as m or km for HUD stats, telemetry, and range readouts
+ */
+export function formatDistance(meters, options = {}) {
+    const requested = options.unit ?? "m";
+    const clamped = Math.max(0, meters);
+    const showUnit = options.showUnit ?? true;
+    const useKm = requested === "km" || (requested === "auto" && clamped >= AUTO_KM_THRESHOLD);
+    if (useKm) {
+        const text = (clamped / 1000).toFixed(options.decimals ?? 1);
+        return showUnit ? `${text}km` : text;
+    }
+    const text = clamped.toFixed(options.decimals ?? 0);
+    return showUnit ? `${text}m` : text;
+}

package/dist/format/duration.d.ts

@@ -0,0 +1,27 @@
+/** Options for {@link formatDuration}. */
+export interface DurationFormat {
+    /** Fractional-second digits to show (0, 1, or 2). Defaults to 0. */
+    decimals?: 0 | 1 | 2;
+    /** Force an `h:mm:ss` layout even under an hour. Defaults to auto (hours shown only when present). */
+    hours?: boolean;
+}
+/** Left-pad a non-negative integer to `width` digits with leading zeros. */
+export declare function padNumber(value: number, width: number): string;
+/**
+ * Format a duration in seconds as a clock string (`m:ss`, `m:ss.ff`, or `h:mm:ss`), the shape every timer and racing HUD needs.
+ *
+ * @capability clock-format render seconds as m:ss / m:ss.ff / h:mm:ss for timers and race HUDs
+ */
+export declare function formatDuration(seconds: number, options?: DurationFormat): string;
+/**
+ * Format a signed time gap as `+m:ss.ff` / `-m:ss.ff`, for race deltas and split times.
+ *
+ * @capability clock-format format a signed time gap like a race split (+/- m:ss.ff)
+ */
+export declare function formatDelta(seconds: number, decimals?: 0 | 1 | 2): string;
+/**
+ * English ordinal for a placement number: 1 → "1st", 2 → "2nd", 3 → "3rd", 11 → "11th".
+ *
+ * @capability ordinal-format format a placement number as 1st/2nd/3rd for HUD ranks
+ */
+export declare function formatOrdinal(value: number): string;

package/dist/format/duration.js

@@ -0,0 +1,45 @@
+/** Left-pad a non-negative integer to `width` digits with leading zeros. */
+export function padNumber(value, width) {
+    return Math.trunc(value).toString().padStart(width, "0");
+}
+/**
+ * Format a duration in seconds as a clock string (`m:ss`, `m:ss.ff`, or `h:mm:ss`), the shape every timer and racing HUD needs.
+ *
+ * @capability clock-format render seconds as m:ss / m:ss.ff / h:mm:ss for timers and race HUDs
+ */
+export function formatDuration(seconds, options = {}) {
+    const decimals = options.decimals ?? 0;
+    const total = Math.max(0, seconds);
+    const whole = Math.floor(total);
+    const frac = decimals > 0 ? (total - whole).toFixed(decimals).slice(1) : "";
+    const showHours = options.hours ?? total >= 3600;
+    if (showHours) {
+        const h = Math.floor(whole / 3600);
+        const m = Math.floor((whole % 3600) / 60);
+        const s = whole % 60;
+        return `${h}:${padNumber(m, 2)}:${padNumber(s, 2)}${frac}`;
+    }
+    const m = Math.floor(whole / 60);
+    const s = whole % 60;
+    return `${m}:${padNumber(s, 2)}${frac}`;
+}
+/**
+ * Format a signed time gap as `+m:ss.ff` / `-m:ss.ff`, for race deltas and split times.
+ *
+ * @capability clock-format format a signed time gap like a race split (+/- m:ss.ff)
+ */
+export function formatDelta(seconds, decimals = 2) {
+    const sign = seconds < 0 ? "-" : "+";
+    return `${sign}${formatDuration(Math.abs(seconds), { decimals })}`;
+}
+/**
+ * English ordinal for a placement number: 1 → "1st", 2 → "2nd", 3 → "3rd", 11 → "11th".
+ *
+ * @capability ordinal-format format a placement number as 1st/2nd/3rd for HUD ranks
+ */
+export function formatOrdinal(value) {
+    const n = Math.trunc(value);
+    const abs = Math.abs(n) % 100;
+    const suffix = abs >= 11 && abs <= 13 ? "th" : ["th", "st", "nd", "rd"][Math.abs(n) % 10] ?? "th";
+    return `${n}${suffix}`;
+}

package/dist/format/speed.d.ts

@@ -0,0 +1,17 @@
+/** Target unit for {@link formatSpeed}: km/h, mph, knots, or raw m/s. */
+export type SpeedUnit = "kmh" | "mph" | "knots" | "ms";
+/** Options for {@link formatSpeed}. */
+export interface SpeedFormat {
+    /** Target unit to convert into from the m/s input. Defaults to `"kmh"`. */
+    unit?: SpeedUnit;
+    /** Fractional digits to show. Defaults to 0. */
+    decimals?: 0 | 1 | 2;
+    /** Append the unit label. Defaults to true; set false to compose custom unit styling. */
+    showUnit?: boolean;
+}
+/**
+ * Format a speed given in meters/second as a HUD-ready string in km/h, mph, knots, or m/s — the one conversion table every speedometer and telemetry readout should share.
+ *
+ * @capability speed-format render a m/s speed as km/h, mph, knots, or m/s for speedometers and telemetry HUDs
+ */
+export declare function formatSpeed(metersPerSecond: number, options?: SpeedFormat): string;

package/dist/format/speed.js

@@ -0,0 +1,25 @@
+const SPEED_UNIT_FACTOR = {
+    kmh: 3.6,
+    mph: 2.2369362920544025,
+    knots: 1.9438444924406046,
+    ms: 1,
+};
+const SPEED_UNIT_LABEL = {
+    kmh: "km/h",
+    mph: "mph",
+    knots: "kn",
+    ms: "m/s",
+};
+/**
+ * Format a speed given in meters/second as a HUD-ready string in km/h, mph, knots, or m/s — the one conversion table every speedometer and telemetry readout should share.
+ *
+ * @capability speed-format render a m/s speed as km/h, mph, knots, or m/s for speedometers and telemetry HUDs
+ */
+export function formatSpeed(metersPerSecond, options = {}) {
+    const unit = options.unit ?? "kmh";
+    const decimals = options.decimals ?? 0;
+    const showUnit = options.showUnit ?? true;
+    const converted = Math.max(0, metersPerSecond) * SPEED_UNIT_FACTOR[unit];
+    const text = converted.toFixed(decimals);
+    return showUnit ? `${text} ${SPEED_UNIT_LABEL[unit]}` : text;
+}

package/dist/game/breeding.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Deterministic creature breeding & genetics — a genre-agnostic engine primitive for
+ * taming/husbandry games. Everything here operates over plain serializable records so a
+ * genome round-trips through save/load and multiplayer sync, and every random decision is
+ * driven by an injected `rng: () => number` (values in `[0, 1)`) so identical inputs and an
+ * identical rng stream always produce the identical offspring.
+ *
+ * The lifecycle it models:
+ *  - **inheritance** — each stat is drawn independently from the higher or lower parent,
+ *  - **mutation** — a bounded number of rolls that boost a stat, bump a heritable lineage
+ *    counter, and optionally flag a cosmetic/color mutation, gated by a soft cap,
+ *  - **imprint** — a rearing bonus accrued by fulfilling care requests over maturation,
+ *  - **incubation & maturation** — temperature-gated gestation viability and stage resolution.
+ *
+ * No species tables, coordinates, or game content live here; callers supply their own stat
+ * ids and tuning.
+ */
+/** A stat block: stat id → numeric point value. Plain serializable record, no ordering assumed. */
+export type StatBlock = Record<string, number>;
+/**
+ * A creature's heritable genome. `stats` are the inherited/mutated point values;
+ * `mutationCount` and `colorMutationCount` are the lineage counters that carry across
+ * generations and drive the mutation soft cap. Fully serializable — no methods or closures.
+ */
+export interface Genome {
+    stats: StatBlock;
+    /** Accumulated point mutations in this creature's lineage. Heritable, monotonic. */
+    mutationCount: number;
+    /** Accumulated cosmetic/color mutations in this creature's lineage. Heritable, monotonic. */
+    colorMutationCount: number;
+}
+/** One mutation that occurred while breeding a single offspring. */
+export interface MutationEvent {
+    /** Stat id that received the point delta. */
+    stat: string;
+    /** Points added to that stat (the configured `mutationDelta`). */
+    delta: number;
+    /** True when this mutation was also flagged cosmetic/color. */
+    color: boolean;
+}
+/**
+ * Soft-cap rule for mutation eligibility. When a parent's `mutationCount` exceeds
+ * `threshold` its lineage is considered "capped"; the per-roll mutation chance is then
+ * either zeroed (`mode: "block"`) or scaled by `reducedFactor` (`mode: "reduce"`).
+ * `scope` decides whether it takes `both` parents capped, or `either` one, to trigger.
+ */
+export interface MutationSoftCap {
+    /** Counter value a parent must exceed to count as capped. Default `20`. */
+    threshold?: number;
+    /** Trigger when `both` parents are capped (default) or `either` one is. */
+    scope?: "both" | "either";
+    /** Zero the chance (`block`, default) or scale it by `reducedFactor` (`reduce`). */
+    mode?: "block" | "reduce";
+    /** Multiplier applied to the base chance when `mode: "reduce"` and capped. Default `0.5`. */
+    reducedFactor?: number;
+}
+/** Tuning for {@link breedOffspring}. Every field has an ARK-style default; all are optional. */
+export interface BreedConfig {
+    /** Per-stat probability the offspring inherits the higher parent's value. Default `0.55`. */
+    higherStatChance?: number;
+    /** Number of independent mutation rolls per offspring. Default `3`. */
+    mutationRolls?: number;
+    /** Probability each mutation roll succeeds (before the soft cap). Default `0.025`. */
+    mutationChance?: number;
+    /** Points added to a random stat by a successful mutation. Default `2`. */
+    mutationDelta?: number;
+    /** Probability a successful mutation is additionally flagged cosmetic. Default `0.5`. */
+    colorMutationChance?: number;
+    /** Mutation-count soft cap rule. Defaults to `{ threshold: 20, scope: "both", mode: "block" }`. */
+    mutationSoftCap?: MutationSoftCap;
+}
+/** Result of {@link breedOffspring}: the new genome plus the mutations that produced it. */
+export interface BreedResult {
+    genome: Genome;
+    mutations: readonly MutationEvent[];
+}
+/**
+ * Breed one offspring from two parents. For each stat present in either parent (iterated in
+ * sorted id order for a stable rng stream) the offspring independently inherits the higher
+ * parent's value with probability `higherStatChance` (default `0.55`), else the lower — a
+ * per-stat coin flip, so a strong parent does not guarantee a strong child. Then up to
+ * `mutationRolls` mutation rolls fire at the soft-capped chance; each success adds
+ * `mutationDelta` to a random stat, bumps the heritable `mutationCount`, and is flagged
+ * cosmetic with probability `colorMutationChance`. Lineage counters carry as the max of the
+ * two parents plus the new mutations, keeping them monotonic and heritable.
+ *
+ * Deterministic: the same parents, config, and rng sequence yield byte-identical results.
+ *
+ * @capability creature-breeding deterministic stat inheritance, mutation, and lineage genetics for taming games
+ */
+export declare function breedOffspring(parentA: Genome, parentB: Genome, rng: () => number, config?: BreedConfig): BreedResult;
+/** Options controlling how an imprint bonus is applied. */
+export interface ImprintBonusConfig {
+    /** Stat multiplier at full imprint, applied to everyone. Default `0.20` (+20%). */
+    statBonusAtFull?: number;
+    /** Extra multiplier at full imprint, applied only for the imprinting owner. Default `0.30` (+30%). */
+    handlerBonusAtFull?: number;
+}
+/**
+ * Imprint gained per fulfilled care request when `requestCount` requests are scheduled over
+ * the maturation window: `1 / requestCount`, so fulfilling every request reaches full (1.0)
+ * imprint. Returns `0` for a non-positive request count.
+ *
+ * @capability imprint-increment per-care-request imprint gain across a maturation schedule
+ */
+export declare function imprintIncrementPerRequest(requestCount: number): number;
+/**
+ * Apply the imprint rearing bonus to a stat block. Every stat is scaled by
+ * `1 + statBonusAtFull * imprint`; when `asOwner` is set, the imprinting handler additionally
+ * gets `1 + handlerBonusAtFull * imprint`. `imprint` is a 0..1 fraction (clamped) and scales
+ * both bonuses linearly, so half-imprint yields half the bonus. Returns a fresh stat block.
+ *
+ * @capability imprint-bonus apply imprint stat and handler bonuses at an imprint fraction
+ */
+export declare function applyImprintBonus(stats: StatBlock, imprint: number, config?: ImprintBonusConfig, options?: {
+    asOwner?: boolean;
+}): StatBlock;
+/** Serializable incubation/gestation state advanced by {@link tickIncubation}. */
+export interface IncubationState {
+    /** Remaining egg/embryo health; incubation fails at `0`. */
+    health: number;
+    /** Accumulated in-range incubation time; only advances while temperature is viable. */
+    elapsed: number;
+}
+/** Temperature gate for {@link tickIncubation}. */
+export interface IncubationConfig {
+    minTemp: number;
+    maxTemp: number;
+    /** Health lost per unit `dt` while temperature is outside `[minTemp, maxTemp]`. Default `1`. */
+    healthLossPerTick?: number;
+}
+/**
+ * Advance incubation one tick. While `temperature` is within `[minTemp, maxTemp]` the embryo
+ * makes progress (`elapsed += dt`) and keeps its health; outside the range it makes no
+ * progress and loses `healthLossPerTick * dt` health (clamped at `0`). Pure — returns a new
+ * state, never mutates the input.
+ *
+ * @capability incubation-tick advance egg incubation health inside/outside its temperature range
+ */
+export declare function tickIncubation(state: IncubationState, temperature: number, dt: number, config: IncubationConfig): IncubationState;
+/**
+ * True while the incubation still has health to hatch.
+ *
+ * @capability incubation-viability test whether an egg incubation still has health to hatch
+ */
+export declare function incubationViable(state: IncubationState): boolean;
+/** A maturation stage keyed by the elapsed fraction (0..1) at which it begins. */
+export interface MaturationStage {
+    id: string;
+    /** Fraction of the maturation duration at which this stage starts (inclusive). */
+    at: number;
+}
+/**
+ * Resolve the maturation stage for an elapsed time against a duration. Computes the clamped
+ * `elapsed / duration` fraction and returns the id of the last stage whose `at` threshold has
+ * been reached (boundaries inclusive). Stages need not be pre-sorted. Returns `""` when no
+ * stage qualifies (e.g. an empty list or all thresholds above the current fraction).
+ *
+ * @capability maturation-stage resolve the baby/juvenile/adolescent/adult stage from elapsed maturation
+ */
+export declare function maturationStage(elapsed: number, duration: number, stages: readonly MaturationStage[]): string;