@jgengine/core 0.10.0 → 0.12.0

package/dist/editor/commands.d.ts

@@ -1,4 +1,8 @@
-import type { EditorDocument, EditorMarker, EditorVec3, EditorVolume } from "./types.js";
+import { type SurfaceDelta, type TerraformDelta, type TerrainMaterialLayer, type WeightDelta } from "../world/terraform.js";
+import type { EditorUiDocument, EditorUiPanelLayout } from "../ui/hudDocument.js";
+import type { EditorGridCellEdit, EditorGridLayer } from "./grid.js";
+import type { ParamSchema } from "../scene/sceneKinds.js";
+import type { EditorCatalogEntry, EditorDocument, EditorEnvironment, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorTerrain, EditorVec3, EditorVolume } from "./types.js";
 /** A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session. */
 export type EditorCommand = {
     type: "select";
@@ -10,19 +14,85 @@ export type EditorCommand = {
     id: string;
     position?: EditorVec3;
     rotationY?: number;
+} | {
+    type: "translate";
+    ids: readonly string[];
+    delta: EditorVec3;
+} | {
+    type: "setParent";
+    ids: readonly string[];
+    parentId: string | null;
 } | {
     type: "addMarker";
     marker: EditorMarker;
 } | {
-    type: "remove";
+    type: "addVolume";
+    volume: EditorVolume;
+} | {
+    type: "addPath";
+    path: EditorPath;
+} | {
+    type: "addNote";
+    note: EditorNote;
+} | {
+    type: "setMarker";
     id: string;
+    patch: Partial<Omit<EditorMarker, "id">>;
 } | {
     type: "setVolume";
     id: string;
     patch: Partial<Omit<EditorVolume, "id">>;
 } | {
-    type: "addVolume";
-    volume: EditorVolume;
+    type: "setPath";
+    id: string;
+    patch: Partial<Omit<EditorPath, "id">>;
+} | {
+    type: "setNote";
+    id: string;
+    patch: Partial<Omit<EditorNote, "id">>;
+} | {
+    type: "setCatalogEntry";
+    catalogId: string;
+    entryId: string;
+    patch: {
+        label?: string;
+        meta?: Record<string, unknown>;
+    };
+} | {
+    type: "addCatalogEntry";
+    catalogId: string;
+    entry: EditorCatalogEntry;
+} | {
+    type: "removeCatalogEntry";
+    catalogId: string;
+    entryId: string;
+} | {
+    type: "addCatalog";
+    id: string;
+    label?: string;
+    schema?: ParamSchema;
+} | {
+    type: "removeCatalog";
+    id: string;
+} | {
+    type: "setCatalogSchema";
+    id: string;
+    schema: ParamSchema;
+    label?: string;
+} | {
+    type: "remove";
+    id: string;
+} | {
+    type: "removeMany";
+    ids: readonly string[];
+} | {
+    type: "duplicate";
+    ids: readonly string[];
+    offset?: EditorVec3;
+} | {
+    type: "addFragment";
+    fragment: EditorDocument;
+    offset?: EditorVec3;
 } | {
     type: "importDocument";
     document: EditorDocument;
@@ -32,11 +102,165 @@ export type EditorCommand = {
 } | {
     type: "replaceDocument";
     document: EditorDocument;
+} | {
+    type: "setTerrain";
+    terrain: EditorTerrain;
+} | {
+    type: "sculptTerrain";
+    delta: TerraformDelta;
+} | {
+    type: "paintTerrain";
+    delta: SurfaceDelta;
+} | {
+    type: "setTerrainLayers";
+    layers: readonly TerrainMaterialLayer[];
+} | {
+    type: "blendTerrain";
+    delta: WeightDelta;
+} | {
+    type: "clearTerrain";
+} | {
+    type: "setMinimapBake";
+    minimap: EditorMinimapBake;
+}
+/**
+ * Replace the scene-document environment/lighting bag. Pass `undefined` to clear authored sky/fog
+ * so world.ts fallbacks apply again. The lighting workspace writes the full merged bag so
+ * undo restores the previous snapshot as one step (use `coalesce` while scrubbing sliders).
+ */
+ | {
+    type: "setEnvironment";
+    environment: EditorEnvironment | undefined;
+} | {
+    type: "convertScatterToObjects";
+    pathId: string;
+    markers: readonly EditorMarker[];
+} | {
+    type: "createPrefab";
+    id: string;
+    name: string;
+    ids: readonly string[];
+} | {
+    type: "insertPrefab";
+    prefabId: string;
+    at: EditorVec3;
+    instanceId?: string;
+} | {
+    type: "detachPrefabInstance";
+    instanceId: string;
+} | {
+    type: "deletePrefab";
+    prefabId: string;
+} | {
+    type: "createCollection";
+    id: string;
+    name: string;
+    memberIds?: readonly string[];
+} | {
+    type: "renameCollection";
+    id: string;
+    name: string;
+} | {
+    type: "deleteCollection";
+    id: string;
+} | {
+    type: "setCollectionMembers";
+    id: string;
+    memberIds: readonly string[];
+} | {
+    type: "addToCollection";
+    id: string;
+    ids: readonly string[];
+} | {
+    type: "removeFromCollection";
+    id: string;
+    ids: readonly string[];
+} | {
+    type: "setCollectionFlags";
+    id: string;
+    patch: {
+        color?: string;
+        locked?: boolean;
+        visible?: boolean;
+    };
+} | {
+    /**
+     * Per-object lock/visibility flags on placeables. `locked: false` / `hidden: false` clear the
+     * field so the document stays compact; collection locks are unchanged.
+     */
+    type: "setObjectFlags";
+    ids: readonly string[];
+    patch: {
+        locked?: boolean;
+        hidden?: boolean;
+    };
+} | {
+    type: "selectCollection";
+    id: string;
+} | {
+    type: "batchSetProperties";
+    ids: readonly string[];
+    patch: {
+        color?: string;
+        label?: string;
+        meta?: Record<string, unknown>;
+    };
+} | {
+    type: "assignMaterial";
+    ids: readonly string[];
+    materialId: string;
+} | {
+    type: "addGridLayer";
+    layer: EditorGridLayer;
+} | {
+    type: "removeGridLayer";
+    id: string;
+} | {
+    type: "setGridLayer";
+    id: string;
+    patch: Partial<Omit<EditorGridLayer, "id" | "cells">>;
+} | {
+    type: "paintGridCells";
+    id: string;
+    cells: readonly EditorGridCellEdit[];
+} | {
+    type: "fillGridRect";
+    id: string;
+    col0: number;
+    row0: number;
+    col1: number;
+    row1: number;
+    value: string;
+} | {
+    type: "floodFillGrid";
+    id: string;
+    col: number;
+    row: number;
+    value: string;
+} | {
+    type: "resizeGridLayer";
+    id: string;
+    cols: number;
+    rows: number;
+} | {
+    type: "setUiPanel";
+    id: string;
+    patch: Partial<EditorUiPanelLayout>;
+} | {
+    type: "removeUiPanel";
+    id: string;
+} | {
+    type: "setUi";
+    ui: EditorUiDocument | undefined;
 } | {
     type: "undo";
 } | {
     type: "redo";
 };
+/** Per-dispatch options; `coalesce` merges consecutive same-key edits into one undo step. */
+export interface EditorDispatchOptions {
+    coalesce?: string;
+}
 /** The document plus current selection at a point in editor history. */
 export interface EditorSessionState {
     document: EditorDocument;
@@ -46,14 +270,18 @@ export interface EditorSessionState {
 export interface EditorSession {
     getState(): EditorSessionState;
     subscribe(listener: (state: EditorSessionState) => void): () => void;
-    dispatch(command: EditorCommand): EditorSessionState;
+    dispatch(command: EditorCommand, options?: EditorDispatchOptions): EditorSessionState;
     exportJson(pretty?: boolean): string;
     canUndo(): boolean;
     canRedo(): boolean;
 }
-/** Creates an editor session with undo/redo history seeded from an initial document. */
+/** Creates an editor session with undo/redo history seeded from an initial document.
+ * @internal
+ */
 export declare function createEditorSession(initial: EditorDocument, historyLimit?: number): EditorSession;
-/** Compact snapshot of a session state — counts, selection, and the selected object. */
+/** Compact snapshot of a session state — counts, selection, and the selected object.
+ * @internal
+ */
 export declare function summarizeEditorSession(state: EditorSessionState): {
     markers: number;
     volumes: number;

package/dist/editor/commands.js

@@ -1,120 +1,30 @@
-import { cloneEditorDocument, findEditorMarker, findEditorVolume, importEditorDocumentJson, } from "./document.js";
+import { applyDeltaToSnapshot, applySurfaceDeltaToSnapshot, applyWeightDeltaToSnapshot, revertDeltaFromSnapshot, revertSurfaceDeltaFromSnapshot, revertWeightDeltaFromSnapshot, } from "../world/terraform.js";
+import { cloneEditorDocument, findEditorMarker, findEditorVolume, } from "./document.js";
+import { applyMutating, isStructural } from "./commandApply.js";
 function snapshotState(state) {
     return {
         document: cloneEditorDocument(state.document),
         selection: [...state.selection],
     };
 }
-function removeById(doc, id) {
-    return {
-        version: 1,
-        markers: doc.markers.filter((marker) => marker.id !== id),
-        volumes: doc.volumes.filter((volume) => volume.id !== id),
-        paths: doc.paths.filter((path) => path.id !== id),
-        annotations: doc.annotations.filter((note) => note.id !== id),
-    };
-}
-function applyMutating(state, command) {
-    switch (command.type) {
-        case "select":
-            return { ...state, selection: [...command.ids] };
-        case "clearSelection":
-            return { ...state, selection: [] };
-        case "setTransform": {
-            const markers = state.document.markers.map((marker) => {
-                if (marker.id !== command.id)
-                    return marker;
-                return {
-                    ...marker,
-                    position: command.position === undefined ? marker.position : { ...command.position },
-                    ...(command.rotationY === undefined ? {} : { rotationY: command.rotationY }),
-                };
-            });
-            const volumes = state.document.volumes.map((volume) => {
-                if (volume.id !== command.id)
-                    return volume;
-                if (command.position === undefined)
-                    return volume;
-                return { ...volume, center: { ...command.position } };
-            });
-            const annotations = state.document.annotations.map((note) => {
-                if (note.id !== command.id)
-                    return note;
-                if (command.position === undefined)
-                    return note;
-                return { ...note, position: { ...command.position } };
-            });
-            return {
-                ...state,
-                document: { ...state.document, markers, volumes, annotations },
-            };
-        }
-        case "addMarker":
-            return {
-                ...state,
-                document: {
-                    ...state.document,
-                    markers: [...state.document.markers.filter((m) => m.id !== command.marker.id), command.marker],
-                },
-                selection: [command.marker.id],
-            };
-        case "addVolume":
-            return {
-                ...state,
-                document: {
-                    ...state.document,
-                    volumes: [...state.document.volumes.filter((v) => v.id !== command.volume.id), command.volume],
-                },
-                selection: [command.volume.id],
-            };
-        case "setVolume": {
-            const volumes = state.document.volumes.map((volume) => {
-                if (volume.id !== command.id)
-                    return volume;
-                return {
-                    ...volume,
-                    ...command.patch,
-                    center: command.patch.center === undefined ? volume.center : { ...command.patch.center },
-                    halfExtents: command.patch.halfExtents === undefined
-                        ? volume.halfExtents
-                        : { ...command.patch.halfExtents },
-                    meta: command.patch.meta === undefined ? volume.meta : { ...command.patch.meta },
-                };
-            });
-            return { ...state, document: { ...state.document, volumes } };
-        }
-        case "remove":
-            return {
-                document: removeById(state.document, command.id),
-                selection: state.selection.filter((id) => id !== command.id),
-            };
-        case "importDocument":
-        case "replaceDocument":
-            return {
-                document: cloneEditorDocument(command.document),
-                selection: [],
-            };
-        case "importJson":
-            return {
-                document: importEditorDocumentJson(command.json),
-                selection: [],
-            };
-        case "undo":
-        case "redo":
-            return null;
-    }
-}
-function isStructural(command) {
-    return (command.type === "setTransform" ||
-        command.type === "addMarker" ||
-        command.type === "addVolume" ||
-        command.type === "setVolume" ||
-        command.type === "remove" ||
-        command.type === "importDocument" ||
-        command.type === "importJson" ||
-        command.type === "replaceDocument");
-}
-/** Creates an editor session with undo/redo history seeded from an initial document. */
+/**
+ * Per-brush apply/revert pair over the heightfield snapshot. One registry drives every terrain
+ * command, push, and undo/redo path, so the three brushes never fork into parallel code.
+ */
+const terrainStrokes = {
+    sculpt: { apply: applyDeltaToSnapshot, revert: revertDeltaFromSnapshot },
+    paint: { apply: applySurfaceDeltaToSnapshot, revert: revertSurfaceDeltaFromSnapshot },
+    blend: { apply: applyWeightDeltaToSnapshot, revert: revertWeightDeltaFromSnapshot },
+};
+/** Maps a terrain-brush command type to its stroke kind. */
+const terrainStrokeKind = {
+    sculptTerrain: "sculpt",
+    paintTerrain: "paint",
+    blendTerrain: "blend",
+};
+/** Creates an editor session with undo/redo history seeded from an initial document.
+ * @internal
+ */
 export function createEditorSession(initial, historyLimit = 100) {
     let state = {
         document: cloneEditorDocument(initial),
@@ -122,11 +32,27 @@ export function createEditorSession(initial, historyLimit = 100) {
     };
     const past = [];
     const future = [];
+    let lastCoalesce = null;
     const listeners = new Set();
     const emit = () => {
         for (const listener of listeners)
             listener(state);
     };
+    const applyStroke = (entry, direction, selection) => {
+        const terrain = state.document.terrain;
+        if (terrain === undefined)
+            return state;
+        const next = terrainStrokes[entry.kind][direction](terrain, entry.delta);
+        return { document: { ...state.document, terrain: next }, selection };
+    };
+    const pushTerrainStroke = (entry) => {
+        past.push(entry);
+        if (past.length > historyLimit)
+            past.shift();
+        future.length = 0;
+        lastCoalesce = null;
+        state = applyStroke(entry, "apply", entry.selection);
+    };
     return {
         getState: () => state,
         subscribe(listener) {
@@ -137,22 +63,47 @@ export function createEditorSession(initial, historyLimit = 100) {
         },
         canUndo: () => past.length > 0,
         canRedo: () => future.length > 0,
-        dispatch(command) {
+        dispatch(command, options) {
             if (command.type === "undo") {
-                const previous = past.pop();
-                if (previous === undefined)
+                const entry = past.pop();
+                if (entry === undefined)
                     return state;
-                future.push(snapshotState(state));
-                state = previous;
+                if (entry.kind === "snapshot") {
+                    future.push({ kind: "snapshot", state: snapshotState(state) });
+                    state = entry.state;
+                }
+                else {
+                    future.push({ ...entry, selection: [...state.selection] });
+                    state = applyStroke(entry, "revert", entry.selection);
+                }
+                lastCoalesce = null;
                 emit();
                 return state;
             }
             if (command.type === "redo") {
-                const next = future.pop();
-                if (next === undefined)
+                const entry = future.pop();
+                if (entry === undefined)
+                    return state;
+                if (entry.kind === "snapshot") {
+                    past.push({ kind: "snapshot", state: snapshotState(state) });
+                    state = entry.state;
+                }
+                else {
+                    past.push({ ...entry, selection: [...state.selection] });
+                    state = applyStroke(entry, "apply", entry.selection);
+                }
+                lastCoalesce = null;
+                emit();
+                return state;
+            }
+            if (command.type === "sculptTerrain" || command.type === "paintTerrain" || command.type === "blendTerrain") {
+                if (state.document.terrain === undefined || command.delta.indices.length === 0)
                     return state;
-                past.push(snapshotState(state));
-                state = next;
+                pushTerrainStroke({
+                    kind: terrainStrokeKind[command.type],
+                    delta: command.delta,
+                    selection: [...state.selection],
+                });
                 emit();
                 return state;
             }
@@ -160,10 +111,15 @@ export function createEditorSession(initial, historyLimit = 100) {
             if (next === null)
                 return state;
             if (isStructural(command)) {
-                past.push(snapshotState(state));
-                if (past.length > historyLimit)
-                    past.shift();
+                const coalesce = options?.coalesce;
+                const merge = coalesce !== undefined && coalesce === lastCoalesce && past.length > 0;
+                if (!merge) {
+                    past.push({ kind: "snapshot", state: snapshotState(state) });
+                    if (past.length > historyLimit)
+                        past.shift();
+                }
                 future.length = 0;
+                lastCoalesce = coalesce ?? null;
             }
             state = next;
             emit();
@@ -174,7 +130,9 @@ export function createEditorSession(initial, historyLimit = 100) {
         },
     };
 }
-/** Compact snapshot of a session state — counts, selection, and the selected object. */
+/** Compact snapshot of a session state — counts, selection, and the selected object.
+ * @internal
+ */
 export function summarizeEditorSession(state) {
     const selectedId = state.selection[0];
     return {

package/dist/editor/directives.d.ts

@@ -0,0 +1,94 @@
+import type { Aabb, Vec2 } from "../world/geometry.js";
+import type { EditorDirective, EditorDirectiveKind, EditorDocument, EditorPopulationDirective, EditorScatterDirective } from "./types.js";
+/**
+ * The deterministic materializer for scene {@link EditorDirective}s — the bake side of the
+ * bake/patch seam in #985. A directive is one authored line ("scatter rocks across the north
+ * ridge"); this expands it into many placements with **stable per-instance ids** (`<directiveId>#
+ * <index>`) so a sparse overlay can hand-tweak or delete individual instances by id without every
+ * re-materialize orphaning those edits. Fully deterministic: same directive + seed + region ⇒ the
+ * same field, every time (safe for verify/CI). Built on the existing `scatter` primitive.
+ */
+/** One materialized placement from a directive — grounded XZ, deterministic scale/yaw, stable id. */
+export interface MaterializedInstance {
+    /** Stable id `<directiveId>#<index>` — the key an overlay patches or deletes. */
+    id: string;
+    /** The directive that minted this instance. */
+    directiveId: string;
+    kind: EditorDirectiveKind;
+    /** What to place: a `scatter` directive's catalog asset, or a `population` directive's species id. */
+    asset: string;
+    x: number;
+    z: number;
+    /** Vertical offset in meters (0 unless an overlay sets it); grounding on terrain stays the caller's job. */
+    y: number;
+    rotationY: number;
+    scale: number;
+}
+/** A resolved directive footprint: the XZ bounds to scatter within, plus an optional clip polygon. */
+export interface DirectiveFootprint {
+    area: Aabb;
+    polygon?: Vec2[];
+}
+/**
+ * Resolves the footprint a directive fills: an explicit `area`, else the footprint of the named
+ * `region` — a scatter/closed path (as a clip polygon) or a volume (its XZ AABB). Null when neither
+ * is present or the region id does not resolve.
+ * @capability world-directives resolve a directive's region footprint from the scene document
+ */
+export declare function resolveDirectiveFootprint(doc: EditorDocument, directive: EditorDirective): DirectiveFootprint | null;
+/**
+ * Materializes a scatter directive into deterministic catalog-prop placements across its footprint,
+ * clipped to the region polygon when one is present. Per-instance scale and yaw derive from the
+ * directive id + seed + point index, so ids are stable across re-materializes.
+ * @capability world-directives materialize a scatter directive into placements
+ */
+export declare function materializeScatterDirective(directive: EditorScatterDirective, footprint: DirectiveFootprint): MaterializedInstance[];
+/**
+ * Materializes a population directive into deterministic mob spawn placements: at most `cap` of each
+ * weighted species, distributed across the footprint. Each placement carries a stable id and its
+ * species id in `asset`, ready to feed `ctx.scene.entity.spawn` / `ai/populationDirector`.
+ * @capability world-directives materialize a population directive into spawns
+ */
+export declare function materializePopulationDirective(directive: EditorPopulationDirective, footprint: DirectiveFootprint): MaterializedInstance[];
+/**
+ * Materializes one directive against a document, resolving its footprint first. Returns an empty
+ * list when the region does not resolve.
+ * @capability world-directives materialize one scene directive into instances
+ */
+export declare function materializeDirective(doc: EditorDocument, directive: EditorDirective): MaterializedInstance[];
+/** A per-instance hand-tweak over a materialized directive, keyed by the minted instance id. */
+export interface DirectiveInstancePatch {
+    /** Override the placement's XZ position. */
+    position?: {
+        x: number;
+        z: number;
+    };
+    /** Override the vertical offset. */
+    y?: number;
+    scale?: number;
+    rotationY?: number;
+    /** Remove this instance from the materialized set. */
+    deleted?: boolean;
+}
+/**
+ * A sparse overlay over one directive's materialized instances — the "nudge *that one* rock" answer.
+ * Hand-edits are keyed by the stable instance id the materializer mints, so they survive re-bakes.
+ */
+export interface EditorDirectiveOverlay {
+    /** The directive id whose instances this overlay patches. */
+    over: string;
+    patches: Record<string, DirectiveInstancePatch>;
+}
+/**
+ * Applies a directive overlay to its materialized instances: patched fields override, `deleted`
+ * drops the instance. Instances with no patch pass through untouched.
+ * @capability world-directives apply a sparse overlay over materialized directive instances
+ */
+export declare function applyDirectiveOverlay(instances: readonly MaterializedInstance[], overlay: EditorDirectiveOverlay): MaterializedInstance[];
+/**
+ * Materializes every directive on a document into one flat instance list, applying each directive's
+ * overlay (matched by `over` === directive id) as it goes. The bulk-content counterpart to
+ * `resolveAuthoredObjects` / `resolveScatter`: games and headless tests read the same list.
+ * @capability world-directives materialize all scene directives with their overlays
+ */
+export declare function materializeDirectives(doc: EditorDocument, overlays?: readonly EditorDirectiveOverlay[]): MaterializedInstance[];