@jgengine/core 0.27.0 → 0.28.0

package/dist/sim/population.d.ts

@@ -0,0 +1,147 @@
+import type { Vec3 } from "../world/geometry.js";
+/** One visitor on site: the id its body, its needs and its money are keyed by. */
+export interface Visitor {
+    readonly id: string;
+    /** Game-second it arrived; a restored visitor keeps the original. */
+    readonly admittedAt: number;
+}
+/** What a flow policy reads to decide how many arrive and when one has had enough. */
+export interface VisitorFlow {
+    /** Visitors on site this tick — the member count, never a tally kept beside it. */
+    readonly onSite: number;
+    /** Most visitors the gates hold this tick, after resolving {@link VisitorPolicy.capacity}. */
+    readonly capacity: number;
+    /** Arrivals since {@link VisitorPopulation.rollDay}. */
+    readonly arrivalsToday: number;
+    readonly departuresToday: number;
+    readonly now: number;
+}
+/** The game's world behind every counted visitor: it creates and removes the body. */
+export interface VisitorWorld {
+    /**
+     * Create one visitor's body and its game-side record, and return where the body now stands.
+     * `null` means the world refused it — no room, no walkable spot — and a refused body is never
+     * counted as on site or as an arrival.
+     */
+    readonly admit: (visitor: Visitor) => Vec3 | null;
+    /** Remove one visitor's body and record. Called for every departure, refusal and reset. */
+    readonly release: (visitor: Visitor) => void;
+    /**
+     * True when the world currently holds a body for this id. `adopt` and `restore` refuse an id the
+     * world does not hold, so the count can never name a body that is not on the ground.
+     */
+    readonly has: (id: string) => boolean;
+}
+/** The game's flow policy: what draws visitors in, how many fit, and when one has had enough. */
+export interface VisitorPolicy {
+    /** Most visitors on site at once; a function lets the cap follow a rating, a level or a build. */
+    readonly capacity: number | ((now: number) => number);
+    /** Visitors arriving per second at this instant; `0` with the gates shut. */
+    readonly arrivalRate: (flow: VisitorFlow) => number;
+    /** True when this visitor should leave now. Omit for a population that only leaves when told. */
+    readonly shouldLeave?: (visitor: Visitor, flow: VisitorFlow) => boolean;
+}
+/** Flow policy fields a scenario can change in play. */
+export interface VisitorPolicyPatch {
+    readonly capacity?: number | ((now: number) => number);
+    readonly arrivalRate?: (flow: VisitorFlow) => number;
+    /** `null` removes the leaving rule, so visitors stay until {@link VisitorPopulation.leave}. */
+    readonly shouldLeave?: ((visitor: Visitor, flow: VisitorFlow) => boolean) | null;
+    readonly arrivalBudget?: number;
+    /** `null` counts every admitted body as on site. */
+    readonly inside?: ((position: Vec3) => boolean) | null;
+}
+/** Counters a HUD, a probe or a test reads. The on-site figure is the visitor list's length. */
+export interface VisitorPopulationStats {
+    onSite: number;
+    capacity: number;
+    arrivalsToday: number;
+    departuresToday: number;
+    /** Highest on-site count since the last {@link VisitorPopulation.rollDay}. */
+    peakToday: number;
+    /** Bodies the world or the bounds check refused. Never counted as arrivals. */
+    refused: number;
+    /** Arrival credit not yet spent. */
+    pending: number;
+}
+/** How a body the game made itself joins the population. */
+export interface VisitorAdoption {
+    /** Game-second it arrived; defaults to the current tick's clock. */
+    readonly admittedAt?: number;
+    /** True for a body that is a new arrival today; false for one a save or a seed restored. */
+    readonly arrival?: boolean;
+}
+/** Serializable state. No on-site count is stored: it is the restored visitor list. */
+export interface VisitorPopulationSnapshot {
+    visitors: {
+        id: string;
+        admittedAt: number;
+    }[];
+    arrivalsToday: number;
+    departuresToday: number;
+    peakToday: number;
+    pending: number;
+    /** Next id suffix, so a restored save does not reuse an id. */
+    sequence: number;
+}
+/** Options for {@link createVisitorPopulation}. */
+export interface VisitorPopulationOptions {
+    readonly world: VisitorWorld;
+    readonly policy: VisitorPolicy;
+    /** First half of every generated id. Default `"visitor#"`. */
+    readonly idPrefix?: string;
+    /** First suffix used after `idPrefix`. Default 1. */
+    readonly sequenceStart?: number;
+    /** Most bodies one tick may admit, so a long frame cannot flood the park. Default 4. */
+    readonly arrivalBudget?: number;
+    /** A body must stand here to count as on site; omit to count every admitted body. */
+    readonly inside?: (position: Vec3) => boolean;
+    /** Register a devtools probe under this name so the overlay shows the crowd and the day. */
+    readonly devtoolsName?: string;
+}
+/**
+ * The crowd a scene reports. Every visitor is a member with a body the game's world made, so the
+ * on-site figure is the member count and the daily figure is the sum of admissions the world
+ * accepted — there is no second tally to drift from what is on the ground. Arrivals, capacity and
+ * leaving are the game's policy; ids, day rollover and counting are this seam's.
+ */
+export interface VisitorPopulation {
+    /** Run the flow for `dt` seconds: leaving first, then arrivals within the budget and the cap. */
+    tick(dt: number, now: number): void;
+    /** Visitors on site. Reads the member count — no scan of the world, safe for a per-frame HUD. */
+    onSite(): number;
+    arrivalsToday(): number;
+    departuresToday(): number;
+    peakToday(): number;
+    /** Ids on site, arrival order. Allocates — HUD lists and tests. */
+    ids(): readonly string[];
+    has(id: string): boolean;
+    visitor(id: string): Visitor | null;
+    /** Send one visitor home now (it reached the exit, or the game evicted it). */
+    leave(id: string): boolean;
+    /**
+     * Take over a body the game created itself — one restored from a save, seeded at park open, or
+     * scripted. It is on site from now on; pass `arrival: true` when it is also a new arrival today.
+     */
+    adopt(id: string, adoption?: VisitorAdoption): boolean;
+    /** Close the day: arrivals, departures and peak reset. The crowd stays where it stands. */
+    rollDay(): void;
+    retune(patch: VisitorPolicyPatch): void;
+    stats(): VisitorPopulationStats;
+    snapshot(): VisitorPopulationSnapshot;
+    /**
+     * Replace the members with the saved ones. Only visitors the world already holds come back, so
+     * restore the bodies first (or `adopt` each one as it spawns); the rest count as refused.
+     */
+    restore(next: VisitorPopulationSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Create the population a scene reports, with the game owning arrival and leaving policy. A
+ * visitor only exists once the world has made its body, so the HUD's count and the bodies on
+ * screen are the same list: `admit` returning `null` is a refused arrival, not a number.
+ *
+ * @capability visitor-population a crowd whose on-site and daily counts are the bodies the game made
+ */
+export declare function createVisitorPopulation(options: VisitorPopulationOptions): VisitorPopulation;

package/dist/sim/population.js

@@ -0,0 +1,182 @@
+import { devtools } from "../devtools/devtools.js";
+const DEFAULT_ARRIVAL_BUDGET = 4;
+function countOf(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * Create the population a scene reports, with the game owning arrival and leaving policy. A
+ * visitor only exists once the world has made its body, so the HUD's count and the bodies on
+ * screen are the same list: `admit` returning `null` is a refused arrival, not a number.
+ *
+ * @capability visitor-population a crowd whose on-site and daily counts are the bodies the game made
+ */
+export function createVisitorPopulation(options) {
+    const world = options.world;
+    let policy = { ...options.policy };
+    const idPrefix = options.idPrefix ?? "visitor#";
+    let arrivalBudget = Math.max(1, Math.floor(options.arrivalBudget ?? DEFAULT_ARRIVAL_BUDGET));
+    let inside = options.inside;
+    let members = new Map();
+    let sequence = Math.max(1, Math.floor(options.sequenceStart ?? 1));
+    let arrivalsToday = 0;
+    let departuresToday = 0;
+    let peakToday = 0;
+    let refused = 0;
+    let pending = 0;
+    let now = 0;
+    let capacityNow = 0;
+    function resolveCapacity(at) {
+        const value = typeof policy.capacity === "function" ? policy.capacity(at) : policy.capacity;
+        return Math.max(0, Math.floor(Number.isFinite(value) ? value : 0));
+    }
+    capacityNow = resolveCapacity(0);
+    function flow() {
+        return { onSite: members.size, capacity: capacityNow, arrivalsToday, departuresToday, now };
+    }
+    function admitOne(at) {
+        const visitor = { id: `${idPrefix}${sequence}`, admittedAt: at };
+        sequence += 1;
+        const position = world.admit(visitor);
+        if (position === null || (inside !== undefined && !inside(position))) {
+            if (position !== null)
+                world.release(visitor);
+            refused += 1;
+            return false;
+        }
+        members.set(visitor.id, visitor);
+        arrivalsToday += 1;
+        if (members.size > peakToday)
+            peakToday = members.size;
+        return true;
+    }
+    function removeVisitor(visitor) {
+        members.delete(visitor.id);
+        world.release(visitor);
+        departuresToday += 1;
+    }
+    function probeLine() {
+        return `${members.size}/${capacityNow} on site ${arrivalsToday} arrived ${departuresToday} left ${refused} refused`;
+    }
+    const unregister = options.devtoolsName === undefined ? null : devtools.probes.register(options.devtoolsName, () => probeLine());
+    return {
+        tick(dt, at) {
+            if (!(dt > 0) || !Number.isFinite(at))
+                return;
+            now = at;
+            capacityNow = resolveCapacity(at);
+            const read = flow();
+            const leave = policy.shouldLeave;
+            if (leave !== undefined) {
+                for (const visitor of members.values()) {
+                    if (leave(visitor, read))
+                        removeVisitor(visitor);
+                }
+            }
+            if (members.size < capacityNow)
+                pending += Math.max(0, policy.arrivalRate(read)) * dt;
+            let budget = arrivalBudget;
+            while (pending >= 1 && budget > 0 && members.size < capacityNow) {
+                pending -= 1;
+                budget -= 1;
+                admitOne(at);
+            }
+            if (pending < 0)
+                pending = 0;
+        },
+        onSite: () => members.size,
+        arrivalsToday: () => arrivalsToday,
+        departuresToday: () => departuresToday,
+        peakToday: () => peakToday,
+        ids() {
+            const out = [];
+            for (const id of members.keys())
+                out.push(id);
+            return out;
+        },
+        has: (id) => members.has(id),
+        visitor: (id) => members.get(id) ?? null,
+        leave(id) {
+            const visitor = members.get(id);
+            if (visitor === undefined)
+                return false;
+            removeVisitor(visitor);
+            return true;
+        },
+        adopt(id, adoption) {
+            if (id === "" || members.has(id) || !world.has(id))
+                return false;
+            const saved = adoption?.admittedAt;
+            const at = saved !== undefined && Number.isFinite(saved) ? saved : now;
+            members.set(id, { id, admittedAt: at });
+            if (members.size > peakToday)
+                peakToday = members.size;
+            if (adoption?.arrival === true)
+                arrivalsToday += 1;
+            return true;
+        },
+        rollDay() {
+            arrivalsToday = 0;
+            departuresToday = 0;
+            peakToday = members.size;
+        },
+        retune(patch) {
+            if (patch.capacity !== undefined) {
+                policy = { ...policy, capacity: patch.capacity };
+                capacityNow = resolveCapacity(now);
+            }
+            if (patch.arrivalRate !== undefined)
+                policy = { ...policy, arrivalRate: patch.arrivalRate };
+            if (patch.shouldLeave === null)
+                policy = { capacity: policy.capacity, arrivalRate: policy.arrivalRate };
+            else if (patch.shouldLeave !== undefined)
+                policy = { ...policy, shouldLeave: patch.shouldLeave };
+            if (patch.arrivalBudget !== undefined) {
+                arrivalBudget = Math.max(1, Math.floor(Number.isFinite(patch.arrivalBudget) ? patch.arrivalBudget : arrivalBudget));
+            }
+            if (patch.inside === null)
+                inside = undefined;
+            else if (patch.inside !== undefined)
+                inside = patch.inside;
+        },
+        stats: () => ({
+            onSite: members.size,
+            capacity: capacityNow,
+            arrivalsToday,
+            departuresToday,
+            peakToday,
+            refused,
+            pending,
+        }),
+        snapshot() {
+            const visitors = [];
+            for (const visitor of members.values())
+                visitors.push({ id: visitor.id, admittedAt: visitor.admittedAt });
+            return { visitors, arrivalsToday, departuresToday, peakToday, pending, sequence };
+        },
+        restore(next) {
+            for (const visitor of members.values())
+                world.release(visitor);
+            members = new Map();
+            arrivalsToday = countOf(next.arrivalsToday);
+            departuresToday = countOf(next.departuresToday);
+            peakToday = countOf(next.peakToday);
+            pending = Number.isFinite(next.pending) && next.pending > 0 ? next.pending : 0;
+            sequence = Math.max(1, Math.floor(Number.isFinite(next.sequence) ? next.sequence : 1));
+            for (const saved of next.visitors) {
+                if (typeof saved?.id !== "string" || saved.id === "" || members.has(saved.id))
+                    continue;
+                if (!world.has(saved.id)) {
+                    refused += 1;
+                    continue;
+                }
+                const at = Number.isFinite(saved.admittedAt) ? saved.admittedAt : 0;
+                members.set(saved.id, { id: saved.id, admittedAt: at });
+            }
+            if (members.size > peakToday)
+                peakToday = members.size;
+        },
+        dispose() {
+            unregister?.();
+        },
+    };
+}

package/dist/sim/queue.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Seconds one guest occupies the head of the line before any boarding interval has been measured.
+ * A bootstrap only: the estimate switches to the queue's own measured throughput as soon as two
+ * boardings have been observed.
+ */
+export declare const DEFAULT_QUEUE_SEED_SERVICE_SECONDS = 8;
+/** Boarding events the throughput window keeps. */
+export declare const DEFAULT_QUEUE_WINDOW = 8;
+/** One guest waiting their turn, and when they joined the line. */
+export interface QueueEntry {
+    readonly id: string;
+    readonly joinedAt: number;
+}
+/** A wait estimate read off the queue's own measured throughput. */
+export interface QueueWait {
+    /** Guests in front of the reader (the whole line for a new arrival). */
+    readonly ahead: number;
+    /** Seconds that wait. */
+    readonly seconds: number;
+    /** Seconds one guest spends at the head; the seed until an interval has been measured. */
+    readonly perGuestSeconds: number;
+    /** Guests boarded per second over the measured window; `0` before any interval is observed. */
+    readonly throughput: number;
+    /** True while the estimate still rests on the seed rather than a measured interval. */
+    readonly seeded: boolean;
+}
+/** Tunables for {@link createWaitQueue}, every one retunable through a restore. */
+export interface WaitQueueOptions {
+    /** Seconds per guest used before the queue has measured an interval. Default 8. */
+    readonly seedServiceSeconds?: number;
+    /** Boarding events the throughput window keeps. Default 8. */
+    readonly window?: number;
+    /** Register a devtools probe under this name so the perf overlay shows the live line. */
+    readonly devtoolsName?: string;
+}
+/** Serializable line state: who is waiting, and the boardings the estimate is measured from. */
+export interface WaitQueueSnapshot {
+    entries: QueueEntry[];
+    boards: {
+        at: number;
+        count: number;
+    }[];
+    seedServiceSeconds: number;
+    window: number;
+}
+/**
+ * A real line: guests join the back, leave the head, and the wait a new arrival faces comes from how
+ * fast this queue has actually been boarding — not from a configured constant. A broken ride stops
+ * boarding, the line grows, and the estimate grows with it.
+ */
+export interface WaitQueue {
+    /** Join the back of the line; false when the id is already waiting. */
+    enqueue(id: string, now: number): boolean;
+    /** Leave from anywhere in the line. */
+    remove(id: string): boolean;
+    has(id: string): boolean;
+    /** 0-based place in line, or `-1` when not waiting. */
+    positionOf(id: string): number;
+    /** When the guest joined, or `null` when not waiting. */
+    joinedAt(id: string): number | null;
+    size(): number;
+    headId(): string | null;
+    /** Id at a 0-based index from the head, or `null` past the end. */
+    at(index: number): string | null;
+    /** Everyone in line, head first. Allocates — debug and tests. */
+    ids(): readonly string[];
+    /** Take the guest at the head, or `null` when the line is empty. */
+    dequeue(): string | null;
+    /** Record that `count` guests left the head at `now`; the throughput window reads these. */
+    recordBoard(now: number, count: number): void;
+    /**
+     * Wait facing `id`, or the whole line when `id` is omitted or not waiting — what a guest joining
+     * now would face.
+     */
+    wait(id?: string): QueueWait;
+    snapshot(): WaitQueueSnapshot;
+    restore(next: WaitQueueSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Create a line whose wait estimate is derived from its own throughput. The queue owns the order and
+ * the measurement; the ride owns how fast guests are taken off the head, so a slower cycle raises the
+ * estimate without the queue being told a cycle time.
+ *
+ * `enqueue` is O(1) and `dequeue` amortized O(1) — a long line never re-indexes.
+ *
+ * @capability wait-queue a real line whose wait estimate comes from its own measured throughput
+ */
+export declare function createWaitQueue(options?: WaitQueueOptions): WaitQueue;

package/dist/sim/queue.js

@@ -0,0 +1,171 @@
+import { devtools } from "../devtools/devtools.js";
+/**
+ * Seconds one guest occupies the head of the line before any boarding interval has been measured.
+ * A bootstrap only: the estimate switches to the queue's own measured throughput as soon as two
+ * boardings have been observed.
+ */
+export const DEFAULT_QUEUE_SEED_SERVICE_SECONDS = 8;
+/** Boarding events the throughput window keeps. */
+export const DEFAULT_QUEUE_WINDOW = 8;
+/**
+ * Create a line whose wait estimate is derived from its own throughput. The queue owns the order and
+ * the measurement; the ride owns how fast guests are taken off the head, so a slower cycle raises the
+ * estimate without the queue being told a cycle time.
+ *
+ * `enqueue` is O(1) and `dequeue` amortized O(1) — a long line never re-indexes.
+ *
+ * @capability wait-queue a real line whose wait estimate comes from its own measured throughput
+ */
+export function createWaitQueue(options = {}) {
+    let seedServiceSeconds = options.seedServiceSeconds ?? DEFAULT_QUEUE_SEED_SERVICE_SECONDS;
+    let window = Math.max(2, Math.floor(options.window ?? DEFAULT_QUEUE_WINDOW));
+    let entries = [];
+    let boards = [];
+    let head = 0;
+    const waiting = new Set();
+    const live = () => entries.length - head;
+    function compact() {
+        if (head > 32 && head * 2 >= entries.length) {
+            entries = entries.slice(head);
+            head = 0;
+        }
+    }
+    /** Guests boarded per second, from consecutive boarding intervals; `0` until one is observed. */
+    function throughput() {
+        if (boards.length < 2)
+            return 0;
+        const first = boards[0];
+        const last = boards[boards.length - 1];
+        const span = last.at - first.at;
+        if (!(span > 0))
+            return 0;
+        let guests = 0;
+        for (let index = 1; index < boards.length; index += 1)
+            guests += boards[index].count;
+        return guests / span;
+    }
+    function readWait(ahead) {
+        const rate = throughput();
+        const perGuestSeconds = rate > 0 ? 1 / rate : Math.max(0, seedServiceSeconds);
+        return {
+            ahead,
+            seconds: ahead * perGuestSeconds,
+            perGuestSeconds,
+            throughput: rate,
+            seeded: rate <= 0,
+        };
+    }
+    const unregister = options.devtoolsName === undefined ? null : devtools.probes.register(options.devtoolsName, () => probeLine());
+    function probeLine() {
+        const wait = readWait(live());
+        return `${live()} in line · ${wait.seconds.toFixed(1)}s wait · ${wait.perGuestSeconds.toFixed(2)}s per guest${wait.seeded ? " (seed)" : ""}`;
+    }
+    function indexOf(id) {
+        for (let index = head; index < entries.length; index += 1) {
+            if (entries[index].id === id)
+                return index;
+        }
+        return -1;
+    }
+    function positionOfId(id) {
+        const at = indexOf(id);
+        return at < 0 ? -1 : at - head;
+    }
+    return {
+        enqueue(id, now) {
+            if (waiting.has(id))
+                return false;
+            entries.push({ id, joinedAt: Number.isFinite(now) ? now : 0 });
+            waiting.add(id);
+            return true;
+        },
+        remove(id) {
+            if (!waiting.has(id))
+                return false;
+            waiting.delete(id);
+            const at = indexOf(id);
+            if (at === head) {
+                head += 1;
+                compact();
+                return true;
+            }
+            entries.splice(at, 1);
+            return true;
+        },
+        has: (id) => waiting.has(id),
+        positionOf: positionOfId,
+        joinedAt(id) {
+            if (!waiting.has(id))
+                return null;
+            const at = indexOf(id);
+            return at < 0 ? null : entries[at].joinedAt;
+        },
+        size: live,
+        headId: () => entries[head]?.id ?? null,
+        at(index) {
+            const absolute = head + Math.floor(index);
+            if (!(index >= 0) || absolute >= entries.length)
+                return null;
+            return entries[absolute]?.id ?? null;
+        },
+        ids() {
+            const out = [];
+            for (let index = head; index < entries.length; index += 1)
+                out.push(entries[index].id);
+            return out;
+        },
+        dequeue() {
+            const entry = entries[head];
+            if (entry === undefined)
+                return null;
+            head += 1;
+            waiting.delete(entry.id);
+            compact();
+            return entry.id;
+        },
+        recordBoard(now, count) {
+            const boarded = Math.floor(count);
+            if (!(boarded > 0) || !Number.isFinite(now))
+                return;
+            boards.push({ at: now, count: boarded });
+            if (boards.length > window)
+                boards = boards.slice(boards.length - window);
+        },
+        wait(id) {
+            const position = id === undefined ? -1 : positionOfId(id);
+            return readWait(position >= 0 ? position : live());
+        },
+        snapshot: () => ({
+            entries: entries.slice(head).map((entry) => ({ id: entry.id, joinedAt: entry.joinedAt })),
+            boards: boards.map((board) => ({ at: board.at, count: board.count })),
+            seedServiceSeconds,
+            window,
+        }),
+        restore(next) {
+            entries = [];
+            head = 0;
+            waiting.clear();
+            for (const entry of next.entries) {
+                if (typeof entry?.id !== "string" || entry.id === "")
+                    continue;
+                entries.push({ id: entry.id, joinedAt: Number.isFinite(entry.joinedAt) ? entry.joinedAt : 0 });
+                waiting.add(entry.id);
+            }
+            boards = [];
+            for (const board of next.boards) {
+                if (!Number.isFinite(board?.at) || !(board?.count > 0))
+                    continue;
+                boards.push({ at: board.at, count: Math.floor(board.count) });
+            }
+            if (boards.length > window)
+                boards = boards.slice(boards.length - window);
+            if (Number.isFinite(next.seedServiceSeconds))
+                seedServiceSeconds = Math.max(0, next.seedServiceSeconds);
+            if (Number.isFinite(next.window))
+                window = Math.max(2, Math.floor(next.window));
+        },
+        dispose() {
+            unregister?.();
+        },
+    };
+}