@jgengine/editor 0.19.0 → 0.22.0

package/dist/handlers/terrain.js

@@ -1,6 +1,15 @@
 import { createTerrainSnapshot, editableTerrainFromSnapshot, } from "@jgengine/core/world/terraform";
 import { resolveScatter, resolveScatterRegion, scatterRegionEstimate, scatterRegionFromPath, SCATTER_PATH_KIND, } from "@jgengine/core/world/scatterRegion";
 import { TERRAIN_MATERIALS } from "../uiStore.js";
+function brushError(request) {
+    if (![request.x, request.z, request.radius ?? 8, request.strength ?? 1].every(Number.isFinite))
+        return "brush coordinates, radius and strength must be finite";
+    if ((request.radius ?? 8) <= 0)
+        return "brush radius must be positive";
+    if ((request.strength ?? 1) < 0)
+        return "brush strength must be nonnegative";
+    return null;
+}
 /** Sculpt heightfield, material painting, terrain layers, and foliage/scatter verbs. */
 export const terrainHandlers = {
     create_terrain: (ctx, request) => {
@@ -8,17 +17,35 @@ export const terrainHandlers = {
         const depth = request.depth ?? 200;
         const cx = request.centerX ?? 0;
         const cz = request.centerZ ?? 0;
+        const cellSize = request.cellSize ?? 2;
+        if (![width, depth, cx, cz, cellSize].every(Number.isFinite) || width <= 0 || depth <= 0 || cellSize <= 0) {
+            return { ok: false, error: "terrain dimensions and cellSize must be finite and positive; center must be finite" };
+        }
+        if ((Math.max(1, Math.round(width / cellSize)) + 1) * (Math.max(1, Math.round(depth / cellSize)) + 1) > 1_000_000) {
+            return { ok: false, error: "terrain exceeds 1,000,000 vertices — increase cellSize or reduce width/depth" };
+        }
+        const bounds = { minX: cx - width / 2, minZ: cz - depth / 2, maxX: cx + width / 2, maxZ: cz + depth / 2 };
+        if (!Object.values(bounds).every(Number.isFinite) || bounds.maxX <= bounds.minX || bounds.maxZ <= bounds.minZ) {
+            return { ok: false, error: "terrain bounds must have a finite, nonzero extent" };
+        }
         const terrain = createTerrainSnapshot({
-            bounds: { minX: cx - width / 2, minZ: cz - depth / 2, maxX: cx + width / 2, maxZ: cz + depth / 2 },
-            cellSize: request.cellSize ?? 2,
+            bounds,
+            cellSize,
         });
         ctx.session.dispatch({ type: "setTerrain", terrain });
         return { ok: true, result: { cols: terrain.cols, rows: terrain.rows, cellSize: terrain.cellSize } };
     },
     sculpt_terrain: (ctx, request) => {
+        const invalid = brushError(request);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
         const terrain = ctx.session.getState().document.terrain;
         if (terrain === undefined)
             return { ok: false, error: "no terrain — call create_terrain first" };
+        if (request.mode === "ramp" && (request.toX === undefined || request.toZ === undefined))
+            return { ok: false, error: "ramp requires toX and toZ" };
+        if ([request.target, request.toX, request.toZ, request.seed].some((value) => value !== undefined && !Number.isFinite(value)))
+            return { ok: false, error: "sculpt target, ramp endpoint and seed must be finite" };
         const live = editableTerrainFromSnapshot(terrain);
         const edit = {
             mode: request.mode,
@@ -66,6 +93,9 @@ export const terrainHandlers = {
         };
     },
     paint_terrain: (ctx, request) => {
+        const invalid = brushError(request);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
         const terrain = ctx.session.getState().document.terrain;
         if (terrain === undefined)
             return { ok: false, error: "no terrain — call create_terrain first" };
@@ -120,23 +150,31 @@ export const terrainHandlers = {
         if (ctx.session.getState().document.terrain === undefined) {
             return { ok: false, error: "no terrain — call create_terrain first" };
         }
+        if (new Set(request.layers.map((layer) => layer.id)).size !== request.layers.length || request.layers.some((layer) => layer.id.length === 0 || layer.surface.length === 0)) {
+            return { ok: false, error: "terrain layers require unique nonempty ids and nonempty surfaces" };
+        }
         ctx.session.dispatch({ type: "setTerrainLayers", layers: request.layers });
         return { ok: true, result: { layers: ctx.session.getState().document.terrain?.layers ?? [] } };
     },
     blend_terrain: (ctx, request) => {
+        const invalid = brushError(request);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
         const terrain = ctx.session.getState().document.terrain;
         if (terrain === undefined)
             return { ok: false, error: "no terrain — call create_terrain first" };
-        // Auto-add the surface as a layer if the stack does not carry it yet.
-        const layers = terrain.layers ?? [];
-        if (!layers.some((layer) => layer.surface === request.surface)) {
-            const next = [...layers, { id: request.surface, surface: request.surface }];
-            ctx.session.dispatch({ type: "setTerrainLayers", layers: next });
+        const live = editableTerrainFromSnapshot(terrain);
+        if ((request.strength ?? 1) > 1)
+            return { ok: false, error: "blend strength must be between 0 and 1" };
+        const addLayer = !live.layers.some((layer) => layer.surface === request.surface);
+        if (addLayer) {
+            let id = request.surface;
+            let suffix = 1;
+            while (live.layers.some((layer) => layer.id === id))
+                id = `${request.surface}_${suffix++}`;
+            const layers = [...live.layers, { id, surface: request.surface }];
+            live.setLayers(layers);
         }
-        const snapshot = ctx.session.getState().document.terrain;
-        if (snapshot === undefined)
-            return { ok: false, error: "no terrain — call create_terrain first" };
-        const live = editableTerrainFromSnapshot(snapshot);
         const delta = live.blendPaintDelta({
             mode: "paint",
             center: [request.x, request.z],
@@ -147,7 +185,9 @@ export const terrainHandlers = {
         });
         if (delta.indices.length === 0)
             return { ok: false, error: "blend touched no cells (check radius/position)" };
-        ctx.session.dispatch({ type: "blendTerrain", delta });
+        ctx.session.dispatch(addLayer
+            ? { type: "setTerrain", terrain: live.snapshot() }
+            : { type: "blendTerrain", delta });
         return { ok: true, result: { changed: delta.indices.length, layers: ctx.session.getState().document.terrain?.layers ?? [] } };
     },
     convert_scatter: (ctx, request) => {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { EditorApp, type EditorAppProps, type EditorSaveFn } from "./EditorApp.js";
+export { CreatorApp, type CreatorConfig } from "./CreatorApp.js";
 export { buildEditorNetworkSnapshot, isNetworkMultiplayerConfigured, type EditorNetworkAdapterKind, type EditorNetworkPresenceActor, type EditorNetworkPresenceInput, type EditorNetworkSession, type EditorNetworkSnapshot, } from "./networkSnapshot.js";
 export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, importAssetToHost, loadDroppedAssets, mergeStandaloneAssets, type StandaloneEditorProps, type StandaloneAsset, type AssetImporter, type BlankPlayableOptions, } from "./StandaloneEditor.js";
 export { EditorLayerOverlays, PathDraftPreview } from "./DebugDraw.js";
@@ -9,7 +10,7 @@ export { TerrainSculpt } from "./TerrainSculpt.js";
 export { ScatterPreview } from "./ScatterPreview.js";
 export { EditorCameraDriver } from "./EditorCameraDriver.js";
 export { AssetBrowser, assetsFromCatalog, editorAssetFromImport, mergeEditorAssets, type EditorAssetEntry, } from "./AssetBrowser.js";
-export { createEditorHost, getEditorHost, installEditorHost, type EditorAssetInfo, type EditorBridgeRequest, type EditorBridgeResponse, type EditorHostApi, type EditorPerfSample, type EditorRunMode, } from "./session.js";
+export { createEditorHost, getEditorHost, installEditorHost, type EditorAssetInfo, type EditorBridgeRequest, type EditorBridgeResponse, type EditorHostApi, type EditorMaterialSlotInfo, type EditorMaterialSlotReport, type EditorMaterialSlotInventory, type EditorPerfSample, type EditorRunMode, } from "./session.js";
 export { PerfProbe } from "./PerfProbe.js";
 export { useStoreSelector, shallowArrayEqual, virtualWindow, type SubscribableStore, type VirtualWindow, } from "./useStoreSelector.js";
 export { useF2Chord } from "./useF2Chord.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { EditorApp } from "./EditorApp.js";
+export { CreatorApp } from "./CreatorApp.js";
 export { buildEditorNetworkSnapshot, isNetworkMultiplayerConfigured, } from "./networkSnapshot.js";
 export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, importAssetToHost, loadDroppedAssets, mergeStandaloneAssets, } from "./StandaloneEditor.js";
 export { EditorLayerOverlays, PathDraftPreview } from "./DebugDraw.js";

package/dist/materialControls.d.ts

@@ -0,0 +1,32 @@
+import { type MaterialAsset, type MaterialFamily, type MaterialSurfaceParameters } from "@jgengine/core/material/materialAsset";
+/** Prepare an explicit artist edit by retaining declarations and adding its shader requirements. @internal */
+export declare function prepareMaterialAuthoringEdit(asset: MaterialAsset): MaterialAsset;
+/** One physical surface field in the material workspace. */
+export interface MaterialControl {
+    key: keyof MaterialSurfaceParameters;
+    label: string;
+    kind: "number" | "color";
+    fallback: number | string;
+    min?: number;
+    max?: number;
+    step?: number;
+    hint?: string;
+}
+/** A family-specific group of primary controls; maps and full physical fields remain available. */
+export interface MaterialControlGroup {
+    label: string;
+    hint: string;
+    controls: readonly MaterialControl[];
+}
+/**
+ * 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 declare function materialControlGroups(family: MaterialFamily): readonly MaterialControlGroup[];
+/** Complete supported physical scalar/color fields, independent of the six primary groups. */
+export declare const advancedMaterialControls: readonly MaterialControl[];
+/**
+ * Reports geometry prerequisites and renderer approximations to authors.
+ * @capability editor-material-controls Explain geometry prerequisites and approximations for a material asset.
+ */
+export declare function materialAuthoringNotes(asset: MaterialAsset): readonly string[];

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.