@jgengine/core 0.18.1 → 0.21.0

package/dist/work/expedition.js

@@ -0,0 +1,195 @@
+import { appendFeed } from "../game/feed.js";
+import { hashString, randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+import { accrueSince } from "../time/accrueSince.js";
+import { steppedCatchUp } from "../time/idleProgress.js";
+function nonnegative(value, name) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new RangeError(`${name} must be finite and nonnegative`);
+    return value;
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new RangeError(`${name} must be a positive safe integer`);
+    return value;
+}
+function validate(config, state, nowMs) {
+    if (!Number.isFinite(nowMs) || !Number.isFinite(state.startedAtMs) || !Number.isFinite(state.lastSettledMs))
+        throw new RangeError("Expedition timestamps must be finite");
+    if (state.lastSettledMs < state.startedAtMs || (state.returnUntilMs !== null && !Number.isFinite(state.returnUntilMs)))
+        throw new RangeError("Invalid expedition time frontier");
+    if (!Number.isSafeInteger(state.cursor))
+        throw new RangeError("Expedition RNG cursor must be a safe integer");
+    positiveInteger(config.tickMs, "tickMs");
+    positiveInteger(config.carryCap, "carryCap");
+    positiveInteger(config.maxTicksPerSettle ?? 10_000, "maxTicksPerSettle");
+    positiveInteger(config.logLimit ?? 200, "logLimit");
+    nonnegative(config.returnFraction, "returnFraction");
+    nonnegative(state.hp, "hp");
+    nonnegative(state.exposure, "exposure");
+    nonnegative(state.elapsedMs, "elapsedMs");
+    for (const count of Object.values(state.supplies))
+        if (!Number.isSafeInteger(count) || count < 0)
+            throw new RangeError("Supply counts must be nonnegative safe integers");
+}
+function record(config, state, event, text) {
+    return { ...state, log: appendFeed(state.log, { ...event, text: text ?? config.describe?.(event, state) ?? "" }, { limit: config.logLimit ?? 200 }) };
+}
+function itemUnits(drops) {
+    let units = 0;
+    for (const drop of drops)
+        if (drop.item !== undefined)
+            units += nonnegative(drop.count, "Item count");
+    return nonnegative(units, "Carried item units");
+}
+function acceptLoot(cap, carried, drops) {
+    let remaining = Math.max(0, cap - itemUnits(carried));
+    const next = carried.map(drop => ({ ...drop }));
+    const accepted = [];
+    for (const drop of drops) {
+        const count = nonnegative(drop.count, "Drop count");
+        if ((drop.item === undefined) === (drop.currency === undefined))
+            throw new RangeError("Expedition drops need exactly one item or currency id");
+        if (drop.item !== undefined && !Number.isSafeInteger(count))
+            throw new RangeError("Item counts must be nonnegative safe integers");
+        const admitted = drop.item === undefined ? count : Math.min(count, remaining);
+        if (drop.item !== undefined)
+            remaining -= admitted;
+        if (admitted === 0)
+            continue;
+        const incoming = { ...drop, count: admitted };
+        accepted.push(incoming);
+        const existing = next.find(entry => drop.item !== undefined ? entry.item === drop.item : entry.currency === drop.currency && entry.item === undefined);
+        if (existing === undefined)
+            next.push({ ...incoming });
+        else
+            existing.count = nonnegative(existing.count + admitted, "Carried count");
+    }
+    return { carried: next, accepted };
+}
+function arrive(config, state, nowMs) {
+    if (state.status !== "returning" || state.returnUntilMs === null || nowMs < state.returnUntilMs)
+        return state;
+    const at = state.returnUntilMs;
+    return record(config, { ...state, status: "home", lastSettledMs: at }, { at, kind: "return" });
+}
+function beginReturn(config, state, at) {
+    const elapsedMs = Math.max(state.elapsedMs, at - state.startedAtMs);
+    const returnUntilMs = at + elapsedMs * config.returnFraction;
+    if (!Number.isFinite(returnUntilMs))
+        throw new RangeError("Expedition return deadline overflowed");
+    return arrive(config, record(config, { ...state, status: "returning", elapsedMs, returnUntilMs, lastSettledMs: at }, { at, kind: "recall" }), at);
+}
+/**
+ * Dispatch plain expedition state with a persisted seeded cursor; no clock, scheduler or storage is owned.
+ *
+ * @capability expedition-dispatch dispatch a saveable timed away mission with finite supplies and a seeded RNG cursor
+ */
+export function dispatchExpedition(input) {
+    if (!Number.isFinite(input.startAtMs))
+        throw new RangeError("startAtMs must be finite");
+    nonnegative(input.hp, "hp");
+    nonnegative(input.exposure ?? 0, "exposure");
+    const supplies = { ...input.supplies };
+    for (const count of Object.values(supplies))
+        if (!Number.isSafeInteger(count) || count < 0)
+            throw new RangeError("Supply counts must be nonnegative safe integers");
+    return { id: input.id, status: input.hp === 0 ? "dead" : "exploring", startedAtMs: input.startAtMs, lastSettledMs: input.startAtMs,
+        elapsedMs: 0, returnUntilMs: null, hp: input.hp, exposure: input.exposure ?? 0, supplies, carried: [], log: [], seed: input.seed, cursor: randomSeedFrom(hashString(input.seed)) };
+}
+/**
+ * Replay due event ticks using the existing stepped catch-up primitive. Order is loot → hazard → ordered
+ * supplies → death → capacity recall. Unprocessed ticks retain their frontier; returning never rolls or
+ * takes damage. Auto-recall uses the triggering tick's time, including offline arrival in the same call.
+ *
+ * @capability expedition-settle settle bounded offline expedition ticks without losing supplies rewards or RNG continuity
+ */
+export function settleExpedition(config, state, nowMs) {
+    validate(config, state, nowMs);
+    if (nowMs < state.lastSettledMs || (state.status === "exploring" && nowMs < state.startedAtMs + state.elapsedMs) || state.status === "dead" || state.status === "home")
+        return state;
+    if (state.status === "returning")
+        return arrive(config, state, nowMs);
+    let next = state;
+    const step = config.randomStep ?? stepRandomSeed;
+    const window = accrueSince(state.lastSettledMs, nowMs);
+    nonnegative(window.elapsedMs, "Catch-up duration");
+    // Normalize to whole one-unit ticks so fractional-second division cannot lose a due millisecond.
+    const ticks = Math.floor(window.elapsedMs / config.tickMs);
+    steppedCatchUp(ticks, 1, () => {
+        if (next.status !== "exploring")
+            return;
+        const at = next.lastSettledMs + config.tickMs;
+        next = { ...next, lastSettledMs: at, elapsedMs: at - next.startedAtMs };
+        let cursor = next.cursor;
+        const rng = () => {
+            const [value, following] = step(cursor);
+            if (!Number.isFinite(value) || value < 0 || value >= 1 || !Number.isSafeInteger(following))
+                throw new RangeError("Expedition RNG must return a [0,1) value and safe integer cursor");
+            cursor = following;
+            return value;
+        };
+        const resolution = config.loot.resolve({ ctx: config.lootCtx(next), rng, seed: next.seed });
+        const accepted = acceptLoot(config.carryCap, next.carried, resolution.drops);
+        next = { ...next, carried: accepted.carried };
+        if (resolution.drops.length > 0)
+            next = record(config, next, { at, kind: "loot", drops: accepted.accepted, loot: resolution });
+        const hazard = config.hazard?.(next, rng) ?? {};
+        const exposure = nonnegative(next.exposure + nonnegative(hazard.exposure ?? 0, "Hazard exposure"), "Exposure");
+        const hp = Math.min(nonnegative(config.maxHp({ ...next, exposure }), "maxHp"), Math.max(0, next.hp - nonnegative(hazard.damage ?? 0, "Hazard damage")));
+        const hpDelta = hp - next.hp, exposureDelta = exposure - next.exposure;
+        next = { ...next, hp, exposure };
+        if (hpDelta !== 0 || exposureDelta !== 0)
+            next = record(config, next, { at, kind: "hazard", hpDelta, exposureDelta });
+        for (const notice of hazard.notices ?? [])
+            next = record(config, next, { at, kind: notice.kind }, notice.text);
+        for (const rule of config.supplies ?? []) {
+            const count = Object.hasOwn(next.supplies, rule.key) ? next.supplies[rule.key] : 0;
+            const restoreHp = nonnegative(rule.restoreHp ?? 0, "Supply restoration"), clearExposure = nonnegative(rule.clearExposure ?? 0, "Supply cleansing");
+            if (count <= 0 || !rule.when(next))
+                continue;
+            const exposure = Math.max(0, next.exposure - clearExposure);
+            const hp = Math.min(nonnegative(config.maxHp({ ...next, exposure }), "maxHp"), nonnegative(next.hp + restoreHp, "Restored hp"));
+            if (hp === next.hp && exposure === next.exposure)
+                continue;
+            const hpDelta = hp - next.hp, exposureDelta = exposure - next.exposure;
+            next = { ...next, hp, exposure, supplies: { ...next.supplies, [rule.key]: count - 1 } };
+            next = record(config, next, { at, kind: "supply", supply: rule.key, hpDelta, exposureDelta });
+        }
+        next = { ...next, cursor };
+        if (next.hp <= 0)
+            next = record(config, { ...next, status: "dead" }, { at, kind: "death" });
+        else if (itemUnits(next.carried) >= config.carryCap)
+            next = beginReturn(config, next, at);
+    }, config.maxTicksPerSettle ?? 10_000);
+    if (next.status === "exploring" && nowMs - next.lastSettledMs < config.tickMs) {
+        const elapsedMs = Math.max(next.elapsedMs, nowMs - next.startedAtMs);
+        nonnegative(elapsedMs, "Exploring duration");
+        if (elapsedMs !== next.elapsedMs)
+            next = { ...next, elapsedMs };
+        if (itemUnits(next.carried) >= config.carryCap)
+            next = beginReturn(config, next, nowMs);
+    }
+    return arrive(config, next, nowMs);
+}
+/**
+ * Settle first, then recall safely. If the catch-up budget leaves due exploring ticks, return that state
+ * without recalling; repeat at the same target until the frontier catches up. Dead state never revives.
+ *
+ * @capability expedition-recall begin a safe fractional-time return after settling the pending expedition frontier
+ */
+export function recallExpedition(config, state, nowMs) {
+    const next = settleExpedition(config, state, nowMs);
+    return next.status === "exploring" && nowMs >= next.startedAtMs + next.elapsedMs && nowMs >= next.lastSettledMs && nowMs - next.lastSettledMs < config.tickMs ? beginReturn(config, next, nowMs) : next;
+}
+/**
+ * Settle first, then complete a live return instantly. Caller owns payment/authorization; pending ticks
+ * remain unsettled when the budget is exhausted, and dead/home state is never changed.
+ *
+ * @capability expedition-return complete an authorized instant return without skipping unsettled ticks or reviving death
+ */
+export function returnExpeditionNow(config, state, nowMs) {
+    const next = settleExpedition(config, state, nowMs);
+    if (next.status === "dead" || next.status === "home" || nowMs < next.lastSettledMs || (next.status === "exploring" && nowMs < next.startedAtMs + next.elapsedMs) || (next.status === "exploring" && nowMs - next.lastSettledMs >= config.tickMs))
+        return next;
+    return record(config, { ...next, status: "home", returnUntilMs: nowMs, lastSettledMs: nowMs }, { at: nowMs, kind: "return" });
+}

package/dist/work/staffedStation.d.ts

@@ -0,0 +1,29 @@
+/** One assigned worker's caller-resolved contribution; stat names and modifiers stay caller-owned. */
+export interface StationWorker {
+    readonly id: string;
+    readonly stat: number;
+}
+/** Serializable staffing snapshot. The caller owns assignment, unique worker ids, and stable order. */
+export interface StaffedStation {
+    readonly stationId: string;
+    /** Nonnegative whole slot count; fractional values round down and nonfinite values admit no workers. */
+    readonly slots: number;
+    /** Only the first `slots` entries contribute; overflow assignments are not reordered or mutated. */
+    readonly workers: readonly StationWorker[];
+}
+/** Caller-owned output tuning in production cycles per game-second. */
+export interface StationRateTuning {
+    readonly base: number;
+    readonly perStat: number;
+    /** Applied to the whole rate, including base; defaults to 1 and clamps to 0…1. */
+    readonly efficiency?: number;
+}
+/**
+ * Resolve `(base + perStat * sum(admitted worker stats)) * efficiency` without allocation.
+ * Empty staffing retains base production. Negative/nonfinite contributions are zero; a nonfinite
+ * efficiency or overflowing result stops production with rate zero. Invalid workers still occupy
+ * their ordered slots. Assign the result to a `ProductionBuildingDef.rate` for `tickProduction`.
+ *
+ * @capability staffed-station-rate turn bounded caller-owned worker stats and efficiency into a production rate
+ */
+export declare function stationOutputRate(station: StaffedStation, tuning: StationRateTuning): number;

package/dist/work/staffedStation.js

@@ -0,0 +1,27 @@
+function contribution(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * Resolve `(base + perStat * sum(admitted worker stats)) * efficiency` without allocation.
+ * Empty staffing retains base production. Negative/nonfinite contributions are zero; a nonfinite
+ * efficiency or overflowing result stops production with rate zero. Invalid workers still occupy
+ * their ordered slots. Assign the result to a `ProductionBuildingDef.rate` for `tickProduction`.
+ *
+ * @capability staffed-station-rate turn bounded caller-owned worker stats and efficiency into a production rate
+ */
+export function stationOutputRate(station, tuning) {
+    const efficiency = Math.min(1, contribution(tuning.efficiency ?? 1));
+    if (efficiency === 0)
+        return 0;
+    const base = contribution(tuning.base);
+    const perStat = contribution(tuning.perStat);
+    if (perStat === 0)
+        return base * efficiency;
+    const slots = Number.isFinite(station.slots) ? Math.max(0, Math.floor(station.slots)) : 0;
+    const count = Math.min(slots, station.workers.length);
+    let total = 0;
+    for (let index = 0; index < count; index += 1)
+        total += contribution(station.workers[index].stat);
+    const rate = (base + perStat * total) * efficiency;
+    return Number.isFinite(rate) ? rate : 0;
+}

package/dist/world/authoredAnimation.d.ts

@@ -0,0 +1,38 @@
+import type { AuthoredAnimation } from "./authoredObjects.js";
+/** Structural marker input; immutable editor scene documents satisfy it. */
+export interface AuthoredAnimationDocumentLike {
+    readonly markers: readonly {
+        readonly id: string;
+        readonly meta?: Readonly<Record<string, unknown>>;
+    }[];
+}
+/** Rejected saved animation data with a document location and a repair. */
+export interface AuthoredAnimationDiagnostic {
+    readonly path: string;
+    readonly message: string;
+    readonly repair: string;
+}
+/** Resolved marker animation or the caller's unchanged default, with rejected-value diagnostics. */
+export interface AuthoredAnimationResult {
+    readonly animation: AuthoredAnimation | undefined;
+    readonly diagnostics: readonly AuthoredAnimationDiagnostic[];
+}
+/**
+ * Resolves a caller-selected marker's animation. Authored configuration replaces game defaults;
+ * omitted or malformed data retains the exact default. Partial roles remain available for editing.
+ * Asset clip and rig compatibility is diagnosed by the animation renderer.
+ * @capability authored-animation bind saved character animation without copying game-side validation
+ */
+export declare function readAuthoredAnimation(document: AuthoredAnimationDocumentLike, markerId: string, defaults?: AuthoredAnimation): AuthoredAnimationResult;
+/**
+ * Validates one saved animation value at the caller's document path without scanning markers.
+ * Omitted or malformed values retain the exact default; valid authored configuration replaces it whole.
+ * @capability authored-animation validate a located animation override in a single-pass document resolver
+ */
+export declare function readAuthoredAnimationValue(value: unknown, path: string, defaults?: AuthoredAnimation): AuthoredAnimationResult;
+/**
+ * Reads the latest immutable document each call, validating only when document identity changes.
+ * The caller owns the marker-to-character association and its asset-specific animation defaults.
+ * @capability authored-animation consume live authored character animation with bounded per-frame work
+ */
+export declare function createAuthoredAnimationReader(getDocument: () => AuthoredAnimationDocumentLike, markerId: string, defaults?: AuthoredAnimation): () => AuthoredAnimationResult;

package/dist/world/authoredAnimation.js

@@ -0,0 +1,99 @@
+import { validateAnimGraph } from "../anim/animGraph.js";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Resolves a caller-selected marker's animation. Authored configuration replaces game defaults;
+ * omitted or malformed data retains the exact default. Partial roles remain available for editing.
+ * Asset clip and rig compatibility is diagnosed by the animation renderer.
+ * @capability authored-animation bind saved character animation without copying game-side validation
+ */
+export function readAuthoredAnimation(document, markerId, defaults) {
+    const index = document.markers.findIndex((marker) => marker.id === markerId);
+    return readAuthoredAnimationValue(document.markers[index]?.meta?.animation, `markers[${index}].meta.animation`, defaults);
+}
+/**
+ * Validates one saved animation value at the caller's document path without scanning markers.
+ * Omitted or malformed values retain the exact default; valid authored configuration replaces it whole.
+ * @capability authored-animation validate a located animation override in a single-pass document resolver
+ */
+export function readAuthoredAnimationValue(value, path, defaults) {
+    const diagnostics = [];
+    if (value === undefined)
+        return { animation: defaults, diagnostics };
+    if (value === "auto" || value === "none")
+        return { animation: value, diagnostics };
+    const reject = (location, message, requirement) => {
+        diagnostics.push({ path: location, message, repair: `Use ${requirement}, or remove the animation override to inherit the game setting.` });
+    };
+    if (!record(value)) {
+        reject(path, "Animation must be an object, auto, or none", "an animation object, auto, or none");
+        return { animation: defaults, diagnostics };
+    }
+    if (value.clock !== undefined && value.clock !== "real" && value.clock !== "game")
+        reject(`${path}.clock`, "clock must be real or game", "real or game");
+    if (value.auto !== undefined && value.auto !== true)
+        reject(`${path}.auto`, "auto must be true when supplied", "true, or omit auto to use explicit configuration");
+    for (const key of ["clip"]) {
+        if (value[key] !== undefined && typeof value[key] !== "string")
+            reject(`${path}.${key}`, `${key} must be a string`, "a clip-name string");
+    }
+    for (const key of ["loop", "paused"]) {
+        if (value[key] !== undefined && typeof value[key] !== "boolean")
+            reject(`${path}.${key}`, `${key} must be a boolean`, "true or false");
+    }
+    for (const key of ["timeScale", "time"]) {
+        if (value[key] !== undefined && (typeof value[key] !== "number" || !Number.isFinite(value[key])))
+            reject(`${path}.${key}`, `${key} must be a finite number`, "a finite number");
+    }
+    if (value.states !== undefined) {
+        if (!record(value.states))
+            reject(`${path}.states`, "states must be an object", "a role-mapping object");
+        else {
+            for (const key of ["idle", "walk", "run"]) {
+                if (value.states[key] !== undefined && typeof value.states[key] !== "string")
+                    reject(`${path}.states.${key}`, `${key} must be a string`, "a clip-name string");
+            }
+            for (const key of ["walkSpeed", "runSpeed", "fadeSec"]) {
+                const number = value.states[key];
+                if (number !== undefined && (typeof number !== "number" || !Number.isFinite(number)))
+                    reject(`${path}.states.${key}`, `${key} must be a finite number`, "a finite number");
+            }
+        }
+    }
+    if (value.oneShots !== undefined) {
+        if (!record(value.oneShots))
+            reject(`${path}.oneShots`, "oneShots must be an object", "an event-to-clip mapping object");
+        else
+            for (const [event, clips] of Object.entries(value.oneShots)) {
+                if (typeof clips !== "string" && !(Array.isArray(clips) && clips.every((clip) => typeof clip === "string")))
+                    reject(`${path}.oneShots[${JSON.stringify(event)}]`, "One-shot clips must be a string or an array of strings", "a clip-name string or an array of clip-name strings");
+            }
+    }
+    let animation = value;
+    if (value.graph !== undefined) {
+        const graph = validateAnimGraph(value.graph);
+        for (const diagnostic of graph.diagnostics)
+            diagnostics.push({ ...diagnostic, path: `${path}.graph${diagnostic.path === "" ? "" : `.${diagnostic.path}`}` });
+        if (graph.graph !== undefined)
+            animation = { ...value, graph: graph.graph };
+    }
+    return { animation: diagnostics.length === 0 ? animation : defaults, diagnostics };
+}
+/**
+ * Reads the latest immutable document each call, validating only when document identity changes.
+ * The caller owns the marker-to-character association and its asset-specific animation defaults.
+ * @capability authored-animation consume live authored character animation with bounded per-frame work
+ */
+export function createAuthoredAnimationReader(getDocument, markerId, defaults) {
+    let previous;
+    let result;
+    return () => {
+        const document = getDocument();
+        if (document !== previous) {
+            result = readAuthoredAnimation(document, markerId, defaults);
+            previous = document;
+        }
+        return result;
+    };
+}

package/dist/world/authoredObjects.d.ts

@@ -1,3 +1,4 @@
+import { type AuthoredAnimationDiagnostic } from "./authoredAnimation.js";
 import type { ModelAnimationConfig } from "../game/playableGame.js";
 import type { SceneMarkerLike } from "./sceneShapes.js";
 /** A placement's authored rig animation override — the stored `marker.meta.animation` contract (#1274). */
@@ -53,10 +54,8 @@ export interface PlaceAuthoredObjectsOptions {
  */
 export declare function markerCatalogId(marker: AuthoredObjectMarkerLike): string | null;
 /**
- * The authored per-placement rig animation override stored at `marker.meta.animation` (#1274), or
- * `undefined` when absent/malformed. `"auto"` / `"none"` pass through as the string modes; any other
- * object is a `ModelAnimationConfig` the shell applies verbatim (validated at author time in the
- * editor). Runtime trusts the persisted document here exactly like it trusts position and rotation.
+ * Validated per-placement animation from `marker.meta.animation`. Missing or malformed overrides
+ * return undefined so the placed object retains its catalog animation; valid data replaces it whole.
  * @capability authored-objects per-placement animation override from marker.meta.animation
  */
 export declare function markerAnimation(marker: AuthoredObjectMarkerLike): AuthoredAnimation | undefined;
@@ -80,6 +79,18 @@ export interface ResolveAuthoredObjectsOptions {
  * @capability authored-objects place catalog mesh props from an editor document
  */
 export declare function resolveAuthoredObjects(document: AuthoredObjectsDocumentLike, options?: ResolveAuthoredObjectsOptions): AuthoredObject[];
+/** Resolved catalog props and located repairs for rejected per-placement animation overrides. */
+export interface AuthoredObjectsResult {
+    objects: AuthoredObject[];
+    diagnostics: readonly AuthoredAnimationDiagnostic[];
+}
+/**
+ * Resolves catalog props and validates their animation in one document pass. Rejected overrides
+ * are omitted so each model inherits its original catalog setting. Excluded and unplaced markers
+ * remain the responsibility of their own consumers.
+ * @capability authored-objects resolve static placements with located animation repairs
+ */
+export declare function resolveAuthoredObjectsWithDiagnostics(document: AuthoredObjectsDocumentLike, options?: ResolveAuthoredObjectsOptions): AuthoredObjectsResult;
 /**
  * Places resolved authored objects into an object store, grounding each on `sampleHeight(x,z)` plus
  * per-object and options vertical offsets. Returns the instance ids that were placed (or kept).
@@ -88,3 +99,12 @@ export declare function resolveAuthoredObjects(document: AuthoredObjectsDocument
 export declare function placeAuthoredObjects(store: AuthoredObjectPlaceTarget, objects: readonly AuthoredObject[], sampleHeight: (x: number, z: number) => number, options?: PlaceAuthoredObjectsOptions): string[];
 /** Convenience: resolve a document then place every authored catalog prop. */
 export declare function placeAuthoredObjectsFromDocument(store: AuthoredObjectPlaceTarget, document: AuthoredObjectsDocumentLike, sampleHeight: (x: number, z: number) => number, options?: PlaceAuthoredObjectsOptions): string[];
+/**
+ * Update changed authored placements and remove previous authored ids absent from the next document.
+ * Initial placement keeps game onInit state; unrelated document edits preserve runtime prop state.
+ * Call on document changes, never on simulation ticks; runtime-created objects remain untouched.
+ * @capability sync-authored-objects synchronize edited catalog prop poses, elevation and removal through the existing object store
+ */
+export declare function syncAuthoredObjects(store: AuthoredObjectPlaceTarget & {
+    remove(instanceId: string): boolean;
+}, objects: readonly AuthoredObject[], previousObjects: readonly AuthoredObject[], sampleHeight: (x: number, z: number) => number, options?: Pick<PlaceAuthoredObjectsOptions, "verticalOffset">): AuthoredObject[];

package/dist/world/authoredObjects.js

@@ -1,3 +1,4 @@
+import { readAuthoredAnimationValue } from "./authoredAnimation.js";
 function metaString(meta, key) {
     const value = meta?.[key];
     return typeof value === "string" && value.length > 0 ? value : null;
@@ -16,23 +17,13 @@ export function markerCatalogId(marker) {
         return marker.catalogId;
     return metaString(marker.meta, "catalogId");
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /**
- * The authored per-placement rig animation override stored at `marker.meta.animation` (#1274), or
- * `undefined` when absent/malformed. `"auto"` / `"none"` pass through as the string modes; any other
- * object is a `ModelAnimationConfig` the shell applies verbatim (validated at author time in the
- * editor). Runtime trusts the persisted document here exactly like it trusts position and rotation.
+ * Validated per-placement animation from `marker.meta.animation`. Missing or malformed overrides
+ * return undefined so the placed object retains its catalog animation; valid data replaces it whole.
  * @capability authored-objects per-placement animation override from marker.meta.animation
  */
 export function markerAnimation(marker) {
-    const value = marker.meta?.["animation"];
-    if (value === "auto" || value === "none")
-        return value;
-    if (isRecord(value))
-        return value;
-    return undefined;
+    return readAuthoredAnimationValue(marker.meta?.["animation"], "meta.animation").animation;
 }
 function markerVerticalOffset(marker) {
     const fromMeta = metaNumber(marker.meta, "verticalOffset") ??
@@ -55,15 +46,29 @@ export const ENTITY_MARKER_KINDS = ["mob", "boss"];
  * @capability authored-objects place catalog mesh props from an editor document
  */
 export function resolveAuthoredObjects(document, options = {}) {
+    return resolveAuthoredObjectsWithDiagnostics(document, options).objects;
+}
+/**
+ * Resolves catalog props and validates their animation in one document pass. Rejected overrides
+ * are omitted so each model inherits its original catalog setting. Excluded and unplaced markers
+ * remain the responsibility of their own consumers.
+ * @capability authored-objects resolve static placements with located animation repairs
+ */
+export function resolveAuthoredObjectsWithDiagnostics(document, options = {}) {
     const excluded = new Set(options.excludeKinds ?? ENTITY_MARKER_KINDS);
     const out = [];
-    for (const marker of document.markers) {
+    const diagnostics = [];
+    for (let index = 0; index < document.markers.length; index += 1) {
+        const marker = document.markers[index];
         if (excluded.has(marker.kind))
             continue;
         const catalogId = markerCatalogId(marker);
         if (catalogId === null)
             continue;
-        const animation = markerAnimation(marker);
+        const result = readAuthoredAnimationValue(marker.meta?.["animation"], `markers[${index}].meta.animation`);
+        const animation = result.animation;
+        for (const diagnostic of result.diagnostics)
+            diagnostics.push(diagnostic);
         out.push({
             catalogId,
             x: marker.position.x,
@@ -74,7 +79,7 @@ export function resolveAuthoredObjects(document, options = {}) {
             ...(animation === undefined ? {} : { animation }),
         });
     }
-    return out;
+    return { objects: out, diagnostics };
 }
 /**
  * Places resolved authored objects into an object store, grounding each on `sampleHeight(x,z)` plus
@@ -100,3 +105,25 @@ export function placeAuthoredObjects(store, objects, sampleHeight, options = {})
 export function placeAuthoredObjectsFromDocument(store, document, sampleHeight, options = {}) {
     return placeAuthoredObjects(store, resolveAuthoredObjects(document), sampleHeight, options);
 }
+/**
+ * Update changed authored placements and remove previous authored ids absent from the next document.
+ * Initial placement keeps game onInit state; unrelated document edits preserve runtime prop state.
+ * Call on document changes, never on simulation ticks; runtime-created objects remain untouched.
+ * @capability sync-authored-objects synchronize edited catalog prop poses, elevation and removal through the existing object store
+ */
+export function syncAuthoredObjects(store, objects, previousObjects, sampleHeight, options = {}) {
+    const nextIds = new Set(objects.map((object) => object.instanceId));
+    if (nextIds.size !== objects.length)
+        throw new Error("Authored object ids must be unique");
+    const previous = new Map(previousObjects.map((object) => [object.instanceId, object]));
+    for (const object of objects) {
+        const before = previous.get(object.instanceId);
+        if (before !== undefined && JSON.stringify(before) === JSON.stringify(object))
+            continue;
+        placeAuthoredObjects(store, [object], sampleHeight, { ...options, onExisting: before === undefined ? "keep" : "replace" });
+    }
+    for (const object of previousObjects)
+        if (!nextIds.has(object.instanceId))
+            store.remove(object.instanceId);
+    return objects.map((object) => ({ ...object, ...(typeof object.animation === "object" ? { animation: structuredClone(object.animation) } : {}) }));
+}

package/dist/world/authoredSimulation.d.ts

@@ -0,0 +1,74 @@
+import { type FlockStepAgent } from "../ai/flock.js";
+import type { EditorDocument } from "../editor/types.js";
+import { type AuthoredWeatherSample, type WeatherExposure, type WeatherExposureSnapshot, type WeatherExposureSurface } from "./authoredWeather.js";
+import { type FireCell, type FireGrid } from "./weather.js";
+import type { ParticleDirector } from "../vfx/particleDirector.js";
+import type { Vec3 } from "../vfx/particles.js";
+/** A watched surface is sampled in metres. Its accumulation survives runtime save/restore. */
+export interface AuthoredSurface extends WeatherExposureSurface {
+    y?: number;
+}
+/** Appearance adapters consume these units without owning weather state or its clock. */
+export interface EnvironmentAppearanceSignals {
+    timeSeconds: number;
+    wind: Vec3;
+    wetness: number;
+    snow: number;
+    exposure: number;
+    /** Normalized local fire heat, independent of the temperature offset in degrees Celsius. */
+    heat: number;
+    temperatureOffsetC: number;
+}
+/** Runtime state excludes authored configuration and cosmetic particle pools. */
+export interface AuthoredSimulationSnapshot {
+    surfaces: WeatherExposureSnapshot;
+    watched: AuthoredSurface[];
+    fires: {
+        id: string;
+        cells: FireCell[];
+    }[];
+    flocks: {
+        id: string;
+        agents: FlockStepAgent[];
+        routeIndex: number;
+    }[];
+}
+/** A habitat's live poses; game species determine appearance and gameplay actor policy. */
+export interface AuthoredFlockState {
+    readonly id: string;
+    readonly species: string;
+    readonly role: "cosmetic" | "gameplay";
+    readonly agents: readonly Readonly<FlockStepAgent>[];
+    readonly routeIndex: number;
+}
+/** Engine-owned authority uses the caller's simulation clock; render quality cannot change it. */
+export interface AuthoredSimulationRuntime {
+    sample(x: number, z: number): AuthoredWeatherSample;
+    appearanceAt(surfaceId: string, position: Vec3): EnvironmentAppearanceSignals;
+    /** Fraction of open sky from bounded authored shelter volumes. World Y points up. */
+    exposureAt(x: number, y: number, z: number): number;
+    readonly surfaces: WeatherExposure;
+    watch(surface: AuthoredSurface): void;
+    forget(id: string): void;
+    /** XZ wind adapted to [x,0,z]; response is 1/second, cap is metres/second² (both 0..1e12). */
+    windAcceleration(position: Vec3, response: number, maxAcceleration: number): Vec3;
+    /** Sum authored fields and wind (response 1/second), capped in metres/second² by game policy. */
+    accelerationAt(position: Vec3, timeSeconds: number, windResponse: number, maxAcceleration: number, mask?: number, out?: [number, number, number]): Vec3;
+    fire(id: string): FireGrid | undefined;
+    /** Cosmetic poses render directly; gameplay habitats are consumed by game actor adapters. */
+    flocks(): readonly AuthoredFlockState[];
+    step(gameDt: number): void;
+    retune(document: EditorDocument): void;
+    snapshot(): AuthoredSimulationSnapshot;
+    restore(state: AuthoredSimulationSnapshot): void;
+    dispose(): void;
+}
+/** Compose authored weather, shelter, accumulation, named effect intents and fire with one clock.
+ * @capability authored-environment compose authored weather, shelter, accumulation, fire, flocks and effects using one simulation clock
+ */
+export declare function createAuthoredSimulation(options: {
+    document?: EditorDocument;
+    timeSeconds: () => number;
+    particles?: ParticleDirector;
+    maxSurfaces?: number;
+}): AuthoredSimulationRuntime;