@jgengine/core 0.11.0 → 0.12.0

package/dist/editor/streamer.js

@@ -0,0 +1,68 @@
+/**
+ * The proximity streamer for a sharded world (#985 stage 3): a stateful scheduler that decides,
+ * as the camera moves, which shards enter and leave residency. It is pure scheduling — actually
+ * reading/merging the shard documents stays the caller's job (compose with
+ * `@jgengine/core/editor/world`'s `loadWorldDocument` on each returned delta) — so the streamer has
+ * no I/O and stays deterministic and testable. Hysteresis (`loadRadius` < `keepRadius`) stops a
+ * shard on a boundary from thrashing load/unload every frame.
+ */
+function isAlwaysResident(shard) {
+    return shard.residency === "always" || shard.bounds === undefined;
+}
+/**
+ * Distance from a point to a shard's XZ footprint (0 when inside), or 0 for an always-resident shard.
+ * @capability world-streaming distance from a camera to a shard footprint
+ */
+export function shardDistance(shard, center) {
+    if (shard.bounds === undefined)
+        return 0;
+    const { min, max } = shard.bounds;
+    const qx = Math.max(min[0], Math.min(center.x, max[0]));
+    const qz = Math.max(min[1], Math.min(center.z, max[1]));
+    return Math.hypot(center.x - qx, center.z - qz);
+}
+/**
+ * Creates a proximity streamer over a world's shards. Always-resident shards are resident from the
+ * first update onward; each bounded shard loads when the camera comes within `loadRadius` of its
+ * footprint and unloads only once the camera passes `keepRadius` (≥ `loadRadius`, clamped up),
+ * giving a hysteresis band that prevents boundary thrash. Purely spatial and deterministic; the
+ * caller wires each delta to `loadWorldDocument`.
+ * @capability world-streaming schedule shard load/unload by camera proximity
+ */
+export function createWorldStreamer(config) {
+    const loadRadius = Math.max(0, config.loadRadius);
+    const keepRadius = Math.max(loadRadius, config.keepRadius);
+    const shards = [...config.shards];
+    const resident = new Set();
+    const residentSorted = () => [...resident].sort();
+    return {
+        update(center) {
+            const load = [];
+            const unload = [];
+            for (const shard of shards) {
+                if (isAlwaysResident(shard)) {
+                    if (!resident.has(shard.id)) {
+                        resident.add(shard.id);
+                        load.push(shard.id);
+                    }
+                    continue;
+                }
+                const distance = shardDistance(shard, center);
+                const isResident = resident.has(shard.id);
+                if (!isResident && distance <= loadRadius) {
+                    resident.add(shard.id);
+                    load.push(shard.id);
+                }
+                else if (isResident && distance > keepRadius) {
+                    resident.delete(shard.id);
+                    unload.push(shard.id);
+                }
+            }
+            return { load: load.sort(), unload: unload.sort(), resident: residentSorted() };
+        },
+        resident: residentSorted,
+        reset() {
+            resident.clear();
+        },
+    };
+}

package/dist/editor/types.d.ts

@@ -1,5 +1,6 @@
 import type { ParamSchema } from "../scene/sceneKinds.js";
 import type { EditorUiDocument } from "../ui/hudDocument.js";
+import type { MinimapBakeBounds } from "../world/minimapBake.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
 import type { EditorGridLayer } from "./grid.js";
 export type { EditorUiDocument, EditorUiPanelLayout, HudResizeAxes, HudPanelTypeDef } from "../ui/hudDocument.js";
@@ -26,6 +27,16 @@ export interface EditorMarker {
     catalogId?: string;
     /** Id of the object this one is parented under; moving the parent moves this with it. */
     parentId?: string;
+    /**
+     * Per-object edit lock — blocks transform/remove the same way a locked collection does.
+     * Combined with collection locks in `isEditorObjectLocked`.
+     */
+    locked?: boolean;
+    /**
+     * Per-object viewport hide — object stays in the hierarchy/document but is omitted from
+     * editor overlays and picking when true. Independent of per-kind layer visibility.
+     */
+    hidden?: boolean;
     meta?: Record<string, unknown>;
 }
 /** A spatial region — zone, aggro range, capture area — placed in the scene. */
@@ -41,6 +52,10 @@ export interface EditorVolume {
     label?: string;
     /** Id of the object this one is parented under; moving the parent moves this with it. */
     parentId?: string;
+    /** Per-object edit lock — see {@link EditorMarker.locked}. */
+    locked?: boolean;
+    /** Per-object viewport hide — see {@link EditorMarker.hidden}. */
+    hidden?: boolean;
     meta?: Record<string, unknown>;
 }
 /** A polyline of points — road, corridor, patrol route — placed in the scene. */
@@ -53,6 +68,10 @@ export interface EditorPath {
     label?: string;
     /** Id of the object this one is parented under; moving the parent moves this with it. */
     parentId?: string;
+    /** Per-object edit lock — see {@link EditorMarker.locked}. */
+    locked?: boolean;
+    /** Per-object viewport hide — see {@link EditorMarker.hidden}. */
+    hidden?: boolean;
     meta?: Record<string, unknown>;
 }
 /** A free-text annotation pinned to a world position for designers. */
@@ -63,6 +82,10 @@ export interface EditorNote {
     color?: string;
     /** Id of the object this one is parented under; moving the parent moves this with it. */
     parentId?: string;
+    /** Per-object edit lock — see {@link EditorMarker.locked}. */
+    locked?: boolean;
+    /** Per-object viewport hide — see {@link EditorMarker.hidden}. */
+    hidden?: boolean;
     meta?: Record<string, unknown>;
 }
 /**
@@ -120,6 +143,14 @@ export interface EditorCatalogEntry {
 export interface EditorCatalogData {
     id: string;
     entries: EditorCatalogEntry[];
+    /**
+     * Optional document-carried `ParamSchema`. Present only for editor-authored catalogs (created from
+     * the Data tab, no matching game export); game-exported catalogs keep their schema in code. Carrying
+     * it here is what lets an editor-only catalog round-trip through save/reload and drive the inspector.
+     */
+    schema?: ParamSchema;
+    /** Optional display label for a document-authored catalog; falls back to the id when absent. */
+    label?: string;
 }
 /**
  * Game-exported catalog definition: a `ParamSchema` plus default entries. Schemas stay in code;
@@ -134,6 +165,48 @@ export interface EditorCatalogDefinition {
 }
 /** Accepted shape for a game's `editorCatalogs` export: definitions, or a factory. */
 export type EditorCatalogsInput = readonly EditorCatalogDefinition[] | (() => readonly EditorCatalogDefinition[]);
+/**
+ * A baked top-down minimap stored on the scene document (#1036): the PNG the editor rasterized from
+ * the authored terrain (a `data:image/png;base64,…` URI) plus the world bounds it spans. Runtime
+ * feeds these straight into the `Minimap`/`WorldMap` `background`/`mapBounds` props — no re-raster.
+ * @capability minimap-bake persist a baked minimap PNG + bounds on the scene document
+ */
+export interface EditorMinimapBake {
+    /** `data:image/png;base64,…` background produced by `bakeMinimapFromDocument`. */
+    background: string;
+    /** World-space rectangle the baked image spans. */
+    bounds: MinimapBakeBounds;
+}
+/** Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`. */
+export type EditorSkyPreset = "day" | "dusk" | "night";
+/**
+ * Linear distance fog authored on the scene document — serializable subset of sky/backdrop fog.
+ * Absent fields keep engine defaults when the document is applied at runtime.
+ */
+export interface EditorFogConfig {
+    color?: string;
+    near?: number;
+    far?: number;
+}
+/**
+ * Scene-document environment/lighting authoring (#1110): sky preset, optional time-of-day drive,
+ * horizon/zenith tints, sun/ambient intensity, and fog. Serializable and genre-agnostic — games
+ * feed it into `environment({ sky: sky(skyFromDocument(doc)) })` (or leave world.ts sky as a
+ * fallback when the field is absent). Absent until the lighting workspace (or a seed layer) writes
+ * it, so existing documents load unchanged.
+ * @capability editor-environment persist sky/fog/lighting knobs on the scene document
+ */
+export interface EditorEnvironment {
+    /** Fixed sky look when `timeOfDay` is off (or no clock is available). */
+    preset?: EditorSkyPreset;
+    /** Drive sun/sky from the world clock's day fraction instead of the fixed `preset`. */
+    timeOfDay?: boolean;
+    horizonColor?: string;
+    zenithColor?: string;
+    sunIntensity?: number;
+    ambientIntensity?: number;
+    fog?: EditorFogConfig;
+}
 /** The full authored scene: every marker, volume, path, note, and sculpted terrain for a game. */
 export interface EditorDocument {
     version: 1;
@@ -160,7 +233,77 @@ export interface EditorDocument {
      * Canvas mode (F2+C) and `canvas_move_panel` / `canvas_resize_panel` write here; HudPanel reads it.
      */
     ui?: EditorUiDocument;
+    /**
+     * Procedural **directives** — the scene-authorable face of the runtime scatter/population
+     * primitives. One directive line materializes into many placements at load (via
+     * `@jgengine/core/editor/directives`) instead of hundreds of explicit entries, so bulk ambient
+     * content (rocks, trees, mob populations) stays one diffable row. Absent until a game authors one.
+     */
+    directives?: EditorDirective[];
+    /**
+     * Baked top-down minimap (#1036) — the editor's `bake_minimap` action rasterizes the authored
+     * terrain into this PNG + bounds; runtime hands them to the `Minimap`/`WorldMap` props. Absent
+     * until baked, so old docs and unbaked games load unchanged.
+     */
+    minimap?: EditorMinimapBake;
+    /**
+     * Scene-document sky/fog/lighting (#1110). Absent until authored in the lighting workspace or
+     * seeded via `editorLayers`, so old docs load unchanged and world.ts can keep a fallback sky.
+     */
+    environment?: EditorEnvironment;
+}
+/** XZ world-space bounds, `[minX, minZ]`..`[maxX, maxZ]`, for a directive that names no region. */
+export interface EditorDirectiveArea {
+    min: [number, number];
+    max: [number, number];
+}
+/** Fields shared by every directive: a stable id, the region/area it fills, and a deterministic seed. */
+interface EditorDirectiveBase {
+    /** Stable directive id; also the prefix of every minted instance id (`<id>#<index>`). */
+    id: string;
+    /** Id of a document volume or scatter path whose footprint bounds the directive. */
+    region?: string;
+    /** Explicit XZ bounds used when no `region` is named. */
+    area?: EditorDirectiveArea;
+    /** Deterministic seed — the same directive + seed always materializes the same field. */
+    seed?: string | number;
+    /** Free-form authoring metadata. */
+    meta?: Record<string, unknown>;
+}
+/** Scatters catalog props (rocks/trees/foliage) across a region — feeds the existing scatter system. */
+export interface EditorScatterDirective extends EditorDirectiveBase {
+    kind: "scatter";
+    /** Catalog/asset id every placement instantiates. */
+    asset: string;
+    /** Items per square meter across the footprint. */
+    density: number;
+    /** Minimum spacing between placements (m); 0 allows clumping. */
+    minSpacing?: number;
+    /** Grid jitter 0..1 — 0 is a rigid lattice, 1 fully scattered. */
+    jitter?: number;
+    minScale?: number;
+    maxScale?: number;
+    /** Yaw range (radians) applied per placement. */
+    minYaw?: number;
+    maxYaw?: number;
+}
+/** One weighted species in a population directive, with a hard instance cap. */
+export interface EditorPopulationSpecies {
+    id: string;
+    /** Relative spawn weight; defaults to 1. */
+    weight?: number;
+    /** Maximum instances of this species the directive materializes. */
+    cap: number;
+}
+/** Populates a region with weighted, capped mob spawns — config for `ai/populationDirector`. */
+export interface EditorPopulationDirective extends EditorDirectiveBase {
+    kind: "population";
+    species: EditorPopulationSpecies[];
 }
+/** A procedural directive on the scene document: scatter props or a mob population. */
+export type EditorDirective = EditorScatterDirective | EditorPopulationDirective;
+/** The distinct directive kinds a materializer expands. */
+export type EditorDirectiveKind = EditorDirective["kind"];
 /** Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory. */
 export type EditorLayersInput = EditorDocument | Partial<Omit<EditorDocument, "version">> | (() => EditorDocument | Partial<Omit<EditorDocument, "version">>);
 /** Per-kind show/hide flags for the editor's layer panel. */

package/dist/editor/world.d.ts

@@ -0,0 +1,136 @@
+import { type EditorDocumentDiagnostic } from "./document.js";
+import type { EditorDocument } from "./types.js";
+/**
+ * A sharded **world**: a scene that is no longer one monolithic `editor.scene.json` but a manifest
+ * plus spatially-partitioned shard documents. A single-file game is the degenerate one-shard case,
+ * so nothing pays for scale it does not have. The shard/overlay documents are the exact
+ * {@link EditorDocument} format loaders already consume — this module is composition over
+ * `mergeEditorDocuments` / `extractEditorFragment` / `editorDocumentBounds`, not a new format.
+ */
+/** The manifest `kind` discriminator — a world folder's `world.json`. */
+export declare const WORLD_MANIFEST_KIND = "world";
+/** Whether a shard is always loaded (terrain, always-resident hero content) or streamed by proximity. */
+export type WorldShardResidency = "always" | "streamed";
+/** A shard's XZ world-space footprint, `[minX, minZ]`..`[maxX, maxZ]`, used to route/stream loads. */
+export interface WorldShardBounds {
+    min: [number, number];
+    max: [number, number];
+}
+/** One entry in a world manifest: a shard document, its footprint, residency, and optional overlay. */
+export interface WorldManifestShard {
+    /** Stable shard id (also the merge/stream unit). */
+    id: string;
+    /** Path to the shard's `EditorDocument` JSON, relative to the world folder. */
+    file: string;
+    /** XZ footprint used to cull the shard against a streaming query; absent = always resident. */
+    bounds?: WorldShardBounds;
+    /** `"always"` keeps the shard resident regardless of the query; default `"streamed"` when bounded. */
+    residency?: WorldShardResidency;
+    /** Path to a sparse overlay document applied on top of this shard (hand-tweaks over materialized content). */
+    overlay?: string;
+}
+/** The world grid the shards partition space on. */
+export interface WorldGrid {
+    /** Cell edge length in meters. */
+    cellSize: number;
+}
+/** Proximity streaming radii, in meters. */
+export interface WorldStreamingConfig {
+    /** Load shards whose footprint is within this distance of the query center. */
+    loadRadius: number;
+    /** Keep already-loaded shards resident until they fall outside this (larger) distance — hysteresis. */
+    keepRadius: number;
+}
+/** A world manifest — the `world.json` at the root of a world folder. */
+export interface WorldManifest {
+    kind: typeof WORLD_MANIFEST_KIND;
+    /** Manifest schema version; defaults to 1 when absent. */
+    version?: number;
+    grid?: WorldGrid;
+    shards: WorldManifestShard[];
+    streaming?: WorldStreamingConfig;
+}
+/** A spatial query used to select which shards a neighborhood needs. */
+export interface WorldQuery {
+    /** Query center in world space (typically the camera/player position). */
+    center: {
+        x: number;
+        z: number;
+    };
+    /** Selection radius in meters; 0 (default) selects only shards whose footprint contains the center. */
+    radius?: number;
+}
+/** Resolves a shard/overlay file path to a decoded document, or null when it cannot be read. */
+export type WorldShardResolver = (file: string) => EditorDocument | null;
+/**
+ * True when a shard should be resident for a query: always-resident shards always, bounded shards
+ * only when the query disc (`center` ± `radius`) overlaps their footprint.
+ * @capability world-shards select shards for a neighborhood by spatial query
+ */
+export declare function shardMatchesQuery(shard: WorldManifestShard, query: WorldQuery): boolean;
+/**
+ * The shards a query needs — always-resident shards plus every bounded shard whose footprint the
+ * query disc overlaps, in manifest order. With no query every shard is selected (load the planet),
+ * so a one-shard game and an unqueried load behave exactly as a monolithic document does today.
+ * @capability world-shards select shards for a neighborhood by spatial query
+ */
+export declare function selectWorldShards(manifest: WorldManifest, query?: WorldQuery): WorldManifestShard[];
+/**
+ * Loads the live neighborhood document for a query: reads each selected shard through `resolve`,
+ * applies its overlay (if any) on top, then merges them into one {@link EditorDocument} downstream
+ * consumers (`placeAuthoredObjects`, `collectAuthoredTriggers`, scatter, …) read unchanged. The
+ * monolith becomes an internal detail of the loader; a one-shard world yields exactly that shard.
+ * @capability world-shards merge the shards for a neighborhood into one live document
+ */
+export declare function loadWorldDocument(manifest: WorldManifest, resolve: WorldShardResolver, query?: WorldQuery): EditorDocument;
+/** The always-resident base shard id used by {@link splitEditorDocumentIntoShards}. */
+export declare const WORLD_BASE_SHARD_ID = "base";
+/** Options controlling how a monolithic document is partitioned into shards. */
+export interface SplitWorldOptions {
+    /** Grid cell edge length in meters. Default 256. */
+    cellSize?: number;
+    /** Directory prefix for generated shard files. Default `"shards"`. */
+    shardDir?: string;
+}
+/** The result of splitting a document: a manifest plus the shard documents keyed by their file path. */
+export interface SplitWorldResult {
+    manifest: WorldManifest;
+    /** Shard file path → document, for a caller to serialize into a world folder. */
+    shards: Record<string, EditorDocument>;
+}
+/**
+ * Splits a monolithic document into a sharded world: placeable objects (markers, volumes, paths,
+ * notes) are bucketed into `cellSize`-meter grid cells by a representative point and extracted into
+ * per-cell shard documents; the non-placeable extras (terrain, catalogs, prefabs, collections,
+ * grids, HUD layout) go into one always-resident `base` shard. Round-trips through
+ * {@link loadWorldDocument} to the same object set — the reverse of monolith authoring, so a large
+ * scene can be sharded once and streamed thereafter. Cell shards carry their exact object footprint
+ * as bounds; empty cells are omitted; order is deterministic (row-major by grid coordinate).
+ * @capability world-shards split a monolithic scene document into spatial shards
+ */
+export declare function splitEditorDocumentIntoShards(doc: EditorDocument, options?: SplitWorldOptions): SplitWorldResult;
+/**
+ * The backward-compatible degenerate manifest: one always-resident shard pointing at a single scene
+ * document file. `loadWorldDocument(singleShardWorldManifest(file), resolve)` returns exactly that
+ * document — the migration path for a game that has one `editor.scene.json` and wants the world API
+ * without sharding yet.
+ * @capability world-shards wrap a single scene document as a one-shard world
+ */
+export declare function singleShardWorldManifest(file: string, shardId?: string): WorldManifest;
+/** Result of {@link decodeWorldManifest}: a typed manifest, or every diagnostic collected decoding it. */
+export type DecodeWorldManifestResult = {
+    ok: true;
+    manifest: WorldManifest;
+} | {
+    ok: false;
+    errors: EditorDocumentDiagnostic[];
+};
+/**
+ * The authoritative decoder for a `world.json` manifest arriving from disk or an agent: validates
+ * `kind`, the shard list, and each shard's fields with a path-specific diagnostic on failure, so a
+ * malformed manifest fails loudly at the boundary instead of streaming a broken world.
+ * @capability world-shards decode an untrusted world manifest with per-field diagnostics
+ */
+export declare function decodeWorldManifest(raw: unknown): DecodeWorldManifestResult;
+/** Serializes a world manifest to pretty JSON for writing `world.json`. */
+export declare function exportWorldManifestJson(manifest: WorldManifest, pretty?: boolean): string;