@jgengine/core 0.11.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/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;

package/dist/game/breeding.js

@@ -0,0 +1,181 @@
+/**
+ * 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.
+ */
+const DEFAULT_HIGHER_STAT_CHANCE = 0.55;
+const DEFAULT_MUTATION_ROLLS = 3;
+const DEFAULT_MUTATION_CHANCE = 0.025;
+const DEFAULT_MUTATION_DELTA = 2;
+const DEFAULT_COLOR_MUTATION_CHANCE = 0.5;
+const DEFAULT_SOFT_CAP_THRESHOLD = 20;
+const DEFAULT_REDUCED_FACTOR = 0.5;
+function clamp01(x) {
+    return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+/**
+ * Per-roll mutation chance after applying the soft cap to both parents. Exposed so callers
+ * and tests can inspect the exact gating rule without breeding.
+ *
+ * @internal
+ */
+function effectiveMutationChance(a, b, config) {
+    const base = config.mutationChance ?? DEFAULT_MUTATION_CHANCE;
+    const cap = config.mutationSoftCap;
+    const threshold = cap?.threshold ?? DEFAULT_SOFT_CAP_THRESHOLD;
+    const scope = cap?.scope ?? "both";
+    const mode = cap?.mode ?? "block";
+    const aOver = a.mutationCount > threshold;
+    const bOver = b.mutationCount > threshold;
+    const capped = scope === "both" ? aOver && bOver : aOver || bOver;
+    if (!capped)
+        return base;
+    return mode === "reduce" ? base * (cap?.reducedFactor ?? DEFAULT_REDUCED_FACTOR) : 0;
+}
+/**
+ * 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 function breedOffspring(parentA, parentB, rng, config = {}) {
+    const higherChance = config.higherStatChance ?? DEFAULT_HIGHER_STAT_CHANCE;
+    const rolls = Math.max(0, Math.floor(config.mutationRolls ?? DEFAULT_MUTATION_ROLLS));
+    const delta = config.mutationDelta ?? DEFAULT_MUTATION_DELTA;
+    const colorChance = config.colorMutationChance ?? DEFAULT_COLOR_MUTATION_CHANCE;
+    // Stable union of stat ids so the rng stream does not depend on object key order.
+    const statIds = Array.from(new Set([...Object.keys(parentA.stats), ...Object.keys(parentB.stats)])).sort();
+    const stats = {};
+    for (const id of statIds) {
+        const av = parentA.stats[id];
+        const bv = parentB.stats[id];
+        // A stat missing on one side behaves as if both parents shared the present value:
+        // one rng draw is still consumed so adding a stat to a parent cannot shift the stream.
+        const present = av ?? bv ?? 0;
+        const high = av === undefined || bv === undefined ? present : Math.max(av, bv);
+        const low = av === undefined || bv === undefined ? present : Math.min(av, bv);
+        stats[id] = rng() < higherChance ? high : low;
+    }
+    const chance = effectiveMutationChance(parentA, parentB, config);
+    const mutations = [];
+    let newMutations = 0;
+    let newColor = 0;
+    for (let i = 0; i < rolls; i++) {
+        if (rng() >= chance)
+            continue;
+        newMutations += 1;
+        let stat = "";
+        if (statIds.length > 0) {
+            const index = Math.min(statIds.length - 1, Math.floor(rng() * statIds.length));
+            stat = statIds[index];
+            stats[stat] = (stats[stat] ?? 0) + delta;
+        }
+        const color = rng() < colorChance;
+        if (color)
+            newColor += 1;
+        mutations.push({ stat, delta: stat === "" ? 0 : delta, color });
+    }
+    const genome = {
+        stats,
+        mutationCount: Math.max(parentA.mutationCount, parentB.mutationCount) + newMutations,
+        colorMutationCount: Math.max(parentA.colorMutationCount, parentB.colorMutationCount) + newColor,
+    };
+    return { genome, mutations };
+}
+const DEFAULT_STAT_BONUS = 0.2;
+const DEFAULT_HANDLER_BONUS = 0.3;
+/**
+ * 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 function imprintIncrementPerRequest(requestCount) {
+    return requestCount > 0 ? 1 / requestCount : 0;
+}
+/**
+ * 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 function applyImprintBonus(stats, imprint, config = {}, options = {}) {
+    const fraction = clamp01(imprint);
+    const statBonus = config.statBonusAtFull ?? DEFAULT_STAT_BONUS;
+    const handlerBonus = config.handlerBonusAtFull ?? DEFAULT_HANDLER_BONUS;
+    let multiplier = 1 + statBonus * fraction;
+    if (options.asOwner)
+        multiplier *= 1 + handlerBonus * fraction;
+    const out = {};
+    for (const id of Object.keys(stats))
+        out[id] = stats[id] * multiplier;
+    return out;
+}
+/**
+ * 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 function tickIncubation(state, temperature, dt, config) {
+    if (dt <= 0)
+        return { health: state.health, elapsed: state.elapsed };
+    const inRange = temperature >= config.minTemp && temperature <= config.maxTemp;
+    if (inRange)
+        return { health: state.health, elapsed: state.elapsed + dt };
+    const loss = (config.healthLossPerTick ?? 1) * dt;
+    return { health: Math.max(0, state.health - loss), elapsed: state.elapsed };
+}
+/**
+ * True while the incubation still has health to hatch.
+ *
+ * @capability incubation-viability test whether an egg incubation still has health to hatch
+ */
+export function incubationViable(state) {
+    return state.health > 0;
+}
+/**
+ * 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 function maturationStage(elapsed, duration, stages) {
+    const fraction = duration > 0 ? clamp01(elapsed / duration) : 1;
+    let bestId = "";
+    let bestAt = -Infinity;
+    for (const stage of stages) {
+        if (stage.at <= fraction && stage.at >= bestAt) {
+            bestAt = stage.at;
+            bestId = stage.id;
+        }
+    }
+    return bestId;
+}