@jgengine/core 0.11.0 → 0.13.0

package/dist/scene/companion.d.ts

@@ -0,0 +1,147 @@
+import type { MobVec3 } from "../ai/mobBrain.js";
+import type { StatCatalog, StatValue, StatValueMap } from "./entityStats.js";
+/**
+ * A tamed companion's standing order. Genre-agnostic aggression + posture preset:
+ * - `follow` — heel to the owner and assist whatever the owner is fighting.
+ * - `stay` — hold at `home` and assist the owner's target from there.
+ * - `passive` — heel to the owner and never engage (a pacifist escort).
+ * - `neutral` — heel to the owner and only fight back nearby threats (defensive).
+ * - `aggressive` — heel to the owner and proactively engage nearby threats and the owner's target.
+ */
+export type CompanionCommand = "follow" | "stay" | "passive" | "neutral" | "aggressive";
+/**
+ * Serializable per-companion state: who owns it, its standing order, where it holds, its
+ * leash radius, and its levelled stat pool. Plain data — JSON round-trips without loss.
+ */
+export interface CompanionRecord {
+    id: string;
+    /** Owning user/entity id — the roster ownership tie. */
+    ownerId: string;
+    /** The {@link RosterEntry.id} this companion was tamed from, or `null` when free-standing. */
+    sourceId: string | null;
+    command: CompanionCommand;
+    /** Hold/return anchor used by `stay`; `null` until the owner parks it somewhere. */
+    home: MobVec3 | null;
+    /** Radius the game keeps the companion within of its resolved anchor (feeds a brain's leash distance). */
+    leash: number;
+    level: number;
+    /** Stat points earned from levels and not yet spent via {@link CompanionRoster.spend}. */
+    unspentPoints: number;
+    /** Levelled stat pool, composed over `scene/entityStats`. */
+    stats: StatValueMap;
+}
+/** Per-tick world context the game supplies so a command resolves into a concrete intent. */
+export interface CompanionIntentContext {
+    /** Owner's current world position — the anchor for every non-`stay` mode; `null` when absent. */
+    ownerPosition?: MobVec3 | null;
+    /** The owner's current attack target — the companion assists/aggros it per its command. */
+    ownerTargetId?: string | null;
+    /** Threat ids near the companion the game offers as engage candidates (already proximity-filtered upstream). */
+    threats?: readonly string[];
+}
+/**
+ * The companion's decision for one tick, shaped for `ai/mobBrain`: feed `candidates` into
+ * `MobBrainDeps.candidates()`, treat `leashTo` as the brain's `home`, and pass `leashDistance`
+ * as `leashDistance`. `kind` summarises the posture for HUD/animation.
+ */
+export interface CompanionIntent {
+    /** `follow`/`hold` when idle at the anchor; `engage` a fresh threat; `assist` the owner's target. */
+    kind: "follow" | "hold" | "engage" | "assist";
+    /** Whether the companion leashes to the owner (follow modes) or its `home` (stay). */
+    anchor: "owner" | "home";
+    /** Resolved anchor world point — owner position or `home`; `null` when that point is unknown. */
+    leashTo: MobVec3 | null;
+    /** Leash radius (copied from the record) the game passes to the brain / clamps movement against. */
+    leashDistance: number;
+    /** Threat ids to expose as `MobBrainDeps.candidates()`; empty when the command forbids engaging. */
+    candidates: readonly string[];
+    /** The primary threat to engage/assist this tick — `candidates[0]`; `null` while following/holding. */
+    targetId: string | null;
+}
+/** Rule for turning one spent level-point into a stat gain. Absent from config ⇒ the stat can't be upgraded. */
+export interface CompanionStatUpgrade {
+    /** Amount a single point adds to the stat's `max` (and heals into `current`). */
+    increment: number;
+    /** Hard ceiling for the stat's `max`; spends that would exceed it are rejected. */
+    maxCap?: number;
+}
+/** Outcome of {@link CompanionRoster.spend}: the updated record + stat, or a rejection reason. */
+export type CompanionSpendResult = {
+    status: "ok";
+    record: CompanionRecord;
+    stat: StatValue;
+} | {
+    status: "rejected";
+    reason: string;
+};
+/** Per-companion configuration shared by every companion the roster mints. */
+export interface CompanionConfig {
+    /** Stat catalog seeded into each new companion's pool (via `entityStats.seedStatValues`). */
+    stats?: StatCatalog;
+    /** Per-stat upgrade rules consulted by {@link CompanionRoster.spend}. */
+    upgrades?: Record<string, CompanionStatUpgrade>;
+    /** Points granted on reaching a given level; default `1` per level. Inject `game/progression` curves here. */
+    pointsPerLevel?: (level: number) => number;
+    /** Level ceiling; `levelUp` past it is a no-op. Default `Infinity`. */
+    maxLevel?: number;
+    /** Level every companion starts at; default `1`. */
+    startLevel?: number;
+    /** Default leash radius for new companions; default `12`. */
+    leash?: number;
+}
+/** Options for {@link CompanionRoster.adopt}. */
+export interface CompanionAdoptOptions {
+    id?: string;
+    /** The {@link RosterEntry.id} this companion springs from — the ownership/catalog tie. */
+    sourceId?: string;
+    command?: CompanionCommand;
+    home?: MobVec3 | null;
+    leash?: number;
+    level?: number;
+    /** Override the config stat catalog for this one companion. */
+    stats?: StatCatalog;
+}
+/**
+ * A set of tamed companions keyed by companion id, scoped to owners. Wraps allegiance/command
+ * state, per-companion levelled stats, and intent resolution behind create/command/level/
+ * snapshot/hydrate — the counterpart of `scene/roster` for creatures that fight beside you.
+ */
+export interface CompanionRoster {
+    /** Mint a companion for an owner (optionally tied to a {@link RosterEntry}). */
+    adopt(ownerId: string, options?: CompanionAdoptOptions): CompanionRecord;
+    release(companionId: string): boolean;
+    get(companionId: string): CompanionRecord | null;
+    ownerOf(companionId: string): string | null;
+    list(ownerId: string): readonly CompanionRecord[];
+    /** Set a companion's standing order; `null` if the id is unknown. */
+    command(companionId: string, command: CompanionCommand): CompanionRecord | null;
+    /** Park/clear a companion's `stay` anchor. */
+    setHome(companionId: string, home: MobVec3 | null): CompanionRecord | null;
+    setLeash(companionId: string, leash: number): CompanionRecord | null;
+    /** Gain `levels` levels (bounded by `maxLevel`), accruing points from `pointsPerLevel`. */
+    levelUp(companionId: string, levels?: number): CompanionRecord | null;
+    /** Spend one earned point into a stat per its {@link CompanionStatUpgrade} rule. */
+    spend(companionId: string, statId: string): CompanionSpendResult;
+    /** Resolve the companion's per-tick {@link CompanionIntent}; `null` if the id is unknown. */
+    resolveIntent(companionId: string, context: CompanionIntentContext): CompanionIntent | null;
+    /** Whole-store serializable copy — the save/replication seam. */
+    snapshot(): Record<string, CompanionRecord>;
+    hydrate(data: Record<string, CompanionRecord>): void;
+}
+/**
+ * Pure command → intent resolver. Maps a companion's standing order plus this tick's owner
+ * position, owner target, and nearby threats into the {@link CompanionIntent} a game feeds into
+ * `ai/mobBrain` (or executes directly). Deterministic and allocation-light — no import of the
+ * `@internal` brain factory; the two interoperate purely by shape.
+ *
+ * @capability companion-intent resolve a companion's command + threat context into a per-tick follow/hold/engage/assist intent
+ */
+export declare function resolveCompanionIntent(record: CompanionRecord, context: CompanionIntentContext): CompanionIntent;
+/**
+ * Build a {@link CompanionRoster}. Composes `scene/roster` ownership (via `ownerId`/`sourceId`),
+ * `scene/entityStats` for the per-companion stat pool, and {@link resolveCompanionIntent} for
+ * `ai/mobBrain`-shaped behavior — turning a captured creature into a loyal, levelling ally.
+ *
+ * @capability companion-roster manage tamed companions — allegiance, commands, per-companion stats/leveling, and mobBrain-shaped intent
+ */
+export declare function createCompanionRoster(config?: CompanionConfig): CompanionRoster;

package/dist/scene/companion.js

@@ -0,0 +1,193 @@
+import { seedStatValues, setStatValue } from "./entityStats.js";
+function dedupePush(out, id) {
+    if (!out.includes(id))
+        out.push(id);
+}
+function candidatesFor(command, ownerTargetId, threats) {
+    switch (command) {
+        case "passive":
+            return [];
+        case "follow":
+        case "stay":
+            return ownerTargetId === null ? [] : [ownerTargetId];
+        case "neutral":
+            return [...threats];
+        case "aggressive": {
+            const out = [];
+            for (const threat of threats)
+                dedupePush(out, threat);
+            if (ownerTargetId !== null)
+                dedupePush(out, ownerTargetId);
+            return out;
+        }
+    }
+}
+/**
+ * Pure command → intent resolver. Maps a companion's standing order plus this tick's owner
+ * position, owner target, and nearby threats into the {@link CompanionIntent} a game feeds into
+ * `ai/mobBrain` (or executes directly). Deterministic and allocation-light — no import of the
+ * `@internal` brain factory; the two interoperate purely by shape.
+ *
+ * @capability companion-intent resolve a companion's command + threat context into a per-tick follow/hold/engage/assist intent
+ */
+export function resolveCompanionIntent(record, context) {
+    const ownerTargetId = context.ownerTargetId ?? null;
+    const threats = context.threats ?? [];
+    const anchor = record.command === "stay" ? "home" : "owner";
+    const leashTo = anchor === "home" ? record.home : (context.ownerPosition ?? null);
+    const candidates = candidatesFor(record.command, ownerTargetId, threats);
+    const targetId = candidates.length > 0 ? candidates[0] : null;
+    let kind;
+    if (targetId === null) {
+        kind = anchor === "home" ? "hold" : "follow";
+    }
+    else if (targetId === ownerTargetId) {
+        kind = "assist";
+    }
+    else {
+        kind = "engage";
+    }
+    return { kind, anchor, leashTo, leashDistance: record.leash, candidates, targetId };
+}
+function cloneStats(stats) {
+    const out = {};
+    for (const [statId, value] of Object.entries(stats))
+        out[statId] = { ...value };
+    return out;
+}
+function cloneRecord(record) {
+    return {
+        id: record.id,
+        ownerId: record.ownerId,
+        sourceId: record.sourceId,
+        command: record.command,
+        home: record.home === null ? null : [record.home[0], record.home[1], record.home[2]],
+        leash: record.leash,
+        level: record.level,
+        unspentPoints: record.unspentPoints,
+        stats: cloneStats(record.stats),
+    };
+}
+/**
+ * Build a {@link CompanionRoster}. Composes `scene/roster` ownership (via `ownerId`/`sourceId`),
+ * `scene/entityStats` for the per-companion stat pool, and {@link resolveCompanionIntent} for
+ * `ai/mobBrain`-shaped behavior — turning a captured creature into a loyal, levelling ally.
+ *
+ * @capability companion-roster manage tamed companions — allegiance, commands, per-companion stats/leveling, and mobBrain-shaped intent
+ */
+export function createCompanionRoster(config = {}) {
+    const records = new Map();
+    const pointsPerLevel = config.pointsPerLevel ?? (() => 1);
+    const maxLevel = config.maxLevel ?? Number.POSITIVE_INFINITY;
+    const startLevel = config.startLevel ?? 1;
+    const defaultLeash = config.leash ?? 12;
+    let counter = 0;
+    const write = (record) => {
+        records.set(record.id, record);
+        return record;
+    };
+    const patch = (companionId, fn) => {
+        const record = records.get(companionId);
+        if (record === undefined)
+            return null;
+        return write(fn(record));
+    };
+    return {
+        adopt(ownerId, options = {}) {
+            counter += 1;
+            const id = options.id ?? `companion_${counter}`;
+            const seed = options.stats ?? config.stats ?? {};
+            const record = {
+                id,
+                ownerId,
+                sourceId: options.sourceId ?? null,
+                command: options.command ?? "follow",
+                home: options.home ?? null,
+                leash: options.leash ?? defaultLeash,
+                level: options.level ?? startLevel,
+                unspentPoints: 0,
+                stats: seedStatValues(seed),
+            };
+            return write(record);
+        },
+        release(companionId) {
+            return records.delete(companionId);
+        },
+        get(companionId) {
+            return records.get(companionId) ?? null;
+        },
+        ownerOf(companionId) {
+            return records.get(companionId)?.ownerId ?? null;
+        },
+        list(ownerId) {
+            const out = [];
+            for (const record of records.values())
+                if (record.ownerId === ownerId)
+                    out.push(record);
+            return out;
+        },
+        command(companionId, command) {
+            return patch(companionId, (record) => ({ ...record, command }));
+        },
+        setHome(companionId, home) {
+            return patch(companionId, (record) => ({
+                ...record,
+                home: home === null ? null : [home[0], home[1], home[2]],
+            }));
+        },
+        setLeash(companionId, leash) {
+            return patch(companionId, (record) => ({ ...record, leash }));
+        },
+        levelUp(companionId, levels = 1) {
+            return patch(companionId, (record) => {
+                let level = record.level;
+                let points = record.unspentPoints;
+                for (let i = 0; i < levels && level < maxLevel; i += 1) {
+                    level += 1;
+                    points += pointsPerLevel(level);
+                }
+                return { ...record, level, unspentPoints: points };
+            });
+        },
+        spend(companionId, statId) {
+            const record = records.get(companionId);
+            if (record === undefined)
+                return { status: "rejected", reason: `unknown companion "${companionId}"` };
+            if (record.unspentPoints <= 0)
+                return { status: "rejected", reason: "no unspent points" };
+            const upgrade = config.upgrades?.[statId];
+            if (upgrade === undefined)
+                return { status: "rejected", reason: `stat "${statId}" is not upgradable` };
+            const existing = record.stats[statId];
+            if (existing === undefined)
+                return { status: "rejected", reason: `unknown stat "${statId}"` };
+            const nextMax = existing.max + upgrade.increment;
+            if (upgrade.maxCap !== undefined && nextMax > upgrade.maxCap) {
+                return { status: "rejected", reason: `stat "${statId}" is at its cap` };
+            }
+            const stats = setStatValue(record.stats, statId, {
+                max: nextMax,
+                current: existing.current + upgrade.increment,
+            });
+            const updated = write({ ...record, unspentPoints: record.unspentPoints - 1, stats });
+            return { status: "ok", record: updated, stat: updated.stats[statId] };
+        },
+        resolveIntent(companionId, context) {
+            const record = records.get(companionId);
+            if (record === undefined)
+                return null;
+            return resolveCompanionIntent(record, context);
+        },
+        snapshot() {
+            const out = {};
+            for (const [id, record] of records)
+                out[id] = cloneRecord(record);
+            return out;
+        },
+        hydrate(data) {
+            records.clear();
+            for (const [id, record] of Object.entries(data))
+                records.set(id, cloneRecord(record));
+        },
+    };
+}

package/dist/scene/entityStats.d.ts

@@ -1,12 +1,9 @@
-export interface StatValue {
-    current: number;
-    max: number;
-    min: number;
+import { type StatPool, type StatPoolAccess, type StatPoolPatch } from "../stats/statPool.js";
+/** Native entity-stat name retained as a compatibility bridge to the portable pool model. */
+export interface StatValue extends StatPool {
 }
-export interface StatValuePatch {
-    current?: number;
-    max?: number;
-    min?: number;
+/** Native entity-stat patch retained as a compatibility bridge. */
+export interface StatValuePatch extends StatPoolPatch {
 }
 export type StatValueMap = Record<string, StatValue>;
 export type StatCatalog = Record<string, {
@@ -40,7 +37,8 @@ export declare function snapshotEntityStats(store: ReadonlyMap<string, StatValue
  * @internal
  */
 export declare function hydrateEntityStats(store: Map<string, StatValueMap>, data: Record<string, StatValueMap>): void;
-export interface EntityStatsApi {
+/** Native entity-stat adapter over the portable {@link StatPoolAccess} contract. */
+export interface EntityStatsApi extends StatPoolAccess {
     get(instanceId: string, statId: string): StatValue | null;
     set(instanceId: string, statId: string, patch: StatValuePatch): boolean;
     delta(instanceId: string, statId: string, amount: number): null | {

package/dist/scene/entityStats.js

@@ -1,6 +1,4 @@
-function clamp(value, min, max) {
-    return Math.min(max, Math.max(min, value));
-}
+import { changeStatPool, createStatPool, patchStatPool, } from "../stats/statPool.js";
 /** @internal */
 export function getStatValue(map, statId) {
     return map[statId] ?? null;
@@ -8,10 +6,10 @@ export function getStatValue(map, statId) {
 /** @internal */
 export function setStatValue(map, statId, patch) {
     const existing = map[statId];
-    const max = patch.max ?? existing?.max ?? 0;
-    const min = patch.min ?? existing?.min ?? 0;
-    const current = clamp(patch.current ?? existing?.current ?? max, min, max);
-    return { ...map, [statId]: { current, max, min } };
+    const next = existing === undefined
+        ? createStatPool({ max: patch.max ?? 0, min: patch.min, current: patch.current })
+        : patchStatPool(existing, patch);
+    return { ...map, [statId]: next };
 }
 /** @internal */
 export function applyPoolDelta(map, statId, amount) {
@@ -19,23 +17,26 @@ export function applyPoolDelta(map, statId, amount) {
     if (existing === undefined) {
         return { status: "rejected", reason: `unknown stat "${statId}"` };
     }
-    const current = clamp(existing.current + amount, existing.min, existing.max);
-    const stat = { ...existing, current };
+    const change = changeStatPool(existing, amount);
+    const stat = change.pool;
+    // No-op change: `changeStatPool` handed back the same pool reference, so keep
+    // the existing map too — callers can guard on reference identity.
+    if (stat === existing) {
+        return { status: "ok", map, stat, hitMin: change.hitMin, hitMax: change.hitMax };
+    }
     return {
         status: "ok",
         map: { ...map, [statId]: stat },
         stat,
-        hitMin: current === existing.min,
-        hitMax: current === existing.max,
+        hitMin: change.hitMin,
+        hitMax: change.hitMax,
     };
 }
 /** @internal */
 export function seedStatValues(catalogStats) {
     const map = {};
     for (const [statId, declaration] of Object.entries(catalogStats)) {
-        const min = declaration.min ?? 0;
-        const current = clamp(declaration.current ?? declaration.max, min, declaration.max);
-        map[statId] = { current, max: declaration.max, min };
+        map[statId] = createStatPool(declaration);
     }
     return map;
 }
@@ -85,10 +86,13 @@ export function createEntityStatsApi(resolve) {
             const map = resolve(instanceId);
             if (map === undefined)
                 return { reason: `unknown instance "${instanceId}"` };
+            const existing = map[statId];
             const result = applyPoolDelta(map, statId, amount);
             if (result.status === "rejected")
                 return { reason: result.reason };
-            map[statId] = result.stat;
+            // Skip the store write when nothing moved so reference guards stay stable.
+            if (result.stat !== existing)
+                map[statId] = result.stat;
             return null;
         },
     };

package/dist/scene/sceneKinds.d.ts

@@ -121,12 +121,28 @@ export interface ParamGroup {
     /** Start collapsed. Default expanded. */
     collapsed?: boolean;
 }
+/**
+ * A named slider/weight bundle for a kind — a saved set of field values the inspector (or the
+ * `apply_preset` verb) writes into an object's `meta` in one patch, ready to tweak afterwards.
+ * Presets are plain data on the schema, so kinds ship archetypes and games can override the
+ * registration with their own.
+ */
+export interface ParamPreset {
+    id: string;
+    label?: string;
+    /** Field values the preset writes; fields not listed keep their current values. */
+    values: Readonly<Record<string, unknown>>;
+}
 /** A kind's full parameter surface: an ordered list of fields the inspector renders top-to-bottom. */
 export interface ParamSchema {
     fields: readonly ParamField[];
     /** Optional named sections; fields reference one by `group`. Ungrouped fields render first, headerless. */
     groups?: readonly ParamGroup[];
+    /** Optional named field-value bundles the inspector offers as one-click applies. */
+    presets?: readonly ParamPreset[];
 }
+/** Look up a schema preset by id, or undefined — the seam `apply_preset` and games resolve bundles through. */
+export declare function findSchemaPreset(schema: ParamSchema, id: string): ParamPreset | undefined;
 /** Parsed params after `parseParams`: every schema field present with a validated, defaulted value. */
 export type ParsedParams = Record<string, number | boolean | string | WeightedParamEntry[]>;
 /**

package/dist/scene/sceneKinds.js

@@ -5,6 +5,10 @@
  * party ship a new authorable "studio" (pole line, water, bookcase) — schema + resolver here, a
  * matching renderer in `shell` — without editing editor or engine files. Scatter is the proof adopter.
  */
+/** Look up a schema preset by id, or undefined — the seam `apply_preset` and games resolve bundles through. */
+export function findSchemaPreset(schema, id) {
+    return schema.presets?.find((preset) => preset.id === id);
+}
 function num(value, fallback, min, max) {
     let n = typeof value === "number" && Number.isFinite(value) ? value : fallback;
     if (min !== undefined)

package/dist/scene/sceneRaycast.js

@@ -1,4 +1,5 @@
 import { colliderBounds, colliderWorldCenter, defaultEntityColliders, defaultObjectColliders, resolveColliders, } from "./colliders.js";
+import { raycastCollisionMesh } from "./collisionMesh.js";
 import { intersectAabb, normalizeDirection } from "./objectQuery.js";
 function excluded(exclude, id) {
     if (exclude === undefined)
@@ -54,6 +55,20 @@ function rayHitsCollider(origin, direction, maxDistance, collider, position, rot
             ],
         };
     }
+    if (collider.shape.kind === "mesh") {
+        const hit = raycastCollisionMesh(collider.shape.mesh, origin, direction, maxDistance, position, rotationY, collider.shape.meshScale, collider.shape.meshTranslate);
+        if (hit === null)
+            return null;
+        return {
+            distance: hit.distance,
+            normal: hit.normal,
+            point: [
+                origin[0] + direction[0] * hit.distance,
+                origin[1] + direction[1] * hit.distance,
+                origin[2] + direction[2] * hit.distance,
+            ],
+        };
+    }
     const bounds = colliderBounds(collider, position, rotationY);
     const hit = intersectAabb(origin, direction, bounds.min, bounds.max, maxDistance);
     if (hit === null)

package/dist/stats/spawnLevelStats.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Per-stat growth definition for one species. `base` is the level-1 value of the stat; `growth`
+ * is how much a single distributed point adds, expressed as a fraction of `base` — so a point on a
+ * `growth: 0.1` stat is worth +10% of base. The resolved value is `base * (1 + points * growth)`.
+ */
+export interface SpawnStatDef {
+    base: number;
+    growth: number;
+}
+/**
+ * A species' stat table: every stat the creature owns keyed to its {@link SpawnStatDef}. The key
+ * order is the deterministic order random points are distributed over, so a serialized species
+ * definition reproduces the same rolls under the same rng sequence.
+ */
+export type SpawnSpeciesDef<TStat extends string> = Record<TStat, SpawnStatDef>;
+/**
+ * A single creature's serializable stat record — a reference to its species (`speciesId`), the
+ * current `level`, the per-stat count of distributed points, and how many post-capture domestic
+ * levels have been spent. Plain data: round-trips through JSON, save/load, and multiplayer sync.
+ * Resolve display values with {@link resolveSpawnStats}.
+ */
+export interface CreatureStatInstance<TStat extends string> {
+    speciesId: string;
+    level: number;
+    points: Record<TStat, number>;
+    domesticLevels: number;
+}
+/**
+ * Outcome of {@link applyCaptureEffectiveness}: the granted `bonusLevels`, the `tamedLevel`
+ * (wild level plus bonus levels), and the post-capture {@link CreatureStatInstance}.
+ * @internal
+ */
+export interface CaptureResult<TStat extends string> {
+    bonusLevels: number;
+    tamedLevel: number;
+    instance: CreatureStatInstance<TStat>;
+}
+/**
+ * Options for {@link spendDomesticLevel}. `maxDomesticLevels` caps how many post-capture levels a
+ * creature may spend; once reached, further spends are refused.
+ * @internal
+ */
+export interface SpendLevelOptions {
+    maxDomesticLevels?: number;
+}
+/**
+ * Result of {@link spendDomesticLevel}: the resulting instance and whether the level was applied
+ * (`spent: false` when the domestic-level cap blocked it, leaving the instance untouched).
+ * @internal
+ */
+export interface SpendLevelResult<TStat extends string> {
+    instance: CreatureStatInstance<TStat>;
+    spent: boolean;
+}
+/**
+ * Roll a fresh wild creature at `level`: distribute `(level - 1)` points randomly across the
+ * species' stats using the injected rng and return a serializable {@link CreatureStatInstance}.
+ * Deterministic — the same rng sequence yields the same point spread. Levels below 1 clamp to 1
+ * (no points). Use `seededRng` from `../random/rng` for a persisted, reproducible stream.
+ *
+ * @capability spawn-level-roll distribute a wild creature's spawn level into random per-stat points
+ */
+export declare function rollSpawnInstance<TStat extends string>(speciesId: string, species: SpawnSpeciesDef<TStat>, level: number, rng: () => number): CreatureStatInstance<TStat>;
+/**
+ * Resolve an instance's live stat values from its distributed points:
+ * `value = base * (1 + points * growth)` per stat. Stats with zero points return their base.
+ *
+ * @capability spawn-stat-values resolve a creature's per-stat values from its distributed points
+ */
+export declare function resolveSpawnStats<TStat extends string>(species: SpawnSpeciesDef<TStat>, instance: CreatureStatInstance<TStat>): Record<TStat, number>;
+/**
+ * Bonus levels granted by a capture at the given effectiveness:
+ * `floor(level * clamp01(effectiveness) / 2)`. A perfect (1.0) capture grants half the wild
+ * level; a botched (0) capture grants none. Effectiveness outside `[0,1]` clamps.
+ *
+ * @capability capture-bonus-levels convert wild level and capture effectiveness into bonus levels
+ */
+export declare function captureBonusLevels(level: number, effectiveness: number): number;
+/**
+ * Apply a capture at the given effectiveness: compute bonus levels via {@link captureBonusLevels},
+ * distribute those extra points randomly with the injected rng, and return the post-capture
+ * instance (level raised to the tamed total) alongside the granted bonus levels and tamed level.
+ * The input instance is not mutated.
+ *
+ * @capability capture-effectiveness-tame apply capture effectiveness to grant and distribute bonus levels
+ */
+export declare function applyCaptureEffectiveness<TStat extends string>(species: SpawnSpeciesDef<TStat>, instance: CreatureStatInstance<TStat>, effectiveness: number, rng: () => number): CaptureResult<TStat>;
+/**
+ * Spend one earned post-capture level into `stat`, adding a single growth increment (one point)
+ * and raising both `level` and `domesticLevels`. When `maxDomesticLevels` is set and already
+ * reached, the spend is refused (`spent: false`) and the instance is returned untouched. Pure:
+ * returns a new instance rather than mutating the input.
+ *
+ * @capability domestic-level-spend spend an earned post-capture level into a chosen stat under a cap
+ */
+export declare function spendDomesticLevel<TStat extends string>(instance: CreatureStatInstance<TStat>, stat: TStat, options?: SpendLevelOptions): SpendLevelResult<TStat>;
+/**
+ * Deep-copy an instance into a detached, serializable record — the transport/save counterpart of
+ * {@link restoreSpawnInstance}. Copies the points map so later edits don't leak into the snapshot.
+ *
+ * @capability spawn-instance-snapshot deep-copy a creature stat instance into a serializable record
+ */
+export declare function snapshotSpawnInstance<TStat extends string>(instance: CreatureStatInstance<TStat>): CreatureStatInstance<TStat>;
+/**
+ * Rehydrate a creature stat instance from decoded data (e.g. `JSON.parse` output), returning a
+ * fresh deep copy the caller owns. Inverse of {@link snapshotSpawnInstance}.
+ *
+ * @capability spawn-instance-restore rehydrate a creature stat instance from decoded snapshot data
+ */
+export declare function restoreSpawnInstance<TStat extends string>(data: CreatureStatInstance<TStat>): CreatureStatInstance<TStat>;