@jgengine/core 0.1.0

package/dist/scene/entityStore.js

@@ -0,0 +1,84 @@
+import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+function toEntityPosition(position) {
+    if (position === undefined)
+        return [0, 0, 0];
+    if ("x" in position)
+        return [position.x, position.y, position.z];
+    return position;
+}
+export function createEntityStore() {
+    const store = createObservableKeyedStore();
+    let nextCounter = 1;
+    function generateId() {
+        let id = `entity-${nextCounter}`;
+        while (store.has(id)) {
+            nextCounter += 1;
+            id = `entity-${nextCounter}`;
+        }
+        nextCounter += 1;
+        return id;
+    }
+    return {
+        spawn(name, options = {}) {
+            if (options.id !== undefined && store.has(options.id)) {
+                throw new Error(`Scene entity id "${options.id}" is already spawned.`);
+            }
+            const id = options.id ?? generateId();
+            store.set(id, {
+                id,
+                name,
+                position: toEntityPosition(options.position),
+                rotationY: options.rotationY ?? 0,
+                rotationX: options.rotationX ?? 0,
+                rotationZ: options.rotationZ ?? 0,
+                role: options.role ?? "prop",
+                movement: options.movement ?? {},
+                behaviors: options.behaviors ?? [],
+                meta: options.meta,
+            });
+            return id;
+        },
+        despawn(id) {
+            const existed = store.has(id);
+            store.delete(id);
+            return existed;
+        },
+        update(id, patch) {
+            const current = store.get(id);
+            if (!current)
+                return false;
+            store.set(id, { ...current, ...patch });
+            return true;
+        },
+        setPose(id, pose) {
+            const current = store.get(id);
+            if (!current)
+                return false;
+            store.set(id, {
+                ...current,
+                position: toEntityPosition(pose.position),
+                rotationY: pose.rotationY ?? current.rotationY,
+                rotationX: pose.rotationX ?? current.rotationX,
+                rotationZ: pose.rotationZ ?? current.rotationZ,
+            });
+            return true;
+        },
+        get(id) {
+            return store.get(id) ?? null;
+        },
+        list() {
+            return store.arraySnapshot();
+        },
+        clear() {
+            for (const entity of store.arraySnapshot()) {
+                store.delete(entity.id);
+            }
+        },
+        subscribe(listener) {
+            return store.subscribe(listener);
+        },
+        snapshot() {
+            return store.arraySnapshot();
+        },
+    };
+}

package/dist/scene/objectStore.d.ts

@@ -0,0 +1,28 @@
+import type { EntityPosition } from "./entityStore.js";
+export interface SceneObject {
+    instanceId: string;
+    catalogId: string;
+    position: EntityPosition;
+    rotationY: number;
+    parentSpace?: string;
+}
+export interface PlaceOptions {
+    instanceId?: string;
+    parentSpace?: string;
+    rotation?: number;
+}
+export interface ObjectListFilter {
+    parentSpace?: string;
+}
+export interface ObjectStore {
+    place(catalogId: string, x: number, y: number, z: number, options?: PlaceOptions): string;
+    remove(instanceId: string): boolean;
+    move(instanceId: string, x: number, y: number, z: number): boolean;
+    rotate(instanceId: string, rotationY: number): boolean;
+    get(instanceId: string): SceneObject | null;
+    list(filter?: ObjectListFilter): readonly SceneObject[];
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): readonly SceneObject[];
+}
+export declare function createObjectStore(): ObjectStore;

package/dist/scene/objectStore.js

@@ -0,0 +1,69 @@
+import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+export function createObjectStore() {
+    const store = createObservableKeyedStore();
+    let nextCounter = 1;
+    function generateId() {
+        let id = `object-${nextCounter}`;
+        while (store.has(id)) {
+            nextCounter += 1;
+            id = `object-${nextCounter}`;
+        }
+        nextCounter += 1;
+        return id;
+    }
+    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 instanceId = options.instanceId ?? generateId();
+            store.set(instanceId, {
+                instanceId,
+                catalogId,
+                position: [x, y, z],
+                rotationY: options.rotation ?? 0,
+                ...(options.parentSpace !== undefined ? { parentSpace: options.parentSpace } : {}),
+            });
+            return instanceId;
+        },
+        remove(instanceId) {
+            const existed = store.has(instanceId);
+            store.delete(instanceId);
+            return existed;
+        },
+        move(instanceId, x, y, z) {
+            const current = store.get(instanceId);
+            if (!current)
+                return false;
+            store.set(instanceId, { ...current, position: [x, y, z] });
+            return true;
+        },
+        rotate(instanceId, rotationY) {
+            const current = store.get(instanceId);
+            if (!current)
+                return false;
+            store.set(instanceId, { ...current, rotationY });
+            return true;
+        },
+        get(instanceId) {
+            return store.get(instanceId) ?? null;
+        },
+        list(filter) {
+            const all = store.arraySnapshot();
+            if (filter?.parentSpace === undefined)
+                return all;
+            return all.filter((object) => object.parentSpace === filter.parentSpace);
+        },
+        clear() {
+            for (const object of store.arraySnapshot()) {
+                store.delete(object.instanceId);
+            }
+        },
+        subscribe(listener) {
+            return store.subscribe(listener);
+        },
+        snapshot() {
+            return store.arraySnapshot();
+        },
+    };
+}

package/dist/scene/spatial.d.ts

@@ -0,0 +1,34 @@
+import type { EntityPosition } from "./entityStore.js";
+export type Aim = {
+    origin: EntityPosition;
+    direction: EntityPosition;
+} | {
+    yaw: number;
+    pitch: number;
+    spread?: number;
+};
+export interface QueryArcOptions {
+    from: string;
+    aim: Aim;
+    radius: number;
+    halfAngleDeg?: number;
+}
+export interface MoveTowardOptions {
+    speed: number;
+    stopDistance?: number;
+    dt: number;
+}
+export interface SpatialApiOptions {
+    resolvePosition: (instanceId: string) => EntityPosition | undefined;
+    candidates: () => string[];
+    occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
+}
+export interface SpatialApi {
+    distance(aInstanceId: string, bInstanceId: string): number | null;
+    inRadius(center: EntityPosition | string, radius: number, filter?: (instanceId: string) => boolean): string[];
+    hasLineOfSight(fromInstanceId: string, toInstanceId: string): boolean;
+    queryArc(options: QueryArcOptions): string[];
+    moveToward(instanceId: string, target: EntityPosition | string, options: MoveTowardOptions): EntityPosition | null;
+}
+export declare function distanceBetween(a: EntityPosition, b: EntityPosition): number;
+export declare function createSpatialApi(options: SpatialApiOptions): SpatialApi;

package/dist/scene/spatial.js

@@ -0,0 +1,96 @@
+export function distanceBetween(a, b) {
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    const dz = b[2] - a[2];
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+function forwardXZ(aim) {
+    if ("origin" in aim) {
+        const [x, , z] = aim.direction;
+        const length = Math.sqrt(x * x + z * z);
+        if (length === 0)
+            return null;
+        return [x / length, z / length];
+    }
+    return [Math.sin(aim.yaw), Math.cos(aim.yaw)];
+}
+export function createSpatialApi(options) {
+    const { resolvePosition, candidates, occluder } = options;
+    function resolveTarget(target) {
+        return typeof target === "string" ? resolvePosition(target) : target;
+    }
+    return {
+        distance(aInstanceId, bInstanceId) {
+            const a = resolvePosition(aInstanceId);
+            const b = resolvePosition(bInstanceId);
+            if (a === undefined || b === undefined)
+                return null;
+            return distanceBetween(a, b);
+        },
+        inRadius(center, radius, filter) {
+            const centerId = typeof center === "string" ? center : null;
+            const centerPosition = resolveTarget(center);
+            if (centerPosition === undefined)
+                return [];
+            return candidates().filter((instanceId) => {
+                if (instanceId === centerId)
+                    return false;
+                if (filter !== undefined && !filter(instanceId))
+                    return false;
+                const position = resolvePosition(instanceId);
+                return position !== undefined && distanceBetween(centerPosition, position) <= radius;
+            });
+        },
+        hasLineOfSight(fromInstanceId, toInstanceId) {
+            const from = resolvePosition(fromInstanceId);
+            const to = resolvePosition(toInstanceId);
+            if (from === undefined || to === undefined)
+                return false;
+            if (occluder === undefined)
+                return true;
+            return !occluder(from, to);
+        },
+        queryArc({ from, aim, radius, halfAngleDeg = 60 }) {
+            const origin = "origin" in aim ? aim.origin : resolvePosition(from);
+            if (origin === undefined)
+                return [];
+            const forward = forwardXZ(aim);
+            if (forward === null)
+                return [];
+            const minDot = Math.cos((halfAngleDeg * Math.PI) / 180);
+            return candidates().filter((instanceId) => {
+                if (instanceId === from)
+                    return false;
+                const position = resolvePosition(instanceId);
+                if (position === undefined)
+                    return false;
+                const dx = position[0] - origin[0];
+                const dz = position[2] - origin[2];
+                const planarDistance = Math.sqrt(dx * dx + dz * dz);
+                if (planarDistance > radius)
+                    return false;
+                if (planarDistance === 0)
+                    return true;
+                const dot = (forward[0] * dx + forward[1] * dz) / planarDistance;
+                return dot >= minDot;
+            });
+        },
+        moveToward(instanceId, target, { speed, stopDistance = 0, dt }) {
+            const current = resolvePosition(instanceId);
+            const destination = resolveTarget(target);
+            if (current === undefined || destination === undefined)
+                return null;
+            const total = distanceBetween(current, destination);
+            const remaining = total - stopDistance;
+            if (remaining <= 0)
+                return current;
+            const step = Math.min(speed * dt, remaining);
+            const scale = step / total;
+            return [
+                current[0] + (destination[0] - current[0]) * scale,
+                current[1] + (destination[1] - current[1]) * scale,
+                current[2] + (destination[2] - current[2]) * scale,
+            ];
+        },
+    };
+}

package/dist/scene/targeting.d.ts

@@ -0,0 +1,20 @@
+export type TargetRelation = "hostile" | "friendly";
+export type TargetFilter = TargetRelation | "any";
+export interface TargetingOptions {
+    candidates: () => string[];
+    classify?: (fromId: string, toId: string) => TargetRelation;
+    orderBy?: (a: string, b: string) => number;
+    distance?: (fromId: string, toId: string) => number | null;
+}
+export interface CycleTargetOptions {
+    filter?: TargetFilter;
+    direction?: "next" | "prev";
+    maxDistance?: number;
+}
+export interface Targeting {
+    setTarget(fromId: string, toId: string | null): void;
+    getTarget(fromId: string): string | null;
+    cycleTarget(fromId: string, options?: CycleTargetOptions): string | null;
+    clearAll(instanceId: string): void;
+}
+export declare function createTargeting(options: TargetingOptions): Targeting;

package/dist/scene/targeting.js

@@ -0,0 +1,56 @@
+export function createTargeting(options) {
+    const targets = new Map();
+    function eligibleCandidates(fromId, filter, maxDistance) {
+        const candidates = options.candidates().filter((id) => id !== fromId);
+        const filtered = filter === "any" || options.classify === undefined
+            ? candidates
+            : candidates.filter((id) => options.classify(fromId, id) === filter);
+        const inRange = maxDistance === undefined || options.distance === undefined
+            ? filtered
+            : filtered.filter((id) => {
+                const distance = options.distance(fromId, id);
+                return distance !== null && distance <= maxDistance;
+            });
+        if (options.orderBy === undefined)
+            return inRange;
+        return inRange.slice().sort(options.orderBy);
+    }
+    return {
+        setTarget(fromId, toId) {
+            if (toId === null)
+                targets.delete(fromId);
+            else
+                targets.set(fromId, toId);
+        },
+        getTarget(fromId) {
+            return targets.get(fromId) ?? null;
+        },
+        cycleTarget(fromId, cycleOptions = {}) {
+            const candidates = eligibleCandidates(fromId, cycleOptions.filter ?? "any", cycleOptions.maxDistance);
+            if (candidates.length === 0) {
+                targets.delete(fromId);
+                return null;
+            }
+            const direction = cycleOptions.direction ?? "next";
+            const currentIndex = candidates.indexOf(targets.get(fromId) ?? "");
+            let nextIndex;
+            if (currentIndex === -1) {
+                nextIndex = direction === "next" ? 0 : candidates.length - 1;
+            }
+            else {
+                const step = direction === "next" ? 1 : -1;
+                nextIndex = (currentIndex + step + candidates.length) % candidates.length;
+            }
+            const target = candidates[nextIndex];
+            targets.set(fromId, target);
+            return target;
+        },
+        clearAll(instanceId) {
+            targets.delete(instanceId);
+            for (const [fromId, toId] of targets) {
+                if (toId === instanceId)
+                    targets.delete(fromId);
+            }
+        },
+    };
+}

package/dist/stats/statModifiers.d.ts

@@ -0,0 +1,18 @@
+export interface StatModifier {
+    add?: number;
+    multiply?: number;
+}
+export type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatModifier>>;
+export interface Stats<TStat extends string> {
+    setBase(stat: TStat, value: number): void;
+    getBase(stat: TStat): number;
+    addSource(sourceId: string, modifiers: StatModifierSet<TStat>, options?: {
+        expiresAtMs?: number;
+    }): void;
+    removeSource(sourceId: string): void;
+    hasSource(sourceId: string): boolean;
+    get(stat: TStat, nowMs?: number): number;
+    pruneExpired(nowMs: number): string[];
+    sources(): string[];
+}
+export declare function createStats<TStat extends string>(base: Record<TStat, number>): Stats<TStat>;

package/dist/stats/statModifiers.js

@@ -0,0 +1,56 @@
+export function createStats(base) {
+    const baseValues = { ...base };
+    const sourceEntries = new Map();
+    function isExpired(entry, nowMs) {
+        return nowMs !== undefined && entry.expiresAtMs !== undefined && entry.expiresAtMs <= nowMs;
+    }
+    function resolve(stat, nowMs) {
+        let total = baseValues[stat];
+        let multiplier = 1;
+        for (const entry of sourceEntries.values()) {
+            if (isExpired(entry, nowMs))
+                continue;
+            const modifier = entry.modifiers[stat];
+            if (!modifier)
+                continue;
+            if (modifier.add !== undefined)
+                total += modifier.add;
+            if (modifier.multiply !== undefined)
+                multiplier *= modifier.multiply;
+        }
+        return total * multiplier;
+    }
+    return {
+        setBase(stat, value) {
+            baseValues[stat] = value;
+        },
+        getBase(stat) {
+            return baseValues[stat];
+        },
+        addSource(sourceId, modifiers, options) {
+            sourceEntries.set(sourceId, { modifiers, expiresAtMs: options?.expiresAtMs });
+        },
+        removeSource(sourceId) {
+            sourceEntries.delete(sourceId);
+        },
+        hasSource(sourceId) {
+            return sourceEntries.has(sourceId);
+        },
+        get(stat, nowMs) {
+            return resolve(stat, nowMs);
+        },
+        pruneExpired(nowMs) {
+            const pruned = [];
+            for (const [sourceId, entry] of sourceEntries) {
+                if (isExpired(entry, nowMs)) {
+                    sourceEntries.delete(sourceId);
+                    pruned.push(sourceId);
+                }
+            }
+            return pruned;
+        },
+        sources() {
+            return Array.from(sourceEntries.keys());
+        },
+    };
+}

package/dist/store/changeSignal.d.ts

@@ -0,0 +1,7 @@
+export interface ChangeSignal {
+    subscribe(listener: () => void): () => void;
+    notify(): void;
+    version(): number;
+}
+export declare function createChangeSignal(): ChangeSignal;
+export declare function notifyAfter<T extends object, K extends keyof T>(target: T, methods: readonly K[], notify: () => void): T;

package/dist/store/changeSignal.js

@@ -0,0 +1,32 @@
+export function createChangeSignal() {
+    const listeners = new Set();
+    let version = 0;
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        notify() {
+            version += 1;
+            for (const listener of listeners)
+                listener();
+        },
+        version() {
+            return version;
+        },
+    };
+}
+export function notifyAfter(target, methods, notify) {
+    const wrapped = { ...target };
+    for (const method of methods) {
+        const fn = target[method];
+        wrapped[method] = ((...args) => {
+            const result = fn(...args);
+            notify();
+            return result;
+        });
+    }
+    return wrapped;
+}

package/dist/store/engineStore.d.ts

@@ -0,0 +1,22 @@
+export interface EngineStoreConfig<TState, TAction, TEventMap extends object> {
+    initialState: TState;
+    reduce: (state: TState, action: TAction) => TState;
+    derive?: (state: TState) => TState;
+    onTransition?: (previous: TState, next: TState, emit: <K extends keyof TEventMap>(eventName: K, payload: TEventMap[K]) => void) => void;
+}
+export declare class EngineStore<TState, TAction, TEventMap extends object> {
+    private snapshot;
+    private readonly stateListeners;
+    private readonly eventListeners;
+    private readonly reduce;
+    private readonly derive;
+    private readonly onTransition;
+    constructor(config: EngineStoreConfig<TState, TAction, TEventMap>);
+    getState(): TState;
+    subscribe(listener: (state: TState) => void): () => boolean;
+    dispatch(action: TAction): void;
+    on<K extends keyof TEventMap>(eventName: K, listener: (payload: TEventMap[K]) => void): () => boolean;
+    private setState;
+    private emit;
+    private getEventBucket;
+}

package/dist/store/engineStore.js

@@ -0,0 +1,50 @@
+export class EngineStore {
+    snapshot;
+    stateListeners = new Set();
+    eventListeners;
+    reduce;
+    derive;
+    onTransition;
+    constructor(config) {
+        this.snapshot = config.derive ? config.derive(config.initialState) : config.initialState;
+        this.reduce = config.reduce;
+        this.derive = config.derive ?? null;
+        this.onTransition = config.onTransition;
+        this.eventListeners = {};
+    }
+    getState() {
+        return this.snapshot;
+    }
+    subscribe(listener) {
+        this.stateListeners.add(listener);
+        return () => this.stateListeners.delete(listener);
+    }
+    dispatch(action) {
+        this.setState((current) => this.reduce(current, action));
+    }
+    on(eventName, listener) {
+        this.getEventBucket(eventName).add(listener);
+        return () => this.getEventBucket(eventName).delete(listener);
+    }
+    setState(updater) {
+        const previous = this.snapshot;
+        const reduced = updater(previous);
+        const next = this.derive ? this.derive(reduced) : reduced;
+        this.snapshot = next;
+        for (const listener of this.stateListeners)
+            listener(next);
+        this.onTransition?.(previous, next, (eventName, payload) => this.emit(eventName, payload));
+    }
+    emit(eventName, payload) {
+        for (const listener of this.getEventBucket(eventName))
+            listener(payload);
+    }
+    getEventBucket(eventName) {
+        const currentBucket = this.eventListeners[eventName];
+        if (currentBucket !== undefined)
+            return currentBucket;
+        const nextBucket = new Set();
+        this.eventListeners[eventName] = nextBucket;
+        return nextBucket;
+    }
+}

package/dist/store/features.d.ts

@@ -0,0 +1,10 @@
+export interface StateFeature<TState, TAction, TEventMap extends object> {
+    reduce?: (state: TState, action: TAction) => TState;
+    derive?: (state: TState) => TState;
+    onTransition?: (previous: TState, next: TState, emit: <K extends keyof TEventMap>(eventName: K, payload: TEventMap[K]) => void) => void;
+}
+export declare function composeStateFeatures<TState, TAction, TEventMap extends object>(features: readonly StateFeature<TState, TAction, TEventMap>[]): {
+    reduce(state: TState, action: TAction): TState;
+    derive(state: TState): TState;
+    onTransition(previous: TState, next: TState, emit: <K extends keyof TEventMap>(eventName: K, payload: TEventMap[K]) => void): void;
+};

package/dist/store/features.js

@@ -0,0 +1,23 @@
+export function composeStateFeatures(features) {
+    return {
+        reduce(state, action) {
+            let nextState = state;
+            for (const feature of features) {
+                nextState = feature.reduce ? feature.reduce(nextState, action) : nextState;
+            }
+            return nextState;
+        },
+        derive(state) {
+            let nextState = state;
+            for (const feature of features) {
+                nextState = feature.derive ? feature.derive(nextState) : nextState;
+            }
+            return nextState;
+        },
+        onTransition(previous, next, emit) {
+            for (const feature of features) {
+                feature.onTransition?.(previous, next, emit);
+            }
+        },
+    };
+}

package/dist/store/observableKeyedStore.d.ts

@@ -0,0 +1,10 @@
+export interface ObservableKeyedStore<T> {
+    set(key: string, value: T): void;
+    delete(key: string): void;
+    get(key: string): T | undefined;
+    has(key: string): boolean;
+    subscribe(listener: () => void): () => void;
+    mapSnapshot(): ReadonlyMap<string, T>;
+    arraySnapshot(): readonly T[];
+}
+export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>;

package/dist/store/observableKeyedStore.js

@@ -0,0 +1,42 @@
+export function createObservableKeyedStore(areEqual) {
+    const store = new Map();
+    const listeners = new Set();
+    const EMPTY = [];
+    let arrayCache = EMPTY;
+    function emit() {
+        arrayCache = store.size === 0 ? EMPTY : Array.from(store.values());
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        set(key, value) {
+            const previous = store.get(key);
+            if (previous !== undefined && areEqual?.(previous, value))
+                return;
+            store.set(key, value);
+            emit();
+        },
+        delete(key) {
+            if (!store.has(key))
+                return;
+            store.delete(key);
+            emit();
+        },
+        get(key) {
+            return store.get(key);
+        },
+        has(key) {
+            return store.has(key);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        mapSnapshot() {
+            return store;
+        },
+        arraySnapshot() {
+            return arrayCache;
+        },
+    };
+}