@jgengine/editor 0.18.0 → 0.19.0

package/dist/mcp/fieldSpec.js

@@ -45,8 +45,8 @@ export const RPC_FIELD_SCHEMAS = {
     set_volume: [req(s("id")), n("radius"), n("height"), n("x"), n("y"), n("z")],
     set_path: [req(s("id")), s("kind"), n("width"), s("color"), s("label"), o("meta")],
     add_path: [req(s("id")), req(oa("points", [req(n("x")), n("y"), req(n("z"))])), s("kind"), n("width"), s("color"), s("label"), o("meta")],
-    add_marker: [req(s("id")), req(s("kind")), req(n("x")), n("y"), req(n("z")), s("color"), s("label"), n("rotationY"), o("meta")],
-    set_marker: [req(s("id")), s("kind"), s("color"), s("label"), n("rotationY"), o("meta")],
+    add_marker: [req(s("id")), req(s("kind")), req(n("x")), n("y"), req(n("z")), s("color"), s("label"), n("rotationY"), s("catalogId"), o("meta")],
+    set_marker: [req(s("id")), s("kind"), s("color"), s("label"), n("rotationY"), s("catalogId"), o("meta")],
     set_note: [req(s("id")), s("text"), o("meta")],
     set_meta: [req(s("id")), req(o("patch"))],
     apply_preset: [req(s("id")), req(s("preset"))],
@@ -75,6 +75,7 @@ export const RPC_FIELD_SCHEMAS = {
     convert_scatter: [req(s("pathId"))],
     generate_streets: [s("volumeId"), v3("center"), n("halfX"), n("halfZ"), s("seed"), s("mode", ["net", "circuit"]), s("kind"), o("params")],
     bake_minimap: [n("padding"), n("resolution"), n("waterLevel")],
+    bakeNavMesh: [req(s("id")), req(val("positions")), req(val("indices")), req(n("agentRadius")), req(n("agentHeight")), req(n("maxSlope")), req(n("maxClimb"))],
     add_foliage: [req(oa("points", [req(n("x")), req(n("z"))])), n("density"), s("item"), s("seed"), n("minSpacing")],
     scatter_summary: [],
     set_parent: [req(sa("ids")), req(sn("parentId"))],

package/dist/mcp/tools.js

@@ -23,8 +23,8 @@ const TOOL_DESCRIPTIONS = [
     { name: "set_volume", description: "Patch a volume radius/height/center." },
     { name: "set_path", description: "Patch a path's kind/width/color/label and merge-patch its meta (studio sliders: scatter density, pole spacing, …). Validated against the kind schema." },
     { name: "add_path", description: "Author a new path/route into the scene document from an ordered list of ≥2 {x,z} (optional y) points — the headless one-shot for placing a route without an export/import roundtrip. kind defaults to `route`; width/color/label/meta are optional and meta is validated against the kind schema. Re-ids on a document-global id collision." },
-    { name: "add_marker", description: "Author a new point marker into the scene document at x/z (optional y) — the headless one-shot for placing a logical marker (spawn, checkpoint, pickup, bounty, or a game's own custom kind) without an export/import roundtrip. kind is required; color/label/rotationY/meta are optional and meta is validated against the kind schema when registered. Re-ids on a document-global id collision." },
-    { name: "set_marker", description: "Patch a marker's kind/color/label/rotationY and merge-patch its meta. Validated against the kind schema when registered." },
+    { name: "add_marker", description: "Author a new point marker into the scene document at x/z (optional y) — the headless one-shot for placing a logical marker (spawn, checkpoint, pickup, bounty, or a game's own custom kind) without an export/import roundtrip. kind is required; color/label/rotationY/catalogId/meta are optional (catalogId names the entity kind a mob/boss marker spawns) and meta is validated against the kind schema when registered. Re-ids on a document-global id collision." },
+    { name: "set_marker", description: "Patch a marker's kind/color/label/rotationY/catalogId and merge-patch its meta. Validated against the kind schema when registered." },
     { name: "set_note", description: "Patch a note's text and merge-patch its meta." },
     { name: "set_meta", description: "Merge-patch the meta bag of any document object (marker/volume/path/note) by id — the generic studio-slider primitive. Rejected if it violates the kind's param schema." },
     { name: "apply_preset", description: "Apply a named preset bundle from the object's kind schema (e.g. a city archetype like manhattan/ruralohio) as one meta patch, ready to tweak afterwards." },
@@ -68,6 +68,7 @@ const TOOL_DESCRIPTIONS = [
     { name: "convert_scatter", description: "Detach a foliage/scatter region into individually-editable placed prop markers, removing the region." },
     { name: "generate_streets", description: "Bake the seed-driven street generator into the scene as authorable road/route paths inside a volume (or explicit center+halfX/halfZ). mode net→roads, circuit→closed route; params overlays sliders (gridness/loopiness/connectivity/winding/...). Idempotent: re-running the same seed replaces its own prior output. One undoable edit; round-trips --save." },
     { name: "bake_minimap", description: "Rasterize the authored terrain into a stored minimap PNG on the document (runtime reads it as the Minimap background). Live-editor only — needs the mounted viewport's terrain sampler, not a headless CLI." },
+    { name: "bakeNavMesh", description: "Bake indexed scene geometry (walkable faces counter-clockwise seen from above) into a named, agent-sized navigation mesh stored in the document." },
     { name: "add_foliage", description: "Add a foliage/scatter region from a closed polygon (≥3 x/z points) with density and item." },
     { name: "scatter_summary", description: "Count foliage/scatter regions and their total deterministic instance placements." },
     { name: "set_parent", description: "Parent objects under another (or null to unparent); cycles are refused. Moving a parent moves its subtree." },

package/dist/modelAnimationAuthoring.d.ts

@@ -1,3 +1,4 @@
+import { type AnimGraph } from "@jgengine/core/anim/animGraph";
 /**
  * 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
@@ -43,6 +44,8 @@ export interface AuthoredAnimationConfig {
     timeScale?: number;
     states?: AuthoredAnimationStates;
     oneShots?: Record<string, string>;
+    /** A stored animation graph; takes over from `states`/`oneShots` at play time. */
+    graph?: AnimGraph;
 }
 /** The value stored at `meta.animation`. */
 export type AnimationSetting = AuthoredAnimationConfig | "auto" | "none";
@@ -73,3 +76,23 @@ export declare function setOneShotClip(setting: AnimationSetting | undefined, ev
 export declare function animationMetaPatch(setting: AnimationSetting | undefined): {
     animation: AnimationSetting | undefined;
 };
+/** Where the graph a placement plays comes from. */
+export type AnimGraphSource = "authored" | "locomotion" | "auto";
+/**
+ * The graph a placement plays at run time: its stored `graph`, else the locomotion graph of its
+ * custom `states`/`oneShots`, else the one clip roles derive for `"auto"` and no-override placements.
+ * `null` for `"none"`, a single-clip config, or a rig whose clips have no idle.
+ */
+export declare function effectiveAnimGraph(setting: AnimationSetting | undefined, clips: readonly string[]): {
+    graph: AnimGraph;
+    source: AnimGraphSource;
+} | null;
+/** Stores `graph` on the placement, keeping its other fields; the stored graph wins at play time. */
+export declare function storeAnimGraph(setting: AnimationSetting | undefined, graph: AnimGraph): AuthoredAnimationConfig;
+/** Removes a stored graph so `states`/`oneShots` (or clip roles) drive the placement again. */
+export declare function clearAnimGraph(setting: AnimationSetting | undefined): AnimationSetting | undefined;
+/**
+ * Sets one transition's crossfade seconds in `graph` and stores the result, so editing a derived
+ * graph turns it into an authored one.
+ */
+export declare function setTransitionDuration(setting: AnimationSetting | undefined, graph: AnimGraph, layerId: string, index: number, duration: number): AuthoredAnimationConfig;

package/dist/modelAnimationAuthoring.js

@@ -1,4 +1,6 @@
-import { rolesFromClips } from "@jgengine/core/game/clipRoles";
+import { parseAnimGraph } from "@jgengine/core/anim/animGraph";
+import { animGraphFromConfig } from "@jgengine/core/anim/locomotionGraph";
+import { resolveAnimationConfig, rolesFromClips } from "@jgengine/core/game/clipRoles";
 /**
  * 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
@@ -63,6 +65,9 @@ export function readAnimationSetting(meta) {
         if (Object.keys(oneShots).length > 0)
             config.oneShots = oneShots;
     }
+    const graph = parseAnimGraph(value["graph"]);
+    if (graph !== undefined)
+        config.graph = graph;
     return config;
 }
 /** The authoring mode a stored setting maps to. */
@@ -162,3 +167,55 @@ export function setOneShotClip(setting, event, clipName) {
 export function animationMetaPatch(setting) {
     return { animation: setting };
 }
+/**
+ * The graph a placement plays at run time: its stored `graph`, else the locomotion graph of its
+ * custom `states`/`oneShots`, else the one clip roles derive for `"auto"` and no-override placements.
+ * `null` for `"none"`, a single-clip config, or a rig whose clips have no idle.
+ */
+export function effectiveAnimGraph(setting, clips) {
+    if (setting === "none")
+        return null;
+    if (setting !== undefined && setting !== "auto") {
+        if (setting.graph !== undefined)
+            return { graph: setting.graph, source: "authored" };
+        const states = setting.states;
+        if (states?.idle === undefined)
+            return null;
+        const graph = animGraphFromConfig({
+            states: { ...states, idle: states.idle, walk: states.walk ?? states.idle },
+            ...(setting.oneShots === undefined ? {} : { oneShots: setting.oneShots }),
+        });
+        return graph === undefined ? null : { graph, source: "locomotion" };
+    }
+    const resolved = resolveAnimationConfig("auto", clips);
+    const graph = resolved === undefined ? undefined : animGraphFromConfig(resolved);
+    return graph === undefined ? null : { graph, source: "auto" };
+}
+/** 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 });
+}
+/** 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;
+}
+/**
+ * Sets one transition's crossfade seconds in `graph` and stores the result, so editing a derived
+ * graph turns it into an authored one.
+ */
+export function setTransitionDuration(setting, graph, layerId, index, duration) {
+    const next = {
+        ...graph,
+        layers: graph.layers.map((layer) => layer.id !== layerId
+            ? layer
+            : {
+                ...layer,
+                transitions: layer.transitions.map((transition, i) => i === index ? { ...transition, duration: Math.max(0, Number.isFinite(duration) ? duration : 0) } : transition),
+            }),
+    };
+    return storeAnimGraph(setting, next);
+}

package/dist/session.d.ts

@@ -105,6 +105,7 @@ export type EditorBridgeRequest = {
     color?: string;
     label?: string;
     rotationY?: number;
+    catalogId?: string;
     meta?: Record<string, unknown>;
 } | {
     method: "set_marker";
@@ -113,6 +114,7 @@ export type EditorBridgeRequest = {
     color?: string;
     label?: string;
     rotationY?: number;
+    catalogId?: string;
     meta?: Record<string, unknown>;
 } | {
     method: "set_note";
@@ -246,6 +248,15 @@ export type EditorBridgeRequest = {
     padding?: number;
     resolution?: number;
     waterLevel?: number;
+} | {
+    method: "bakeNavMesh";
+    id: string;
+    positions: number[];
+    indices: number[];
+    agentRadius: number;
+    agentHeight: number;
+    maxSlope: number;
+    maxClimb: number;
 } | {
     method: "add_foliage";
     points: {

package/dist/session.js

@@ -1,6 +1,7 @@
 import { createDocumentLiveSync, createEditorSession, createRuntimePlayControl, installDocumentLiveSync, listEditorKinds, normalizeEditorLayers, resolveCatalogDefinitions, seedEditorCatalogs, } from "@jgengine/core/editor/index";
 import { registerBuiltinSceneKinds } from "@jgengine/core/scene/builtinSceneKinds";
 import { EDITOR_RPC_HANDLERS } from "./handlers/index.js";
+import { warmNavBake } from "./handlers/navmesh.js";
 import { emitEditorConsole } from "./shell/consoleSink.js";
 registerBuiltinSceneKinds();
 /** The accepted run modes, in canonical order — the runtime guard behind {@link EditorRunMode}. @internal */
@@ -22,6 +23,7 @@ export function getEditorHost() {
 }
 /** Builds and installs an editor host for a game: session, visibility, assets, and RPC handling. @internal */
 export function createEditorHost(options) {
+    warmNavBake();
     const catalogDefinitions = options.catalogs ?? [];
     const document = seedEditorCatalogs(normalizeEditorLayers(options.layers), catalogDefinitions);
     const session = createEditorSession(document);

package/dist/shell/AnimationGraphPanel.d.ts

@@ -0,0 +1,16 @@
+import type { EditorSession } from "@jgengine/core/editor/index";
+import type { EditorAssetEntry } from "../AssetBrowser.js";
+import type { EditorUiStore } from "../uiStore.js";
+/**
+ * Graph mode of the Animation dock: the selected placement's animation graph (layers, states,
+ * transitions), a scrubbed preview driven by the headless graph runtime and shown on the rig in the
+ * viewport, trigger buttons that record presses on the timeline, and crossfade editing that stores
+ * the graph on the placement as an undoable edit.
+ *
+ * @internal
+ */
+export declare function AnimationGraphPanel({ session, ui, rigged, }: {
+    session: EditorSession;
+    ui: EditorUiStore;
+    rigged: readonly EditorAssetEntry[];
+}): import("react").JSX.Element;

package/dist/shell/AnimationGraphPanel.js

@@ -0,0 +1,172 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
+import { animationMetaPatch, clearAnimGraph, effectiveAnimGraph, readAnimationSetting, setTransitionDuration, storeAnimGraph, } from "../modelAnimationAuthoring.js";
+import { shallowArrayEqual, useStoreSelector } from "../useStoreSelector.js";
+import { graphParamControls, graphTriggers, MAX_PREVIEW_SECONDS, recordTrigger, simulateGraphPreview, } from "./animGraphPreview.js";
+import { initialClipPreviewState } from "./clipPreview.js";
+import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
+import { EmptyState, IconButton } from "./ui.js";
+const SOURCE_LABEL = {
+    authored: "Stored on this placement",
+    locomotion: "Built from the placement's states and one-shots",
+    auto: "Derived from the rig's clip names",
+};
+function conditionText(condition) {
+    return `${condition.param} ${condition.op} ${String(condition.value)}`;
+}
+function stateClips(state) {
+    if (state.kind === "clip")
+        return state.clip;
+    if (state.kind === "blend1D")
+        return state.points.map((point) => `${point.clip}@${point.at}`).join(" · ");
+    return state.points.map((point) => `${point.clip}@${point.at[0]},${point.at[1]}`).join(" · ");
+}
+/**
+ * Graph mode of the Animation dock: the selected placement's animation graph (layers, states,
+ * transitions), a scrubbed preview driven by the headless graph runtime and shown on the rig in the
+ * viewport, trigger buttons that record presses on the timeline, and crossfade editing that stores
+ * the graph on the placement as an undoable edit.
+ *
+ * @internal
+ */
+export function AnimationGraphPanel({ session, ui, rigged, }) {
+    const selection = useStoreSelector(session, (state) => state.selection, shallowArrayEqual);
+    const markers = useStoreSelector(session, (state) => state.document.markers);
+    const target = useMemo(() => {
+        for (const id of selection) {
+            const marker = markers.find((entry) => entry.id === id);
+            if (marker === undefined)
+                continue;
+            const catalogId = markerCatalogId(marker);
+            const asset = catalogId === null ? undefined : rigged.find((entry) => entry.id === catalogId);
+            if (asset?.url !== undefined && asset.clips !== undefined)
+                return { marker, asset };
+        }
+        return null;
+    }, [selection, markers, rigged]);
+    if (target === null) {
+        return (_jsx(EmptyState, { icon: "film", title: "Animation graph", badge: "Placed rig", description: "Select a placed instance of a rigged asset to see the graph it plays: layers, states and transitions, with a scrubbed preview on the rig in the viewport." }));
+    }
+    return _jsx(GraphInspector, { session: session, ui: ui, marker: target.marker, asset: target.asset }, target.marker.id);
+}
+function GraphInspector({ session, ui, marker, asset, }) {
+    const clips = asset.clips ?? [];
+    const setting = readAnimationSetting(marker.meta);
+    const effective = useMemo(() => effectiveAnimGraph(setting, clips), [JSON.stringify(setting), clips]);
+    const graph = effective?.graph ?? null;
+    const controls = useMemo(() => (graph === null ? [] : graphParamControls(graph)), [graph]);
+    const triggerNames = useMemo(() => (graph === null ? [] : graphTriggers(graph)), [graph]);
+    const [time, setTime] = useState(0);
+    const [playing, setPlaying] = useState(false);
+    const [params, setParams] = useState({});
+    const [triggers, setTriggers] = useState([]);
+    const durations = useStoreSelector(ui, (state) => state.clipPreview?.clipDurations);
+    const frame = useMemo(() => {
+        if (graph === null)
+            return null;
+        const merged = {};
+        for (const control of controls)
+            merged[control.name] = params[control.name] ?? (control.kind === "boolean" ? false : 0);
+        return simulateGraphPreview({ graph, durations: durations ?? {}, time, params: merged, triggers });
+    }, [graph, controls, params, triggers, time, durations]);
+    useEffect(() => {
+        if (asset.url === undefined)
+            return;
+        const current = ui.getState().clipPreview;
+        const sameAsset = current?.source.assetId === asset.id;
+        ui.patch({
+            clipPreview: {
+                source: { assetId: asset.id, label: asset.label, url: asset.url, clips },
+                driver: initialClipPreviewState(null),
+                duration: 0,
+                ...(sameAsset && current?.clipDurations !== undefined ? { clipDurations: current.clipDurations } : {}),
+            },
+        });
+        return () => {
+            if (ui.getState().clipPreview?.source.assetId === asset.id)
+                ui.patch({ clipPreview: null });
+        };
+    }, [asset.id, asset.url, asset.label, clips, ui]);
+    useEffect(() => {
+        const current = ui.getState().clipPreview;
+        if (current === null || current.source.assetId !== asset.id)
+            return;
+        if (graph === null || frame === null) {
+            if (current.graphPose !== undefined)
+                ui.patch({ clipPreview: { ...current, graphPose: undefined } });
+            return;
+        }
+        ui.patch({ clipPreview: { ...current, graphPose: { graph, clips: frame.clips } } });
+    }, [graph, frame, asset.id, ui, durations]);
+    const timeRef = useRef(time);
+    timeRef.current = time;
+    useEffect(() => {
+        if (!playing)
+            return;
+        let handle = 0;
+        let last = performance.now();
+        const tick = (now) => {
+            const next = timeRef.current + Math.min(0.05, Math.max(0, (now - last) / 1000));
+            last = now;
+            if (next >= MAX_PREVIEW_SECONDS) {
+                setTime(MAX_PREVIEW_SECONDS);
+                setPlaying(false);
+                return;
+            }
+            setTime(next);
+            handle = requestAnimationFrame(tick);
+        };
+        handle = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(handle);
+    }, [playing]);
+    const commit = (next) => session.dispatch({ type: "setMarker", id: marker.id, patch: { meta: { ...marker.meta, ...animationMetaPatch(next) } } }, { coalesce: `animation:${marker.id}` });
+    if (graph === null || effective === null || frame === null) {
+        return (_jsx(EmptyState, { icon: "film", title: "No graph", badge: marker.label ?? marker.id, description: "This placement plays no graph: its animation is off, a single clip, or the rig has no idle clip. Pick Custom or Auto in the inspector's Animation section." }));
+    }
+    const weights = new Map(frame.clips.map((clip) => [`${clip.layer}:${clip.clip}`, clip.weight]));
+    const trigger = (name) => setTriggers((current) => recordTrigger(current, name, timeRef.current));
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsxs("div", { className: "flex h-7 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: [_jsx("span", { className: "text-[10px] uppercase tracking-wider text-neutral-500", children: marker.label ?? marker.id }), _jsxs("span", { className: "text-[10px] text-neutral-600", children: [asset.label, " \u00B7 ", SOURCE_LABEL[effective.source]] }), _jsx("div", { className: "ml-auto flex items-center gap-1", children: effective.source === "authored" ? (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit(clearAnimGraph(setting)), title: "Drop the stored graph", children: "Use derived graph" })) : (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit(storeAnimGraph(setting, graph)), title: "Store this graph on the placement", children: "Store graph" })) })] }), _jsxs("div", { className: "flex min-h-0 flex-1 gap-3 overflow-auto p-3", children: [_jsxs("div", { className: "flex w-64 shrink-0 flex-col gap-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(IconButton, { icon: playing ? "pause" : "play", label: playing ? "Pause preview" : "Play preview", size: 14, active: playing, onClick: () => setPlaying((value) => !value) }), _jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => {
+                                            setPlaying(false);
+                                            setTime(0);
+                                            setTriggers([]);
+                                        }, children: "Reset" }), _jsxs("span", { className: `ml-auto text-[10px] text-neutral-400 ${NUMERIC}`, children: [time.toFixed(2), " s"] })] }), _jsxs("label", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Scrub" }), _jsx("input", { type: "range", min: 0, max: MAX_PREVIEW_SECONDS, step: 0.01, value: time, "aria-label": "Graph preview time", className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => {
+                                            setPlaying(false);
+                                            setTime(Number(event.target.value));
+                                        } }), _jsx(TriggerTicks, { triggers: triggers })] }), controls.map((control) => control.kind === "boolean" ? (_jsxs("label", { className: "flex items-center gap-2 text-[11px] text-neutral-300", children: [_jsx("input", { type: "checkbox", checked: params[control.name] === true, "aria-label": `Parameter ${control.name}`, onChange: (event) => setParams((current) => ({ ...current, [control.name]: event.target.checked })) }), control.name] }, control.name)) : (_jsxs("label", { className: "flex flex-col gap-1", children: [_jsxs("div", { className: "flex items-center justify-between text-[9px] uppercase tracking-wider text-neutral-600", children: [_jsx("span", { children: control.name }), _jsx("span", { className: NUMERIC, children: Number(params[control.name] ?? 0).toFixed(2) })] }), _jsx("input", { type: "range", min: control.min, max: control.max, step: (control.max - control.min) / 200, value: Number(params[control.name] ?? 0), "aria-label": `Parameter ${control.name}`, className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => setParams((current) => ({ ...current, [control.name]: Number(event.target.value) })) })] }, control.name))), triggerNames.length > 0 ? (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Triggers at the playhead" }), _jsx("div", { className: "flex flex-wrap gap-1", children: triggerNames.map((name) => (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => trigger(name), children: name }, name))) })] })) : null, frame.events.length > 0 ? (_jsxs("div", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Clip events" }), frame.events.slice(-6).map((event, index) => (_jsxs("span", { className: `text-[10px] text-amber-200/80 ${NUMERIC}`, children: [event.at.toFixed(2), " s \u00B7 ", event.name, " (", event.clip, ")"] }, index)))] })) : null] }), _jsx("div", { className: "flex min-w-0 flex-1 flex-col gap-3", children: graph.layers.map((layer) => (_jsxs("section", { className: "rounded-[6px] border border-white/[0.07] bg-white/[0.02]", "aria-label": `Layer ${layer.id}`, children: [_jsxs("header", { className: "flex items-center gap-2 border-b border-white/[0.06] px-2.5 py-1.5", children: [_jsx("span", { className: "text-[11px] font-medium text-neutral-100", children: layer.id }), _jsxs("span", { className: "text-[10px] text-neutral-500", children: ["entry ", layer.entry] }), layer.mask !== undefined ? _jsxs(Chip, { children: ["mask ", layer.mask.join(", ")] }) : null, layer.additive === true ? _jsx(Chip, { children: "additive" }) : null, layer.weight !== undefined ? _jsxs(Chip, { children: ["weight ", layer.weight] }) : null, _jsxs("span", { className: "ml-auto text-[10px] text-cyan-200", children: ["\u25B6 ", frame.states[layer.id]] })] }), _jsxs("div", { className: "grid grid-cols-2 gap-3 p-2.5", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "States" }), Object.entries(layer.states).map(([name, state]) => {
+                                                    const active = frame.states[layer.id] === name;
+                                                    const clipsOfState = state.kind === "clip" ? [state.clip] : state.points.map((point) => point.clip);
+                                                    const weight = clipsOfState.reduce((sum, clip) => sum + (weights.get(`${layer.id}:${clip}`) ?? 0), 0);
+                                                    return (_jsxs("div", { className: `rounded-[5px] border px-2 py-1 ${active ? "border-cyan-400/40 bg-cyan-500/10" : "border-white/[0.05]"}`, children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-[11px] text-neutral-100", children: name }), _jsx("span", { className: "text-[10px] text-neutral-500", children: state.kind }), _jsx("span", { className: `ml-auto text-[10px] text-neutral-400 ${NUMERIC}`, children: weight > 0 ? weight.toFixed(2) : "" })] }), _jsx("div", { className: "truncate text-[10px] text-neutral-500", title: stateClips(state), children: stateClips(state) }), _jsx("div", { className: "mt-1 h-1 rounded bg-white/[0.05]", children: _jsx("div", { className: "h-1 rounded bg-cyan-400/70", style: { width: `${Math.round(Math.min(1, weight) * 100)}%` } }) })] }, name));
+                                                })] }), _jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Transitions" }), layer.transitions.length === 0 ? _jsx("span", { className: "text-[10px] text-neutral-600", children: "None" }) : null, layer.transitions.map((transition, index) => (_jsx(TransitionRow, { transition: transition, onTrigger: transition.trigger === undefined ? undefined : () => trigger(transition.trigger), onDuration: (duration) => commit(setTransitionDuration(setting, graph, layer.id, index, duration)) }, index)))] })] })] }, layer.id))) })] })] }));
+}
+const SMALL_BUTTON = `rounded-[5px] border border-white/[0.08] bg-white/[0.03] px-2 py-0.5 text-[10px] text-neutral-300 transition-colors hover:bg-white/[0.07] ${FOCUS_RING}`;
+function Chip({ children }) {
+    return _jsx("span", { className: "rounded-[4px] bg-white/[0.05] px-1.5 py-0.5 text-[9px] text-neutral-400", children: children });
+}
+function TriggerTicks({ triggers }) {
+    if (triggers.length === 0)
+        return null;
+    return (_jsx("div", { className: "relative h-3", "aria-label": "Recorded triggers", children: triggers.map((entry, index) => (_jsx("span", { title: `${entry.name} at ${entry.at.toFixed(2)} s`, className: "absolute top-0 h-3 w-0.5 bg-amber-300/80", style: { left: `${(entry.at / MAX_PREVIEW_SECONDS) * 100}%` } }, index))) }));
+}
+function TransitionRow({ transition, onTrigger, onDuration, }) {
+    const [draft, setDraft] = useState(String(transition.duration ?? 0.2));
+    useEffect(() => setDraft(String(transition.duration ?? 0.2)), [transition.duration]);
+    const label = `${transition.from} → ${transition.to}`;
+    return (_jsxs("div", { className: "flex items-center gap-1.5 rounded-[5px] border border-white/[0.05] px-2 py-1", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "truncate text-[11px] text-neutral-100", children: label }), _jsx("div", { className: "truncate text-[10px] text-neutral-500", children: [
+                            transition.trigger === undefined ? null : `trigger ${transition.trigger}`,
+                            ...(transition.when ?? []).map(conditionText),
+                            transition.exitTime === undefined ? null : `exit ${transition.exitTime}`,
+                        ]
+                            .filter((part) => part !== null)
+                            .join(" · ") || "always" })] }), _jsx("input", { className: `${INPUT_CLS} h-6 w-14 px-1 text-right text-[11px] ${NUMERIC}`, value: draft, "aria-label": `Crossfade seconds for ${label}`, inputMode: "decimal", onChange: (event) => setDraft(event.target.value), onBlur: () => {
+                    const value = Number(draft);
+                    if (Number.isFinite(value) && value !== (transition.duration ?? 0.2))
+                        onDuration(value);
+                    else
+                        setDraft(String(transition.duration ?? 0.2));
+                }, onKeyDown: (event) => {
+                    if (event.key === "Enter")
+                        event.target.blur();
+                } }), _jsx("span", { className: "text-[9px] text-neutral-600", children: "s" }), onTrigger !== undefined ? _jsx(IconButton, { icon: "play", label: `Trigger ${transition.trigger}`, size: 11, onClick: onTrigger }) : null] }));
+}

package/dist/shell/AnimationPanel.d.ts

@@ -3,7 +3,9 @@ import type { EditorAssetEntry } from "../AssetBrowser.js";
 import type { EditorHostApi } from "../session.js";
 import type { EditorUiStore } from "../uiStore.js";
 /**
- * Animation dock with two modes:
+ * Animation dock with three modes:
+ * - **Graph** — the selected placement's animation graph with a scrubbed, triggerable preview posed
+ *   on the rig in the viewport (see {@link AnimationGraphPanel}).
  * - **Path** — scrub/play the editor orbit camera along authored scene polylines (real path points,
  *   no fabricated keyframes).
  * - **Clips** — preview a rigged asset's animation clips in the viewport (scrub, loop, speed) via the

package/dist/shell/AnimationPanel.js

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
 import { shallowArrayEqual, useStoreSelector } from "../useStoreSelector.js";
 import { advancePreview, clipEntriesFromRef, initialClipPreviewState, MAX_PREVIEW_SPEED, MIN_PREVIEW_SPEED, scrubPreview, selectPreviewClip, setPreviewLoop, setPreviewSpeed, togglePreviewPlaying, } from "./clipPreview.js";
+import { AnimationGraphPanel } from "./AnimationGraphPanel.js";
 import { listScrubbablePaths, samplePathAt } from "./pathFlythrough.js";
 import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
 import { EmptyState, IconButton } from "./ui.js";
@@ -13,7 +14,9 @@ function riggedAssets(assets) {
     return assets.filter((entry) => entry.url !== undefined && entry.clips !== undefined && entry.clips.length > 0);
 }
 /**
- * Animation dock with two modes:
+ * Animation dock with three modes:
+ * - **Graph** — the selected placement's animation graph with a scrubbed, triggerable preview posed
+ *   on the rig in the viewport (see {@link AnimationGraphPanel}).
  * - **Path** — scrub/play the editor orbit camera along authored scene polylines (real path points,
  *   no fabricated keyframes).
  * - **Clips** — preview a rigged asset's animation clips in the viewport (scrub, loop, speed) via the
@@ -23,9 +26,7 @@ function riggedAssets(assets) {
  */
 export function AnimationPanel({ session, api, ui, assets, }) {
     const rigged = useMemo(() => riggedAssets(assets), [assets]);
-    // Default to clips only when the scene has rigged assets but no scrubbable path yet.
-    const paths = useStoreSelector(session, (state) => state.document.paths);
-    const [mode, setMode] = useState(() => rigged.length > 0 && listScrubbablePaths(paths).length === 0 ? "clips" : "path");
+    const [mode, setMode] = useState(() => (rigged.length > 0 ? "graph" : "path"));
     // Tear down the viewport preview when the panel unmounts; leaving clip mode tears down in the
     // tab click below.
     useEffect(() => () => {
@@ -33,13 +34,14 @@ export function AnimationPanel({ session, api, ui, assets, }) {
             ui.patch({ clipPreview: null });
     }, [ui]);
     return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsx("div", { className: "flex h-8 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: _jsx("div", { className: "flex items-center gap-0.5", role: "tablist", "aria-label": "Animation mode", children: [
-                        ["path", "Path flythrough"],
+                        ["graph", "Graph"],
                         ["clips", "Clip preview"],
+                        ["path", "Path flythrough"],
                     ].map(([id, label]) => (_jsx("button", { type: "button", role: "tab", "aria-selected": mode === id, className: `rounded-[5px] px-2 py-0.5 text-[10px] uppercase tracking-wider transition-colors ${FOCUS_RING} ${mode === id ? "bg-cyan-500/15 text-cyan-200" : "text-neutral-500 hover:text-neutral-300"}`, onClick: () => {
-                            if (id !== "clips" && ui.getState().clipPreview !== null)
+                            if (id !== mode && ui.getState().clipPreview !== null)
                                 ui.patch({ clipPreview: null });
                             setMode(id);
-                        }, children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : (_jsx(ClipPreview, { session: session, ui: ui, rigged: rigged }))] }));
+                        }, children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : mode === "graph" ? (_jsx(AnimationGraphPanel, { session: session, ui: ui, rigged: rigged })) : (_jsx(ClipPreview, { session: session, ui: ui, rigged: rigged }))] }));
 }
 /** Clip-preview mode: pick a rigged asset (placed instance or catalog) and play its clips in the viewport. */
 function ClipPreview({ session, ui, rigged, }) {

package/dist/shell/WorkspaceRail.js

@@ -8,7 +8,7 @@ export const WORKSPACES = [
     { id: "assets", label: "Assets", icon: "image", supported: true },
     { id: "materials", label: "Materials", icon: "sphere", supported: true },
     { id: "scripting", label: "Scripting", icon: "script", supported: true },
-    { id: "animation", label: "Animation", icon: "film", supported: false },
+    { id: "animation", label: "Animation", icon: "film", supported: true },
     { id: "audio", label: "Audio", icon: "audio", supported: false },
     { id: "lighting", label: "Lighting", icon: "bulb", supported: true },
     { id: "ai", label: "AI", icon: "sparkle", supported: true },

package/dist/shell/animGraphPreview.d.ts

@@ -0,0 +1,56 @@
+import { type AnimClipOutput, type AnimGraph, type AnimParams } from "@jgengine/core/anim/animGraph";
+/**
+ * Editor animation-graph preview: pure logic, no JSX. Replays a graph from its entry states to a
+ * scrub time with fixed steps, arming each recorded trigger at its time, so scrubbing back and forth
+ * always shows the same pose the runtime would reach.
+ *
+ * @internal
+ */
+/** A trigger pressed during preview, at a time on the scrub timeline. */
+export interface GraphPreviewTrigger {
+    at: number;
+    name: string;
+}
+/** Inputs for {@link simulateGraphPreview}. */
+export interface GraphPreviewInput {
+    graph: AnimGraph;
+    /** Clip durations in seconds from the loaded rig; unknown clips count as one second. */
+    durations: Readonly<Record<string, number>>;
+    time: number;
+    params: AnimParams;
+    triggers: readonly GraphPreviewTrigger[];
+    /** Fixed step in seconds. Default 1/30. */
+    step?: number;
+}
+/** What the rig shows at the scrub time. */
+export interface GraphPreviewFrame {
+    time: number;
+    /** Current state per layer id. */
+    states: Record<string, string>;
+    clips: AnimClipOutput[];
+    /** Clip events fired from zero to `time`, with when they fired. */
+    events: {
+        at: number;
+        name: string;
+        clip: string;
+    }[];
+}
+/** Longest preview timeline the scrubber offers, in seconds. */
+export declare const MAX_PREVIEW_SECONDS = 20;
+/** Replays `graph` from its entry states to `time` and reports the pose there. */
+export declare function simulateGraphPreview(input: GraphPreviewInput): GraphPreviewFrame;
+/** Every clip name a graph plays. */
+export declare function graphClipNames(graph: AnimGraph): string[];
+/** Every trigger name a graph's transitions listen for, in first-seen order. */
+export declare function graphTriggers(graph: AnimGraph): string[];
+/** A parameter the preview needs a control for: blend inputs and condition operands. */
+export interface GraphParamControl {
+    name: string;
+    kind: "number" | "boolean";
+    min: number;
+    max: number;
+}
+/** Parameters a graph reads, with a range covering its blend points and condition values. */
+export declare function graphParamControls(graph: AnimGraph): GraphParamControl[];
+/** Adds a trigger press at `at`, keeping the log in time order. */
+export declare function recordTrigger(triggers: readonly GraphPreviewTrigger[], name: string, at: number): GraphPreviewTrigger[];

package/dist/shell/animGraphPreview.js

@@ -0,0 +1,92 @@
+import { createAnimGraphRuntime, } from "@jgengine/core/anim/animGraph";
+/** Longest preview timeline the scrubber offers, in seconds. */
+export const MAX_PREVIEW_SECONDS = 20;
+/** Replays `graph` from its entry states to `time` and reports the pose there. */
+export function simulateGraphPreview(input) {
+    const step = input.step ?? 1 / 30;
+    const time = Math.max(0, Math.min(MAX_PREVIEW_SECONDS, input.time));
+    const runtime = createAnimGraphRuntime(input.graph);
+    const clips = {};
+    for (const name of graphClipNames(input.graph))
+        clips[name] = input.durations[name] ?? 1;
+    const pending = [...input.triggers].filter((trigger) => trigger.at <= time).sort((a, b) => a.at - b.at);
+    const events = [];
+    let elapsed = 0;
+    let next = 0;
+    let out = runtime.advance(0, input.params, clips);
+    while (elapsed < time - 1e-9) {
+        const dt = Math.min(step, time - elapsed);
+        while (next < pending.length && pending[next].at <= elapsed + 1e-9)
+            runtime.trigger(pending[next++].name);
+        out = runtime.advance(dt, input.params, clips);
+        elapsed += dt;
+        for (const event of out.events)
+            events.push({ at: elapsed, name: event.name, clip: event.clip });
+    }
+    if (next < pending.length) {
+        while (next < pending.length)
+            runtime.trigger(pending[next++].name);
+        out = runtime.advance(0, input.params, clips);
+    }
+    const states = {};
+    for (const layer of input.graph.layers)
+        states[layer.id] = runtime.stateOf(layer.id) ?? layer.entry;
+    return { time, states, clips: out.clips, events };
+}
+/** Every clip name a graph plays. */
+export function graphClipNames(graph) {
+    const names = new Set();
+    for (const layer of graph.layers) {
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "clip")
+                names.add(state.clip);
+            else
+                for (const point of state.points)
+                    names.add(point.clip);
+        }
+    }
+    return [...names];
+}
+/** Every trigger name a graph's transitions listen for, in first-seen order. */
+export function graphTriggers(graph) {
+    const names = new Set();
+    for (const layer of graph.layers)
+        for (const transition of layer.transitions)
+            if (transition.trigger !== undefined)
+                names.add(transition.trigger);
+    return [...names];
+}
+/** Parameters a graph reads, with a range covering its blend points and condition values. */
+export function graphParamControls(graph) {
+    const controls = new Map();
+    const widen = (name, value) => {
+        const kind = typeof value === "boolean" ? "boolean" : "number";
+        const current = controls.get(name) ?? { name, kind, min: 0, max: 1 };
+        if (kind === "number") {
+            current.min = Math.min(current.min, value);
+            current.max = Math.max(current.max, value * 1.25, value + 0.5);
+        }
+        controls.set(name, current);
+    };
+    for (const layer of graph.layers) {
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "blend1D")
+                for (const point of state.points)
+                    widen(state.param, point.at);
+            if (state.kind === "blend2D") {
+                for (const point of state.points) {
+                    widen(state.params[0], point.at[0]);
+                    widen(state.params[1], point.at[1]);
+                }
+            }
+        }
+        for (const transition of layer.transitions)
+            for (const condition of transition.when ?? [])
+                widen(condition.param, condition.value);
+    }
+    return [...controls.values()];
+}
+/** Adds a trigger press at `at`, keeping the log in time order. */
+export function recordTrigger(triggers, name, at) {
+    return [...triggers, { at, name }].sort((a, b) => a.at - b.at);
+}