@jgengine/core 0.18.0 → 0.19.0

package/dist/vfx/particleDirector.js

@@ -0,0 +1,81 @@
+/**
+ * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
+ * State is data-only and serializable: standing emitters survive `snapshot`/`restore`,
+ * queued bursts are transient. The renderer subscribes, drains bursts, and mirrors
+ * the emitter list — the director never allocates particle pools itself.
+ *
+ * @capability particle-director game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+ */
+export function createParticleDirector() {
+    let nextSeq = 1;
+    let bursts = [];
+    const emitters = new Map();
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        burst(config, count, blending) {
+            const wanted = Math.floor(count);
+            if (wanted <= 0)
+                return;
+            bursts.push({ seq: nextSeq++, config, count: wanted, ...(blending === undefined ? {} : { blending }) });
+            notify();
+        },
+        attach(id, config, options) {
+            emitters.set(id, {
+                id,
+                config,
+                ...(options?.follow === undefined ? {} : { follow: options.follow }),
+                ...(options?.offset === undefined ? {} : { offset: options.offset }),
+                ...(options?.blending === undefined ? {} : { blending: options.blending }),
+            });
+            notify();
+        },
+        retune(id, patch) {
+            const current = emitters.get(id);
+            if (current === undefined)
+                return;
+            emitters.set(id, { ...current, config: { ...current.config, ...patch } });
+            notify();
+        },
+        detach(id) {
+            if (!emitters.delete(id))
+                return;
+            notify();
+        },
+        clear() {
+            if (emitters.size === 0 && bursts.length === 0)
+                return;
+            emitters.clear();
+            bursts = [];
+            notify();
+        },
+        emitters() {
+            return Array.from(emitters.values());
+        },
+        drainBursts() {
+            if (bursts.length === 0)
+                return [];
+            const drained = bursts;
+            bursts = [];
+            return drained;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { nextSeq, emitters: Array.from(emitters.values()) };
+        },
+        restore(state) {
+            nextSeq = state.nextSeq;
+            bursts = [];
+            emitters.clear();
+            for (const spec of state.emitters)
+                emitters.set(spec.id, spec);
+            notify();
+        },
+    };
+}

package/dist/visibility/simulationCulling.d.ts

@@ -1,4 +1,4 @@
-import type { LodBand } from "../world/lod.js";
+import type { LodBand, LodSchedulerState } from "../world/lod.js";
 /**
  * Simulation culling is a SEPARATE, opt-in system from render culling. Render culling only
  * decides what is drawn; this decides whether a low-priority off-screen entity updates this
@@ -23,6 +23,11 @@ export interface SimulationDecision {
     /** Seconds of accumulated time delivered when `update` is true (for catch-up integration). */
     elapsed: number;
 }
+/** Plain JSON state of a {@link SimulationCuller}: the enabled flag and each id's throttle accumulator. */
+export interface SimulationCullerState {
+    enabled: boolean;
+    scheduler: LodSchedulerState;
+}
 export interface SimulationCuller {
     enabled(): boolean;
     setEnabled(value: boolean): void;
@@ -30,5 +35,7 @@ export interface SimulationCuller {
     step(id: string, distance: number, dt: number): SimulationDecision;
     forget(id: string): void;
     clear(): void;
+    snapshot(): SimulationCullerState;
+    restore(next: SimulationCullerState): void;
 }
 export declare function createSimulationCuller(options?: SimulationCullingOptions): SimulationCuller;

package/dist/visibility/simulationCulling.js

@@ -32,5 +32,12 @@ export function createSimulationCuller(options = {}) {
         clear() {
             scheduler.clear();
         },
+        snapshot() {
+            return { enabled, scheduler: scheduler.snapshot() };
+        },
+        restore(next) {
+            enabled = next.enabled;
+            scheduler.restore(next.scheduler);
+        },
     };
 }

package/dist/visibility/spatialIndex.d.ts

@@ -10,6 +10,25 @@ export interface SpatialIndexOptions {
      */
     readonly maxCellSpan?: number;
 }
+/** Integer cell bounds an object covers, inclusive on both ends. */
+export interface SpatialCellRange {
+    x0: number;
+    y0: number;
+    z0: number;
+    x1: number;
+    y1: number;
+    z1: number;
+}
+/**
+ * Plain JSON state of a {@link SpatialIndex}. Cells and their ids keep insertion order, so a restored
+ * index returns query results in the same order.
+ */
+export interface SpatialIndexState {
+    /** Per object: its cell range (`null` when oversized) and whether it was inserted as dynamic. */
+    entries: [id: string, range: SpatialCellRange | null, dynamic: boolean][];
+    cells: [x: number, y: number, z: number, ids: string[]][];
+    oversized: string[];
+}
 /**
  * A uniform 3D spatial hash the renderer and streaming system query for potentially-visible
  * objects instead of scanning the whole scene. Objects are keyed by their world AABB into
@@ -39,6 +58,8 @@ export interface SpatialIndex {
     }[];
     cellSize(): number;
     clear(): void;
+    snapshot(): SpatialIndexState;
+    restore(next: SpatialIndexState): void;
 }
 export declare function createSpatialIndex(options?: SpatialIndexOptions): SpatialIndex;
 /** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */

package/dist/visibility/spatialIndex.js

@@ -206,6 +206,22 @@ export function createSpatialIndex(options = {}) {
             entries.clear();
             stamps.clear();
         },
+        snapshot() {
+            return {
+                entries: [...entries].map(([id, entry]) => [id, entry.range === null ? null : { ...entry.range }, entry.dynamic]),
+                cells: [...cells.values()].map((bucket) => [bucket.x, bucket.y, bucket.z, [...bucket.ids]]),
+                oversized: [...oversized],
+            };
+        },
+        restore(next) {
+            this.clear();
+            for (const [id, range, dynamic] of next.entries)
+                entries.set(id, { range: range === null ? null : { ...range }, dynamic });
+            for (const [x, y, z, ids] of next.cells)
+                cells.set(packCell(x, y, z), { x, y, z, ids: new Set(ids) });
+            for (const id of next.oversized)
+                oversized.add(id);
+        },
     };
 }
 /** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */

package/dist/world/authoredSolids.d.ts

@@ -0,0 +1,46 @@
+import type { WorldSolid, WorldSolids } from "./worldSolids.js";
+type Vec3Like = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** Minimal editor document shape {@link resolveAuthoredSolids} walks; any `EditorDocument` satisfies it. */
+export interface AuthoredSolidsDocumentLike {
+    markers: readonly {
+        id: string;
+        kind: string;
+        position: Vec3Like;
+        rotationY?: number;
+        meta?: Record<string, unknown>;
+    }[];
+    volumes: readonly {
+        id: string;
+        kind: string;
+        center: Vec3Like;
+        halfExtents?: Vec3Like;
+        radius?: number;
+        meta?: Record<string, unknown>;
+    }[];
+    paths: readonly {
+        id: string;
+        kind: string;
+        points: readonly Vec3Like[];
+        meta?: Record<string, unknown>;
+    }[];
+}
+/** Layer prefix `syncAuthoredSolids` owns in `ctx.world.solids`; one layer per document object. */
+export declare const AUTHORED_SOLID_LAYER_PREFIX = "authored:";
+/**
+ * Solids for every document object whose scene kind declares `solids`, keyed by object id. Objects
+ * whose kind has no `solids` hook, or whose hook returns none, are left out.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export declare function resolveAuthoredSolids(document: AuthoredSolidsDocumentLike, sampleHeight?: (x: number, z: number) => number): Map<string, readonly WorldSolid[]>;
+/**
+ * Write a document's studio solids into `solids` (usually `ctx.world.solids`), one
+ * `authored:<objectId>` layer per object, dropping authored layers the document no longer has.
+ * Call again whenever the document changes.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export declare function syncAuthoredSolids(solids: WorldSolids, document: AuthoredSolidsDocumentLike, sampleHeight?: (x: number, z: number) => number): void;
+export {};

package/dist/world/authoredSolids.js

@@ -0,0 +1,75 @@
+import { registerBuiltinSceneKinds } from "../scene/builtinSceneKinds.js";
+import { getSceneKind, parseParams } from "../scene/sceneKinds.js";
+/** Layer prefix `syncAuthoredSolids` owns in `ctx.world.solids`; one layer per document object. */
+export const AUTHORED_SOLID_LAYER_PREFIX = "authored:";
+function kindObjects(document) {
+    const objects = [];
+    for (const marker of document.markers) {
+        objects.push({
+            id: marker.id,
+            kind: marker.kind,
+            position: marker.position,
+            ...(marker.rotationY === undefined ? {} : { rotationY: marker.rotationY }),
+            ...(marker.meta === undefined ? {} : { meta: marker.meta }),
+        });
+    }
+    for (const volume of document.volumes) {
+        objects.push({
+            id: volume.id,
+            kind: volume.kind,
+            center: volume.center,
+            ...(volume.halfExtents === undefined ? {} : { halfExtents: volume.halfExtents }),
+            ...(volume.radius === undefined ? {} : { radius: volume.radius }),
+            ...(volume.meta === undefined ? {} : { meta: volume.meta }),
+        });
+    }
+    for (const path of document.paths) {
+        objects.push({
+            id: path.id,
+            kind: path.kind,
+            points: path.points,
+            ...(path.meta === undefined ? {} : { meta: path.meta }),
+        });
+    }
+    return objects;
+}
+/**
+ * Solids for every document object whose scene kind declares `solids`, keyed by object id. Objects
+ * whose kind has no `solids` hook, or whose hook returns none, are left out.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export function resolveAuthoredSolids(document, sampleHeight) {
+    registerBuiltinSceneKinds();
+    const out = new Map();
+    const objects = kindObjects(document);
+    const context = { ...(sampleHeight === undefined ? {} : { sampleHeight }), objects };
+    for (const object of objects) {
+        const definition = getSceneKind(object.kind);
+        if (definition?.solids === undefined || definition.resolve === undefined)
+            continue;
+        const params = parseParams(definition.schema, object.meta);
+        const solids = definition.solids(definition.resolve(object, params, context), object, params, context);
+        if (solids.length > 0)
+            out.set(object.id, solids);
+    }
+    return out;
+}
+/**
+ * Write a document's studio solids into `solids` (usually `ctx.world.solids`), one
+ * `authored:<objectId>` layer per object, dropping authored layers the document no longer has.
+ * Call again whenever the document changes.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export function syncAuthoredSolids(solids, document, sampleHeight) {
+    const resolved = resolveAuthoredSolids(document, sampleHeight);
+    solids.batch(() => {
+        for (const layer of solids.layers()) {
+            if (!layer.startsWith(AUTHORED_SOLID_LAYER_PREFIX))
+                continue;
+            if (!resolved.has(layer.slice(AUTHORED_SOLID_LAYER_PREFIX.length)))
+                solids.remove(layer);
+        }
+        for (const [id, set] of resolved)
+            solids.set(`${AUTHORED_SOLID_LAYER_PREFIX}${id}`, set);
+    });
+}

package/dist/world/buildingGenerator.js

@@ -7,7 +7,7 @@
  * @capability building-generator seeded building as a placeable parametric asset
  */
 import { registerAssetGenerator, partsBounds } from "../scene/assetGenerator.js";
-import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_CONFIG, generateBuilding, resolveBuildingPalette } from "./buildings.js";
+import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_CONFIG, buildingSurfaceColor, generateBuilding, resolveBuildingPalette } from "./buildings.js";
 /** The generator id a catalog entry / placed marker references. */
 export const BUILDING_GENERATOR_ID = "building";
 /** The building generator's slider schema — drives the inspector via #809. */
@@ -47,7 +47,7 @@ export function generateBuildingAsset(params, seed) {
         position: part.position,
         size: part.scale,
         rotationY: part.rotationY,
-        color: palette[part.kind],
+        color: buildingSurfaceColor(palette[part.kind]),
     }));
     return { parts, bounds: partsBounds(parts) };
 }

package/dist/world/buildingKit.d.ts

@@ -3,7 +3,7 @@
  * as an instanced asset kit instead of untextured blocks. Pure serializable data — core resolves
  * bindings, the renderer loads them.
  */
-import type { BuildingKitSlot, BuildingPartKind, BuildingVariantCounts, Vec3 } from "./buildings.js";
+import type { BuildingKitSlot, BuildingPartKind, BuildingSurfaceMaterial, BuildingVariantCounts, Vec3 } from "./buildings.js";
 /**
  * How a kit model's native bounds are mapped onto the slot box `BuildingPartPlacement.scale`
  * describes.
@@ -32,6 +32,8 @@ export interface BuildingKitPart {
     /** Multiplier applied after `fit`. */
     scale?: Vec3;
     tint?: string;
+    /** Tiled PBR maps applied over the model's own materials; `color` tints, `repeat` sets the tiling. */
+    material?: BuildingSurfaceMaterial;
     /**
      * Quarter-turn the model when its long horizontal axis disagrees with the slot's, so a panel
      * authored running along Z still tiles a bay that runs along X. Default true — modular kits do not

package/dist/world/buildings.d.ts

@@ -103,11 +103,55 @@ export interface BuildingGridConfig {
     floorRange?: readonly [number, number];
 }
 export declare const DEFAULT_BUILDING_CONFIG: BuildingConfig;
-export type BuildingPalette = Record<BuildingPartKind, string>;
+/** URLs of the PBR maps a building surface tiles; `buildMaterialCatalog(...).resolve(id)!.maps` fits directly. */
+export interface BuildingSurfaceMaps {
+    color?: string;
+    normal?: string;
+    roughness?: string;
+    ao?: string;
+    metalness?: string;
+}
+/**
+ * A textured building surface: a base colour plus optional tiled PBR maps. With `maps`, `color`
+ * multiplies the albedo (leave it light to show the map as authored); without, it is the flat
+ * colour the part has always had.
+ */
+export interface BuildingSurfaceMaterial {
+    /** Base colour; the style's colour for that part kind when unset. */
+    color?: string;
+    maps?: BuildingSurfaceMaps;
+    /**
+     * Texture tiles per part slot along [x, y]; a number tiles both. Slots within one building share
+     * a size, so one repeat per kind is uniform there; it drifts across buildings with a different
+     * `bayWidth`. Default 1.
+     */
+    repeat?: number | readonly [number, number];
+    roughness?: number;
+    metalness?: number;
+}
+/** What a building part kind is painted with: a hex colour, or a colour plus tiled PBR maps. */
+export type BuildingSurface = string | BuildingSurfaceMaterial;
+export type BuildingPalette = Record<BuildingPartKind, BuildingSurface>;
 export type BuildingPaletteOverrides = Partial<BuildingPalette>;
+/** The flat colour of a surface: the hex itself, or a material's `color`, else `fallback`. */
+export declare function buildingSurfaceColor(surface: BuildingSurface | undefined, fallback?: string): string;
+/** Normalises a surface to its material form so a renderer reads one shape. */
+export declare function resolveBuildingSurface(surface: BuildingSurface): BuildingSurfaceMaterial;
 export type BuildingStyle = "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial";
 export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
-export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, BuildingPalette>;
+export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, Record<BuildingPartKind, string>>;
+/**
+ * Per-style facade-tone family: the wall colours a district spreads across its buildings so
+ * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's
+ * own `wall`; the rest fan warmer/cooler and lighter/darker around it.
+ */
+export declare const BUILDING_STYLE_WALL_TONES: Record<BuildingStyle, readonly string[]>;
+/**
+ * The facade-tone family for a style — the ramp {@link BUILDING_STYLE_WALL_TONES} keeps, falling
+ * back to the style's single palette wall when a style has no ramp.
+ * @internal
+ */
+export declare function resolveBuildingWallTones(style?: BuildingStyle): readonly string[];
 /** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
 /**

package/dist/world/buildings.js

@@ -38,6 +38,16 @@ export const DEFAULT_BUILDING_CONFIG = {
     probabilities: DEFAULT_PROBABILITIES,
     variants: DEFAULT_VARIANTS,
 };
+/** The flat colour of a surface: the hex itself, or a material's `color`, else `fallback`. */
+export function buildingSurfaceColor(surface, fallback = "#808080") {
+    if (surface === undefined)
+        return fallback;
+    return typeof surface === "string" ? surface : (surface.color ?? fallback);
+}
+/** Normalises a surface to its material form so a renderer reads one shape. */
+export function resolveBuildingSurface(surface) {
+    return typeof surface === "string" ? { color: surface } : surface;
+}
 export const DEFAULT_BUILDING_STYLE = "generic";
 export const BUILDING_STYLE_PALETTES = {
     generic: {
@@ -181,6 +191,34 @@ export const BUILDING_STYLE_PALETTES = {
         corner: "#c3d0d7",
     },
 };
+/**
+ * Per-style facade-tone family: the wall colours a district spreads across its buildings so
+ * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's
+ * own `wall`; the rest fan warmer/cooler and lighter/darker around it.
+ */
+export const BUILDING_STYLE_WALL_TONES = {
+    generic: ["#9c8f80", "#736a60", "#b7a894", "#8b8a80", "#c3ac90", "#635c54", "#a1978c"],
+    capital: ["#cfc5ad", "#ac9878", "#e6e0cf", "#a8a698", "#c8b48d", "#847b68", "#ded2b3"],
+    village: ["#b59e7a", "#9c8360", "#c9b895", "#8d7a5f", "#c2a173", "#a8977f", "#d6c3a1"],
+    desert: ["#c9a877", "#b08f61", "#ddc396", "#a4855c", "#d3b98d", "#93764f", "#c6b189"],
+    industrial: ["#7c838f", "#565d69", "#96a0ac", "#68737a", "#8a8173", "#4a5058", "#a0a6ac"],
+    coastal: ["#e8e2d2", "#cfd6d3", "#f1ece0", "#c9c0ac", "#dbe0dc", "#b7b3a3", "#e5d9c4"],
+    neon: ["#1b1b26", "#262233", "#141a24", "#2c2030", "#181f2b", "#221d1f", "#101018"],
+    ruin: ["#6b6156", "#57503f", "#7d7266", "#4f4a44", "#736450", "#8a8072", "#5d5b53"],
+    frontier: ["#7f5539", "#6a462d", "#96684a", "#5c4331", "#8a6540", "#a07a55", "#6f523c"],
+    aerial: ["#dfe7ec", "#c6d2da", "#eef3f6", "#b6c3cb", "#d3dde2", "#a7b7c0", "#e7eef1"],
+};
+/**
+ * The facade-tone family for a style — the ramp {@link BUILDING_STYLE_WALL_TONES} keeps, falling
+ * back to the style's single palette wall when a style has no ramp.
+ * @internal
+ */
+export function resolveBuildingWallTones(style = DEFAULT_BUILDING_STYLE) {
+    const tones = BUILDING_STYLE_WALL_TONES[style];
+    if (tones !== undefined && tones.length > 0)
+        return tones;
+    return [buildingSurfaceColor(resolveBuildingPalette(style).wall)];
+}
 /** @internal */
 export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {
     const preset = BUILDING_STYLE_PALETTES[style];
@@ -413,9 +451,21 @@ function pushRoof(parts, config, width, depth) {
     for (let index = 0; index < roofCells; index += 1) {
         if (!chance(config.seed, `roof:prop:${index}`, config.probabilities.roofProp))
             continue;
-        const x = config.center[0] - width / 2 + config.bayWidth * ((index % config.baysWide) + 0.5);
-        const z = config.center[1] - depth / 2 + config.bayWidth * (Math.floor(index / config.baysWide) + 0.5);
-        parts.push(part(config, "roofProp", "roof", [x, height + config.facadeDepth + config.floorHeight * 0.16, z], [config.bayWidth * 0.34, config.floorHeight * 0.32, config.bayWidth * 0.34], `roof:prop:${index}`, { facade: "roof", level: config.floors, bay: index }, ["decor"]));
+        // Plant sized and nudged off its cell centre: props locked to the bay grid at one size read as
+        // a checkerboard of cubes rather than a roof of mechanical units.
+        const wide = hash01(config.seed, `roof:prop:${index}:w`);
+        const tall = hash01(config.seed, `roof:prop:${index}:h`);
+        const propW = config.bayWidth * (0.2 + wide * 0.4);
+        const propD = config.bayWidth * (0.18 + (1 - wide) * 0.36);
+        const propH = config.floorHeight * (0.14 + tall * 0.52);
+        const x = config.center[0] -
+            width / 2 +
+            config.bayWidth * ((index % config.baysWide) + 0.5 + (hash01(config.seed, `roof:prop:${index}:x`) - 0.5) * 0.5);
+        const z = config.center[1] -
+            depth / 2 +
+            config.bayWidth *
+                (Math.floor(index / config.baysWide) + 0.5 + (hash01(config.seed, `roof:prop:${index}:z`) - 0.5) * 0.5);
+        parts.push(part(config, "roofProp", "roof", [x, height + config.facadeDepth + propH / 2, z], [propW, propH, propD], `roof:prop:${index}`, { facade: "roof", level: config.floors, bay: index }, ["decor"]));
     }
 }
 function pushCorners(parts, config, width, depth) {