@jgengine/core 0.26.0 → 0.28.0

package/dist/sim/rides.js

@@ -0,0 +1,471 @@
+import { createUtilityBrain, sampleResponseCurve, } from "../ai/utilityBrain.js";
+import { devtools } from "../devtools/devtools.js";
+import { clamp } from "../math/scalar.js";
+import { resolveRng } from "../random/resolveRng.js";
+import { createWaitQueue } from "./queue.js";
+/** A ride's breakdown curve a park starts from when it has none and retunes only part of one. */
+export const DEFAULT_RIDE_BREAKDOWN = {
+    baseChance: 0,
+    wearChance: 0,
+    repairSeconds: 60,
+    repairCost: 0,
+    serviceCost: 0,
+};
+function cloneBreakdown(breakdown) {
+    return breakdown === undefined ? undefined : { ...breakdown };
+}
+function cloneDefinition(def) {
+    return {
+        id: def.id,
+        ratings: { ...def.ratings },
+        capacity: def.capacity,
+        loadSeconds: def.loadSeconds,
+        rideSeconds: def.rideSeconds,
+        unloadSeconds: def.unloadSeconds,
+        breakdown: cloneBreakdown(def.breakdown),
+    };
+}
+function validateDefinition(def) {
+    if (typeof def.id !== "string" || def.id === "")
+        throw new Error("ride needs a non-empty id");
+    if (!Number.isFinite(def.capacity) || def.capacity < 1) {
+        throw new Error(`ride "${def.id}" needs a capacity of at least 1, got ${def.capacity}`);
+    }
+    for (const field of ["loadSeconds", "rideSeconds", "unloadSeconds"]) {
+        if (!Number.isFinite(def[field]) || def[field] < 0) {
+            throw new Error(`ride "${def.id}" needs a non-negative ${field}, got ${def[field]}`);
+        }
+    }
+    for (const field of ["excitement", "intensity", "nausea"]) {
+        if (!Number.isFinite(def.ratings[field])) {
+            throw new Error(`ride "${def.id}" needs a finite ${field} rating, got ${def.ratings[field]}`);
+        }
+    }
+}
+/**
+ * Create the rides a park runs. Each ride cycles on its own data, boards from its own line up to its
+ * own capacity, wears against its own breakdown curve and reports its repairs through the sink, so
+ * the caller keeps the wallet, the bodies and the visuals.
+ *
+ * @capability ride-sim rides with capacity, cycles, queues, ratings, breakdowns and maintenance
+ */
+export function createRideSystem(config) {
+    const rides = [];
+    const stateOf = new Map();
+    const defs = [];
+    const ids = [];
+    const seedServiceSeconds = config.queueSeedServiceSeconds;
+    for (const definition of config.rides) {
+        validateDefinition(definition);
+        if (stateOf.has(definition.id))
+            throw new Error(`duplicate ride id "${definition.id}"`);
+        const def = cloneDefinition(definition);
+        const state = {
+            def,
+            queue: createWaitQueue({ seedServiceSeconds }),
+            phase: "idle",
+            timer: 0,
+            riders: [],
+            cycles: 0,
+            wear: 0,
+            breakdowns: 0,
+            repairSpend: 0,
+            serviceSpend: 0,
+            boarded: 0,
+        };
+        rides.push(state);
+        defs.push(def);
+        ids.push(def.id);
+        stateOf.set(def.id, state);
+    }
+    let elapsed = 0;
+    let revision = 0;
+    let ticks = 0;
+    let slowestTickMs = 0;
+    let rng = config.rng;
+    function rollRng() {
+        if (rng === undefined)
+            rng = resolveRng(undefined, "createRideSystem");
+        return rng();
+    }
+    function probeLine() {
+        let broken = 0;
+        let queued = 0;
+        let boarded = 0;
+        for (const state of rides) {
+            if (state.phase === "broken")
+                broken += 1;
+            queued += state.queue.size();
+            boarded += state.boarded;
+        }
+        return `${rides.length} rides ${broken} broken ${queued} queued ${boarded} carried ${ticks} ticks ${slowestTickMs.toFixed(2)} ms slowest`;
+    }
+    const unregister = config.devtoolsName === undefined ? null : devtools.probes.register(config.devtoolsName, () => probeLine());
+    function board(state, sink) {
+        const capacity = Math.max(1, Math.floor(state.def.capacity));
+        let boarded = 0;
+        while (boarded < capacity) {
+            const guestId = state.queue.dequeue();
+            if (guestId === null)
+                break;
+            state.riders.push(guestId);
+            boarded += 1;
+            state.boarded += 1;
+            sink?.onBoard?.(state.def.id, guestId, elapsed);
+        }
+        if (boarded > 0)
+            state.queue.recordBoard(elapsed, boarded);
+        state.phase = "loading";
+        state.timer = Math.max(0, state.def.loadSeconds);
+    }
+    function finishCycle(state, sink) {
+        const id = state.def.id;
+        for (const guestId of state.riders)
+            sink?.onAlight?.(id, guestId, elapsed);
+        state.riders.length = 0;
+        state.cycles += 1;
+        state.wear += 1;
+        const breakdown = state.def.breakdown;
+        if (breakdown !== undefined) {
+            const chance = clamp(breakdown.baseChance + breakdown.wearChance * state.wear, 0, 1);
+            if (chance > 0 && rollRng() < chance) {
+                state.phase = "broken";
+                state.timer = Math.max(0, breakdown.repairSeconds);
+                state.breakdowns += 1;
+                sink?.onBreak?.(id, elapsed);
+                return;
+            }
+        }
+        state.phase = "idle";
+        state.timer = 0;
+    }
+    function tickRide(state, dt, sink) {
+        if (state.phase === "idle") {
+            if (state.queue.size() > 0)
+                board(state, sink);
+            return;
+        }
+        state.timer -= dt;
+        if (state.timer > 0)
+            return;
+        switch (state.phase) {
+            case "broken": {
+                const cost = state.def.breakdown?.repairCost ?? 0;
+                state.repairSpend += cost;
+                state.phase = "idle";
+                state.timer = 0;
+                sink?.onRepaired?.(state.def.id, cost, elapsed);
+                return;
+            }
+            case "loading":
+                state.phase = "riding";
+                state.timer = Math.max(0, state.def.rideSeconds);
+                return;
+            case "riding":
+                state.phase = "unloading";
+                state.timer = Math.max(0, state.def.unloadSeconds);
+                return;
+            case "unloading":
+                finishCycle(state, sink);
+                return;
+        }
+    }
+    function viewOf(state) {
+        return {
+            id: state.def.id,
+            ratings: state.def.ratings,
+            capacity: state.def.capacity,
+            phase: state.phase,
+            phaseSeconds: state.timer,
+            riders: state.riders.length,
+            queue: { size: state.queue.size(), wait: state.queue.wait() },
+            cycles: state.cycles,
+            wear: state.wear,
+            breakdowns: state.breakdowns,
+            spend: state.repairSpend + state.serviceSpend,
+        };
+    }
+    return {
+        now: () => elapsed,
+        revision: () => revision,
+        rideIds: () => ids,
+        definitions: () => defs,
+        ride(id) {
+            const state = stateOf.get(id);
+            return state === undefined ? null : viewOf(state);
+        },
+        rides: () => rides.map(viewOf),
+        queue(id) {
+            const state = stateOf.get(id);
+            return state === undefined ? null : state.queue;
+        },
+        join(id, guestId) {
+            const state = stateOf.get(id);
+            if (state === undefined)
+                return false;
+            return state.queue.enqueue(guestId, elapsed);
+        },
+        leave(id, guestId) {
+            const state = stateOf.get(id);
+            if (state === undefined)
+                return false;
+            return state.queue.remove(guestId);
+        },
+        waitSeconds(id) {
+            const state = stateOf.get(id);
+            return state === undefined ? 0 : state.queue.wait().seconds;
+        },
+        tick(dt, sink) {
+            if (!(dt > 0) || rides.length === 0)
+                return;
+            const started = performance.now();
+            elapsed += dt;
+            for (const state of rides)
+                tickRide(state, dt, sink);
+            ticks += 1;
+            slowestTickMs = Math.max(slowestTickMs, performance.now() - started);
+        },
+        service(id) {
+            const state = stateOf.get(id);
+            if (state === undefined)
+                return null;
+            const wear = state.wear;
+            const breakdown = state.def.breakdown;
+            if (breakdown === undefined || wear <= 0)
+                return { id, cost: 0, wear };
+            state.wear = 0;
+            state.serviceSpend += breakdown.serviceCost;
+            return { id, cost: breakdown.serviceCost, wear };
+        },
+        retune(id, patch) {
+            const state = stateOf.get(id);
+            if (state === undefined)
+                return false;
+            const def = state.def;
+            const index = rides.indexOf(state);
+            const breakdown = patch.breakdown === undefined
+                ? def.breakdown
+                : patch.breakdown === null
+                    ? undefined
+                    : { ...(def.breakdown ?? DEFAULT_RIDE_BREAKDOWN), ...patch.breakdown };
+            const next = {
+                id: def.id,
+                ratings: patch.ratings === undefined ? def.ratings : { ...def.ratings, ...patch.ratings },
+                capacity: patch.capacity === undefined ? def.capacity : Math.max(1, Math.floor(patch.capacity)),
+                loadSeconds: patch.loadSeconds === undefined ? def.loadSeconds : Math.max(0, patch.loadSeconds),
+                rideSeconds: patch.rideSeconds === undefined ? def.rideSeconds : Math.max(0, patch.rideSeconds),
+                unloadSeconds: patch.unloadSeconds === undefined ? def.unloadSeconds : Math.max(0, patch.unloadSeconds),
+                breakdown,
+            };
+            validateDefinition(next);
+            state.def = next;
+            defs[index] = next;
+            revision += 1;
+            return true;
+        },
+        stats() {
+            let broken = 0;
+            let riders = 0;
+            let queued = 0;
+            let boarded = 0;
+            let cycles = 0;
+            let breakdowns = 0;
+            let spend = 0;
+            for (const state of rides) {
+                if (state.phase === "broken")
+                    broken += 1;
+                riders += state.riders.length;
+                queued += state.queue.size();
+                boarded += state.boarded;
+                cycles += state.cycles;
+                breakdowns += state.breakdowns;
+                spend += state.repairSpend + state.serviceSpend;
+            }
+            return { rides: rides.length, broken, riders, queued, boarded, cycles, breakdowns, spend, ticks, slowestTickMs };
+        },
+        snapshot() {
+            return {
+                elapsed,
+                rides: rides.map((state) => ({
+                    definition: cloneDefinition(state.def),
+                    phase: state.phase,
+                    timer: state.timer,
+                    riders: [...state.riders],
+                    cycles: state.cycles,
+                    wear: state.wear,
+                    breakdowns: state.breakdowns,
+                    repairSpend: state.repairSpend,
+                    serviceSpend: state.serviceSpend,
+                    boarded: state.boarded,
+                    queue: state.queue.snapshot(),
+                })),
+            };
+        },
+        restore(next) {
+            rides.length = 0;
+            stateOf.clear();
+            defs.length = 0;
+            ids.length = 0;
+            for (const saved of next.rides) {
+                const def = cloneDefinition(saved.definition);
+                const state = {
+                    def,
+                    queue: createWaitQueue({ seedServiceSeconds }),
+                    phase: saved.phase,
+                    timer: saved.timer,
+                    riders: [...saved.riders],
+                    cycles: saved.cycles,
+                    wear: saved.wear,
+                    breakdowns: saved.breakdowns,
+                    repairSpend: saved.repairSpend,
+                    serviceSpend: saved.serviceSpend,
+                    boarded: saved.boarded,
+                };
+                state.queue.restore(saved.queue);
+                rides.push(state);
+                defs.push(def);
+                ids.push(def.id);
+                stateOf.set(def.id, state);
+            }
+            elapsed = Number.isFinite(next.elapsed) ? next.elapsed : 0;
+            revision += 1;
+        },
+        dispose() {
+            unregister?.();
+        },
+    };
+}
+/** A 0–10 rating scale, the usual shape of a ride catalog. Override it when a park rates differently. */
+export const DEFAULT_RIDE_RATING_RANGE = { excitementMax: 10, intensityMax: 10, nauseaMax: 10 };
+/** How empty a bored guest's fun need has to be before a ride starts to pull, by default. */
+export const DEFAULT_RIDE_FUN_CURVE = { kind: "linear", from: 0.15, to: 0.9 };
+/**
+ * Appeal that rises with the rating: `0` at zero, `1` at `max`. Response curves sample a `0..1`
+ * satisfaction, so a rating is normalized against the park's own scale first.
+ */
+function risesTo(rating, max) {
+    if (!(max > 0))
+        return 1;
+    return sampleResponseCurve({ kind: "linear", from: 1, to: 0 }, clamp(rating / max, 0, 1));
+}
+/** `1` while the rating stays inside the guest's comfort, falling to `0` at the park's maximum. */
+function comfortFit(rating, comfort, max) {
+    if (!(max > comfort))
+        return 1;
+    return sampleResponseCurve({ kind: "linear", from: clamp(comfort / max, 0, 1), to: 1 }, clamp(rating / max, 0, 1));
+}
+/**
+ * One ride's standing appeal to one guest, before queue cost. Excitement draws, force and nausea
+ * push back — what a guest's own card or thought bubble can show.
+ *
+ * @capability ride-appeal how much one guest likes one ride, from its ratings and their taste
+ */
+export function rideAppeal(ratings, taste, range = DEFAULT_RIDE_RATING_RANGE) {
+    return (risesTo(ratings.excitement, range.excitementMax) *
+        comfortFit(ratings.intensity, taste.intensityComfort, range.intensityMax) *
+        comfortFit(ratings.nausea, taste.nauseaComfort, range.nauseaMax));
+}
+/**
+ * Compile a guest's taste and the park's ride data into utility options, so the guest's pick comes
+ * from `createUtilityBrain` like every other decision it makes. Ride choice is one more set of
+ * options a guest can score, not a separate scoring function.
+ *
+ * @capability ride-choice guests pick rides by taste and queue tolerance through the utility brain
+ */
+export function rideChoiceOptions(rides, taste, policy = {}) {
+    const range = policy.range ?? DEFAULT_RIDE_RATING_RANGE;
+    const terms = policy.funNeed === undefined
+        ? undefined
+        : [{ need: policy.funNeed, curve: policy.funCurve ?? DEFAULT_RIDE_FUN_CURVE, weight: policy.funWeight ?? 1 }];
+    return rides.map((ride) => ({ id: ride.id, base: rideAppeal(ride.ratings, taste, range), terms }));
+}
+/**
+ * Cost each ride by the wait its own line reports, so a guest weighs a ride by seconds in line
+ * rather than by a fixed order. `out` is reused for the array; the candidate records are not.
+ *
+ * @capability ride-choice guests pick rides by taste and queue tolerance through the utility brain
+ */
+export function rideChoiceCandidates(source, out = []) {
+    out.length = 0;
+    for (const id of source.rideIds())
+        out.push({ option: id, cost: source.waitSeconds(id) });
+    return out;
+}
+/**
+ * Score points per second of queue wait: a guest's own tolerance is the denominator. A guest who
+ * merges rides into a brain that also scores food and exits uses this as its `costWeight`.
+ *
+ * @capability ride-choice guests pick rides by taste and queue tolerance through the utility brain
+ */
+export function rideQueueCostWeight(taste) {
+    return 1 / Math.max(taste.queueTolerance, 1e-3);
+}
+function validateTaste(taste) {
+    for (const field of ["intensityComfort", "nauseaComfort", "queueTolerance"]) {
+        if (!Number.isFinite(taste[field]) || taste[field] < 0) {
+            throw new Error(`ride taste needs a non-negative ${field}, got ${taste[field]}`);
+        }
+    }
+}
+/**
+ * Create one guest's ride choice over a park. Options are rebuilt when the park is retuned, so a
+ * coaster whose track changes its ratings is re-scored without rebuilding the guest.
+ *
+ * @capability ride-choice guests pick rides by taste and queue tolerance through the utility brain
+ */
+export function createRideChooser(config) {
+    const system = config.system;
+    let taste = { ...config.taste };
+    validateTaste(taste);
+    const candidates = [];
+    let brain = null;
+    let builtRevision = -1;
+    function build() {
+        const held = brain?.chosen() ?? null;
+        brain?.dispose();
+        const options = rideChoiceOptions(system.definitions(), taste, config.policy);
+        const next = createUtilityBrain({
+            needs: config.needs,
+            options,
+            costWeight: rideQueueCostWeight(taste),
+            switchMargin: config.switchMargin,
+            minHoldSeconds: config.minHoldSeconds,
+            rng: config.rng,
+            devtoolsName: config.devtoolsName,
+        });
+        brain = next;
+        builtRevision = system.revision();
+        if (held !== null && options.some((option) => option.id === held))
+            next.decide([{ option: held, cost: 0 }]);
+        return next;
+    }
+    function active() {
+        if (brain === null || system.revision() !== builtRevision)
+            return build();
+        return brain;
+    }
+    return {
+        choose() {
+            const pick = active().decide(rideChoiceCandidates(system, candidates));
+            return pick.option;
+        },
+        scoreOf: (rideId) => active().scoreOf(rideId),
+        advance(dt) {
+            active().advance(dt);
+        },
+        setTaste(next) {
+            validateTaste(next);
+            taste = { ...next };
+            build();
+        },
+        snapshot: () => ({ taste: { ...taste }, brain: (brain ?? build()).snapshot() }),
+        restore(next) {
+            taste = { ...next.taste };
+            build().restore(next.brain);
+        },
+        dispose() {
+            brain?.dispose();
+            brain = null;
+        },
+    };
+}

package/dist/sim/routine.js

@@ -1,6 +1,14 @@
 import { SECONDS_PER_GAME_DAY } from "../time/gameClock.js";
-function wrap(value, cycle) {
-    return ((value % cycle) + cycle) % cycle;
+/**
+ * Seconds into the cycle, plus how far float rounding can have moved them.
+ *
+ * `time` is a sum of whole cycles and a stop time, so it arrives with the low bits of the stop time
+ * already rounded away; comparing a boundary against it needs a tolerance or a boundary that *is*
+ * now reads as a change still to come, which would repeat forever.
+ */
+function localAt(time, cycleSeconds) {
+    const cycle = Math.floor(time / cycleSeconds) * cycleSeconds;
+    return { cycle, local: time - cycle, tolerance: Math.max(1e-9, Math.abs(time) * Number.EPSILON * 8) };
 }
 /**
  * Resolve an authored routine into a timeline driven by the world clock.
@@ -62,8 +70,7 @@ export function resolveRoutine(config) {
         refill: spec.refill === undefined ? null : { ...spec.refill },
     }));
     function phaseAt(time) {
-        const cycle = Math.floor(time / cycleSeconds) * cycleSeconds;
-        const local = wrap(time, cycleSeconds);
+        const { cycle, local, tolerance } = localAt(time, cycleSeconds);
         if (stops.length === 1) {
             const only = stops[0];
             return {
@@ -78,7 +85,7 @@ export function resolveRoutine(config) {
             };
         }
         for (const stop of stops) {
-            if (local >= stop.arriveAt && local < stop.departAt) {
+            if (local >= stop.arriveAt - tolerance && local < stop.departAt - tolerance) {
                 return {
                     stop: stop.index,
                     place: stop.place,
@@ -93,7 +100,7 @@ export function resolveRoutine(config) {
         }
         let from = stops.length - 1;
         for (let i = 0; i < stops.length; i += 1) {
-            if (stops[i].departAt <= local)
+            if (stops[i].departAt <= local + tolerance)
                 from = i;
         }
         const next = (from + 1) % stops.length;
@@ -119,19 +126,20 @@ export function resolveRoutine(config) {
         stops,
         phaseAt,
         nextChangeAfter(time) {
-            const cycle = Math.floor(time / cycleSeconds) * cycleSeconds;
-            const local = wrap(time, cycleSeconds);
+            const { cycle, tolerance } = localAt(time, cycleSeconds);
             let best = Infinity;
             for (const stop of stops) {
                 for (const boundary of [stop.arriveAt, stop.departAt]) {
-                    let candidate = boundary;
-                    if (candidate <= local)
+                    // Absolute time, so a boundary that rounding has put a hair behind `time` cannot answer
+                    // with `time` itself and stall every caller that steps by the answer.
+                    let candidate = cycle + boundary;
+                    if (candidate <= time + tolerance)
                         candidate += cycleSeconds;
                     if (candidate < best)
                         best = candidate;
                 }
             }
-            return cycle + best;
+            return best;
         },
     };
 }

package/dist/ui/loadingTips.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The tip rotation behind a loading screen: a deterministic shuffle of the game's tips, shown one at a
+ * time, cycling without repeating until the list is exhausted. Deterministic for a given seed, so a
+ * capture or a test sees the same first tip every run. Presentation-free — the loading block owns the
+ * look and the timer.
+ */
+/** How a tip rotation is wired. */
+export interface TipRotationConfig {
+    /** The tips to rotate, in authored order. Empty means no tip is shown. */
+    tips: readonly string[];
+    /** Seed for the shuffle. Default `"tips"`, so the order is stable across runs. */
+    seed?: string | number;
+}
+/** Serializable rotation state. */
+export interface TipRotationSnapshot {
+    /** Shuffled indices into the authored tip list. */
+    order: number[];
+    /** Position in {@link order} of the tip being shown. */
+    cursor: number;
+}
+/** A deterministic, cycle-through tip list. */
+export interface TipRotation {
+    /** The tip being shown, or `null` when the game authored none. */
+    current(): string | null;
+    /** Advance to the next tip (wrapping) and return it. */
+    next(): string | null;
+    /** Index into {@link TipRotationConfig.tips} of the current tip, or `-1`. */
+    index(): number;
+    /** Restart at the first tip of the same shuffled order. */
+    reset(): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): TipRotationSnapshot;
+    restore(snapshot: TipRotationSnapshot): void;
+}
+/**
+ * Create a {@link TipRotation} over the game's tips. Order is a seeded shuffle; `next()` walks it and
+ * wraps, so every tip is seen once per cycle instead of a random repeat.
+ *
+ * @capability loading-tips deterministic loading-screen tip rotation with a seeded shuffle and snapshot/restore
+ */
+export declare function createTipRotation(config: TipRotationConfig): TipRotation;

package/dist/ui/loadingTips.js

@@ -0,0 +1,64 @@
+import { hashString } from "../random/rng.js";
+function shuffled(count, seed) {
+    const order = [...Array(count).keys()];
+    let state = hashString(String(seed)) >>> 0;
+    for (let i = order.length - 1; i > 0; i -= 1) {
+        state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+        const j = state % (i + 1);
+        const swap = order[i];
+        order[i] = order[j];
+        order[j] = swap;
+    }
+    return order;
+}
+/**
+ * Create a {@link TipRotation} over the game's tips. Order is a seeded shuffle; `next()` walks it and
+ * wraps, so every tip is seen once per cycle instead of a random repeat.
+ *
+ * @capability loading-tips deterministic loading-screen tip rotation with a seeded shuffle and snapshot/restore
+ */
+export function createTipRotation(config) {
+    const tips = [...config.tips];
+    let snapshot = { order: shuffled(tips.length, config.seed ?? "tips"), cursor: 0 };
+    const listeners = new Set();
+    function commit(next) {
+        snapshot = next;
+        for (const listener of listeners)
+            listener();
+    }
+    function current() {
+        if (tips.length === 0)
+            return null;
+        return tips[snapshot.order[snapshot.cursor] ?? 0] ?? null;
+    }
+    return {
+        current,
+        next() {
+            if (tips.length === 0)
+                return null;
+            commit({ order: snapshot.order, cursor: (snapshot.cursor + 1) % tips.length });
+            return current();
+        },
+        index() {
+            if (tips.length === 0)
+                return -1;
+            return snapshot.order[snapshot.cursor] ?? -1;
+        },
+        reset() {
+            commit({ order: snapshot.order, cursor: 0 });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot: () => ({ order: [...snapshot.order], cursor: snapshot.cursor }),
+        restore(next) {
+            const order = next.order.filter((index) => Number.isInteger(index) && index >= 0 && index < tips.length);
+            const valid = order.length === tips.length && new Set(order).size === tips.length;
+            commit({
+                order: valid ? [...order] : shuffled(tips.length, config.seed ?? "tips"),
+                cursor: valid ? Math.max(0, Math.min(next.cursor, tips.length - 1)) : 0,
+            });
+        },
+    };
+}