@jgengine/core 0.8.0 → 0.10.0

package/dist/scene/colliders.js

@@ -0,0 +1,101 @@
+export const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
+export const DEFAULT_OBJECT_HALF_EXTENTS = [0.5, 0.5, 0.5];
+/** Matches the shell's fallback actor capsule (~0.7m wide, feet at y=0 to head at ~1.8m). */
+export const DEFAULT_ENTITY_BODY_HALF_EXTENTS = [0.35, 0.9, 0.35];
+/** Entity-local center of the default body hitbox (half its height above the feet). */
+export const DEFAULT_ENTITY_BODY_OFFSET = [0, 0.9, 0];
+export function defaultEntityColliders() {
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape: {
+                    kind: "aabb",
+                    halfExtents: DEFAULT_ENTITY_BODY_HALF_EXTENTS,
+                    offset: DEFAULT_ENTITY_BODY_OFFSET,
+                },
+                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,
+        },
+    };
+}
+/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh). */
+export function scaledObjectColliders(scale) {
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape: {
+                kind: "aabb",
+                halfExtents: [scale[0] / 2, scale[1] / 2, scale[2] / 2],
+                offset: [0, scale[1] / 2, 0],
+            },
+            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/entityStats.d.ts

@@ -28,6 +28,10 @@ export declare function getStatValue(map: StatValueMap, statId: string): StatVal
 export declare function setStatValue(map: StatValueMap, statId: string, patch: StatValuePatch): StatValueMap;
 export declare function applyPoolDelta(map: StatValueMap, statId: string, amount: number): PoolDeltaResult;
 export declare function seedStatValues(catalogStats: StatCatalog): StatValueMap;
+/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}. */
+export declare function snapshotEntityStats(store: ReadonlyMap<string, StatValueMap>): Record<string, StatValueMap>;
+/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it. */
+export declare function hydrateEntityStats(store: Map<string, StatValueMap>, data: Record<string, StatValueMap>): void;
 export interface EntityStatsApi {
     get(instanceId: string, statId: string): StatValue | null;
     set(instanceId: string, statId: string, patch: StatValuePatch): boolean;

package/dist/scene/entityStats.js

@@ -35,6 +35,27 @@ export function seedStatValues(catalogStats) {
     }
     return map;
 }
+/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}. */
+export function snapshotEntityStats(store) {
+    const out = {};
+    for (const [instanceId, map] of store) {
+        const copy = {};
+        for (const [statId, value] of Object.entries(map))
+            copy[statId] = { ...value };
+        out[instanceId] = copy;
+    }
+    return out;
+}
+/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it. */
+export function hydrateEntityStats(store, data) {
+    store.clear();
+    for (const [instanceId, map] of Object.entries(data)) {
+        const copy = {};
+        for (const [statId, value] of Object.entries(map))
+            copy[statId] = { ...value };
+        store.set(instanceId, copy);
+    }
+}
 export function createEntityStatsApi(resolve) {
     return {
         get(instanceId, statId) {

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,17 +53,60 @@ 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;
+};
+/**
+ * Per-entity scratch and cooldown timers, auto-cleared on despawn (#533.8) — the home for AI state
+ * (next-shot-at, alert level) that would otherwise be smuggled through the serializable `meta` or a
+ * hand-pruned module-level map. Keys share one namespace per entity: `arm`/`ready`/`remaining` store a
+ * deadline under a key, `get`/`set` store arbitrary scratch.
+ */
+export interface EntityBlackboard {
+    /** Read a scratch value; `undefined` if unset or the entity has despawned. */
+    get<T>(id: string, key: string): T | undefined;
+    /** Write a scratch value; does not notify subscribers, and clears when the entity despawns. */
+    set(id: string, key: string, value: unknown): void;
+    has(id: string, key: string): boolean;
+    delete(id: string, key: string): void;
+    /** Drop all scratch and timers for one entity. */
+    clear(id: string): void;
+    /** Arm a cooldown for `key` that stays busy until absolute time `untilMs`. */
+    arm(id: string, key: string, untilMs: number): void;
+    /** True when no cooldown is armed for `key`, or its deadline has passed. */
+    ready(id: string, key: string, nowMs: number): boolean;
+    /** Milliseconds until the armed cooldown elapses; 0 when ready. */
+    remaining(id: string, key: string, nowMs: number): number;
+}
+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;
     subscribe(listener: () => void): () => void;
     snapshot(): readonly SceneEntity<TMeta>[];
+    /**
+     * Apply a `snapshot()` (e.g. from an authoritative host) to this store — the counterpart of `snapshot()`
+     * for host→client world mirroring: spawns entities present in the snapshot but not here, overwrites
+     * existing ones field-for-field (including velocity), and despawns any local entity absent from it.
+     */
+    hydrate(entities: readonly SceneEntity<TMeta>[]): void;
     spawnPoseOf(id: string): SpawnPose | null;
     resetToSpawn(id: string): boolean;
+    blackboard: EntityBlackboard;
 }
-export declare function createEntityStore<TMeta = undefined>(): EntityStore<TMeta>;
+export declare function createEntityStore<TMeta = unknown>(): EntityStore<TMeta>;

package/dist/scene/entityStore.js

@@ -20,7 +20,35 @@ function toEntityPosition(position) {
 export function createEntityStore() {
     const store = createObservableKeyedStore();
     const spawnPoses = new Map();
+    const constraints = new Map();
+    const blackboards = new Map();
     let nextCounter = 1;
+    const blackboard = {
+        get: (id, key) => blackboards.get(id)?.get(key),
+        set(id, key, value) {
+            const board = blackboards.get(id) ?? new Map();
+            board.set(key, value);
+            blackboards.set(id, board);
+        },
+        has: (id, key) => blackboards.get(id)?.has(key) ?? false,
+        delete(id, key) {
+            blackboards.get(id)?.delete(key);
+        },
+        clear(id) {
+            blackboards.delete(id);
+        },
+        arm(id, key, untilMs) {
+            this.set(id, key, untilMs);
+        },
+        ready(id, key, nowMs) {
+            const until = blackboards.get(id)?.get(key);
+            return typeof until !== "number" || nowMs >= until;
+        },
+        remaining(id, key, nowMs) {
+            const until = blackboards.get(id)?.get(key);
+            return typeof until === "number" ? Math.max(0, until - nowMs) : 0;
+        },
+    };
     function generateId() {
         let id = `entity-${nextCounter}`;
         while (store.has(id)) {
@@ -33,7 +61,12 @@ 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.`);
+                blackboards.delete(options.id);
             }
             const id = options.id ?? generateId();
             const position = toEntityPosition(options.position);
@@ -58,20 +91,58 @@ export function createEntityStore() {
             const existed = store.has(id);
             store.delete(id);
             spawnPoses.delete(id);
+            constraints.delete(id);
+            blackboards.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 +150,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 +171,8 @@ export function createEntityStore() {
             for (const entity of store.arraySnapshot()) {
                 store.delete(entity.id);
             }
+            constraints.clear();
+            blackboards.clear();
         },
         subscribe(listener) {
             return store.subscribe(listener);
@@ -106,6 +180,35 @@ export function createEntityStore() {
         snapshot() {
             return store.arraySnapshot();
         },
+        hydrate(entities) {
+            const incoming = new Set(entities.map((entity) => entity.id));
+            for (const current of store.arraySnapshot()) {
+                if (!incoming.has(current.id)) {
+                    store.delete(current.id);
+                    spawnPoses.delete(current.id);
+                    constraints.delete(current.id);
+                    blackboards.delete(current.id);
+                }
+            }
+            for (const entity of entities) {
+                store.set(entity.id, {
+                    id: entity.id,
+                    name: entity.name,
+                    position: entity.position,
+                    rotationY: entity.rotationY,
+                    rotationX: entity.rotationX,
+                    rotationZ: entity.rotationZ,
+                    velocity: entity.velocity,
+                    role: entity.role,
+                    movement: entity.movement,
+                    behaviors: entity.behaviors,
+                    meta: entity.meta,
+                });
+                if (!spawnPoses.has(entity.id)) {
+                    spawnPoses.set(entity.id, { position: entity.position, rotationY: entity.rotationY });
+                }
+            }
+        },
         spawnPoseOf(id) {
             return spawnPoses.get(id) ?? null;
         },
@@ -114,8 +217,12 @@ 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;
         },
+        blackboard,
     };
 }

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);
+                            }
+                        }
                     }
                 }
             }

package/dist/scene/sceneRaycast.d.ts

@@ -0,0 +1,80 @@
+import type { EntityPosition } from "./entityStore.js";
+import { type ColliderPurpose, type EntityColliderSet } from "./colliders.js";
+import type { SceneObject } from "./objectStore.js";
+export type SceneRaycastTargetKind = "entity" | "object" | "terrain" | "wall";
+export interface SceneRaycastHit {
+    targetKind: SceneRaycastTargetKind;
+    instanceId: string;
+    catalogId?: string;
+    colliderName: string;
+    purpose: ColliderPurpose;
+    damageEligible: boolean;
+    blocks: boolean;
+    distance: number;
+    point: EntityPosition;
+    normal: EntityPosition;
+}
+export interface SceneRaycastFilter {
+    entities?: boolean;
+    objects?: boolean;
+    terrain?: boolean;
+    walls?: boolean;
+}
+export interface SceneRaycastInput {
+    origin: EntityPosition;
+    direction: EntityPosition;
+    maxDistance: number;
+    excludeInstanceIds?: ReadonlySet<string> | readonly string[];
+    filter?: SceneRaycastFilter;
+    /** When set, only hits satisfying the predicate are kept (applied after geometry). */
+    accept?: (hit: SceneRaycastHit) => boolean;
+}
+export interface SceneEntityQuerySource {
+    list(): readonly {
+        id: string;
+        position: EntityPosition;
+        rotationY: number;
+        name?: string;
+    }[];
+    collidersOf?(instanceId: string): EntityColliderSet | null | undefined;
+    inRadius?(center: EntityPosition, radius: number): readonly string[];
+    get?(instanceId: string): {
+        id: string;
+        position: EntityPosition;
+        rotationY: number;
+        name?: string;
+    } | null;
+}
+export interface SceneObjectQuerySource {
+    list(): readonly SceneObject[];
+    inBox?(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
+    collidersOf?(instanceId: string): EntityColliderSet | null | undefined;
+    halfExtentsOf?(catalogId: string): EntityPosition | null | undefined;
+}
+export interface TerrainRaycastSource {
+    sampleHeight(x: number, z: number): number;
+}
+export interface WallSegment {
+    id: string;
+    /** Segment endpoints on the XZ plane; extruded by halfHeight along Y around yCenter. */
+    a: readonly [number, number];
+    b: readonly [number, number];
+    yCenter?: number;
+    halfHeight?: number;
+    thickness?: number;
+}
+export interface SceneRaycastDeps {
+    entities?: SceneEntityQuerySource;
+    objects?: SceneObjectQuerySource;
+    terrain?: TerrainRaycastSource;
+    walls?: readonly WallSegment[];
+}
+export interface SceneRaycastApi {
+    raycast(input: SceneRaycastInput): SceneRaycastHit | null;
+    raycastAll(input: SceneRaycastInput): SceneRaycastHit[];
+}
+/** First impact: nearest hit that blocks, or nearest hit if none block. */
+export declare function firstImpact(hits: readonly SceneRaycastHit[]): SceneRaycastHit | null;
+/** Hits up to and including the first blocking collider (damage hitboxes before a wall stay). */
+export declare function hitsUntilBlocked(hits: readonly SceneRaycastHit[]): SceneRaycastHit[];
+export declare function createSceneRaycast(deps: SceneRaycastDeps): SceneRaycastApi;