@jgengine/core 0.8.0 → 0.9.0

package/dist/visibility/frustum.d.ts

@@ -0,0 +1,47 @@
+import type { Vec3, RenderBounds } from "./bounds.js";
+/** 3D perspective camera (the default game camera). */
+export interface PerspectiveView {
+    readonly kind: "perspective";
+    readonly position: Vec3;
+    readonly target: Vec3;
+    readonly up?: Vec3;
+    /** Vertical field of view in degrees. Default 55. */
+    readonly fovDeg?: number;
+    /** Width / height. Default 16 / 9. */
+    readonly aspect?: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+/** 2D / orthographic camera (top-down, side-scroller, minimap). */
+export interface OrthographicView {
+    readonly kind: "orthographic";
+    readonly position: Vec3;
+    readonly target: Vec3;
+    readonly up?: Vec3;
+    readonly halfWidth: number;
+    readonly halfHeight: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+export type CameraView = PerspectiveView | OrthographicView;
+export interface Frustum {
+    /** 6 inward-facing planes, packed [nx,ny,nz,d] × 6. A point p is inside plane i when nx·px+ny·py+nz·pz+d ≥ 0. */
+    readonly planes: Float64Array;
+    /** 8 world corners, packed xyz × [ntl,ntr,nbl,nbr,ftl,ftr,fbl,fbr]. */
+    readonly corners: Float64Array;
+    minX: number;
+    minY: number;
+    minZ: number;
+    maxX: number;
+    maxY: number;
+    maxZ: number;
+}
+export declare function createFrustum(): Frustum;
+export declare function updateFrustum(out: Frustum, view: CameraView): Frustum;
+/** Conservative AABB-vs-frustum: never a false negative (may keep a corner-case that is truly outside). */
+export declare function aabbInFrustum(f: Frustum, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): boolean;
+export declare function sphereInFrustum(f: Frustum, cx: number, cy: number, cz: number, radius: number): boolean;
+/** Sphere broad-phase reject, then the tight AABB test. Both conservative. */
+export declare function boundsInFrustum(f: Frustum, b: RenderBounds): boolean;
+/** Push every plane outward by `margin` (unit normals ⇒ d += margin) to form a preload/hysteresis region. */
+export declare function dilateFrustum(src: Frustum, margin: number, out: Frustum): Frustum;

package/dist/visibility/frustum.js

@@ -0,0 +1,186 @@
+const WORLD_UP = [0, 1, 0];
+const ALT_UP = [1, 0, 0];
+export function createFrustum() {
+    return {
+        planes: new Float64Array(24),
+        corners: new Float64Array(24),
+        minX: 0,
+        minY: 0,
+        minZ: 0,
+        maxX: 0,
+        maxY: 0,
+        maxZ: 0,
+    };
+}
+function setCorner(corners, i, x, y, z) {
+    corners[i * 3] = x;
+    corners[i * 3 + 1] = y;
+    corners[i * 3 + 2] = z;
+}
+function planeFromCorners(planes, slot, corners, a, b, c, centroidX, centroidY, centroidZ) {
+    const ax = corners[a * 3], ay = corners[a * 3 + 1], az = corners[a * 3 + 2];
+    const bx = corners[b * 3], by = corners[b * 3 + 1], bz = corners[b * 3 + 2];
+    const cx = corners[c * 3], cy = corners[c * 3 + 1], cz = corners[c * 3 + 2];
+    const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+    const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
+    let nx = e1y * e2z - e1z * e2y;
+    let ny = e1z * e2x - e1x * e2z;
+    let nz = e1x * e2y - e1y * e2x;
+    const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+    nx /= len;
+    ny /= len;
+    nz /= len;
+    let d = -(nx * ax + ny * ay + nz * az);
+    // Orient inward: the centroid of all 8 corners is guaranteed interior.
+    if (nx * centroidX + ny * centroidY + nz * centroidZ + d < 0) {
+        nx = -nx;
+        ny = -ny;
+        nz = -nz;
+        d = -d;
+    }
+    planes[slot * 4] = nx;
+    planes[slot * 4 + 1] = ny;
+    planes[slot * 4 + 2] = nz;
+    planes[slot * 4 + 3] = d;
+}
+export function updateFrustum(out, view) {
+    const { position, target } = view;
+    let fx = target[0] - position[0];
+    let fy = target[1] - position[1];
+    let fz = target[2] - position[2];
+    const fLen = Math.sqrt(fx * fx + fy * fy + fz * fz) || 1;
+    fx /= fLen;
+    fy /= fLen;
+    fz /= fLen;
+    const up = view.up ?? WORLD_UP;
+    let rx = fy * up[2] - fz * up[1];
+    let ry = fz * up[0] - fx * up[2];
+    let rz = fx * up[1] - fy * up[0];
+    let rLen = Math.sqrt(rx * rx + ry * ry + rz * rz);
+    if (rLen < 1e-8) {
+        rx = fy * ALT_UP[2] - fz * ALT_UP[1];
+        ry = fz * ALT_UP[0] - fx * ALT_UP[2];
+        rz = fx * ALT_UP[1] - fy * ALT_UP[0];
+        rLen = Math.sqrt(rx * rx + ry * ry + rz * rz) || 1;
+    }
+    rx /= rLen;
+    ry /= rLen;
+    rz /= rLen;
+    const ux = ry * fz - rz * fy;
+    const uy = rz * fx - rx * fz;
+    const uz = rx * fy - ry * fx;
+    const near = view.near ?? 0.1;
+    const far = view.far ?? 1000;
+    let halfHNear, halfWNear, halfHFar, halfWFar;
+    if (view.kind === "perspective") {
+        const fov = ((view.fovDeg ?? 55) * Math.PI) / 180;
+        const aspect = view.aspect ?? 16 / 9;
+        halfHNear = Math.tan(fov / 2) * near;
+        halfWNear = halfHNear * aspect;
+        halfHFar = Math.tan(fov / 2) * far;
+        halfWFar = halfHFar * aspect;
+    }
+    else {
+        halfHNear = view.halfHeight;
+        halfWNear = view.halfWidth;
+        halfHFar = view.halfHeight;
+        halfWFar = view.halfWidth;
+    }
+    const corners = out.corners;
+    const ncx = position[0] + fx * near, ncy = position[1] + fy * near, ncz = position[2] + fz * near;
+    const fcx = position[0] + fx * far, fcy = position[1] + fy * far, fcz = position[2] + fz * far;
+    // [ntl,ntr,nbl,nbr,ftl,ftr,fbl,fbr]
+    setCorner(corners, 0, ncx + ux * halfHNear - rx * halfWNear, ncy + uy * halfHNear - ry * halfWNear, ncz + uz * halfHNear - rz * halfWNear);
+    setCorner(corners, 1, ncx + ux * halfHNear + rx * halfWNear, ncy + uy * halfHNear + ry * halfWNear, ncz + uz * halfHNear + rz * halfWNear);
+    setCorner(corners, 2, ncx - ux * halfHNear - rx * halfWNear, ncy - uy * halfHNear - ry * halfWNear, ncz - uz * halfHNear - rz * halfWNear);
+    setCorner(corners, 3, ncx - ux * halfHNear + rx * halfWNear, ncy - uy * halfHNear + ry * halfWNear, ncz - uz * halfHNear + rz * halfWNear);
+    setCorner(corners, 4, fcx + ux * halfHFar - rx * halfWFar, fcy + uy * halfHFar - ry * halfWFar, fcz + uz * halfHFar - rz * halfWFar);
+    setCorner(corners, 5, fcx + ux * halfHFar + rx * halfWFar, fcy + uy * halfHFar + ry * halfWFar, fcz + uz * halfHFar + rz * halfWFar);
+    setCorner(corners, 6, fcx - ux * halfHFar - rx * halfWFar, fcy - uy * halfHFar - ry * halfWFar, fcz - uz * halfHFar - rz * halfWFar);
+    setCorner(corners, 7, fcx - ux * halfHFar + rx * halfWFar, fcy - uy * halfHFar + ry * halfWFar, fcz - uz * halfHFar + rz * halfWFar);
+    let cX = 0, cY = 0, cZ = 0;
+    let minX = Infinity, minY = Infinity, minZ = Infinity;
+    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    for (let i = 0; i < 8; i += 1) {
+        const x = corners[i * 3], y = corners[i * 3 + 1], z = corners[i * 3 + 2];
+        cX += x;
+        cY += y;
+        cZ += z;
+        if (x < minX)
+            minX = x;
+        if (y < minY)
+            minY = y;
+        if (z < minZ)
+            minZ = z;
+        if (x > maxX)
+            maxX = x;
+        if (y > maxY)
+            maxY = y;
+        if (z > maxZ)
+            maxZ = z;
+    }
+    cX /= 8;
+    cY /= 8;
+    cZ /= 8;
+    out.minX = minX;
+    out.minY = minY;
+    out.minZ = minZ;
+    out.maxX = maxX;
+    out.maxY = maxY;
+    out.maxZ = maxZ;
+    const planes = out.planes;
+    planeFromCorners(planes, 0, corners, 0, 1, 2, cX, cY, cZ); // near
+    planeFromCorners(planes, 1, corners, 4, 6, 5, cX, cY, cZ); // far
+    planeFromCorners(planes, 2, corners, 0, 2, 4, cX, cY, cZ); // left
+    planeFromCorners(planes, 3, corners, 1, 5, 3, cX, cY, cZ); // right
+    planeFromCorners(planes, 4, corners, 0, 4, 1, cX, cY, cZ); // top
+    planeFromCorners(planes, 5, corners, 2, 3, 6, cX, cY, cZ); // bottom
+    return out;
+}
+/** Conservative AABB-vs-frustum: never a false negative (may keep a corner-case that is truly outside). */
+export function aabbInFrustum(f, minX, minY, minZ, maxX, maxY, maxZ) {
+    const planes = f.planes;
+    for (let i = 0; i < 6; i += 1) {
+        const nx = planes[i * 4], ny = planes[i * 4 + 1], nz = planes[i * 4 + 2], d = planes[i * 4 + 3];
+        const px = nx >= 0 ? maxX : minX;
+        const py = ny >= 0 ? maxY : minY;
+        const pz = nz >= 0 ? maxZ : minZ;
+        if (nx * px + ny * py + nz * pz + d < 0)
+            return false;
+    }
+    return true;
+}
+export function sphereInFrustum(f, cx, cy, cz, radius) {
+    const planes = f.planes;
+    for (let i = 0; i < 6; i += 1) {
+        const nx = planes[i * 4], ny = planes[i * 4 + 1], nz = planes[i * 4 + 2], d = planes[i * 4 + 3];
+        if (nx * cx + ny * cy + nz * cz + d < -radius)
+            return false;
+    }
+    return true;
+}
+/** Sphere broad-phase reject, then the tight AABB test. Both conservative. */
+export function boundsInFrustum(f, b) {
+    if (!sphereInFrustum(f, b.centerX, b.centerY, b.centerZ, b.radius))
+        return false;
+    return aabbInFrustum(f, b.minX, b.minY, b.minZ, b.maxX, b.maxY, b.maxZ);
+}
+/** Push every plane outward by `margin` (unit normals ⇒ d += margin) to form a preload/hysteresis region. */
+export function dilateFrustum(src, margin, out) {
+    const sp = src.planes;
+    const op = out.planes;
+    for (let i = 0; i < 6; i += 1) {
+        op[i * 4] = sp[i * 4];
+        op[i * 4 + 1] = sp[i * 4 + 1];
+        op[i * 4 + 2] = sp[i * 4 + 2];
+        op[i * 4 + 3] = sp[i * 4 + 3] + margin;
+    }
+    out.corners.set(src.corners);
+    out.minX = src.minX - margin;
+    out.minY = src.minY - margin;
+    out.minZ = src.minZ - margin;
+    out.maxX = src.maxX + margin;
+    out.maxY = src.maxY + margin;
+    out.maxZ = src.maxZ + margin;
+    return out;
+}

package/dist/visibility/occlusion.d.ts

@@ -0,0 +1,36 @@
+import type { RenderBounds } from "./bounds.js";
+import type { CameraView } from "./frustum.js";
+export interface OcclusionInput {
+    readonly camera: CameraView;
+    readonly bounds: RenderBounds;
+    /** Candidate blockers already known to be in front of the object (nearer to the camera). */
+    readonly occluders: Iterable<RenderBounds>;
+}
+/**
+ * Optional occlusion stage. Kept behind a feature flag and disabled by default: a fragile
+ * occlusion test that wrongly hides a visible object is worse than no occlusion at all.
+ * Any tester here MUST be conservative — it may return false (visible) for a truly hidden
+ * object, but must never return true (hidden) for an object the player can actually see.
+ */
+export interface OcclusionTester {
+    readonly enabled: boolean;
+    isOccluded(input: OcclusionInput): boolean;
+}
+/** The safe default: never occludes anything. */
+export declare const noOcclusion: OcclusionTester;
+export interface AxisOccluderOptions {
+    enabled?: boolean;
+    /** An occluder is only trusted when its bounding sphere is at least this large (world units). Default 8. */
+    minOccluderRadius?: number;
+}
+/**
+ * A deliberately conservative bounding-volume occlusion tester. It hides an object only when a
+ * single large occluder's AABB fully contains the object's AABB on every axis AND sits strictly
+ * nearer the camera on the dominant view axis — the object is then provably in the occluder's
+ * shadow. Full containment (not just the two perpendicular axes) makes it stricter than it needs
+ * to be, which is the safe direction: it never hides a partially-visible object.
+ *
+ * This is the architecture/interface for occlusion, not a production hierarchical-Z implementation.
+ * It stays disabled by default; enable only where the scene has genuine large blockers.
+ */
+export declare function createAxisAlignedOcclusionTester(options?: AxisOccluderOptions): OcclusionTester;

package/dist/visibility/occlusion.js

@@ -0,0 +1,45 @@
+/** The safe default: never occludes anything. */
+export const noOcclusion = {
+    enabled: false,
+    isOccluded: () => false,
+};
+function screenlessContains(outer, inner) {
+    return (outer.minX <= inner.minX && outer.maxX >= inner.maxX &&
+        outer.minZ <= inner.minZ && outer.maxZ >= inner.maxZ &&
+        outer.minY <= inner.minY && outer.maxY >= inner.maxY);
+}
+/**
+ * A deliberately conservative bounding-volume occlusion tester. It hides an object only when a
+ * single large occluder's AABB fully contains the object's AABB on every axis AND sits strictly
+ * nearer the camera on the dominant view axis — the object is then provably in the occluder's
+ * shadow. Full containment (not just the two perpendicular axes) makes it stricter than it needs
+ * to be, which is the safe direction: it never hides a partially-visible object.
+ *
+ * This is the architecture/interface for occlusion, not a production hierarchical-Z implementation.
+ * It stays disabled by default; enable only where the scene has genuine large blockers.
+ */
+export function createAxisAlignedOcclusionTester(options = {}) {
+    const minRadius = options.minOccluderRadius ?? 8;
+    return {
+        enabled: options.enabled ?? false,
+        isOccluded({ camera, bounds, occluders }) {
+            const dirX = camera.target[0] - camera.position[0];
+            const dirZ = camera.target[2] - camera.position[2];
+            const horizontal = Math.abs(dirX) >= Math.abs(dirZ);
+            const objAxis = horizontal ? camera.position[0] : camera.position[2];
+            const objDepth = horizontal ? bounds.minX : bounds.minZ;
+            for (const occ of occluders) {
+                if (occ.radius < minRadius)
+                    continue;
+                if (!screenlessContains(occ, bounds))
+                    continue;
+                const occNear = horizontal
+                    ? Math.abs(occ.maxX - objAxis) < Math.abs(objDepth - objAxis)
+                    : Math.abs(occ.maxZ - objAxis) < Math.abs(objDepth - objAxis);
+                if (occNear)
+                    return true;
+            }
+            return false;
+        },
+    };
+}

package/dist/visibility/settings.d.ts

@@ -0,0 +1,75 @@
+import type { BoundsSpec } from "./bounds.js";
+import type { CameraVisibilityContext } from "./camera.js";
+/**
+ * Global render-culling behavior. Defaults favor correctness and visual stability over
+ * aggressive rejection: a generous preload margin, hysteresis, and a large default render
+ * distance so upgrading the engine never makes an existing game's objects vanish.
+ */
+export interface CullingSettings {
+    readonly enabled: boolean;
+    readonly frustumCulling: boolean;
+    readonly distanceCulling: boolean;
+    /** Occlusion culling is opt-in and off until proven reliable for the renderer. */
+    readonly occlusionCulling: boolean;
+    readonly defaultMinRenderDistance: number;
+    readonly defaultMaxRenderDistance: number;
+    /** World units the preload region extends beyond the visible frustum, hiding pop-in. */
+    readonly preloadMargin: number;
+    /** World-unit band added when re-testing a previously visible object, preventing boundary flicker. */
+    readonly hysteresis: number;
+}
+export declare const DEFAULT_CULLING_SETTINGS: CullingSettings;
+export interface StreamingSettings {
+    readonly enabled: boolean;
+    /** Extra world units around the camera whose assets are preloaded ahead of visibility. */
+    readonly preloadMargin: number;
+    /** Seconds an asset must stay outside the active area before it is eligible for unload. */
+    readonly unloadGraceSeconds: number;
+    readonly maxLoadsPerFrame: number;
+    readonly maxUnloadsPerFrame: number;
+    /** Assets at or below this byte size are kept resident once loaded (small shared assets). */
+    readonly keepResidentBytes: number;
+}
+export declare const DEFAULT_STREAMING_SETTINGS: StreamingSettings;
+/**
+ * Per-object visibility/streaming overrides. Also the shape used at the layer, scene, and
+ * global-override levels — resolution merges object → layer → scene → global-override, so a
+ * game can, say, mark a whole "hud" layer alwaysVisible without touching each object.
+ */
+export interface ObjectVisibilityOverrides {
+    /** Bypass all render culling — always submitted (UI, skybox, camera-attached, marked always-visible). */
+    readonly alwaysVisible?: boolean;
+    /** Never auto-unload this object's assets. */
+    readonly neverUnload?: boolean;
+    readonly minRenderDistance?: number;
+    readonly maxRenderDistance?: number;
+    readonly preloadMargin?: number;
+    readonly cullingDisabled?: boolean;
+    readonly streamingDisabled?: boolean;
+    readonly classification?: "static" | "dynamic";
+    readonly bounds?: BoundsSpec;
+    /**
+     * Final say on render visibility. Return true/false to force, or undefined to defer to the
+     * standard frustum+distance+occlusion pipeline. Evaluated per relevant camera.
+     */
+    readonly customVisibility?: (camera: CameraVisibilityContext) => boolean | undefined;
+    /** Pin the object's assets resident regardless of distance. */
+    readonly pinned?: boolean;
+}
+export interface ResolvedOverrides {
+    alwaysVisible: boolean;
+    neverUnload: boolean;
+    minRenderDistance: number | undefined;
+    maxRenderDistance: number | undefined;
+    preloadMargin: number | undefined;
+    cullingDisabled: boolean;
+    streamingDisabled: boolean;
+    classification: "static" | "dynamic" | undefined;
+    bounds: BoundsSpec | undefined;
+    customVisibility: ((camera: CameraVisibilityContext) => boolean | undefined) | undefined;
+    pinned: boolean;
+}
+/** Merge override layers by precedence: earlier arguments win. Pass object, then layer, then scene, then global. */
+export declare function resolveOverrides(...layers: readonly (ObjectVisibilityOverrides | undefined)[]): ResolvedOverrides;
+export declare function mergeCullingSettings(base: CullingSettings, patch: Partial<CullingSettings>): CullingSettings;
+export declare function mergeStreamingSettings(base: StreamingSettings, patch: Partial<StreamingSettings>): StreamingSettings;

package/dist/visibility/settings.js

@@ -0,0 +1,49 @@
+export const DEFAULT_CULLING_SETTINGS = {
+    enabled: true,
+    frustumCulling: true,
+    distanceCulling: true,
+    occlusionCulling: false,
+    defaultMinRenderDistance: 0,
+    defaultMaxRenderDistance: Infinity,
+    preloadMargin: 24,
+    hysteresis: 2,
+};
+export const DEFAULT_STREAMING_SETTINGS = {
+    enabled: true,
+    preloadMargin: 32,
+    unloadGraceSeconds: 10,
+    maxLoadsPerFrame: 4,
+    maxUnloadsPerFrame: 2,
+    keepResidentBytes: 64 * 1024,
+};
+const EMPTY = {};
+/** Merge override layers by precedence: earlier arguments win. Pass object, then layer, then scene, then global. */
+export function resolveOverrides(...layers) {
+    const pick = (key) => {
+        for (const layer of layers) {
+            const value = (layer ?? EMPTY)[key];
+            if (value !== undefined)
+                return value;
+        }
+        return undefined;
+    };
+    return {
+        alwaysVisible: pick("alwaysVisible") ?? false,
+        neverUnload: pick("neverUnload") ?? false,
+        minRenderDistance: pick("minRenderDistance"),
+        maxRenderDistance: pick("maxRenderDistance"),
+        preloadMargin: pick("preloadMargin"),
+        cullingDisabled: pick("cullingDisabled") ?? false,
+        streamingDisabled: pick("streamingDisabled") ?? false,
+        classification: pick("classification"),
+        bounds: pick("bounds"),
+        customVisibility: pick("customVisibility"),
+        pinned: pick("pinned") ?? false,
+    };
+}
+export function mergeCullingSettings(base, patch) {
+    return { ...base, ...patch };
+}
+export function mergeStreamingSettings(base, patch) {
+    return { ...base, ...patch };
+}

package/dist/visibility/simulationCulling.d.ts

@@ -0,0 +1,34 @@
+import type { LodBand } 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
+ * tick. It is disabled by default and never throttles a protected entity — physics-critical,
+ * networking-critical, audio-critical, scripted, or explicitly-active entities always update.
+ * Gameplay correctness must never depend on an entity being on-screen, so opt in only where
+ * skipping updates is provably safe.
+ */
+export interface SimulationCullingOptions {
+    /** Off by default. */
+    readonly enabled?: boolean;
+    /** Distance bands → update interval (seconds). Nearer bands update every tick; far bands throttle. */
+    readonly bands?: readonly LodBand[];
+    /** Interval for entities beyond the last band. null = never throttle (still update). Default null. */
+    readonly beyondInterval?: number | null;
+    /** Return true for entities that must never be throttled (physics/net/audio/scripted/active). */
+    readonly isProtected?: (id: string) => boolean;
+}
+export interface SimulationDecision {
+    /** Whether the entity should run its update this tick. */
+    update: boolean;
+    /** Seconds of accumulated time delivered when `update` is true (for catch-up integration). */
+    elapsed: number;
+}
+export interface SimulationCuller {
+    enabled(): boolean;
+    setEnabled(value: boolean): void;
+    /** Decide whether `id` at `distance` from the nearest camera updates this tick. */
+    step(id: string, distance: number, dt: number): SimulationDecision;
+    forget(id: string): void;
+    clear(): void;
+}
+export declare function createSimulationCuller(options?: SimulationCullingOptions): SimulationCuller;

package/dist/visibility/simulationCulling.js

@@ -0,0 +1,36 @@
+import { createLodScheduler } from "../world/lod.js";
+const DEFAULT_BANDS = [
+    { maxDistance: 40, interval: 0 },
+    { maxDistance: 90, interval: 0.1 },
+    { maxDistance: 160, interval: 0.25 },
+];
+export function createSimulationCuller(options = {}) {
+    let enabled = options.enabled ?? false;
+    const isProtected = options.isProtected;
+    const scheduler = createLodScheduler({
+        bands: options.bands ?? DEFAULT_BANDS,
+        beyondInterval: options.beyondInterval ?? null,
+        stagger: true,
+    });
+    return {
+        enabled() {
+            return enabled;
+        },
+        setEnabled(value) {
+            enabled = value;
+        },
+        step(id, distance, dt) {
+            if (!enabled || (isProtected !== undefined && isProtected(id))) {
+                return { update: true, elapsed: dt };
+            }
+            const elapsed = scheduler.step(id, distance, dt);
+            return elapsed > 0 ? { update: true, elapsed } : { update: false, elapsed: 0 };
+        },
+        forget(id) {
+            scheduler.remove(id);
+        },
+        clear() {
+            scheduler.clear();
+        },
+    };
+}

package/dist/visibility/spatialIndex.d.ts

@@ -0,0 +1,45 @@
+import type { RenderBounds } from "./bounds.js";
+import { aabbIntersects } from "./bounds.js";
+import type { Frustum } from "./frustum.js";
+export interface SpatialIndexOptions {
+    /** Grid cell size in world units. Default 16. Objects are hashed into every cell their AABB overlaps. */
+    readonly cellSize?: number;
+    /**
+     * An object whose AABB spans more cells than this on any axis is parked in an "oversized"
+     * bucket that every query visits, rather than smearing across the grid. Default 6.
+     */
+    readonly maxCellSpan?: number;
+}
+/**
+ * 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
+ * every overlapping cell; a moving object only rewrites the cells that actually changed.
+ * Static objects are inserted once and never touched again. Oversized objects (huge terrain
+ * chunks, world bounds) are held separately so they are always considered.
+ */
+export interface SpatialIndex {
+    insert(id: string, bounds: RenderBounds, dynamic?: boolean): void;
+    update(id: string, bounds: RenderBounds): void;
+    remove(id: string): void;
+    has(id: string): boolean;
+    size(): number;
+    /** Collect ids whose cells the frustum's world-AABB touches (broad phase). Reuses `out`. */
+    queryFrustum(frustum: Frustum, out: string[]): string[];
+    queryBox(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, out: string[]): string[];
+    querySphere(cx: number, cy: number, cz: number, radius: number, out: string[]): string[];
+    cells(): {
+        key: string;
+        count: number;
+        minX: number;
+        minY: number;
+        minZ: number;
+        maxX: number;
+        maxY: number;
+        maxZ: number;
+    }[];
+    cellSize(): number;
+    clear(): void;
+}
+export declare function createSpatialIndex(options?: SpatialIndexOptions): SpatialIndex;
+/** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */
+export { aabbIntersects };