@jgengine/editor 0.19.0 → 0.21.0

package/dist/materialControls.js

@@ -0,0 +1,79 @@
+import { materialCapabilitiesForAsset } from "@jgengine/core/material/materialAsset";
+/** Prepare an explicit artist edit by retaining declarations and adding its shader requirements. @internal */
+export function prepareMaterialAuthoringEdit(asset) {
+    return { ...asset, capabilities: [...new Set([...asset.capabilities, ...materialCapabilitiesForAsset(asset)])] };
+}
+const color = { key: "color", label: "Base color", kind: "color", fallback: "#ffffff" };
+const roughness = { key: "roughness", label: "Roughness", kind: "number", fallback: 1, min: 0, max: 1, step: 0.01 };
+const metalness = { key: "metalness", label: "Metalness", kind: "number", fallback: 0, min: 0, max: 1, step: 0.01 };
+const anisotropy = { key: "anisotropy", label: "Directional highlight", kind: "number", fallback: 0, min: 0, max: 1, step: 0.01 };
+const rotation = { key: "anisotropyRotation", label: "Highlight direction (radians)", kind: "number", fallback: 0, min: -Math.PI, max: Math.PI, step: 0.01 };
+const sheen = { key: "sheen", label: "Grazing sheen", kind: "number", fallback: 0, min: 0, max: 1, step: 0.01 };
+const sheenRoughness = { key: "sheenRoughness", label: "Sheen roughness", kind: "number", fallback: 1, min: 0.07, max: 1, step: 0.01 };
+const coat = { key: "clearcoat", label: "Coating", kind: "number", fallback: 0, min: 0, max: 1, step: 0.01 };
+const coatRoughness = { key: "clearcoatRoughness", label: "Coating roughness", kind: "number", fallback: 0, min: 0, max: 1, step: 0.01 };
+const ior = { key: "ior", label: "Index of refraction", kind: "number", fallback: 1.5, min: 1, max: 2.333, step: 0.01 };
+const specular = { key: "specularIntensity", label: "Specular intensity", kind: "number", fallback: 1, min: 0, max: 1, step: 0.01 };
+const transmission = { key: "transmission", label: "Transmission", kind: "number", fallback: 0, min: 0, max: 1, step: 0.01, hint: "Light through a surface. Keep opacity at 1 for physical transmission." };
+const thickness = { key: "thickness", label: "Thickness", kind: "number", fallback: 0, min: 0, step: 0.01 };
+const opacity = { key: "opacity", label: "Opacity", kind: "number", fallback: 1, min: 0, max: 1, step: 0.01 };
+const cutoff = { key: "alphaCutoff", label: "Mask cutoff", kind: "number", fallback: 0.5, min: 0, max: 1, step: 0.01 };
+const base = { label: "Base", hint: "Surface color multiplies the base-color map.", controls: [color] };
+const highlights = { label: "Highlights", hint: "Microsurface roughness controls the width of reflections.", controls: [roughness] };
+const detail = { label: "Detail", hint: "Assign normal and roughness maps below; their UVs and scale belong to each texture.", controls: [] };
+const coverage = { label: "Coverage", hint: "Alpha masking cuts holes; blending changes coverage. Neither is physical transmission.", controls: [opacity, cutoff] };
+/**
+ * Returns six primary groups suited to the material family without hiding the physical model.
+ * @capability editor-material-controls Group physical controls by surface family while retaining advanced fields.
+ */
+export function materialControlGroups(family) {
+    switch (family) {
+        case "fabric": return [base, highlights,
+            { label: "Fibre sheen", hint: "Sheen approximates grazing fuzz; it does not add fibres to the silhouette.", controls: [sheen, sheenRoughness] },
+            { label: "Weave direction", hint: "Directional silk highlights need valid UVs and normals. Tangents improve authored orientation.", controls: [anisotropy, rotation] }, detail, coverage];
+        case "hair": return [base, highlights,
+            { label: "Strand highlights", hint: "A directional physical lobe approximates card or strand highlights; this is not a dedicated hair scattering model.", controls: [anisotropy, rotation] },
+            { label: "Backlighting", hint: "The hair-card adapter adds an approximate light response from behind. It does not provide hair multiple scattering.", controls: [] }, detail, coverage];
+        case "glass": return [base, highlights,
+            { label: "Transmission", hint: "Use opaque coverage with transmission. Refraction needs content behind the glass.", controls: [transmission, ior] },
+            { label: "Volume", hint: "Thickness and attenuation approximate the distance travelled through the medium.", controls: [thickness, { key: "attenuationColor", label: "Attenuation color", kind: "color", fallback: "#ffffff" }, { key: "attenuationDistance", label: "Attenuation distance", kind: "number", fallback: 1, min: 0.001, step: 0.01 }] }, detail, coverage];
+        case "metal": return [base, highlights,
+            { label: "Metal response", hint: "Metalness blends conductor and dielectric response.", controls: [metalness] },
+            { label: "Brush direction", hint: "Directional highlights require UVs and normals; geometry and a direction map define the brushing.", controls: [anisotropy, rotation] }, detail,
+            { label: "Coating", hint: "A separate clear surface lobe overlays the substrate.", controls: [coat, coatRoughness] }];
+        default: return [base, highlights,
+            { label: "Surface response", hint: family === "skin" ? "Standard surface response approximates skin; subsurface scattering is not provided." : "Dielectric specular response and metallic coverage.", controls: [metalness, specular, ior] },
+            { label: "Coating", hint: "Clearcoat adds a surface lobe; geometry remains unchanged.", controls: [coat, coatRoughness] }, detail, coverage];
+    }
+}
+/** Complete supported physical scalar/color fields, independent of the six primary groups. */
+export const advancedMaterialControls = [
+    color, roughness, metalness, specular, ior,
+    { key: "specularColor", label: "Specular color", kind: "color", fallback: "#ffffff" },
+    sheen, sheenRoughness, { key: "sheenColor", label: "Sheen color", kind: "color", fallback: "#000000" },
+    anisotropy, rotation, coat, coatRoughness, transmission, thickness,
+    { key: "attenuationColor", label: "Attenuation color", kind: "color", fallback: "#ffffff" },
+    { key: "attenuationDistance", label: "Attenuation distance", kind: "number", fallback: 1, min: 0.001, step: 0.01 },
+    { key: "iridescence", label: "Iridescence", kind: "number", fallback: 0, min: 0, max: 1, step: 0.01 },
+    { key: "iridescenceIOR", label: "Film index of refraction", kind: "number", fallback: 1.3, min: 1, step: 0.01 },
+    { key: "emissive", label: "Emissive color", kind: "color", fallback: "#000000" },
+    { key: "emissiveIntensity", label: "Emissive intensity", kind: "number", fallback: 1, min: 0, step: 0.1 }, opacity, cutoff,
+];
+/**
+ * Reports geometry prerequisites and renderer approximations to authors.
+ * @capability editor-material-controls Explain geometry prerequisites and approximations for a material asset.
+ */
+export function materialAuthoringNotes(asset) {
+    const notes = [];
+    if (asset.family === "fabric")
+        notes.push("Material controls do not bend cloth, add collision, or create fibre geometry.");
+    if (asset.family === "hair")
+        notes.push("Cards or strand geometry must be authored separately. This approximation supplies coverage and directional highlights, not a groom, collision, motion, or a hair scattering model.");
+    if (asset.family === "skin")
+        notes.push("Skin uses physical surface shading. Subsurface scattering is not implemented.");
+    if ((asset.surface.anisotropy ?? 0) > 0)
+        notes.push("Directional highlights need valid mesh UVs and normals; authored tangents or a direction map control orientation.");
+    if ((asset.surface.transmission ?? 0) > 0)
+        notes.push("Transmission adds a renderer pass. Use opacity 1; inspect front, grazing, and backlit views.");
+    return notes;
+}

package/dist/mcp/fieldSpec.d.ts

@@ -18,7 +18,7 @@ export interface RpcFieldSpec {
  * `EditorHostApi.handle` (whose per-method guards return honest `ok:false` diagnostics for
  * missing/unknown targets). Type-checking presented fields is what keeps a fuzzed value — a string
  * where a number belongs, a scalar where an object belongs — from reaching a live session uncoerced.
- * Unknown extra fields are ignored so a superset payload stays forward-compatible.
+ * Undeclared top-level fields are rejected by the decoder for every method.
  *
  * The same table generates the MCP tool `inputSchema`s (see `mcp/tools.ts`), so `required`/`oneOf`/
  * `of` here also shape what agents are told a tool accepts. The `Record<EditorBridgeRequest["method"],

package/dist/mcp/fieldSpec.js

@@ -18,7 +18,7 @@ const AXES = ["xz", "xy"];
  * `EditorHostApi.handle` (whose per-method guards return honest `ok:false` diagnostics for
  * missing/unknown targets). Type-checking presented fields is what keeps a fuzzed value — a string
  * where a number belongs, a scalar where an object belongs — from reaching a live session uncoerced.
- * Unknown extra fields are ignored so a superset payload stays forward-compatible.
+ * Undeclared top-level fields are rejected by the decoder for every method.
  *
  * The same table generates the MCP tool `inputSchema`s (see `mcp/tools.ts`), so `required`/`oneOf`/
  * `of` here also shape what agents are told a tool accepts. The `Record<EditorBridgeRequest["method"],
@@ -55,6 +55,8 @@ export const RPC_FIELD_SCHEMAS = {
     camera_goto: [s("id"), n("x"), n("y"), n("z"), n("distance"), n("pitch"), n("yaw"), n("height")],
     camera_frame: [n("distance"), n("pitch"), n("yaw"), n("height")],
     scene_summary: [],
+    get_simulation: [],
+    set_simulation: [req(val("simulation"))],
     export_document: [],
     import_document: [req(s("json"))],
     dispatch: [req(o("command"))],
@@ -81,6 +83,7 @@ export const RPC_FIELD_SCHEMAS = {
     set_parent: [req(sa("ids")), req(sn("parentId"))],
     hierarchy: [],
     list_prefabs: [],
+    set_prefab_static_bake: [req(s("prefabId")), req({ name: "bake", kind: "object", nullable: true, of: [req(s("assetId")), oa("collisionBoxes", [req(val("min")), req(val("max"))]), oa("clearances", [req(s("id")), req(val("min")), req(val("max"))])] })],
     create_prefab: [req(s("id")), req(s("name")), req(sa("ids"))],
     insert_prefab: [req(s("prefabId")), n("x"), n("y"), n("z")],
     detach_prefab_instance: [req(s("instanceId"))],
@@ -96,6 +99,12 @@ export const RPC_FIELD_SCHEMAS = {
     select_collection: [req(s("id"))],
     set_object_flags: [req(sa("ids")), b("locked"), b("hidden")],
     batch_set_properties: [req(sa("ids")), s("color"), s("label"), o("meta")],
+    list_material_assets: [],
+    list_material_slots: [req(s("id"))],
+    upsert_material_asset: [req(o("asset")), s("coalesce")],
+    remove_material_asset: [req(s("id"))],
+    assign_material_asset: [req(sa("ids")), req(s("materialId")), req(o("selector"))],
+    clear_material_assets: [req(sa("ids"))],
     assign_material: [req(sa("ids")), req(s("materialId"))],
     list_grids: [],
     get_grid_cell: [req(s("id")), req(n("col")), req(n("row"))],
@@ -107,7 +116,7 @@ export const RPC_FIELD_SCHEMAS = {
     flood_fill_grid: [req(s("id")), req(n("col")), req(n("row")), req(s("value"))],
     resize_grid_layer: [req(s("id")), req(n("cols")), req(n("rows"))],
     import_grid: [req(s("id")), req(s("kind")), req(s("format", ["ascii", "csv"])), req(s("text")), s("empty"), n("cellSize"), v3("origin"), o("glyphMap"), oa("palette")],
-    push_document_patch: [req(o("patch")), b("force")],
+    push_document_patch: [{ ...req(o("patch")), of: [req(s("type", ["snapshot", "commands"])), req(n("baseRevision")), oa("commands"), o("document"), n("revision")] }, b("force")],
     pull_document_patches: [n("sinceRevision")],
     document_revision: [b("includeDocument")],
     push_runtime_delta: [n("at"), oa("entities"), sa("removeIds"), o("tunables")],

package/dist/mcp/importOptionalGameModule.d.ts

@@ -0,0 +1,2 @@
+/** @internal Missing optional files are valid; existing modules must load successfully. */
+export declare function importOptionalGameModule(path: URL): Promise<Record<string, unknown> | undefined>;

package/dist/mcp/importOptionalGameModule.js

@@ -0,0 +1,13 @@
+import { access } from "node:fs/promises";
+/** @internal Missing optional files are valid; existing modules must load successfully. */
+export async function importOptionalGameModule(path) {
+    try {
+        await access(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    return import(path.href);
+}

package/dist/mcp/loadGameCatalogs.js

@@ -1,12 +1,4 @@
-async function importOptionalEditorCatalogsModule(gameId) {
-    try {
-        const path = new URL(`../../../../Games/${gameId}/src/editorCatalogs.ts`, import.meta.url);
-        return (await import(path.href));
-    }
-    catch {
-        return undefined;
-    }
-}
+import { importOptionalGameModule } from "./importOptionalGameModule.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -72,11 +64,12 @@ export function decodeGameCatalogs(resolved) {
  * @internal
  */
 export async function loadGameCatalogs(gameId) {
-    const mod = await importOptionalEditorCatalogsModule(gameId);
-    if (mod?.editorCatalogs === undefined)
-        return { ok: true, catalogs: [] };
     let resolved;
     try {
+        const path = new URL(`../../../../Games/${gameId}/src/editorCatalogs.ts`, import.meta.url);
+        const mod = await importOptionalGameModule(path);
+        if (mod?.editorCatalogs === undefined)
+            return { ok: true, catalogs: [] };
         const value = mod.editorCatalogs;
         resolved = typeof value === "function" ? value() : value;
     }

package/dist/mcp/rpcRequest.d.ts

@@ -18,8 +18,8 @@ export type DecodeRpcRequestResult = {
  * call) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known
  * `method`, then type-checks every field the method understands against {@link RPC_FIELD_SCHEMAS}.
  * A garbled method, or a field whose value is the wrong type (a string where a number belongs, a
- * scalar where an object belongs), is rejected here with a path-specific diagnostic instead of
- * flowing into a live session on a blind cast. Missing fields and unknown extra fields are left for
- * `handle` to interpret so the boundary stays forward-compatible.
+ * scalar where an object belongs), or an undeclared field is rejected here with a path-specific
+ * diagnostic instead of flowing into a live session on a blind cast. Missing fields are left for
+ * `handle` to interpret.
  */
 export declare function decodeEditorBridgeRequest(raw: unknown): DecodeRpcRequestResult;

package/dist/mcp/rpcRequest.js

@@ -60,9 +60,9 @@ function validateField(value, spec, errors) {
  * call) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known
  * `method`, then type-checks every field the method understands against {@link RPC_FIELD_SCHEMAS}.
  * A garbled method, or a field whose value is the wrong type (a string where a number belongs, a
- * scalar where an object belongs), is rejected here with a path-specific diagnostic instead of
- * flowing into a live session on a blind cast. Missing fields and unknown extra fields are left for
- * `handle` to interpret so the boundary stays forward-compatible.
+ * scalar where an object belongs), or an undeclared field is rejected here with a path-specific
+ * diagnostic instead of flowing into a live session on a blind cast. Missing fields are left for
+ * `handle` to interpret.
  */
 export function decodeEditorBridgeRequest(raw) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
@@ -77,7 +77,13 @@ export function decodeEditorBridgeRequest(raw) {
         return { ok: false, errors: [{ path: "$.method", message: `unknown method "${method}"` }] };
     }
     const errors = [];
-    for (const spec of RPC_FIELD_SCHEMAS[method]) {
+    const specs = RPC_FIELD_SCHEMAS[method];
+    const allowed = new Set(["method", ...specs.map((spec) => spec.name)]);
+    for (const field of Object.keys(record)) {
+        if (!allowed.has(field))
+            errors.push({ path: `$.${field}`, message: `unknown field "${field}" for method "${method}"` });
+    }
+    for (const spec of specs) {
         validateField(record[spec.name], spec, errors);
     }
     if (errors.length > 0)

package/dist/mcp/tools.js

@@ -31,10 +31,12 @@ const TOOL_DESCRIPTIONS = [
     { name: "select", description: "Select editor object ids." },
     { name: "camera_goto", description: "Focus the editor camera on an id or world x/z. Optional distance/pitch/yaw/height reposition the orbit camera (pitch is degrees above the horizon; 90 = straight-down aerial) so an aerial composes in one call." },
     { name: "camera_frame", description: "Frame the whole editor document. Optional distance/pitch/yaw/height compose an aerial; when pitch is set without distance the region is auto-fit into view so the camera never buries in terrain." },
+    { name: "get_simulation", description: "Read authored weather profiles/schedules, wind zones, named emitters, fire areas and flock habitats. Distances are metres, time is game seconds, wind is XZ metres/second." },
+    { name: "set_simulation", description: "Replace validated authored simulation inputs atomically as one undo step. Pass null to clear. Runtime heat, particles and accumulation never overwrite authored inputs." },
     { name: "scene_summary", description: "Compact summary of the editor document and bounds." },
     { name: "export_document", description: "Export the editor document as JSON text." },
     { name: "import_document", description: "Replace the session document from JSON text." },
-    { name: "push_document_patch", description: "Apply a versioned document patch (snapshot or commands) over the live-sync bus. Document is authoritative; force skips baseRevision checks." },
+    { name: "push_document_patch", description: "Apply a versioned document patch (snapshot or commands). Command batches validate atomically, publish once, and form one undo step; failure reports commands[index] without applying any edits. Same-kind add commands upsert stable ids. History commands are rejected. Force skips baseRevision checks." },
     { name: "pull_document_patches", description: "Pull document patches after a known revision (live-sync stream for a running game)." },
     { name: "document_revision", description: "Current live-sync document revision; optionally include the full document." },
     { name: "push_runtime_delta", description: "Publish ephemeral runtime state (entities/tunables) on the reverse channel — does not mutate the document." },
@@ -74,6 +76,7 @@ const TOOL_DESCRIPTIONS = [
     { name: "set_parent", description: "Parent objects under another (or null to unparent); cycles are refused. Moving a parent moves its subtree." },
     { name: "hierarchy", description: "The scene's parent/child tree: root ids and each root's direct children." },
     { name: "list_prefabs", description: "List the document's reusable prefab stamps (id, name, fragment content)." },
+    { name: "set_prefab_static_bake", description: "Author static prefab export settings (assetId, local collisionBoxes, named clearance boxes); null clears settings. One undo step. Export verified source bytes offline through assets/staticPrefabBake." },
     { name: "create_prefab", description: "Make a reusable prefab from selected ids, centered on their own bounds." },
     { name: "insert_prefab", description: "Insert a fresh, tagged instance of a prefab at the camera focus or given x/y/z." },
     { name: "detach_prefab_instance", description: "Strip the prefab link from every object in an instance, keeping its content." },
@@ -89,6 +92,12 @@ const TOOL_DESCRIPTIONS = [
     { name: "select_collection", description: "Restore the current selection to a collection's member ids." },
     { name: "set_object_flags", description: "Set per-object locked (blocks transform/delete) and/or hidden (viewport hide) flags on placeables by id. false clears the field." },
     { name: "batch_set_properties", description: "Patch color/label/meta across every listed id in one dispatch, regardless of kind." },
+    { name: "list_material_assets", description: "List reusable authored material assets and per-marker named slot assignments." },
+    { name: "list_material_slots", description: "Read a marker's canonical loaded mesh/material slot names, indices, material type, UV sets and tangents. Select the marker and open Materials to load it; loading/unavailable states return explicit status rather than empty ready data." },
+    { name: "upsert_material_asset", description: "Validate and save a reusable physical material asset as one undo step; omitted surface fields preserve imported appearance." },
+    { name: "remove_material_asset", description: "Remove an unreferenced material asset; assigned materials fail with a diagnostic." },
+    { name: "assign_material_asset", description: "Assign a material asset to exact mesh/material-slot names or slot index on selected markers. Untouched imported slots remain intact." },
+    { name: "clear_material_assets", description: "Clear selected markers authored slot assignments and restore imported materials." },
     { name: "assign_material", description: "Stamp meta.materialId on every listed object — the drag-drop material assignment primitive." },
     { name: "list_grids", description: "List the scene document's grid/tile layers (id, kind, bounds, cell count, palette ids)." },
     { name: "get_grid_cell", description: "Eyedrop: read the value id at col,row of a grid layer (empty value for unset/out-of-bounds cells)." },

package/dist/modelAnimationAuthoring.d.ts

@@ -1,4 +1,5 @@
-import { type AnimGraph } from "@jgengine/core/anim/animGraph";
+import type { AnimGraph } from "@jgengine/core/anim/animGraph";
+import { type AuthoredAnimationDiagnostic, type AuthoredAnimationDocumentLike } from "@jgengine/core/world/authoredAnimation";
 /**
  * Authoring model for a placement's `ModelConfig.animation`, persisted on a marker's `meta.animation`
  * and consumed by the shell exactly like a game-authored config. Pure data + reducers, no JSX — the
@@ -39,11 +40,15 @@ export interface AuthoredAnimationStates {
 }
 /** Structurally compatible with `ModelAnimationConfig`, but every field optional for authoring. */
 export interface AuthoredAnimationConfig {
+    auto?: true;
+    clock?: "real" | "game";
     clip?: string;
     loop?: boolean;
     timeScale?: number;
+    paused?: boolean;
+    time?: number;
     states?: AuthoredAnimationStates;
-    oneShots?: Record<string, string>;
+    oneShots?: Record<string, string | readonly string[]>;
     /** A stored animation graph; takes over from `states`/`oneShots` at play time. */
     graph?: AnimGraph;
 }
@@ -51,8 +56,13 @@ export interface AuthoredAnimationConfig {
 export type AnimationSetting = AuthoredAnimationConfig | "auto" | "none";
 /** Which authoring mode a stored setting represents. `default` = no override key. */
 export type AnimationMode = "default" | "auto" | "none" | "custom";
-/** Reads and shape-validates the animation override from a marker's meta; undefined when absent/invalid. */
+/** Reads a whole valid override, retaining authored fields; malformed values return undefined. */
 export declare function readAnimationSetting(meta: Record<string, unknown> | undefined): AnimationSetting | undefined;
+/** Validates a placement's animation with its saved-document repair locations. @internal */
+export declare function readAnimationSettingResult(document: AuthoredAnimationDocumentLike, markerId: string): {
+    setting: AnimationSetting | undefined;
+    diagnostics: readonly AuthoredAnimationDiagnostic[];
+};
 /** The authoring mode a stored setting maps to. */
 export declare function animationMode(setting: AnimationSetting | undefined): AnimationMode;
 /**
@@ -64,11 +74,21 @@ export declare function setAnimationMode(setting: AnimationSetting | undefined,
 /** A concrete custom config derived from a rigged asset's clip roles — the `custom` mode seed. */
 export declare function defaultCustomConfig(clips: readonly string[]): AuthoredAnimationConfig;
 /** Sets or clears (null) a locomotion state clip; forces the setting into `custom`. */
-export declare function setLocomotionClip(setting: AnimationSetting | undefined, role: LocomotionRole, clipName: string | null): AuthoredAnimationConfig;
+export declare function setLocomotionClip(setting: AnimationSetting | undefined, role: LocomotionRole, clipName: string | null, clips?: readonly string[]): AuthoredAnimationConfig;
 /** Sets or clears (null) a numeric locomotion tuning. */
-export declare function setLocomotionNumber(setting: AnimationSetting | undefined, key: LocomotionNumber, value: number | null): AuthoredAnimationConfig;
-/** Binds or clears (null) a one-shot event to a clip. */
-export declare function setOneShotClip(setting: AnimationSetting | undefined, event: string, clipName: string | null): AuthoredAnimationConfig;
+export declare function setLocomotionNumber(setting: AnimationSetting | undefined, key: LocomotionNumber, value: number | null, clips?: readonly string[]): AuthoredAnimationConfig;
+/** Binds or clears (null) a one-shot event's clip or variant list. */
+export declare function setOneShotClip(setting: AnimationSetting | undefined, event: string, clipName: string | readonly string[] | null): AuthoredAnimationConfig;
+/** Sets a single playback clip, explicitly replacing speed-driven states and a stored graph. @internal */
+export declare function setPlaybackClip(setting: AnimationSetting | undefined, clip: string | null): AuthoredAnimationConfig;
+/** Changes a playback scalar while preserving role mappings, variants and the stored graph. @internal */
+export declare function setPlaybackNumber(setting: AnimationSetting | undefined, key: "time" | "timeScale", value: number | null): AuthoredAnimationConfig;
+/** Chooses the playback clock without replacing mappings, graph, or other authored fields. @internal */
+export declare function setPlaybackClock(setting: AnimationSetting | undefined, clock: "real" | "game"): AuthoredAnimationConfig;
+/** Requests loaded-rig role inference, or removes that request, retaining explicit overrides whole. @internal */
+export declare function setAutomaticRoles(setting: AnimationSetting | undefined, derive: boolean): AuthoredAnimationConfig;
+/** Changes a playback toggle without replacing the remaining authored settings. @internal */
+export declare function setPlaybackBoolean(setting: AnimationSetting | undefined, key: "paused" | "loop", value: boolean): AuthoredAnimationConfig;
 /**
  * The meta patch that persists a setting (or clears the override when undefined). Shallow-merges onto
  * `marker.meta` via `setMarker`; an undefined value drops out of the saved JSON document.

package/dist/modelAnimationAuthoring.js

@@ -1,4 +1,4 @@
-import { parseAnimGraph } from "@jgengine/core/anim/animGraph";
+import { readAuthoredAnimation } from "@jgengine/core/world/authoredAnimation";
 import { animGraphFromConfig } from "@jgengine/core/anim/locomotionGraph";
 import { resolveAnimationConfig, rolesFromClips } from "@jgengine/core/game/clipRoles";
 /**
@@ -24,51 +24,14 @@ export const LOCOMOTION_NUMBERS = ["walkSpeed", "runSpeed", "fadeSec"];
  * `combat.hitReaction` / `entity.died`; the rest fire when the game calls `playEntityAnimation`.
  */
 export const ONE_SHOT_EVENTS = ["attack", "hit", "death", "jump", "interact", "cheer"];
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Reads and shape-validates the animation override from a marker's meta; undefined when absent/invalid. */
+/** Reads a whole valid override, retaining authored fields; malformed values return undefined. */
 export function readAnimationSetting(meta) {
-    const value = meta?.["animation"];
-    if (value === "auto" || value === "none")
-        return value;
-    if (!isRecord(value))
-        return undefined;
-    const config = {};
-    if (typeof value["clip"] === "string")
-        config.clip = value["clip"];
-    if (typeof value["loop"] === "boolean")
-        config.loop = value["loop"];
-    if (typeof value["timeScale"] === "number")
-        config.timeScale = value["timeScale"];
-    if (isRecord(value["states"])) {
-        const raw = value["states"];
-        const states = {};
-        for (const role of LOCOMOTION_ROLES)
-            if (typeof raw[role] === "string")
-                states[role] = raw[role];
-        for (const key of LOCOMOTION_NUMBERS)
-            if (typeof raw[key] === "number")
-                states[key] = raw[key];
-        if (Object.keys(states).length > 0)
-            config.states = states;
-    }
-    if (isRecord(value["oneShots"])) {
-        const raw = value["oneShots"];
-        const oneShots = {};
-        for (const [event, clip] of Object.entries(raw)) {
-            if (typeof clip === "string")
-                oneShots[event] = clip;
-            else if (Array.isArray(clip) && typeof clip[0] === "string")
-                oneShots[event] = clip[0];
-        }
-        if (Object.keys(oneShots).length > 0)
-            config.oneShots = oneShots;
-    }
-    const graph = parseAnimGraph(value["graph"]);
-    if (graph !== undefined)
-        config.graph = graph;
-    return config;
+    return readAnimationSettingResult({ markers: [{ id: "animation", meta }] }, "animation").setting;
+}
+/** Validates a placement's animation with its saved-document repair locations. @internal */
+export function readAnimationSettingResult(document, markerId) {
+    const result = readAuthoredAnimation(document, markerId);
+    return { setting: result.animation, diagnostics: result.diagnostics };
 }
 /** The authoring mode a stored setting maps to. */
 export function animationMode(setting) {
@@ -83,14 +46,6 @@ export function animationMode(setting) {
 function asConfig(setting) {
     return setting !== undefined && setting !== "auto" && setting !== "none" ? setting : {};
 }
-function normalizeConfig(config) {
-    const next = { ...config };
-    if (next.states !== undefined && Object.keys(next.states).length === 0)
-        delete next.states;
-    if (next.oneShots !== undefined && Object.keys(next.oneShots).length === 0)
-        delete next.oneShots;
-    return next;
-}
 /**
  * Switches authoring mode. `custom` seeds from the asset's clip-role defaults (so the user starts from
  * a working config, then overrides) when there is no existing object config; the other modes are the
@@ -105,7 +60,7 @@ export function setAnimationMode(setting, mode, clips = []) {
         return "none";
     if (setting !== undefined && setting !== "auto" && setting !== "none")
         return setting;
-    return normalizeConfig(defaultCustomConfig(clips));
+    return defaultCustomConfig(clips);
 }
 /** A concrete custom config derived from a rigged asset's clip roles — the `custom` mode seed. */
 export function defaultCustomConfig(clips) {
@@ -119,9 +74,9 @@ export function defaultCustomConfig(clips) {
         states.run = roles.run[0];
     const oneShots = {};
     for (const event of ONE_SHOT_EVENTS) {
-        const variant = roles[event]?.[0];
-        if (variant !== undefined)
-            oneShots[event] = variant;
+        const variants = roles[event];
+        if (variants !== undefined && variants.length > 0)
+            oneShots[event] = variants.length === 1 ? variants[0] : [...variants];
     }
     const config = {};
     if (Object.keys(states).length > 0)
@@ -131,34 +86,72 @@ export function defaultCustomConfig(clips) {
     return config;
 }
 /** Sets or clears (null) a locomotion state clip; forces the setting into `custom`. */
-export function setLocomotionClip(setting, role, clipName) {
+export function setLocomotionClip(setting, role, clipName, clips = []) {
     const config = asConfig(setting);
-    const states = { ...config.states };
+    const states = { ...(config.states ?? (clipName === null ? undefined : defaultCustomConfig(clips).states)) };
     if (clipName === null)
         delete states[role];
     else
         states[role] = clipName;
-    return normalizeConfig({ ...config, states });
+    return { ...config, ...(config.states !== undefined || Object.keys(states).length > 0 ? { states } : {}) };
 }
 /** Sets or clears (null) a numeric locomotion tuning. */
-export function setLocomotionNumber(setting, key, value) {
+export function setLocomotionNumber(setting, key, value, clips = []) {
     const config = asConfig(setting);
-    const states = { ...config.states };
+    const states = { ...(config.states ?? (value === null || !Number.isFinite(value) ? undefined : defaultCustomConfig(clips).states)) };
     if (value === null || !Number.isFinite(value))
         delete states[key];
     else
         states[key] = value;
-    return normalizeConfig({ ...config, states });
+    return { ...config, ...(config.states !== undefined || Object.keys(states).length > 0 ? { states } : {}) };
 }
-/** Binds or clears (null) a one-shot event to a clip. */
+/** Binds or clears (null) a one-shot event's clip or variant list. */
 export function setOneShotClip(setting, event, clipName) {
     const config = asConfig(setting);
     const oneShots = { ...config.oneShots };
-    if (clipName === null)
+    if (clipName === null || (Array.isArray(clipName) && clipName.length === 0))
         delete oneShots[event];
     else
-        oneShots[event] = clipName;
-    return normalizeConfig({ ...config, oneShots });
+        oneShots[event] = typeof clipName === "string" ? clipName : clipName.length === 1 ? clipName[0] : [...clipName];
+    const next = { ...config, oneShots };
+    if (Object.keys(oneShots).length === 0)
+        delete next.oneShots;
+    return next;
+}
+/** Sets a single playback clip, explicitly replacing speed-driven states and a stored graph. @internal */
+export function setPlaybackClip(setting, clip) {
+    if (clip === null) {
+        const { clip: _clip, ...config } = asConfig(setting);
+        return config;
+    }
+    const { states: _states, graph: _graph, auto: _auto, ...config } = asConfig(setting);
+    return { ...config, clip };
+}
+/** Changes a playback scalar while preserving role mappings, variants and the stored graph. @internal */
+export function setPlaybackNumber(setting, key, value) {
+    const config = { ...asConfig(setting) };
+    if (value === null || !Number.isFinite(value))
+        delete config[key];
+    else
+        config[key] = key === "time" ? Math.max(0, value) : value;
+    return config;
+}
+/** Chooses the playback clock without replacing mappings, graph, or other authored fields. @internal */
+export function setPlaybackClock(setting, clock) {
+    return { ...(setting === "auto" ? { auto: true } : asConfig(setting)), clock };
+}
+/** Requests loaded-rig role inference, or removes that request, retaining explicit overrides whole. @internal */
+export function setAutomaticRoles(setting, derive) {
+    const config = { ...asConfig(setting) };
+    if (derive)
+        config.auto = true;
+    else
+        delete config.auto;
+    return config;
+}
+/** Changes a playback toggle without replacing the remaining authored settings. @internal */
+export function setPlaybackBoolean(setting, key, value) {
+    return { ...asConfig(setting), [key]: value };
 }
 /**
  * The meta patch that persists a setting (or clears the override when undefined). Shallow-merges onto
@@ -175,14 +168,19 @@ export function animationMetaPatch(setting) {
 export function effectiveAnimGraph(setting, clips) {
     if (setting === "none")
         return null;
+    if (setting !== undefined && setting !== "auto" && setting.auto === true) {
+        const resolved = resolveAnimationConfig(setting, clips);
+        const graph = resolved === undefined ? undefined : animGraphFromConfig(resolved);
+        return graph === undefined ? null : { graph, source: setting.graph !== undefined ? "authored" : setting.states !== undefined ? "locomotion" : "auto" };
+    }
     if (setting !== undefined && setting !== "auto") {
         if (setting.graph !== undefined)
             return { graph: setting.graph, source: "authored" };
         const states = setting.states;
-        if (states?.idle === undefined)
+        if (states?.idle === undefined || states.idle.trim().length === 0)
             return null;
         const graph = animGraphFromConfig({
-            states: { ...states, idle: states.idle, walk: states.walk ?? states.idle },
+            states: { ...states, idle: states.idle, walk: states.walk === undefined || states.walk.trim().length === 0 ? states.idle : states.walk },
             ...(setting.oneShots === undefined ? {} : { oneShots: setting.oneShots }),
         });
         return graph === undefined ? null : { graph, source: "locomotion" };
@@ -193,15 +191,14 @@ export function effectiveAnimGraph(setting, clips) {
 }
 /** Stores `graph` on the placement, keeping its other fields; the stored graph wins at play time. */
 export function storeAnimGraph(setting, graph) {
-    return normalizeConfig({ ...asConfig(setting), graph });
+    return { ...asConfig(setting), graph };
 }
 /** Removes a stored graph so `states`/`oneShots` (or clip roles) drive the placement again. */
 export function clearAnimGraph(setting) {
     if (setting === undefined || setting === "auto" || setting === "none")
         return setting;
     const { graph: _graph, ...rest } = setting;
-    const next = normalizeConfig(rest);
-    return Object.keys(next).length === 0 ? undefined : next;
+    return Object.keys(rest).length === 0 ? undefined : rest;
 }
 /**
  * Sets one transition's crossfade seconds in `graph` and stores the result, so editing a derived