@jgengine/core 0.8.0 → 0.9.0

package/dist/visibility/spatialIndex.js

@@ -0,0 +1,198 @@
+import { aabbIntersects } from "./bounds.js";
+import { aabbInFrustum } from "./frustum.js";
+function cellOf(value, size) {
+    return Math.floor(value / size);
+}
+function packCell(x, y, z) {
+    return `${x}:${y}:${z}`;
+}
+export function createSpatialIndex(options = {}) {
+    const size = options.cellSize ?? 16;
+    const maxSpan = options.maxCellSpan ?? 6;
+    const cells = new Map();
+    const oversized = new Set();
+    const entries = new Map();
+    // Allocation-free dedup for queries: an id is "seen" for query N when stamps.get(id) === N.
+    const stamps = new Map();
+    let queryStamp = 0;
+    function rangeOf(bounds) {
+        return {
+            x0: cellOf(bounds.minX, size), y0: cellOf(bounds.minY, size), z0: cellOf(bounds.minZ, size),
+            x1: cellOf(bounds.maxX, size), y1: cellOf(bounds.maxY, size), z1: cellOf(bounds.maxZ, size),
+        };
+    }
+    function spanTooBig(range) {
+        return (range.x1 - range.x0 > maxSpan ||
+            range.y1 - range.y0 > maxSpan ||
+            range.z1 - range.z0 > maxSpan);
+    }
+    function addToCells(id, range) {
+        for (let x = range.x0; x <= range.x1; x += 1) {
+            for (let y = range.y0; y <= range.y1; y += 1) {
+                for (let z = range.z0; z <= range.z1; z += 1) {
+                    const key = packCell(x, y, z);
+                    let bucket = cells.get(key);
+                    if (bucket === undefined) {
+                        bucket = new Set();
+                        cells.set(key, bucket);
+                    }
+                    bucket.add(id);
+                }
+            }
+        }
+    }
+    function removeFromCells(id, range) {
+        for (let x = range.x0; x <= range.x1; x += 1) {
+            for (let y = range.y0; y <= range.y1; y += 1) {
+                for (let z = range.z0; z <= range.z1; z += 1) {
+                    const key = packCell(x, y, z);
+                    const bucket = cells.get(key);
+                    if (bucket === undefined)
+                        continue;
+                    bucket.delete(id);
+                    if (bucket.size === 0)
+                        cells.delete(key);
+                }
+            }
+        }
+    }
+    function rangesEqual(a, b) {
+        return a.x0 === b.x0 && a.y0 === b.y0 && a.z0 === b.z0 && a.x1 === b.x1 && a.y1 === b.y1 && a.z1 === b.z1;
+    }
+    function place(id, bounds, dynamic) {
+        const range = rangeOf(bounds);
+        if (spanTooBig(range)) {
+            oversized.add(id);
+            entries.set(id, { range: null, dynamic });
+            return;
+        }
+        addToCells(id, range);
+        entries.set(id, { range, dynamic });
+    }
+    function collectCell(key, out) {
+        const bucket = cells.get(key);
+        if (bucket === undefined)
+            return;
+        for (const id of bucket) {
+            if (stamps.get(id) === queryStamp)
+                continue;
+            stamps.set(id, queryStamp);
+            out.push(id);
+        }
+    }
+    function collectOversized(out) {
+        for (const id of oversized) {
+            if (stamps.get(id) === queryStamp)
+                continue;
+            stamps.set(id, queryStamp);
+            out.push(id);
+        }
+    }
+    function collectBoxCells(minX, minY, minZ, maxX, maxY, maxZ, out, cellFilter) {
+        queryStamp += 1;
+        out.length = 0;
+        const x0 = cellOf(minX, size), y0 = cellOf(minY, size), z0 = cellOf(minZ, size);
+        const x1 = cellOf(maxX, size), y1 = cellOf(maxY, size), z1 = cellOf(maxZ, size);
+        for (let x = x0; x <= x1; x += 1) {
+            for (let y = y0; y <= y1; y += 1) {
+                for (let z = z0; z <= z1; z += 1) {
+                    if (cellFilter !== undefined && !cellFilter(x, y, z))
+                        continue;
+                    collectCell(packCell(x, y, z), out);
+                }
+            }
+        }
+        collectOversized(out);
+    }
+    return {
+        insert(id, bounds, dynamic = false) {
+            const existing = entries.get(id);
+            if (existing !== undefined) {
+                this.update(id, bounds);
+                return;
+            }
+            place(id, bounds, dynamic);
+        },
+        update(id, bounds) {
+            const existing = entries.get(id);
+            if (existing === undefined) {
+                place(id, bounds, true);
+                return;
+            }
+            const range = rangeOf(bounds);
+            const tooBig = spanTooBig(range);
+            if (tooBig) {
+                if (existing.range !== null)
+                    removeFromCells(id, existing.range);
+                oversized.add(id);
+                existing.range = null;
+                return;
+            }
+            if (existing.range === null) {
+                oversized.delete(id);
+                addToCells(id, range);
+                existing.range = range;
+                return;
+            }
+            if (rangesEqual(existing.range, range))
+                return;
+            removeFromCells(id, existing.range);
+            addToCells(id, range);
+            existing.range = range;
+        },
+        remove(id) {
+            const existing = entries.get(id);
+            if (existing === undefined)
+                return;
+            if (existing.range === null)
+                oversized.delete(id);
+            else
+                removeFromCells(id, existing.range);
+            entries.delete(id);
+            stamps.delete(id);
+        },
+        has(id) {
+            return entries.has(id);
+        },
+        size() {
+            return entries.size;
+        },
+        queryFrustum(frustum, out) {
+            collectBoxCells(frustum.minX, frustum.minY, frustum.minZ, frustum.maxX, frustum.maxY, frustum.maxZ, out, (x, y, z) => aabbInFrustum(frustum, x * size, y * size, z * size, (x + 1) * size, (y + 1) * size, (z + 1) * size));
+            return out;
+        },
+        queryBox(minX, minY, minZ, maxX, maxY, maxZ, out) {
+            collectBoxCells(minX, minY, minZ, maxX, maxY, maxZ, out);
+            return out;
+        },
+        querySphere(cx, cy, cz, radius, out) {
+            collectBoxCells(cx - radius, cy - radius, cz - radius, cx + radius, cy + radius, cz + radius, out);
+            return out;
+        },
+        cells() {
+            const result = [];
+            for (const [key, bucket] of cells) {
+                const parts = key.split(":");
+                const x = Number(parts[0]), y = Number(parts[1]), z = Number(parts[2]);
+                result.push({
+                    key,
+                    count: bucket.size,
+                    minX: x * size, minY: y * size, minZ: z * size,
+                    maxX: (x + 1) * size, maxY: (y + 1) * size, maxZ: (z + 1) * size,
+                });
+            }
+            return result;
+        },
+        cellSize() {
+            return size;
+        },
+        clear() {
+            cells.clear();
+            oversized.clear();
+            entries.clear();
+            stamps.clear();
+        },
+    };
+}
+/** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */
+export { aabbIntersects };

package/dist/visibility/visibilitySystem.d.ts

@@ -0,0 +1,90 @@
+import type { Vec3, RenderBounds, BoundsSpec } from "./bounds.js";
+import type { BoundsCache } from "./bounds.js";
+import type { CameraVisibilityContext, CameraKind } from "./camera.js";
+import type { SpatialIndex } from "./spatialIndex.js";
+import type { CullingSettings, ObjectVisibilityOverrides } from "./settings.js";
+import type { OcclusionTester } from "./occlusion.js";
+import type { VisibilityStats } from "./diagnostics.js";
+/**
+ * A scene object the visibility system considers. A normal game object already carries a
+ * position and a version counter, so it becomes cullable automatically — no separate
+ * "cullable" component. Everything else is optional override.
+ */
+export interface Renderable {
+    readonly id: string;
+    readonly position: Vec3;
+    /** Bumps when transform, geometry, bounds, or overrides change — gates bounds/override recompute. */
+    readonly version: number;
+    readonly bounds?: BoundsSpec;
+    readonly overrides?: ObjectVisibilityOverrides;
+    readonly layer?: string;
+    /** Fast-path exemption for UI, skyboxes, debug overlays, camera-attached, marked always-visible. */
+    readonly alwaysVisible?: boolean;
+    /** Asset ids this object needs loaded; feeds the streaming preload/retain sets. */
+    readonly assets?: readonly string[];
+}
+export interface VisibilitySystemOptions {
+    readonly renderables: () => Iterable<Renderable>;
+    readonly cameras: () => readonly CameraVisibilityContext[];
+    readonly settings?: Partial<CullingSettings>;
+    readonly sceneOverrides?: ObjectVisibilityOverrides;
+    readonly globalOverrides?: ObjectVisibilityOverrides;
+    readonly layerOverrides?: (layer: string) => ObjectVisibilityOverrides | undefined;
+    readonly occlusion?: OcclusionTester;
+    /** Injected shared index. Defaults to an internally-owned uniform 3D hash. */
+    readonly index?: SpatialIndex;
+    readonly boundsCache?: BoundsCache;
+    readonly now?: () => number;
+}
+export interface VisibilityResult {
+    /** Objects to submit to the renderer this frame. Valid until the next `update()` (reused set). */
+    readonly visible: ReadonlySet<string>;
+    /** Objects within the preload region — load their assets, whether or not they render. */
+    readonly preload: ReadonlySet<string>;
+    readonly stats: VisibilityStats;
+}
+export interface VisibilityDebugSnapshot {
+    cameras: {
+        id: string;
+        kind: CameraKind;
+        corners: number[];
+        preloadMargin: number;
+    }[];
+    bounds: {
+        id: string;
+        minX: number;
+        minY: number;
+        minZ: number;
+        maxX: number;
+        maxY: number;
+        maxZ: number;
+        visible: boolean;
+    }[];
+    partitions: {
+        key: string;
+        count: number;
+        minX: number;
+        minY: number;
+        minZ: number;
+        maxX: number;
+        maxY: number;
+        maxZ: number;
+    }[];
+    culled: string[];
+    stats: VisibilityStats;
+}
+export interface VisibilitySystem {
+    update(): VisibilityResult;
+    isVisible(id: string): boolean;
+    isPreloaded(id: string): boolean;
+    boundsOf(id: string): RenderBounds | undefined;
+    settings(): CullingSettings;
+    setSettings(patch: Partial<CullingSettings>): void;
+    stats(): VisibilityStats;
+    /** Assets required by the preload set — hand to an AssetStreamingSystem. */
+    requiredAssets(): ReadonlySet<string>;
+    index(): SpatialIndex;
+    debugSnapshot(): VisibilityDebugSnapshot;
+    clear(): void;
+}
+export declare function createVisibilitySystem(options: VisibilitySystemOptions): VisibilitySystem;

package/dist/visibility/visibilitySystem.js

@@ -0,0 +1,257 @@
+import { DEFAULT_BOUNDS, createBoundsCache } from "./bounds.js";
+import { cameraInfluencesStreaming } from "./camera.js";
+import { createFrustum, updateFrustum, dilateFrustum, boundsInFrustum } from "./frustum.js";
+import { culledByDistance } from "./distance.js";
+import { createSpatialIndex } from "./spatialIndex.js";
+import { DEFAULT_CULLING_SETTINGS, mergeCullingSettings, resolveOverrides } from "./settings.js";
+import { noOcclusion } from "./occlusion.js";
+import { createVisibilityStats, resetCullingStats, nowMs } from "./diagnostics.js";
+export function createVisibilitySystem(options) {
+    let settings = mergeCullingSettings(DEFAULT_CULLING_SETTINGS, options.settings ?? {});
+    const occlusion = options.occlusion ?? noOcclusion;
+    const index = options.index ?? createSpatialIndex();
+    const bounds = options.boundsCache ?? createBoundsCache();
+    const clock = options.now ?? nowMs;
+    const records = new Map();
+    const stats = createVisibilityStats();
+    let visible = new Set();
+    let prevVisible = new Set();
+    const preload = new Set();
+    const requiredAssets = new Set();
+    const candidateScratch = [];
+    const consideredStamp = new Map();
+    let consideredCounter = 0;
+    const baseFrustum = createFrustum();
+    const preloadFrustum = createFrustum();
+    const hysteresisFrustum = createFrustum();
+    let updateCounter = 0;
+    function specOf(r, resolved) {
+        return resolved.bounds ?? r.bounds ?? DEFAULT_BOUNDS;
+    }
+    function recordFor(r) {
+        let record = records.get(r.id);
+        if (record !== undefined && record.version === r.version) {
+            record.lastSeen = updateCounter;
+            return record;
+        }
+        const resolved = resolveOverrides(r.overrides, r.layer !== undefined ? options.layerOverrides?.(r.layer) : undefined, options.sceneOverrides, options.globalOverrides);
+        const alwaysVisible = resolved.alwaysVisible || r.alwaysVisible === true;
+        const dynamic = resolved.classification !== "static";
+        if (record === undefined) {
+            record = { version: r.version, resolved, alwaysVisible, dynamic, assets: r.assets, lastSeen: updateCounter };
+            records.set(r.id, record);
+        }
+        else {
+            record.version = r.version;
+            record.resolved = resolved;
+            record.alwaysVisible = alwaysVisible;
+            record.dynamic = dynamic;
+            record.assets = r.assets;
+            record.lastSeen = updateCounter;
+        }
+        return record;
+    }
+    function maintain() {
+        const alwaysVisibleList = [];
+        for (const r of options.renderables()) {
+            const record = recordFor(r);
+            const b = bounds.get(r.id, r.version, specOf(r, record.resolved), r.position);
+            index.insert(r.id, b, record.dynamic);
+            stats.totalObjects += 1;
+            if (record.alwaysVisible)
+                alwaysVisibleList.push(r);
+        }
+        // Prune objects that vanished this frame.
+        for (const [id, record] of records) {
+            if (record.lastSeen === updateCounter)
+                continue;
+            index.remove(id);
+            bounds.delete(id);
+            records.delete(id);
+        }
+        return alwaysVisibleList;
+    }
+    function markConsidered(id) {
+        if (consideredStamp.get(id) === consideredCounter)
+            return false;
+        consideredStamp.set(id, consideredCounter);
+        return true;
+    }
+    function distanceLimits(camera, resolved) {
+        const min = resolved.minRenderDistance ?? settings.defaultMinRenderDistance;
+        let max = resolved.maxRenderDistance ?? settings.defaultMaxRenderDistance;
+        if (camera.maxRenderDistance !== undefined)
+            max = Math.min(max, camera.maxRenderDistance);
+        return { min, max };
+    }
+    function evaluateCamera(camera) {
+        const streaming = cameraInfluencesStreaming(camera);
+        updateFrustum(baseFrustum, camera.view);
+        dilateFrustum(baseFrustum, settings.preloadMargin, preloadFrustum);
+        dilateFrustum(baseFrustum, settings.hysteresis, hysteresisFrustum);
+        const cullingOff = camera.cullingDisabled === true || !settings.enabled;
+        const t0 = clock();
+        index.queryFrustum(preloadFrustum, candidateScratch);
+        stats.spatialQueryMs += clock() - t0;
+        const t1 = clock();
+        for (const id of candidateScratch) {
+            const record = records.get(id);
+            if (record === undefined)
+                continue;
+            const b = bounds.peek(id);
+            if (b === undefined)
+                continue;
+            const fresh = markConsidered(id);
+            if (fresh)
+                stats.consideredForRender += 1;
+            const resolved = record.resolved;
+            const cx = camera.view.position[0], cy = camera.view.position[1], cz = camera.view.position[2];
+            let isVisible;
+            if (cullingOff || record.alwaysVisible || resolved.cullingDisabled) {
+                isVisible = true;
+            }
+            else {
+                const custom = resolved.customVisibility?.(camera);
+                if (custom !== undefined) {
+                    isVisible = custom;
+                }
+                else {
+                    const frustum = prevVisible.has(id) ? hysteresisFrustum : baseFrustum;
+                    if (settings.frustumCulling && !boundsInFrustum(frustum, b)) {
+                        if (fresh)
+                            stats.rejectedByFrustum += 1;
+                        isVisible = false;
+                    }
+                    else {
+                        const limits = distanceLimits(camera, resolved);
+                        if (settings.distanceCulling &&
+                            culledByDistance(cx, cy, cz, b.centerX, b.centerY, b.centerZ, limits.min, limits.max, b.radius, settings.hysteresis)) {
+                            if (fresh)
+                                stats.rejectedByDistance += 1;
+                            isVisible = false;
+                        }
+                        else if (settings.occlusionCulling &&
+                            occlusion.enabled &&
+                            occlusion.isOccluded({ camera: camera.view, bounds: b, occluders: [] })) {
+                            if (fresh)
+                                stats.rejectedByOcclusion += 1;
+                            isVisible = false;
+                        }
+                        else {
+                            isVisible = true;
+                        }
+                    }
+                }
+            }
+            // Preload region: candidates already come from the preload-dilated frustum. Anything
+            // visible, or within the preload region and not distance-culled far past the margin, preloads.
+            const inPreload = isVisible || resolved.pinned || (!cullingOff && withinPreloadDistance(camera, resolved, b));
+            if (inPreload) {
+                preload.add(id);
+                if (streaming && record.assets !== undefined) {
+                    for (const asset of record.assets)
+                        requiredAssets.add(asset);
+                }
+            }
+            if (isVisible)
+                visible.add(id);
+        }
+        stats.cullingMs += clock() - t1;
+    }
+    function withinPreloadDistance(camera, resolved, b) {
+        const limits = distanceLimits(camera, resolved);
+        const max = limits.max === Infinity ? Infinity : limits.max + settings.preloadMargin;
+        return !culledByDistance(camera.view.position[0], camera.view.position[1], camera.view.position[2], b.centerX, b.centerY, b.centerZ, 0, max, b.radius, 0);
+    }
+    function addAlwaysVisible(list) {
+        for (const r of list) {
+            visible.add(r.id);
+            preload.add(r.id);
+            const record = records.get(r.id);
+            if (record?.assets !== undefined) {
+                for (const asset of record.assets)
+                    requiredAssets.add(asset);
+            }
+        }
+    }
+    return {
+        update() {
+            updateCounter += 1;
+            consideredCounter += 1;
+            resetCullingStats(stats);
+            // Swap current → prev, reuse the old prev as the new current (cleared).
+            const swap = prevVisible;
+            prevVisible = visible;
+            visible = swap;
+            visible.clear();
+            preload.clear();
+            requiredAssets.clear();
+            const alwaysVisibleList = maintain();
+            const cameras = options.cameras();
+            for (const camera of cameras)
+                evaluateCamera(camera);
+            addAlwaysVisible(alwaysVisibleList);
+            stats.visible = visible.size;
+            stats.preloaded = preload.size;
+            stats.drawCallsAvoided = Math.max(0, stats.totalObjects - visible.size);
+            return { visible, preload, stats };
+        },
+        isVisible(id) {
+            return visible.has(id);
+        },
+        isPreloaded(id) {
+            return preload.has(id);
+        },
+        boundsOf(id) {
+            return bounds.peek(id);
+        },
+        settings() {
+            return settings;
+        },
+        setSettings(patch) {
+            settings = mergeCullingSettings(settings, patch);
+        },
+        stats() {
+            return stats;
+        },
+        requiredAssets() {
+            return requiredAssets;
+        },
+        index() {
+            return index;
+        },
+        debugSnapshot() {
+            const cameras = options.cameras().map((camera) => {
+                updateFrustum(baseFrustum, camera.view);
+                return {
+                    id: camera.id,
+                    kind: camera.kind ?? "main",
+                    corners: Array.from(baseFrustum.corners),
+                    preloadMargin: settings.preloadMargin,
+                };
+            });
+            const boundsOut = [];
+            const culled = [];
+            for (const id of records.keys()) {
+                const b = bounds.peek(id);
+                if (b === undefined)
+                    continue;
+                const vis = visible.has(id);
+                boundsOut.push({ id, minX: b.minX, minY: b.minY, minZ: b.minZ, maxX: b.maxX, maxY: b.maxY, maxZ: b.maxZ, visible: vis });
+                if (!vis)
+                    culled.push(id);
+            }
+            return { cameras, bounds: boundsOut, partitions: index.cells(), culled, stats };
+        },
+        clear() {
+            index.clear();
+            bounds.clear();
+            records.clear();
+            visible.clear();
+            prevVisible.clear();
+            preload.clear();
+            requiredAssets.clear();
+            consideredStamp.clear();
+        },
+    };
+}

package/dist/world/buildings.d.ts

@@ -92,6 +92,12 @@ export interface BuildingGridConfig {
     floorRange?: readonly [number, number];
 }
 export declare const DEFAULT_BUILDING_CONFIG: BuildingConfig;
+export type BuildingPalette = Record<BuildingPartKind, string>;
+export type BuildingPaletteOverrides = Partial<BuildingPalette>;
+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 function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
 export declare function createBuildingConfig(input?: BuildingConfigInput): BuildingConfig;
 export declare function generateBuilding(input?: BuildingConfigInput): GeneratedBuilding;
 export declare function createBuildingGrid(config: BuildingGridConfig): BuildingLot[];