@jgengine/core 0.8.0 → 0.10.0

package/dist/visibility/assetStreaming.js

@@ -0,0 +1,201 @@
+import { DEFAULT_STREAMING_SETTINGS, mergeStreamingSettings } from "./settings.js";
+import { nowMs } from "./diagnostics.js";
+export function createAssetStreamingSystem(options) {
+    const settings = mergeStreamingSettings(DEFAULT_STREAMING_SETTINGS, options.settings ?? {});
+    const clock = options.now ?? nowMs;
+    const records = new Map();
+    const queued = new Set();
+    const signals = new Map();
+    const inFlight = new Set();
+    let unloadedTotal = 0;
+    let cancelledTotal = 0;
+    function ensure(id) {
+        let record = records.get(id);
+        if (record === undefined) {
+            record = { id, state: "unloaded", bytes: 0, priority: 0, refCount: 0, pinned: false, lastActiveMs: clock(), value: undefined };
+            records.set(id, record);
+        }
+        return record;
+    }
+    function enqueue(record, priority) {
+        if (record.state === "loaded" || record.state === "loading") {
+            record.priority = Math.max(record.priority, priority);
+            return;
+        }
+        record.state = "queued";
+        record.priority = Math.max(record.priority, priority);
+        queued.add(record.id);
+    }
+    function startLoad(record) {
+        queued.delete(record.id);
+        record.state = "loading";
+        const signal = { cancelled: false };
+        signals.set(record.id, signal);
+        const promise = options
+            .load(record.id, signal)
+            .then((result) => {
+            signals.delete(record.id);
+            if (signal.cancelled || !records.has(record.id)) {
+                record.state = "unloaded";
+                return;
+            }
+            record.state = "loaded";
+            record.bytes = result.bytes ?? 0;
+            record.value = result.value;
+            record.lastActiveMs = clock();
+        })
+            .catch(() => {
+            signals.delete(record.id);
+            if (!signal.cancelled)
+                record.state = "error";
+        })
+            .finally(() => {
+            inFlight.delete(promise);
+        });
+        inFlight.add(promise);
+    }
+    function evictable(record, now) {
+        if (record.state !== "loaded")
+            return false;
+        if (record.pinned || record.refCount > 0)
+            return false;
+        if (record.bytes > 0 && record.bytes <= settings.keepResidentBytes)
+            return false;
+        return now - record.lastActiveMs >= settings.unloadGraceSeconds * 1000;
+    }
+    return {
+        request(assetId, priority = 0) {
+            const record = ensure(assetId);
+            record.lastActiveMs = clock();
+            enqueue(record, priority);
+        },
+        retain(assetId) {
+            ensure(assetId).refCount += 1;
+        },
+        release(assetId) {
+            const record = records.get(assetId);
+            if (record !== undefined && record.refCount > 0)
+                record.refCount -= 1;
+        },
+        pin(assetId) {
+            ensure(assetId).pinned = true;
+        },
+        unpin(assetId) {
+            const record = records.get(assetId);
+            if (record !== undefined)
+                record.pinned = false;
+        },
+        markActive(assetId) {
+            const record = records.get(assetId);
+            if (record !== undefined)
+                record.lastActiveMs = clock();
+        },
+        tick() {
+            const now = clock();
+            if (queued.size > 0) {
+                const pending = [];
+                for (const id of queued) {
+                    const record = records.get(id);
+                    if (record !== undefined)
+                        pending.push(record);
+                }
+                pending.sort((a, b) => b.priority - a.priority);
+                const budget = Math.min(settings.maxLoadsPerFrame, pending.length);
+                for (let i = 0; i < budget; i += 1)
+                    startLoad(pending[i]);
+            }
+            let unloads = 0;
+            for (const record of records.values()) {
+                if (unloads >= settings.maxUnloadsPerFrame)
+                    break;
+                if (!evictable(record, now))
+                    continue;
+                options.unload?.(record.id);
+                record.state = "unloaded";
+                record.bytes = 0;
+                record.value = undefined;
+                unloadedTotal += 1;
+                unloads += 1;
+            }
+        },
+        cancel(assetId) {
+            if (queued.delete(assetId)) {
+                const record = records.get(assetId);
+                if (record !== undefined)
+                    record.state = "unloaded";
+                cancelledTotal += 1;
+                return;
+            }
+            const signal = signals.get(assetId);
+            if (signal !== undefined) {
+                signal.cancelled = true;
+                const record = records.get(assetId);
+                if (record !== undefined)
+                    record.state = "unloaded";
+                cancelledTotal += 1;
+            }
+        },
+        stateOf(assetId) {
+            return records.get(assetId)?.state;
+        },
+        isLoaded(assetId) {
+            return records.get(assetId)?.state === "loaded";
+        },
+        record(assetId) {
+            return records.get(assetId);
+        },
+        stats() {
+            let queuedCount = 0, loading = 0, loaded = 0, errored = 0, bytes = 0;
+            for (const record of records.values()) {
+                switch (record.state) {
+                    case "queued":
+                        queuedCount += 1;
+                        break;
+                    case "loading":
+                        loading += 1;
+                        break;
+                    case "loaded":
+                        loaded += 1;
+                        bytes += record.bytes;
+                        break;
+                    case "error":
+                        errored += 1;
+                        break;
+                }
+            }
+            return {
+                queued: queuedCount,
+                loading,
+                loaded,
+                unloaded: unloadedTotal,
+                errored,
+                inFlight: inFlight.size,
+                cancelled: cancelledTotal,
+                bytes,
+            };
+        },
+        applyTo(stats) {
+            const s = this.stats();
+            stats.assetsQueued = s.queued;
+            stats.assetsLoading = s.loading;
+            stats.assetsLoaded = s.loaded;
+            stats.assetsUnloaded = s.unloaded;
+            stats.streamedBytes = s.bytes;
+        },
+        async settle() {
+            while (inFlight.size > 0) {
+                await Promise.all(Array.from(inFlight));
+            }
+        },
+        clear() {
+            for (const signal of signals.values())
+                signal.cancelled = true;
+            records.clear();
+            queued.clear();
+            signals.clear();
+            inFlight.clear();
+            unloadedTotal = 0;
+            cancelledTotal = 0;
+        },
+    };
+}

package/dist/visibility/bounds.d.ts

@@ -0,0 +1,66 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+export type Vec3 = EntityPosition;
+/**
+ * World-space bounds a culler tests against. Kept as flat scalars (not tuples) so the
+ * hot culling path reads them without allocating. Carries both a bounding sphere (cheap
+ * broad reject) and a tight AABB (precise reject) — the standard "engine bounds" the
+ * frustum, distance, and spatial-index tests all consume.
+ */
+export interface RenderBounds {
+    centerX: number;
+    centerY: number;
+    centerZ: number;
+    radius: number;
+    minX: number;
+    minY: number;
+    minZ: number;
+    maxX: number;
+    maxY: number;
+    maxZ: number;
+}
+/**
+ * How a renderable declares its extent. AABB, bounding sphere, and 2D rectangle cover the
+ * common cases; `point` is the degenerate zero-size default for objects that never override.
+ * `offset` shifts the volume from the object origin (e.g. a tall model whose pivot is at its feet).
+ */
+export type BoundsSpec = {
+    readonly kind: "sphere";
+    readonly radius: number;
+    readonly offset?: Vec3;
+} | {
+    readonly kind: "aabb";
+    readonly half: Vec3;
+    readonly offset?: Vec3;
+} | {
+    readonly kind: "rect";
+    readonly halfWidth: number;
+    readonly halfDepth: number;
+    readonly halfHeight?: number;
+    readonly offset?: Vec3;
+} | {
+    readonly kind: "point";
+};
+/** Conservative default: a unit sphere. Objects without explicit bounds cull as a small volume, never a point. */
+export declare const DEFAULT_BOUNDS: BoundsSpec;
+export declare function createRenderBounds(): RenderBounds;
+/** Resolve a spec + world position into concrete bounds. Writes into `out` when supplied (no allocation). */
+export declare function resolveBounds(spec: BoundsSpec, position: Vec3, out?: RenderBounds): RenderBounds;
+export declare function expandRenderBounds(bounds: RenderBounds, margin: number, out?: RenderBounds): RenderBounds;
+export declare function aabbIntersects(aMinX: number, aMinY: number, aMinZ: number, aMaxX: number, aMaxY: number, aMaxZ: number, bMinX: number, bMinY: number, bMinZ: number, bMaxX: number, bMaxY: number, bMaxZ: number): boolean;
+export declare function boundsIntersect(a: RenderBounds, b: RenderBounds): boolean;
+/**
+ * BoundsSystem: caches resolved bounds per object and recomputes only when the caller's
+ * version advances — i.e. when a transform, geometry, or the bounds spec itself changed.
+ * The cached `RenderBounds` object is reused across recomputes, so a steady-state frame
+ * that touches thousands of objects performs zero bounds allocations.
+ */
+export interface BoundsCache {
+    get(id: string, version: number, spec: BoundsSpec, position: Vec3): RenderBounds;
+    peek(id: string): RenderBounds | undefined;
+    invalidate(id: string): void;
+    delete(id: string): void;
+    clear(): void;
+    size(): number;
+    recomputes(): number;
+}
+export declare function createBoundsCache(): BoundsCache;

package/dist/visibility/bounds.js

@@ -0,0 +1,113 @@
+/** Conservative default: a unit sphere. Objects without explicit bounds cull as a small volume, never a point. */
+export const DEFAULT_BOUNDS = { kind: "sphere", radius: 1 };
+export function createRenderBounds() {
+    return {
+        centerX: 0,
+        centerY: 0,
+        centerZ: 0,
+        radius: 0,
+        minX: 0,
+        minY: 0,
+        minZ: 0,
+        maxX: 0,
+        maxY: 0,
+        maxZ: 0,
+    };
+}
+function fillBounds(out, cx, cy, cz, hx, hy, hz) {
+    out.centerX = cx;
+    out.centerY = cy;
+    out.centerZ = cz;
+    out.minX = cx - hx;
+    out.minY = cy - hy;
+    out.minZ = cz - hz;
+    out.maxX = cx + hx;
+    out.maxY = cy + hy;
+    out.maxZ = cz + hz;
+    out.radius = Math.sqrt(hx * hx + hy * hy + hz * hz);
+    return out;
+}
+/** Resolve a spec + world position into concrete bounds. Writes into `out` when supplied (no allocation). */
+export function resolveBounds(spec, position, out = createRenderBounds()) {
+    if (spec.kind === "point") {
+        return fillBounds(out, position[0], position[1], position[2], 0, 0, 0);
+    }
+    const offset = spec.offset;
+    const cx = position[0] + (offset?.[0] ?? 0);
+    const cy = position[1] + (offset?.[1] ?? 0);
+    const cz = position[2] + (offset?.[2] ?? 0);
+    switch (spec.kind) {
+        case "sphere": {
+            const r = spec.radius;
+            fillBounds(out, cx, cy, cz, r, r, r);
+            out.radius = r;
+            return out;
+        }
+        case "aabb":
+            return fillBounds(out, cx, cy, cz, spec.half[0], spec.half[1], spec.half[2]);
+        case "rect":
+            return fillBounds(out, cx, cy, cz, spec.halfWidth, spec.halfHeight ?? 0, spec.halfDepth);
+    }
+}
+export function expandRenderBounds(bounds, margin, out = createRenderBounds()) {
+    out.centerX = bounds.centerX;
+    out.centerY = bounds.centerY;
+    out.centerZ = bounds.centerZ;
+    out.radius = bounds.radius + margin;
+    out.minX = bounds.minX - margin;
+    out.minY = bounds.minY - margin;
+    out.minZ = bounds.minZ - margin;
+    out.maxX = bounds.maxX + margin;
+    out.maxY = bounds.maxY + margin;
+    out.maxZ = bounds.maxZ + margin;
+    return out;
+}
+export function aabbIntersects(aMinX, aMinY, aMinZ, aMaxX, aMaxY, aMaxZ, bMinX, bMinY, bMinZ, bMaxX, bMaxY, bMaxZ) {
+    return (aMinX <= bMaxX && aMaxX >= bMinX &&
+        aMinY <= bMaxY && aMaxY >= bMinY &&
+        aMinZ <= bMaxZ && aMaxZ >= bMinZ);
+}
+export function boundsIntersect(a, b) {
+    return aabbIntersects(a.minX, a.minY, a.minZ, a.maxX, a.maxY, a.maxZ, b.minX, b.minY, b.minZ, b.maxX, b.maxY, b.maxZ);
+}
+export function createBoundsCache() {
+    const entries = new Map();
+    let recomputes = 0;
+    return {
+        get(id, version, spec, position) {
+            const existing = entries.get(id);
+            if (existing !== undefined && existing.version === version)
+                return existing.bounds;
+            if (existing === undefined) {
+                const bounds = resolveBounds(spec, position);
+                entries.set(id, { version, bounds });
+                recomputes += 1;
+                return bounds;
+            }
+            resolveBounds(spec, position, existing.bounds);
+            existing.version = version;
+            recomputes += 1;
+            return existing.bounds;
+        },
+        peek(id) {
+            return entries.get(id)?.bounds;
+        },
+        invalidate(id) {
+            const existing = entries.get(id);
+            if (existing !== undefined)
+                existing.version = Number.NaN;
+        },
+        delete(id) {
+            entries.delete(id);
+        },
+        clear() {
+            entries.clear();
+        },
+        size() {
+            return entries.size;
+        },
+        recomputes() {
+            return recomputes;
+        },
+    };
+}

package/dist/visibility/camera.d.ts

@@ -0,0 +1,21 @@
+import type { CameraView } from "./frustum.js";
+export type CameraKind = "main" | "splitScreen" | "renderToTexture" | "editor" | "minimap";
+/**
+ * A camera's contribution to visibility. The VisibilitySystem unions results across every
+ * active context: an object stays renderable/loaded if *any* relevant camera needs it.
+ * A camera can opt out of driving asset streaming (e.g. a minimap that only needs positions,
+ * not loaded meshes) via `influencesStreaming: false`.
+ */
+export interface CameraVisibilityContext {
+    readonly id: string;
+    readonly view: CameraView;
+    /** Default "main". Editor/minimap cameras are still honored but tagged for diagnostics. */
+    readonly kind?: CameraKind;
+    /** Default true. When false this camera keeps objects renderable but does not preload their assets. */
+    readonly influencesStreaming?: boolean;
+    /** When true this camera renders everything (no frustum/distance reject). Default false. */
+    readonly cullingDisabled?: boolean;
+    /** Overrides the global render distance for this camera. */
+    readonly maxRenderDistance?: number;
+}
+export declare function cameraInfluencesStreaming(context: CameraVisibilityContext): boolean;

package/dist/visibility/camera.js

@@ -0,0 +1,3 @@
+export function cameraInfluencesStreaming(context) {
+    return context.influencesStreaming !== false;
+}

package/dist/visibility/config.d.ts

@@ -0,0 +1,21 @@
+import type { CullingSettings, StreamingSettings, ObjectVisibilityOverrides } from "./settings.js";
+/**
+ * Per-game visibility configuration, surfaced on `PlayableGame.visibility`. Everything is
+ * optional: an existing game that sets nothing gets the conservative engine defaults
+ * automatically. This is the scene-level and per-kind override seam (requirement: per-object,
+ * per-layer, per-scene, and global controls).
+ */
+export interface VisibilityConfig {
+    /** Master switch for render culling in the shell. Default true. */
+    readonly enabled?: boolean;
+    /** Overrides for the global culling defaults (margins, distances, hysteresis, occlusion flag). */
+    readonly culling?: Partial<CullingSettings>;
+    /** Overrides for the asset-streaming defaults. */
+    readonly streaming?: Partial<StreamingSettings>;
+    /** Scene-wide overrides applied to every object. */
+    readonly scene?: ObjectVisibilityOverrides;
+    /** Overrides keyed by entity kind name. */
+    readonly entities?: Record<string, ObjectVisibilityOverrides>;
+    /** Overrides keyed by placed-object catalog id. */
+    readonly objects?: Record<string, ObjectVisibilityOverrides>;
+}

package/dist/visibility/config.js

@@ -0,0 +1 @@
+export {};

package/dist/visibility/diagnostics.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-frame visibility + streaming counters. The VisibilitySystem fills the culling and
+ * timing fields; the AssetStreamingSystem fills the asset fields. Everything is a plain
+ * number so a HUD or the devtools hub can read it without adapters.
+ */
+export interface VisibilityStats {
+    totalObjects: number;
+    consideredForRender: number;
+    rejectedByFrustum: number;
+    rejectedByDistance: number;
+    rejectedByOcclusion: number;
+    drawCallsAvoided: number;
+    visible: number;
+    preloaded: number;
+    assetsQueued: number;
+    assetsLoading: number;
+    assetsLoaded: number;
+    assetsUnloaded: number;
+    streamedBytes: number;
+    spatialQueryMs: number;
+    cullingMs: number;
+}
+export declare function createVisibilityStats(): VisibilityStats;
+export declare function resetCullingStats(stats: VisibilityStats): void;
+/** High-resolution clock that degrades to a monotonic-ish fallback when `performance` is absent. */
+export declare function nowMs(): number;

package/dist/visibility/diagnostics.js

@@ -0,0 +1,36 @@
+export function createVisibilityStats() {
+    return {
+        totalObjects: 0,
+        consideredForRender: 0,
+        rejectedByFrustum: 0,
+        rejectedByDistance: 0,
+        rejectedByOcclusion: 0,
+        drawCallsAvoided: 0,
+        visible: 0,
+        preloaded: 0,
+        assetsQueued: 0,
+        assetsLoading: 0,
+        assetsLoaded: 0,
+        assetsUnloaded: 0,
+        streamedBytes: 0,
+        spatialQueryMs: 0,
+        cullingMs: 0,
+    };
+}
+export function resetCullingStats(stats) {
+    stats.totalObjects = 0;
+    stats.consideredForRender = 0;
+    stats.rejectedByFrustum = 0;
+    stats.rejectedByDistance = 0;
+    stats.rejectedByOcclusion = 0;
+    stats.drawCallsAvoided = 0;
+    stats.visible = 0;
+    stats.preloaded = 0;
+    stats.spatialQueryMs = 0;
+    stats.cullingMs = 0;
+}
+/** High-resolution clock that degrades to a monotonic-ish fallback when `performance` is absent. */
+export function nowMs() {
+    const perf = globalThis.performance;
+    return perf !== undefined ? perf.now() : 0;
+}

package/dist/visibility/distance.d.ts

@@ -0,0 +1,11 @@
+import type { Vec3 } from "./bounds.js";
+export declare function distanceSquared(ax: number, ay: number, az: number, bx: number, by: number, bz: number): number;
+/**
+ * Whether an object at `objectCenter` should be distance-culled from `cameraPos`.
+ * Compares squared distances against squared thresholds — no per-object square root.
+ * `nearestSurface` subtracts the object radius so a large object is not culled by the
+ * distance to its far side. `hysteresis` widens the max band by a fixed world-unit
+ * band for objects that were visible last check, so they don't flicker at the boundary.
+ */
+export declare function culledByDistance(cameraX: number, cameraY: number, cameraZ: number, objectX: number, objectY: number, objectZ: number, minDistance: number, maxDistance: number, radius?: number, hysteresis?: number): boolean;
+export declare function distance(a: Vec3, b: Vec3): number;

package/dist/visibility/distance.js

@@ -0,0 +1,30 @@
+export function distanceSquared(ax, ay, az, bx, by, bz) {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const dz = bz - az;
+    return dx * dx + dy * dy + dz * dz;
+}
+/**
+ * Whether an object at `objectCenter` should be distance-culled from `cameraPos`.
+ * Compares squared distances against squared thresholds — no per-object square root.
+ * `nearestSurface` subtracts the object radius so a large object is not culled by the
+ * distance to its far side. `hysteresis` widens the max band by a fixed world-unit
+ * band for objects that were visible last check, so they don't flicker at the boundary.
+ */
+export function culledByDistance(cameraX, cameraY, cameraZ, objectX, objectY, objectZ, minDistance, maxDistance, radius = 0, hysteresis = 0) {
+    const distSq = distanceSquared(cameraX, cameraY, cameraZ, objectX, objectY, objectZ);
+    if (minDistance > 0) {
+        const nearFar = minDistance + radius;
+        if (distSq < nearFar * nearFar)
+            return true;
+    }
+    if (maxDistance !== Infinity && maxDistance !== Number.POSITIVE_INFINITY) {
+        const farNear = maxDistance + radius + hysteresis;
+        if (distSq > farNear * farNear)
+            return true;
+    }
+    return false;
+}
+export function distance(a, b) {
+    return Math.sqrt(distanceSquared(a[0], a[1], a[2], b[0], b[1], b[2]));
+}

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;