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

package/dist/cutscene.d.ts

@@ -0,0 +1,47 @@
+import type { NativeServer } from "./native.js";
+import type { Player } from "./player.js";
+export interface CutsceneOptions {
+    /**
+     * How it's skipped (the game's skip button):
+     * - `"vote"` (the default): each press is a vote, and it skips for
+     *   everyone once a majority of those watching have voted (`skipVotes`);
+     * - `"leader"`: the first player's press skips it for everyone;
+     * - `"anyone"`: anyone's press skips it for everyone;
+     * - `"none"`: it can't be skipped.
+     *
+     * Nobody skips it on their own: everyone sees the same thing.
+     */
+    skip?: "vote" | "leader" | "anyone" | "none";
+    /**
+     * For `"vote"`: it skips once more than this share of the watchers have
+     * voted (everyone at most). Default 0.5, a majority: 2 of 2, 2 of 3, 3 of
+     * 4. 1: everyone.
+     */
+    skipVotes?: number;
+    /** How long to wait for slow loaders before starting without them (ms). Default 20 s. */
+    loadTimeout?: number;
+}
+export interface CutsceneResult {
+    /** Whether it was skipped for everyone (or stopped). */
+    skipped: boolean;
+    /** Who watched it (loaded in time and stayed). */
+    players: Player[];
+}
+/** A cutscene playing for a group of players (`server.playCutscene()`). */
+export declare class CutscenePlay {
+    #private;
+    readonly id: number;
+    readonly name: string;
+    /** Resolves when everyone's has finished (or it was stopped). Never rejects. */
+    readonly done: Promise<CutsceneResult>;
+    /** @internal */
+    constructor(native: NativeServer, id: number, players: Player[], name: string, options: CutsceneOptions, finished: (play: CutscenePlay) => void);
+    /** Whether it has finished for everyone. */
+    get over(): boolean;
+    /** Stops it for everyone (or, before it starts, cancels it). */
+    stop(): void;
+    /** @internal */
+    state(player: Player, state: "loaded" | "finished" | "failed" | "skipVote", skipped: boolean): void;
+    /** @internal A player left. */
+    left(player: Player): void;
+}

package/dist/cutscene.js

@@ -0,0 +1,190 @@
+const ACTION = { load: 0, start: 1, stop: 2 };
+/** A cutscene playing for a group of players (`server.playCutscene()`). */
+export class CutscenePlay {
+    id;
+    name;
+    /** Resolves when everyone's has finished (or it was stopped). Never rejects. */
+    done;
+    #native;
+    #options;
+    #players;
+    #phase = new Map();
+    #watched = new Set();
+    #skipped = false;
+    #started = false;
+    #over = false;
+    #resolve;
+    #timer;
+    #votes = new Set();
+    #voteText = new Map();
+    #finished;
+    /** @internal */
+    constructor(native, id, players, name, options, finished) {
+        this.#native = native;
+        this.id = id;
+        this.name = name;
+        this.#options = options;
+        this.#players = players.filter((p) => p.connected);
+        this.#finished = finished;
+        this.done = new Promise((resolve) => (this.#resolve = resolve));
+        for (const p of this.#players) {
+            this.#phase.set(p, "loading");
+            native.cutscene(p.id, id, ACTION.load, name);
+        }
+        this.#timer = setTimeout(() => this.#start(), options.loadTimeout ?? 20_000);
+        this.#check();
+    }
+    /** Whether it has finished for everyone. */
+    get over() {
+        return this.#over;
+    }
+    /** Stops it for everyone (or, before it starts, cancels it). */
+    stop() {
+        if (this.#over)
+            return;
+        this.#skipped = true;
+        for (const [p, phase] of this.#phase) {
+            if (phase !== "done" && p.connected)
+                this.#native.cutscene(p.id, this.id, ACTION.stop);
+        }
+        // Their games report back; don't wait on anyone who never does.
+        setTimeout(() => this.#finish(), 3000);
+    }
+    /** @internal */
+    state(player, state, skipped) {
+        if (this.#over)
+            return;
+        const phase = this.#phase.get(player);
+        if (!phase || phase === "done")
+            return;
+        if (state === "skipVote") {
+            if (phase === "playing")
+                this.#vote(player);
+            return;
+        }
+        if (state === "loaded") {
+            if (this.#started) {
+                // Too late: everyone else has started.
+                this.#native.cutscene(player.id, this.id, ACTION.stop);
+                this.#phase.set(player, "done");
+            }
+            else {
+                this.#phase.set(player, "loaded");
+            }
+        }
+        else {
+            this.#phase.set(player, "done");
+        }
+        this.#check();
+    }
+    // A press of the skip button.
+    #vote(player) {
+        const mode = this.#options.skip ?? "vote";
+        if (mode === "none")
+            return;
+        if (mode === "anyone" || (mode === "leader" && player === this.#players[0])) {
+            this.stop();
+            return;
+        }
+        if (mode !== "vote")
+            return;
+        this.#votes.add(player);
+        this.#tally();
+    }
+    // The vote as it stands: skipped once it has a majority (more than
+    // `skipVotes` of those watching, everyone at most), else shown on screen.
+    #tally() {
+        if (this.#over || (this.#options.skip ?? "vote") !== "vote")
+            return;
+        const watching = [...this.#phase].filter(([p, phase]) => phase === "playing" && p.connected).map(([p]) => p);
+        if (watching.length === 0)
+            return;
+        const votes = watching.filter((p) => this.#votes.has(p)).length;
+        const share = Math.min(1, Math.max(0, this.#options.skipVotes ?? 0.5));
+        const needed = Math.min(watching.length, Math.floor(watching.length * share) + 1);
+        if (votes >= needed) {
+            this.stop();
+            return;
+        }
+        for (const p of watching) {
+            const text = this.#votes.has(p)
+                ? `Skip ~y~${votes}/${needed}~w~: waiting for the others`
+                : `Skip ~y~${votes}/${needed}~w~: press ~y~Space~w~ or ~y~Enter`;
+            this.#prompt(p, text);
+        }
+    }
+    // Bottom right of their screen, over the cutscene.
+    #prompt(player, text) {
+        const d = this.#voteText.get(player);
+        if (d)
+            d.set({ text });
+        else
+            this.#voteText.set(player, player.draw.text(text, -16, -40, { anchor: "bottom-right", align: "right", font: "sa-menu", size: 14, outline: 1 }));
+    }
+    /** @internal A player left. */
+    left(player) {
+        if (!this.#phase.has(player))
+            return;
+        this.#phase.set(player, "done");
+        this.#watched.delete(player);
+        this.#voteText.delete(player);
+        this.#check();
+        if (this.#started)
+            this.#tally(); // fewer watching: fewer votes needed
+    }
+    #check() {
+        const phases = [...this.#phase.values()];
+        if (!this.#started && !phases.includes("loading"))
+            this.#start();
+        if (this.#started && phases.every((p) => p === "done"))
+            this.#finish();
+    }
+    // Starts it for everyone whose has loaded; whoever is still loading misses it.
+    #start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = null;
+        for (const [p, phase] of this.#phase) {
+            if (!p.connected)
+                continue;
+            if (phase === "loaded") {
+                this.#phase.set(p, "playing");
+                this.#watched.add(p);
+                this.#native.cutscene(p.id, this.id, ACTION.start);
+            }
+            else if (phase === "loading") {
+                this.#phase.set(p, "done");
+                this.#native.cutscene(p.id, this.id, ACTION.stop);
+            }
+        }
+        // How to skip, from the start.
+        const mode = this.#options.skip ?? "vote";
+        if (mode === "vote")
+            this.#tally();
+        else if (mode === "anyone")
+            for (const p of this.#watched)
+                this.#prompt(p, "Press ~y~Space~w~ or ~y~Enter~w~ to skip");
+        else if (mode === "leader" && this.#watched.has(this.#players[0]))
+            this.#prompt(this.#players[0], "Press ~y~Space~w~ or ~y~Enter~w~ to skip");
+        this.#check();
+    }
+    #finish() {
+        if (this.#over)
+            return;
+        this.#over = true;
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = null;
+        for (const p of this.#phase.keys())
+            this.#phase.set(p, "done");
+        for (const d of this.#voteText.values())
+            d.remove();
+        this.#voteText.clear();
+        this.#finished(this);
+        this.#resolve({ skipped: this.#skipped, players: [...this.#watched].filter((p) => p.connected) });
+    }
+}
+//# sourceMappingURL=cutscene.js.map

package/dist/cutscene.js.map

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

package/dist/draw.d.ts

@@ -0,0 +1,106 @@
+import type { NativeDraw, NativeServer } from "./native.js";
+import { type MapColor } from "./map.js";
+import type { Player } from "./player.js";
+/** A font for drawn text: the game's own, or Inter. */
+export type DrawFont = "pricedown" | "sa-menu" | "sa-text" | "sa-gothic" | "Inter";
+/**
+ * Where on the screen a draw's position is measured from: a corner, the
+ * middle of an edge, or the centre. `"canvas"`: SA-MP's 640x448 canvas,
+ * stretched to the screen, for code ported from SA-MP.
+ */
+export type Anchor = "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right" | "canvas";
+/** Where a draw sits. */
+export interface PlaceOptions {
+    /** Default `"top-left"`. */
+    anchor?: Anchor;
+    /** Higher on top. */
+    layer?: number;
+}
+/**
+ * How drawn text looks. Positions and sizes are in units of 1/448 of the
+ * screen height (the same horizontally: nothing stretches), from `anchor`.
+ */
+export interface TextOptions extends PlaceOptions {
+    /** Default `"sa-text"` (the game's subtitle font). */
+    font?: DrawFont;
+    /** Text height on the canvas. Default 12. */
+    size?: number;
+    /** `"#RRGGBB[AA]"` or 0xRRGGBBAA. Default white. */
+    color?: MapColor;
+    /** A black outline this thick (canvas units); the game's look is about 1. */
+    outline?: number;
+    /** A black drop shadow this far (canvas units), instead of an outline. */
+    shadow?: number;
+    /** The outline's or shadow's colour instead of black (SA-MP's TextDrawBackgroundColor). */
+    outlineColor?: MapColor;
+    /** A box behind the text in this colour. */
+    box?: MapColor;
+    /** Space between the text and its box. */
+    boxPadding?: number;
+    /** Which edge `x` is: `"left"` (default), `"center"`, `"right"`. */
+    align?: "left" | "center" | "right";
+    /** Wraps at this width; left out, one line. */
+    width?: number;
+}
+/** What a draw can change to (`drawn.set()`). */
+export type DrawChanges = TextOptions & {
+    text?: string;
+    x?: number;
+    y?: number;
+    height?: number;
+    file?: string;
+};
+/** @internal */
+export declare function encodeDraw(o: DrawChanges): Partial<NativeDraw>;
+/** Something drawn on screen: change it with `set()`, take it away with `remove()`. */
+export declare class Drawn {
+    #private;
+    /** @internal */
+    constructor(spec: NativeDraw, send: (spec: NativeDraw) => void);
+    get id(): number;
+    /** Changes it: text, position, colour, ... */
+    set(changes: DrawChanges): this;
+    remove(): void;
+    /** @internal */
+    get removed(): boolean;
+    /** @internal */
+    get spec(): NativeDraw;
+}
+/**
+ * Drawing on screen, SA-MP textdraw style: text, boxes and images at
+ * offsets from an anchor point of the screen (a corner, an edge, the
+ * centre), in units of 1/448 of the screen height, the same both ways, so
+ * nothing stretches and things stay by their edge on any screen. `player.draw`
+ * is one player's; `server.draw` everyone's (players joining later too).
+ * Client scripts have the same, apart (`sagl.draw`).
+ */
+export declare class ScreenDraw {
+    #private;
+    /** @internal */
+    constructor(send: (spec: NativeDraw) => void, nextId: () => number);
+    /**
+     * Text at `x`, `y` from its anchor (`y` is its top; `align` picks which of
+     * its edges `x` is). Negative offsets go left / up.
+     */
+    text(text: string, x: number, y: number, options?: TextOptions): Drawn;
+    /** A filled rectangle. */
+    box(x: number, y: number, width: number, height: number, color?: MapColor, options?: PlaceOptions & {
+        align?: "left" | "center" | "right";
+    }): Drawn;
+    /** An image: a client file (PNG or JPEG), optionally tinted with `color`. */
+    image(file: string, x: number, y: number, width: number, height: number, options?: PlaceOptions & {
+        color?: MapColor;
+        align?: "left" | "center" | "right";
+    }): Drawn;
+}
+/** @internal Everyone's draws: kept, so players joining later get them. */
+export declare class ServerDraw extends ScreenDraw {
+    #private;
+    constructor(native: NativeServer, players: () => Player[], nextId: () => number);
+    /** @internal Wraps creation to remember it. */
+    text(...a: Parameters<ScreenDraw["text"]>): Drawn;
+    box(...a: Parameters<ScreenDraw["box"]>): Drawn;
+    image(...a: Parameters<ScreenDraw["image"]>): Drawn;
+    /** @internal A player joined: everything drawn for everyone. */
+    replay(player: Player): void;
+}

package/dist/draw.js

@@ -0,0 +1,132 @@
+import { mapColor } from "./map.js";
+const ANCHOR = {
+    "top-left": 0, top: 1, "top-right": 2, left: 3, center: 4, right: 5,
+    "bottom-left": 6, bottom: 7, "bottom-right": 8, canvas: 9,
+};
+const ALIGN = { left: 0, center: 1, right: 2 };
+/** @internal */
+export function encodeDraw(o) {
+    const out = {};
+    for (const k of ["x", "y", "width", "height", "size", "outline", "shadow", "boxPadding", "layer", "font"]) {
+        if (o[k] !== undefined)
+            out[k] = o[k];
+    }
+    if (o.text !== undefined)
+        out.text = String(o.text).slice(0, 511);
+    if (o.file !== undefined)
+        out.text = o.file;
+    if (o.color !== undefined)
+        out.color = mapColor(o.color, 0xffffffff);
+    if (o.box !== undefined)
+        out.boxColor = o.box ? mapColor(o.box, 0x00000080) : 0;
+    if (o.outlineColor !== undefined)
+        out.outlineColor = mapColor(o.outlineColor, 0x000000ff);
+    if (o.align !== undefined)
+        out.align = ALIGN[o.align];
+    if (o.anchor !== undefined)
+        out.anchor = ANCHOR[o.anchor];
+    return out;
+}
+/** Something drawn on screen: change it with `set()`, take it away with `remove()`. */
+export class Drawn {
+    #spec;
+    #send;
+    #removed = false;
+    /** @internal */
+    constructor(spec, send) {
+        this.#spec = spec;
+        this.#send = send;
+        send(spec);
+    }
+    get id() {
+        return this.#spec.id;
+    }
+    /** Changes it: text, position, colour, ... */
+    set(changes) {
+        if (this.#removed)
+            return this;
+        this.#spec = { ...this.#spec, ...encodeDraw(changes) };
+        this.#send(this.#spec);
+        return this;
+    }
+    remove() {
+        if (this.#removed)
+            return;
+        this.#removed = true;
+        this.#send({ id: this.#spec.id, remove: true });
+    }
+    /** @internal */
+    get removed() {
+        return this.#removed;
+    }
+    /** @internal */
+    get spec() {
+        return this.#spec;
+    }
+}
+/**
+ * Drawing on screen, SA-MP textdraw style: text, boxes and images at
+ * offsets from an anchor point of the screen (a corner, an edge, the
+ * centre), in units of 1/448 of the screen height, the same both ways, so
+ * nothing stretches and things stay by their edge on any screen. `player.draw`
+ * is one player's; `server.draw` everyone's (players joining later too).
+ * Client scripts have the same, apart (`sagl.draw`).
+ */
+export class ScreenDraw {
+    #send;
+    #nextId;
+    /** @internal */
+    constructor(send, nextId) {
+        this.#send = send;
+        this.#nextId = nextId;
+    }
+    /**
+     * Text at `x`, `y` from its anchor (`y` is its top; `align` picks which of
+     * its edges `x` is). Negative offsets go left / up.
+     */
+    text(text, x, y, options = {}) {
+        return new Drawn({ id: this.#nextId(), kind: 0, ...encodeDraw({ ...options, text, x, y }) }, this.#send);
+    }
+    /** A filled rectangle. */
+    box(x, y, width, height, color = 0x00000080, options = {}) {
+        return new Drawn({ id: this.#nextId(), kind: 1, ...encodeDraw({ x, y, width, height, color, ...options }) }, this.#send);
+    }
+    /** An image: a client file (PNG or JPEG), optionally tinted with `color`. */
+    image(file, x, y, width, height, options = {}) {
+        return new Drawn({ id: this.#nextId(), kind: 2, ...encodeDraw({ file, x, y, width, height, ...options }) }, this.#send);
+    }
+}
+/** @internal Everyone's draws: kept, so players joining later get them. */
+export class ServerDraw extends ScreenDraw {
+    #all = new Map();
+    #native;
+    #players;
+    constructor(native, players, nextId) {
+        let self = null;
+        super((spec) => self.#broadcast(spec), nextId);
+        self = this;
+        this.#native = native;
+        this.#players = players;
+    }
+    #broadcast(spec) {
+        for (const p of this.#players())
+            this.#native.draw(p.id, spec);
+        if (spec.remove)
+            this.#all.delete(spec.id);
+    }
+    /** @internal Wraps creation to remember it. */
+    text(...a) { return this.#keep(super.text(...a)); }
+    box(...a) { return this.#keep(super.box(...a)); }
+    image(...a) { return this.#keep(super.image(...a)); }
+    #keep(d) {
+        this.#all.set(d.id, d);
+        return d;
+    }
+    /** @internal A player joined: everything drawn for everyone. */
+    replay(player) {
+        for (const d of this.#all.values())
+            if (!d.removed)
+                this.#native.draw(player.id, d.spec);
+    }
+}
+//# sourceMappingURL=draw.js.map

package/dist/draw.js.map

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

package/dist/effects.d.ts

@@ -0,0 +1,91 @@
+import type { NativeServer } from "./native.js";
+import { GameObject, Broadcast } from "./objects.js";
+import { type MapColor } from "./map.js";
+import { Ped } from "./ped.js";
+import { Player, type Vector3 } from "./player.js";
+import { Vehicle } from "./vehicle.js";
+/** Where an effect is: a spot, or a player, ped, vehicle or object it follows. */
+export type EffectTarget = Vector3 | Player | Ped | Vehicle | GameObject;
+export interface EffectOptions {
+    /** From what it's on (m, in its own space), or from the spot. */
+    offset?: Vector3;
+    /**
+     * Runs until `stop()` (a fire, smoke from a chimney), and is shown to
+     * players joining later. Default false: it plays once, as the game's
+     * effect does.
+     */
+    loop?: boolean;
+    /** Who sees it. Default everyone. */
+    to?: readonly Player[];
+}
+export interface DustOptions {
+    /** Default white. */
+    color?: MapColor;
+    /** Instead: a colour of the game's car palette (0-127), as `vehicle.colors` has. */
+    carColor?: number;
+    /** Each puff's size (m). Default 1. */
+    size?: number;
+    /** Puffs. Default 20, at most 200. */
+    count?: number;
+    /** How far out from the spot they start (m). Default 1. */
+    spread?: number;
+    /** How fast they drift up (m/s). Default 0.3. */
+    rise?: number;
+    /** How long they last, as a scale of the game's smoke. Default 1. */
+    life?: number;
+    /** From what it's on (m), or from the spot. */
+    offset?: Vector3;
+    /** Who sees it. Default everyone. */
+    to?: readonly Player[];
+}
+type EffectSpec = Parameters<NativeServer["effect"]>[1] & {
+    id: number;
+};
+/** An effect (`server.effects.play()`). */
+export declare class Effect {
+    #private;
+    readonly id: number;
+    readonly name: string;
+    /** @internal */
+    constructor(id: number, name: string, b: Broadcast<EffectSpec>, forget: (e: Effect) => void);
+    /** False once stopped. A one-off effect stays "playing" until stopped, as far as the server knows. */
+    get playing(): boolean;
+    /** Stops it (its last particles fade out). */
+    stop(): void;
+    /** @internal */
+    replay(player: Player): void;
+    /** @internal */
+    get loops(): boolean;
+}
+/**
+ * `server.effects`: the game's particle effects, by name (`"explosion_crate"`,
+ * `"fire"`, `"riot_smoke"`...: the game's effects.fxp), and puffs of
+ * coloured dust.
+ */
+export declare class ServerEffects {
+    #private;
+    /** @internal */
+    constructor(native: NativeServer, players: () => Player[]);
+    /**
+     * Plays one of the game's effects, at a spot or on something it follows.
+     *
+     * ```ts
+     * server.effects.play("explosion_crate", crate.position);
+     * const fire = server.effects.play("fire", car, { loop: true, offset: { x: 0, y: 2, z: 0.5 } });
+     * fire.stop();
+     * ```
+     */
+    play(name: string, at: EffectTarget, options?: EffectOptions): Effect;
+    /**
+     * Puffs of coloured dust (the game's smoke, tinted): a Pay 'n' Spray's
+     * cloud, a car skidding on sand.
+     *
+     * ```ts
+     * server.effects.dust(car, { color: "#c03030", count: 40, spread: 2.5, size: 1.5 });
+     * ```
+     */
+    dust(at: EffectTarget, options?: DustOptions): void;
+    /** @internal A player joined: the loops playing for everyone. */
+    replay(player: Player): void;
+}
+export {};