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

package/dist/player.js

@@ -0,0 +1,1163 @@
+import { encodeEffects } from "./audio_effects.js";
+import { GameMap, mapColor } from "./map.js";
+import { PlayerHud } from "./hud.js";
+import { PlayerSplash } from "./splash.js";
+import { PlayerCamera } from "./camera.js";
+import { PlayerMenus } from "./menu.js";
+import { ScreenEffects } from "./screeneffects.js";
+import { ScreenDraw } from "./draw.js";
+import { PlayerUi } from "./ui.js";
+import { speechOf } from "./ped.js";
+import { Key } from "./constants.js";
+import { specialPresets, kSpecialSlot } from "./special.js";
+import { native } from "./native.js";
+export class Player {
+    /** Slot number, unique among connected players (reused after they leave). */
+    id;
+    /** Their name: as given when joining, or `setName`'s. */
+    get name() {
+        return this.#state()?.name ?? this.#name;
+    }
+    #name;
+    /**
+     * Gives them another name (SA-MP's SetPlayerName): 3-24 letters, digits
+     * and `_[]().$@=`, and not another player's (any case). Everyone's game
+     * shows it. **Returns** false if it can't be theirs.
+     */
+    setName(name) {
+        if (!this.#connected || !this.#native.renamePlayer(this.id, name))
+            return false;
+        this.#name = name;
+        return true;
+    }
+    /**
+     * Watches another player or a vehicle (SA-MP's TogglePlayerSpectating
+     * with PlayerSpectatePlayer / PlayerSpectateVehicle): no one sees them
+     * meanwhile, and their camera follows the target (a player's vehicle
+     * while they're in one). Another target switches to it; null ends it, and
+     * they're back where they were.
+     *
+     * ```ts
+     * admin.spectate(suspect);
+     * admin.spectate(null);
+     * ```
+     */
+    spectate(target) {
+        if (!this.#connected || target === this)
+            return;
+        this.#spectating = target;
+        const kind = target === null ? 0 : target instanceof Player ? 1 : 2;
+        this.#native.spectate(this.id, kind, target?.id ?? 0);
+    }
+    /**
+     * Whether `viewer` sees them at all (their character, name, blip):
+     * hidden, they aren't in the viewer's game. For scenes each player plays
+     * alone in the same spot (each sees only themselves answer a phone).
+     * Default visible.
+     */
+    setVisibleFor(viewer, visible) {
+        if (this.#connected && viewer !== this && viewer.connected)
+            this.#native.setVisibleFor(this.id, viewer.id, visible);
+    }
+    /** Who or what they watch (`spectate`), or null. */
+    get spectating() {
+        return this.#spectating;
+    }
+    #spectating = null;
+    /**
+     * Their own weather (`Weather`, 0-22; -1 the game's own cycle), over
+     * their world's (SA-MP's SetPlayerWeather); null: their world's again.
+     */
+    get weather() {
+        return this.#weather;
+    }
+    set weather(weather) {
+        if (weather !== null && (!Number.isInteger(weather) || weather < -1 || weather > 22)) {
+            throw new RangeError(`not a weather: ${weather} (0-22, -1)`);
+        }
+        this.#weather = weather;
+        if (this.#connected)
+            this.#native.setPlayerWeather(this.id, weather);
+    }
+    #weather = null;
+    /**
+     * A box on the map they can't leave (SA-MP's SetPlayerWorldBounds, e.g. a
+     * prison yard): their game pushes them back in, on foot or driving.
+     * Null: free again.
+     *
+     * ```ts
+     * player.worldBounds = { minX: 101.6, maxX: 337.6, minY: 1798.7, maxY: 1941 };
+     * ```
+     */
+    get worldBounds() {
+        return this.#bounds ? { ...this.#bounds } : null;
+    }
+    set worldBounds(b) {
+        if (b && (!(b.minX < b.maxX) || !(b.minY < b.maxY)))
+            throw new RangeError("worldBounds: min must be below max");
+        this.#bounds = b ? { ...b } : null;
+        if (this.#connected)
+            this.#native.worldBounds(this.id, !!b, b?.minX ?? 0, b?.maxX ?? 0, b?.minY ?? 0, b?.maxY ?? 0);
+    }
+    #bounds = null;
+    /**
+     * Plays them the police scanner reporting a crime (SA-MP's
+     * PlayCrimeReportForPlayer): `crime` is the game's (`Crime`), `suspect`
+     * a player or a spot (the scanner names its area).
+     *
+     * ```ts
+     * for (const cop of cops) cop.playCrimeReport(robber, Crime.FireWeapon);
+     * ```
+     */
+    playCrimeReport(suspect, crime) {
+        if (!Number.isInteger(crime) || crime < 1 || crime > 22)
+            throw new RangeError(`not a crime: ${crime} (1-22)`);
+        const at = suspect instanceof Player ? suspect.position : suspect;
+        if (this.#connected)
+            this.#native.crimeReport(this.id, crime, at.x, at.y, at.z);
+    }
+    /**
+     * The game's stunt bonuses for them: wheelies, stoppies, two wheels and
+     * insane stunt jumps (as SA-MP's EnableStuntBonusForPlayer). Off, their
+     * game gives neither the message nor the money. Default on, or as
+     * `server.stuntBonus`.
+     */
+    get stuntBonus() {
+        return this.#stuntBonus;
+    }
+    set stuntBonus(on) {
+        this.#stuntBonus = on;
+        if (this.#connected)
+            this.#native.setStuntBonus(this.id, on);
+    }
+    #stuntBonus = true;
+    /** A number by their name in the player list (SetPlayerScore); shown once anyone's isn't 0. */
+    get score() {
+        return this.#score;
+    }
+    set score(score) {
+        this.#score = Math.trunc(score) | 0;
+        if (this.#connected)
+            this.#native.setScore(this.id, this.#score);
+    }
+    #score = 0;
+    /** Free-form per-player storage for gamemode data. */
+    data = {};
+    #native;
+    #vehicle;
+    #connected = true;
+    /** @internal Created by Server; gamemodes receive Player objects from events. */
+    constructor(nativeServer, id, vehicle) {
+        this.#native = nativeServer;
+        this.#vehicle = vehicle;
+        this.id = id;
+        this.#name = this.#state()?.name ?? `player${id}`;
+    }
+    /** False once the player has left. */
+    get connected() {
+        return this.#connected;
+    }
+    /** @internal */
+    markDisconnected() {
+        this.#connected = false;
+        this.#camera?.disconnected();
+        this.#ui?.disconnected();
+    }
+    #state() {
+        return this.#connected ? this.#native.player(this.id) : null;
+    }
+    /**
+     * The player's IP address. Through a trusted proxy (proxy mode), the one
+     * the proxy forwarded rather than the proxy's own.
+     */
+    get ip() {
+        return this.#state()?.ip ?? "";
+    }
+    /** True when the player came through a trusted proxy. */
+    get viaProxy() {
+        return this.#state()?.viaProxy ?? false;
+    }
+    /**
+     * The address the player connected to, as they typed it (e.g.
+     * "race.example.com" and 7777), for telling apart servers that share an IP.
+     */
+    get connectHost() {
+        return this.#state()?.connectHost ?? "";
+    }
+    get connectPort() {
+        return this.#state()?.connectPort ?? 0;
+    }
+    /** Round-trip time in milliseconds. */
+    get ping() {
+        return this.#state()?.ping ?? 0;
+    }
+    /** True while the player is alive in the world (as their client reports). */
+    /**
+     * Whether they're within `radius` m of `position` (and, `maxDz`, no more
+     * than that above or below it): the check before trusting a client
+     * script that says its player is at something.
+     */
+    isNear(position, radius, maxDz = 3) {
+        const p = this.position;
+        return Math.hypot(p.x - position.x, p.y - position.y) <= radius && Math.abs(p.z - position.z) <= maxDz;
+    }
+    get alive() {
+        return this.#state()?.alive ?? false;
+    }
+    /** True while the player has the pause menu open. The game keeps running. */
+    get paused() {
+        return this.#state()?.paused ?? false;
+    }
+    /** False while the player's game window is in the background (alt-tabbed). */
+    get focused() {
+        return this.#state()?.focused ?? true;
+    }
+    /** The vehicle they are in (driving or as a passenger), or null. */
+    get vehicle() {
+        const id = this.#state()?.vehicleId;
+        return id === null || id === undefined ? null : this.#vehicle(id) ?? null;
+    }
+    /**
+     * The vehicle they last drove, while it exists. Ambient cleanup leaves it
+     * alone while they're connected (unless it's a wreck); destroy it yourself
+     * to get rid of it.
+     */
+    get lastVehicle() {
+        const id = this.#state()?.lastVehicleId;
+        return id === null || id === undefined ? null : this.#vehicle(id) ?? null;
+    }
+    /** The vehicle they remote-control (`remoteControl()`), or null. */
+    get remoteVehicle() {
+        const id = this.#state()?.remoteVehicleId;
+        return id === null || id === undefined ? null : this.#vehicle(id) ?? null;
+    }
+    /**
+     * Remote control, as with an RC vehicle: they drive `vehicle` (nobody in
+     * it, in their world) with their own controls from where they stand, the
+     * camera following it, until they press the enter/exit key, it blows up,
+     * or this is called with null. `detonate`: fire blows it up (and an RC
+     * Bandit blows up touching a car), as in the game's RC missions. Works
+     * with any vehicle, not just RC ones. False if it can't be given (they're
+     * in a vehicle, someone is in it, another world, a wreck).
+     */
+    remoteControl(vehicle, options = {}) {
+        if (!this.#connected)
+            return false;
+        return this.#native.setRemoteControl(this.id, vehicle?.id ?? 0, options.detonate ?? false);
+    }
+    /** Their seat in `vehicle`: 0 is the driver's, 1-8 passengers'. null on foot. */
+    get seat() {
+        return this.#state()?.seat ?? null;
+    }
+    /** Ped model id (0 is CJ). Setting it changes the model for everyone. */
+    get skin() {
+        return this.#state()?.skin ?? 0;
+    }
+    set skin(model) {
+        if (!native.isValidSkin(model)) {
+            throw new RangeError(`not a valid ped model: ${model}`);
+        }
+        if (this.#connected)
+            this.#native.setSkin(this.id, model);
+    }
+    /**
+     * Money, as the server keeps it. The player's game shows exactly this;
+     * anything their game changes by itself is undone.
+     */
+    get money() {
+        return this.#state()?.money ?? 0;
+    }
+    set money(value) {
+        if (!Number.isFinite(value))
+            throw new RangeError(`not a number: ${value}`);
+        if (this.#connected)
+            this.#native.setMoney(this.id, Math.trunc(value));
+    }
+    /** This player's own additions to the pause menu's map (see `GameMap`). */
+    get map() {
+        return (this.#map ??= new GameMap(this.#native, this.id));
+    }
+    #map;
+    /** Full-screen effects (your shaders) on their screen. See `ScreenEffects`. */
+    get screenEffects() {
+        return (this.#screenEffects ??= new ScreenEffects(this.#native, this, () => []));
+    }
+    #screenEffects;
+    /** Their camera: fixed shots, glides between them, following something, or back behind them. See `PlayerCamera`. */
+    get camera() {
+        return (this.#camera ??= new PlayerCamera(this.#native, this.id));
+    }
+    #camera;
+    /**
+     * Their splash screen: the loading screen kept up (or shown again) while
+     * you set the scene, their game's sound muted. See `PlayerSplash`.
+     */
+    get splash() {
+        return (this.#splash ??= new PlayerSplash(this.#native, this.id, false));
+    }
+    #splash;
+    /** @internal Joined with the splash up (the server option `splash`). */
+    holdSplash() {
+        return (this.#splash = new PlayerSplash(this.#native, this.id, true));
+    }
+    /** Their mission HUD: radar blips, objective text, timers and counters, result screens. */
+    get hud() {
+        return (this.#hud ??= new PlayerHud(this.#native, this.id));
+    }
+    #hud;
+    /** Drawing on their screen, SA-MP textdraw style: see `ScreenDraw`. */
+    get draw() {
+        let next = 1;
+        return (this.#draw ??= new ScreenDraw((spec) => { if (this.#connected)
+            this.#native.draw(this.id, spec); }, () => next++));
+    }
+    #draw;
+    /** UI documents (RML client files) the server opens on their screen: see `PlayerUi`. */
+    get ui() {
+        return (this.#ui ??= new PlayerUi(this.#native, this));
+    }
+    #ui;
+    /**
+     * Sends data (anything JSON can hold) on a channel to this player's client
+     * scripts, where `sagl.on(channel, fn)` gets it. See `server.channel()`.
+     */
+    emit(channel, data) {
+        if (!channel || channel.length > 64)
+            throw new RangeError("channel names are 1-64 characters");
+        const json = JSON.stringify(data ?? null);
+        if (json === undefined)
+            throw new TypeError("channel data must be JSON-serialisable");
+        if (this.#connected)
+            this.#native.sendScriptMessage(this.id, channel, json);
+    }
+    /**
+     * Wanted level, 0-6 stars, as the server keeps it; their game shows it
+     * and cops respond. Setting it sets it (capped at `maxWantedLevel`).
+     * Their crimes only change it where the population's `wanted` is on.
+     */
+    get wantedLevel() {
+        return this.#state()?.wantedLevel ?? 0;
+    }
+    set wantedLevel(level) {
+        if (!Number.isInteger(level) || level < 0)
+            throw new RangeError(`not a wanted level: ${level}`);
+        if (this.#connected)
+            this.#native.setWantedLevel(this.id, level);
+    }
+    /**
+     * Clears their wanted level. With `parole` (as the game's Pay 'n' Spray):
+     * their old stars flash for 20 seconds, and a crime meanwhile brings
+     * them back (where the population's `wanted` is on).
+     *
+     * ```ts
+     * player.clearWantedLevel({ parole: true });
+     * ```
+     */
+    clearWantedLevel(options = {}) {
+        if (!this.#connected)
+            return;
+        if (options.parole)
+            this.#native.paroleWantedLevel(this.id);
+        else
+            this.#native.setWantedLevel(this.id, 0);
+    }
+    /** The most their wanted level can be, 0-6 (default 6). */
+    get maxWantedLevel() {
+        return this.#state()?.maxWantedLevel ?? 6;
+    }
+    set maxWantedLevel(level) {
+        if (!Number.isInteger(level) || level < 0)
+            throw new RangeError(`not a wanted level: ${level}`);
+        if (this.#connected)
+            this.#native.setMaxWantedLevel(this.id, level);
+    }
+    /**
+     * Their virtual world (default 0). They see and meet players and vehicles
+     * in it, and see into worlds it views (`server.setWorldView`). Changing it
+     * takes them out of a vehicle that stays behind; move both with
+     * `vehicle.world`.
+     */
+    get world() {
+        return this.#state()?.world ?? 0;
+    }
+    set world(world) {
+        if (this.#connected)
+            this.#native.setPlayerWorld(this.id, world);
+    }
+    /**
+     * The interior they're in: the game's areas, 0 outside, 1-18 its
+     * interiors (as SA-MP's SetPlayerInterior). Their game shows that
+     * interior; they see, and are seen by, players and vehicles in the same.
+     * Teleports keep it: set both to go in or out.
+     *
+     * ```ts
+     * player.interior = 3;
+     * player.setPosition({ x: 384.8, y: 173.8, z: 1008.4 });   // the bike school
+     * ```
+     */
+    get interior() {
+        return this.#state()?.interior ?? 0;
+    }
+    set interior(interior) {
+        if (!Number.isInteger(interior) || interior < 0 || interior > 255)
+            throw new RangeError(`not an interior: ${interior}`);
+        if (this.#connected)
+            this.#native.setPlayerInterior(this.id, interior);
+    }
+    // ---- Stats and how they are played (their game and everyone's copy). ----
+    /** Never tires when sprinting (or swimming, cycling). */
+    get infiniteSprint() {
+        return this.#state()?.infiniteSprint ?? false;
+    }
+    set infiniteSprint(infinite) {
+        if (this.#connected)
+            this.#native.setInfiniteSprint(this.id, infinite);
+    }
+    /**
+     * Walks, runs and idles like their skin (true) or like CJ (false, the
+     * default). Holding a gun they move like CJ either way: the player's
+     * armed moves are made for his animations.
+     */
+    get skinAnimations() {
+        return this.#state()?.skinAnimations ?? false;
+    }
+    set skinAnimations(skin) {
+        if (this.#connected)
+            this.#native.setSkinAnimations(this.id, skin);
+    }
+    /**
+     * Sets a game stat (`Stat`): stamina, muscle, max health, weapon and
+     * driving skills... Only the server changes stats: playing doesn't, and
+     * ones never set stay at a new game's values. 0-1000 for most.
+     */
+    setStat(stat, value) {
+        if (this.#connected && !this.#native.setStat(this.id, stat, value)) {
+            throw new RangeError(`not a stat (or too many set): ${stat}`);
+        }
+    }
+    /** A stat as the server set it, or undefined (a new game's value). */
+    getStat(stat) {
+        return this.#state()?.stats[stat];
+    }
+    /** Back to a new game's value. */
+    resetStat(stat) {
+        if (this.#connected)
+            this.#native.clearStat(this.id, stat);
+    }
+    // ---- Weapons: the server's inventory; their game only has what's given. ----
+    /** The weapon in their hand (`Weapon`), 0 unarmed. */
+    get weapon() {
+        return this.#state()?.weapon ?? 0;
+    }
+    /** Puts a weapon they have in their hand (0: unarmed). */
+    set weapon(weapon) {
+        if (this.#connected)
+            this.#native.setCurrentWeapon(this.id, weapon);
+    }
+    /**
+     * Spawns them again, as SA-MP's SpawnPlayer: out of any vehicle,
+     * animations and special actions stopped, unfrozen, the camera behind
+     * them, health 100 and armour 0, then `playerSpawn` fires so your spawn
+     * code puts them where they belong (a short fade covers the move).
+     * Weapons, money and wanted level stay. A dead player respawns by
+     * themselves (`playerSpawn` follows): nothing happens then.
+     *
+     * ```ts
+     * kickFromFaction(player);
+     * await player.respawn();   // at the civilians' spawn, by your playerSpawn handler
+     * ```
+     */
+    async respawn() {
+        if (!this.#connected || !this.alive)
+            return;
+        await this.fadeOut(300);
+        if (!this.#connected)
+            return;
+        this.removeFromVehicle();
+        this.specialAction = null;
+        this.stopAnim();
+        this.frozen = false;
+        this.camera.reset();
+        this.health = 100;
+        this.armour = 0;
+        this.#respawned?.(this);
+        await new Promise((r) => setTimeout(r, 300)); // the world streams in where they were put
+        if (this.#connected)
+            await this.fadeIn(300);
+    }
+    #respawned = null;
+    /** @internal */
+    setRespawner(fn) {
+        this.#respawned = fn;
+    }
+    /**
+     * Puts the weapon in their hand away (unarmed). **Returns** a function
+     * that gives it back (if they still have it).
+     *
+     * ```ts
+     * const giveBack = player.holster();
+     * await scene();
+     * giveBack();
+     * ```
+     */
+    holster() {
+        const held = this.weapon;
+        if (this.#connected && held)
+            this.weapon = 0;
+        let done = false;
+        return () => {
+            if (done || !this.#connected || !held)
+                return;
+            done = true;
+            if (this.weapons.some((w) => w.weapon === held))
+                this.weapon = held;
+        };
+    }
+    /** What they carry, slot by slot, with ammo (the server's count). */
+    get weapons() {
+        return this.#state()?.weapons ?? [];
+    }
+    /**
+     * Gives a weapon with `ammo` (into its slot, replacing whatever was there),
+     * or adds `ammo` if they have it already.
+     */
+    giveWeapon(weapon, ammo) {
+        if (this.#connected && !this.#native.giveWeapon(this.id, weapon, Math.max(0, Math.trunc(ammo)))) {
+            throw new RangeError(`not a weapon: ${weapon}`);
+        }
+    }
+    /** Sets the ammo of a weapon they have. */
+    setAmmo(weapon, ammo) {
+        if (this.#connected)
+            this.#native.setWeaponAmmo(this.id, weapon, Math.max(0, Math.trunc(ammo)));
+    }
+    removeWeapon(weapon) {
+        if (this.#connected)
+            this.#native.removeWeapon(this.id, weapon);
+    }
+    /** Takes all their weapons. */
+    resetWeapons() {
+        if (this.#connected)
+            this.#native.resetWeapons(this.id);
+    }
+    /**
+     * Puts them out of their vehicle, beside it; with `jump`, they get out as
+     * the game does (diving out of one that's moving: a bail).
+     */
+    removeFromVehicle(options = {}) {
+        if (this.#connected)
+            this.#native.removeFromVehicle(this.id, options.jump ?? false);
+    }
+    /** Radio station names aren't shown on their screen (in any vehicle). */
+    get radioNameHidden() {
+        return this.#state()?.radioNameHidden ?? false;
+    }
+    set radioNameHidden(hidden) {
+        if (this.#connected)
+            this.#native.setRadioNameHidden(this.id, hidden);
+    }
+    /** Adds (or, if negative, takes) money. */
+    giveMoney(amount) {
+        this.money = this.money + amount;
+    }
+    // What was just set (until their game has had time to report it): the
+    // value read back, and what the other setter sends with its own.
+    #justSet = { at: 0 };
+    #recent(key) {
+        return Date.now() - this.#justSet.at < 1000 ? this.#justSet[key] : undefined;
+    }
+    get health() {
+        return this.#recent("health") ?? this.#state()?.health ?? 0;
+    }
+    set health(value) {
+        if (!this.#connected)
+            return;
+        const armour = this.armour;
+        this.#justSet = { ...(Date.now() - this.#justSet.at < 1000 ? this.#justSet : {}), health: value, at: Date.now() };
+        this.#native.setHealth(this.id, value, armour);
+    }
+    get armour() {
+        return this.#recent("armour") ?? this.#state()?.armour ?? 0;
+    }
+    set armour(value) {
+        if (!this.#connected)
+            return;
+        const health = this.health;
+        this.#justSet = { ...(Date.now() - this.#justSet.at < 1000 ? this.#justSet : {}), armour: value, at: Date.now() };
+        this.#native.setHealth(this.id, health, value);
+    }
+    /** Position in metres (world coordinates); their vehicle's while driving. */
+    get position() {
+        const s = this.#state();
+        return { x: s?.x ?? 0, y: s?.y ?? 0, z: s?.z ?? 0 };
+    }
+    /** Facing direction in degrees, 0 = north, increasing anticlockwise. */
+    get heading() {
+        return ((this.#state()?.heading ?? 0) * 180) / Math.PI;
+    }
+    /** Velocity in m/s, as their last sync (a passenger: their vehicle's). */
+    get velocity() {
+        const v = this.#state()?.velocity;
+        return { x: v?.x ?? 0, y: v?.y ?? 0, z: v?.z ?? 0 };
+    }
+    /**
+     * Whether they're aiming a gun at `target` (a ped, player, vehicle or
+     * spot): holding aim with a firearm, within `range` m (default 10), their
+     * camera pointing within `angle` degrees of it (default 12). For a ped
+     * that gives up at gunpoint.
+     *
+     * ```ts
+     * if (player.isAimingAt(benny, { range: 6 })) void benny.handsUp(3000);
+     * ```
+     */
+    isAimingAt(target, options = {}) {
+        const s = this.#state();
+        if (!s || !s.cameraFront || !s.cameraPosition || s.vehicleId !== null)
+            return false;
+        if ((s.keys & Key.Aim) === 0 || s.weapon < 22 || s.weapon > 38)
+            return false; // aiming a firearm
+        const at = "position" in target ? target.position : target;
+        const range = options.range ?? 10;
+        if (Math.hypot(at.x - s.x, at.y - s.y, at.z - s.z) > range)
+            return false;
+        // From their camera to it (its middle, a little up), against where the camera looks.
+        const d = { x: at.x - s.cameraPosition.x, y: at.y - s.cameraPosition.y, z: at.z + 0.3 - s.cameraPosition.z };
+        const len = Math.hypot(d.x, d.y, d.z) || 1;
+        const f = s.cameraFront;
+        const cos = (d.x * f.x + d.y * f.y + d.z * f.z) / len;
+        return cos >= Math.cos(((options.angle ?? 12) * Math.PI) / 180);
+    }
+    /** The buttons they hold (`Key` bits), as their last sync. See `playerKeys`. */
+    get keys() {
+        return this.#state()?.keys ?? 0;
+    }
+    /** Teleports the player. `heading` in degrees. */
+    setPosition(position, heading = 0) {
+        if (this.#connected) {
+            this.#native.setPosition(this.id, position.x, position.y, position.z, (heading * Math.PI) / 180);
+        }
+    }
+    /**
+     * Fades their screen out to `color` (default black) over `ms`, and keeps
+     * it there until `fadeIn()`. Resolves when it's dark.
+     */
+    fadeOut(ms = 500, color = "#000000") {
+        if (this.#connected)
+            this.#native.screenFade(this.id, false, Math.max(0, ms), mapColor(color, 0xff) >>> 8);
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /** Fades their screen back in over `ms`. Resolves when it's clear. */
+    fadeIn(ms = 500) {
+        if (this.#connected)
+            this.#native.screenFade(this.id, true, Math.max(0, ms), 0);
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Plays one of the game's animations on them (everyone sees it), e.g.
+     * `playAnim("PED", "phone_talk", { loop: true })`. `ms` stops it after
+     * that long; without, it plays to its end (a looping one: until
+     * `stopAnim()`, or they move off). Blocks other than "PED" stream in
+     * first. Resolves after `ms` (or at once). `hold` keeps it on its last
+     * frame until the next replaces it (SA-MP's ApplyAnimation freeze): for
+     * animations played one after another, which otherwise blend back
+     * towards standing in the moment between them. `upperBody` plays it on
+     * the upper body only (the game's secondary task): they can walk
+     * meanwhile, e.g. `playAnim("GANGS", "smkcig_prtl", { upperBody: true })`.
+     */
+    playAnim(block, name, options = {}) {
+        if (!/^[A-Za-z0-9_]{1,23}$/.test(block) || !/^[A-Za-z0-9_]{1,31}$/.test(name)) {
+            throw new RangeError(`not an animation: ${block}/${name}`);
+        }
+        const ms = Math.max(0, Math.trunc(options.ms ?? 0));
+        if (this.#connected)
+            this.#native.playerAnim(this.id, block, name, options.loop ?? false, ms, false, options.hold ?? false, options.upperBody ?? false);
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /** Stops whatever animation they're playing. */
+    stopAnim() {
+        if (this.#connected)
+            this.#native.playerAnim(this.id, "", "", false, 0, true);
+    }
+    /**
+     * Whether they're frozen: they can't move (their controls are off, as in
+     * a cutscene) until unfrozen. Animations still play.
+     */
+    get frozen() {
+        return this.#frozen;
+    }
+    set frozen(frozen) {
+        this.#frozen = frozen;
+        if (this.#connected)
+            this.#native.freezePlayer(this.id, frozen);
+    }
+    #frozen = false;
+    /**
+     * Moves them on foot to a spot nearby and turns them to `heading`
+     * (degrees): the game's own slide, as its machine scripts put a player in
+     * front of a vending machine. Unlike `setPosition`, no teleport (no drop
+     * from the game standing them on `z`). Resolves when they're there, or
+     * after `ms` (default 2000). Works while `frozen`.
+     *
+     * ```ts
+     * player.frozen = true;
+     * await player.slideTo({ x: 2326.2, y: -1646.1, z: 14.2 }, 0);
+     * await player.playAnim("VENDING", "VEND_Use", { ms: 2600 });
+     * ```
+     */
+    slideTo(position, heading = this.heading, ms = 2000) {
+        if (!this.#connected)
+            return Promise.resolve();
+        this.#native.slidePlayer(this.id, position.x, position.y, position.z, heading);
+        return new Promise((resolve) => {
+            const started = Date.now();
+            const check = setInterval(() => {
+                const p = this.position;
+                const turn = Math.abs(((this.heading - heading) % 360 + 540) % 360 - 180);
+                if (!this.#connected || Date.now() - started >= ms ||
+                    (Math.hypot(p.x - position.x, p.y - position.y) < 0.2 && turn < 10)) {
+                    clearInterval(check);
+                    resolve();
+                }
+            }, 100);
+        });
+    }
+    /**
+     * Says a line of the game's mission dialogue as CJ (`dialogue`, its GXT
+     * key such as "RYD2_CA", from mission table `table`): its recording from
+     * this player, with its text as the subtitle, heard by `to` or everyone
+     * within 40 m. Resolves when it's done. `effects` puts the recording
+     * through audio effects (`"phone"`...; then the lips don't move).
+     */
+    say(line) {
+        const spoken = speechOf(this.#native, line);
+        if (this.#connected) {
+            this.#native.playerSay(this.id, spoken.dialogue, spoken.subtitle, line.ms ?? 0, line.to ? line.to.filter((p) => p.connected).map((p) => p.id) : null, encodeEffects(line.effects));
+        }
+        return new Promise((resolve) => setTimeout(resolve, spoken.ms));
+    }
+    /**
+     * A subtitle at the bottom of their screen, in the game's style, for `ms`
+     * (left out: as long as reading it takes). Shown only if they have
+     * subtitles on in their pause menu.
+     */
+    subtitle(text, ms = 0) {
+        if (this.#connected)
+            this.#native.subtitle(this.id, text.slice(0, 255), Math.max(0, ms));
+    }
+    /**
+     * Their colour: their name in chat and their name tag (as SA-MP's
+     * SetPlayerColor), unless `nameTag.color` says otherwise. 0xRRGGBB,
+     * default white.
+     */
+    get color() {
+        return this.#color;
+    }
+    set color(color) {
+        this.#color = color & 0xffffff;
+        this.#sendTag?.(this);
+    }
+    #color = 0xffffff;
+    /**
+     * Their name tag, as everyone sees it (unless `setNameTagFor` says
+     * otherwise for someone): `hidden` (a mask), `text` instead of their name,
+     * `color` (0xRRGGBB) instead of `player.color`. Setting it replaces it
+     * (`{}`: as normal).
+     *
+     * ```ts
+     * player.nameTag = { text: `Stranger ${player.id}` };   // a mask
+     * player.nameTag = { hidden: true };
+     * ```
+     */
+    get nameTag() {
+        return { ...this.#tag };
+    }
+    set nameTag(tag) {
+        this.#tag = { ...tag };
+        this.#sendTag?.(this);
+    }
+    /**
+     * Their name tag as `viewer` sees it, over `nameTag` (as SA-MP's
+     * ShowPlayerNameTagForPlayer, with text and colour too); null: as
+     * everyone sees it.
+     *
+     * ```ts
+     * target.setNameTagFor(admin, { text: `${target.name} (masked)` });
+     * ```
+     */
+    setNameTagFor(viewer, tag) {
+        if (tag)
+            this.#tagFor.set(viewer.id, { ...tag });
+        else
+            this.#tagFor.delete(viewer.id);
+        this.#sendTag?.(this, viewer);
+    }
+    /** @internal Their tag as `viewer` sees it: [hidden, text, colour]. */
+    tagFor(viewer) {
+        const t = { ...this.#tag, ...this.#tagFor.get(viewer.id) };
+        const color = t.color ?? this.#color;
+        return [t.hidden ?? false, t.text ?? "", color === 0xffffff ? null : color & 0xffffff];
+    }
+    /** @internal A viewer left: their overrides go. */
+    forgetViewer(viewer) {
+        this.#tagFor.delete(viewer.id);
+    }
+    #tag = {};
+    #tagFor = new Map();
+    #sendTag = null;
+    /** @internal */
+    setTagSender(fn) {
+        this.#sendTag = fn;
+    }
+    /**
+     * Shows a message to this player. `color` is 0xRRGGBB; `{RRGGBB}` in the
+     * text colours what follows. `markdown`: the text is markdown (bold,
+     * italic, code, links) instead. `{key:ID}` shows an action's key either way.
+     */
+    send(text, color, options = {}) {
+        if (this.#connected)
+            this.#native.sendMessage(this.id, text, color ?? 0, options.markdown ?? false);
+    }
+    /**
+     * Their checkpoint, as SA-MP's SetPlayerCheckpoint: a red cylinder on the
+     * ground at `position`, `size` m across (default 2), with a radar blip.
+     * One at a time: setting another replaces it. Entering and leaving it
+     * fire `playerEnterCheckpoint` / `playerLeaveCheckpoint`.
+     *
+     * ```ts
+     * player.setCheckpoint({ x: 2495, y: -1690, z: 13.5 }, 3);
+     * server.on("playerEnterCheckpoint", (player) => { player.disableCheckpoint(); ... });
+     * ```
+     */
+    setCheckpoint(position, size = 2) {
+        this.checkpoint = { position: { ...position }, size };
+        this.inCheckpoint = false;
+        if (this.#connected)
+            this.#native.checkpoint(this.id, { race: false, enabled: true, ...position, size });
+    }
+    /** Takes their checkpoint away (DisablePlayerCheckpoint). */
+    disableCheckpoint() {
+        this.checkpoint = null;
+        this.inCheckpoint = false;
+        if (this.#connected)
+            this.#native.checkpoint(this.id, { race: false, enabled: false });
+    }
+    /**
+     * Their race checkpoint, as SA-MP's SetPlayerRaceCheckpoint: the game's
+     * own, its arrow pointing at `next`. `type`: 0 normal, 1 finish, 2
+     * nothing (no arrow), 3 in the air (a ring), 4 the air finish. Entering
+     * and leaving fire `playerEnterRaceCheckpoint` / `playerLeaveRaceCheckpoint`.
+     */
+    setRaceCheckpoint(position, options = {}) {
+        const size = options.size ?? 4, type = options.type ?? 0, next = options.next ?? position;
+        this.raceCheckpoint = { position: { ...position }, size, type, next: { ...next } };
+        this.inRaceCheckpoint = false;
+        if (this.#connected) {
+            this.#native.checkpoint(this.id, {
+                race: true, enabled: true, ...position, size, type, nextX: next.x, nextY: next.y, nextZ: next.z,
+            });
+        }
+    }
+    /** Takes their race checkpoint away. */
+    disableRaceCheckpoint() {
+        this.raceCheckpoint = null;
+        this.inRaceCheckpoint = false;
+        if (this.#connected)
+            this.#native.checkpoint(this.id, { race: true, enabled: false });
+    }
+    /** Their checkpoint, or null. */
+    checkpoint = null;
+    /** In it now. */
+    inCheckpoint = false;
+    /** Their race checkpoint, or null. */
+    raceCheckpoint = null;
+    /** In it now. */
+    inRaceCheckpoint = false;
+    /**
+     * Shows them a dialog, as SA-MP's ShowPlayerDialog, and resolves with
+     * their answer: `response` true for the first button (Enter), false for
+     * the second (Escape); `listItem` the row they chose (list styles, else
+     * -1); `input` what they typed. One at a time: a new one replaces (and
+     * resolves, `response` false) the one showing.
+     *
+     * ```ts
+     * const { response, input } = await player.dialog({ style: "password", title: "Login", body: "Your password:", button1: "Login", button2: "Quit" });
+     * const { listItem } = await player.dialog({ style: "tablist", title: "Buy", body: "Pistol\t$500\nShotgun\t$1200", button1: "Buy", button2: "Close" });
+     * ```
+     */
+    dialog(d) {
+        const styles = { msgbox: 0, input: 1, list: 2, password: 3, tablist: 4, tablistHeaders: 5 };
+        const style = styles[d.style ?? "msgbox"];
+        if (style === undefined)
+            throw new RangeError(`not a dialog style: ${d.style}`);
+        this.#dialogAnswer?.({ response: false, listItem: -1, input: "" });
+        const id = (this.#dialogId = (this.#dialogId % 0x7fffffff) + 1);
+        if (!this.#connected)
+            return Promise.resolve({ response: false, listItem: -1, input: "" });
+        this.#native.dialog(this.id, {
+            id, style, title: (d.title ?? "").slice(0, 128), body: (d.body ?? "").slice(0, 4095),
+            button1: (d.button1 ?? "OK").slice(0, 32), button2: (d.button2 ?? "").slice(0, 32), markdown: d.markdown ?? false,
+        });
+        return new Promise((resolve) => {
+            this.#dialogAnswer = (a) => {
+                this.#dialogAnswer = null;
+                resolve(a);
+            };
+        });
+    }
+    /**
+     * Shows a menu as the game's shops have (SA-MP's CreateMenu /
+     * ShowMenuForPlayer): a box at the top left, a title, rows of up to two
+     * columns, one chosen. Up/Down move (`onChoose`), Enter selects
+     * (`onSelect`), Backspace or Escape go back (`onBack`; the menu stays up
+     * until you close it or show another). One at a time: a new one
+     * replaces it. Keys go to the menu while it's up, so freeze them or
+     * leave them be as you need.
+     *
+     * ```ts
+     * const menu = player.menu({
+     *   title: "Ammu-Nation",
+     *   rows: [["Pistol", "$500"], ["Shotgun", "$1200"]],
+     *   footer: `Cash: $${player.money}`,
+     *   onSelect: (row) => { ... },
+     *   onBack: (m) => m.close(),
+     * });
+     * ```
+     */
+    menu(options) {
+        return this.#menus.open(options);
+    }
+    /** The menu showing, or null. */
+    get currentMenu() {
+        const m = this.#menus.current;
+        return m?.isOpen ? m : null;
+    }
+    /** @internal */
+    menuHeard(id, kind, row) {
+        this.#menus.heard(id, kind, row);
+    }
+    /** @internal Gone: no more menu events. */
+    forgetMenus() {
+        this.#menus.forget();
+    }
+    /** Takes away the dialog showing (it resolves, `response` false). */
+    hideDialog() {
+        if (!this.#dialogAnswer)
+            return;
+        if (this.#connected)
+            this.#native.dialog(this.id, { id: this.#dialogId, hide: true });
+        this.#dialogAnswer({ response: false, listItem: -1, input: "" });
+    }
+    /** @internal Their answer to dialog `id`. */
+    dialogAnswered(id, a) {
+        if (id === this.#dialogId)
+            this.#dialogAnswer?.(a);
+    }
+    #menusOf;
+    get #menus() {
+        return (this.#menusOf ??= new PlayerMenus(this.#native, this.id));
+    }
+    #dialogId = 0;
+    #dialogAnswer = null;
+    /**
+     * An object they hold, as SA-MP's SetPlayerAttachedObject: in `slot`
+     * (0-9; setting a slot again replaces it), on `bone` (`Bone`: SA-MP's
+     * 1-18, head, hands, spine...), offset, turned (degrees) and scaled from
+     * it. Everyone sees it, following every animation.
+     *
+     * ```ts
+     * player.attachObject(0, 19006, Bone.Head, { offset: { x: 0.1, y: 0.04, z: 0 }, rotation: { x: 90, y: 90, z: 0 } }); // glasses
+     * ```
+     */
+    attachObject(slot, model, bone, options = {}) {
+        if (!Number.isInteger(slot) || slot < 0 || slot > 9)
+            throw new RangeError(`not an attachment slot: ${slot} (0-9)`);
+        if (!Number.isInteger(bone) || bone < 1 || bone > 18)
+            throw new RangeError(`not a bone: ${bone} (1-18)`);
+        const o = options.offset ?? { x: 0, y: 0, z: 0 }, r = options.rotation ?? { x: 0, y: 0, z: 0 }, s = options.scale ?? { x: 1, y: 1, z: 1 };
+        const spec = { playerId: this.id, slot, model, bone, ox: o.x, oy: o.y, oz: o.z, rx: r.x, ry: r.y, rz: r.z, sx: s.x, sy: s.y, sz: s.z };
+        this.attachments.set(slot, spec);
+        this.#broadcastAttachment?.(spec);
+    }
+    /**
+     * What they're doing, as SA-MP's SetPlayerSpecialAction (or null):
+     * drinking (`"drinkBeer"`, `"drinkWine"`, `"drinkSprunk"`: a bottle or
+     * can in hand, fire to drink, which makes them drunker for beer and wine),
+     * `"smoke"` (fire for a drag), `"phone"` (on the phone; they can walk),
+     * `"carry"` (arms out as if carrying something; they can walk),
+     * `"handsUp"`, `"dance1"`-`"dance4"`, `"piss"` (these keep them in place),
+     * `"jetpack"`. Enter/exit drops a drink or cigarette (back to null).
+     * Everyone sees it, players arriving later too. It ends when they die,
+     * or get in a vehicle (except the phone).
+     *
+     * ```ts
+     * player.specialAction = "handsUp";
+     * player.specialAction = null;
+     * ```
+     */
+    get specialAction() {
+        return this.#special;
+    }
+    set specialAction(action) {
+        if (action !== null && !(action in specialPresets))
+            throw new RangeError(`not a special action: ${action}`);
+        if (!this.#connected)
+            return;
+        const was = this.#special ? specialPresets[this.#special] : null;
+        const now = action ? specialPresets[action] : null;
+        this.#special = action;
+        if (was?.prop && !now?.prop)
+            this.removeAttachedObject(kSpecialSlot);
+        if (now?.prop) {
+            const spec = { playerId: this.id, slot: kSpecialSlot, model: now.prop.model, bone: now.prop.bone, ox: now.prop.offset.x, oy: now.prop.offset.y, oz: now.prop.offset.z,
+                rx: now.prop.rotation.x, ry: now.prop.rotation.y, rz: now.prop.rotation.z, sx: 1, sy: 1, sz: 1 };
+            this.attachments.set(kSpecialSlot, spec);
+            this.#broadcastAttachment?.(spec);
+        }
+        const l = now?.loop;
+        this.#native.playerLoop(this.id, l?.block ?? "", l?.name ?? "", l?.upperBody ?? false, now?.jetpack ?? false, l?.hold ?? false, !!now?.use);
+    }
+    #special = null;
+    /** @internal Their buttons changed: what their special action does with them. */
+    specialKeys(keys, old) {
+        const p = this.#special ? specialPresets[this.#special] : null;
+        if (!p)
+            return;
+        const pressed = (k) => (keys & k) !== 0 && (old & k) === 0;
+        if (p.drop && pressed(Key.EnterExit)) {
+            this.specialAction = null;
+        }
+        else if (p.use && pressed(Key.Fire)) {
+            void this.playAnim(p.use.block, p.use.name, { upperBody: true });
+            if (p.use.drunk)
+                this.drunkLevel = Math.min(50000, this.drunkLevel + p.use.drunk);
+        }
+    }
+    /** @internal They died or got in a vehicle: it ends (the phone stays on in a vehicle). */
+    specialEnds(inVehicle) {
+        if (this.#special && !(inVehicle && this.#special === "phone"))
+            this.specialAction = null;
+    }
+    /** Takes the object in `slot` away (RemovePlayerAttachedObject). */
+    removeAttachedObject(slot) {
+        if (!this.attachments.delete(slot))
+            return;
+        this.#broadcastAttachment?.({ playerId: this.id, slot, remove: true });
+    }
+    /** @internal What their client script attached (or took away), for everyone. */
+    attachedByScript(spec) {
+        if (spec.remove) {
+            this.attachments.delete(spec.slot);
+        }
+        else {
+            if (!Number.isInteger(spec.bone) || spec.bone < 1 || spec.bone > 18)
+                return;
+            this.attachments.set(spec.slot, spec);
+        }
+        this.#broadcastAttachment?.(spec);
+    }
+    /** Whether `slot` holds an object (IsPlayerAttachedObjectSlotUsed). */
+    isAttachmentSlotUsed(slot) {
+        return this.attachments.has(slot);
+    }
+    /** @internal What they hold, by slot. */
+    attachments = new Map();
+    #broadcastAttachment = null;
+    /** @internal */
+    setAttachmentSender(fn) {
+        this.#broadcastAttachment = fn;
+    }
+    /**
+     * Text over their head for a while, as SA-MP's SetPlayerChatBubble: seen
+     * by those within `distance` m (default 20), for `ms` (default 5000).
+     * Another replaces it. A label on them that goes by itself.
+     *
+     * ```ts
+     * server.on("playerChat", (p, text) => { p.chatBubble(text, { color: 0xffffffff }); });
+     * ```
+     */
+    chatBubble(text, options = {}) {
+        this.#bubble?.remove();
+        if (this.#bubbleTimer)
+            clearTimeout(this.#bubbleTimer);
+        if (!this.#connected || !this.#makeBubble || !text)
+            return;
+        // SA-MP's {RRGGBB}: a leading one is its colour; others go (labels
+        // take the game's ~ codes).
+        let color = options.color ?? 0xffffffff;
+        const lead = /^\{([0-9a-fA-F]{6})\}/.exec(text);
+        if (lead)
+            color = ((parseInt(lead[1], 16) << 8) | 0xff) >>> 0;
+        text = text.replace(/\{[0-9a-fA-F]{6}\}/g, "");
+        const label = this.#makeBubble(text, color, options.distance ?? 20);
+        this.#bubble = label;
+        this.#bubbleTimer = setTimeout(() => {
+            label.remove();
+            if (this.#bubble === label)
+                this.#bubble = null;
+        }, Math.max(1, options.ms ?? 5000));
+    }
+    #bubble = null;
+    #bubbleTimer = null;
+    #makeBubble = null;
+    /** @internal */
+    setBubbleMaker(fn) {
+        this.#makeBubble = fn;
+    }
+    /**
+     * Puts them straight into a vehicle's seat (0 the driver's, the default;
+     * 1-8 passengers), as SA-MP's PutPlayerInVehicle. The vehicle must be in
+     * their world and near enough for their game to have it (move them to it
+     * first if it's far).
+     */
+    putInVehicle(vehicle, seat = 0) {
+        if (!Number.isInteger(seat) || seat < 0 || seat > 8)
+            throw new RangeError(`not a seat: ${seat}`);
+        if (this.#connected && vehicle.exists)
+            this.#native.putInVehicle(this.id, vehicle.id, seat);
+    }
+    /**
+     * Their fighting style (`FightingStyle`: Normal, Boxing, KungFu,
+     * KneeHead, GrabKick, Elbow), as SA-MP's SetPlayerFightingStyle (the
+     * same numbers). Everyone sees them fight so.
+     */
+    get fightingStyle() {
+        return this.#state()?.fightingStyle || 4;
+    }
+    set fightingStyle(style) {
+        if (![4, 5, 6, 7, 15, 16].includes(style))
+            throw new RangeError(`not a fighting style: ${style}`);
+        if (this.#connected)
+            this.#native.setFightingStyle(this.id, style);
+    }
+    /**
+     * How drunk they are, as SA-MP's SetPlayerDrunkLevel: above 2000 their
+     * camera sways (the more, the worse), and it falls by 60 a second
+     * (reading it gives what it's down to now). 0: sober.
+     */
+    get drunkLevel() {
+        return Math.max(0, Math.round(this.#drunk - (Date.now() - this.#drunkAt) * 0.06));
+    }
+    set drunkLevel(level) {
+        const l = Math.max(0, Math.min(50000, Math.trunc(level)));
+        this.#drunk = l;
+        this.#drunkAt = Date.now();
+        if (this.#connected)
+            this.#native.setDrunkLevel(this.id, l);
+    }
+    #drunk = 0;
+    #drunkAt = 0;
+    /** Empties their chat's log. */
+    clearChat() {
+        if (this.#connected)
+            this.#native.clearChat(this.id);
+    }
+    /** Disconnects the player, telling them why. */
+    kick(reason = "") {
+        if (this.#connected)
+            this.#native.kick(this.id, reason);
+    }
+    toString() {
+        return `${this.name} (${this.id})`;
+    }
+}
+//# sourceMappingURL=player.js.map