@jgengine/core 0.8.0 → 0.9.0

package/dist/runtime/visibility.d.ts

@@ -0,0 +1,74 @@
+/** Stable identifier for a visibility-tracked object or camera. */
+export type VisibilityId = string | number;
+/** World-space point; `z` is optional for 2D adapters. */
+export interface VisibilityPoint {
+    x: number;
+    y: number;
+    z?: number;
+}
+/** Sphere bounds used for visibility/streaming distance checks. */
+export interface VisibilityBounds {
+    center: VisibilityPoint;
+    radius: number;
+}
+/** A camera's position and reach, as seen by the visibility system. */
+export interface CameraVisibilityContext {
+    id: VisibilityId;
+    position: VisibilityPoint;
+    /** Approximate visible radius in world units. Adapters may derive this from a frustum. */
+    visibleRadius: number;
+    /** Extra distance used to request assets before an object becomes visible. */
+    preloadMargin?: number;
+    /** Cameras such as editor thumbnails can opt out of influencing streaming. */
+    influencesStreaming?: boolean;
+}
+/** Per-object escape hatches that bypass or tune the default visibility policy. */
+export interface VisibilityOverrides {
+    alwaysVisible?: boolean;
+    neverUnload?: boolean;
+    cullingDisabled?: boolean;
+    streamingDisabled?: boolean;
+    minRenderDistance?: number;
+    maxRenderDistance?: number;
+    preloadMargin?: number;
+}
+/** An entity/asset tracked by `VisibilitySystem.evaluate`. */
+export interface VisibilityObject {
+    id: VisibilityId;
+    bounds: VisibilityBounds;
+    overrides?: VisibilityOverrides;
+}
+/** Baseline policy settings a `VisibilitySystem` is constructed with. */
+export interface VisibilityDefaults {
+    enabled: boolean;
+    streamingEnabled: boolean;
+    minRenderDistance: number;
+    maxRenderDistance: number;
+    preloadMargin: number;
+    unloadGraceMs: number;
+    hysteresis: number;
+}
+/** Default `VisibilityDefaults` a `VisibilitySystem` falls back to when unspecified. */
+export declare const DEFAULT_VISIBILITY_SETTINGS: Readonly<VisibilityDefaults>;
+/** Result of evaluating one object against the active cameras this tick. */
+export interface VisibilityDecision {
+    render: boolean;
+    load: boolean;
+    unload: boolean;
+    reason: "always-visible" | "culling-disabled" | "visible" | "preload" | "distance-culled" | "outside-view" | "grace-period" | "streaming-disabled";
+}
+/**
+ * Engine-level visibility and asset-residency policy.
+ *
+ * Render culling and asset streaming are intentionally separate. This class never
+ * destroys entities or throttles simulation; adapters decide how to apply results.
+ */
+export declare class VisibilitySystem {
+    #private;
+    readonly settings: VisibilityDefaults;
+    constructor(settings?: Partial<VisibilityDefaults>);
+    evaluate(object: VisibilityObject, cameras: readonly CameraVisibilityContext[], now?: number): VisibilityDecision;
+    setLoaded(id: VisibilityId, loaded: boolean, now?: number): void;
+    forget(id: VisibilityId): void;
+    clear(): void;
+}

package/dist/runtime/visibility.js

@@ -0,0 +1,127 @@
+/** Default `VisibilityDefaults` a `VisibilitySystem` falls back to when unspecified. */
+export const DEFAULT_VISIBILITY_SETTINGS = Object.freeze({
+    enabled: true,
+    streamingEnabled: true,
+    minRenderDistance: 0,
+    maxRenderDistance: Number.POSITIVE_INFINITY,
+    preloadMargin: 24,
+    unloadGraceMs: 5_000,
+    hysteresis: 8,
+});
+function squaredDistance(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    const dz = (a.z ?? 0) - (b.z ?? 0);
+    return dx * dx + dy * dy + dz * dz;
+}
+function intersectsRadius(camera, bounds, extraMargin) {
+    const radius = Math.max(0, camera.visibleRadius + extraMargin + bounds.radius);
+    return squaredDistance(camera.position, bounds.center) <= radius * radius;
+}
+/**
+ * Engine-level visibility and asset-residency policy.
+ *
+ * Render culling and asset streaming are intentionally separate. This class never
+ * destroys entities or throttles simulation; adapters decide how to apply results.
+ */
+export class VisibilitySystem {
+    settings;
+    #states = new Map();
+    constructor(settings = {}) {
+        this.settings = { ...DEFAULT_VISIBILITY_SETTINGS, ...settings };
+    }
+    evaluate(object, cameras, now = Date.now()) {
+        const overrides = object.overrides ?? {};
+        const state = this.#states.get(object.id) ?? { loaded: false, lastNeededAt: now };
+        if (overrides.alwaysVisible) {
+            this.#markNeeded(object.id, state, now);
+            return { render: true, load: true, unload: false, reason: "always-visible" };
+        }
+        if (!this.settings.enabled || overrides.cullingDisabled) {
+            this.#markNeeded(object.id, state, now);
+            return { render: true, load: true, unload: false, reason: "culling-disabled" };
+        }
+        const minDistance = Math.max(0, overrides.minRenderDistance ?? this.settings.minRenderDistance);
+        const maxDistance = Math.max(minDistance, overrides.maxRenderDistance ?? this.settings.maxRenderDistance);
+        const minDistanceSq = minDistance * minDistance;
+        const maxDistanceWithRadius = maxDistance + object.bounds.radius;
+        const maxDistanceSq = maxDistanceWithRadius * maxDistanceWithRadius;
+        let insideDistance = false;
+        let visible = false;
+        let preload = false;
+        for (const camera of cameras) {
+            const distanceSq = squaredDistance(camera.position, object.bounds.center);
+            if (distanceSq < minDistanceSq || distanceSq > maxDistanceSq)
+                continue;
+            insideDistance = true;
+            if (intersectsRadius(camera, object.bounds, this.settings.hysteresis)) {
+                visible = true;
+            }
+            if (camera.influencesStreaming !== false) {
+                const margin = overrides.preloadMargin ?? camera.preloadMargin ?? this.settings.preloadMargin;
+                if (intersectsRadius(camera, object.bounds, margin + this.settings.hysteresis)) {
+                    preload = true;
+                }
+            }
+        }
+        if (visible) {
+            this.#markNeeded(object.id, state, now);
+            return { render: true, load: true, unload: false, reason: "visible" };
+        }
+        if (overrides.streamingDisabled || !this.settings.streamingEnabled) {
+            state.loaded = true;
+            this.#states.set(object.id, state);
+            return {
+                render: false,
+                load: true,
+                unload: false,
+                reason: "streaming-disabled",
+            };
+        }
+        if (preload) {
+            this.#markNeeded(object.id, state, now);
+            return { render: false, load: true, unload: false, reason: "preload" };
+        }
+        if (overrides.neverUnload) {
+            state.loaded = true;
+            this.#states.set(object.id, state);
+            return {
+                render: false,
+                load: true,
+                unload: false,
+                reason: insideDistance ? "outside-view" : "distance-culled",
+            };
+        }
+        const graceActive = state.loaded && now - state.lastNeededAt < this.settings.unloadGraceMs;
+        if (graceActive) {
+            this.#states.set(object.id, state);
+            return { render: false, load: true, unload: false, reason: "grace-period" };
+        }
+        state.loaded = false;
+        this.#states.set(object.id, state);
+        return {
+            render: false,
+            load: false,
+            unload: true,
+            reason: insideDistance ? "outside-view" : "distance-culled",
+        };
+    }
+    setLoaded(id, loaded, now = Date.now()) {
+        const previous = this.#states.get(id);
+        this.#states.set(id, {
+            loaded,
+            lastNeededAt: loaded ? now : previous?.lastNeededAt ?? now,
+        });
+    }
+    forget(id) {
+        this.#states.delete(id);
+    }
+    clear() {
+        this.#states.clear();
+    }
+    #markNeeded(id, state, now) {
+        state.loaded = true;
+        state.lastNeededAt = now;
+        this.#states.set(id, state);
+    }
+}

package/dist/scene/colliders.d.ts

@@ -0,0 +1,44 @@
+import type { EntityPosition } from "./entityStore.js";
+export type ColliderPurpose = "physical" | "damage";
+export type ColliderShape = {
+    kind: "sphere";
+    radius: number;
+    offset?: EntityPosition;
+} | {
+    kind: "aabb";
+    halfExtents: EntityPosition;
+    offset?: EntityPosition;
+};
+export interface ColliderDef {
+    name: string;
+    purpose: ColliderPurpose;
+    shape: ColliderShape;
+    /** Defaults true for `purpose: "damage"`, false for `purpose: "physical"`. */
+    damageEligible?: boolean;
+    /** Defaults true — a blocking collider stops a ray at first impact. */
+    blocks?: boolean;
+}
+export interface EntityColliderSet {
+    /** Single physical collision body (push / obstruction). */
+    body?: ColliderDef;
+    /** Named damage hitboxes (zero or more). */
+    hitboxes?: readonly ColliderDef[];
+}
+export interface ResolvedCollider {
+    name: string;
+    purpose: ColliderPurpose;
+    shape: ColliderShape;
+    damageEligible: boolean;
+    blocks: boolean;
+}
+export declare const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
+export declare const DEFAULT_OBJECT_HALF_EXTENTS: EntityPosition;
+export declare function defaultEntityColliders(): EntityColliderSet;
+export declare function defaultObjectColliders(halfExtents?: EntityPosition): EntityColliderSet;
+export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
+export declare function worldOffset(local: EntityPosition | undefined, position: EntityPosition, rotationY: number): EntityPosition;
+export declare function colliderWorldCenter(collider: ResolvedCollider, position: EntityPosition, rotationY: number): EntityPosition;
+export declare function colliderBounds(collider: ResolvedCollider, position: EntityPosition, rotationY: number): {
+    min: EntityPosition;
+    max: EntityPosition;
+};

package/dist/scene/colliders.js

@@ -0,0 +1,77 @@
+export const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
+export const DEFAULT_OBJECT_HALF_EXTENTS = [0.5, 0.5, 0.5];
+export function defaultEntityColliders() {
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape: { kind: "sphere", radius: DEFAULT_ENTITY_HIT_RADIUS },
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+export function defaultObjectColliders(halfExtents = DEFAULT_OBJECT_HALF_EXTENTS) {
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape: { kind: "aabb", halfExtents },
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
+export function resolveColliders(set) {
+    if (set === null || set === undefined)
+        return [];
+    const out = [];
+    if (set.body !== undefined)
+        out.push(resolveOne(set.body));
+    if (set.hitboxes !== undefined) {
+        for (const hitbox of set.hitboxes)
+            out.push(resolveOne(hitbox));
+    }
+    return out;
+}
+function resolveOne(def) {
+    const damageEligible = def.damageEligible ?? def.purpose === "damage";
+    const blocks = def.blocks ?? def.purpose === "physical";
+    return {
+        name: def.name,
+        purpose: def.purpose,
+        shape: def.shape,
+        damageEligible,
+        blocks,
+    };
+}
+export function worldOffset(local, position, rotationY) {
+    if (local === undefined)
+        return position;
+    const cos = Math.cos(rotationY);
+    const sin = Math.sin(rotationY);
+    const lx = local[0];
+    const ly = local[1];
+    const lz = local[2];
+    return [position[0] + lx * cos + lz * sin, position[1] + ly, position[2] - lx * sin + lz * cos];
+}
+export function colliderWorldCenter(collider, position, rotationY) {
+    return worldOffset(collider.shape.offset, position, rotationY);
+}
+export function colliderBounds(collider, position, rotationY) {
+    const center = colliderWorldCenter(collider, position, rotationY);
+    if (collider.shape.kind === "sphere") {
+        const r = collider.shape.radius;
+        return {
+            min: [center[0] - r, center[1] - r, center[2] - r],
+            max: [center[0] + r, center[1] + r, center[2] + r],
+        };
+    }
+    const h = collider.shape.halfExtents;
+    return {
+        min: [center[0] - h[0], center[1] - h[1], center[2] - h[2]],
+        max: [center[0] + h[0], center[1] + h[1], center[2] + h[2]],
+    };
+}

package/dist/scene/entityStore.d.ts

@@ -10,7 +10,7 @@ export type SpawnPositionInput = EntityPosition | {
     y: number;
     z: number;
 };
-export interface SceneEntity<TMeta = undefined> {
+export interface SceneEntity<TMeta = unknown> {
     id: string;
     name: string;
     position: EntityPosition;
@@ -22,12 +22,13 @@ export interface SceneEntity<TMeta = undefined> {
     role: EntityRole;
     movement: EntityMovement;
     behaviors: readonly BehaviorDescriptor[];
+    /** Game-defined per-instance data set at `spawn`/`update` and carried to `renderEntity`/queries — narrow with a cast or type guard on read (#286.1); never encode state in the id/name string. */
     meta: TMeta;
 }
 /** Ground speed (horizontal magnitude of velocity) in world units per second. Scale to km/h or mph in game code. */
 export declare function groundSpeed(entity: SceneEntity<unknown>): number;
 export declare function movedWhileFrozen(entity: SceneEntity<unknown>, threshold?: number): boolean;
-export interface SpawnOptions<TMeta = undefined> {
+export interface SpawnOptions<TMeta = unknown> {
     id?: string;
     position?: SpawnPositionInput;
     rotationY?: number;
@@ -37,6 +38,8 @@ export interface SpawnOptions<TMeta = undefined> {
     movement?: EntityMovement;
     behaviors?: readonly BehaviorDescriptor[];
     meta?: TMeta;
+    /** When `id` is already spawned: `"throw"` (default), `"replace"` (fresh spawn over it — remount-safe world setup, #284.10), or `"keep"` (leave it untouched and return the id). */
+    onExisting?: "throw" | "replace" | "keep";
 }
 export interface EntityPose {
     position: SpawnPositionInput;
@@ -50,11 +53,25 @@ export interface SpawnPose {
     position: EntityPosition;
     rotationY: number;
 }
-export interface EntityStore<TMeta = undefined> {
+export interface PoseConstraintFrame {
+    entityId: string;
+    current: EntityPosition;
+    next: EntityPosition;
+    dt?: number;
+}
+/** Return a replacement position to constrain the step, or nothing to accept it. */
+export type PoseConstraint = (frame: PoseConstraintFrame) => readonly [number, number, number] | undefined | void;
+export type EntityUpdatePatch<TMeta = unknown> = Partial<Pick<SceneEntity<TMeta>, "name" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "meta">> & {
+    /** Accepts the same friendly shapes as `spawn`/`setPose` (#286.13). Raw patch semantics — velocity is not derived; use `setPose` with `dt` for that. */
+    position?: SpawnPositionInput;
+};
+export interface EntityStore<TMeta = unknown> {
     spawn(name: string, options?: SpawnOptions<TMeta>): string;
     despawn(id: string): boolean;
-    update(id: string, patch: Partial<Pick<SceneEntity<TMeta>, "name" | "position" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "meta">>): boolean;
+    update(id: string, patch: EntityUpdatePatch<TMeta>): boolean;
     setPose(id: string, pose: EntityPose): boolean;
+    /** Register a constraint applied inside every `setPose` for this entity — the self-driven sibling of the shell's `beforeCommit` (#282.9): nav clamps, corridor walls, arena bounds without wrapping every call site. `null` clears; despawn clears automatically. */
+    setPoseConstraint(id: string, constraint: PoseConstraint | null): void;
     get(id: string): SceneEntity<TMeta> | null;
     list(): readonly SceneEntity<TMeta>[];
     clear(): void;
@@ -63,4 +80,4 @@ export interface EntityStore<TMeta = undefined> {
     spawnPoseOf(id: string): SpawnPose | null;
     resetToSpawn(id: string): boolean;
 }
-export declare function createEntityStore<TMeta = undefined>(): EntityStore<TMeta>;
+export declare function createEntityStore<TMeta = unknown>(): EntityStore<TMeta>;

package/dist/scene/entityStore.js

@@ -20,6 +20,7 @@ function toEntityPosition(position) {
 export function createEntityStore() {
     const store = createObservableKeyedStore();
     const spawnPoses = new Map();
+    const constraints = new Map();
     let nextCounter = 1;
     function generateId() {
         let id = `entity-${nextCounter}`;
@@ -33,7 +34,11 @@ export function createEntityStore() {
     return {
         spawn(name, options = {}) {
             if (options.id !== undefined && store.has(options.id)) {
-                throw new Error(`Scene entity id "${options.id}" is already spawned.`);
+                const onExisting = options.onExisting ?? "throw";
+                if (onExisting === "keep")
+                    return options.id;
+                if (onExisting === "throw")
+                    throw new Error(`Scene entity id "${options.id}" is already spawned.`);
             }
             const id = options.id ?? generateId();
             const position = toEntityPosition(options.position);
@@ -58,20 +63,57 @@ export function createEntityStore() {
             const existed = store.has(id);
             store.delete(id);
             spawnPoses.delete(id);
+            constraints.delete(id);
             return existed;
         },
         update(id, patch) {
             const current = store.get(id);
             if (!current)
                 return false;
-            store.set(id, { ...current, ...patch });
+            if (patch.position !== undefined)
+                current.position = toEntityPosition(patch.position);
+            if (patch.name !== undefined)
+                current.name = patch.name;
+            if (patch.rotationY !== undefined)
+                current.rotationY = patch.rotationY;
+            if (patch.rotationX !== undefined)
+                current.rotationX = patch.rotationX;
+            if (patch.rotationZ !== undefined)
+                current.rotationZ = patch.rotationZ;
+            if (patch.role !== undefined)
+                current.role = patch.role;
+            if (patch.movement !== undefined)
+                current.movement = patch.movement;
+            if (patch.behaviors !== undefined)
+                current.behaviors = patch.behaviors;
+            if (patch.meta !== undefined)
+                current.meta = patch.meta;
+            store.set(id, current);
             return true;
         },
+        setPoseConstraint(id, constraint) {
+            if (constraint === null)
+                constraints.delete(id);
+            else
+                constraints.set(id, constraint);
+        },
         setPose(id, pose) {
             const current = store.get(id);
             if (!current)
                 return false;
-            const position = toEntityPosition(pose.position);
+            let position = toEntityPosition(pose.position);
+            const constraint = constraints.get(id);
+            if (constraint !== undefined) {
+                const frame = {
+                    entityId: id,
+                    current: current.position,
+                    next: position,
+                    ...(pose.dt === undefined ? {} : { dt: pose.dt }),
+                };
+                const replacement = constraint(frame);
+                if (replacement !== undefined)
+                    position = toEntityPosition(replacement);
+            }
             const velocity = pose.dt !== undefined && pose.dt > 0
                 ? [
                     (position[0] - current.position[0]) / pose.dt,
@@ -79,14 +121,15 @@ export function createEntityStore() {
                     (position[2] - current.position[2]) / pose.dt,
                 ]
                 : current.velocity;
-            store.set(id, {
-                ...current,
-                position,
-                velocity,
-                rotationY: pose.rotationY ?? current.rotationY,
-                rotationX: pose.rotationX ?? current.rotationX,
-                rotationZ: pose.rotationZ ?? current.rotationZ,
-            });
+            current.position = position;
+            current.velocity = velocity;
+            if (pose.rotationY !== undefined)
+                current.rotationY = pose.rotationY;
+            if (pose.rotationX !== undefined)
+                current.rotationX = pose.rotationX;
+            if (pose.rotationZ !== undefined)
+                current.rotationZ = pose.rotationZ;
+            store.set(id, current);
             return true;
         },
         get(id) {
@@ -99,6 +142,7 @@ export function createEntityStore() {
             for (const entity of store.arraySnapshot()) {
                 store.delete(entity.id);
             }
+            constraints.clear();
         },
         subscribe(listener) {
             return store.subscribe(listener);
@@ -114,7 +158,10 @@ export function createEntityStore() {
             const current = store.get(id);
             if (pose === undefined || current === undefined)
                 return false;
-            store.set(id, { ...current, position: pose.position, rotationY: pose.rotationY, velocity: [0, 0, 0] });
+            current.position = pose.position;
+            current.rotationY = pose.rotationY;
+            current.velocity = [0, 0, 0];
+            store.set(id, current);
             return true;
         },
     };

package/dist/scene/objectQuery.d.ts

@@ -14,5 +14,16 @@ export interface ObjectRaycastHit {
     point: EntityPosition;
     normal: EntityPosition;
 }
-export declare function raycastObjects(objects: readonly SceneObject[], input: ObjectRaycastInput): ObjectRaycastHit | null;
-export declare function raycastObjectsAll(objects: readonly SceneObject[], input: ObjectRaycastInput): ObjectRaycastHit[];
+/** Optional broadphase for large object sets — typically `ObjectStore.inBox`. */
+export interface ObjectQueryBroadphase {
+    inBox(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
+}
+export type ObjectRaycastSource = readonly SceneObject[] | ObjectQueryBroadphase;
+declare function normalize(direction: EntityPosition): EntityPosition;
+declare function intersectAabb(origin: EntityPosition, direction: EntityPosition, min: EntityPosition, max: EntityPosition, maxDistance: number): {
+    distance: number;
+    normal: EntityPosition;
+} | null;
+export declare function raycastObjects(source: ObjectRaycastSource, input: ObjectRaycastInput): ObjectRaycastHit | null;
+export declare function raycastObjectsAll(source: ObjectRaycastSource, input: ObjectRaycastInput): ObjectRaycastHit[];
+export { intersectAabb, normalize as normalizeDirection };

package/dist/scene/objectQuery.js

@@ -5,6 +5,9 @@ function normalize(direction) {
         return [0, 0, 0];
     return [direction[0] / length, direction[1] / length, direction[2] / length];
 }
+function isBroadphase(source) {
+    return !Array.isArray(source) && typeof source.inBox === "function";
+}
 function intersectAabb(origin, direction, min, max, maxDistance) {
     let tMin = 0;
     let tMax = maxDistance;
@@ -73,11 +76,38 @@ function hitFor(object, origin, direction, halfExtents, maxDistance) {
         normal: hit.normal,
     };
 }
-export function raycastObjects(objects, input) {
+function raySegmentBounds(origin, direction, maxDistance, halfExtents) {
+    const endX = origin[0] + direction[0] * maxDistance;
+    const endY = origin[1] + direction[1] * maxDistance;
+    const endZ = origin[2] + direction[2] * maxDistance;
+    const padX = halfExtents[0];
+    const padY = halfExtents[1];
+    const padZ = halfExtents[2];
+    return {
+        min: [
+            Math.min(origin[0], endX) - padX,
+            Math.min(origin[1], endY) - padY,
+            Math.min(origin[2], endZ) - padZ,
+        ],
+        max: [
+            Math.max(origin[0], endX) + padX,
+            Math.max(origin[1], endY) + padY,
+            Math.max(origin[2], endZ) + padZ,
+        ],
+    };
+}
+function resolveCandidates(source, origin, direction, maxDistance, halfExtents) {
+    if (!isBroadphase(source))
+        return source;
+    const bounds = raySegmentBounds(origin, direction, maxDistance, halfExtents);
+    return source.inBox(bounds.min, bounds.max);
+}
+export function raycastObjects(source, input) {
     const direction = normalize(input.direction);
     if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
         return null;
     const halfExtents = input.halfExtents ?? DEFAULT_HALF_EXTENTS;
+    const objects = resolveCandidates(source, input.origin, direction, input.maxDistance, halfExtents);
     let nearest = null;
     for (const object of objects) {
         if (input.filter !== undefined && !input.filter(object))
@@ -90,11 +120,12 @@ export function raycastObjects(objects, input) {
     }
     return nearest;
 }
-export function raycastObjectsAll(objects, input) {
+export function raycastObjectsAll(source, input) {
     const direction = normalize(input.direction);
     if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
         return [];
     const halfExtents = input.halfExtents ?? DEFAULT_HALF_EXTENTS;
+    const objects = resolveCandidates(source, input.origin, direction, input.maxDistance, halfExtents);
     const hits = [];
     for (const object of objects) {
         if (input.filter !== undefined && !input.filter(object))
@@ -106,3 +137,4 @@ export function raycastObjectsAll(objects, input) {
     hits.sort((a, b) => a.distance - b.distance);
     return hits;
 }
+export { intersectAabb, normalize as normalizeDirection };

package/dist/scene/objectStore.d.ts

@@ -17,6 +17,8 @@ export interface PlaceOptions {
     parentSpace?: string;
     rotation?: number;
     visual?: ObjectVisual;
+    /** When `instanceId` is already placed: `"throw"` (default), `"replace"` (fresh placement over it — remount-safe world setup, #284.10), or `"keep"` (leave it untouched and return the id). */
+    onExisting?: "throw" | "replace" | "keep";
 }
 export interface ObjectListFilter {
     parentSpace?: string;

package/dist/scene/objectStore.js

@@ -42,8 +42,14 @@ export function createObjectStore() {
     }
     return {
         place(catalogId, x, y, z, options = {}) {
-            if (options.instanceId !== undefined && store.has(options.instanceId)) {
-                throw new Error(`Scene object id "${options.instanceId}" is already placed.`);
+            const existing = options.instanceId === undefined ? null : store.get(options.instanceId);
+            if (existing !== null && existing !== undefined) {
+                const onExisting = options.onExisting ?? "throw";
+                if (onExisting === "keep")
+                    return options.instanceId;
+                if (onExisting === "throw")
+                    throw new Error(`Scene object id "${options.instanceId}" is already placed.`);
+                indexRemove(options.instanceId, existing.position);
             }
             const instanceId = options.instanceId ?? generateId();
             const position = [x, y, z];
@@ -137,16 +143,29 @@ export function createObjectStore() {
         },
         inBox(min, max) {
             const hits = [];
-            for (const bucket of cellIndex.values()) {
-                for (const instanceId of bucket) {
-                    const object = store.get(instanceId);
-                    if (object === undefined)
-                        continue;
-                    const [x, y, z] = object.position;
-                    if (x >= min[0] && x <= max[0] &&
-                        y >= min[1] && y <= max[1] &&
-                        z >= min[2] && z <= max[2]) {
-                        hits.push(object);
+            const minCx = cellIndexOf(min[0]);
+            const maxCx = cellIndexOf(max[0]);
+            const minCy = cellIndexOf(min[1]);
+            const maxCy = cellIndexOf(max[1]);
+            const minCz = cellIndexOf(min[2]);
+            const maxCz = cellIndexOf(max[2]);
+            for (let cx = minCx; cx <= maxCx; cx += 1) {
+                for (let cy = minCy; cy <= maxCy; cy += 1) {
+                    for (let cz = minCz; cz <= maxCz; cz += 1) {
+                        const bucket = cellIndex.get(cellKey(cx, cy, cz));
+                        if (bucket === undefined)
+                            continue;
+                        for (const instanceId of bucket) {
+                            const object = store.get(instanceId);
+                            if (object === undefined)
+                                continue;
+                            const [x, y, z] = object.position;
+                            if (x >= min[0] && x <= max[0] &&
+                                y >= min[1] && y <= max[1] &&
+                                z >= min[2] && z <= max[2]) {
+                                hits.push(object);
+                            }
+                        }
                     }
                 }
             }