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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Burnett-Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @sagl/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The server for **SAGL**, a multiplayer mod for GTA: San Andreas, built for
+roleplay servers. Write your gamemode in TypeScript or JavaScript on
+Node.js: players, vehicles, peds, missions, UI, cameras, shaders and more,
+with the server in control.
+
+```sh
+npm install @sagl/server
+```
+
+```ts
+import { Server, Color } from "@sagl/server";
+
+const server = new Server({ name: "My server", port: 7777 });
+
+server.on("playerJoin", (player) => {
+  player.send(`Welcome, **${player.name}**! Press {key:chat} to talk.`, Color.White, { markdown: true });
+});
+
+server.on("playerSpawn", (player) => {
+  player.setPosition({ x: 2495, y: -1670, z: 13.4 }, 90);
+});
+
+server.listen();
+```
+
+Run it with `node index.ts`: Node 22.18 and newer run TypeScript directly
+(older 22s need `--experimental-strip-types`). Players join with the SAGL
+client.
+
+## Documentation
+
+**[docs.sagl.mp](https://docs.sagl.mp)**: getting started, the full API,
+and the example gamemodes.
+
+## Platforms
+
+The server's core is native code, installed for your computer
+automatically:
+
+| Platform | Package |
+|---|---|
+| Linux x64 (glibc 2.28 or newer: Debian 10+, Ubuntu 20.04+, RHEL 8+) | `@sagl/server-linux-x64` |
+| Windows x64 | `@sagl/server-win32-x64` |
+
+Node.js 22 or newer.
+
+## Versions
+
+SAGL's client, server and this SDK share one version. Within the same
+**minor** version (0.4.x) clients and servers work together; a new minor
+version changes the network protocol, so update servers and players'
+clients together. `Server.version` and `Server.protocolVersion` say what
+you're running.
+
+`npm install @sagl/server` gets the latest release; `@sagl/server@next` the
+newest prerelease, built from every change.
+
+## Licence
+
+MIT

package/dist/actions.d.ts

@@ -0,0 +1,46 @@
+import type { NativeServer } from "./native.js";
+import type { Player } from "./player.js";
+/**
+ * Key names for actions' default keys, by their place on a US keyboard
+ * (players see what their own layout prints there). Escape and Alt can't
+ * be bound.
+ */
+export declare const KEY_NAMES: readonly string[];
+export interface ActionOptions {
+    /** What players see in Settings, Controls. */
+    label: string;
+    /** Its key until a player binds their own (`KEY_NAMES`); none if left out. */
+    key?: string;
+}
+/**
+ * The server's actions (`server.actions`): things players do with a key
+ * of their choosing. Each shows in their Settings, Controls, under the
+ * server's name, with its default key; they can bind it to another (or
+ * two), kept for this server. Pressing it reaches `playerAction` (and the
+ * handler given here). Client scripts have the same: `sagl.actions`, which
+ * also hears the server's.
+ *
+ * Keys work while the game has the keyboard (not while typing in the chat
+ * or a menu), and the game still sees them: pick keys the game doesn't use
+ * on foot or driving (or let players choose).
+ *
+ * ```ts
+ * server.actions.register("engine", { label: "Engine on/off", key: "N" }, (player) => {
+ *   const v = player.vehicle;
+ *   if (v && player.seat === 0) v.engine = !v.engine;
+ * });
+ * ```
+ */
+export declare class Actions {
+    #private;
+    /** @internal */
+    constructor(native: NativeServer);
+    /** Defines (or redefines) an action: `id` up to 32 characters. */
+    register(id: string, options: ActionOptions, handler?: (player: Player) => void): void;
+    /** Removes an action (from players' Controls too). */
+    remove(id: string): void;
+    /** The actions defined. */
+    get ids(): string[];
+    /** @internal A player pressed one. */
+    pressed(player: Player, id: string): void;
+}

package/dist/actions.js

@@ -0,0 +1,80 @@
+/**
+ * Key names for actions' default keys, by their place on a US keyboard
+ * (players see what their own layout prints there). Escape and Alt can't
+ * be bound.
+ */
+export const KEY_NAMES = [
+    ..."ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789".split(""),
+    ...Array.from({ length: 24 }, (_, i) => `F${i + 1}`),
+    ...Array.from({ length: 10 }, (_, i) => `Numpad${i}`),
+    "NumpadMultiply", "NumpadPlus", "NumpadMinus", "NumpadDecimal", "NumpadDivide",
+    "Space", "Tab", "Enter", "Backspace", "Insert", "Delete", "Home", "End", "PageUp", "PageDown",
+    "Up", "Down", "Left", "Right", "Shift", "Ctrl", "CapsLock",
+    "Comma", "Period", "Semicolon", "Slash", "Minus", "Equals", "LeftBracket", "RightBracket",
+    "Backslash", "Quote", "Backquote", "IntlBackslash",
+];
+/**
+ * The server's actions (`server.actions`): things players do with a key
+ * of their choosing. Each shows in their Settings, Controls, under the
+ * server's name, with its default key; they can bind it to another (or
+ * two), kept for this server. Pressing it reaches `playerAction` (and the
+ * handler given here). Client scripts have the same: `sagl.actions`, which
+ * also hears the server's.
+ *
+ * Keys work while the game has the keyboard (not while typing in the chat
+ * or a menu), and the game still sees them: pick keys the game doesn't use
+ * on foot or driving (or let players choose).
+ *
+ * ```ts
+ * server.actions.register("engine", { label: "Engine on/off", key: "N" }, (player) => {
+ *   const v = player.vehicle;
+ *   if (v && player.seat === 0) v.engine = !v.engine;
+ * });
+ * ```
+ */
+export class Actions {
+    #native;
+    #handlers = new Map();
+    #defined = new Set();
+    /** @internal */
+    constructor(native) {
+        this.#native = native;
+    }
+    /** Defines (or redefines) an action: `id` up to 32 characters. */
+    register(id, options, handler) {
+        if (!/^[A-Za-z0-9_.:-]{1,32}$/.test(id))
+            throw new RangeError(`action id "${id}": 1-32 of A-Z, 0-9, _ . : -`);
+        const key = options.key ?? "";
+        if (key && !KEY_NAMES.includes(key))
+            throw new RangeError(`not a key name: "${key}" (see KEY_NAMES)`);
+        this.#native.defineAction(id, String(options.label).slice(0, 64), key);
+        this.#defined.add(id);
+        if (handler)
+            this.#handlers.set(id, handler);
+        else
+            this.#handlers.delete(id);
+    }
+    /** Removes an action (from players' Controls too). */
+    remove(id) {
+        this.#native.removeAction(id);
+        this.#defined.delete(id);
+        this.#handlers.delete(id);
+    }
+    /** The actions defined. */
+    get ids() {
+        return [...this.#defined];
+    }
+    /** @internal A player pressed one. */
+    pressed(player, id) {
+        const handler = this.#handlers.get(id);
+        if (!handler)
+            return;
+        try {
+            handler(player);
+        }
+        catch (err) {
+            console.error(`[sagl] action "${id}" failed:`, err);
+        }
+    }
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

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

package/dist/animations.d.ts

@@ -0,0 +1,32 @@
+import type { NativeServer } from "./native.js";
+import type { Player } from "./player.js";
+/** One of the server's own animation sets: an IFP client file. */
+export interface AnimationSetInfo {
+    /** The set's name (inside the file): what `playAnim(set, name)` takes. */
+    name: string;
+    /** The client file. */
+    file: string;
+    /** How many animations it has. */
+    animations: number;
+}
+/**
+ * The server's own animations: every `.ifp` among the client files (San
+ * Andreas' format, or III / Vice City's older one) is an animation set,
+ * named by the name inside it. `player.playAnim(set, name)` and
+ * `ped.playAnim(set, name)` play them like the game's own; players' games
+ * load a set when it's first played, and unload idle ones when they need
+ * room. `server.animations`.
+ */
+export declare class ServerAnimations {
+    #private;
+    /** @internal */
+    constructor(native: NativeServer, players: () => Player[], dir: string | undefined);
+    /** The sets, by name. */
+    get sets(): AnimationSetInfo[];
+    /** Whether there's a set of that name (the server's own, not the game's). */
+    has(name: string): boolean;
+    /** @internal Reads the client files' IFPs again (with `server.rescanClientFiles()`). */
+    rescan(): void;
+    /** @internal A player joined: every set. */
+    replay(player: Player): void;
+}

package/dist/animations.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The server's own animations: every `.ifp` among the client files (San
+ * Andreas' format, or III / Vice City's older one) is an animation set,
+ * named by the name inside it. `player.playAnim(set, name)` and
+ * `ped.playAnim(set, name)` play them like the game's own; players' games
+ * load a set when it's first played, and unload idle ones when they need
+ * room. `server.animations`.
+ */
+export class ServerAnimations {
+    #native;
+    #players;
+    #dir;
+    #sets = new Map();
+    /** @internal */
+    constructor(native, players, dir) {
+        this.#native = native;
+        this.#players = players;
+        this.#dir = dir;
+        this.rescan();
+    }
+    /** The sets, by name. */
+    get sets() {
+        return [...this.#sets.values()];
+    }
+    /** Whether there's a set of that name (the server's own, not the game's). */
+    has(name) {
+        return this.#sets.has(name.toUpperCase());
+    }
+    /** @internal Reads the client files' IFPs again (with `server.rescanClientFiles()`). */
+    rescan() {
+        const old = this.#sets;
+        this.#sets = new Map();
+        if (this.#dir)
+            this.#scan(this.#dir, "");
+        for (const p of this.#players()) {
+            for (const [key, set] of old)
+                if (!this.#sets.has(key))
+                    this.#native.animationSet(p.id, set.name, "");
+            for (const set of this.#sets.values())
+                this.#native.animationSet(p.id, set.name, set.file);
+        }
+    }
+    /** @internal A player joined: every set. */
+    replay(player) {
+        for (const set of this.#sets.values())
+            this.#native.animationSet(player.id, set.name, set.file);
+    }
+    #scan(dir, prefix) {
+        for (const entry of fs.readdirSync(path.join(dir, prefix), { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                this.#scan(dir, rel);
+            }
+            else if (entry.name.toLowerCase().endsWith(".ifp")) {
+                const info = readHeader(path.join(dir, rel));
+                if (!info) {
+                    console.warn(`[sagl] animations: ${rel} isn't an animation file (IFP)`);
+                }
+                else if (info.name.length > 15 || !/^[A-Za-z0-9_]+$/.test(info.name)) {
+                    console.warn(`[sagl] animations: ${rel}'s set name "${info.name}" must be 1-15 letters, digits or _`);
+                }
+                else if (this.#sets.has(info.name.toUpperCase())) {
+                    console.warn(`[sagl] animations: ${rel} and ${this.#sets.get(info.name.toUpperCase()).file} are both set "${info.name}"`);
+                }
+                else {
+                    this.#sets.set(info.name.toUpperCase(), { name: info.name, file: rel, animations: info.animations });
+                }
+            }
+        }
+    }
+}
+// The set name and animation count from an IFP's header.
+function readHeader(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const b = Buffer.alloc(64);
+        fs.readSync(fd, b, 0, 64, 0);
+        const tag = b.toString("latin1", 0, 4);
+        const cstr = (at, max) => {
+            const end = b.indexOf(0, at);
+            return b.toString("latin1", at, end < 0 || end > at + max ? at + max : end);
+        };
+        if (tag === "ANP3" || tag === "ANP2")
+            return { name: cstr(8, 24), animations: b.readUInt32LE(32) };
+        if (tag === "ANPK" && b.toString("latin1", 8, 12) === "INFO")
+            return { name: cstr(20, 24), animations: b.readUInt32LE(16) };
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=animations.js.map

package/dist/animations.js.map

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

package/dist/audio.d.ts

@@ -0,0 +1,180 @@
+import type { NativeServer } from "./native.js";
+import type { Ped } from "./ped.js";
+import { Player, type Vector3 } from "./player.js";
+import { Vehicle } from "./vehicle.js";
+import type { Zone } from "./zone.js";
+import { type AudioEffects } from "./audio_effects.js";
+export interface SoundOptions {
+    /** Heard from this spot, or from this ped, player or vehicle (following it). Left out: everywhere, as is. */
+    at?: Vector3 | Ped | Player | Vehicle;
+    /** How far it carries (m) when it has a place. Default 30. */
+    range?: number;
+    /** Plays until `stop()`. */
+    loop?: boolean;
+    /** 0-1, of each player's sound effects volume. Default 1. */
+    volume?: number;
+    /** Who hears it. Default everyone (players joining later too, while it loops). */
+    to?: readonly Player[];
+    /** Through audio effects: a preset (`"phone"`, `"hall"`...) or stages layered. See `AudioEffects`. */
+    effects?: AudioEffects;
+    /**
+     * Positioned: its highs fade with distance, and it's muffled with a
+     * building between it and the listener. Default `server.audio.realism`.
+     */
+    realism?: boolean;
+    /**
+     * Speech (dialogue, a phone call): the radio goes quiet while it plays
+     * and it's near enough to hear, as for the game's mission dialogue.
+     */
+    speech?: boolean;
+}
+/** A sound playing (`server.audio.play()`). */
+export declare class Sound {
+    #private;
+    readonly id: number;
+    readonly file: string;
+    /** How long the file plays (ms), read from the server's copy; undefined if it can't be read. */
+    readonly duration: number | undefined;
+    /**
+     * Resolves when it's over: when it has played through (by its duration,
+     * from when the server sent it), or is stopped. A looping one, when
+     * stopped.
+     *
+     * ```ts
+     * await server.audio.play("audio/caller.mp3", { to: [player] }).done;
+     * ```
+     */
+    readonly done: Promise<void>;
+    /** @internal */
+    constructor(id: number, file: string, duration: number | undefined, loop: boolean, stop: (s: Sound) => void);
+    /** False once it has played through or been stopped. */
+    get playing(): boolean;
+    stop(): void;
+}
+/**
+ * A line as subtitles: its sentences, short ones together, up to about
+ * `max` characters each (default 70).
+ */
+export declare function splitSubtitles(text: string, max?: number): string[];
+export interface SpeakOptions extends Omit<SoundOptions, "loop"> {
+    /**
+     * What's said, shown as subtitles in step with the recording: a string
+     * (split into sentence-sized subtitles), or the subtitles one by one.
+     * Each shows for its share of the recording, by length.
+     */
+    subtitle?: string | readonly string[];
+    /** Who sees the subtitles. Default: `to`, else everyone within `range` of `at`, else everyone. */
+    subtitleTo?: readonly Player[];
+    /** Before each subtitle: a colour code such as `"~y~"`. */
+    prefix?: string;
+    /** Through the glass of `at` (a vehicle): muffled, as someone shut inside it. */
+    muffled?: boolean;
+}
+/** A line being spoken (`server.audio.speak()`). */
+export interface Speech {
+    readonly sound: Sound;
+    /** Resolves when it's been said (or stopped). */
+    readonly done: Promise<void>;
+    /** Stops it and its subtitles. */
+    stop(): void;
+}
+/**
+ * Sounds from client files (MP3, WAV, FLAC) on players' games:
+ * `server.audio`. Positioned ones are heard from where they are, fading
+ * with distance, as the game's own sounds.
+ */
+export declare class ServerAudio {
+    #private;
+    /**
+     * The default for positioned sounds' `realism` (highs fading with
+     * distance, muffled behind buildings). Default false.
+     */
+    realism: boolean;
+    /** @internal */
+    constructor(native: NativeServer, players: () => Player[], clientFiles?: string);
+    /**
+     * How long a client file plays (ms), from the server's copy (the
+     * `clientFiles` directory); undefined if it isn't there or isn't a sound.
+     */
+    duration(file: string): number | undefined;
+    /**
+     * Plays a recorded line with its subtitles timed to it, as speech (the
+     * radio ducks under it). `at` a ped or vehicle: from them (`muffled`:
+     * from inside the vehicle, through the glass).
+     *
+     * ```ts
+     * await server.audio.speak("audio/benny-my-car.mp3", { at: benny, subtitle: "My car! That's my car!" }).done;
+     * await server.audio.speak("audio/caller.mp3", { to: [player], effects: "phone", subtitle: lines, prefix: "~y~" }).done;
+     * ```
+     */
+    speak(file: string, options?: SpeakOptions): Speech;
+    /**
+     * Plays a client file. `at` places it (a spot, or a ped, player or
+     * vehicle it follows); `to` picks who hears it.
+     *
+     * ```ts
+     * const ring = server.audio.play("audio/payphone-ring.mp3", { at: phone, loop: true, range: 25 });
+     * ring.stop();
+     * ```
+     */
+    play(file: string, options?: SoundOptions): Sound;
+    /**
+     * Plays one of the game's own sounds (see `GameSound`): a frontend one
+     * (the HUD's: pickups, the Pay 'n' Spray jingle), or, with `at`, one of
+     * the mission script's sounds at a spot. `to` picks who hears it
+     * (default everyone).
+     *
+     * ```ts
+     * server.audio.playGame(GameSound.CarRespray, { to: [player] });
+     * ```
+     */
+    playGame(sound: number, options?: {
+        at?: Vector3;
+        to?: readonly Player[];
+    }): void;
+    /**
+     * Plays one of the game's mission audio, by its audio id: the recordings
+     * and effects its missions and machines load (a vending machine's clunk:
+     * 42600). From a player, ped or vehicle (following them), a spot, or
+     * (no `at`) as is. `to` picks who hears it (default everyone). Each
+     * game reads it from its own copy and plays it as the server's sounds,
+     * so `effects` work on it.
+     *
+     * ```ts
+     * server.audio.playMission(42600, { at: player });
+     * ```
+     */
+    playMission(id: number, options?: {
+        at?: Vector3 | Player | Ped | Vehicle;
+        range?: number;
+        to?: readonly Player[];
+        effects?: AudioEffects;
+        realism?: boolean;
+    }): void;
+    /**
+     * The effects every sound of the server's and its scripts' passes through
+     * for this player now: where they are (a hall's reverb, a tunnel's echo).
+     * `null`: none. The game's own world sounds aren't affected.
+     *
+     * ```ts
+     * server.audio.setEnvironment(player, "tunnel");
+     * ```
+     */
+    setEnvironment(player: Player, effects: AudioEffects | null): void;
+    /**
+     * An environment for everyone inside a zone, while they're in it (the
+     * most recently entered, where zones overlap; one set with
+     * `setEnvironment` wins over all).
+     *
+     * ```ts
+     * server.audio.setZoneEnvironment(server.createZone({ ... }), "hall");
+     * ```
+     */
+    setZoneEnvironment(zone: Zone, effects: AudioEffects | null): void;
+    /** @internal */
+    zoneEvent(player: Player, zone: Zone, entered: boolean): void;
+    /** @internal */
+    forget(player: Player): void;
+    /** @internal A player joined: the loops playing for everyone. */
+    replay(player: Player): void;
+}