@sagl/server 0.0.0-stage → 0.1.0-next.49

package/dist/mission.js

@@ -0,0 +1,1258 @@
+/** How often waits and fail conditions are checked. */
+const TICK_MS = 250;
+/** Defines a mission (it only adds types). */
+export function defineMission(definition) {
+    return definition;
+}
+/**
+ * Thrown into the script's pending waits when the mission ends (a fail
+ * condition, every player leaving, ...). The helper catches it: let it go.
+ */
+export class MissionEnded extends Error {
+    outcome;
+    constructor(outcome) {
+        super(`mission ended: ${outcome.reason}`);
+        this.name = "MissionEnded";
+        this.outcome = outcome;
+    }
+}
+/** Starting or joining a mission was refused. `reason` says why. */
+export class MissionRefused extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.name = "MissionRefused";
+        this.reason = reason;
+    }
+}
+/** A blip every party member has, players who join later included. */
+export class MissionBlip {
+    #blips = new Map();
+    #target;
+    #options;
+    #removed = false;
+    /** @internal */
+    constructor(target, options) {
+        this.#target = target;
+        this.#options = options;
+    }
+    /** Changes its options. */
+    set(options) {
+        this.#options = { ...this.#options, ...options };
+        for (const b of this.#blips.values())
+            b.set(options);
+        return this;
+    }
+    remove() {
+        this.#removed = true;
+        for (const b of this.#blips.values())
+            b.remove();
+        this.#blips.clear();
+    }
+    /** @internal */
+    add(player) {
+        if (!this.#removed && !this.#blips.has(player))
+            this.#blips.set(player, player.hud.blip(this.#target, this.#options));
+    }
+    /** @internal */
+    drop(player) {
+        this.#blips.get(player)?.remove();
+        this.#blips.delete(player);
+    }
+    get removed() {
+        return this.#removed;
+    }
+}
+/** A HUD counter or timer every party member has. */
+export class MissionCounter {
+    #counters = new Map();
+    #make;
+    #value;
+    #label;
+    #removed = false;
+    // Timers: when it reaches 0 (Date.now()), to start joiners at the right time.
+    #endsAt;
+    #pausedLeft = null; // paused: the time left
+    /** @internal */
+    constructor(label, value, endsAt, make) {
+        this.#label = label;
+        this.#value = value;
+        this.#endsAt = endsAt;
+        this.#make = (p) => {
+            const c = make(p, this.#label, this.value);
+            if (this.#pausedLeft !== null)
+                c.setPaused(true, this.#pausedLeft);
+            return c;
+        };
+    }
+    /** The number (a counter), the time left (a timer, ms), or how full (a bar). */
+    get value() {
+        if (this.#pausedLeft !== null)
+            return this.#pausedLeft;
+        return this.#endsAt === null ? this.#value : Math.max(0, this.#endsAt - Date.now());
+    }
+    /** A timer: whether it's held still (`pause()`). */
+    get paused() {
+        return this.#pausedLeft !== null;
+    }
+    /** Holds a timer still (it doesn't run out meanwhile); `resume()` counts on from there. */
+    pause() {
+        if (this.#endsAt === null || this.#pausedLeft !== null || this.#removed)
+            return;
+        this.#pausedLeft = Math.max(0, this.#endsAt - Date.now());
+        for (const c of this.#counters.values())
+            c.setPaused(true, this.#pausedLeft);
+    }
+    resume() {
+        if (this.#pausedLeft === null)
+            return;
+        const left = this.#pausedLeft;
+        this.#pausedLeft = null;
+        this.#endsAt = Date.now() + left;
+        for (const c of this.#counters.values())
+            c.setPaused(false, left);
+    }
+    /** @internal Is it a timer (counting down or up)? */
+    get isTimer() {
+        return this.#endsAt !== null;
+    }
+    set value(value) {
+        if (this.#endsAt !== null)
+            this.#endsAt = Date.now() + value;
+        else
+            this.#value = value;
+        for (const c of this.#counters.values())
+            c.value = value;
+    }
+    set label(label) {
+        this.#label = label;
+        for (const c of this.#counters.values())
+            c.label = label;
+    }
+    remove() {
+        this.#removed = true;
+        for (const c of this.#counters.values())
+            c.remove();
+        this.#counters.clear();
+    }
+    get removed() {
+        return this.#removed;
+    }
+    /** @internal */
+    add(player) {
+        if (!this.#removed && !this.#counters.has(player))
+            this.#counters.set(player, this.#make(player));
+    }
+    /** @internal */
+    drop(player) {
+        this.#counters.get(player)?.remove();
+        this.#counters.delete(player);
+    }
+}
+/**
+ * A running mission: its party, what it created (removed when it ends), its
+ * HUD, fail conditions and waits. The script gets it as `m`.
+ *
+ * Every wait (`reach`, `until`, `wait`, `step`, ...) rejects with
+ * `MissionEnded` when the mission ends, so the script stops where it is;
+ * the helper catches it. Mission calls made after the end throw it too.
+ */
+export class Mission {
+    name;
+    definition;
+    /** Free-form storage for the script. */
+    data = {};
+    /** When it started (Date.now()). */
+    startedAt = Date.now();
+    /** Resolves when it ends, passed or not (never rejects). */
+    done;
+    #missions;
+    #server;
+    #players = [];
+    #outcome = null;
+    #resolveDone;
+    #peds = [];
+    #vehicles = [];
+    #blips = [];
+    #counters = [];
+    #objective = null;
+    #failWhen = [];
+    #listeners = [];
+    #intervals = new Set();
+    #speeches = new Set();
+    #restore = []; // population changes, cinematics: undone at the end
+    #startFrom = null;
+    #stage = "";
+    #waiters = new Set();
+    #timers = new Set();
+    #cooldowns = new Map();
+    #tick;
+    #spawn = null;
+    #cutscene = null;
+    #objects = [];
+    #pickups = [];
+    #warned = new Set(); // shown keepClose's warning instead of the objective
+    /** @internal */
+    constructor(missions, server, definition, players) {
+        this.#missions = missions;
+        this.#server = server;
+        this.definition = definition;
+        this.name = definition.name;
+        this.#players = [...players];
+        this.done = new Promise((resolve) => (this.#resolveDone = resolve));
+        this.#tick = setInterval(() => this.#check(), TICK_MS);
+    }
+    /** The party, leader first. */
+    get players() {
+        return this.#players;
+    }
+    /** Who started it, or the next in line once they leave. */
+    get leader() {
+        return this.#players[0];
+    }
+    /** Whether it's still running. */
+    get running() {
+        return this.#outcome === null;
+    }
+    /** How it ended, or null while it runs. */
+    get outcome() {
+        return this.#outcome;
+    }
+    // ---- The party ----------------------------------------------------------
+    /**
+     * Adds a player to the party (an invitation). They get its HUD and see its
+     * peds. Throws `MissionRefused` if they're in another mission, it's full,
+     * they don't meet `requires`, or they're cooling down.
+     */
+    addPlayer(player) {
+        this.#live();
+        if (this.#players.includes(player))
+            return;
+        if (this.#players.length >= (this.definition.maxPlayers ?? 1))
+            this.#missions.refuse(this.definition, player, "The mission is full.");
+        this.#missions.admit(this.definition, player);
+        this.#players.push(player);
+        this.#missions.bind(player, this);
+        this.#show(player);
+        this.#updateVisibility();
+        this.#missions.event({ type: "join", name: this.name, mission: this, player, reason: "" });
+    }
+    /** Takes a player out of the party (their HUD for it goes). The last one leaving abandons it. */
+    removePlayer(player) {
+        const i = this.#players.indexOf(player);
+        if (i < 0)
+            return;
+        this.#players.splice(i, 1);
+        this.#missions.bind(player, null);
+        this.#hide(player);
+        this.#updateVisibility();
+        this.#missions.event({ type: "leave", name: this.name, mission: this, player, reason: "" });
+        if (this.running && this.#players.length === 0)
+            this.#end(false, "abandoned", "");
+    }
+    // ---- Things it creates ----------------------------------------------------
+    /**
+     * A ped for the mission. When it ends, it fades out, or if it's dead its
+     * body is released (`ped.release()`: it lies there until the cleanup
+     * takes it); with `keep` it stays for good. Seen by the party (players joining later
+     * too) unless `visibleTo` says otherwise.
+     */
+    createPed(model, position, heading = 0, options = {}) {
+        this.#live();
+        const partyVisible = options.visibleTo === undefined;
+        const ped = this.#server.createPed(model, position, heading, {
+            ...options,
+            visibleTo: options.visibleTo ?? this.#players,
+        });
+        this.#peds.push({ ped, onEnd: options.onEnd ?? (options.keep ? "keep" : "release"), partyVisible });
+        return ped;
+    }
+    /**
+     * A vehicle for the mission, released when it ends (it stays until nobody
+     * is around, as the game's), `onEnd: "destroy"` removed at once, or
+     * `onEnd: "keep"` (or `keep`) left for good.
+     */
+    createVehicle(model, position, heading = 0, options = {}) {
+        this.#live();
+        const vehicle = this.#server.createVehicle(model, position, heading, options);
+        this.#vehicles.push({ vehicle, onEnd: options.onEnd ?? (options.keep ? "keep" : "release") });
+        return vehicle;
+    }
+    /** An object for the mission (the party sees it), removed when it ends. See `server.createObject`. */
+    createObject(model, position, rotation, options = {}) {
+        this.#live();
+        const o = this.#server.createObject(model, position, rotation, { visibleTo: this.#players, ...options });
+        this.#objects.push(o);
+        return o;
+    }
+    /** A pickup for the mission (the party sees it), removed when it ends. See `server.createPickup`. */
+    createPickup(options) {
+        this.#live();
+        const p = this.#server.createPickup({ visibleTo: this.#players, ...options });
+        this.#pickups.push(p);
+        return p;
+    }
+    // ---- HUD ------------------------------------------------------------------
+    /** Objective text at the bottom of the party's screens, for `ms` (left out: as long as reading takes). */
+    objective(text, ms) {
+        this.#live();
+        if (this.#held) {
+            // Losing the cops first: this one after.
+            this.#held.before = { text, ms };
+            return;
+        }
+        this.#objective = { text, until: ms ? Date.now() + ms : Date.now() + Math.max(3000, text.length * 80) };
+        // Those keepClose is warning see it once they're back.
+        for (const p of this.#players)
+            if (!this.#warned.has(p))
+                p.hud.objective(text, ms);
+    }
+    clearObjective() {
+        if (this.#held) {
+            this.#held.before = null;
+            return;
+        }
+        this.#objective = null;
+        for (const p of this.#players)
+            p.hud.clearObjective();
+    }
+    /** Big text in the middle of the party's screens. */
+    bigText(text, ms) {
+        this.#live();
+        for (const p of this.#players)
+            p.hud.bigText(text, ms);
+    }
+    /** A blip (and marker) on a spot, ped, vehicle or player, for the whole party. */
+    blip(target, options = {}) {
+        this.#live();
+        const blip = new MissionBlip(target, options);
+        this.#blips.push(blip);
+        for (const p of this.#players)
+            blip.add(p);
+        return blip;
+    }
+    /** A counter on the party's HUD ("Crates 2/6"). */
+    counter(label, options = {}) {
+        this.#live();
+        const c = new MissionCounter(label, options.value ?? 0, null, (p, l, v) => p.hud.counter(l, { ...options, value: v }));
+        this.#counters.push(c);
+        for (const p of this.#players)
+            c.add(p);
+        return c;
+    }
+    /**
+     * A countdown on the party's HUD (or counting up with `countUp`). With
+     * `fail`, the mission fails with that reason when a countdown reaches 0.
+     */
+    timer(label, ms, options = {}) {
+        this.#live();
+        const { fail, ...hud } = options;
+        const c = new MissionCounter(label, ms, options.countUp ? null : Date.now() + ms, (p, l, v) => p.hud.timer(l, v, hud));
+        this.#counters.push(c);
+        for (const p of this.#players)
+            c.add(p);
+        if (fail !== undefined && !options.countUp) {
+            const check = () => {
+                if (!this.running || c.removed)
+                    return;
+                const left = c.value;
+                if (left <= 0)
+                    this.fail(fail);
+                else
+                    this.#later(check, left);
+            };
+            this.#later(check, ms);
+        }
+        return c;
+    }
+    /**
+     * While anyone in the party is wanted, the mission's timers stand still
+     * and `message` stays as the objective (default "Lose the ~r~cops~w~.");
+     * once they're all clear, the timers run on and the objective is back.
+     * For a mission that shouldn't be failed by a chase it didn't mean.
+     *
+     * ```ts
+     * m.holdWhileWanted();
+     * ```
+     */
+    holdWhileWanted(message = "Lose the ~r~cops~w~.") {
+        this.#live();
+        const check = () => {
+            if (!this.running)
+                return;
+            const wanted = this.#players.some((p) => p.connected && p.wantedLevel > 0);
+            const timers = this.#counters.filter((c) => c.isTimer && !c.removed);
+            if (wanted) {
+                for (const c of timers)
+                    c.pause(); // and any started meanwhile
+                if (!this.#held) {
+                    const o = this.#objective;
+                    this.#held = { before: o && o.until > Date.now() ? { text: o.text, ms: o.until === Infinity ? Infinity : o.until - Date.now() } : null };
+                    this.#objective = { text: message, until: Infinity };
+                    for (const p of this.#players)
+                        p.hud.objective(message, Infinity);
+                }
+            }
+            else if (this.#held) {
+                const before = this.#held.before;
+                this.#held = null;
+                for (const c of timers)
+                    c.resume();
+                if (before)
+                    this.objective(before.text, before.ms);
+                else
+                    this.clearObjective();
+            }
+            this.#later(check, 500);
+        };
+        check();
+    }
+    // Held while wanted: the objective the script set meanwhile, shown after.
+    #held = null;
+    failWhen(a, b, c) {
+        this.#live();
+        let entry;
+        if (typeof a === "function") {
+            entry = { check: a, reason: b };
+        }
+        else if (b === "died") {
+            const ped = a;
+            entry = { check: () => !ped.exists || ped.dead, reason: c ?? "" };
+        }
+        else {
+            const vehicle = a;
+            entry = { check: () => !vehicle.exists || vehicle.wrecked, reason: c ?? "" };
+        }
+        this.#failWhen.push(entry);
+        return {
+            stop: () => {
+                const i = this.#failWhen.indexOf(entry);
+                if (i >= 0)
+                    this.#failWhen.splice(i, 1);
+            },
+        };
+    }
+    /** Fails it for everyone: "MISSION FAILED!" with `reason` under it. */
+    fail(reason = "") {
+        if (this.running)
+            this.#end(false, "failed", reason);
+    }
+    /**
+     * Passes it: each player gets `money` (once) and "MISSION PASSED!" with
+     * `text` under it (default: the money, as "$2500"). Refused, with no
+     * reward, if it's sooner than `minDuration` or a player doesn't meet
+     * `requires` any more.
+     */
+    pass(reward = {}) {
+        if (!this.running)
+            return;
+        const ms = Date.now() - this.startedAt;
+        if (this.definition.minDuration && ms < this.definition.minDuration) {
+            console.warn(`[sagl] mission "${this.name}" passed in ${ms} ms (minDuration ${this.definition.minDuration}): refused`);
+            this.#end(false, "tooFast", "");
+            return;
+        }
+        for (const p of this.#players) {
+            const why = this.definition.requires?.(p);
+            if (why) {
+                this.#end(false, "requirements", why);
+                return;
+            }
+        }
+        const money = Math.max(0, Math.trunc(reward.money ?? 0));
+        if (money)
+            for (const p of this.#players)
+                p.giveMoney(money);
+        this.#end(true, "passed", reward.text ?? (money ? `$${money}` : ""));
+    }
+    // ---- Waiting --------------------------------------------------------------
+    /** Resolves after `ms`. */
+    wait(ms) {
+        this.#live();
+        return new Promise((resolve, reject) => {
+            const w = { check: () => false, resolve, reject };
+            this.#waiters.add(w);
+            this.#later(() => {
+                if (this.#waiters.delete(w))
+                    resolve();
+            }, ms);
+        });
+    }
+    /**
+     * Resolves once `condition()` is true (checked four times a second), with
+     * `true`; with `timeout` (ms), with `false` if that passes first. A wait
+     * with a limit can't leave a scene stuck when something gets in the way.
+     *
+     * ```ts
+     * if (!await m.until(() => benny.vehicle === cab, { timeout: 8000 })) benny.putInVehicle(cab, 2);
+     * ```
+     */
+    until(condition, options = {}) {
+        this.#live();
+        return new Promise((resolve, reject) => {
+            const w = { check: condition, resolve: () => resolve(true), reject };
+            this.#waiters.add(w);
+            if (options.timeout !== undefined) {
+                this.#later(() => {
+                    if (this.#waiters.delete(w))
+                        resolve(false);
+                }, Math.max(0, options.timeout));
+            }
+        });
+    }
+    step(promise, options = {}) {
+        this.#live();
+        return new Promise((resolve, reject) => {
+            const w = { check: () => false, resolve: () => { }, reject };
+            this.#waiters.add(w);
+            promise.then((v) => {
+                if (this.#waiters.delete(w))
+                    resolve(v);
+            }, (e) => {
+                if (this.#waiters.delete(w))
+                    reject(e);
+            });
+            if (options.timeout !== undefined) {
+                this.#later(() => {
+                    if (this.#waiters.delete(w))
+                        resolve(undefined);
+                }, Math.max(0, options.timeout));
+            }
+        });
+    }
+    // ---- Lifetime helpers ---------------------------------------------------------
+    /**
+     * Listens to a server event while the mission runs: removed when it ends
+     * (however it ends), or earlier with the function it returns.
+     *
+     * ```ts
+     * m.on("playerExitVehicle", (player, vehicle) => { if (vehicle === getaway) ... });
+     * ```
+     */
+    on(event, listener) {
+        this.#live();
+        this.#server.on(event, listener);
+        let on = true;
+        const off = () => {
+            if (!on)
+                return;
+            on = false;
+            this.#server.off(event, listener);
+            const i = this.#listeners.indexOf(off);
+            if (i >= 0)
+                this.#listeners.splice(i, 1);
+        };
+        this.#listeners.push(off);
+        return off;
+    }
+    /**
+     * Calls `fn` every `ms` while the mission runs (stopped when it ends, or
+     * with the function it returns). An error is logged, not fatal.
+     */
+    every(ms, fn) {
+        this.#live();
+        const t = setInterval(() => {
+            if (!this.running)
+                return;
+            try {
+                fn();
+            }
+            catch (e) {
+                console.error(`[sagl] mission "${this.name}" every() threw:`, e);
+            }
+        }, Math.max(10, ms));
+        this.#intervals.add(t);
+        return () => {
+            clearInterval(t);
+            this.#intervals.delete(t);
+        };
+    }
+    /**
+     * Changes the population (peds, traffic, police, fire...) of the leader's
+     * world until the mission ends (or the function it returns is called):
+     * then the settings it changed are as they were.
+     *
+     * ```ts
+     * const fireBack = m.population({ fire: false });   // no fire engines to the car we torch
+     * ```
+     */
+    population(settings) {
+        this.#live();
+        const world = this.#server.world(this.leader.world);
+        const before = world.population;
+        const was = {};
+        for (const k of Object.keys(settings))
+            was[k] = before[k];
+        world.population = settings;
+        let done = false;
+        const restore = () => {
+            if (done)
+                return;
+            done = true;
+            world.population = was;
+            const i = this.#restore.indexOf(restore);
+            if (i >= 0)
+                this.#restore.splice(i, 1);
+        };
+        this.#restore.push(restore);
+        return restore;
+    }
+    /**
+     * A recorded line with its subtitles timed to it (as speech: the radio
+     * ducks under it), shown to the party. Resolves when it's been said;
+     * stopped if the mission ends. `at` a ped (or vehicle): from them; left
+     * out, at the party's ears (`effects: "phone"` for a caller).
+     *
+     * ```ts
+     * await m.say("audio/voice-call2.mp3", { effects: "phone", subtitle: VOICE.call2, prefix: "~y~" });
+     * await m.say("audio/benny-my-car.mp3", { at: benny, subtitle: "My car! That's my car!" });
+     * ```
+     */
+    async say(file, options = {}) {
+        this.#live();
+        const speech = this.#server.audio.speak(file, {
+            ...options,
+            to: options.to ?? (options.at ? undefined : this.#players),
+            subtitleTo: options.subtitleTo ?? this.#players,
+        });
+        this.#speeches.add(speech);
+        try {
+            await this.step(speech.done);
+        }
+        finally {
+            this.#speeches.delete(speech);
+        }
+    }
+    /**
+     * A cinematic shot for the party (or `players`): black bars, the camera
+     * on `shot`, everyone frozen and their weapons put away, while `scene`
+     * runs; then the camera's back behind them, they can move and their
+     * weapons are back, however the scene ends (the mission ending too).
+     * `cut(shot)` changes the shot during it; `cut(null)` back to the first.
+     *
+     * ```ts
+     * await m.cinematic({ position: ACROSS_STREET, lookAt: car.position }, async (cut) => {
+     *   await m.wait(3000);
+     *   cut({ position: car.offset({ right: 3 }), lookAt: { vehicle: car } });
+     *   await m.wait(2000);
+     * });
+     * ```
+     */
+    async cinematic(shot, scene, options = {}) {
+        this.#live();
+        const players = (options.players ?? this.#players).filter((p) => p.connected);
+        const giveBack = [];
+        for (const p of players) {
+            if (options.freeze !== false)
+                p.frozen = true;
+            if (options.holster !== false)
+                giveBack.push(p.holster());
+        }
+        const cut = (to) => {
+            for (const p of players)
+                if (p.connected)
+                    void p.camera.set({ ...(to ?? shot), widescreen: true });
+        };
+        cut(null);
+        let restored = false;
+        const restore = () => {
+            if (restored)
+                return;
+            restored = true;
+            for (const p of players) {
+                if (!p.connected)
+                    continue;
+                p.camera.reset();
+                if (options.freeze !== false)
+                    p.frozen = false;
+            }
+            for (const g of giveBack)
+                g();
+            const i = this.#restore.indexOf(restore);
+            if (i >= 0)
+                this.#restore.splice(i, 1);
+        };
+        this.#restore.push(restore);
+        try {
+            await scene(cut);
+        }
+        finally {
+            restore();
+        }
+    }
+    /**
+     * Marks where the script is (logged, and a `missionEvent` of type
+     * `"stage"`). Steps (`steps`) do it themselves.
+     */
+    stage(name) {
+        this.#stage = name;
+        console.log(`[mission] ${this.name} (${this.leader?.name ?? "?"}): ${name}`);
+        this.#missions.event({ type: "stage", name: this.name, mission: this, player: null, reason: name });
+    }
+    /** The stage (or step) it's at. */
+    get currentStage() {
+        return this.#stage;
+    }
+    /** @internal Starts the steps from this one (`missions.start(..., { from })`). */
+    startFrom(step) {
+        this.#startFrom = step;
+    }
+    /** Resolves once every one of these peds is dead or gone. */
+    allDead(peds) {
+        return this.until(() => peds.every((p) => !p.exists || p.dead)).then(() => { });
+    }
+    /**
+     * Waits for the party to reach a spot: the first player (the default), or
+     * all of them (`allPlayers`, a waiting point: each counts once they've
+     * been there, and the rest are waited for). Shows it with a blip and the
+     * game's marker meanwhile, for those who haven't reached it. Resolves
+     * with the player who completed it (the last, for `allPlayers`).
+     */
+    reach(spot, options = {}) {
+        this.#live();
+        const radius = options.radius ?? 3;
+        const reached = new Set();
+        const at = (p) => {
+            if (reached.has(p))
+                return true;
+            if (!p.alive || dist(p.position, spot) > radius)
+                return false;
+            if (options.vehicle && p.vehicle !== options.vehicle)
+                return false;
+            reached.add(p);
+            return true;
+        };
+        const markerOptions = options.marker === false ? null : options.marker === true || !options.marker ? {} : options.marker;
+        const blip = markerOptions ? this.blip(spot, markerOptions) : null;
+        return this.#party(at, options, (done) => {
+            if (blip)
+                for (const p of done)
+                    blip.drop(p);
+        }).finally(() => blip?.remove());
+    }
+    /** Waits for the party to get in a vehicle: the first player (the default), or all of them at once. */
+    enter(vehicle, options = {}) {
+        this.#live();
+        return this.#party((p) => p.vehicle === vehicle && (!options.driver || vehicle.driver === p), options);
+    }
+    /**
+     * Waits until `condition(player)` holds for the first player (the default),
+     * or for every player at once (`allPlayers`). Resolves with that player.
+     */
+    untilPlayer(condition, options = {}) {
+        this.#live();
+        return this.#party(condition, options);
+    }
+    /**
+     * Keeps the party near someone (a ped to escort or follow, a vehicle):
+     * a player further than `warnAt` (m) gets `warning` instead of the
+     * objective until they're back in range (then the objective returns);
+     * with `failAt`, the mission fails (`fail`) when every player is further
+     * than that. Lasts until the mission ends or `stop()`.
+     */
+    keepClose(target, options = {}) {
+        this.#live();
+        const warnAt = options.warnAt ?? 25;
+        const warning = options.warning ?? "You're too far away. Go back.";
+        const warned = new Set();
+        let stopped = false;
+        const distance = (p) => {
+            const t = target.position, q = p.position;
+            return Math.hypot(t.x - q.x, t.y - q.y, t.z - q.z);
+        };
+        const check = () => {
+            if (stopped || !this.running)
+                return;
+            for (const p of this.#players) {
+                const far = distance(p) > warnAt;
+                if (far && !warned.has(p)) {
+                    warned.add(p);
+                    this.#warned.add(p);
+                    p.hud.objective(warning, 60_000);
+                }
+                else if (!far && warned.has(p)) {
+                    warned.delete(p);
+                    this.#warned.delete(p);
+                    if (this.#objective)
+                        p.hud.objective(this.#objective.text, Math.max(1, this.#objective.until - Date.now()));
+                    else
+                        p.hud.clearObjective();
+                }
+            }
+            for (const p of [...warned]) {
+                if (!this.#players.includes(p)) {
+                    warned.delete(p);
+                    this.#warned.delete(p);
+                }
+            }
+            this.#later(check, 500);
+        };
+        if (options.failAt !== undefined) {
+            const failAt = options.failAt;
+            this.failWhen(() => !stopped && this.#players.length > 0 && this.#players.every((p) => distance(p) > failAt), options.fail ?? "You left them behind.");
+        }
+        check();
+        return {
+            stop: () => {
+                stopped = true;
+                for (const p of warned) {
+                    this.#warned.delete(p);
+                    if (this.#objective)
+                        p.hud.objective(this.#objective.text, Math.max(1, this.#objective.until - Date.now()));
+                    else
+                        p.hud.clearObjective();
+                }
+                warned.clear();
+            },
+        };
+    }
+    /** True if `key` was used in the last `ms` (and starts it again if not): throttles repeated actions. */
+    cooldown(key, ms) {
+        const now = Date.now();
+        const until = this.#cooldowns.get(key) ?? 0;
+        if (now < until)
+            return true;
+        this.#cooldowns.set(key, now + ms);
+        return false;
+    }
+    /**
+     * Plays one of the game's cutscenes (e.g. `"ryder2a"`) for the party
+     * together; resolves when everyone's has finished. The leader's skip ends
+     * it for everyone (see `CutsceneOptions`). Ending the mission stops it.
+     */
+    cutscene(name, options = {}) {
+        this.#live();
+        this.#cutscene?.stop();
+        const play = this.#server.playCutscene(this.#players, name, options);
+        this.#cutscene = play;
+        return this.step(play.done).finally(() => {
+            if (this.#cutscene === play)
+                this.#cutscene = null;
+        });
+    }
+    // ---- Sections -------------------------------------------------------------
+    /**
+     * Starts a section: where the party respawns if they die, and where
+     * anyone far behind (more than `catchUpDistance`, or in another world)
+     * is brought, faded out and back in. Resolves once they're there.
+     */
+    async section(name, options) {
+        this.#live();
+        const spots = Array.isArray(options.at) ? options.at : [options.at];
+        if (spots.length === 0)
+            throw new RangeError(`section "${name}": no spots`);
+        this.#spawn = { at: spots, heading: options.heading ?? 0 };
+        const far = options.catchUpDistance ?? this.definition.catchUpDistance ?? 150;
+        const world = this.leader.world;
+        const behind = this.#players.filter((p, i) => p.alive && (p.world !== world || dist(p.position, spots[i % spots.length]) > far));
+        await Promise.all(behind.map((p) => this.#bring(p, 500)));
+    }
+    // ---- Internals ------------------------------------------------------------
+    /** @internal Runs the script. */
+    async run() {
+        for (const p of this.#players)
+            this.#missions.bind(p, this);
+        try {
+            const steps = this.definition.steps;
+            if (steps?.length) {
+                const state = this.definition.state ? this.definition.state() : {};
+                let i = this.#startFrom ? steps.findIndex((s) => s.name === this.#startFrom) : 0;
+                if (i < 0)
+                    throw new RangeError(`mission "${this.name}" has no step "${this.#startFrom}"`);
+                if (i > 0)
+                    await steps[i].setup?.(this, state);
+                for (; i < steps.length && this.running; ++i) {
+                    this.stage(steps[i].name);
+                    await steps[i].run(this, state);
+                }
+            }
+            else {
+                await this.definition.run?.(this);
+            }
+            if (this.running)
+                this.pass();
+        }
+        catch (e) {
+            if (e instanceof MissionEnded)
+                return;
+            console.error(`[sagl] mission "${this.name}" threw:`, e);
+            if (this.running)
+                this.#end(false, "error", "");
+        }
+    }
+    /** @internal A party member respawned: back to the section start. */
+    respawned(player) {
+        // After the gamemode's own playerSpawn handlers, which may place them.
+        if (this.running && this.#spawn)
+            this.#later(() => void this.#bring(player, 0), 100);
+    }
+    /** @internal A party member died. */
+    died(player) {
+        if (!this.running)
+            return;
+        if (this.definition.deathFails) {
+            this.#end(false, "failed", `${player.name} died.`);
+        }
+        else if (this.#players.every((p) => p === player || !p.alive)) {
+            this.#end(false, "failed", "Everyone died.");
+        }
+    }
+    // Faded out, moved to their section spot, faded in.
+    async #bring(player, fadeMs) {
+        if (!this.#spawn)
+            return;
+        const i = Math.max(0, this.#players.indexOf(player));
+        const spot = this.#spawn.at[i % this.#spawn.at.length];
+        if (fadeMs)
+            await player.fadeOut(fadeMs);
+        if (!player.connected)
+            return;
+        player.world = this.leader?.world ?? player.world;
+        player.setPosition(spot, this.#spawn.heading);
+        await new Promise((r) => setTimeout(r, 300)); // the world streams in
+        await player.fadeIn(fadeMs || 300);
+    }
+    #party(condition, options, progress) {
+        const all = options.allPlayers === true;
+        let last = null;
+        return new Promise((resolve, reject) => {
+            const w = {
+                check: () => {
+                    const done = this.#players.filter(condition);
+                    progress?.(done);
+                    if (done.length === 0)
+                        return false;
+                    if (all && done.length < this.#players.length)
+                        return false;
+                    last = done[done.length - 1];
+                    return true;
+                },
+                resolve: () => resolve(last),
+                reject,
+            };
+            this.#waiters.add(w);
+        });
+    }
+    #wait(check) {
+        return new Promise((resolve, reject) => {
+            this.#waiters.add({ check, resolve, reject });
+        });
+    }
+    #check() {
+        if (!this.running)
+            return;
+        for (const f of this.#failWhen) {
+            let hit = false;
+            try {
+                hit = f.check();
+            }
+            catch (e) {
+                console.error(`[sagl] mission "${this.name}" fail condition threw:`, e);
+            }
+            if (hit) {
+                this.#end(false, "failed", f.reason);
+                return;
+            }
+        }
+        for (const w of [...this.#waiters]) {
+            let ok = false;
+            try {
+                ok = w.check();
+            }
+            catch (e) {
+                this.#waiters.delete(w);
+                w.reject(e);
+                continue;
+            }
+            if (ok && this.#waiters.delete(w))
+                w.resolve();
+        }
+    }
+    #later(fn, ms) {
+        const t = setTimeout(() => {
+            this.#timers.delete(t);
+            fn();
+        }, ms);
+        this.#timers.add(t);
+    }
+    #live() {
+        if (this.#outcome)
+            throw new MissionEnded(this.#outcome);
+    }
+    // A joining player gets the HUD as it is.
+    #show(player) {
+        for (const b of this.#blips)
+            b.add(player);
+        for (const c of this.#counters)
+            c.add(player);
+        if (this.#objective && this.#objective.until > Date.now()) {
+            player.hud.objective(this.#objective.text, this.#objective.until - Date.now());
+        }
+    }
+    #hide(player) {
+        if (!player.connected)
+            return;
+        for (const b of this.#blips)
+            b.drop(player);
+        for (const c of this.#counters)
+            c.drop(player);
+        player.hud.clearObjective();
+    }
+    #updateVisibility() {
+        for (const { ped, partyVisible } of this.#peds) {
+            if (partyVisible && ped.exists)
+                ped.visibleTo = this.#players;
+        }
+    }
+    #end(passed, reason, text) {
+        if (this.#outcome)
+            return;
+        const outcome = { passed, reason, text, players: [...this.#players], ms: Date.now() - this.startedAt };
+        this.#outcome = outcome;
+        clearInterval(this.#tick);
+        this.#cutscene?.stop();
+        for (const off of [...this.#listeners])
+            off();
+        for (const t of this.#intervals)
+            clearInterval(t);
+        this.#intervals.clear();
+        for (const sp of this.#speeches)
+            sp.stop();
+        this.#speeches.clear();
+        for (const r of [...this.#restore].reverse()) {
+            try {
+                r();
+            }
+            catch (e) {
+                console.error(`[sagl] mission "${this.name}" cleanup threw:`, e);
+            }
+        }
+        for (const t of this.#timers)
+            clearTimeout(t);
+        this.#timers.clear();
+        const ended = new MissionEnded(outcome);
+        for (const w of this.#waiters)
+            w.reject(ended);
+        this.#waiters.clear();
+        // Cleanup: its HUD, and what it made.
+        for (const b of this.#blips)
+            b.remove();
+        for (const c of this.#counters)
+            c.remove();
+        // Its characters go (fading out); bodies lie where they fell until
+        // the cleanup takes them, and vehicles stay until nobody is around, as
+        // in the game. `keep` ones stay for good.
+        for (const { ped, onEnd } of this.#peds) {
+            if (!ped.exists)
+                continue;
+            if (onEnd === "keep")
+                ped.visibleTo = "world";
+            else if (ped.dead && onEnd === "release")
+                ped.release();
+            else
+                ped.destroy();
+        }
+        for (const { vehicle, onEnd } of this.#vehicles) {
+            if (!vehicle.exists || onEnd === "keep")
+                continue;
+            if (onEnd === "destroy")
+                vehicle.destroy();
+            else
+                vehicle.release();
+        }
+        for (const o of this.#objects)
+            o.destroy();
+        for (const p of this.#pickups)
+            p.remove();
+        for (const p of this.#players) {
+            if (!p.connected)
+                continue;
+            p.hud.clearObjective();
+            if (passed)
+                p.hud.missionPassed(text);
+            else if (reason !== "abandoned")
+                p.hud.missionFailed(text);
+            this.#missions.bind(p, null);
+        }
+        this.#missions.finished(this, outcome);
+        this.#resolveDone(outcome);
+    }
+}
+/** A spot that starts a mission when a player walks into it (`server.missions.marker()`). */
+export class MissionMarker {
+    definition;
+    position;
+    #remove;
+    /** @internal */
+    constructor(definition, position, remove) {
+        this.definition = definition;
+        this.position = position;
+        this.#remove = remove;
+    }
+    remove() {
+        this.#remove();
+    }
+}
+/**
+ * Starts and tracks missions (`server.missions`). A player is in one
+ * mission at a time.
+ */
+export class Missions {
+    #server;
+    #emit;
+    #of = new Map();
+    #running = new Set();
+    // Cooldowns by mission name, then player name (names are the closest thing
+    // to an identity until players have accounts).
+    #passedAt = new Map();
+    /** @internal */
+    constructor(server, emit) {
+        this.#server = server;
+        this.#emit = emit;
+        server.on("playerQuit", (p) => this.#of.get(p)?.removePlayer(p));
+        server.on("playerDeath", (p) => this.#of.get(p)?.died(p));
+        server.on("playerSpawn", (p) => this.#of.get(p)?.respawned(p));
+    }
+    /** The missions running now. */
+    get running() {
+        return [...this.#running];
+    }
+    /** The mission a player is in, or null. */
+    of(player) {
+        return this.#of.get(player) ?? null;
+    }
+    /**
+     * Starts a mission for these players (the first is the leader). Throws
+     * `MissionRefused` if any of them is in a mission, cooling down or
+     * doesn't meet `requires`, or there are too many.
+     */
+    start(definition, players, options = {}) {
+        if (options.from !== undefined && !definition.steps?.some((st) => st.name === options.from)) {
+            throw new RangeError(`mission "${definition.name}" has no step "${options.from}"`);
+        }
+        const party = Array.isArray(players) ? [...players] : [players];
+        if (party.length === 0)
+            throw new RangeError("a mission needs a player");
+        if (party.length > (definition.maxPlayers ?? 1)) {
+            this.refuse(definition, party[0], `At most ${definition.maxPlayers ?? 1} players.`);
+        }
+        for (const p of party)
+            this.admit(definition, p);
+        const m = new Mission(this, this.#server, definition, party);
+        m.startFrom(options.from ?? null);
+        this.#running.add(m);
+        for (const p of party)
+            this.#of.set(p, m);
+        this.event({ type: "start", name: definition.name, mission: m, player: party[0], reason: "" });
+        void m.run();
+        return m;
+    }
+    /**
+     * A start marker: a blip and the game's yellow marker for everyone not in
+     * a mission. Walking into it on foot starts the mission with everyone
+     * else standing in it (up to `maxPlayers`).
+     */
+    marker(definition, at, options = {}) {
+        const radius = options.radius ?? 1.5;
+        const world = options.world ?? 0;
+        const blips = new Map();
+        const inside = new Set();
+        const refused = options.onRefused ?? ((p, why) => p.hud.objective(why, 3000));
+        const tick = setInterval(() => {
+            for (const p of this.#server.players) {
+                const free = !this.#of.has(p) && p.world === world;
+                const blip = blips.get(p);
+                if (options.blip !== false && free && !blip)
+                    blips.set(p, p.hud.blip(at, options.blip || {}));
+                if (blip && !free) {
+                    blip.remove();
+                    blips.delete(p);
+                }
+                // Only walking in starts it: whoever is still standing in it when a
+                // mission ends (or after being refused) has to step out first.
+                if (p.world !== world || dist(p.position, at) > radius) {
+                    inside.delete(p);
+                    continue;
+                }
+                if (inside.has(p))
+                    continue;
+                if (!p.alive || p.vehicle)
+                    continue; // getting out in it counts as walking in
+                inside.add(p);
+                if (!free)
+                    continue;
+                const others = this.#server.players.filter((o) => o !== p && !this.#of.has(o) && o.world === world &&
+                    o.alive && !o.vehicle && dist(o.position, at) <= radius);
+                const party = [p, ...others].slice(0, definition.maxPlayers ?? 1);
+                for (const o of party)
+                    inside.add(o);
+                try {
+                    this.start(definition, party);
+                }
+                catch (e) {
+                    if (e instanceof MissionRefused)
+                        refused(p, e.reason);
+                    else
+                        throw e;
+                }
+            }
+            for (const p of [...blips.keys()])
+                if (!p.connected)
+                    blips.delete(p);
+            for (const p of [...inside])
+                if (!p.connected)
+                    inside.delete(p);
+        }, TICK_MS);
+        return new MissionMarker(definition, at, () => {
+            clearInterval(tick);
+            for (const b of blips.values())
+                b.remove();
+            blips.clear();
+        });
+    }
+    /** @internal Throws MissionRefused if the player can't start or join it. */
+    admit(definition, player) {
+        if (this.#of.has(player))
+            this.refuse(definition, player, "You're already on a mission.");
+        const passed = this.#passedAt.get(definition.name)?.get(player.name);
+        if (definition.cooldown && passed !== undefined && Date.now() - passed < definition.cooldown) {
+            const minutes = Math.ceil((definition.cooldown - (Date.now() - passed)) / 60000);
+            this.refuse(definition, player, `Try again in ${minutes} minute${minutes === 1 ? "" : "s"}.`);
+        }
+        const why = definition.requires?.(player);
+        if (why)
+            this.refuse(definition, player, why);
+    }
+    /** @internal */
+    refuse(definition, player, reason) {
+        this.event({ type: "refused", name: definition.name, mission: null, player, reason });
+        throw new MissionRefused(reason);
+    }
+    /** @internal */
+    bind(player, mission) {
+        if (mission)
+            this.#of.set(player, mission);
+        else
+            this.#of.delete(player);
+    }
+    /** @internal */
+    finished(mission, outcome) {
+        this.#running.delete(mission);
+        if (outcome.passed) {
+            const byName = this.#passedAt.get(mission.name) ?? new Map();
+            for (const p of outcome.players)
+                byName.set(p.name, Date.now());
+            this.#passedAt.set(mission.name, byName);
+        }
+        this.event({ type: outcome.passed ? "pass" : "fail", name: mission.name, mission, player: null,
+            reason: outcome.passed ? "" : outcome.reason === "failed" ? outcome.text || "failed" : outcome.reason });
+    }
+    /** @internal */
+    event(e) {
+        this.#emit(e);
+    }
+}
+function dist(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+//# sourceMappingURL=mission.js.map