@jgengine/core 0.19.0 → 0.22.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;