@jgengine/core 0.7.0 → 0.9.0

package/dist/scene/objectStore.js

@@ -1,6 +1,17 @@
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+const CELL_SIZE = 1;
+function cellIndexOf(value) {
+    return Math.floor(value / CELL_SIZE);
+}
+function cellKey(cx, cy, cz) {
+    return `${cx}:${cy}:${cz}`;
+}
+function cellKeyOf(position) {
+    return cellKey(cellIndexOf(position[0]), cellIndexOf(position[1]), cellIndexOf(position[2]));
+}
 export function createObjectStore() {
     const store = createObservableKeyedStore();
+    const cellIndex = new Map();
     let nextCounter = 1;
     function generateId() {
         let id = `object-${nextCounter}`;
@@ -11,31 +22,64 @@ export function createObjectStore() {
         nextCounter += 1;
         return id;
     }
+    function indexAdd(instanceId, position) {
+        const key = cellKeyOf(position);
+        let bucket = cellIndex.get(key);
+        if (bucket === undefined) {
+            bucket = new Set();
+            cellIndex.set(key, bucket);
+        }
+        bucket.add(instanceId);
+    }
+    function indexRemove(instanceId, position) {
+        const key = cellKeyOf(position);
+        const bucket = cellIndex.get(key);
+        if (bucket === undefined)
+            return;
+        bucket.delete(instanceId);
+        if (bucket.size === 0)
+            cellIndex.delete(key);
+    }
     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];
             store.set(instanceId, {
                 instanceId,
                 catalogId,
-                position: [x, y, z],
+                position,
                 rotationY: options.rotation ?? 0,
                 ...(options.parentSpace !== undefined ? { parentSpace: options.parentSpace } : {}),
+                ...(options.visual !== undefined ? { visual: options.visual } : {}),
             });
+            indexAdd(instanceId, position);
             return instanceId;
         },
         remove(instanceId) {
-            const existed = store.has(instanceId);
+            const current = store.get(instanceId);
+            if (!current)
+                return false;
             store.delete(instanceId);
-            return existed;
+            indexRemove(instanceId, current.position);
+            return true;
         },
         move(instanceId, x, y, z) {
             const current = store.get(instanceId);
             if (!current)
                 return false;
-            store.set(instanceId, { ...current, position: [x, y, z] });
+            const position = [x, y, z];
+            store.set(instanceId, { ...current, position });
+            indexRemove(instanceId, current.position);
+            indexAdd(instanceId, position);
             return true;
         },
         rotate(instanceId, rotationY) {
@@ -45,6 +89,20 @@ export function createObjectStore() {
             store.set(instanceId, { ...current, rotationY });
             return true;
         },
+        setVisual(instanceId, visual) {
+            const current = store.get(instanceId);
+            if (!current)
+                return false;
+            store.set(instanceId, {
+                instanceId: current.instanceId,
+                catalogId: current.catalogId,
+                position: current.position,
+                rotationY: current.rotationY,
+                ...(current.parentSpace !== undefined ? { parentSpace: current.parentSpace } : {}),
+                ...(visual !== undefined ? { visual } : {}),
+            });
+            return true;
+        },
         get(instanceId) {
             return store.get(instanceId) ?? null;
         },
@@ -54,10 +112,70 @@ export function createObjectStore() {
                 return all;
             return all.filter((object) => object.parentSpace === filter.parentSpace);
         },
+        at(x, y, z, tolerance = 0) {
+            const minCx = cellIndexOf(x - tolerance);
+            const maxCx = cellIndexOf(x + tolerance);
+            const minCy = cellIndexOf(y - tolerance);
+            const maxCy = cellIndexOf(y + tolerance);
+            const minCz = cellIndexOf(z - tolerance);
+            const maxCz = cellIndexOf(z + tolerance);
+            const results = [];
+            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 dx = object.position[0] - x;
+                            const dy = object.position[1] - y;
+                            const dz = object.position[2] - z;
+                            if (Math.hypot(dx, dy, dz) <= tolerance)
+                                results.push(object);
+                        }
+                    }
+                }
+            }
+            return results;
+        },
+        inBox(min, max) {
+            const hits = [];
+            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);
+                            }
+                        }
+                    }
+                }
+            }
+            return hits;
+        },
         clear() {
             for (const object of store.arraySnapshot()) {
                 store.delete(object.instanceId);
             }
+            cellIndex.clear();
         },
         subscribe(listener) {
             return store.subscribe(listener);
@@ -67,3 +185,9 @@ export function createObjectStore() {
         },
     };
 }
+export function objectVisualScale(visual) {
+    const scale = visual?.scale;
+    if (scale === undefined)
+        return [1, 1, 1];
+    return typeof scale === "number" ? [scale, scale, scale] : scale;
+}

package/dist/scene/paintLayer.d.ts

@@ -0,0 +1,15 @@
+export interface PaintStroke {
+    u: number;
+    v: number;
+    radius: number;
+    color: string;
+}
+export interface PaintLayer {
+    paint(instanceId: string, stroke: PaintStroke): void;
+    strokes(instanceId: string): readonly PaintStroke[];
+    paintedIds(): readonly string[];
+    clear(instanceId?: string): void;
+    version(instanceId: string): number;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createPaintLayer(): PaintLayer;

package/dist/scene/paintLayer.js

@@ -0,0 +1,53 @@
+export function createPaintLayer() {
+    const strokesByInstance = new Map();
+    const versionByInstance = new Map();
+    const listeners = new Set();
+    function bumpVersion(instanceId) {
+        versionByInstance.set(instanceId, (versionByInstance.get(instanceId) ?? 0) + 1);
+    }
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        paint(instanceId, stroke) {
+            const list = strokesByInstance.get(instanceId);
+            if (list === undefined)
+                strokesByInstance.set(instanceId, [stroke]);
+            else
+                list.push(stroke);
+            bumpVersion(instanceId);
+            notify();
+        },
+        strokes(instanceId) {
+            return strokesByInstance.get(instanceId) ?? [];
+        },
+        paintedIds() {
+            return Array.from(strokesByInstance.keys());
+        },
+        clear(instanceId) {
+            if (instanceId === undefined) {
+                if (strokesByInstance.size === 0)
+                    return;
+                for (const id of strokesByInstance.keys())
+                    bumpVersion(id);
+                strokesByInstance.clear();
+                notify();
+                return;
+            }
+            if (!strokesByInstance.delete(instanceId))
+                return;
+            bumpVersion(instanceId);
+            notify();
+        },
+        version(instanceId) {
+            return versionByInstance.get(instanceId) ?? 0;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

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;

package/dist/scene/sceneRaycast.js

@@ -0,0 +1,284 @@
+import { colliderBounds, colliderWorldCenter, defaultEntityColliders, defaultObjectColliders, resolveColliders, } from "./colliders.js";
+import { intersectAabb, normalizeDirection } from "./objectQuery.js";
+function excluded(exclude, id) {
+    if (exclude === undefined)
+        return false;
+    if (typeof exclude.has === "function") {
+        return exclude.has(id);
+    }
+    for (const value of exclude) {
+        if (value === id)
+            return true;
+    }
+    return false;
+}
+function enabled(filter, key) {
+    if (filter === undefined)
+        return true;
+    return filter[key] !== false;
+}
+function rayHitsSphere(origin, direction, center, radius, maxDistance) {
+    const ox = origin[0] - center[0];
+    const oy = origin[1] - center[1];
+    const oz = origin[2] - center[2];
+    const b = ox * direction[0] + oy * direction[1] + oz * direction[2];
+    const c = ox * ox + oy * oy + oz * oz - radius * radius;
+    const disc = b * b - c;
+    if (disc < 0)
+        return null;
+    const sqrt = Math.sqrt(disc);
+    let t = -b - sqrt;
+    if (t < 0)
+        t = -b + sqrt;
+    if (t < 0 || t > maxDistance)
+        return null;
+    const px = origin[0] + direction[0] * t - center[0];
+    const py = origin[1] + direction[1] * t - center[1];
+    const pz = origin[2] + direction[2] * t - center[2];
+    const len = Math.hypot(px, py, pz) || 1;
+    return { distance: t, normal: [px / len, py / len, pz / len] };
+}
+function rayHitsCollider(origin, direction, maxDistance, collider, position, rotationY) {
+    if (collider.shape.kind === "sphere") {
+        const center = colliderWorldCenter(collider, position, rotationY);
+        const hit = rayHitsSphere(origin, direction, center, collider.shape.radius, maxDistance);
+        if (hit === null)
+            return null;
+        return {
+            distance: hit.distance,
+            normal: hit.normal,
+            point: [
+                origin[0] + direction[0] * hit.distance,
+                origin[1] + direction[1] * hit.distance,
+                origin[2] + direction[2] * hit.distance,
+            ],
+        };
+    }
+    const bounds = colliderBounds(collider, position, rotationY);
+    const hit = intersectAabb(origin, direction, bounds.min, bounds.max, maxDistance);
+    if (hit === null)
+        return null;
+    return {
+        distance: hit.distance,
+        normal: hit.normal,
+        point: [
+            origin[0] + direction[0] * hit.distance,
+            origin[1] + direction[1] * hit.distance,
+            origin[2] + direction[2] * hit.distance,
+        ],
+    };
+}
+function pushColliderHits(hits, targetKind, instanceId, catalogId, colliders, position, rotationY, origin, direction, maxDistance) {
+    for (const collider of colliders) {
+        const hit = rayHitsCollider(origin, direction, maxDistance, collider, position, rotationY);
+        if (hit === null)
+            continue;
+        hits.push({
+            targetKind,
+            instanceId,
+            ...(catalogId !== undefined ? { catalogId } : {}),
+            colliderName: collider.name,
+            purpose: collider.purpose,
+            damageEligible: collider.damageEligible,
+            blocks: collider.blocks,
+            distance: hit.distance,
+            point: hit.point,
+            normal: hit.normal,
+        });
+    }
+}
+function wallAabb(wall) {
+    const thickness = wall.thickness ?? 0.25;
+    const halfHeight = wall.halfHeight ?? 1.5;
+    const yCenter = wall.yCenter ?? halfHeight;
+    const ax = wall.a[0];
+    const az = wall.a[1];
+    const bx = wall.b[0];
+    const bz = wall.b[1];
+    const dx = bx - ax;
+    const dz = bz - az;
+    const len = Math.hypot(dx, dz) || 1;
+    const nx = (-dz / len) * thickness;
+    const nz = (dx / len) * thickness;
+    const xs = [ax + nx, ax - nx, bx + nx, bx - nx];
+    const zs = [az + nz, az - nz, bz + nz, bz - nz];
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+    return {
+        min: [minX, yCenter - halfHeight, minZ],
+        max: [maxX, yCenter + halfHeight, maxZ],
+        center: [(ax + bx) / 2, yCenter, (az + bz) / 2],
+    };
+}
+function rayHitsTerrain(origin, direction, maxDistance, terrain) {
+    const steps = Math.max(8, Math.ceil(maxDistance * 2));
+    const step = maxDistance / steps;
+    let prevAbove = null;
+    let prevT = 0;
+    for (let i = 0; i <= steps; i += 1) {
+        const t = Math.min(maxDistance, i * step);
+        const x = origin[0] + direction[0] * t;
+        const y = origin[1] + direction[1] * t;
+        const z = origin[2] + direction[2] * t;
+        const ground = terrain.sampleHeight(x, z);
+        const above = y >= ground;
+        if (prevAbove === true && !above) {
+            let lo = prevT;
+            let hi = t;
+            for (let refine = 0; refine < 8; refine += 1) {
+                const mid = (lo + hi) / 2;
+                const my = origin[1] + direction[1] * mid;
+                const mg = terrain.sampleHeight(origin[0] + direction[0] * mid, origin[2] + direction[2] * mid);
+                if (my >= mg)
+                    lo = mid;
+                else
+                    hi = mid;
+            }
+            const distance = hi;
+            const px = origin[0] + direction[0] * distance;
+            const py = origin[1] + direction[1] * distance;
+            const pz = origin[2] + direction[2] * distance;
+            return {
+                targetKind: "terrain",
+                instanceId: "terrain",
+                colliderName: "ground",
+                purpose: "physical",
+                damageEligible: false,
+                blocks: true,
+                distance,
+                point: [px, py, pz],
+                normal: [0, 1, 0],
+            };
+        }
+        prevAbove = above;
+        prevT = t;
+    }
+    return null;
+}
+function candidateEntityIds(entities, origin, maxDistance) {
+    if (entities.inRadius !== undefined && entities.get !== undefined) {
+        const ids = entities.inRadius(origin, maxDistance + 2);
+        const out = [];
+        for (const id of ids) {
+            const entity = entities.get(id);
+            if (entity !== null && entity !== undefined)
+                out.push(entity);
+        }
+        return out;
+    }
+    return entities.list();
+}
+function candidateObjects(objects, origin, direction, maxDistance) {
+    if (objects.inBox !== undefined) {
+        const end = [
+            origin[0] + direction[0] * maxDistance,
+            origin[1] + direction[1] * maxDistance,
+            origin[2] + direction[2] * maxDistance,
+        ];
+        const pad = 2;
+        const min = [
+            Math.min(origin[0], end[0]) - pad,
+            Math.min(origin[1], end[1]) - pad,
+            Math.min(origin[2], end[2]) - pad,
+        ];
+        const max = [
+            Math.max(origin[0], end[0]) + pad,
+            Math.max(origin[1], end[1]) + pad,
+            Math.max(origin[2], end[2]) + pad,
+        ];
+        return objects.inBox(min, max);
+    }
+    return objects.list();
+}
+function gatherHits(deps, input) {
+    const direction = normalizeDirection(input.direction);
+    if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
+        return [];
+    const hits = [];
+    const { origin, maxDistance } = input;
+    if (enabled(input.filter, "entities") && deps.entities !== undefined) {
+        for (const entity of candidateEntityIds(deps.entities, origin, maxDistance)) {
+            if (excluded(input.excludeInstanceIds, entity.id))
+                continue;
+            const set = deps.entities.collidersOf?.(entity.id) ?? defaultEntityColliders();
+            const colliders = resolveColliders(set);
+            pushColliderHits(hits, "entity", entity.id, entity.name, colliders.length > 0 ? colliders : resolveColliders(defaultEntityColliders()), entity.position, entity.rotationY, origin, direction, maxDistance);
+        }
+    }
+    if (enabled(input.filter, "objects") && deps.objects !== undefined) {
+        for (const object of candidateObjects(deps.objects, origin, direction, maxDistance)) {
+            if (excluded(input.excludeInstanceIds, object.instanceId))
+                continue;
+            const half = deps.objects.halfExtentsOf?.(object.catalogId) ?? undefined;
+            const set = deps.objects.collidersOf?.(object.instanceId) ??
+                defaultObjectColliders(half === null || half === undefined ? undefined : half);
+            const colliders = resolveColliders(set);
+            pushColliderHits(hits, "object", object.instanceId, object.catalogId, colliders, object.position, object.rotationY, origin, direction, maxDistance);
+        }
+    }
+    if (enabled(input.filter, "walls") && deps.walls !== undefined) {
+        for (const wall of deps.walls) {
+            if (excluded(input.excludeInstanceIds, wall.id))
+                continue;
+            const box = wallAabb(wall);
+            const hit = intersectAabb(origin, direction, box.min, box.max, maxDistance);
+            if (hit === null)
+                continue;
+            hits.push({
+                targetKind: "wall",
+                instanceId: wall.id,
+                colliderName: "wall",
+                purpose: "physical",
+                damageEligible: false,
+                blocks: true,
+                distance: hit.distance,
+                point: [
+                    origin[0] + direction[0] * hit.distance,
+                    origin[1] + direction[1] * hit.distance,
+                    origin[2] + direction[2] * hit.distance,
+                ],
+                normal: hit.normal,
+            });
+        }
+    }
+    if (enabled(input.filter, "terrain") && deps.terrain !== undefined) {
+        const terrainHit = rayHitsTerrain(origin, direction, maxDistance, deps.terrain);
+        if (terrainHit !== null)
+            hits.push(terrainHit);
+    }
+    hits.sort((a, b) => a.distance - b.distance || a.instanceId.localeCompare(b.instanceId) || a.colliderName.localeCompare(b.colliderName));
+    if (input.accept !== undefined)
+        return hits.filter(input.accept);
+    return hits;
+}
+/** First impact: nearest hit that blocks, or nearest hit if none block. */
+export function firstImpact(hits) {
+    for (const hit of hits) {
+        if (hit.blocks)
+            return hit;
+    }
+    return hits[0] ?? null;
+}
+/** Hits up to and including the first blocking collider (damage hitboxes before a wall stay). */
+export function hitsUntilBlocked(hits) {
+    const out = [];
+    for (const hit of hits) {
+        out.push(hit);
+        if (hit.blocks)
+            break;
+    }
+    return out;
+}
+export function createSceneRaycast(deps) {
+    return {
+        raycast(input) {
+            const hits = gatherHits(deps, input);
+            return firstImpact(hits);
+        },
+        raycastAll(input) {
+            return gatherHits(deps, input);
+        },
+    };
+}

package/dist/scene/spatial.d.ts

@@ -18,10 +18,25 @@ export interface MoveTowardOptions {
     stopDistance?: number;
     dt: number;
 }
+export interface SpatialGridOptions {
+    cellSize: number;
+}
 export interface SpatialApiOptions {
     resolvePosition: (instanceId: string) => EntityPosition | undefined;
-    candidates: () => string[];
+    candidates: () => readonly string[];
+    /**
+     * When omitted, `hasLineOfSight` always returns true for known entities (open-field bypass).
+     * Wire a wall/collision test here for combat LoS; `true` means the segment is blocked.
+     */
     occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
+    /**
+     * Broadphase for `inRadius`/`queryArc`. Defaults to `{ cellSize: 8 }`. Pass `false` to force a
+     * linear scan. When enabled, the index rebuilds lazily on first use after `invalidate()` or when
+     * `getVersion()` advances — call `invalidate()` after moves unless a version source is wired.
+     */
+    grid?: SpatialGridOptions | false;
+    /** When this number changes between queries, the grid rebuilds without an explicit `invalidate()`. */
+    getVersion?: () => number;
 }
 export interface SpatialApi {
     distance(aInstanceId: string, bInstanceId: string): number | null;
@@ -29,6 +44,7 @@ export interface SpatialApi {
     hasLineOfSight(fromInstanceId: string, toInstanceId: string): boolean;
     queryArc(options: QueryArcOptions): string[];
     moveToward(instanceId: string, target: EntityPosition | string, options: MoveTowardOptions): EntityPosition | null;
+    invalidate(): void;
 }
 export declare function distanceBetween(a: EntityPosition, b: EntityPosition): number;
 export declare function createSpatialApi(options: SpatialApiOptions): SpatialApi;