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

package/dist/menu.js

@@ -0,0 +1,129 @@
+const clean = (s) => s.replace(/[\n\t]/g, " ");
+/** @internal Hints as sent ("" the default, "-" none). */
+export function menuHints(hints) {
+    if (!hints)
+        return "";
+    if (!hints.length)
+        return "-";
+    return hints.map((h) => `${clean(h.key)}\t${clean(h.label)}`).join("\n");
+}
+/** @internal A row as sent: text, tab, value, tab, swatch. */
+export function menuRow(r) {
+    if (typeof r === "string")
+        return clean(r);
+    if (Array.isArray(r))
+        return `${clean(r[0])}\t${clean(r[1])}`;
+    const swatch = r.swatch === undefined ? "" : `\t${(r.swatch & 0xffffff).toString(16).padStart(6, "0")}`;
+    return `${clean(r.text)}\t${clean(r.value ?? "")}${swatch}`;
+}
+const MAX_ROWS = 4095; // bytes, as sent
+/** @internal The menu showing on one player (one at a time). */
+export class PlayerMenus {
+    #native;
+    #player;
+    #next = 1;
+    current = null;
+    constructor(native, player) {
+        this.#native = native;
+        this.#player = player;
+    }
+    open(options) {
+        this.current?.markClosed();
+        const id = this.#next;
+        this.#next = (this.#next % 0x7fffffff) + 1;
+        const menu = new PlayerMenu(this, id, options);
+        this.current = menu;
+        menu.send();
+        return menu;
+    }
+    send(spec) {
+        this.#native.gameMenu(this.#player, spec);
+    }
+    heard(id, kind, row) {
+        const menu = this.current;
+        if (!menu || menu.id !== id)
+            return;
+        menu.heard(kind, row);
+    }
+    /** Gone (they left, or the server reset them): no more events. */
+    forget() {
+        this.current?.markClosed();
+        this.current = null;
+    }
+}
+/**
+ * A menu on a player's screen, as the game's shops have (and SA-MP's
+ * menus): a box at the top left with a title and rows, one chosen. They
+ * move with Up/Down, select with Enter and go back with Backspace or
+ * Escape. One at a time: opening another replaces it. See `player.menu`.
+ */
+export class PlayerMenu {
+    id;
+    #menus;
+    #o;
+    #row;
+    #open = true;
+    /** @internal */
+    constructor(menus, id, options) {
+        this.#menus = menus;
+        this.id = id;
+        this.#o = { ...options };
+        this.#row = options.row ?? 0;
+    }
+    /** The row chosen. */
+    get row() {
+        return this.#row;
+    }
+    /** Still on their screen. */
+    get isOpen() {
+        return this.#open;
+    }
+    /** Changes what it shows (rows, title, footer, hints, the row chosen), in place. */
+    update(changes) {
+        if (!this.#open)
+            return this;
+        Object.assign(this.#o, changes);
+        if (changes.row !== undefined)
+            this.#row = changes.row;
+        this.#row = Math.max(0, Math.min(this.#row, this.#o.rows.length - 1));
+        this.send();
+        return this;
+    }
+    /** Takes it off their screen. */
+    close() {
+        if (!this.#open)
+            return;
+        this.markClosed();
+        if (this.#menus.current === this)
+            this.#menus.current = null;
+        this.#menus.send({ id: this.id, hide: true });
+    }
+    /** @internal */
+    markClosed() {
+        this.#open = false;
+    }
+    /** @internal */
+    send() {
+        const rows = this.#o.rows.map(menuRow).join("\n");
+        if (Buffer.byteLength(rows) > MAX_ROWS)
+            throw new RangeError(`menu rows too long (${Buffer.byteLength(rows)} bytes, at most ${MAX_ROWS})`);
+        this.#menus.send({
+            id: this.id, title: this.#o.title ?? "", rows, row: this.#row, footer: menuRow(this.#o.footer ?? ""), hints: menuHints(this.#o.hints),
+            columns: this.#o.columns ?? 0, image: this.#o.image ?? "",
+        });
+    }
+    /** @internal */
+    heard(kind, row) {
+        if (!this.#open)
+            return;
+        if (row >= 0 && row < this.#o.rows.length)
+            this.#row = row;
+        if (kind === 0)
+            this.#o.onChoose?.(this.#row, this);
+        else if (kind === 1)
+            this.#o.onSelect?.(this.#row, this);
+        else if (kind === 2)
+            this.#o.onBack?.(this);
+    }
+}
+//# sourceMappingURL=menu.js.map

package/dist/menu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu.js","sourceRoot":"","sources":["../src/menu.ts"],"names":[],"mappings":"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"}

package/dist/mission.d.ts

@@ -0,0 +1,482 @@
+import type { BlipOptions, HudCounter } from "./hud.js";
+import type { MapColor } from "./map.js";
+import type { Ped } from "./ped.js";
+import type { Player, Vector3 } from "./player.js";
+import type { PedOptions, Server, ServerEvents, VehicleOptions } from "./server.js";
+import type { CameraShot } from "./camera.js";
+import type { SpeakOptions } from "./audio.js";
+import type { Population } from "./world.js";
+import type { CutsceneOptions, CutsceneResult } from "./cutscene.js";
+import type { GameObject, ObjectOptions, Pickup, PickupOptions, Rotation } from "./objects.js";
+import type { Vehicle } from "./vehicle.js";
+/**
+ * What happens to something the mission made when it ends: `"release"`
+ * (the default: left to the game's cleanup), `"destroy"` (gone at once),
+ * `"keep"` (left for good).
+ */
+export type OnEnd = "release" | "destroy" | "keep";
+export interface EndOptions {
+    onEnd?: OnEnd;
+    /** As `onEnd: "keep"`. */
+    keep?: boolean;
+}
+/**
+ * A mission: what it's called, who may play it, and its script. Pass it to
+ * `server.missions.start()` or `server.missions.marker()`.
+ */
+/**
+ * A named step of a mission (`steps`): run in order, each a checkpoint the
+ * mission can be started from (`server.missions.start(def, players, { from })`).
+ * Starting from a step runs its `setup` first: whatever earlier steps would
+ * have left behind (a ped in a car, the party somewhere), into the state.
+ */
+export interface MissionStep<S> {
+    name: string;
+    /** Only when the mission starts from this step. */
+    setup?: (m: Mission, s: S) => Promise<void> | void;
+    run: (m: Mission, s: S) => Promise<void> | void;
+}
+export interface MissionDefinition<S = any> {
+    /** Shown nowhere by itself; used for cooldowns and `missionEvent`. */
+    name: string;
+    /** Party size. Default 1. */
+    maxPlayers?: number;
+    /** After a pass, the same player can't start it again for this long (ms). */
+    cooldown?: number;
+    /** A pass sooner than this after the start (ms) is refused, with no reward. */
+    minDuration?: number;
+    /**
+     * Checked for each player when they start or join it, and again on pass.
+     * Return a reason (shown to them) to refuse, or nothing to allow.
+     */
+    requires?: (player: Player) => string | void | undefined | null | false;
+    /** One player dying fails it for everyone. Default false: they respawn at the section start. */
+    deathFails?: boolean;
+    /**
+     * How far (m) from a new section's start a player can be before they're
+     * faded out and brought there. Default 150.
+     */
+    catchUpDistance?: number;
+    /**
+     * The mission's script. When it returns without `pass()` or `fail()`, the
+     * mission passes. Or `steps` instead.
+     */
+    run?(m: Mission): Promise<void> | void;
+    /**
+     * Or the script as named steps, run in order, sharing `state()` (made
+     * fresh for each run). Each step is a checkpoint: the mission can be
+     * started from it (testing), and `m.stage` is logged as it starts.
+     */
+    steps?: MissionStep<S>[];
+    state?: () => S;
+}
+/** Defines a mission (it only adds types). */
+export declare function defineMission<S = any>(definition: MissionDefinition<S>): MissionDefinition<S>;
+export type MissionEndReason = "passed" | "failed" | "abandoned" | "tooFast" | "requirements" | "error";
+export interface MissionOutcome {
+    passed: boolean;
+    reason: MissionEndReason;
+    /** The fail reason, or the pass subtitle. */
+    text: string;
+    /** Who was in it at the end. */
+    players: Player[];
+    ms: number;
+}
+/** What `server.on("missionEvent")` gets: every start, join, leave, pass, fail and refusal. */
+export interface MissionEvent {
+    /** `"stage"`: the script reached a stage or step (`m.stage`), its name in `reason`. */
+    type: "start" | "join" | "leave" | "pass" | "fail" | "refused" | "stage";
+    name: string;
+    mission: Mission | null;
+    /** The player who joined, left or was refused. */
+    player: Player | null;
+    /** Why it failed or was refused. */
+    reason: string;
+}
+/**
+ * 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 declare class MissionEnded extends Error {
+    readonly outcome: MissionOutcome;
+    constructor(outcome: MissionOutcome);
+}
+/** Starting or joining a mission was refused. `reason` says why. */
+export declare class MissionRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export interface WaitOptions {
+    /** The first player completes it for everyone (the default). */
+    anyPlayer?: boolean;
+    /** A waiting point: every player in the party must do it. */
+    allPlayers?: boolean;
+}
+export interface ReachOptions extends WaitOptions {
+    /** Default 3 m. */
+    radius?: number;
+    /** They must be in this vehicle (driving or riding). */
+    vehicle?: Vehicle;
+    /** Show the spot with a blip and the game's marker while it's waited for. Default true. */
+    marker?: boolean | BlipOptions;
+}
+export interface SectionOptions {
+    /** Where it starts: one spot, or one per party member (in party order). */
+    at: Vector3 | Vector3[];
+    /** Degrees. */
+    heading?: number;
+    /** Override the mission's `catchUpDistance`. */
+    catchUpDistance?: number;
+}
+/** A blip every party member has, players who join later included. */
+export declare class MissionBlip {
+    #private;
+    /** @internal */
+    constructor(target: Parameters<Player["hud"]["blip"]>[0], options: BlipOptions);
+    /** Changes its options. */
+    set(options: BlipOptions): this;
+    remove(): void;
+    /** @internal */
+    add(player: Player): void;
+    /** @internal */
+    drop(player: Player): void;
+    get removed(): boolean;
+}
+/** A HUD counter or timer every party member has. */
+export declare class MissionCounter {
+    #private;
+    /** @internal */
+    constructor(label: string, value: number, endsAt: number | null, make: (p: Player, label: string, value: number) => HudCounter);
+    /** The number (a counter), the time left (a timer, ms), or how full (a bar). */
+    get value(): number;
+    /** A timer: whether it's held still (`pause()`). */
+    get paused(): boolean;
+    /** Holds a timer still (it doesn't run out meanwhile); `resume()` counts on from there. */
+    pause(): void;
+    resume(): void;
+    /** @internal Is it a timer (counting down or up)? */
+    get isTimer(): boolean;
+    set value(value: number);
+    set label(label: string);
+    remove(): void;
+    get removed(): boolean;
+    /** @internal */
+    add(player: Player): void;
+    /** @internal */
+    drop(player: Player): void;
+}
+/**
+ * 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 declare class Mission {
+    #private;
+    readonly name: string;
+    readonly definition: MissionDefinition;
+    /** Free-form storage for the script. */
+    readonly data: Record<string, unknown>;
+    /** When it started (Date.now()). */
+    readonly startedAt: number;
+    /** Resolves when it ends, passed or not (never rejects). */
+    readonly done: Promise<MissionOutcome>;
+    /** @internal */
+    constructor(missions: Missions, server: Server, definition: MissionDefinition, players: Player[]);
+    /** The party, leader first. */
+    get players(): readonly Player[];
+    /** Who started it, or the next in line once they leave. */
+    get leader(): Player;
+    /** Whether it's still running. */
+    get running(): boolean;
+    /** How it ended, or null while it runs. */
+    get outcome(): MissionOutcome | null;
+    /**
+     * 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: Player): void;
+    /** Takes a player out of the party (their HUD for it goes). The last one leaving abandons it. */
+    removePlayer(player: Player): void;
+    /**
+     * 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: number | string, position: Vector3, heading?: number, options?: PedOptions & EndOptions): 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: number, position: Vector3, heading?: number, options?: VehicleOptions & EndOptions): Vehicle;
+    /** An object for the mission (the party sees it), removed when it ends. See `server.createObject`. */
+    createObject(model: number, position: Vector3, rotation?: Rotation, options?: ObjectOptions): GameObject;
+    /** A pickup for the mission (the party sees it), removed when it ends. See `server.createPickup`. */
+    createPickup(options: PickupOptions): Pickup;
+    /** Objective text at the bottom of the party's screens, for `ms` (left out: as long as reading takes). */
+    objective(text: string, ms?: number): void;
+    clearObjective(): void;
+    /** Big text in the middle of the party's screens. */
+    bigText(text: string, ms?: number): void;
+    /** A blip (and marker) on a spot, ped, vehicle or player, for the whole party. */
+    blip(target: Vector3 | Ped | Vehicle | Player, options?: BlipOptions): MissionBlip;
+    /** A counter on the party's HUD ("Crates 2/6"). */
+    counter(label: string, options?: {
+        value?: number;
+        max?: number;
+        bar?: boolean;
+        color?: MapColor;
+    }): MissionCounter;
+    /**
+     * 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: string, ms: number, options?: {
+        countUp?: boolean;
+        color?: MapColor;
+        fail?: string;
+    }): MissionCounter;
+    /**
+     * 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?: string): void;
+    /**
+     * Fails it when `target` dies (a ped: `"died"`), is wrecked (a vehicle:
+     * `"wrecked"`), or is removed; or when `condition()` becomes true.
+     */
+    failWhen(target: Ped, event: "died", reason: string): {
+        stop(): void;
+    };
+    failWhen(target: Vehicle, event: "wrecked", reason: string): {
+        stop(): void;
+    };
+    failWhen(condition: () => boolean, reason: string): {
+        stop(): void;
+    };
+    /** Fails it for everyone: "MISSION FAILED!" with `reason` under it. */
+    fail(reason?: string): void;
+    /**
+     * 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?: {
+        money?: number;
+        text?: string;
+    }): void;
+    /** Resolves after `ms`. */
+    wait(ms: number): Promise<void>;
+    /**
+     * 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: () => boolean, options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
+     * Waits for any promise (a ped's order, ...) but rejects with
+     * `MissionEnded` if the mission ends first. With `timeout` (ms), resolves
+     * with `undefined` if that passes first (the promise is left to finish).
+     *
+     * ```ts
+     * await m.step(benny.walkTo(OUTSIDE, { pace: "run" }), { timeout: 4000 });  // knocked down: on anyway
+     * ```
+     */
+    step<T>(promise: Promise<T>): Promise<T>;
+    step<T>(promise: Promise<T>, options: {
+        timeout: number;
+    }): Promise<T | undefined>;
+    /**
+     * 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<E extends keyof ServerEvents>(event: E, listener: ServerEvents[E]): () => void;
+    /**
+     * 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: number, fn: () => void): () => void;
+    /**
+     * 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: Partial<Population>): () => void;
+    /**
+     * 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!" });
+     * ```
+     */
+    say(file: string, options?: SpeakOptions): Promise<void>;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    cinematic(shot: CameraShot, scene: (cut: (shot: CameraShot | null) => void) => Promise<void> | void, options?: {
+        players?: readonly Player[];
+        freeze?: boolean;
+        holster?: boolean;
+    }): Promise<void>;
+    /**
+     * Marks where the script is (logged, and a `missionEvent` of type
+     * `"stage"`). Steps (`steps`) do it themselves.
+     */
+    stage(name: string): void;
+    /** The stage (or step) it's at. */
+    get currentStage(): string;
+    /** @internal Starts the steps from this one (`missions.start(..., { from })`). */
+    startFrom(step: string | null): void;
+    /** Resolves once every one of these peds is dead or gone. */
+    allDead(peds: readonly Ped[]): Promise<void>;
+    /**
+     * 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: Vector3, options?: ReachOptions): Promise<Player>;
+    /** Waits for the party to get in a vehicle: the first player (the default), or all of them at once. */
+    enter(vehicle: Vehicle, options?: WaitOptions & {
+        driver?: boolean;
+    }): Promise<Player>;
+    /**
+     * Waits until `condition(player)` holds for the first player (the default),
+     * or for every player at once (`allPlayers`). Resolves with that player.
+     */
+    untilPlayer(condition: (player: Player) => boolean, options?: WaitOptions): Promise<Player>;
+    /**
+     * 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: Ped | Vehicle | Player, options?: {
+        warnAt?: number;
+        warning?: string;
+        failAt?: number;
+        fail?: string;
+    }): {
+        stop(): void;
+    };
+    /** True if `key` was used in the last `ms` (and starts it again if not): throttles repeated actions. */
+    cooldown(key: string, ms: number): boolean;
+    /**
+     * 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: string, options?: CutsceneOptions): Promise<CutsceneResult>;
+    /**
+     * 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.
+     */
+    section(name: string, options: SectionOptions): Promise<void>;
+    /** @internal Runs the script. */
+    run(): Promise<void>;
+    /** @internal A party member respawned: back to the section start. */
+    respawned(player: Player): void;
+    /** @internal A party member died. */
+    died(player: Player): void;
+}
+export interface MarkerOptions {
+    /** Default 1.5 m. */
+    radius?: number;
+    /** Virtual world. Default 0. */
+    world?: number;
+    /** The blip and marker; `false` for none (detection only). Default: the game's yellow. */
+    blip?: BlipOptions | false;
+    /** Who's refused hears why: default an objective line for 3 s. */
+    onRefused?: (player: Player, reason: string) => void;
+}
+/** A spot that starts a mission when a player walks into it (`server.missions.marker()`). */
+export declare class MissionMarker {
+    #private;
+    readonly definition: MissionDefinition;
+    readonly position: Vector3;
+    /** @internal */
+    constructor(definition: MissionDefinition, position: Vector3, remove: () => void);
+    remove(): void;
+}
+/**
+ * Starts and tracks missions (`server.missions`). A player is in one
+ * mission at a time.
+ */
+export declare class Missions {
+    #private;
+    /** @internal */
+    constructor(server: Server, emit: (e: MissionEvent) => void);
+    /** The missions running now. */
+    get running(): Mission[];
+    /** The mission a player is in, or null. */
+    of(player: Player): Mission | 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: MissionDefinition, players: Player | readonly Player[], options?: {
+        from?: string;
+    }): Mission;
+    /**
+     * 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: MissionDefinition, at: Vector3, options?: MarkerOptions): MissionMarker;
+    /** @internal Throws MissionRefused if the player can't start or join it. */
+    admit(definition: MissionDefinition, player: Player): void;
+    /** @internal */
+    refuse(definition: MissionDefinition, player: Player, reason: string): never;
+    /** @internal */
+    bind(player: Player, mission: Mission | null): void;
+    /** @internal */
+    finished(mission: Mission, outcome: MissionOutcome): void;
+    /** @internal */
+    event(e: MissionEvent): void;
+}