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

package/dist/server.js

@@ -0,0 +1,1080 @@
+import { native } from "./native.js";
+import { Player } from "./player.js";
+import { Vehicle } from "./vehicle.js";
+import { Ped, setPedSpeaker } from "./ped.js";
+import { Garage, Zone } from "./zone.js";
+import { Actions } from "./actions.js";
+import { CullZone, World } from "./world.js";
+import { Console } from "./console.js";
+import { GameMap, mapColor } from "./map.js";
+import { GangZone } from "./gangzones.js";
+import { ServerDraw } from "./draw.js";
+import { Missions } from "./mission.js";
+import { PayNSpray } from "./paynspray.js";
+import { ScreenEffects } from "./screeneffects.js";
+import { VehicleColors } from "./vehiclecolors.js";
+import { ModShops } from "./modshop.js";
+import { CutscenePlay } from "./cutscene.js";
+import { Interactions } from "./interaction.js";
+import { ServerAudio } from "./audio.js";
+import { ServerEffects } from "./effects.js";
+import { Claims } from "./claims.js";
+import { Commands, setLookup as setCommandLookup } from "./commands.js";
+import { ServerAnimations } from "./animations.js";
+import { ServerModels } from "./models.js";
+import { WorldThings } from "./objects.js";
+import { Channel, ClientScripts, checkChannel, decode } from "./scripts.js";
+/**
+ * A SAGL server.
+ *
+ * ```ts
+ * const server = new Server({ port: 7777, name: "My server" });
+ * server.on("playerJoin", (p) => server.broadcast(`${p.name} joined`));
+ * server.listen();
+ * ```
+ */
+export class Server {
+    options;
+    /** Operator console on stdin; add commands with `server.console.command()`. */
+    console;
+    /** JavaScript run (sandboxed) in every player's game: see `ClientScripts`. */
+    clientScripts;
+    /** The pause menu's map, everyone's: see `GameMap`. */
+    map;
+    /** Drawing on everyone's screen (players joining later too), SA-MP textdraw style: see `ScreenDraw`. */
+    draw;
+    /** Missions: starting them, start markers, who's in which. See `Missions`. */
+    missions;
+    /** Car colours: the game's, and your own (ids 128 up). See `VehicleColors`. */
+    vehicleColors;
+    /** Full-screen effects (your shaders) on everyone's screen, players joining later too. See `ScreenEffects`. */
+    screenEffects;
+    /** The game's Pay 'n' Sprays, on by default. See `PayNSpray`. */
+    payNSpray;
+    /** The game's mod shops (TransFender, Loco Low Co, Wheel Arch Angels), on by default. See `ModShops`. */
+    modShops;
+    /** What players can walk up to and use: vending machines, payphones... See `Interactions`. */
+    interactions;
+    /** Things players do with a key they choose (Settings, Controls): see `Actions`. */
+    actions;
+    /** Sounds from client files, positioned or not: see `ServerAudio`. */
+    audio;
+    /** The game's particle effects and coloured dust: see `ServerEffects`. */
+    effects;
+    /** First come, first served: one player at a time holds a thing. See `Claims`. */
+    claims = new Claims();
+    /** Chat commands, built as Minecraft's (`command(...)`): see `Commands`. */
+    commands;
+    /** How chat lines go out, and its flood limit: see `ChatOptions`. */
+    chat = {
+        format: (player, text) => `{${(player.color & 0xffffff).toString(16).padStart(6, "0")}}${player.name}{FFFFFF}: ${text}`,
+        floodLines: 5,
+        floodPerSecond: 1,
+    };
+    /** The server's own animation sets (IFP client files): see `ServerAnimations`. */
+    animations;
+    /** The server's own models (DFF/TXD client files), as SA-MP's AddSimpleModel: see `ServerModels`. */
+    models;
+    /** Floating text in the world: `server.labels.add(text, at, options)`. See `Label`. */
+    labels;
+    #things;
+    #native;
+    #cutscenes = new Map();
+    #nextCutscene = 1;
+    #players = new Map();
+    #vehicles = new Map();
+    #peds = new Map();
+    #zones = new Map();
+    #garages = [];
+    #cullZones = new Map();
+    #listeners = {};
+    #timer = null;
+    #warnedAsyncVeto = false;
+    #channels = new Map();
+    #branding = {};
+    constructor(options = {}) {
+        this.options = options;
+        this.#native = new native.NativeServer({
+            port: options.port,
+            name: options.name,
+            maxPlayers: options.maxPlayers,
+            timeHour: options.time?.hour,
+            timeMinute: options.time?.minute,
+            timeFrozen: options.time?.frozen ?? true,
+            trustedProxies: options.trustedProxies,
+            startMoney: options.startMoney,
+            weather: options.weather,
+            skinAnimations: options.skinAnimations,
+            gameEntrances: options.gameEntrances,
+            splash: !!options.splash,
+            carjacking: options.carjacking ?? true,
+            indicatorKeys: options.indicators?.keys ?? true,
+            indicatorCancel: options.indicators?.autoCancel ?? true,
+            indicatorSound: options.indicators?.sound === false ? "-" : (options.indicators?.sound ?? ""),
+            clientFiles: options.clientFiles,
+        });
+        this.#native.setHooks({
+            join: (id) => this.#onJoin(id),
+            quit: (id, reason) => this.#onQuit(id, reason),
+            damage: (victimId, attackerId, hit, attackerPedId) => this.#onDamage(victimId, this.#attacker(attackerId, attackerPedId), hit),
+            death: (id, killerId, weapon, killerPedId) => {
+                const player = this.#players.get(id);
+                if (!player)
+                    return;
+                player.specialEnds(false);
+                this.#emit("playerDeath", player, this.#attacker(killerId, killerPedId) ?? null, weapon);
+            },
+            spawn: (id) => {
+                const player = this.#players.get(id);
+                if (player)
+                    this.#emit("playerSpawn", player);
+            },
+            pause: (id, paused, focused) => {
+                const player = this.#players.get(id);
+                if (player)
+                    this.#emit("playerPause", player, paused, focused);
+            },
+            enterVehicle: (playerId, vehicleId) => {
+                const player = this.#players.get(playerId);
+                const vehicle = this.#vehicleById(vehicleId);
+                if (!player || !vehicle)
+                    return;
+                player.specialEnds(true);
+                this.#emit("playerEnterVehicle", player, vehicle);
+            },
+            radio: (playerId, vehicleId, station) => {
+                const player = this.#players.get(playerId);
+                const vehicle = this.#vehicleById(vehicleId);
+                if (!player || !vehicle)
+                    return undefined;
+                let result;
+                for (const r of this.#emit("vehicleRadio", player, vehicle, station)) {
+                    if (r === false)
+                        return false;
+                    if (typeof r === "number")
+                        result = r;
+                }
+                return result;
+            },
+            shoot: (playerId, shot) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return undefined;
+                for (const r of this.#emit("playerShoot", player, shot)) {
+                    if (r === false)
+                        return false;
+                }
+                return undefined;
+            },
+            scriptMessage: (playerId, channel, text) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return;
+                const data = decode(text);
+                if (channel === "sagl:error") {
+                    const e = (data ?? {});
+                    this.#emit("clientScriptError", player, { where: String(e.where ?? "?"), message: String(e.message ?? data) });
+                    return;
+                }
+                this.#channels.get(channel)?.dispatch(player, data);
+                this.#emit("clientMessage", player, channel, data);
+            },
+            uiEvent: (playerId, event) => {
+                this.#players.get(playerId)?.ui.dispatch(event);
+            },
+            objectHit: (playerId, id, damage, weapon) => {
+                const player = this.#players.get(playerId);
+                if (player)
+                    this.#things.objects.get(id)?.hit(player, damage, weapon);
+            },
+            pickupTouch: (playerId, id) => {
+                const player = this.#players.get(playerId);
+                if (player)
+                    this.#things.pickups.get(id)?.touch(player);
+            },
+            carjack: (jackerId, victimId, vehicleId) => {
+                const jacker = this.#players.get(jackerId), victim = this.#players.get(victimId), vehicle = this.#vehicleById(vehicleId);
+                if (jacker && victim && vehicle)
+                    this.#emit("playerCarjack", jacker, victim, vehicle);
+            },
+            playerAttach: (playerId, spec) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return;
+                const model = spec.remove ? null : (spec.model ?? 0);
+                if (this.#emit("playerAttachObject", player, spec.slot, model).includes(false))
+                    return;
+                player.attachedByScript(spec);
+            },
+            gameMenuEvent: (playerId, id, kind, row) => {
+                this.#players.get(playerId)?.menuHeard(id, kind, row);
+            },
+            documentResult: (playerId, id, button) => {
+                this.#players.get(playerId)?.ui.documentAnswered(id, button);
+            },
+            cameraEvent: (playerId, id, step, kind) => {
+                this.#players.get(playerId)?.camera.heard(id, step, kind);
+            },
+            dialogResponse: (playerId, id, response, listItem, input) => {
+                this.#players.get(playerId)?.dialogAnswered(id, { response, listItem, input });
+            },
+            chat: (playerId, text) => {
+                const player = this.#players.get(playerId);
+                if (player)
+                    void this.#onChat(player, text);
+            },
+            suggestRequest: (playerId, id, text) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return;
+                void this.commands.suggest(player, text).then((r) => {
+                    if (r && player.connected)
+                        this.#native.suggestions(player.id, id, r[0], r[1]);
+                }).catch((err) => console.error("[sagl] command suggestions failed:", err));
+            },
+            playerKeys: (playerId, keys, old) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return;
+                player.specialKeys(keys, old);
+                this.#emit("playerKeys", player, keys, old);
+            },
+            playerInterior: (playerId, interior, old) => {
+                const player = this.#players.get(playerId);
+                if (player)
+                    this.#emit("playerInterior", player, interior, old);
+            },
+            playerAction: (playerId, id) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return;
+                this.actions.pressed(player, id);
+                this.#emit("playerAction", player, id);
+            },
+            interactionUse: (playerId, id, where) => {
+                const player = this.#players.get(playerId);
+                if (player)
+                    this.interactions.use(player, id, where);
+            },
+            cutsceneState: (playerId, id, state, skipped) => {
+                const player = this.#players.get(playerId);
+                if (player)
+                    this.#cutscenes.get(id)?.state(player, state, skipped);
+            },
+            wantedLevel: (playerId, level, old) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return undefined;
+                let out;
+                for (const r of this.#emit("playerWantedLevel", player, level, old)) {
+                    if (r === false)
+                        return false;
+                    if (typeof r === "number")
+                        out = r;
+                }
+                return out;
+            },
+            weaponViolation: (playerId, reason, weapon) => {
+                const player = this.#players.get(playerId);
+                if (player)
+                    this.#emit("playerWeaponViolation", player, reason, weapon);
+            },
+            pedDamage: (pedId, attackerId, hit, attackerPedId) => {
+                const ped = this.#pedById(pedId);
+                const attacker = this.#attacker(attackerId, attackerPedId);
+                if (!ped || !attacker)
+                    return undefined;
+                let damage;
+                const own = ped.damagedBy(attacker, { ...hit });
+                if (own === false)
+                    return false;
+                if (typeof own === "number")
+                    damage = own;
+                for (const result of this.#emit("pedDamage", ped, attacker, { ...hit })) {
+                    if (result === false)
+                        return false;
+                    if (typeof result === "number")
+                        damage = result;
+                }
+                return damage;
+            },
+            pedOrder: (pedId, orderId, step, state, reason) => {
+                const ped = this.#pedById(pedId);
+                if (!ped)
+                    return;
+                ped.handleOrder(orderId, step, state, reason);
+                this.#emit("pedOrder", ped, { orderId, step, state, reason: reason || undefined });
+            },
+            pedDeath: (pedId, killerId, weapon, killerPedId) => {
+                const ped = this.#pedById(pedId);
+                if (ped)
+                    this.#emit("pedDeath", ped, this.#attacker(killerId, killerPedId) ?? null, weapon);
+            },
+            populationSpawn: (playerId, spawn) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return undefined;
+                const info = {
+                    vehicle: spawn.vehicle ? spawn.vehicleModel : null,
+                    position: spawn.position,
+                    heading: (spawn.heading * 180) / Math.PI,
+                    peds: spawn.peds,
+                };
+                for (const r of this.#emit("populationSpawn", info, player)) {
+                    if (r === false)
+                        return false;
+                }
+                return undefined;
+            },
+            pedViolation: (playerId, pedId, reason) => {
+                const player = this.#players.get(playerId);
+                const ped = this.#pedById(pedId);
+                if (player && ped)
+                    this.#emit("pedViolation", player, ped, reason);
+            },
+            vehicleRespawn: (vehicleId) => {
+                const vehicle = this.#vehicleById(vehicleId);
+                if (vehicle)
+                    this.#emit("vehicleRespawn", vehicle);
+            },
+            vehicleHit: (vehicleId, h) => {
+                const vehicle = this.#vehicleById(vehicleId);
+                if (!vehicle)
+                    return undefined;
+                const hit = {
+                    cause: h.cause,
+                    with: h.with,
+                    weapon: h.weapon,
+                    vehicle: h.otherVehicleId === null ? null : (this.#vehicleById(h.otherVehicleId) ?? null),
+                    player: h.playerId === null ? null : (this.#players.get(h.playerId) ?? null),
+                    ped: h.pedId === null ? null : (this.#pedById(h.pedId) ?? null),
+                    healthBefore: h.healthBefore,
+                    health: h.health,
+                    loss: h.loss,
+                    intensity: h.intensity,
+                    position: h.position,
+                };
+                let out;
+                const own = vehicle.hitBy(hit);
+                if (own === false)
+                    return false;
+                if (typeof own === "number")
+                    out = own;
+                for (const r of this.#emit("vehicleHit", vehicle, hit)) {
+                    if (r === false)
+                        return false;
+                    if (typeof r === "number")
+                        out = r;
+                }
+                return out;
+            },
+            vehicleDeath: (vehicleId, killerId) => {
+                const vehicle = this.#vehicleById(vehicleId);
+                if (!vehicle)
+                    return undefined;
+                const killer = killerId === null ? null : (this.#players.get(killerId) ?? null);
+                for (const r of this.#emit("vehicleDeath", vehicle, killer)) {
+                    if (r === false)
+                        return false;
+                }
+                return undefined;
+            },
+            explosion: (playerId, e) => {
+                const player = this.#players.get(playerId);
+                if (!player)
+                    return undefined;
+                const explosion = {
+                    type: e.type,
+                    weapon: e.weapon,
+                    vehicle: e.vehicleId ? (this.#vehicleById(e.vehicleId) ?? null) : null,
+                    position: e.position,
+                };
+                for (const v of this.#vehicles.values())
+                    v.explosionNear(player, explosion);
+                for (const r of this.#emit("playerExplosion", player, explosion)) {
+                    if (r === false)
+                        return false;
+                }
+                return undefined;
+            },
+            zoneEnter: (playerId, zoneId) => this.#zoneEvent("zoneEnter", playerId, zoneId),
+            zoneLeave: (playerId, zoneId) => this.#zoneEvent("zoneLeave", playerId, zoneId),
+            zoneMove: (playerId, zoneId) => this.#zoneEvent("zoneMove", playerId, zoneId),
+            exitVehicle: (playerId, vehicleId) => {
+                const player = this.#players.get(playerId);
+                const vehicle = this.#vehicleById(vehicleId);
+                if (player && vehicle)
+                    this.#emit("playerExitVehicle", player, vehicle);
+            },
+        });
+        this.console = new Console(this);
+        this.clientScripts = new ClientScripts(this.#native);
+        if (options.branding)
+            this.branding = options.branding;
+        this.map = new GameMap(this.#native, -1);
+        let nextDraw = 1_000_000; // apart from players' own ids
+        this.draw = new ServerDraw(this.#native, () => this.players, () => nextDraw++);
+        this.missions = new Missions(this, (e) => this.#emit("missionEvent", e));
+        this.interactions = new Interactions(this.#native, () => this.players);
+        this.actions = new Actions(this.#native);
+        this.audio = new ServerAudio(this.#native, () => this.players, options.clientFiles);
+        setPedSpeaker((file, options) => this.audio.speak(file, options));
+        this.commands = new Commands((p, tree) => this.#native.commandTree(p.id, tree), () => this.players, (p, text) => p.send(text, 0xff6060));
+        setCommandLookup({ players: () => this.players, vehicle: (id) => this.#vehicleById(id) });
+        this.effects = new ServerEffects(this.#native, () => this.players);
+        this.animations = new ServerAnimations(this.#native, () => this.players, options.clientFiles);
+        this.models = new ServerModels(this.#native, () => this.players);
+        this.#things = new WorldThings(this.#native, () => this.players);
+        this.labels = { add: (text, at, opts) => this.#things.addLabel(text, at, opts) };
+        for (const state of this.#native.garages()) {
+            const garage = new Garage(this.#native, state);
+            garage.zone = new Zone(state.zoneId, garage, (z) => this.destroyZone(z));
+            this.#zones.set(state.zoneId, garage.zone);
+            this.#garages.push(garage);
+        }
+        this.screenEffects = new ScreenEffects(this.#native, null, () => this.players);
+        this.vehicleColors = new VehicleColors(this.#native, () => this.players);
+        this.payNSpray = new PayNSpray(this, (p, v, colors) => this.#emit("vehicleRespray", p, v, colors));
+        this.modShops = new ModShops(this, {
+            mod: (p, v, part, price) => this.#emit("vehicleMod", p, v, part, price),
+            paintjob: (p, v, paintjob, price) => this.#emit("vehiclePaintjob", p, v, paintjob, price),
+            respray: (p, v, colors) => this.#emit("vehicleRespray", p, v, colors),
+            shop: (p, v, shop, entered, site) => this.#emit("modShop", p, v, shop, entered, site),
+            livery: (p, v, livery, price) => this.#emit("vehicleLivery", p, v, livery, price),
+            plate: (p, v, plate, price) => this.#emit("vehiclePlate", p, v, plate, price),
+            finish: (p, v, finish, price) => this.#emit("vehicleFinish", p, v, finish, price),
+        });
+    }
+    #zoneEvent(event, playerId, zoneId) {
+        const player = this.#players.get(playerId);
+        const zone = this.#zones.get(zoneId);
+        if (player && zone) {
+            if (event !== "zoneMove")
+                this.audio.zoneEvent(player, zone, event === "zoneEnter");
+            this.#emit(event, player, zone);
+        }
+    }
+    /** Protocol version clients must speak. */
+    static get protocolVersion() {
+        return native.protocolVersion;
+    }
+    /** SAGL's version this server is (as the client and the SDK: one version for all of SAGL). */
+    static get version() {
+        return native.version;
+    }
+    // ---- Lifecycle --------------------------------------------------------------
+    /**
+     * Starts accepting players. Also starts the operator console unless
+     * `{ console: false }`, and stops cleanly on SIGINT/SIGTERM.
+     */
+    listen({ console: withConsole = true } = {}) {
+        if (this.#timer)
+            return this;
+        if (!this.#native.start()) {
+            throw new Error(`could not start the server on UDP port ${this.options.port ?? 7777}`);
+        }
+        this.#timer = setInterval(() => this.#native.service(0), this.options.tickMs ?? 5);
+        this.#checkpointTimer = setInterval(() => {
+            this.#checkCheckpoints();
+            if (++this.#aimTick % 3 === 0)
+                this.#checkAims();
+        }, 100);
+        if (withConsole)
+            this.console.start();
+        const stop = () => {
+            this.close();
+            process.exit(0);
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        return this;
+    }
+    /** Disconnects everyone and stops the network. */
+    close() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = null;
+        }
+        if (this.#checkpointTimer) {
+            clearInterval(this.#checkpointTimer);
+            this.#checkpointTimer = null;
+        }
+        this.console.stop();
+        this.#native.shutdown();
+    }
+    // ---- Events -----------------------------------------------------------------
+    /** The server's branding, for players joining from now. */
+    get branding() {
+        return { ...this.#branding };
+    }
+    set branding(b) {
+        const error = this.#native.setBranding(b.logo ?? "", mapColor(b.primary, 0), mapColor(b.secondary, 0), b.background ?? "", b.showName ?? false);
+        if (error)
+            throw new Error(`branding: ${error}`);
+        this.#branding = { ...b };
+    }
+    /** What players download from the `clientFiles` directory: path, size, SHA-256 (hex). */
+    get clientFiles() {
+        return this.#native.clientFiles();
+    }
+    /**
+     * Reads the `clientFiles` directory again (after changing it); players
+     * joining from now get it as it is. Returns how many files there are.
+     */
+    rescanClientFiles() {
+        const n = this.#native.rescanClientFiles();
+        this.animations.rescan();
+        return n;
+    }
+    /**
+     * The named channel between the gamemode and its client scripts (made on
+     * first use): `.on((player, data) => ...)` for what scripts send,
+     * `.send(player, data)` / `.broadcast(data)` to them. Data is JSON.
+     */
+    channel(name) {
+        let ch = this.#channels.get(name);
+        if (!ch) {
+            checkChannel(name);
+            ch = new Channel(this.#native, name);
+            this.#channels.set(name, ch);
+        }
+        return ch;
+    }
+    on(event, listener) {
+        (this.#listeners[event] ??= []).push(listener);
+        return this;
+    }
+    off(event, listener) {
+        const list = this.#listeners[event];
+        const index = list?.indexOf(listener) ?? -1;
+        if (list && index >= 0)
+            list.splice(index, 1);
+        return this;
+    }
+    #emit(event, ...args) {
+        const results = [];
+        for (const listener of [...(this.#listeners[event] ?? [])]) {
+            try {
+                const result = listener(...args);
+                if (result instanceof Promise) {
+                    result.catch((err) => console.error(`[sagl] ${event} handler failed:`, err));
+                }
+                results.push(result);
+            }
+            catch (err) {
+                console.error(`[sagl] ${event} handler threw:`, err);
+            }
+        }
+        return results;
+    }
+    #flood = new Map();
+    #checkpointTimer = null;
+    #aimTick = 0;
+    // Peds with onThreatened: is any player aiming at them? (a few times a second)
+    #checkAims() {
+        for (const ped of this.#peds.values()) {
+            if (!ped.watchesThreats || !ped.exists)
+                continue;
+            for (const p of this.#players.values())
+                if (p.connected && !p.vehicle)
+                    ped.checkAim(p);
+        }
+    }
+    // Checkpoints: in one when within its radius on the ground (their position
+    // is their middle, or their vehicle's), checked ten times a second.
+    #checkCheckpoints() {
+        const inside = (p, c) => {
+            const at = p.position;
+            return Math.hypot(at.x - c.position.x, at.y - c.position.y) <= c.size &&
+                at.z >= c.position.z - 2 && at.z <= c.position.z + Math.max(4, c.size);
+        };
+        for (const p of this.#players.values()) {
+            if (p.checkpoint) {
+                const now = p.alive && inside(p, p.checkpoint);
+                if (now !== p.inCheckpoint) {
+                    p.inCheckpoint = now;
+                    this.#emit(now ? "playerEnterCheckpoint" : "playerLeaveCheckpoint", p);
+                }
+            }
+            if (p.raceCheckpoint) {
+                const now = p.alive && inside(p, p.raceCheckpoint);
+                if (now !== p.inRaceCheckpoint) {
+                    p.inRaceCheckpoint = now;
+                    this.#emit(now ? "playerEnterRaceCheckpoint" : "playerLeaveRaceCheckpoint", p);
+                }
+            }
+        }
+    }
+    async #onChat(player, raw) {
+        const text = raw.replace(/[\x00-\x1f]/g, "").trim().slice(0, 256);
+        if (!text)
+            return;
+        // A burst of floodLines, then floodPerSecond.
+        const now = Date.now();
+        const f = this.#flood.get(player) ?? { tokens: this.chat.floodLines, at: now };
+        f.tokens = Math.min(this.chat.floodLines, f.tokens + ((now - f.at) / 1000) * this.chat.floodPerSecond);
+        f.at = now;
+        this.#flood.set(player, f);
+        if (f.tokens < 1) {
+            player.send("You're sending messages too fast.", 0xff6060);
+            return;
+        }
+        f.tokens -= 1;
+        if (text.startsWith("/")) {
+            if (await this.commands.handle(player, text))
+                return;
+            if (this.#emit("playerCommandText", player, text).some((r) => r === true))
+                return;
+            player.send(`Unknown command: ${text.split(/\s+/)[0]}`, 0xff6060);
+            return;
+        }
+        let line = text;
+        for (const r of this.#emit("playerChat", player, text)) {
+            if (r === false)
+                return;
+            if (typeof r === "string")
+                line = r;
+        }
+        this.broadcast(this.chat.format(player, line));
+    }
+    #onJoin(id) {
+        const player = new Player(this.#native, id, (vid) => this.#vehicleById(vid));
+        this.#players.set(id, player);
+        if (this.options.splash) {
+            // Up until the gamemode hides it (or the timeout does).
+            const splash = player.holdSplash();
+            const ms = typeof this.options.splash === "object" ? (this.options.splash.timeoutMs ?? 30000) : 30000;
+            setTimeout(() => {
+                if (!player.connected || splash.everHidden)
+                    return;
+                console.warn(`[sagl] ${player.name}'s splash screen was still up after ${ms} ms: hidden (call player.splash.hide() when they're ready)`);
+                splash.hide();
+            }, ms).unref?.();
+        }
+        this.draw.replay(player);
+        this.interactions.replay(player);
+        this.audio.replay(player);
+        this.effects.replay(player);
+        this.animations.replay(player);
+        this.models.replay(player); // before the objects that use them
+        this.#things.replay(player);
+        this.commands.refresh(player);
+        // What everyone holds, to them; what they hold (nothing yet), to everyone.
+        // Chat bubbles: a label on them, above their head (a little higher than a name).
+        player.setBubbleMaker((text, color, distance) => this.labels.add(text, player, { color, distance, offset: { x: 0, y: 0, z: 1.3 } }));
+        player.setAttachmentSender((spec) => {
+            for (const p of this.players)
+                if (p.connected)
+                    this.#native.playerAttachment(p.id, spec);
+        });
+        for (const p of this.players) {
+            for (const spec of p.attachments.values())
+                this.#native.playerAttachment(player.id, spec);
+        }
+        player.setRespawner((p) => this.#emit("playerSpawn", p));
+        this.screenEffects.joined(player);
+        this.vehicleColors.joined(player);
+        // Name tags: how they show, and everyone's that isn't as normal.
+        player.setTagSender((target, viewer) => {
+            for (const v of viewer ? [viewer] : this.players) {
+                if (v !== target && v.connected && target.connected)
+                    this.#native.nameTag(v.id, target.id, ...target.tagFor(v));
+            }
+        });
+        this.#sendNameTagOptions(player);
+        if (!this.#stuntBonus)
+            player.stuntBonus = false;
+        for (const z of this.#gangZones.values())
+            z.replay(player);
+        for (const p of this.players) {
+            if (p === player)
+                continue;
+            const [hidden, text, color] = p.tagFor(player);
+            if (hidden || text || color !== null)
+                this.#native.nameTag(player.id, p.id, hidden, text, color);
+        }
+        this.#emit("playerJoin", player);
+    }
+    #onQuit(id, reason) {
+        const player = this.#players.get(id);
+        if (!player)
+            return;
+        this.#emit("playerQuit", player, reason);
+        this.#players.delete(id);
+        for (const p of this.#players.values())
+            p.forgetViewer(player);
+        for (const z of this.#gangZones.values())
+            z.forget(player);
+        this.#things.forgetTarget(2, id);
+        this.audio.forget(player);
+        this.claims.forget(player);
+        this.#flood.delete(player);
+        player.hideDialog();
+        player.forgetMenus();
+        for (const ped of this.#peds.values())
+            ped.forgetPlayer(player);
+        for (const play of [...this.#cutscenes.values()])
+            play.left(player);
+        player.markDisconnected();
+    }
+    // A player or (attackerId null) a server ped.
+    #attacker(playerId, pedId) {
+        if (playerId !== null && playerId !== undefined)
+            return this.#players.get(playerId);
+        return pedId === null || pedId === undefined ? undefined : this.#pedById(pedId);
+    }
+    #onDamage(victimId, attacker, hit) {
+        const victim = this.#players.get(victimId);
+        if (!victim || !attacker)
+            return undefined;
+        let damage;
+        for (const result of this.#emit("playerDamage", victim, attacker, { ...hit })) {
+            if (result === false)
+                return false;
+            if (typeof result === "number")
+                damage = result;
+            if (result instanceof Promise && !this.#warnedAsyncVeto) {
+                this.#warnedAsyncVeto = true;
+                console.warn("[sagl] playerDamage handlers must return synchronously; a Promise can't veto a hit");
+            }
+        }
+        return damage;
+    }
+    // ---- Players ----------------------------------------------------------------
+    /**
+     * How name tags show, for everyone: within `distance` m (default 70),
+     * hidden behind buildings and objects (`lineOfSight`, default true), with
+     * their id (`ids`, default true), with health and armour bars under them
+     * (`bars`, default false). Setting it sets what's given. Each player's own:
+     * `player.nameTag`.
+     */
+    get nameTags() {
+        return { ...this.#nameTags };
+    }
+    set nameTags(options) {
+        this.#nameTags = { ...this.#nameTags, ...options };
+        for (const p of this.players)
+            this.#sendNameTagOptions(p);
+    }
+    /**
+     * A gang zone: a coloured rectangle on the radar and maps (SA-MP's
+     * GangZoneCreate), shown to no one until `show()`. See `GangZone`.
+     */
+    createGangZone(area, color) {
+        const id = this.#nextGangZone++;
+        const zone = new GangZone(this.#native, () => this.players, id, area, color, () => this.#gangZones.delete(id));
+        this.#gangZones.set(id, zone);
+        return zone;
+    }
+    /** Every gang zone not destroyed. */
+    get gangZones() {
+        return [...this.#gangZones.values()];
+    }
+    #gangZones = new Map();
+    #nextGangZone = 1;
+    /**
+     * The game's stunt bonuses for everyone (EnableStuntBonusForAll), players
+     * joining later too; `player.stuntBonus` changes one player's.
+     */
+    get stuntBonus() {
+        return this.#stuntBonus;
+    }
+    set stuntBonus(on) {
+        this.#stuntBonus = on;
+        for (const p of this.players)
+            p.stuntBonus = on;
+    }
+    #stuntBonus = true;
+    #nameTags = { distance: 70, lineOfSight: true, ids: true, bars: false };
+    #sendNameTagOptions(player) {
+        const o = this.#nameTags;
+        if (player.connected)
+            this.#native.nameTagOptions(player.id, Math.max(0, o.distance), o.lineOfSight, o.ids, o.bars);
+    }
+    /** Connected players. */
+    get players() {
+        return [...this.#players.values()];
+    }
+    player(id) {
+        return this.#players.get(id);
+    }
+    /**
+     * Shows a message to every player. `color` is 0xRRGGBB. `markdown`: the
+     * text is markdown (bold, italic, code, links). `{key:ID}` shows an
+     * action's key either way.
+     */
+    broadcast(text, color, options = {}) {
+        this.#native.sendMessage(-1, text, color ?? 0, options.markdown ?? false);
+    }
+    /**
+     * An explosion at a spot, as SA-MP's CreateExplosion: the game's own
+     * (`ExplosionType`: grenade, molotov, rocket, car, small, tiny...), its
+     * blast, fire and damage, in the games of `to` (default everyone). It's
+     * no one's: a player it hurts is hurt as by a fall (no attacker), and a
+     * vehicle it wrecks is wrecked by nobody.
+     */
+    createExplosion(position, type = 0, options = {}) {
+        if (!Number.isInteger(type) || type < 0 || type > 12)
+            throw new RangeError(`not an explosion type: ${type} (0-12)`);
+        for (const p of options.to ?? this.players) {
+            if (p.connected)
+                this.#native.explosion(p.id, position.x, position.y, position.z, type);
+        }
+    }
+    /** Empties everyone's chat log. */
+    clearChat() {
+        for (const p of this.players)
+            p.clearChat();
+    }
+    /** A random valid ped model. */
+    randomSkin() {
+        return this.#native.randomSkin();
+    }
+    // ---- Vehicles ---------------------------------------------------------------
+    /**
+     * Creates a vehicle for everyone, standing on the ground at `position`.
+     * `heading` in degrees (0 = north, anticlockwise).
+     */
+    createVehicle(model, position, heading = 0, options = {}) {
+        const id = this.#native.createVehicle(model, position.x, position.y, position.z, (heading * Math.PI) / 180, options.colors?.[0] ?? -1, options.colors?.[1] ?? -1, options.radio ?? -1, options.world ?? 0, options.ambient ?? false, Math.max(0, (options.respawnDelay ?? 0) * 1000), options.plate ?? "");
+        if (!id)
+            throw new RangeError(`could not create vehicle model ${model}`);
+        const vehicle = new Vehicle(this.#native, id, (pid) => this.#players.get(pid), (v) => this.destroyVehicle(v), (pedId) => this.#pedById(pedId), (vid) => this.#vehicleById(vid));
+        this.#vehicles.set(id, vehicle);
+        return vehicle;
+    }
+    /**
+     * Creates a ped standing at `position` (feet) facing `heading` degrees:
+     * a ped model (skin), or one of the story's characters by name ("ryder",
+     * "sweet", "smoke", "cesar"...), which each player's game loads (up to 10
+     * different ones near a player at once).
+     * The nearest player's game runs its AI.
+     */
+    createPed(model, position, heading = 0, options = {}) {
+        if (typeof model === "string" && !/^[A-Za-z0-9_]{1,20}$/.test(model)) {
+            throw new RangeError(`not a character name: "${model}"`);
+        }
+        const id = this.#native.createPed(model, position.x, position.y, position.z, (heading * Math.PI) / 180, options.world ?? 0, options.weapon ?? 0, options.health ?? 100, options.behaviour === "wander" ? 1 : 0, options.visibleTo && options.visibleTo !== "world" ? options.visibleTo.filter((p) => p.connected).map((p) => p.id) : null, options.controller ? options.controller.id : null);
+        if (!id)
+            throw new RangeError(`could not create ped ${typeof model === "string" ? `character "${model}"` : `model ${model}`}`);
+        const ped = new Ped(this.#native, id, (pid) => this.#players.get(pid), (vid) => this.#vehicleById(vid), (p) => this.destroyPed(p));
+        this.#peds.set(id, ped);
+        ped.initVisibility(options.visibleTo ?? "world", options.controller ?? null);
+        if (options.mission) {
+            ped.set({ reactions: "self-defence", keepTask: true, ...(options.mission === true ? {} : options.mission) });
+        }
+        return ped;
+    }
+    /** Removes a ped for everyone (same as `ped.destroy()`). */
+    destroyPed(ped) {
+        if (this.#native.destroyPed(ped.id)) {
+            this.#peds.delete(ped.id);
+            this.#things.forgetTarget(1, ped.id);
+            ped.markDestroyed();
+        }
+    }
+    /** Every ped, the ambient population's included. */
+    get peds() {
+        return this.#native.pedIds().map((id) => this.#pedById(id)).filter((p) => !!p);
+    }
+    /** A ped by id. */
+    ped(id) {
+        return this.#pedById(id);
+    }
+    // Wrappers for peds and vehicles the server made itself (the ambient
+    // population) are made when first needed, and dropped once they're gone.
+    #pedById(id) {
+        let ped = this.#peds.get(id);
+        const exists = this.#native.ped(id) !== null;
+        if (!ped && exists) {
+            ped = new Ped(this.#native, id, (pid) => this.#players.get(pid), (vid) => this.#vehicleById(vid), (p) => this.destroyPed(p));
+            this.#peds.set(id, ped);
+        }
+        else if (ped && !exists) {
+            this.#peds.delete(id);
+            this.#things.forgetTarget(1, id);
+            ped.markDestroyed();
+            return undefined;
+        }
+        return ped;
+    }
+    #vehicleById(id) {
+        let vehicle = this.#vehicles.get(id);
+        const exists = this.#native.vehicle(id) !== null;
+        if (!vehicle && exists) {
+            vehicle = new Vehicle(this.#native, id, (pid) => this.#players.get(pid), (v) => this.destroyVehicle(v), (pedId) => this.#pedById(pedId), (vid) => this.#vehicleById(vid));
+            this.#vehicles.set(id, vehicle);
+        }
+        else if (vehicle && !exists) {
+            this.#vehicles.delete(id);
+            this.#things.forgetTarget(3, id);
+            vehicle.markDestroyed();
+            return undefined;
+        }
+        return vehicle;
+    }
+    /** Removes a vehicle for everyone (same as `vehicle.destroy()`). */
+    destroyVehicle(vehicle) {
+        if (this.#native.destroyVehicle(vehicle.id)) {
+            this.#vehicles.delete(vehicle.id);
+            this.#things.forgetTarget(3, vehicle.id);
+            vehicle.markDestroyed();
+        }
+    }
+    /** Every vehicle, the ambient traffic's included. */
+    get vehicles() {
+        return this.#native.vehicleIds().map((id) => this.#vehicleById(id)).filter((v) => !!v);
+    }
+    vehicle(id) {
+        return this.#vehicleById(id);
+    }
+    /**
+     * World 0's ambient population (and every world's without its own): see
+     * `world.population`. Off by default.
+     */
+    get population() {
+        return this.world(0).population;
+    }
+    set population(settings) {
+        this.world(0).population = settings;
+    }
+    // ---- Zones and garages ------------------------------------------------------
+    /**
+     * Watches an area: a sphere (`{ center, radius }`) or an axis-aligned box
+     * between two corners (`{ min, max }`).
+     */
+    createZone(shape) {
+        const world = shape.world ?? -1;
+        const id = "radius" in shape
+            ? this.#native.createSphereZone(shape.center.x, shape.center.y, shape.center.z, shape.radius, world)
+            : this.#native.createBoxZone(shape.min.x, shape.min.y, shape.min.z, shape.max.x, shape.max.y, shape.max.z, world);
+        const zone = new Zone(id, null, (z) => this.destroyZone(z));
+        this.#zones.set(id, zone);
+        return zone;
+    }
+    destroyZone(zone) {
+        if (this.#native.destroyZone(zone.id)) {
+            this.#zones.delete(zone.id);
+            zone.markDestroyed();
+        }
+    }
+    get zones() {
+        return [...this.#zones.values()];
+    }
+    /** The game's garages, by id. */
+    get garages() {
+        return this.#garages;
+    }
+    garage(id) {
+        return this.#garages[id];
+    }
+    // ---- Virtual worlds ---------------------------------------------------------
+    /**
+     * Lets players in `viewer` world see (not meet) players and vehicles in
+     * `target` world, one way: a safehouse world viewing world 0 sees the
+     * street; world 0 still doesn't see in.
+     */
+    /**
+     * One of the game's objects (any object model: crates, gates, barriers,
+     * switches...) where you put it, for everyone (or `visibleTo`). It stays
+     * put: players' games never push or break it. With `health` it's
+     * breakable: players' shots, blows and cars wear it down until it's
+     * destroyed (`onDestroyed`). `move()` glides it (gates, shutters).
+     */
+    createObject(model, position, rotation, options) {
+        return this.#things.createObject(model, position, rotation, options);
+    }
+    /**
+     * A pickup, spinning and glowing as the game's: a weapon (`weapon`,
+     * `ammo`), `health`, `armour` or `money`, given when a player walks into
+     * it (checked by the server), or any `model` with `onPickup` doing the
+     * rest. Taken once, or back after `respawn` ms.
+     */
+    createPickup(options) {
+        return this.#things.createPickup(options);
+    }
+    /**
+     * Plays one of the game's cutscenes (from `anim/cuts.img`, e.g.
+     * `"ryder2a"`) for these players together: each game loads it (their
+     * screens fade out), it starts for everyone once all have it, and `done`
+     * resolves when everyone's has finished. The first player is the leader:
+     * their skip ends it for everyone (see `CutsceneOptions`).
+     */
+    playCutscene(players, name, options = {}) {
+        if (!/^[A-Za-z0-9_]{1,8}$/.test(name))
+            throw new RangeError(`not a cutscene name: "${name}"`);
+        const group = Array.isArray(players) ? [...players] : [players];
+        const id = this.#nextCutscene++;
+        const play = new CutscenePlay(this.#native, id, group, name.toLowerCase(), options, (p) => this.#cutscenes.delete(p.id));
+        if (!play.over)
+            this.#cutscenes.set(id, play); // (nobody to play it for: over already)
+        return play;
+    }
+    setWorldView(viewer, target, visible = true) {
+        this.#native.setWorldView(viewer, target, visible);
+    }
+    /** Whether `viewer` world sees `target` world. */
+    worldSees(viewer, target) {
+        return this.#native.worldSees(viewer, target);
+    }
+    /** A virtual world's settings: its time and weather (world 0's by default). */
+    world(id) {
+        return new World(this.#native, id);
+    }
+    // ---- Cull zones ---------------------------------------------------------------
+    /**
+     * An area with effects like the game's own cull and audio zones, applied by
+     * the games of players in `world` (default: every world): interior music
+     * (`audio`, an `AudioZone`), `attributes` (`ZoneAttribute` bits, e.g. no
+     * rain) and/or a `mirror` (the plane at `coord` across `axis` 0 x / 1 y /
+     * 2 z, facing `sign`). An axis-aligned box between `min` and `max`.
+     */
+    createCullZone(zone) {
+        const id = this.#native.createCullZone({
+            world: zone.world ?? -1,
+            min: [zone.min.x, zone.min.y, zone.min.z],
+            max: [zone.max.x, zone.max.y, zone.max.z],
+            audio: zone.audio ?? -1,
+            attributes: zone.attributes ?? 0,
+            mirror: zone.mirror,
+        });
+        const cz = new CullZone(id, (z) => this.destroyCullZone(z));
+        this.#cullZones.set(id, cz);
+        return cz;
+    }
+    destroyCullZone(zone) {
+        if (this.#native.destroyCullZone(zone.id)) {
+            this.#cullZones.delete(zone.id);
+            zone.markDestroyed();
+        }
+    }
+    // ---- World ------------------------------------------------------------------
+    /** World 0's weather (`Weather`); other worlds follow it unless set apart. */
+    get weather() {
+        return this.#native.getWeather(0);
+    }
+    set weather(weather) {
+        this.#native.setWeather(weather, 0);
+    }
+    /** World 0's traffic lights (every world's without its own): see `TrafficLights`. */
+    get trafficLights() {
+        return this.world(0).trafficLights;
+    }
+    /** In-game time (world 0's). Setting it keeps the current frozen/running state. */
+    get time() {
+        return this.#native.getTime();
+    }
+    set time(value) {
+        if (value.hour < 0 || value.hour > 23 || value.minute < 0 || value.minute > 59) {
+            throw new RangeError("time must be 00:00-23:59");
+        }
+        this.#native.setTime(value.hour, value.minute);
+    }
+    freezeTime() {
+        this.#native.freezeTime(true);
+    }
+    unfreezeTime() {
+        this.#native.freezeTime(false);
+    }
+}
+//# sourceMappingURL=server.js.map