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

package/dist/ui.js

@@ -0,0 +1,243 @@
+// The order of ServerUi.events' bits; "close" always comes.
+const EVENT_BITS = ["click", "change", "submit", "keydown", "focus", "blur", "mouseover", "mouseout"];
+const ACTION = { open: 0, close: 1, show: 2, hide: 3, set: 4, listen: 5 };
+const CHANGE = { text: 0, html: 1, value: 2, classOn: 3, classOff: 4, attribute: 5, removeAttribute: 6, focus: 7, checked: 8 };
+/** The most text or RML one change carries, in UTF-8 bytes. */
+const MAX_VALUE = 5119;
+/**
+ * A UI document the server opened on one player: an RML client file the
+ * server fills in by element id and hears clicks, changes and submits from.
+ * For anything that has to react without a round trip to the server
+ * (animation, per-frame updates, client-side logic), use a client script's
+ * `sagl.ui` instead.
+ */
+export class UiDocument {
+    id;
+    /** The client file it was opened from. */
+    file;
+    player;
+    #ui;
+    #open = true;
+    #handlers = [];
+    #events = 0;
+    /** @internal */
+    constructor(ui, player, id, file) {
+        this.#ui = ui;
+        this.player = player;
+        this.id = id;
+        this.file = file;
+    }
+    /** False once it's closed (by `close()`, the player, or them leaving). */
+    get open() {
+        return this.#open && this.player.connected;
+    }
+    /** Sets an element's text (shown as text: no markup). */
+    setText(id, text) {
+        return this.#set(CHANGE.text, id, "", String(text));
+    }
+    /** Replaces an element's contents with RML (up to 5 KB). */
+    setHtml(id, rml) {
+        return this.#set(CHANGE.html, id, "", rml);
+    }
+    /** A form control's value (`<input>`, `<select>`, `<textarea>`). */
+    setValue(id, value) {
+        return this.#set(CHANGE.value, id, "", String(value));
+    }
+    /** Checks or unchecks a checkbox or radio button. */
+    setChecked(id, checked = true) {
+        return this.#set(CHANGE.checked, id, "", checked ? "1" : "");
+    }
+    /** Adds (`on`, the default) or removes a class. */
+    setClass(id, name, on = true) {
+        return this.#set(on ? CHANGE.classOn : CHANGE.classOff, id, name, "");
+    }
+    /** Sets an attribute, or removes it with `null`. Not `id`. */
+    setAttribute(id, name, value) {
+        if (name === "id")
+            throw new TypeError("ids can't be changed");
+        return value === null
+            ? this.#set(CHANGE.removeAttribute, id, name, "")
+            : this.#set(CHANGE.attribute, id, name, String(value));
+    }
+    /** Gives an element keyboard and gamepad focus. */
+    focus(id) {
+        return this.#set(CHANGE.focus, id, "", "");
+    }
+    /** Shows it again (and takes input again, if it does). */
+    show() {
+        if (this.open)
+            this.#ui.send({ doc: this.id, action: ACTION.show });
+        return this;
+    }
+    /** Hides it (and gives input back) without closing it. */
+    hide() {
+        if (this.open)
+            this.#ui.send({ doc: this.id, action: ACTION.hide });
+        return this;
+    }
+    /** Closes it for good. Its `close` handlers don't run: you closed it. */
+    close() {
+        if (!this.open)
+            return;
+        this.#open = false;
+        this.#ui.send({ doc: this.id, action: ACTION.close });
+        this.#ui.forget(this.id);
+    }
+    on(type, a, b) {
+        const [id, fn] = typeof a === "function" ? [null, a] : [a, b];
+        if (typeof fn !== "function")
+            throw new TypeError("on(type, [id,] handler)");
+        const bit = EVENT_BITS.indexOf(type);
+        if (bit < 0 && type !== "close")
+            throw new RangeError(`no "${type}" events`);
+        this.#handlers.push({ type, id, fn });
+        if (bit >= 0 && !(this.#events & (1 << bit))) {
+            this.#events |= 1 << bit;
+            if (this.open)
+                this.#ui.send({ doc: this.id, action: ACTION.listen, events: this.#events });
+        }
+        return this;
+    }
+    /** Removes a handler, or every handler of that type. */
+    off(type, handler) {
+        this.#handlers = this.#handlers.filter((h) => h.type !== type || (handler && h.fn !== handler));
+        return this;
+    }
+    /** Calls `fn` when the player closes it. */
+    onClose(fn) {
+        return this.on("close", fn);
+    }
+    /** @internal */
+    dispatch(raw) {
+        if (raw.type === "error") {
+            this.#open = false;
+            this.#ui.forget(this.id);
+            console.error(`[sagl] ui: ${this.file} on ${this.player.name}: ${raw.value}`);
+            return;
+        }
+        const e = {
+            type: raw.type, document: this, player: this.player,
+            id: raw.id, value: raw.value, checked: raw.checked, enter: raw.enter, key: raw.key, fields: raw.fields,
+        };
+        if (e.type === "close") {
+            this.#open = false;
+            this.#ui.forget(this.id);
+        }
+        for (const h of [...this.#handlers]) {
+            if (h.type !== e.type || (h.id !== null && h.id !== e.id))
+                continue;
+            try {
+                h.fn(e);
+            }
+            catch (err) {
+                console.error(`[sagl] ui ${e.type} handler threw:`, err);
+            }
+        }
+    }
+    #set(change, element, name, value) {
+        if (Buffer.byteLength(value) > MAX_VALUE)
+            throw new RangeError("at most 5 KB per change");
+        if (this.open)
+            this.#ui.send({ doc: this.id, action: ACTION.set, change, element, name, value });
+        return this;
+    }
+}
+/** UI documents the server opens on one player (`player.ui`). */
+export class PlayerUi {
+    #native;
+    #player;
+    #docs = new Map();
+    #next = 1;
+    /** @internal */
+    constructor(nativeServer, player) {
+        this.#native = nativeServer;
+        this.#player = player;
+    }
+    /**
+     * Opens an RML client file on their screen. Its relative links (images,
+     * stylesheets) resolve beside it. At most 16 at once per player.
+     */
+    open(file, options = {}) {
+        if (!this.#native.clientFiles().some((f) => f.path === file)) {
+            throw new ReferenceError(`no client file "${file}"`);
+        }
+        if (this.#docs.size >= 16)
+            throw new RangeError("at most 16 open documents per player");
+        const input = options.input ?? true;
+        const flags = (input ? 1 : 0) | ((options.cursor ?? input) ? 2 : 0) | ((options.keyboard ?? input) ? 4 : 0) |
+            ((options.gamepad ?? input) ? 8 : 0) | (options.movement ? 16 : 0) | ((options.escapeCloses ?? true) ? 32 : 0);
+        const doc = new UiDocument(this, this.#player, this.#next++, file);
+        this.#docs.set(doc.id, doc);
+        this.send({ doc: doc.id, action: ACTION.open, file, flags });
+        return doc;
+    }
+    /**
+     * Shows a markdown client file in the document viewer: a title, the
+     * document scrolling, a row of buttons. For help pages, rules, terms of
+     * service. Resolves with the index of the button pressed, or -1 if they
+     * closed it (or left). `{key:ID}` in it shows an action's key. One at a
+     * time on their screen; more wait their turn.
+     *
+     * ```ts
+     * const choice = await player.ui.showDocument("docs/rules.md", {
+     *   title: "Server rules", buttons: ["Decline", "Accept"], requireEnd: true, closable: false,
+     * });
+     * if (choice !== 1) player.kick("You must accept the rules to play.");
+     * ```
+     */
+    showDocument(file, options = {}) {
+        if (!this.#native.clientFiles().some((f) => f.path === file))
+            throw new ReferenceError(`no client file "${file}"`);
+        const buttons = (options.buttons ?? []).map((b) => String(b).replace(/\n/g, " ").slice(0, 64));
+        if (buttons.join("\n").length > 512)
+            throw new RangeError("the buttons' text is over 512 characters");
+        const id = this.#nextDocument++;
+        this.#native.documentView(this.#player.id, {
+            id, title: (options.title ?? "").slice(0, 128), file, buttons: buttons.join("\n"),
+            requireEnd: options.requireEnd ?? false, closable: options.closable ?? true,
+        });
+        return new Promise((resolve) => this.#documents.set(id, resolve));
+    }
+    /** Takes down every document viewer they have showing or waiting (each resolves -1). */
+    closeDocuments() {
+        for (const id of this.#documents.keys())
+            this.#native.documentView(this.#player.id, { id, close: true });
+    }
+    /** @internal Their answer from the viewer. */
+    documentAnswered(id, button) {
+        const done = this.#documents.get(id);
+        this.#documents.delete(id);
+        done?.(button);
+    }
+    /** @internal They left: every document resolves -1. */
+    disconnected() {
+        for (const done of this.#documents.values())
+            done(-1);
+        this.#documents.clear();
+    }
+    #documents = new Map();
+    #nextDocument = 1;
+    /** The documents open now. */
+    get documents() {
+        return [...this.#docs.values()];
+    }
+    /** Closes every document. */
+    closeAll() {
+        for (const doc of this.documents)
+            doc.close();
+    }
+    /** @internal */
+    send(spec) {
+        if (this.#player.connected)
+            this.#native.ui(this.#player.id, spec);
+    }
+    /** @internal */
+    forget(id) {
+        this.#docs.delete(id);
+    }
+    /** @internal */
+    dispatch(e) {
+        this.#docs.get(e.doc)?.dispatch(e);
+    }
+}
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

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

package/dist/vehicle.d.ts

@@ -0,0 +1,306 @@
+import { type Livery, type PaintFinish } from "./paint.js";
+import { type NativeServer } from "./native.js";
+import type { Player } from "./player.js";
+import type { Ped } from "./ped.js";
+import type { Vector3 } from "./player.js";
+import type { Explosion, VehicleHit } from "./server.js";
+/** Door, bonnet and boot states. */
+export declare enum DoorDamage {
+    Ok = 0,
+    Open = 1,
+    Damaged = 2,
+    OpenDamaged = 3,
+    Gone = 4
+}
+/** Tyre states. */
+export declare enum TyreDamage {
+    Ok = 0,
+    Burst = 1,
+    Gone = 2
+}
+/** Body panel states (wings, windscreen, bumpers), as the game's doors'. */
+export declare enum PanelDamage {
+    Ok = 0,
+    Loose = 1,
+    Damaged = 2,
+    LooseDamaged = 3
+}
+/**
+ * A vehicle's visible damage (the game's CDamageManager). Bikes use only the
+ * first two tyres.
+ */
+export interface VehicleDamage {
+    /** 0 fine; rises as the engine takes damage (smoke past about 100). */
+    engine: number;
+    /** Front left, rear left, front right, rear right. */
+    tyres: [TyreDamage, TyreDamage, TyreDamage, TyreDamage];
+    /** Bonnet, boot, front left, front right, rear left, rear right. */
+    doors: [DoorDamage, DoorDamage, DoorDamage, DoorDamage, DoorDamage, DoorDamage];
+    /** Front left, front right, rear left, rear right wings, windscreen, front and rear bumpers (7). */
+    panels: PanelDamage[];
+    /** Front left, front right, rear right, rear left: true when smashed. */
+    lights: [boolean, boolean, boolean, boolean];
+}
+/** A vehicle's indicators. */
+export type Indicators = "off" | "left" | "right" | "hazard";
+export declare class Vehicle {
+    #private;
+    readonly id: number;
+    /** Vehicle model, 400-611. */
+    readonly model: number;
+    /** Free-form per-vehicle storage for gamemode data. */
+    readonly data: Record<string, unknown>;
+    /**
+     * Modified in a mod shop (anything bought there: set by `server.modShops`,
+     * or by you, e.g. for a car loaded with parts). A Pay 'n' Spray only
+     * repairs a modified car: its paint stays.
+     */
+    modded: boolean;
+    /**
+     * Its paint finish: drawn with a shader instead of the game's plain paint
+     * (metallic flake, or your own). Null (the default): the game's. See
+     * `PaintFinish`.
+     *
+     * ```ts
+     * vehicle.paintFinish = { type: "metallic", flakes: 0.8 };
+     * vehicle.paintFinish = { shader: "shaders/candy.hlsl", params: { depth: 0.6 } };
+     * ```
+     */
+    get paintFinish(): PaintFinish | null;
+    set paintFinish(finish: PaintFinish | null);
+    /**
+     * A livery (paint job) over its paint: an image of yours, projected onto
+     * any car (a sticker bomb) or laid on by the paint's own layout (a
+     * texture drawn for that model, as the game's paint jobs are). It shows
+     * under any `paintFinish`. Null (the default): none. See `Livery`.
+     *
+     * ```ts
+     * vehicle.livery = { texture: "liveries/stickerbomb.jpg", scale: 1.5 };
+     * ```
+     */
+    get livery(): Livery | null;
+    set livery(livery: Livery | null);
+    /** @internal Created by Server. */
+    constructor(nativeServer: NativeServer, id: number, player: (id: number) => Player | undefined, destroy: (vehicle: Vehicle) => void, ped?: (id: number) => Ped | undefined, vehicle?: (id: number) => Vehicle | undefined);
+    /** False once destroyed. */
+    get exists(): boolean;
+    /** @internal */
+    markDestroyed(): void;
+    /** Last synced position: the driver's, or where it was left. */
+    get position(): Vector3;
+    /** The trailer it tows (a driver backing into one, or `attachTrailer`), or null. */
+    get trailer(): Vehicle | null;
+    /**
+     * Hitches `trailer` to it (SA-MP's AttachTrailerToVehicle), wherever it
+     * is. **Returns** false if it can't (another world, someone driving the
+     * trailer, a wreck).
+     */
+    attachTrailer(trailer: Vehicle): boolean;
+    /** Unhitches what it tows (DetachTrailerFromVehicle). */
+    detachTrailer(): void;
+    /**
+     * What happens to it when hit, for this vehicle alone (as
+     * `server.on("vehicleHit")` for all): return `false` to refuse the harm,
+     * or a number for the health it costs instead. Called before the server's
+     * listeners. **Returns** a function that removes it.
+     *
+     * ```ts
+     * const off = car.onHit((hit) => (hit.cause === "weapon" ? undefined : false));  // only weapons hurt it
+     * ```
+     */
+    onHit(fn: (hit: VehicleHit) => boolean | number | void): () => void;
+    /** @internal A hit, to its own listeners: false refused, a number its cost, else nothing said. */
+    hitBy(hit: VehicleHit): boolean | number | undefined;
+    /**
+     * A player's grenade, molotov, rocket or satchel going off within
+     * `radius` m of it (or the vehicle they wrecked blowing up nearby): for
+     * telling when something was thrown at it, before it takes any harm.
+     * **Returns** a function that removes it.
+     */
+    onExplosionNear(radius: number, fn: (player: Player, explosion: Explosion) => void): () => void;
+    /** @internal An explosion somewhere: to those near enough to hear of it. */
+    explosionNear(player: Player, e: Explosion): void;
+    /** Speed in m/s, as last synced (0 once nobody has for a second). */
+    get speed(): number;
+    /** Whether it's one of the law's: police cars and bikes, rangers, SWAT, FBI, army. */
+    get isPolice(): boolean;
+    /**
+     * A point relative to it, by its heading: `right`, `ahead` and `up` m
+     * from its middle (negative for left, behind, below). For camera shots
+     * and placing things by it.
+     *
+     * ```ts
+     * player.camera.set({ position: car.offset({ right: 3, ahead: 1, up: 1 }), lookAt: { vehicle: car } });
+     * ```
+     */
+    offset(by: {
+        right?: number;
+        ahead?: number;
+        up?: number;
+    }): Vector3;
+    /** Velocity in m/s, as last synced (still once nobody has for a second). */
+    get velocity(): Vector3;
+    /**
+     * 1000 is undamaged; it catches fire below 250 and then blows up. Only the
+     * server raises it (a player's game saying it's better is ignored);
+     * setting it sets it for everyone (1-100000). Not for a wreck.
+     */
+    get health(): number;
+    set health(health: number);
+    /**
+     * Its visible damage: what's open, dented, burst or gone. Like health,
+     * only the server repairs; setting it (better or worse) sets it for
+     * everyone. Not for a wreck.
+     */
+    get damage(): VehicleDamage;
+    set damage(damage: VehicleDamage);
+    /**
+     * Its licence plate, the same for everyone. Setting it changes it at
+     * once: up to 8 of A-Z, 0-9 and spaces (lower case is raised).
+     */
+    get plate(): string;
+    set plate(plate: string);
+    /** Puts it back where it was created, new, for everyone (a wreck too). */
+    respawn(): void;
+    /**
+     * Seconds after it's wrecked, or left empty away from where it was
+     * created, that it respawns by itself (when nobody is near enough to
+     * see); 0: never.
+     */
+    get respawnDelay(): number;
+    set respawnDelay(seconds: number);
+    /**
+     * Colours: the game's palette (carcols.dat), 0-127, or your own
+     * (`server.vehicleColors.add`, 128 up). Only the server recolours
+     * vehicles: setting this recolours it for everyone.
+     */
+    get colors(): [number, number];
+    set colors([color1, color2]: [number, number]);
+    /**
+     * Its radio station (`RadioStation`), or -1 before anyone has been in it.
+     * Everyone in it hears the same thing; setting it retunes it for them.
+     */
+    get radio(): number;
+    set radio(station: number);
+    /** Its virtual world. Setting it moves everyone in it along. */
+    get world(): number;
+    /**
+     * Puts it there, at a standstill (as SA-MP's SetVehiclePos and
+     * SetVehicleZAngle): `position` on the ground, as `createVehicle` takes
+     * it; `heading` in degrees (default as it was). Anyone in it goes too.
+     */
+    setPosition(position: Vector3, heading?: number): void;
+    /**
+     * Fits a tuning part (component 1000-1193: spoilers, hoods, wheels,
+     * nitro, hydraulics...), replacing what's in its slot, for everyone, as
+     * SA-MP's AddVehicleComponent. Returns false if it doesn't fit this model
+     * (by the game's own carmods.dat).
+     */
+    addComponent(part: number): boolean;
+    /** Takes a tuning part off. */
+    removeComponent(part: number): void;
+    /** The tuning parts on it. */
+    get components(): number[];
+    /**
+     * The part in a slot (`ComponentSlot`: spoiler, hood, roof, side skirt,
+     * lamps, nitro, exhaust, wheels, stereo, hydraulics, bumpers, vents), or
+     * 0, as SA-MP's GetVehicleComponentInSlot.
+     */
+    componentInSlot(slot: number): number;
+    /** Its paintjob (0-2, for the models that have them), or -1: none. As SA-MP's ChangeVehiclePaintjob (3 there: none). */
+    get paintjob(): number;
+    set paintjob(paintjob: number);
+    /**
+     * Its doors locked, for everyone (as SA-MP's SetVehicleParamsEx doors):
+     * no one can get in; those in it stay. `lockFor` sets it for one player.
+     */
+    get locked(): boolean;
+    set locked(locked: boolean);
+    /**
+     * Its doors for one player, whatever `locked` is for everyone (as
+     * SA-MP's SetVehicleParamsForPlayer): true locked, false open, null as
+     * for everyone again. A car lock system: `car.locked = true;
+     * car.lockFor(owner, false)`.
+     */
+    lockFor(player: Player, locked: boolean | null): void;
+    /**
+     * Its engine: true running, false off (it won't drive: SA-MP's manual
+     * engines), null as the game has it (on when someone drives). Default null.
+     */
+    get engine(): boolean | null;
+    set engine(on: boolean | null);
+    /** Its lights: true on, false off, null as the game has them (on at night). Default null. */
+    get lights(): boolean | null;
+    set lights(on: boolean | null);
+    /**
+     * A helicopter's searchlight: true on, false off, null as its pilot has it
+     * (a Police Maverick's pilot switches it with the horn). Default null.
+     * Any helicopter can have one. `searchlightOn` is whether it's on now.
+     */
+    get searchlight(): boolean | null;
+    set searchlight(on: boolean | null);
+    /**
+     * A plane's smoke trail: true on, false off, null as its pilot has it (a
+     * Stuntplane's or Cropduster's pilot switches it). Default null. It only
+     * shows while someone flies it with the engine running. `smokeOn` is
+     * whether it's on now.
+     */
+    get smoke(): boolean | null;
+    set smoke(on: boolean | null);
+    /**
+     * Its indicators: `"left"`, `"right"`, `"hazard"` or `"off"`, held so
+     * (its driver's keys then do nothing), or null as its driver has them
+     * (the default). They stay as left when the driver gets out. Cars, bikes
+     * and trucks; everyone sees them flash together. `indicatorsOn` is what
+     * they show now.
+     */
+    get indicators(): Indicators | null;
+    set indicators(to: Indicators | null);
+    /** Its indicators now (held, or as its driver last had them). */
+    get indicatorsOn(): Indicators;
+    /** Whether its searchlight is on now, as its driver's game has it. */
+    get searchlightOn(): boolean;
+    /**
+     * How dirty it is, 0 (clean) to 15 (the dirtiest the game shows), the
+     * same on every screen; null (the default): as each player's game has it
+     * (the game picks one as it makes the car). Pay 'n' Sprays and mod shop
+     * paint clean it (0).
+     */
+    get dirt(): number | null;
+    set dirt(level: number | null);
+    /** Whether its smoke trail is on now, as its driver's game has it. */
+    get smokeOn(): boolean;
+    /** Which way it faces (degrees, 0 north, anticlockwise). */
+    get heading(): number;
+    /** The interior it's in (seen only from there), as SA-MP's LinkVehicleToInterior. */
+    get interior(): number;
+    set interior(interior: number);
+    set world(world: number);
+    /** The player driving it, or null. */
+    get driver(): Player | null;
+    /** Full health and no visible damage, for everyone. Not for a wreck. */
+    repair(): void;
+    /** Part of the ambient traffic (the server removes it when nobody is near). */
+    get ambient(): boolean;
+    /** Blown up. A wreck stays one until respawned or destroyed. */
+    get wrecked(): boolean;
+    /** Blows it up for everyone, credited to `killer` if given. */
+    explode(killer?: Player): void;
+    /** Everyone in it, driver included: seat number -> player. */
+    /** Server peds in it: seat number -> ped. */
+    get peds(): Map<number, Ped>;
+    get occupants(): Map<number, Player>;
+    /**
+     * Hands it back to the game: the server removes it as it does ambient
+     * traffic, once nobody is near (a wreck after a while), unless it's
+     * someone's last car.
+     */
+    release(): void;
+    /** Removes it for everyone; its occupants are put out first. */
+    destroy(): void;
+    toString(): string;
+}
+/** A tuning part's slot (`ComponentSlot`), or -1. */
+export declare function componentSlot(part: number): number;
+/** Whether a tuning part fits a vehicle model (the game's own carmods.dat). */
+export declare function componentFits(model: number, part: number): boolean;