@jgengine/core 0.7.0 → 0.9.0

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

@@ -2,6 +2,7 @@ import type { BehaviorDescriptor } from "./behaviors.js";
 export type EntityRole = "player" | "npc" | "prop";
 export interface EntityMovement {
     walkSpeed?: number;
+    frozen?: boolean;
 }
 export type EntityPosition = readonly [number, number, number];
 export type SpawnPositionInput = EntityPosition | {
@@ -9,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;
@@ -21,11 +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 interface SpawnOptions<TMeta = undefined> {
+export declare function movedWhileFrozen(entity: SceneEntity<unknown>, threshold?: number): boolean;
+export interface SpawnOptions<TMeta = unknown> {
     id?: string;
     position?: SpawnPositionInput;
     rotationY?: number;
@@ -35,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;
@@ -44,15 +49,35 @@ export interface EntityPose {
     /** Seconds since the previous pose; when > 0 the store derives `velocity` from the position delta. Omit for teleports (velocity unchanged). */
     dt?: number;
 }
-export interface EntityStore<TMeta = undefined> {
+export interface SpawnPose {
+    position: EntityPosition;
+    rotationY: number;
+}
+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;
     subscribe(listener: () => void): () => void;
     snapshot(): readonly SceneEntity<TMeta>[];
+    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

@@ -3,6 +3,13 @@ import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 export function groundSpeed(entity) {
     return Math.hypot(entity.velocity[0], entity.velocity[2]);
 }
+const DEFAULT_FROZEN_MOVE_THRESHOLD = 1e-6;
+export function movedWhileFrozen(entity, threshold = DEFAULT_FROZEN_MOVE_THRESHOLD) {
+    if (entity.movement.frozen !== true)
+        return false;
+    const speed = Math.hypot(entity.velocity[0], entity.velocity[1], entity.velocity[2]);
+    return speed > threshold;
+}
 function toEntityPosition(position) {
     if (position === undefined)
         return [0, 0, 0];
@@ -12,6 +19,8 @@ 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}`;
@@ -25,14 +34,20 @@ 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);
+            const rotationY = options.rotationY ?? 0;
             store.set(id, {
                 id,
                 name,
-                position: toEntityPosition(options.position),
-                rotationY: options.rotationY ?? 0,
+                position,
+                rotationY,
                 rotationX: options.rotationX ?? 0,
                 rotationZ: options.rotationZ ?? 0,
                 velocity: [0, 0, 0],
@@ -41,25 +56,64 @@ export function createEntityStore() {
                 behaviors: options.behaviors ?? [],
                 meta: options.meta,
             });
+            spawnPoses.set(id, { position, rotationY });
             return id;
         },
         despawn(id) {
             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,
@@ -67,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) {
@@ -87,6 +142,7 @@ export function createEntityStore() {
             for (const entity of store.arraySnapshot()) {
                 store.delete(entity.id);
             }
+            constraints.clear();
         },
         subscribe(listener) {
             return store.subscribe(listener);
@@ -94,5 +150,19 @@ export function createEntityStore() {
         snapshot() {
             return store.arraySnapshot();
         },
+        spawnPoseOf(id) {
+            return spawnPoses.get(id) ?? null;
+        },
+        resetToSpawn(id) {
+            const pose = spawnPoses.get(id);
+            const current = store.get(id);
+            if (pose === undefined || current === undefined)
+                return false;
+            current.position = pose.position;
+            current.rotationY = pose.rotationY;
+            current.velocity = [0, 0, 0];
+            store.set(id, current);
+            return true;
+        },
     };
 }

package/dist/scene/movementSpeed.d.ts

@@ -0,0 +1,35 @@
+import type { StatValue } from "./entityStats.js";
+export interface MovementSpeedModifiers {
+    multiplier?: number;
+    flatBonus?: number;
+}
+/** `base * (multiplier ?? 1) + (flatBonus ?? 0)`, clamped to never go negative. */
+export declare function deriveWalkSpeed(base: number, modifiers: MovementSpeedModifiers): number;
+export interface MovementSpeedDeps {
+    stats: {
+        get(instanceId: string, statId: string): StatValue | null;
+    };
+    entities: {
+        get(id: string): {
+            movement?: {
+                walkSpeed?: number;
+            };
+        } | null;
+        update(id: string, patch: {
+            movement: {
+                walkSpeed: number;
+            };
+        }): boolean;
+    };
+}
+export interface MovementSpeedConfig {
+    baseSpeed: number;
+    multiplierStat?: string;
+    flatBonusStat?: string;
+}
+/**
+ * Recomputes `movement.walkSpeed` for an entity from its stats and writes it back via `deps.entities.update`.
+ * Either stat id is optional; an omitted or unresolved stat contributes its neutral value (multiplier 1,
+ * flat bonus 0) rather than failing. Returns false only when the entity itself doesn't exist.
+ */
+export declare function applyStatDrivenSpeed(deps: MovementSpeedDeps, instanceId: string, config: MovementSpeedConfig): boolean;

package/dist/scene/movementSpeed.js

@@ -0,0 +1,20 @@
+/** `base * (multiplier ?? 1) + (flatBonus ?? 0)`, clamped to never go negative. */
+export function deriveWalkSpeed(base, modifiers) {
+    const multiplier = modifiers.multiplier ?? 1;
+    const flatBonus = modifiers.flatBonus ?? 0;
+    return Math.max(0, base * multiplier + flatBonus);
+}
+/**
+ * Recomputes `movement.walkSpeed` for an entity from its stats and writes it back via `deps.entities.update`.
+ * Either stat id is optional; an omitted or unresolved stat contributes its neutral value (multiplier 1,
+ * flat bonus 0) rather than failing. Returns false only when the entity itself doesn't exist.
+ */
+export function applyStatDrivenSpeed(deps, instanceId, config) {
+    const entity = deps.entities.get(instanceId);
+    if (entity === null)
+        return false;
+    const multiplier = config.multiplierStat !== undefined ? deps.stats.get(instanceId, config.multiplierStat)?.current : undefined;
+    const flatBonus = config.flatBonusStat !== undefined ? deps.stats.get(instanceId, config.flatBonusStat)?.current : undefined;
+    const walkSpeed = deriveWalkSpeed(config.baseSpeed, { multiplier, flatBonus });
+    return deps.entities.update(instanceId, { movement: { ...entity.movement, walkSpeed } });
+}

package/dist/scene/objectQuery.d.ts

@@ -0,0 +1,29 @@
+import type { EntityPosition } from "./entityStore.js";
+import type { SceneObject } from "./objectStore.js";
+export interface ObjectRaycastInput {
+    origin: EntityPosition;
+    direction: EntityPosition;
+    maxDistance: number;
+    halfExtents?: EntityPosition;
+    filter?: (object: SceneObject) => boolean;
+}
+export interface ObjectRaycastHit {
+    instanceId: string;
+    catalogId: string;
+    distance: number;
+    point: EntityPosition;
+    normal: EntityPosition;
+}
+/** 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

@@ -0,0 +1,140 @@
+const DEFAULT_HALF_EXTENTS = [0.5, 0.5, 0.5];
+function normalize(direction) {
+    const length = Math.hypot(direction[0], direction[1], direction[2]);
+    if (length === 0)
+        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;
+    let normalAxis = -1;
+    let normalSign = 0;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const originAxis = origin[axis];
+        const dirAxis = direction[axis];
+        const minAxis = min[axis];
+        const maxAxis = max[axis];
+        if (Math.abs(dirAxis) < 1e-12) {
+            if (originAxis < minAxis || originAxis > maxAxis)
+                return null;
+            continue;
+        }
+        const invD = 1 / dirAxis;
+        const t1 = (minAxis - originAxis) * invD;
+        const t2 = (maxAxis - originAxis) * invD;
+        const minIsNear = t1 <= t2;
+        const tNearAxis = minIsNear ? t1 : t2;
+        const tFarAxis = minIsNear ? t2 : t1;
+        const nearFaceSign = minIsNear ? -1 : 1;
+        if (tNearAxis > tMin) {
+            tMin = tNearAxis;
+            normalAxis = axis;
+            normalSign = nearFaceSign;
+        }
+        tMax = Math.min(tMax, tFarAxis);
+        if (tMin > tMax)
+            return null;
+    }
+    if (tMin > maxDistance || tMin < 0)
+        return null;
+    const normal = normalAxis === 0
+        ? [normalSign, 0, 0]
+        : normalAxis === 1
+            ? [0, normalSign, 0]
+            : normalAxis === 2
+                ? [0, 0, normalSign]
+                : [0, 1, 0];
+    return { distance: tMin, normal };
+}
+function hitFor(object, origin, direction, halfExtents, maxDistance) {
+    const min = [
+        object.position[0] - halfExtents[0],
+        object.position[1] - halfExtents[1],
+        object.position[2] - halfExtents[2],
+    ];
+    const max = [
+        object.position[0] + halfExtents[0],
+        object.position[1] + halfExtents[1],
+        object.position[2] + halfExtents[2],
+    ];
+    const hit = intersectAabb(origin, direction, min, max, maxDistance);
+    if (hit === null)
+        return null;
+    return {
+        instanceId: object.instanceId,
+        catalogId: object.catalogId,
+        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,
+    };
+}
+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))
+            continue;
+        const hit = hitFor(object, input.origin, direction, halfExtents, input.maxDistance);
+        if (hit === null)
+            continue;
+        if (nearest === null || hit.distance < nearest.distance)
+            nearest = hit;
+    }
+    return nearest;
+}
+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))
+            continue;
+        const hit = hitFor(object, input.origin, direction, halfExtents, input.maxDistance);
+        if (hit !== null)
+            hits.push(hit);
+    }
+    hits.sort((a, b) => a.distance - b.distance);
+    return hits;
+}
+export { intersectAabb, normalize as normalizeDirection };

package/dist/scene/objectStore.d.ts

@@ -1,15 +1,24 @@
 import type { EntityPosition } from "./entityStore.js";
+export interface ObjectVisual {
+    scale?: number | readonly [number, number, number];
+    color?: string;
+    opacity?: number;
+}
 export interface SceneObject {
     instanceId: string;
     catalogId: string;
     position: EntityPosition;
     rotationY: number;
     parentSpace?: string;
+    visual?: ObjectVisual;
 }
 export interface PlaceOptions {
     instanceId?: string;
     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;
@@ -19,10 +28,14 @@ export interface ObjectStore {
     remove(instanceId: string): boolean;
     move(instanceId: string, x: number, y: number, z: number): boolean;
     rotate(instanceId: string, rotationY: number): boolean;
+    setVisual(instanceId: string, visual: ObjectVisual | undefined): boolean;
     get(instanceId: string): SceneObject | null;
     list(filter?: ObjectListFilter): readonly SceneObject[];
+    at(x: number, y: number, z: number, tolerance?: number): SceneObject[];
+    inBox(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
     clear(): void;
     subscribe(listener: () => void): () => void;
     snapshot(): readonly SceneObject[];
 }
 export declare function createObjectStore(): ObjectStore;
+export declare function objectVisualScale(visual: ObjectVisual | undefined): readonly [number, number, number];