@jgengine/editor 0.19.0 → 0.22.0

package/dist/SelectionGizmo.js

@@ -4,6 +4,7 @@ import { memo, useEffect, useMemo } from "react";
 import * as THREE from "three";
 import { findEditorMarker, findEditorNote, findEditorPath, findEditorVolume, } from "@jgengine/core/editor/index";
 import { TransformGizmo, } from "@jgengine/shell/structures/TransformGizmo";
+import { placementGround, pathSegmentDistance, selectionGizmoMode, snapPlacement } from "./authoringPlacement.js";
 import { isPointerClick } from "./viewportContextMenu.js";
 import { resolvePivotPosition } from "./gizmoPivot.js";
 import { newPlacementId, } from "./uiStore.js";
@@ -108,13 +109,17 @@ export const ViewportSelect = memo(function ViewportSelect({ api, ui }) {
         const planeHit = new THREE.Vector3();
         let down = null;
         const session = () => api.getSession();
-        const screenDistance = (point, lift, clickX, clickY, rect) => {
+        const screenPoint = (point, lift, rect) => {
             projected.set(point.x, point.y + lift, point.z).project(camera);
             if (projected.z < -1 || projected.z > 1)
                 return null;
             const px = (projected.x * 0.5 + 0.5) * rect.width;
             const py = (-projected.y * 0.5 + 0.5) * rect.height;
-            return Math.hypot(px - clickX, py - clickY);
+            return { x: px, y: py };
+        };
+        const screenDistance = (point, lift, clickX, clickY, rect) => {
+            const projectedPoint = screenPoint(point, lift, rect);
+            return projectedPoint === null ? null : Math.hypot(projectedPoint.x - clickX, projectedPoint.y - clickY);
         };
         const groundPoint = (clickX, clickY, rect) => {
             ndc.set((clickX / rect.width) * 2 - 1, -(clickY / rect.height) * 2 + 1);
@@ -135,6 +140,11 @@ export const ViewportSelect = memo(function ViewportSelect({ api, ui }) {
             const placement = ui.getState().placement;
             if (placement === null)
                 return;
+            const ground = placementGround(session().getState().document.terrain, api.getTerrainSampler());
+            const snapped = snapPlacement(point, ui.getState().snapMode, ui.getState().gridSize, (x, z) => ground?.sampleHeight(x, z) ?? 0);
+            if (snapped === null)
+                return;
+            point = snapped;
             if (placement.tool === "path") {
                 ui.pushDraftPoint(point);
                 return;
@@ -201,11 +211,17 @@ export const ViewportSelect = memo(function ViewportSelect({ api, ui }) {
                 if (visibility[path.kind] === false || path.hidden === true)
                     continue;
                 let best = null;
+                let previous = null;
                 for (const point of path.points) {
-                    const distance = screenDistance(point, 0.8, clickX, clickY, rect);
-                    if (distance !== null && distance < SCREEN_PICK_RADIUS_PX && (best === null || distance < best)) {
-                        best = distance;
+                    const projectedPoint = screenPoint(point, 0.8, rect);
+                    if (projectedPoint !== null) {
+                        const distance = previous === null
+                            ? Math.hypot(projectedPoint.x - clickX, projectedPoint.y - clickY)
+                            : pathSegmentDistance({ x: clickX, y: clickY }, previous, projectedPoint);
+                        if (distance < SCREEN_PICK_RADIUS_PX && (best === null || distance < best))
+                            best = distance;
                     }
+                    previous = projectedPoint;
                 }
                 if (best !== null)
                     candidates.push({ id: path.id, distance: best });
@@ -410,7 +426,7 @@ export const ViewportSelect = memo(function ViewportSelect({ api, ui }) {
 });
 function resolveTarget(session, selection, pathPoint, pivot) {
     const { document } = session.getState();
-    if (pathPoint !== null) {
+    if (pathPoint !== null && selection.length === 1 && selection[0] === pathPoint.pathId) {
         const path = findEditorPath(document, pathPoint.pathId);
         const point = path?.points[pathPoint.index];
         if (point !== undefined)
@@ -436,13 +452,6 @@ function resolveTarget(session, selection, pathPoint, pivot) {
     // Multi-select always translates as a group from the pivot; rotation/scale stay primary-kind limited.
     return { position: pivotPos, lift: primary.lift, rotationY: primary.rotationY, kind: primary.kind };
 }
-function effectiveMode(mode, kind) {
-    if (kind === "marker")
-        return mode === "scale" ? "translate" : mode;
-    if (kind === "volume")
-        return mode === "rotate" ? "translate" : mode;
-    return "translate";
-}
 /**
  * Drag-to-transform gizmo bound to the current selection, dispatching editor commands on
  * release. Mounts the shared shell `TransformGizmo` and maps release poses onto editor
@@ -453,7 +462,7 @@ export const SelectionGizmo = memo(function SelectionGizmo({ session, ui, ground
     const state = session.getState();
     const selectedId = state.selection[0];
     const target = useMemo(() => resolveTarget(session, state.selection, uiState.pathPoint, uiState.gizmoPivot), [state, uiState.pathPoint, uiState.gizmoPivot, session]);
-    const mode = target === null ? "translate" : effectiveMode(uiState.gizmoMode, target.kind);
+    const mode = target === null ? "translate" : selectionGizmoMode(uiState.gizmoMode, target.kind, target.kind === "pathPoint" ? 1 : state.selection.length);
     if (target === null)
         return null;
     const onRelease = (pose) => {

package/dist/SimulationInspector.d.ts

@@ -0,0 +1,9 @@
+import type { CreatorPolicy } from "@jgengine/core/editor/creatorStorage";
+import type { EditorSession } from "@jgengine/core/editor/commands";
+/** Production authoring controls share the same validated command and undo history as RPC.
+ * @capability simulation-inspector author weather schedules, effects, fire, wind zones, forces and habitats with validated undoable controls
+ */
+export declare function SimulationInspector({ session, creatorPolicy }: {
+    session: EditorSession;
+    creatorPolicy?: CreatorPolicy;
+}): import("react").JSX.Element;

package/dist/SimulationInspector.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { useStoreSelector } from "./useStoreSelector.js";
+const modes = ["clear", "rain", "snow", "mixed", "dust"];
+function NumberInput({ label, value, onChange, min = 0, step = 0.1 }) {
+    return _jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { children: label }), _jsx("input", { "aria-label": label, className: "w-24 rounded border border-neutral-700 bg-neutral-900 p-1", type: "number", min: min, step: step, value: value, onChange: (event) => onChange(Number(event.target.value)) })] });
+}
+/** Production authoring controls share the same validated command and undo history as RPC.
+ * @capability simulation-inspector author weather schedules, effects, fire, wind zones, forces and habitats with validated undoable controls
+ */
+export function SimulationInspector({ session, creatorPolicy }) {
+    const simulation = useStoreSelector(session, (state) => state.document.simulation);
+    const [error, setError] = useState(null);
+    const [advanced, setAdvanced] = useState(null);
+    const [species, setSpecies] = useState("");
+    const weather = simulation?.weather ?? {};
+    const allowWeather = creatorPolicy === undefined || (creatorPolicy.maxSimulationParticles ?? 0) >= 5556;
+    const allowEmitters = creatorPolicy === undefined || (creatorPolicy.maxSimulationParticles ?? 0) > 0;
+    const allowFire = creatorPolicy === undefined || (creatorPolicy.maxFireCells ?? 0) > 0;
+    const allowFlocks = creatorPolicy === undefined || (creatorPolicy.maxPopulation ?? 0) > 0;
+    const allowForces = creatorPolicy === undefined || (creatorPolicy.maxForceFields ?? 0) > 0;
+    function update(next) {
+        try {
+            session.dispatch({ type: "setSimulation", simulation: next });
+            setError(null);
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : String(reason));
+        }
+    }
+    function setWeather(next) { update({ ...simulation, weather: next }); }
+    function id(prefix, rows) {
+        let index = 1;
+        while (rows.some((row) => row.id === `${prefix}-${index}`))
+            index += 1;
+        return `${prefix}-${index}`;
+    }
+    return _jsxs("section", { "aria-label": "Simulation authoring", className: "space-y-4 p-3 text-xs text-neutral-300", children: [_jsx("h3", { className: "text-sm font-semibold text-neutral-100", children: "Weather & simulation" }), _jsx("p", { children: "Metres \u00B7 game seconds \u00B7 wind on world X/Z. Save stores authored inputs; play state saves separately." }), error !== null ? _jsx("p", { role: "alert", className: "text-red-300", children: error }) : null, _jsxs("fieldset", { hidden: !allowWeather, className: "space-y-2", children: [_jsx("legend", { children: "Ambient weather" }), _jsxs("label", { className: "flex justify-between", children: ["Mode", _jsx("select", { "aria-label": "Weather mode", value: weather.ambient?.mode ?? "clear", onChange: (event) => setWeather({ ...weather, ambient: { ...weather.ambient, mode: event.target.value, intensity: weather.ambient?.intensity ?? 1 } }), children: modes.map((mode) => _jsx("option", { children: mode }, mode)) })] }), _jsx(NumberInput, { label: "Weather intensity", value: weather.ambient?.intensity ?? 0, onChange: (intensity) => setWeather({ ...weather, ambient: { mode: "clear", ...weather.ambient, intensity } }) }), _jsx(NumberInput, { label: "Temperature offset \u00B0C", min: -100, value: weather.ambient?.temperatureOffset ?? 0, onChange: (temperatureOffset) => setWeather({ ...weather, ambient: { mode: "clear", intensity: 0, ...weather.ambient, temperatureOffset } }) }), _jsx(NumberInput, { label: "Wind speed m/s", value: weather.wind?.speed ?? 0, onChange: (speed) => setWeather({ ...weather, wind: { ...weather.wind, speed } }) }), _jsx(NumberInput, { label: "Wind X direction", min: -1, value: weather.wind?.direction?.[0] ?? 1, onChange: (x) => setWeather({ ...weather, wind: { ...weather.wind, direction: [x, weather.wind?.direction?.[1] ?? 0] } }) }), _jsx(NumberInput, { label: "Wind Z direction", min: -1, value: weather.wind?.direction?.[1] ?? 0, onChange: (z) => setWeather({ ...weather, wind: { ...weather.wind, direction: [weather.wind?.direction?.[0] ?? 1, z] } }) })] }), _jsxs("fieldset", { hidden: !allowWeather, className: "space-y-2", children: [_jsx("legend", { children: "Named profiles" }), (weather.profiles ?? []).map((profile, index) => _jsxs("div", { className: "space-y-1 border-l border-neutral-700 pl-2", children: [_jsxs("label", { children: ["Profile id", _jsx("input", { "aria-label": `Profile ${index + 1} id`, value: profile.id, onChange: (event) => {
+                                            const nextId = event.target.value;
+                                            setWeather({ ...weather, initialProfileId: weather.initialProfileId === profile.id ? nextId : weather.initialProfileId, profiles: weather.profiles.map((row, i) => i === index ? { ...row, id: nextId } : row), schedule: weather.schedule?.map((row) => row.profileId === profile.id ? { ...row, profileId: nextId } : row) });
+                                        } })] }), _jsx("select", { "aria-label": `Profile ${profile.id} mode`, value: profile.mode, onChange: (event) => setWeather({ ...weather, profiles: weather.profiles.map((row, i) => i === index ? { ...row, mode: event.target.value } : row) }), children: modes.map((mode) => _jsx("option", { children: mode }, mode)) }), _jsx(NumberInput, { label: `Profile ${profile.id} intensity`, value: profile.intensity, onChange: (intensity) => setWeather({ ...weather, profiles: weather.profiles.map((row, i) => i === index ? { ...row, intensity } : row) }) }), _jsx("button", { type: "button", onClick: () => setWeather({ ...weather, profiles: weather.profiles.filter((_, i) => i !== index), initialProfileId: weather.initialProfileId === profile.id ? undefined : weather.initialProfileId, schedule: weather.schedule?.filter((row) => row.profileId !== profile.id) }), children: "Remove profile" })] }, profile.id)), _jsx("button", { type: "button", onClick: () => setWeather({ ...weather, profiles: [...(weather.profiles ?? []), { id: id("profile", weather.profiles ?? []), mode: "rain", intensity: 0.5 }] }), children: "Add weather profile" })] }), _jsxs("fieldset", { hidden: !allowWeather, className: "space-y-2", children: [_jsx("legend", { children: "Schedule" }), (weather.schedule ?? []).map((transition, index) => _jsxs("div", { className: "space-y-1 border-l border-neutral-700 pl-2", children: [_jsx("select", { "aria-label": `Transition ${index + 1} profile`, value: transition.profileId, onChange: (event) => setWeather({ ...weather, schedule: weather.schedule.map((row, i) => i === index ? { ...row, profileId: event.target.value } : row) }), children: weather.profiles?.map((profile) => _jsx("option", { children: profile.id }, profile.id)) }), _jsx(NumberInput, { label: `Transition ${index + 1} at seconds`, value: transition.atSeconds, onChange: (atSeconds) => setWeather({ ...weather, schedule: weather.schedule.map((row, i) => i === index ? { ...row, atSeconds } : row) }) }), _jsx(NumberInput, { label: `Transition ${index + 1} duration seconds`, value: transition.transitionSeconds ?? 0, onChange: (transitionSeconds) => setWeather({ ...weather, schedule: weather.schedule.map((row, i) => i === index ? { ...row, transitionSeconds } : row) }) }), _jsx("button", { type: "button", onClick: () => setWeather({ ...weather, schedule: weather.schedule.filter((_, i) => i !== index) }), children: "Remove transition" })] }, index)), _jsx("button", { type: "button", disabled: !weather.profiles?.length, onClick: () => setWeather({ ...weather, schedule: [...(weather.schedule ?? []), { atSeconds: (weather.schedule?.at(-1)?.atSeconds ?? 0) + 10, profileId: weather.profiles[0].id, transitionSeconds: 2 }] }), children: "Add transition" })] }), _jsxs("fieldset", { hidden: !allowWeather, className: "space-y-2", children: [_jsx("legend", { children: "Local wind zones" }), (weather.zones ?? []).map((zone, index) => _jsxs("div", { className: "space-y-1 border-l border-neutral-700 pl-2", children: [_jsx("span", { children: zone.id }), _jsx(NumberInput, { label: `${zone.id} X metres`, min: -1e6, value: zone.center[0], onChange: (x) => setWeather({ ...weather, zones: weather.zones.map((row, i) => i === index ? { ...row, center: [x, row.center[1]] } : row) }) }), _jsx(NumberInput, { label: `${zone.id} Z metres`, min: -1e6, value: zone.center[1], onChange: (z) => setWeather({ ...weather, zones: weather.zones.map((row, i) => i === index ? { ...row, center: [row.center[0], z] } : row) }) }), _jsx(NumberInput, { label: `${zone.id} radius metres`, value: zone.radius, onChange: (radius) => setWeather({ ...weather, zones: weather.zones.map((row, i) => i === index ? { ...row, radius } : row) }) }), _jsx(NumberInput, { label: `${zone.id} speed m/s`, value: zone.wind?.speed ?? 0, onChange: (speed) => setWeather({ ...weather, zones: weather.zones.map((row, i) => i === index ? { ...row, wind: { ...row.wind, speed } } : row) }) }), _jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: zone.radial ?? false, onChange: (event) => setWeather({ ...weather, zones: weather.zones.map((row, i) => i === index ? { ...row, radial: event.target.checked } : row) }) }), " Radial wind"] }), _jsx("button", { type: "button", onClick: () => setWeather({ ...weather, zones: weather.zones.filter((_, i) => i !== index) }), children: "Remove wind zone" })] }, zone.id)), _jsx("button", { type: "button", onClick: () => setWeather({ ...weather, zones: [...(weather.zones ?? []), { id: id("wind", weather.zones ?? []), center: [0, 0], radius: 10, falloff: 5, wind: { direction: [1, 0], speed: 3 } }] }), children: "Add wind zone" })] }), _jsxs("fieldset", { hidden: !allowForces, className: "space-y-2", children: [_jsx("legend", { children: "Spatial forces" }), (simulation?.forces ?? []).map((field, index) => _jsxs("div", { className: "space-y-1 border-l border-neutral-700 pl-2", children: [[0, 1, 2].map((axis) => _jsx(NumberInput, { label: `Force ${index + 1} ${["X", "Y", "Z"][axis]} metres`, min: -1e6, value: field.center[axis], onChange: (value) => update({ ...simulation, forces: simulation.forces.map((row, i) => i === index ? { ...row, center: row.center.map((entry, j) => j === axis ? value : entry) } : row) }) }, axis)), field.shape.kind === "sphere" ? _jsx(NumberInput, { label: `Force ${index + 1} radius metres`, value: field.shape.radius, onChange: (radius) => update({ ...simulation, forces: simulation.forces.map((row, i) => i === index ? { ...row, shape: { kind: "sphere", radius } } : row) }) }) : _jsx("span", { children: "Box bounds are available in advanced editing." }), _jsx(NumberInput, { label: `Force ${index + 1} attraction m/s²`, min: -1e6, value: field.strength, onChange: (strength) => update({ ...simulation, forces: simulation.forces.map((row, i) => i === index ? { ...row, strength } : row) }) }), _jsx(NumberInput, { label: `Force ${index + 1} vortex m/s²`, min: -1e6, value: field.vortex?.strength ?? 0, onChange: (strength) => update({ ...simulation, forces: simulation.forces.map((row, i) => i === index ? { ...row, vortex: { axis: [0, 1, 0], ...row.vortex, strength } } : row) }) }), _jsx(NumberInput, { label: `Force ${index + 1} lift m/s²`, min: -1e6, value: field.vortex?.lift ?? 0, onChange: (lift) => update({ ...simulation, forces: simulation.forces.map((row, i) => i === index ? { ...row, vortex: { axis: [0, 1, 0], strength: 0, ...row.vortex, lift } } : row) }) }), _jsx(NumberInput, { label: `Force ${index + 1} falloff`, value: field.attenuation ?? 1, onChange: (attenuation) => update({ ...simulation, forces: simulation.forces.map((row, i) => i === index ? { ...row, attenuation } : row) }) }), _jsx("button", { type: "button", onClick: () => update({ ...simulation, forces: simulation.forces.filter((_, i) => i !== index) }), children: "Remove force" })] }, index)), _jsx("button", { type: "button", onClick: () => update({ ...simulation, forces: [...(simulation?.forces ?? []), { center: [0, 0, 0], shape: { kind: "sphere", radius: 10 }, strength: 0, attenuation: 1, vortex: { axis: [0, 1, 0], strength: 2, lift: 1 }, mask: 1 }] }), children: "Add spatial force" })] }), _jsxs("fieldset", { hidden: !allowEmitters, className: "space-y-2", children: [_jsx("legend", { children: "Named effects" }), (simulation?.emitters ?? []).map((emitter, index) => _jsxs("div", { className: "space-y-1 border-l border-neutral-700 pl-2", children: [_jsx("span", { children: emitter.id }), _jsx("select", { "aria-label": `${emitter.id} appearance`, value: emitter.options?.render?.shape ?? "point", onChange: (event) => update({ ...simulation, emitters: simulation.emitters.map((row, i) => i === index ? { ...row, options: { ...row.options, render: { shape: event.target.value } } } : row) }), children: ["point", "streak", "flake", "flame", "smoke", "ribbon", "ripple"].map((shape) => _jsx("option", { children: shape }, shape)) }), _jsx(NumberInput, { label: `${emitter.id} particles/second`, value: emitter.config.rate ?? 0, onChange: (rate) => update({ ...simulation, emitters: simulation.emitters.map((row, i) => i === index ? { ...row, config: { ...row.config, rate } } : row) }) }), _jsx(NumberInput, { label: `${emitter.id} particle capacity`, step: 1, value: emitter.config.max ?? 512, onChange: (max) => update({ ...simulation, emitters: simulation.emitters.map((row, i) => i === index ? { ...row, config: { ...row.config, max } } : row) }) }), ["x", "y", "z"].map((axis) => _jsx(NumberInput, { label: `${emitter.id} ${axis.toUpperCase()} metres`, min: -1e6, value: emitter.position[axis], onChange: (value) => update({ ...simulation, emitters: simulation.emitters.map((row, i) => i === index ? { ...row, position: { ...row.position, [axis]: value } } : row) }) }, axis)), _jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: emitter.options?.active !== false, onChange: (event) => update({ ...simulation, emitters: simulation.emitters.map((row, i) => i === index ? { ...row, options: { ...row.options, active: event.target.checked } } : row) }) }), " Spawning"] }), _jsxs("label", { children: ["Fire binding", _jsxs("select", { "aria-label": `${emitter.id} fire area`, value: emitter.fireAreaId ?? "", onChange: (event) => update({ ...simulation, emitters: simulation.emitters.map((row, i) => i === index ? { ...row, fireAreaId: event.target.value || undefined } : row) }), children: [_jsx("option", { value: "", children: "Independent" }), simulation?.fires?.map((area) => _jsx("option", { children: area.id }, area.id))] })] }), _jsx("button", { type: "button", onClick: () => update({ ...simulation, emitters: simulation.emitters.filter((_, i) => i !== index) }), children: "Remove emitter" })] }, emitter.id)), _jsx("button", { type: "button", onClick: () => update({ ...simulation, emitters: [...(simulation?.emitters ?? []), { id: id("emitter", simulation?.emitters ?? []), position: { x: 0, y: 1, z: 0 }, config: { rate: 8, max: 64, lifetime: { min: 1, max: 2 }, seed: "authored" }, options: { render: { shape: "smoke" } } }] }), children: "Add named emitter" })] }), _jsxs("fieldset", { hidden: !allowFire, className: "space-y-2", children: [_jsx("legend", { children: "Fire areas" }), (simulation?.fires ?? []).map((area, index) => _jsxs("div", { className: "space-y-1 border-l border-neutral-700 pl-2", children: [_jsx("span", { children: area.id }), ["x", "y", "z"].map((axis) => _jsx(NumberInput, { label: `${area.id} ${axis.toUpperCase()} metres`, min: -1e6, value: area.position[axis], onChange: (value) => update({ ...simulation, fires: simulation.fires.map((row, i) => i === index ? { ...row, position: { ...row.position, [axis]: value } } : row) }) }, axis)), _jsx(NumberInput, { label: `${area.id} cell size metres`, value: area.config.cellSize, onChange: (cellSize) => update({ ...simulation, fires: simulation.fires.map((row, i) => i === index ? { ...row, config: { ...row.config, cellSize } } : row) }) }), _jsx(NumberInput, { label: `${area.id} fuel consumed/second`, value: area.config.burnRate ?? 0.25, onChange: (burnRate) => update({ ...simulation, fires: simulation.fires.map((row, i) => i === index ? { ...row, config: { ...row.config, burnRate } } : row) }) }), _jsx(NumberInput, { label: `${area.id} rain cooling heat/second`, value: area.extinguishRate ?? 0, onChange: (extinguishRate) => update({ ...simulation, fires: simulation.fires.map((row, i) => i === index ? { ...row, extinguishRate } : row) }) }), _jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: (area.ignitions?.length ?? 0) > 0, onChange: (event) => update({ ...simulation, fires: simulation.fires.map((row, i) => i === index ? { ...row, ignitions: event.target.checked ? [{ col: 0, row: 0 }] : [] } : row) }) }), " Ignite first cell on play"] }), _jsx("button", { type: "button", onClick: () => update({ ...simulation, fires: simulation.fires.filter((_, i) => i !== index), emitters: simulation?.emitters?.map((emitter) => emitter.fireAreaId === area.id ? { ...emitter, fireAreaId: undefined } : emitter) }), children: "Remove fire area" })] }, area.id)), _jsx("button", { type: "button", onClick: () => update({ ...simulation, fires: [...(simulation?.fires ?? []), { id: id("fire", simulation?.fires ?? []), position: { x: 0, y: 0, z: 0 }, config: { cols: 4, rows: 4, cellSize: 1 }, ignitions: [] }] }), children: "Add fire area" })] }), _jsxs("fieldset", { hidden: !allowFlocks, className: "space-y-2", children: [_jsx("legend", { children: "Flock habitats" }), (simulation?.habitats ?? []).map((habitat, index) => _jsxs("div", { className: "space-y-1 border-l border-neutral-700 pl-2", children: [_jsxs("span", { children: [habitat.id, " \u00B7 ", habitat.species] }), _jsxs("select", { "aria-label": `${habitat.id} role`, value: habitat.role, onChange: (event) => update({ ...simulation, habitats: simulation.habitats.map((row, i) => i === index ? { ...row, role: event.target.value } : row) }), children: [_jsx("option", { children: "cosmetic" }), _jsx("option", { children: "gameplay" })] }), _jsx(NumberInput, { label: `${habitat.id} bird count`, step: 1, value: habitat.count, onChange: (count) => update({ ...simulation, habitats: simulation.habitats.map((row, i) => i === index ? { ...row, count } : row) }) }), _jsx(NumberInput, { label: `${habitat.id} radius metres`, value: habitat.radius, onChange: (radius) => update({ ...simulation, habitats: simulation.habitats.map((row, i) => i === index ? { ...row, radius } : row) }) }), ["x", "y", "z"].map((axis) => _jsx(NumberInput, { label: `${habitat.id} ${axis.toUpperCase()} metres`, min: -1e6, value: habitat.position[axis], onChange: (value) => update({ ...simulation, habitats: simulation.habitats.map((row, i) => i === index ? { ...row, position: { ...row.position, [axis]: value } } : row) }) }, axis)), _jsxs("select", { "aria-label": `${habitat.id} route`, value: habitat.routeId ?? "", onChange: (event) => update({ ...simulation, habitats: simulation.habitats.map((row, i) => i === index ? { ...row, routeId: event.target.value || undefined } : row) }), children: [_jsx("option", { value: "", children: "Stay in habitat" }), session.getState().document.paths.filter((path) => path.points.length > 1).map((path) => _jsx("option", { value: path.id, children: path.label ?? path.id }, path.id))] }), _jsx("button", { type: "button", onClick: () => update({ ...simulation, habitats: simulation.habitats.filter((_, i) => i !== index) }), children: "Remove habitat" })] }, habitat.id)), _jsxs("label", { children: ["Game species", _jsx("input", { "aria-label": "Game species", value: species, onChange: (event) => setSpecies(event.target.value) })] }), _jsx("button", { type: "button", disabled: !species.trim(), onClick: () => update({ ...simulation, habitats: [...(simulation?.habitats ?? []), { id: id("habitat", simulation?.habitats ?? []), species: species.trim(), position: { x: 0, y: 4, z: 0 }, radius: 8, count: 8, seed: "authored", role: "cosmetic", steering: { maxSpeed: 4, separationRadius: 1, neighborRadius: 5 } }] }), children: "Add flock habitat" })] }), _jsx("button", { type: "button", onClick: () => setAdvanced(JSON.stringify(simulation ?? {}, null, 2)), children: "Edit complete simulation data" }), advanced !== null ? _jsxs("div", { className: "space-y-2", children: [_jsx("textarea", { "aria-label": "Simulation JSON", className: "h-60 w-full bg-neutral-900 p-2 font-mono", value: advanced, onChange: (event) => setAdvanced(event.target.value) }), _jsx("button", { type: "button", onClick: () => { try {
+                            update(JSON.parse(advanced));
+                        }
+                        catch (reason) {
+                            setError(String(reason));
+                        } }, children: "Apply simulation data" }), _jsx("button", { type: "button", onClick: () => setAdvanced(null), children: "Close data editor" })] }) : null] });
+}

package/dist/TerrainSculpt.js

@@ -5,18 +5,14 @@ import * as THREE from "three";
 import { createTerrainPaletteSampler, raycastHeightField, } from "@jgengine/core/world/terrain";
 import { beginSurfaceStroke, beginTerraformStroke, editableTerrainFromSnapshot, } from "@jgengine/core/world/terraform";
 import { useGameContext } from "@jgengine/react/provider";
-import { displaceHeightfieldGeometry, normalizeHeightBlend, TerraformBrushCursor, } from "@jgengine/shell/terrain";
+import { displaceHeightfieldGeometry, normalizeHeightBlend, createTerrainPaintColorSampler, TerraformBrushCursor, } from "@jgengine/shell/terrain";
 import { editorPerfMarks } from "./perfMarks.js";
-import { TERRAIN_MATERIAL_COLORS, } from "./uiStore.js";
+import {} from "./uiStore.js";
 import { useStoreSelector } from "./useStoreSelector.js";
 const GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
 const LOW = new THREE.Color("#3f5d34");
 const HIGH = new THREE.Color("#8f9c66");
 const COLOR_SPAN = 24;
-/** Resolves a material layer to its render color (its tint, else its palette surface color). */
-function layerColor(layer) {
-    return layer.tint ?? TERRAIN_MATERIAL_COLORS[layer.surface] ?? "#7c7f86";
-}
 /** The game's `environment({ terrain })` descriptor, when the world it declares carries one — the same descriptor `TerrainGround` samples at runtime via `createTerrainPaletteSampler`. */
 function terrainDescriptorOf(world) {
     return world?.kind === "environment" ? world.terrain : undefined;
@@ -65,28 +61,11 @@ function editFromSettings(settings, center, clickHeight) {
         ...(heightLimit === undefined ? {} : { heightLimit }),
     };
 }
-const BLEND_A = new THREE.Color();
-const BLEND_B = new THREE.Color();
-/** Parsed once — `toneAt` runs per vertex, so hex→Color parsing must not. */
-const SURFACE_COLOR_CACHE = new Map();
-function surfaceColor(hex) {
-    let color = SURFACE_COLOR_CACHE.get(hex);
-    if (color === undefined) {
-        color = new THREE.Color(hex);
-        SURFACE_COLOR_CACHE.set(hex, color);
-    }
-    return color;
-}
 /** World-unit spacing between topographic relief bands drawn on the sculpt preview. */
 const CONTOUR_INTERVAL = 1.5;
-/**
- * Topographic relief baked into a vertex's color so elevation reads from the editor's high camera,
- * where lighting alone leaves gentle hills invisible. Smooth cosine bands every `CONTOUR_INTERVAL`
- * darken slopes toward each band trough (a contour-map look) and higher ground brightens slightly —
- * a `multiply`, so painted grass/dirt/rock keep their hue. Flat ground at a band height (the common
- * unsculpted case at y=0) is left untouched: only varying height shows the bands. `strength` 0 is a
- * no-op.
- */
+const BLEND_A = new THREE.Color();
+const BLEND_B = new THREE.Color();
+/** Multiplicative contour bands preserve painted hue while making elevation readable. */
 function applyRelief(out, height, strength) {
     if (strength <= 0)
         return;
@@ -102,37 +81,9 @@ function applyRelief(out, height, strength) {
  * default — so `materialRegions`/base `colors`/`material` (worn paths, rock outcrops, biome tint)
  * show through in the editor the same way `TerrainGround` renders them at runtime.
  */
-function toneAt(terrain, x, z, height, out, paletteAt, heightRange, layerColors) {
-    const layers = terrain.layers;
-    if (layers.length > 0) {
-        const weights = terrain.weightsAt(x, z);
-        if (weights.length === layers.length) {
-            let total = 0;
-            let r = 0;
-            let g = 0;
-            let b = 0;
-            for (let l = 0; l < layers.length; l += 1) {
-                const w = weights[l] * (layers[l].opacity ?? 1);
-                if (w <= 0)
-                    continue;
-                const color = layerColors[l];
-                r += color.r * w;
-                g += color.g * w;
-                b += color.b * w;
-                total += w;
-            }
-            if (total > 0) {
-                out.setRGB(r / total, g / total, b / total);
-                return;
-            }
-        }
-    }
-    const surface = terrain.surfaceAt(x, z);
-    const painted = surface === null ? undefined : TERRAIN_MATERIAL_COLORS[surface];
-    if (painted !== undefined) {
-        out.copy(surfaceColor(painted));
+function toneAt(x, z, height, out, paletteAt, heightRange, paintColorAt) {
+    if (paintColorAt(x, z, out))
         return;
-    }
     if (paletteAt !== null) {
         const palette = paletteAt(x, z);
         const blend = normalizeHeightBlend(height, heightRange[0], heightRange[1]);
@@ -151,12 +102,12 @@ function toneAt(terrain, x, z, height, out, paletteAt, heightRange, layerColors)
  */
 function displace(geometry, terrain, bounds, region, paletteAt, heightRange, contourStrength) {
     const started = performance.now();
-    const layerColors = terrain.layers.map((layer) => surfaceColor(layerColor(layer)));
+    const paintColorAt = createTerrainPaintColorSampler(terrain);
     displaceHeightfieldGeometry(geometry, terrain.sampleHeight, {
         bounds,
         region,
         color: (x, z, height, out) => {
-            toneAt(terrain, x, z, height, out, paletteAt, heightRange, layerColors);
+            toneAt(x, z, height, out, paletteAt, heightRange, paintColorAt);
             applyRelief(out, height, contourStrength);
         },
     });
@@ -172,6 +123,7 @@ function unionRect(a, b) {
 }
 /** Memoized so cursor-hover state updates in the parent never reconcile the mesh subtree. */
 const SculptMesh = memo(function SculptMesh({ terrain, bounds, segments, revision, pendingRef, paletteAt, heightRange, contourStrength, }) {
+    const invalidate = useThree((state) => state.invalidate);
     const geometry = useMemo(() => {
         const width = Math.max(1, bounds.maxX - bounds.minX);
         const depth = Math.max(1, bounds.maxZ - bounds.minZ);
@@ -188,8 +140,9 @@ const SculptMesh = memo(function SculptMesh({ terrain, bounds, segments, revisio
         pendingRef.current = null;
         const region = pending !== null && pending.kind === "region" ? pending.region : null;
         displace(geometry, terrain, bounds, region, paletteAt, heightRange, contourStrength);
+        invalidate();
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [geometry, terrain, revision, paletteAt, heightRange, contourStrength]);
+    }, [geometry, terrain, revision, paletteAt, heightRange, contourStrength, invalidate]);
     return (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 0.95, metalness: 0, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) }));
 });
 function selectSculptUi(state) {

package/dist/agent/toolBridge.js

@@ -10,6 +10,8 @@ const READ_ONLY_METHODS = new Set([
     "camera_goto",
     "camera_frame",
     "scene_summary",
+    "get_simulation",
+    "set_simulation",
     "export_document",
     "list_assets",
     "perf_report",

package/dist/authoringPlacement.d.ts

@@ -0,0 +1,21 @@
+import type { EditorVec3 } from "@jgengine/core/editor/index";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+import { type TerraformSnapshot } from "@jgengine/core/world/terraform";
+import type { GizmoMode, SnapMode } from "./uiStore.js";
+/** Compose authored sculpt offsets over the same base field as the terrain preview. @internal */
+export declare function placementGround(terrain: TerraformSnapshot | undefined, base: TerrainField | null): TerrainField | null;
+/** Snap XZ and resample the shared ground field; reject a nonfinite surface height. @internal */
+export declare function snapPlacement(point: EditorVec3, mode: SnapMode, gridSize: number, groundHeightAt: (x: number, z: number) => number): EditorVec3 | null;
+/** Distance from a pointer to a projected path segment, including either endpoint. @internal */
+export declare function pathSegmentDistance(pointer: {
+    x: number;
+    y: number;
+}, a: {
+    x: number;
+    y: number;
+}, b: {
+    x: number;
+    y: number;
+}): number;
+/** Group transforms use the translation command for every selected object. @internal */
+export declare function selectionGizmoMode(mode: GizmoMode, kind: string, count: number): GizmoMode;

package/dist/authoringPlacement.js

@@ -0,0 +1,34 @@
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+/** Compose authored sculpt offsets over the same base field as the terrain preview. @internal */
+export function placementGround(terrain, base) {
+    return terrain === undefined ? base : editableTerrainFromSnapshot(terrain, base ?? undefined);
+}
+/** Snap XZ and resample the shared ground field; reject a nonfinite surface height. @internal */
+export function snapPlacement(point, mode, gridSize, groundHeightAt) {
+    if (mode !== "grid" || !Number.isFinite(gridSize) || gridSize <= 0)
+        return point;
+    const x = Math.round(point.x / gridSize) * gridSize;
+    const z = Math.round(point.z / gridSize) * gridSize;
+    if (!Number.isFinite(x) || !Number.isFinite(z))
+        return null;
+    const y = groundHeightAt(x, z);
+    return Number.isFinite(y) ? { x, y, z } : null;
+}
+/** Distance from a pointer to a projected path segment, including either endpoint. @internal */
+export function pathSegmentDistance(pointer, a, b) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const lengthSquared = dx * dx + dy * dy;
+    const t = lengthSquared === 0 ? 0 : Math.max(0, Math.min(1, ((pointer.x - a.x) * dx + (pointer.y - a.y) * dy) / lengthSquared));
+    return Math.hypot(pointer.x - a.x - t * dx, pointer.y - a.y - t * dy);
+}
+/** Group transforms use the translation command for every selected object. @internal */
+export function selectionGizmoMode(mode, kind, count) {
+    if (count > 1)
+        return "translate";
+    if (kind === "marker")
+        return mode === "scale" ? "translate" : mode;
+    if (kind === "volume")
+        return mode === "rotate" ? "translate" : mode;
+    return "translate";
+}

package/dist/handlers/context.d.ts

@@ -16,6 +16,7 @@ export interface HandlerContext {
     api: EditorHostApi;
     session: EditorSession;
     liveSync: DocumentLiveSync;
+    persistAssetUrls?: boolean;
     gameId: string;
     catalogDefinitions: readonly EditorCatalogDefinition[];
     catalogById: ReadonlyMap<string, EditorCatalogDefinition>;

package/dist/handlers/document.d.ts

@@ -1,3 +1,3 @@
 import type { HandlerTable } from "./context.js";
 /** Document, selection, camera, mode, asset placement, and status verbs. */
-export declare const documentHandlers: Pick<HandlerTable, "editor_status" | "set_mode" | "perf_report" | "list_layers" | "list_selection" | "get_marker" | "get_volume" | "set_transform" | "set_volume" | "set_path" | "add_path" | "add_marker" | "set_marker" | "set_note" | "set_meta" | "apply_preset" | "select" | "clear_selection" | "camera_goto" | "camera_frame" | "scene_summary" | "export_document" | "import_document" | "dispatch" | "undo" | "redo" | "list_assets" | "place_asset" | "batch_set_properties" | "assign_material" | "set_object_flags">;
+export declare const documentHandlers: Pick<HandlerTable, "editor_status" | "set_mode" | "perf_report" | "list_layers" | "list_selection" | "get_marker" | "get_volume" | "set_transform" | "set_volume" | "set_path" | "add_path" | "add_marker" | "set_marker" | "set_note" | "set_meta" | "apply_preset" | "select" | "clear_selection" | "camera_goto" | "camera_frame" | "scene_summary" | "get_simulation" | "set_simulation" | "export_document" | "import_document" | "dispatch" | "undo" | "redo" | "list_assets" | "place_asset" | "batch_set_properties" | "list_material_assets" | "list_material_slots" | "upsert_material_asset" | "remove_material_asset" | "assign_material_asset" | "clear_material_assets" | "assign_material" | "set_object_flags">;

package/dist/handlers/document.js

@@ -1,3 +1,4 @@
+import { parseEditorMaterialAsset } from "@jgengine/core/editor/materialAuthoring";
 import { editorDocumentBounds, listEditorKinds, summarizeEditorSession, } from "@jgengine/core/editor/index";
 import { resolvePlaceAsset, toEditorMarker } from "@jgengine/core/world/placeAsset";
 import { findSchemaPreset, getSceneKind, validateParams } from "@jgengine/core/scene/sceneKinds";
@@ -314,6 +315,11 @@ export const documentHandlers = {
         ctx.api.setFocusTarget(target);
         return { ok: true, result: { target, bounds } };
     },
+    get_simulation: (ctx) => ({ ok: true, result: { simulation: structuredClone(ctx.session.getState().document.simulation ?? {}) } }),
+    set_simulation: (ctx, request) => {
+        ctx.session.dispatch({ type: "setSimulation", simulation: request.simulation === null ? undefined : request.simulation });
+        return { ok: true, result: { simulation: structuredClone(ctx.session.getState().document.simulation ?? {}) } };
+    },
     scene_summary: (ctx) => ({
         ok: true,
         result: {
@@ -361,7 +367,7 @@ export const documentHandlers = {
             kind: request.kind,
             knownKind: asset?.kind,
             knownLabel: asset?.label,
-            knownUrl: asset?.url,
+            knownUrl: ctx.persistAssetUrls === false ? undefined : asset?.url,
         });
         const placedMarker = toEditorMarker(placed);
         // URL-backed catalog models need a first-class catalogId so AuthoredObjects places the mesh;
@@ -411,6 +417,28 @@ export const documentHandlers = {
         });
         return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
     },
+    list_material_assets: (ctx) => ({ ok: true, result: { assets: ctx.session.getState().document.materialAssets ?? [], assignments: ctx.session.getState().document.markers.filter((marker) => marker.meta?.materialAssignments !== undefined).map((marker) => ({ id: marker.id, assignments: marker.meta.materialAssignments })) } }),
+    list_material_slots: (ctx, request) => {
+        const inventory = ctx.api.getMaterialSlots(request.id);
+        return inventory.status === "ready" ? { ok: true, result: inventory } : { ok: false, result: inventory, error: inventory.status === "loading" ? "Material slots are still loading." : inventory.reason };
+    },
+    upsert_material_asset: (ctx, request) => {
+        const asset = parseEditorMaterialAsset(request.asset);
+        ctx.session.dispatch({ type: "upsertMaterialAsset", asset }, request.coalesce === undefined ? undefined : { coalesce: request.coalesce });
+        return { ok: true, result: { asset } };
+    },
+    remove_material_asset: (ctx, request) => {
+        const result = ctx.session.transaction([{ type: "removeMaterialAsset", id: request.id }]);
+        return result.ok ? { ok: true, result: summarizeEditorSession(result.state) } : { ok: false, error: result.error };
+    },
+    assign_material_asset: (ctx, request) => {
+        const result = ctx.session.transaction([{ type: "assignMaterialAsset", ids: request.ids, materialId: request.materialId, selector: request.selector }]);
+        return result.ok ? { ok: true, result: summarizeEditorSession(result.state) } : { ok: false, error: result.error };
+    },
+    clear_material_assets: (ctx, request) => {
+        const result = ctx.session.transaction([{ type: "clearMaterialAssets", ids: request.ids }]);
+        return result.ok ? { ok: true, result: summarizeEditorSession(result.state) } : { ok: false, error: result.error };
+    },
     assign_material: (ctx, request) => {
         if (!documentHasAnyId(ctx.session.getState().document, request.ids)) {
             return { ok: false, error: "assign_material matched no objects" };

package/dist/handlers/hierarchy.d.ts

@@ -1,3 +1,3 @@
 import type { HandlerTable } from "./context.js";
 /** Parent/child hierarchy and prefab library verbs. */
-export declare const hierarchyHandlers: Pick<HandlerTable, "set_parent" | "hierarchy" | "list_prefabs" | "create_prefab" | "insert_prefab" | "detach_prefab_instance" | "delete_prefab">;
+export declare const hierarchyHandlers: Pick<HandlerTable, "set_parent" | "hierarchy" | "list_prefabs" | "create_prefab" | "insert_prefab" | "detach_prefab_instance" | "delete_prefab" | "set_prefab_static_bake">;

package/dist/handlers/hierarchy.js

@@ -45,6 +45,10 @@ export const hierarchyHandlers = {
         ctx.session.dispatch({ type: "detachPrefabInstance", instanceId: request.instanceId });
         return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
     },
+    set_prefab_static_bake: (ctx, request) => {
+        const result = ctx.session.transaction([{ type: "setPrefabStaticBake", prefabId: request.prefabId, bake: request.bake }]);
+        return result.ok ? { ok: true, result: findEditorPrefab(ctx.session.getState().document, request.prefabId) } : { ok: false, error: result.error };
+    },
     delete_prefab: (ctx, request) => {
         if (findEditorPrefab(ctx.session.getState().document, request.prefabId) === undefined) {
             return { ok: false, error: `prefab not found: ${request.prefabId}` };

package/dist/handlers/runtime.js

@@ -11,8 +11,8 @@ export const runtimeHandlers = {
         if (patch.type !== "snapshot" && patch.type !== "commands") {
             return { ok: false, error: `unknown document patch type: ${String(patch.type)} (snapshot | commands)` };
         }
-        if (typeof patch.baseRevision !== "number") {
-            return { ok: false, error: "push_document_patch requires a numeric baseRevision" };
+        if (!Number.isSafeInteger(patch.baseRevision) || patch.baseRevision < 0) {
+            return { ok: false, error: "push_document_patch requires a nonnegative safe-integer baseRevision" };
         }
         if (!force && patch.baseRevision !== ctx.liveSync.getRevision()) {
             return { ok: false, error: `baseRevision mismatch: patch=${patch.baseRevision} current=${ctx.liveSync.getRevision()}` };
@@ -32,13 +32,10 @@ export const runtimeHandlers = {
             return { ok: false, error: "commands patch requires a commands array" };
         if (patch.commands.length === 0)
             return { ok: false, error: "commands patch is empty" };
-        for (const command of patch.commands) {
-            const { applied } = ctx.dispatchGuarded(command);
-            if (!applied && command.type !== "select" && command.type !== "clearSelection") {
-                return { ok: false, error: `${command.type} rejected while applying patch` };
-            }
-        }
-        return { ok: true, result: { revision: ctx.liveSync.getRevision(), ...summarizeEditorSession(ctx.session.getState()) } };
+        const transaction = ctx.session.transaction(patch.commands);
+        if (!transaction.ok)
+            return { ok: false, error: transaction.error, result: { commandIndex: transaction.commandIndex, revision: ctx.liveSync.getRevision() } };
+        return { ok: true, result: { revision: ctx.liveSync.getRevision(), changed: transaction.changed, ...summarizeEditorSession(transaction.state) } };
     },
     pull_document_patches: (ctx, request) => ({
         ok: true,
@@ -60,14 +57,20 @@ export const runtimeHandlers = {
         });
         return { ok: true, result: delta };
     },
-    pull_runtime_deltas: (ctx, request) => ({
-        ok: true,
-        result: {
-            seq: ctx.liveSync.getRuntimeState().seq,
-            deltas: ctx.liveSync.pullRuntimeDeltas(request.sinceSeq ?? 0),
-            ...(request.includeSnapshot === true ? { snapshot: ctx.liveSync.getRuntimeState() } : {}),
-        },
-    }),
+    pull_runtime_deltas: (ctx, request) => {
+        const sinceSeq = request.sinceSeq ?? 0;
+        const snapshot = ctx.liveSync.getRuntimeState();
+        const deltas = ctx.liveSync.pullRuntimeDeltas(sinceSeq);
+        const historyGap = deltas.length > 0 && deltas[0].seq > sinceSeq + 1;
+        return {
+            ok: true,
+            result: {
+                seq: snapshot.seq,
+                deltas: historyGap ? [] : deltas,
+                ...(request.includeSnapshot === true || historyGap ? { snapshot } : {}),
+            },
+        };
+    },
     runtime_snapshot: (ctx) => ({ ok: true, result: ctx.liveSync.getRuntimeState() }),
     runtime_summary: (ctx) => ({
         ok: true,