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

package/dist/player.d.ts

@@ -0,0 +1,685 @@
+import { type AudioEffects } from "./audio_effects.js";
+import { GameMap, type MapColor } from "./map.js";
+import { PlayerHud } from "./hud.js";
+import { PlayerSplash } from "./splash.js";
+import { PlayerCamera } from "./camera.js";
+import { type MenuOptions, type PlayerMenu } from "./menu.js";
+import { ScreenEffects } from "./screeneffects.js";
+import { ScreenDraw } from "./draw.js";
+import { PlayerUi } from "./ui.js";
+import { type SpecialAction } from "./special.js";
+import type { NativeServer } from "./native.js";
+import type { Vehicle } from "./vehicle.js";
+export interface Vector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * A connected player. Getters read the latest state the server has (synced
+ * from the player's client ~20 times a second); setters send a change to the
+ * player's client.
+ *
+ * Player objects stay valid until the `playerQuit` event for them has been
+ * handled; after that `connected` is false and changes are ignored.
+ */
+/** A dialog (`player.dialog`). */
+/** A box on the map: see `player.worldBounds`. */
+export interface WorldBounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/** A name tag: see `player.nameTag`. */
+export interface NameTagSettings {
+    /** Not shown (default false). */
+    hidden?: boolean;
+    /** Shown instead of their name. */
+    text?: string | null;
+    /** 0xRRGGBB, instead of `player.color`. */
+    color?: number | null;
+}
+export interface DialogOptions {
+    /** msgbox (text, buttons), input, password, list (one row a line), tablist (columns by \t), tablistHeaders (the first row the headings). Default msgbox. */
+    style?: "msgbox" | "input" | "password" | "list" | "tablist" | "tablistHeaders";
+    title?: string;
+    /** The text, or the rows. `{RRGGBB}` colours a part. */
+    body?: string;
+    /** The first button (Enter). Default "OK". */
+    button1?: string;
+    /** The second (Escape); left out: only the one. */
+    button2?: string;
+    /** The body is markdown (the msgbox, input and password styles). `{key:ID}` shows an action's key either way. */
+    markdown?: boolean;
+}
+/** Their answer to a dialog. */
+export interface DialogAnswer {
+    /** The first button (true), or the second / Escape (false). */
+    response: boolean;
+    /** The row chosen (list styles), or -1. */
+    listItem: number;
+    /** What they typed (input styles). */
+    input: string;
+}
+export declare class Player {
+    #private;
+    /** Slot number, unique among connected players (reused after they leave). */
+    readonly id: number;
+    /** Their name: as given when joining, or `setName`'s. */
+    get name(): string;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: Player | Vehicle | null): void;
+    /**
+     * 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: Player, visible: boolean): void;
+    /** Who or what they watch (`spectate`), or null. */
+    get spectating(): Player | Vehicle | 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(): number | null;
+    set weather(weather: number | 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(): WorldBounds | null;
+    set worldBounds(b: WorldBounds | 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: Player | Vector3, crime: number): void;
+    /**
+     * 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(): boolean;
+    set stuntBonus(on: boolean);
+    /** A number by their name in the player list (SetPlayerScore); shown once anyone's isn't 0. */
+    get score(): number;
+    set score(score: number);
+    /** Free-form per-player storage for gamemode data. */
+    readonly data: Record<string, unknown>;
+    /** @internal Created by Server; gamemodes receive Player objects from events. */
+    constructor(nativeServer: NativeServer, id: number, vehicle: (id: number) => Vehicle | undefined);
+    /** False once the player has left. */
+    get connected(): boolean;
+    /** @internal */
+    markDisconnected(): void;
+    /**
+     * The player's IP address. Through a trusted proxy (proxy mode), the one
+     * the proxy forwarded rather than the proxy's own.
+     */
+    get ip(): string;
+    /** True when the player came through a trusted proxy. */
+    get viaProxy(): boolean;
+    /**
+     * 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(): string;
+    get connectPort(): number;
+    /** Round-trip time in milliseconds. */
+    get ping(): number;
+    /** 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: Vector3, radius: number, maxDz?: number): boolean;
+    get alive(): boolean;
+    /** True while the player has the pause menu open. The game keeps running. */
+    get paused(): boolean;
+    /** False while the player's game window is in the background (alt-tabbed). */
+    get focused(): boolean;
+    /** The vehicle they are in (driving or as a passenger), or null. */
+    get vehicle(): Vehicle | 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(): Vehicle | null;
+    /** The vehicle they remote-control (`remoteControl()`), or null. */
+    get remoteVehicle(): Vehicle | 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: Vehicle | null, options?: {
+        detonate?: boolean;
+    }): boolean;
+    /** Their seat in `vehicle`: 0 is the driver's, 1-8 passengers'. null on foot. */
+    get seat(): number | null;
+    /** Ped model id (0 is CJ). Setting it changes the model for everyone. */
+    get skin(): number;
+    set skin(model: number);
+    /**
+     * Money, as the server keeps it. The player's game shows exactly this;
+     * anything their game changes by itself is undone.
+     */
+    get money(): number;
+    set money(value: number);
+    /** This player's own additions to the pause menu's map (see `GameMap`). */
+    get map(): GameMap;
+    /** Full-screen effects (your shaders) on their screen. See `ScreenEffects`. */
+    get screenEffects(): ScreenEffects;
+    /** Their camera: fixed shots, glides between them, following something, or back behind them. See `PlayerCamera`. */
+    get camera(): PlayerCamera;
+    /**
+     * 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(): PlayerSplash;
+    /** @internal Joined with the splash up (the server option `splash`). */
+    holdSplash(): PlayerSplash;
+    /** Their mission HUD: radar blips, objective text, timers and counters, result screens. */
+    get hud(): PlayerHud;
+    /** Drawing on their screen, SA-MP textdraw style: see `ScreenDraw`. */
+    get draw(): ScreenDraw;
+    /** UI documents (RML client files) the server opens on their screen: see `PlayerUi`. */
+    get ui(): PlayerUi;
+    /**
+     * 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: string, data?: unknown): void;
+    /**
+     * 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(): number;
+    set wantedLevel(level: number);
+    /**
+     * 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?: {
+        parole?: boolean;
+    }): void;
+    /** The most their wanted level can be, 0-6 (default 6). */
+    get maxWantedLevel(): number;
+    set maxWantedLevel(level: number);
+    /**
+     * 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(): number;
+    set world(world: number);
+    /**
+     * 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(): number;
+    set interior(interior: number);
+    /** Never tires when sprinting (or swimming, cycling). */
+    get infiniteSprint(): boolean;
+    set infiniteSprint(infinite: boolean);
+    /**
+     * 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(): boolean;
+    set skinAnimations(skin: boolean);
+    /**
+     * 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: number, value: number): void;
+    /** A stat as the server set it, or undefined (a new game's value). */
+    getStat(stat: number): number | undefined;
+    /** Back to a new game's value. */
+    resetStat(stat: number): void;
+    /** The weapon in their hand (`Weapon`), 0 unarmed. */
+    get weapon(): number;
+    /** Puts a weapon they have in their hand (0: unarmed). */
+    set weapon(weapon: number);
+    /**
+     * 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
+     * ```
+     */
+    respawn(): Promise<void>;
+    /** @internal */
+    setRespawner(fn: (p: Player) => void): void;
+    /**
+     * 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(): () => void;
+    /** What they carry, slot by slot, with ammo (the server's count). */
+    get weapons(): {
+        slot: number;
+        weapon: number;
+        ammo: number;
+    }[];
+    /**
+     * Gives a weapon with `ammo` (into its slot, replacing whatever was there),
+     * or adds `ammo` if they have it already.
+     */
+    giveWeapon(weapon: number, ammo: number): void;
+    /** Sets the ammo of a weapon they have. */
+    setAmmo(weapon: number, ammo: number): void;
+    removeWeapon(weapon: number): void;
+    /** Takes all their weapons. */
+    resetWeapons(): void;
+    /**
+     * 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?: {
+        jump?: boolean;
+    }): void;
+    /** Radio station names aren't shown on their screen (in any vehicle). */
+    get radioNameHidden(): boolean;
+    set radioNameHidden(hidden: boolean);
+    /** Adds (or, if negative, takes) money. */
+    giveMoney(amount: number): void;
+    get health(): number;
+    set health(value: number);
+    get armour(): number;
+    set armour(value: number);
+    /** Position in metres (world coordinates); their vehicle's while driving. */
+    get position(): Vector3;
+    /** Facing direction in degrees, 0 = north, increasing anticlockwise. */
+    get heading(): number;
+    /** Velocity in m/s, as their last sync (a passenger: their vehicle's). */
+    get velocity(): Vector3;
+    /**
+     * 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: {
+        position: Vector3;
+    } | Vector3, options?: {
+        range?: number;
+        angle?: number;
+    }): boolean;
+    /** The buttons they hold (`Key` bits), as their last sync. See `playerKeys`. */
+    get keys(): number;
+    /** Teleports the player. `heading` in degrees. */
+    setPosition(position: Vector3, heading?: number): void;
+    /**
+     * Fades their screen out to `color` (default black) over `ms`, and keeps
+     * it there until `fadeIn()`. Resolves when it's dark.
+     */
+    fadeOut(ms?: number, color?: MapColor): Promise<void>;
+    /** Fades their screen back in over `ms`. Resolves when it's clear. */
+    fadeIn(ms?: number): Promise<void>;
+    /**
+     * 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: string, name: string, options?: {
+        loop?: boolean;
+        ms?: number;
+        hold?: boolean;
+        upperBody?: boolean;
+    }): Promise<void>;
+    /** Stops whatever animation they're playing. */
+    stopAnim(): void;
+    /**
+     * Whether they're frozen: they can't move (their controls are off, as in
+     * a cutscene) until unfrozen. Animations still play.
+     */
+    get frozen(): boolean;
+    set frozen(frozen: boolean);
+    /**
+     * 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: Vector3, heading?: number, ms?: number): Promise<void>;
+    /**
+     * 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: {
+        dialogue: string;
+        table?: string;
+        subtitle?: string;
+        ms?: number;
+        to?: readonly Player[];
+        effects?: AudioEffects;
+    }): Promise<void>;
+    /**
+     * 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: string, ms?: number): void;
+    /**
+     * 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(): number;
+    set color(color: number);
+    /**
+     * 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(): NameTagSettings;
+    set nameTag(tag: NameTagSettings);
+    /**
+     * 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: Player, tag: NameTagSettings | null): void;
+    /** @internal Their tag as `viewer` sees it: [hidden, text, colour]. */
+    tagFor(viewer: Player): [boolean, string, number | null];
+    /** @internal A viewer left: their overrides go. */
+    forgetViewer(viewer: Player): void;
+    /** @internal */
+    setTagSender(fn: (target: Player, viewer?: Player) => void): void;
+    /**
+     * 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: string, color?: number, options?: {
+        markdown?: boolean;
+    }): void;
+    /**
+     * 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: Vector3, size?: number): void;
+    /** Takes their checkpoint away (DisablePlayerCheckpoint). */
+    disableCheckpoint(): void;
+    /**
+     * 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: Vector3, options?: {
+        next?: Vector3;
+        size?: number;
+        type?: number;
+    }): void;
+    /** Takes their race checkpoint away. */
+    disableRaceCheckpoint(): void;
+    /** Their checkpoint, or null. */
+    checkpoint: {
+        position: Vector3;
+        size: number;
+    } | null;
+    /** In it now. */
+    inCheckpoint: boolean;
+    /** Their race checkpoint, or null. */
+    raceCheckpoint: {
+        position: Vector3;
+        size: number;
+        type: number;
+        next: Vector3;
+    } | null;
+    /** In it now. */
+    inRaceCheckpoint: boolean;
+    /**
+     * 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: DialogOptions): Promise<DialogAnswer>;
+    /**
+     * 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: MenuOptions): PlayerMenu;
+    /** The menu showing, or null. */
+    get currentMenu(): PlayerMenu | null;
+    /** @internal */
+    menuHeard(id: number, kind: number, row: number): void;
+    /** @internal Gone: no more menu events. */
+    forgetMenus(): void;
+    /** Takes away the dialog showing (it resolves, `response` false). */
+    hideDialog(): void;
+    /** @internal Their answer to dialog `id`. */
+    dialogAnswered(id: number, a: DialogAnswer): void;
+    /**
+     * 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: number, model: number, bone: number, options?: {
+        offset?: Vector3;
+        rotation?: Vector3;
+        scale?: Vector3;
+    }): void;
+    /**
+     * 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(): SpecialAction | null;
+    set specialAction(action: SpecialAction | null);
+    /** @internal Their buttons changed: what their special action does with them. */
+    specialKeys(keys: number, old: number): void;
+    /** @internal They died or got in a vehicle: it ends (the phone stays on in a vehicle). */
+    specialEnds(inVehicle: boolean): void;
+    /** Takes the object in `slot` away (RemovePlayerAttachedObject). */
+    removeAttachedObject(slot: number): void;
+    /** @internal What their client script attached (or took away), for everyone. */
+    attachedByScript(spec: Parameters<NativeServer["playerAttachment"]>[1]): void;
+    /** Whether `slot` holds an object (IsPlayerAttachedObjectSlotUsed). */
+    isAttachmentSlotUsed(slot: number): boolean;
+    /** @internal What they hold, by slot. */
+    readonly attachments: Map<number, {
+        playerId: number;
+        slot: number;
+        remove?: boolean;
+        model?: number;
+        bone?: number;
+        ox?: number;
+        oy?: number;
+        oz?: number;
+        rx?: number;
+        ry?: number;
+        rz?: number;
+        sx?: number;
+        sy?: number;
+        sz?: number;
+    }>;
+    /** @internal */
+    setAttachmentSender(fn: (spec: Parameters<NativeServer["playerAttachment"]>[1]) => void): void;
+    /**
+     * 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: string, options?: {
+        color?: number;
+        distance?: number;
+        ms?: number;
+    }): void;
+    /** @internal */
+    setBubbleMaker(fn: (text: string, color: number, distance: number) => {
+        remove(): void;
+    }): void;
+    /**
+     * 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: Vehicle, seat?: number): void;
+    /**
+     * 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(): number;
+    set fightingStyle(style: number);
+    /**
+     * 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(): number;
+    set drunkLevel(level: number);
+    /** Empties their chat's log. */
+    clearChat(): void;
+    /** Disconnects the player, telling them why. */
+    kick(reason?: string): void;
+    toString(): string;
+}