@jgengine/core 0.10.0 → 0.12.0

package/dist/editor/directives.js

@@ -0,0 +1,206 @@
+import { scatter } from "../world/scatter.js";
+import { pointInPolygon, polygonBounds } from "../world/scatterRegion.js";
+function hash(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) / 4294967296;
+}
+/**
+ * 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 function resolveDirectiveFootprint(doc, directive) {
+    if (directive.area !== undefined) {
+        const { min, max } = directive.area;
+        return { area: { minX: min[0], minZ: min[1], maxX: max[0], maxZ: max[1] } };
+    }
+    if (directive.region === undefined)
+        return null;
+    const path = doc.paths.find((p) => p.id === directive.region);
+    if (path !== undefined && path.points.length >= 3) {
+        const polygon = path.points.map((point) => [point.x, point.z]);
+        const area = polygonBounds(polygon);
+        if (area === null)
+            return null;
+        return { area, polygon };
+    }
+    const volume = doc.volumes.find((v) => v.id === directive.region);
+    if (volume !== undefined) {
+        const half = volume.halfExtents !== undefined
+            ? { x: volume.halfExtents.x, z: volume.halfExtents.z }
+            : volume.radius !== undefined
+                ? { x: volume.radius, z: volume.radius }
+                : null;
+        if (half === null)
+            return null;
+        return {
+            area: {
+                minX: volume.center.x - half.x,
+                minZ: volume.center.z - half.z,
+                maxX: volume.center.x + half.x,
+                maxZ: volume.center.z + half.z,
+            },
+        };
+    }
+    return null;
+}
+function scatterSeed(directive) {
+    return `${directive.id}:${directive.seed ?? directive.id}`;
+}
+/**
+ * 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 function materializeScatterDirective(directive, footprint) {
+    if (directive.density <= 0)
+        return [];
+    const seed = scatterSeed(directive);
+    const points = scatter({
+        area: footprint.area,
+        density: directive.density,
+        minDistance: directive.minSpacing ?? 0,
+        jitter: directive.jitter ?? 1,
+        seed,
+    });
+    const minScale = directive.minScale ?? 1;
+    const maxScale = directive.maxScale ?? 1;
+    const minYaw = directive.minYaw ?? 0;
+    const maxYaw = directive.maxYaw ?? Math.PI * 2;
+    const out = [];
+    for (const point of points) {
+        if (footprint.polygon !== undefined && !pointInPolygon([point.x, point.z], footprint.polygon))
+            continue;
+        const scaleRoll = hash(`${seed}:scale:${point.index}`);
+        const yawRoll = hash(`${seed}:yaw:${point.index}`);
+        out.push({
+            id: `${directive.id}#${point.index}`,
+            directiveId: directive.id,
+            kind: "scatter",
+            asset: directive.asset,
+            x: point.x,
+            z: point.z,
+            y: 0,
+            rotationY: minYaw + (maxYaw - minYaw) * yawRoll,
+            scale: minScale + (maxScale - minScale) * scaleRoll,
+        });
+    }
+    return out;
+}
+function pickSpecies(available, roll) {
+    const total = available.reduce((sum, s) => sum + Math.max(0, s.weight ?? 1), 0);
+    if (total <= 0)
+        return available[0];
+    let acc = roll * total;
+    for (const species of available) {
+        acc -= Math.max(0, species.weight ?? 1);
+        if (acc <= 0)
+            return species;
+    }
+    return available[available.length - 1];
+}
+/**
+ * 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 function materializePopulationDirective(directive, footprint) {
+    const remaining = new Map();
+    for (const species of directive.species) {
+        remaining.set(species.id, Math.max(0, (remaining.get(species.id) ?? 0) + species.cap));
+    }
+    const total = [...remaining.values()].reduce((sum, cap) => sum + cap, 0);
+    if (total <= 0)
+        return [];
+    const seed = scatterSeed(directive);
+    const points = scatter({ area: footprint.area, count: total, minDistance: 0, seed });
+    const out = [];
+    for (const point of points) {
+        if (footprint.polygon !== undefined && !pointInPolygon([point.x, point.z], footprint.polygon))
+            continue;
+        const available = directive.species.filter((s) => (remaining.get(s.id) ?? 0) > 0);
+        if (available.length === 0)
+            break;
+        const picked = pickSpecies(available, hash(`${seed}:species:${point.index}`));
+        remaining.set(picked.id, (remaining.get(picked.id) ?? 0) - 1);
+        out.push({
+            id: `${directive.id}#${point.index}`,
+            directiveId: directive.id,
+            kind: "population",
+            asset: picked.id,
+            x: point.x,
+            z: point.z,
+            y: 0,
+            rotationY: hash(`${seed}:yaw:${point.index}`) * Math.PI * 2,
+            scale: 1,
+        });
+    }
+    return out;
+}
+/**
+ * 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 function materializeDirective(doc, directive) {
+    const footprint = resolveDirectiveFootprint(doc, directive);
+    if (footprint === null)
+        return [];
+    return directive.kind === "scatter"
+        ? materializeScatterDirective(directive, footprint)
+        : materializePopulationDirective(directive, footprint);
+}
+/**
+ * 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 function applyDirectiveOverlay(instances, overlay) {
+    const out = [];
+    for (const instance of instances) {
+        const patch = overlay.patches[instance.id];
+        if (patch === undefined) {
+            out.push(instance);
+            continue;
+        }
+        if (patch.deleted === true)
+            continue;
+        out.push({
+            ...instance,
+            x: patch.position?.x ?? instance.x,
+            z: patch.position?.z ?? instance.z,
+            y: patch.y ?? instance.y,
+            scale: patch.scale ?? instance.scale,
+            rotationY: patch.rotationY ?? instance.rotationY,
+        });
+    }
+    return out;
+}
+/**
+ * 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 function materializeDirectives(doc, overlays) {
+    const directives = doc.directives ?? [];
+    if (directives.length === 0)
+        return [];
+    const overlayByDirective = new Map((overlays ?? []).map((overlay) => [overlay.over, overlay]));
+    const out = [];
+    for (const directive of directives) {
+        let instances = materializeDirective(doc, directive);
+        const overlay = overlayByDirective.get(directive.id);
+        if (overlay !== undefined)
+            instances = applyDirectiveOverlay(instances, overlay);
+        out.push(...instances);
+    }
+    return out;
+}

package/dist/editor/document.d.ts

@@ -1,31 +1,212 @@
-import type { EditorDocument, EditorLayersInput, EditorMarker, EditorNote, EditorPath, EditorVolume } from "./types.js";
-/** Builds a fresh, empty editor document to start authoring a scene from scratch. */
+import { type EditorGridLayer } from "./grid.js";
+import type { EditorCatalogData, EditorCatalogDefinition, EditorCatalogEntry, EditorCollection, EditorDirective, EditorDocument, EditorEnvironment, EditorFragmentContent, EditorLayersInput, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorPrefab, EditorTerrain, EditorVolume } from "./types.js";
+/** Spread-ready non-placeable fields preserved across document rebuilds. @internal */
+export declare function editorDocumentExtras(doc: EditorDocument): {
+    prefabs: EditorPrefab[];
+    collections: EditorCollection[];
+    catalogs: EditorCatalogData[];
+    grids?: EditorGridLayer[];
+    terrain?: EditorTerrain;
+    ui?: EditorDocument["ui"];
+    directives?: EditorDirective[];
+    minimap?: EditorMinimapBake;
+    environment?: EditorEnvironment;
+};
+/** Builds a fresh, empty editor document to start authoring a scene from scratch.
+ * @internal
+ */
 export declare function createEmptyEditorDocument(): EditorDocument;
-/** Deep-copies an editor document so edits never mutate the source. */
+/**
+ * Deep-copies an editor document so edits never mutate the source. The terrain snapshot is
+ * shared by reference: sculpt commands replace it wholesale (copy-on-write), never mutate it in
+ * place, so history snapshots stay cheap even on large heightfields.
+  * @internal
+  */
 export declare function cloneEditorDocument(doc: EditorDocument): EditorDocument;
-/** Resolves a game's `editorLayers` export — document, partial data, or factory — into a full document. */
+/** Resolves a game's `editorLayers` export — document, partial data, or factory — into a full document.
+ * @internal
+ */
 export declare function normalizeEditorLayers(input: EditorLayersInput | undefined | null): EditorDocument;
-/** Combines multiple editor documents' markers, volumes, paths, and notes into one. */
+/**
+ * Reserves `id` in `taken` and returns it unchanged when free; otherwise mints the next free
+ * `<id>_copy`/`<id>_copyN` suffix and reserves that instead. The one place object ids are made
+ * unique across a document's markers/volumes/paths/annotations as a single global namespace, so a
+ * merged-in or imported object can never silently shadow an existing object in another collection.
+ * @internal
+ */
+export declare function ensureUniqueEditorId(id: string, taken: Set<string>): string;
+/** Combines multiple editor documents' markers, volumes, paths, notes, prefabs, and collections
+ * into one, re-idding any placeable object whose id collides with one already merged in — across
+ * all four collections, since selection/parenting/removal treat those ids as one document-global
+ * namespace.
+ * @internal
+ */
 export declare function mergeEditorDocuments(...docs: readonly EditorDocument[]): EditorDocument;
-/** Looks up a marker by id in an editor document. */
+/** Extracts the subset of a document matching the given ids — the clipboard fragment for copy/paste.
+ * @internal
+ */
+export declare function extractEditorFragment(doc: EditorDocument, ids: readonly string[]): EditorDocument;
+/** Counts every object in a document across markers, volumes, paths, and notes.
+ * @internal
+ */
+export declare function editorDocumentSize(doc: EditorDocument): number;
+/** Looks up a prefab by id in an editor document.
+ * @internal
+ */
+export declare function findEditorPrefab(doc: EditorDocument, id: string): EditorPrefab | undefined;
+/** Looks up a named collection / selection set by id in an editor document.
+ * @internal
+ */
+export declare function findEditorCollection(doc: EditorDocument, id: string): EditorCollection | undefined;
+/**
+ * Looks up a gameplay data catalog by id on the scene document.
+ * @capability editor-catalogs Find a persisted catalog bag by id.
+ */
+export declare function findEditorCatalog(doc: EditorDocument, id: string): EditorCatalogData | undefined;
+/**
+ * Looks up one entry inside a gameplay data catalog.
+ * @capability editor-catalogs Find a catalog entry's meta bag by catalog + entry id.
+ */
+export declare function findEditorCatalogEntry(doc: EditorDocument, catalogId: string, entryId: string): EditorCatalogEntry | undefined;
+/**
+ * Seeds default catalog rows from game-exported definitions into a document: missing catalogs and
+ * missing entries are filled from the definition; existing document values win (overlay already applied).
+ * @capability editor-catalogs Seed scene-document catalogs from game-exported schemas.
+ */
+export declare function seedEditorCatalogs(doc: EditorDocument, definitions: readonly EditorCatalogDefinition[]): EditorDocument;
+/**
+ * True when an object carries a per-object `locked` flag (hierarchy lock toggle).
+ * Collection membership is checked separately by {@link isEditorObjectLocked}.
+ * @internal
+ */
+export declare function isEditorObjectSelfLocked(doc: EditorDocument, id: string): boolean;
+/**
+ * True when an object is a member of any locked collection (production group lock).
+ * @internal
+ */
+export declare function isEditorObjectCollectionLocked(doc: EditorDocument, id: string): boolean;
+/**
+ * True when an object id is locked for edit — either its own `locked` flag or membership in a
+ * locked collection. Blocks move/delete via session mutations.
+ * @internal
+ */
+export declare function isEditorObjectLocked(doc: EditorDocument, id: string): boolean;
+/**
+ * True when an object carries `hidden: true` — omitted from editor viewport overlays and picking
+ * while remaining in the hierarchy and document.
+ * @internal
+ */
+export declare function isEditorObjectHidden(doc: EditorDocument, id: string): boolean;
+/**
+ * Extracts the selected ids into a prefab fragment centered on their own bounds centroid, so the
+ * same prefab reinserts consistently regardless of where in the scene (or which game) it lands.
+  * @internal
+  */
+export declare function createPrefabFragment(doc: EditorDocument, ids: readonly string[]): EditorFragmentContent;
+/** Looks up a marker by id in an editor document.
+ * @internal
+ */
 export declare function findEditorMarker(doc: EditorDocument, id: string): EditorMarker | undefined;
-/** Looks up a volume by id in an editor document. */
+/** Looks up a marker by id and throws when it is absent — for scene contracts where a
+ * missing marker is an authoring error to surface loudly, not a runtime branch to handle.
+ * @internal
+ */
+export declare function requireEditorMarker(doc: EditorDocument, id: string): EditorMarker;
+/** A marker's world position as an `[x, y, z]` tuple — the shared shape gameplay tables read.
+ * @internal
+ */
+export declare function editorMarkerPosition(marker: EditorMarker): readonly [x: number, y: number, z: number];
+/** A marker's ground position as an `[x, z]` tuple, dropping the vertical axis.
+ * @internal
+ */
+export declare function editorMarkerXZ(marker: EditorMarker): readonly [x: number, z: number];
+/** Looks up a volume by id in an editor document.
+ * @internal
+ */
 export declare function findEditorVolume(doc: EditorDocument, id: string): EditorVolume | undefined;
-/** Looks up a path by id in an editor document. */
+/** Looks up a path by id in an editor document.
+ * @internal
+ */
 export declare function findEditorPath(doc: EditorDocument, id: string): EditorPath | undefined;
-/** Looks up an annotation note by id in an editor document. */
+/** Looks up an annotation note by id in an editor document.
+ * @internal
+ */
 export declare function findEditorNote(doc: EditorDocument, id: string): EditorNote | undefined;
-/** Lists the distinct marker, volume, and path kinds authored in a document. */
+/** Lists the distinct marker, volume, and path kinds authored in a document.
+ * @internal
+ */
 export declare function listEditorKinds(doc: EditorDocument): {
     markers: string[];
     volumes: string[];
     paths: string[];
 };
-/** Serializes an editor document to JSON text for saving or export. */
+/** The id of an object's parent, or undefined when it is a root (or unknown).
+ * @internal
+ */
+export declare function editorParentOf(doc: EditorDocument, id: string): string | undefined;
+/** The direct child ids of an object (empty when it has none).
+ * @internal
+ */
+export declare function editorChildren(doc: EditorDocument, parentId: string): string[];
+/** Object ids with no parent (or whose parent no longer exists) — the roots of the hierarchy.
+ * @internal
+ */
+export declare function editorRoots(doc: EditorDocument): string[];
+/** Every descendant id of the given ids (children, grandchildren, …), excluding the inputs.
+ * @internal
+ */
+export declare function collectDescendants(doc: EditorDocument, ids: Iterable<string>): Set<string>;
+/** True when parenting `id` under `parentId` would form a cycle (or parent itself to itself).
+ * @internal
+ */
+export declare function wouldCreateCycle(doc: EditorDocument, id: string, parentId: string | null): boolean;
+/** Serializes an editor document to JSON text for saving or export.
+ * @internal
+ */
 export declare function exportEditorDocumentJson(doc: EditorDocument, pretty?: boolean): string;
-/** Parses JSON text back into a normalized editor document. */
+/** One field-level failure surfaced while decoding an untrusted editor document, `path` pointing
+ * at the exact field that failed (e.g. `$.markers[2].position`).
+ * @internal
+ */
+export interface EditorDocumentDiagnostic {
+    path: string;
+    message: string;
+}
+/** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while
+ * decoding it.
+ * @internal
+ */
+export type DecodeEditorDocumentResult = {
+    ok: true;
+    document: EditorDocument;
+} | {
+    ok: false;
+    errors: EditorDocumentDiagnostic[];
+};
+/**
+ * The authoritative decoder/migrator for an editor document arriving from outside this process
+ * (disk, network, an agent's `import_document` RPC): validates every field with a path-specific
+ * diagnostic on failure instead of trusting the shape, then migrates forward — routes any embedded
+ * terrain through {@link migrateTerrainSnapshot} and normalizes `version` to the one this build
+ * understands. Every other loader in this module funnels through here.
+ * @internal
+ */
+export declare function decodeEditorDocument(raw: unknown): DecodeEditorDocumentResult;
+/** Parses JSON text back into a normalized editor document, throwing a message that names every
+ * field that failed to decode when the shape is malformed.
+ * @internal
+ */
 export declare function importEditorDocumentJson(raw: string): EditorDocument;
-/** Computes the world-space min/max bounds spanning every object in a document, or null if empty. */
+/**
+ * Applies a saved editor document on top of a game's derived layers: overlay objects replace
+ * same-id base objects and new overlay objects are appended, so editor saves win over source
+ * data until they are folded back in.
+  * @internal
+  */
+export declare function applyEditorDocumentOverlay(base: EditorDocument, overlay: EditorDocument): EditorDocument;
+/** Computes the world-space min/max bounds spanning every object in a document, or null if empty.
+ * @internal
+ */
 export declare function editorDocumentBounds(doc: EditorDocument): {
     min: {
         x: number;