@jgengine/core 0.6.0 → 0.7.0

package/dist/sensor/frustumSensor.d.ts

@@ -0,0 +1,60 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+export interface FrustumCamera {
+    position: EntityPosition;
+    lookAt: EntityPosition;
+    /** Vertical field of view in degrees. Default 55. */
+    fovDeg?: number;
+    /** Width / height. Default 16 / 9. */
+    aspect?: number;
+    near?: number;
+    far?: number;
+}
+export interface FrustumTarget {
+    id: string;
+    position: EntityPosition;
+    /** Subject radius in world units, used by the framing-size score. Default 0.5. */
+    radius?: number;
+}
+export interface FrustumProjection {
+    inView: boolean;
+    distance: number;
+    /** -1..1, 0 = screen center, negative = left/down. */
+    screenX: number;
+    screenY: number;
+}
+/**
+ * Project a world point into the camera's view. Pure geometry — no three.js —
+ * so a game can run "is this framed?" checks headlessly (photo-mode scoring,
+ * server-side kill-cam validation) as well as from the live render camera.
+ */
+export declare function projectToView(camera: FrustumCamera, point: EntityPosition): FrustumProjection;
+export interface FramingConfig {
+    /** World-unit distance from camera that reads as "ideally framed" size. Default 6. */
+    idealDistance?: number;
+    /** Weight of screen-center placement in the framing score. Default 0.6. */
+    centerWeight?: number;
+    /** Weight of subject size (distance-to-ideal) in the framing score. Default 0.4. */
+    sizeWeight?: number;
+}
+/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection. */
+export declare function framingScore(projection: FrustumProjection, config?: FramingConfig): number;
+export interface FrustumSample {
+    id: string;
+    inView: boolean;
+    distance: number;
+    screenX: number;
+    screenY: number;
+    framing: number;
+    /** Seconds continuously in view, up to and including this tick; resets to 0 the instant the subject leaves view. */
+    dwellSeconds: number;
+}
+export interface FrustumSensor {
+    tick(camera: FrustumCamera, targets: readonly FrustumTarget[], dt: number): FrustumSample[];
+    reset(id?: string): void;
+}
+/**
+ * A view-frustum sensor on a held camera object: which entities are in frame,
+ * how well framed they are, and how long they've stayed on-screen (photo-mode
+ * "is this subject framed", Content Warning-style monster-filming scoring).
+ */
+export declare function createFrustumSensor(config?: FramingConfig): FrustumSensor;

package/dist/sensor/frustumSensor.js

@@ -0,0 +1,104 @@
+function subtract(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function length(v) {
+    return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+}
+function normalize(v) {
+    const len = length(v);
+    return len === 0 ? [0, 0, 0] : [v[0] / len, v[1] / len, v[2] / len];
+}
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+const WORLD_UP = [0, 1, 0];
+/**
+ * Project a world point into the camera's view. Pure geometry — no three.js —
+ * so a game can run "is this framed?" checks headlessly (photo-mode scoring,
+ * server-side kill-cam validation) as well as from the live render camera.
+ */
+export function projectToView(camera, point) {
+    const forward = normalize(subtract(camera.lookAt, camera.position));
+    const relative = subtract(point, camera.position);
+    const distance = length(relative);
+    const depth = dot(relative, forward);
+    const near = camera.near ?? 0.1;
+    const far = camera.far ?? Number.POSITIVE_INFINITY;
+    if (forward[0] === 0 && forward[1] === 0 && forward[2] === 0) {
+        return { inView: false, distance, screenX: 0, screenY: 0 };
+    }
+    if (depth <= near || depth >= far) {
+        return { inView: false, distance, screenX: 0, screenY: 0 };
+    }
+    let right = normalize(cross(forward, WORLD_UP));
+    if (right[0] === 0 && right[1] === 0 && right[2] === 0) {
+        right = normalize(cross(forward, [1, 0, 0]));
+    }
+    const up = cross(right, forward);
+    const fovDeg = camera.fovDeg ?? 55;
+    const aspect = camera.aspect ?? 16 / 9;
+    const halfHeight = Math.tan((fovDeg * Math.PI) / 360);
+    const halfWidth = halfHeight * aspect;
+    const screenX = dot(relative, right) / (depth * halfWidth);
+    const screenY = dot(relative, up) / (depth * halfHeight);
+    const inView = Math.abs(screenX) <= 1 && Math.abs(screenY) <= 1;
+    return { inView, distance, screenX, screenY };
+}
+/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection. */
+export function framingScore(projection, config) {
+    if (!projection.inView)
+        return 0;
+    const idealDistance = config?.idealDistance ?? 6;
+    const centerWeight = config?.centerWeight ?? 0.6;
+    const sizeWeight = config?.sizeWeight ?? 0.4;
+    const radial = Math.min(1, Math.sqrt(projection.screenX * projection.screenX + projection.screenY * projection.screenY));
+    const centerScore = 1 - radial;
+    const sizeScore = idealDistance <= 0
+        ? 0
+        : Math.max(0, 1 - Math.abs(projection.distance - idealDistance) / idealDistance);
+    return Math.max(0, Math.min(1, centerWeight * centerScore + sizeWeight * sizeScore));
+}
+/**
+ * A view-frustum sensor on a held camera object: which entities are in frame,
+ * how well framed they are, and how long they've stayed on-screen (photo-mode
+ * "is this subject framed", Content Warning-style monster-filming scoring).
+ */
+export function createFrustumSensor(config) {
+    const dwell = new Map();
+    return {
+        tick(camera, targets, dt) {
+            const seen = new Set();
+            const samples = [];
+            for (const target of targets) {
+                seen.add(target.id);
+                const projection = projectToView(camera, target.position);
+                const framing = framingScore(projection, config);
+                const nextDwell = projection.inView ? (dwell.get(target.id) ?? 0) + dt : 0;
+                dwell.set(target.id, nextDwell);
+                samples.push({
+                    id: target.id,
+                    inView: projection.inView,
+                    distance: projection.distance,
+                    screenX: projection.screenX,
+                    screenY: projection.screenY,
+                    framing,
+                    dwellSeconds: nextDwell,
+                });
+            }
+            for (const id of dwell.keys()) {
+                if (!seen.has(id))
+                    dwell.delete(id);
+            }
+            return samples;
+        },
+        reset(id) {
+            if (id === undefined)
+                dwell.clear();
+            else
+                dwell.delete(id);
+        },
+    };
+}

package/dist/sensor/hiddenStateProbe.d.ts

@@ -0,0 +1,31 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+export type HiddenStateValue = number | string | boolean;
+export interface HiddenStateSource {
+    id: string;
+    position: EntityPosition;
+    variables: Readonly<Record<string, HiddenStateValue>>;
+}
+export interface SensorProbeOptions {
+    range: number;
+    variableId: string;
+    /** How reading `strength` falls off with distance. Default "linear". */
+    falloff?: "linear" | "none";
+}
+export interface SensorReading {
+    sourceId: string;
+    variableId: string;
+    value: HiddenStateValue;
+    /** 1 at the source, 0 at the edge of `range` ("none" falloff always reads 1 in range). */
+    strength: number;
+    distance: number;
+}
+/**
+ * A sensor verb: probe a hidden zone/entity state variable in range and surface
+ * a reading (EMF reader, spirit box, thermometer, geiger counter). Unlike
+ * `proximityPrompt` (a UI affordance), this reads world state the player has no
+ * other way to see — the strongest in-range reading wins, mirroring how a real
+ * handheld sensor needle settles on the loudest nearby source.
+ */
+export declare function probeHiddenState(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading | null;
+/** All in-range readings for `variableId`, strongest first. */
+export declare function probeHiddenStateAll(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading[];

package/dist/sensor/hiddenStateProbe.js

@@ -0,0 +1,40 @@
+import { distanceBetween } from "../scene/spatial.js";
+function strengthAt(distance, range, falloff) {
+    if (falloff === "none")
+        return 1;
+    if (range <= 0)
+        return 0;
+    return Math.max(0, 1 - distance / range);
+}
+/**
+ * A sensor verb: probe a hidden zone/entity state variable in range and surface
+ * a reading (EMF reader, spirit box, thermometer, geiger counter). Unlike
+ * `proximityPrompt` (a UI affordance), this reads world state the player has no
+ * other way to see — the strongest in-range reading wins, mirroring how a real
+ * handheld sensor needle settles on the loudest nearby source.
+ */
+export function probeHiddenState(origin, sources, options) {
+    const readings = probeHiddenStateAll(origin, sources, options);
+    return readings.length === 0 ? null : readings[0];
+}
+/** All in-range readings for `variableId`, strongest first. */
+export function probeHiddenStateAll(origin, sources, options) {
+    const { range, variableId, falloff = "linear" } = options;
+    const readings = [];
+    for (const source of sources) {
+        if (!(variableId in source.variables))
+            continue;
+        const distance = distanceBetween(origin, source.position);
+        if (distance > range)
+            continue;
+        readings.push({
+            sourceId: source.id,
+            variableId,
+            value: source.variables[variableId],
+            strength: strengthAt(distance, range, falloff),
+            distance,
+        });
+    }
+    readings.sort((a, b) => b.strength - a.strength);
+    return readings;
+}

package/dist/sensor/recordingBuffer.d.ts

@@ -0,0 +1,29 @@
+export interface RecordingFrame<T> {
+    /** Game-time seconds (from `ctx.time`), so pause/fast-forward scrub the recording consistently with the sim. */
+    t: number;
+    data: T;
+}
+export interface RecordingBufferOptions {
+    /** Evict frames older than `latestT - maxDurationSeconds`. Default unlimited. */
+    maxDurationSeconds?: number;
+    /** Hard cap on frame count, oldest evicted first. Default unlimited. */
+    maxFrames?: number;
+}
+export interface RecordingBuffer<T> {
+    append(t: number, data: T): void;
+    /** Nearest frame at or before `t`, or null if the buffer is empty or `t` precedes every frame. */
+    seek(t: number): RecordingFrame<T> | null;
+    /** Frames with `fromT <= t <= toT`, in recorded order. */
+    range(fromT: number, toT: number): RecordingFrame<T>[];
+    clear(): void;
+    duration(): number;
+    frames(): readonly RecordingFrame<T>[];
+}
+/**
+ * A session-recording buffer for replay / photo mode / kill-cam: append
+ * timestamped snapshots (poses, camera state, whatever `T` is) on game-time,
+ * then seek/scrub the recording independent of the live sim. Frames are
+ * expected in non-decreasing `t` order (one push per tick); `seek`/`range`
+ * binary-search on that assumption.
+ */
+export declare function createRecordingBuffer<T>(options?: RecordingBufferOptions): RecordingBuffer<T>;

package/dist/sensor/recordingBuffer.js

@@ -0,0 +1,61 @@
+function evict(frames, options) {
+    if (options.maxDurationSeconds !== undefined && frames.length > 0) {
+        const cutoff = frames[frames.length - 1].t - options.maxDurationSeconds;
+        let dropTo = 0;
+        while (dropTo < frames.length && frames[dropTo].t < cutoff)
+            dropTo += 1;
+        if (dropTo > 0)
+            frames.splice(0, dropTo);
+    }
+    if (options.maxFrames !== undefined && frames.length > options.maxFrames) {
+        frames.splice(0, frames.length - options.maxFrames);
+    }
+}
+/**
+ * A session-recording buffer for replay / photo mode / kill-cam: append
+ * timestamped snapshots (poses, camera state, whatever `T` is) on game-time,
+ * then seek/scrub the recording independent of the live sim. Frames are
+ * expected in non-decreasing `t` order (one push per tick); `seek`/`range`
+ * binary-search on that assumption.
+ */
+export function createRecordingBuffer(options = {}) {
+    const frames = [];
+    function floorIndex(t) {
+        let lo = 0;
+        let hi = frames.length - 1;
+        let result = -1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            if (frames[mid].t <= t) {
+                result = mid;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return result;
+    }
+    return {
+        append(t, data) {
+            frames.push({ t, data });
+            evict(frames, options);
+        },
+        seek(t) {
+            const index = floorIndex(t);
+            return index === -1 ? null : frames[index];
+        },
+        range(fromT, toT) {
+            return frames.filter((frame) => frame.t >= fromT && frame.t <= toT);
+        },
+        clear() {
+            frames.length = 0;
+        },
+        duration() {
+            return frames.length === 0 ? 0 : frames[frames.length - 1].t - frames[0].t;
+        },
+        frames() {
+            return frames;
+        },
+    };
+}

package/dist/sensor/revealQuery.d.ts

@@ -0,0 +1,22 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+export interface RevealHit {
+    instanceId: string;
+    distance: number;
+    tags: readonly string[];
+}
+export interface RevealQueryOptions {
+    resolvePosition: (instanceId: string) => EntityPosition | undefined;
+    resolveTags: (instanceId: string) => readonly string[];
+    candidates: () => string[];
+}
+export interface RevealQuery {
+    inRadius(center: EntityPosition | string, radius: number, tags: readonly string[]): RevealHit[];
+}
+/**
+ * `inRadius` already ignores occlusion; combat's AoE resolution is what layers a
+ * line-of-sight filter on top of it (see `effect({ at, radius, los })`). This is
+ * the same unfiltered radius query, scoped to catalog-declared tags and shaped
+ * for a vision readout (Dark Sight / detective-vision reveal) instead of damage
+ * resolution — it never consults an occluder, by design.
+ */
+export declare function createRevealQuery(options: RevealQueryOptions): RevealQuery;

package/dist/sensor/revealQuery.js

@@ -0,0 +1,36 @@
+import { distanceBetween } from "../scene/spatial.js";
+/**
+ * `inRadius` already ignores occlusion; combat's AoE resolution is what layers a
+ * line-of-sight filter on top of it (see `effect({ at, radius, los })`). This is
+ * the same unfiltered radius query, scoped to catalog-declared tags and shaped
+ * for a vision readout (Dark Sight / detective-vision reveal) instead of damage
+ * resolution — it never consults an occluder, by design.
+ */
+export function createRevealQuery(options) {
+    const { resolvePosition, resolveTags, candidates } = options;
+    return {
+        inRadius(center, radius, tags) {
+            const centerId = typeof center === "string" ? center : null;
+            const centerPosition = typeof center === "string" ? resolvePosition(center) : center;
+            if (centerPosition === undefined)
+                return [];
+            const hits = [];
+            for (const instanceId of candidates()) {
+                if (instanceId === centerId)
+                    continue;
+                const position = resolvePosition(instanceId);
+                if (position === undefined)
+                    continue;
+                const distance = distanceBetween(centerPosition, position);
+                if (distance > radius)
+                    continue;
+                const entityTags = resolveTags(instanceId);
+                if (tags.length > 0 && !tags.some((tag) => entityTags.includes(tag)))
+                    continue;
+                hits.push({ instanceId, distance, tags: entityTags });
+            }
+            hits.sort((a, b) => a.distance - b.distance);
+            return hits;
+        },
+    };
+}

package/dist/session/contestedChannel.d.ts

@@ -0,0 +1,36 @@
+export type ContestedPhase = "idle" | "active" | "paused" | "contested" | "complete" | "interrupted";
+export type ContestReaction = "pause" | "decay";
+export interface ContestedChannelConfig {
+    duration: number;
+    interruptOnDamage?: boolean;
+    resetOnInterrupt?: boolean;
+    favorability?: Record<string, number>;
+    ratePerOccupant?: boolean;
+    contested?: ContestReaction;
+    decayRate?: number;
+}
+export type ContestedEventKind = "start" | "tick" | "contested" | "paused" | "complete" | "interrupted";
+export interface ContestedEvent {
+    kind: ContestedEventKind;
+    owner: string | null;
+    progress: number;
+    reason?: string;
+}
+export interface ContestedSnapshot {
+    phase: ContestedPhase;
+    progress: number;
+    owner: string | null;
+    remaining: number;
+}
+export interface ContestedChannel {
+    start(team: string): ContestedEvent | null;
+    tick(dt: number, occupants?: Record<string, number>): ContestedEvent[];
+    damage(reason?: string): ContestedEvent | null;
+    reset(): void;
+    progress(): number;
+    phase(): ContestedPhase;
+    owner(): string | null;
+    remaining(): number;
+    snapshot(): ContestedSnapshot;
+}
+export declare function createContestedChannel(config: ContestedChannelConfig): ContestedChannel;

package/dist/session/contestedChannel.js

@@ -0,0 +1,100 @@
+function occupantsOf(occupants, team) {
+    return occupants?.[team] ?? 0;
+}
+function anyContester(occupants, owner) {
+    if (occupants === undefined)
+        return false;
+    for (const [team, count] of Object.entries(occupants)) {
+        if (team !== owner && count > 0)
+            return true;
+    }
+    return false;
+}
+export function createContestedChannel(config) {
+    const duration = config.duration > 0 ? config.duration : Number.EPSILON;
+    const interruptOnDamage = config.interruptOnDamage ?? true;
+    const resetOnInterrupt = config.resetOnInterrupt ?? false;
+    const favorability = config.favorability ?? {};
+    const contested = config.contested ?? "pause";
+    const decayRate = config.decayRate !== undefined ? Math.abs(config.decayRate) : 1 / duration;
+    let phase = "idle";
+    let progress = 0;
+    let owner = null;
+    function fillRate(occupantCount) {
+        const multiplier = favorability[owner ?? ""] ?? 1;
+        const scale = config.ratePerOccupant ? Math.max(1, occupantCount) : 1;
+        return (multiplier * scale) / duration;
+    }
+    function snapshot() {
+        return { phase, progress, owner, remaining: Math.max(0, (1 - progress) * duration) };
+    }
+    function emit(kind, reason) {
+        const event = { kind, owner, progress };
+        if (reason !== undefined)
+            event.reason = reason;
+        return event;
+    }
+    return {
+        start(team) {
+            if (phase === "active" || phase === "contested" || phase === "paused")
+                return null;
+            owner = team;
+            progress = phase === "interrupted" && !resetOnInterrupt ? progress : 0;
+            phase = "active";
+            return emit("start");
+        },
+        tick(dt, occupants) {
+            if (dt <= 0)
+                return [];
+            if (phase !== "active" && phase !== "paused" && phase !== "contested")
+                return [];
+            if (owner === null)
+                return [];
+            const ownerCount = occupantsOf(occupants, owner);
+            if (occupants !== undefined && ownerCount <= 0) {
+                if (phase !== "paused") {
+                    phase = "paused";
+                    return [emit("paused", "owner-left")];
+                }
+                return [];
+            }
+            if (anyContester(occupants, owner)) {
+                if (contested === "pause") {
+                    const changed = phase !== "contested";
+                    phase = "contested";
+                    return changed ? [emit("contested")] : [];
+                }
+                progress = Math.max(0, progress - decayRate * dt);
+                phase = "contested";
+                return [emit("contested")];
+            }
+            phase = "active";
+            progress = Math.min(1, progress + fillRate(ownerCount) * dt);
+            if (progress >= 1) {
+                phase = "complete";
+                return [emit("tick"), emit("complete")];
+            }
+            return [emit("tick")];
+        },
+        damage(reason) {
+            if (phase !== "active" && phase !== "paused" && phase !== "contested")
+                return null;
+            if (!interruptOnDamage)
+                return null;
+            phase = "interrupted";
+            if (resetOnInterrupt)
+                progress = 0;
+            return emit("interrupted", reason ?? "damage");
+        },
+        reset() {
+            phase = "idle";
+            progress = 0;
+            owner = null;
+        },
+        progress: () => progress,
+        phase: () => phase,
+        owner: () => owner,
+        remaining: () => Math.max(0, (1 - progress) * duration),
+        snapshot,
+    };
+}

package/dist/session/extraction.d.ts

@@ -0,0 +1,54 @@
+import { type ConsolationPolicy, type ContainerSnapshot, type DeliveryEntry, type DeliveryQueue, type InsurancePolicy, type ItemStack } from "../inventory/storageTier.js";
+import { type ContestedChannel, type ContestedEvent } from "./contestedChannel.js";
+import type { RingPoint } from "./ring.js";
+export interface ExtractPoint {
+    id: string;
+    center: RingPoint;
+    radius: number;
+    holdSeconds: number;
+    favorability?: Record<string, number>;
+    interruptOnDamage?: boolean;
+}
+export interface RaidSessionConfig {
+    extracts: readonly ExtractPoint[];
+    insurance?: InsurancePolicy;
+    consolation?: ConsolationPolicy;
+}
+export type RaidStatus = "in-raid" | "extracting" | "extracted" | "dead";
+export interface ExtractionAttempt {
+    extractId: string;
+    channel: ContestedChannel;
+}
+export interface ExtractionResult {
+    userId: string;
+    extractId: string;
+    banked: readonly ItemStack[];
+}
+export interface DeathResult {
+    userId: string;
+    kept: readonly ItemStack[];
+    lost: readonly ItemStack[];
+    scheduled: DeliveryEntry | null;
+    consolationLoadoutId: string | null;
+}
+export interface RaidPlayerSnapshot {
+    status: RaidStatus;
+    extractId: string | null;
+    progress: number;
+    remaining: number;
+}
+export interface RaidSession {
+    beginExtract(userId: string, extractId: string, team?: string): ContestedEvent | null;
+    tickExtract(userId: string, dt: number, occupants?: Record<string, number>): ContestedEvent[];
+    damage(userId: string, reason?: string): ContestedEvent | null;
+    cancelExtract(userId: string): void;
+    resolveExtraction(userId: string, containers: readonly ContainerSnapshot[]): ExtractionResult;
+    resolveDeath(userId: string, containers: readonly ContainerSnapshot[], now: number, rng?: () => number): DeathResult;
+    claimDeliveries(now: number): readonly DeliveryEntry[];
+    pendingDeliveries(userId?: string): readonly DeliveryEntry[];
+    deliveries(): DeliveryQueue;
+    extractPoint(extractId: string): ExtractPoint | undefined;
+    status(userId: string): RaidStatus;
+    playerSnapshot(userId: string): RaidPlayerSnapshot;
+}
+export declare function createRaidSession(config: RaidSessionConfig): RaidSession;