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

package/dist/effects.js

@@ -0,0 +1,116 @@
+import { GameObject, Broadcast } from "./objects.js";
+import { mapColor } from "./map.js";
+import { Ped } from "./ped.js";
+import { Player } from "./player.js";
+import { Vehicle } from "./vehicle.js";
+/** An effect (`server.effects.play()`). */
+export class Effect {
+    id;
+    name;
+    #b;
+    #playing = true;
+    #forget;
+    /** @internal */
+    constructor(id, name, b, forget) {
+        this.id = id;
+        this.name = name;
+        this.#b = b;
+        this.#forget = forget;
+    }
+    /** False once stopped. A one-off effect stays "playing" until stopped, as far as the server knows. */
+    get playing() {
+        return this.#playing;
+    }
+    /** Stops it (its last particles fade out). */
+    stop() {
+        if (!this.#playing)
+            return;
+        this.#playing = false;
+        this.#b.sendAll({ stop: true });
+        this.#forget(this);
+    }
+    /** @internal */
+    replay(player) {
+        this.#b.replay(player);
+    }
+    /** @internal */
+    get loops() {
+        return this.#b.spec.loop === true;
+    }
+}
+/**
+ * `server.effects`: the game's particle effects, by name (`"explosion_crate"`,
+ * `"fire"`, `"riot_smoke"`...: the game's effects.fxp), and puffs of
+ * coloured dust.
+ */
+export class ServerEffects {
+    #native;
+    #players;
+    #next = 1;
+    #loops = new Map();
+    /** @internal */
+    constructor(native, players) {
+        this.#native = native;
+        this.#players = players;
+    }
+    /**
+     * Plays one of the game's effects, at a spot or on something it follows.
+     *
+     * ```ts
+     * server.effects.play("explosion_crate", crate.position);
+     * const fire = server.effects.play("fire", car, { loop: true, offset: { x: 0, y: 2, z: 0.5 } });
+     * fire.stop();
+     * ```
+     */
+    play(name, at, options = {}) {
+        if (!/^[A-Za-z0-9_]{1,31}$/.test(name))
+            throw new RangeError(`not an effect name: "${name}"`);
+        const id = this.#next++;
+        const spec = { id, name, loop: options.loop ?? false, ...this.#where(at, options.offset) };
+        // A one-off is for those here now; a loop for those joining later too.
+        const b = new Broadcast((p, s) => this.#native.effect(p.id, s), this.#players, options.to, spec);
+        const effect = new Effect(id, name, b, (e) => this.#loops.delete(e.id));
+        if (spec.loop && !options.to)
+            this.#loops.set(id, effect);
+        return effect;
+    }
+    /**
+     * Puffs of coloured dust (the game's smoke, tinted): a Pay 'n' Spray's
+     * cloud, a car skidding on sand.
+     *
+     * ```ts
+     * server.effects.dust(car, { color: "#c03030", count: 40, spread: 2.5, size: 1.5 });
+     * ```
+     */
+    dust(at, options = {}) {
+        const spec = {
+            id: this.#next++, ...this.#where(at, options.offset),
+            color: options.color === undefined ? 0xffffffff : mapColor(options.color, 0xffffffff),
+            size: options.size ?? 1, count: Math.max(1, Math.min(200, Math.trunc(options.count ?? 20))),
+            spread: options.spread ?? 1, rise: options.rise ?? 0.3, life: options.life ?? 1,
+            carColor: options.carColor === undefined ? 0 : Math.max(0, Math.min(127, Math.trunc(options.carColor))) + 1,
+        };
+        for (const p of options.to ?? this.#players()) {
+            if (p.connected)
+                this.#native.effect(p.id, spec);
+        }
+    }
+    #where(at, offset) {
+        const o = offset ?? { x: 0, y: 0, z: 0 };
+        if (at instanceof Player)
+            return { on: 2, target: at.id, ...o };
+        if (at instanceof Vehicle)
+            return { on: 3, target: at.id, ...o };
+        if (at instanceof Ped)
+            return { on: 1, target: at.id, ...o };
+        if (at instanceof GameObject)
+            return { on: 4, target: at.id, ...o };
+        return { x: at.x + o.x, y: at.y + o.y, z: at.z + o.z };
+    }
+    /** @internal A player joined: the loops playing for everyone. */
+    replay(player) {
+        for (const e of this.#loops.values())
+            e.replay(player);
+    }
+}
+//# sourceMappingURL=effects.js.map

package/dist/effects.js.map

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

package/dist/gangzones.d.ts

@@ -0,0 +1,47 @@
+import { type MapColor } from "./map.js";
+import type { NativeServer } from "./native.js";
+import type { Player } from "./player.js";
+/** Where a gang zone is: two opposite corners on the map. */
+export interface GangZoneArea {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * A coloured rectangle on the radar and the maps (SA-MP's gang zones:
+ * turfs, no-go areas), seen by the players it's shown to. Colours are
+ * 0xRRGGBBAA or "#RRGGBB[AA]"; a see-through alpha suits them.
+ *
+ * ```ts
+ * const turf = server.createGangZone({ minX: 2400, minY: -1750, maxX: 2550, maxY: -1630 }, 0x00ff0060);
+ * turf.show();                       // everyone, players joining later too
+ * turf.flash(0xff000080);            // under attack
+ * ```
+ */
+export declare class GangZone {
+    #private;
+    readonly id: number;
+    readonly area: GangZoneArea;
+    /** @internal */
+    constructor(native: NativeServer, players: () => Player[], id: number, area: GangZoneArea, color: MapColor, forget: () => void);
+    /** Its colour (0xRRGGBBAA); setting it changes it for everyone who sees it. */
+    get color(): number;
+    set color(color: MapColor);
+    /** Shows it to one player, or (none given) everyone, players joining later too. */
+    show(player?: Player): this;
+    /** Hides it from one player, or (none given) everyone. */
+    hide(player?: Player): this;
+    /** Flashes it between its colour and `color`, for everyone who sees it. */
+    flash(color: MapColor): this;
+    /** Stops it flashing. */
+    stopFlash(): this;
+    /** Whether `player` sees it. */
+    shownTo(player: Player): boolean;
+    /** Takes it away from everyone, for good. */
+    destroy(): void;
+    /** @internal A player joined: they see it if it's everyone's. */
+    replay(player: Player): void;
+    /** @internal A player left. */
+    forget(player: Player): void;
+}

package/dist/gangzones.js

@@ -0,0 +1,122 @@
+import { mapColor } from "./map.js";
+/**
+ * A coloured rectangle on the radar and the maps (SA-MP's gang zones:
+ * turfs, no-go areas), seen by the players it's shown to. Colours are
+ * 0xRRGGBBAA or "#RRGGBB[AA]"; a see-through alpha suits them.
+ *
+ * ```ts
+ * const turf = server.createGangZone({ minX: 2400, minY: -1750, maxX: 2550, maxY: -1630 }, 0x00ff0060);
+ * turf.show();                       // everyone, players joining later too
+ * turf.flash(0xff000080);            // under attack
+ * ```
+ */
+export class GangZone {
+    id;
+    area;
+    #native;
+    #players;
+    #color;
+    #flash = null;
+    #everyone = false;
+    #shown = new Set();
+    #destroyed = false;
+    #forget;
+    /** @internal */
+    constructor(native, players, id, area, color, forget) {
+        this.#native = native;
+        this.#players = players;
+        this.#forget = forget;
+        this.id = id;
+        this.area = {
+            minX: Math.min(area.minX, area.maxX), maxX: Math.max(area.minX, area.maxX),
+            minY: Math.min(area.minY, area.maxY), maxY: Math.max(area.minY, area.maxY),
+        };
+        this.#color = mapColor(color, 0xffffff80);
+    }
+    /** Its colour (0xRRGGBBAA); setting it changes it for everyone who sees it. */
+    get color() {
+        return this.#color;
+    }
+    set color(color) {
+        this.#color = mapColor(color, 0xffffff80);
+        this.#resend();
+    }
+    /** Shows it to one player, or (none given) everyone, players joining later too. */
+    show(player) {
+        if (this.#destroyed)
+            return this;
+        if (player)
+            this.#shown.add(player);
+        else
+            this.#everyone = true;
+        for (const p of player ? [player] : this.#players())
+            this.#send(p);
+        return this;
+    }
+    /** Hides it from one player, or (none given) everyone. */
+    hide(player) {
+        if (player) {
+            this.#shown.delete(player);
+            if (this.#everyone)
+                return this; // everyone's still includes them
+            this.#remove(player);
+        }
+        else {
+            this.#everyone = false;
+            this.#shown.clear();
+            for (const p of this.#players())
+                this.#remove(p);
+        }
+        return this;
+    }
+    /** Flashes it between its colour and `color`, for everyone who sees it. */
+    flash(color) {
+        this.#flash = mapColor(color, 0xff000080);
+        this.#resend();
+        return this;
+    }
+    /** Stops it flashing. */
+    stopFlash() {
+        this.#flash = null;
+        this.#resend();
+        return this;
+    }
+    /** Whether `player` sees it. */
+    shownTo(player) {
+        return !this.#destroyed && (this.#everyone || this.#shown.has(player));
+    }
+    /** Takes it away from everyone, for good. */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.hide();
+        this.#destroyed = true;
+        this.#forget();
+    }
+    /** @internal A player joined: they see it if it's everyone's. */
+    replay(player) {
+        if (this.shownTo(player))
+            this.#send(player);
+    }
+    /** @internal A player left. */
+    forget(player) {
+        this.#shown.delete(player);
+    }
+    #resend() {
+        for (const p of this.#players())
+            if (this.shownTo(p))
+                this.#send(p);
+    }
+    #send(player) {
+        if (!player.connected)
+            return;
+        const a = this.area;
+        this.#native.gangZone(player.id, { id: this.id, remove: false, minX: a.minX, minY: a.minY, maxX: a.maxX, maxY: a.maxY,
+            color: this.#color, flashing: this.#flash !== null, flashColor: this.#flash ?? 0 });
+    }
+    #remove(player) {
+        if (player.connected)
+            this.#native.gangZone(player.id, { id: this.id, remove: true, minX: 0, minY: 0, maxX: 0, maxY: 0, color: 0, flashing: false, flashColor: 0 });
+    }
+}
+//# sourceMappingURL=gangzones.js.map

package/dist/gangzones.js.map

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

package/dist/geo.d.ts

@@ -0,0 +1,11 @@
+import type { Vector3 } from "./player.js";
+/** How far apart two points are (m). */
+export declare function distance(a: Vector3, b: Vector3): number;
+/** How far apart two points are on the map, ignoring height (m). */
+export declare function distance2d(a: Vector3, b: Vector3): number;
+/** The way a heading points, as a unit vector on the map (`z` 0). */
+export declare function headingVector(heading: number): Vector3;
+/** The heading from `from` towards `to` (degrees). */
+export declare function headingTo(from: Vector3, to: Vector3): number;
+/** `at` moved `distance` m along `heading` (and `up` m up). */
+export declare function along(at: Vector3, heading: number, distance: number, up?: number): Vector3;

package/dist/geo.js

@@ -0,0 +1,25 @@
+// Small geometry helpers for scripts: distances and headings as the game
+// has them (degrees, 0 north, anticlockwise).
+/** How far apart two points are (m). */
+export function distance(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+/** How far apart two points are on the map, ignoring height (m). */
+export function distance2d(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y);
+}
+/** The way a heading points, as a unit vector on the map (`z` 0). */
+export function headingVector(heading) {
+    const h = (heading * Math.PI) / 180;
+    return { x: -Math.sin(h), y: Math.cos(h), z: 0 };
+}
+/** The heading from `from` towards `to` (degrees). */
+export function headingTo(from, to) {
+    return ((Math.atan2(-(to.x - from.x), to.y - from.y) * 180) / Math.PI + 360) % 360;
+}
+/** `at` moved `distance` m along `heading` (and `up` m up). */
+export function along(at, heading, distance, up = 0) {
+    const v = headingVector(heading);
+    return { x: at.x + v.x * distance, y: at.y + v.y * distance, z: at.z + up };
+}
+//# sourceMappingURL=geo.js.map

package/dist/geo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.js","sourceRoot":"","sources":["../src/geo.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,8CAA8C;AAI9C,wCAAwC;AACxC,MAAM,UAAU,QAAQ,CAAC,CAAU,EAAE,CAAU;IAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,UAAU,CAAC,CAAU,EAAE,CAAU;IAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;IACpC,OAAO,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,SAAS,CAAC,IAAa,EAAE,EAAW;IAClD,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACrF,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,KAAK,CAAC,EAAW,EAAE,OAAe,EAAE,QAAgB,EAAE,EAAE,GAAG,CAAC;IAC1E,MAAM,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC;AAC9E,CAAC"}

package/dist/hud.d.ts

@@ -0,0 +1,159 @@
+import type { NativeServer } from "./native.js";
+import { type MapColor } from "./map.js";
+import type { Player, Vector3 } from "./player.js";
+import { Ped } from "./ped.js";
+import { Vehicle } from "./vehicle.js";
+/** The game's blip colours, or `"#RRGGBB[AA]"` / 0xRRGGBBAA. */
+export type BlipColor = "red" | "green" | "blue" | "white" | "yellow" | "purple" | "cyan" | "threat" | "destination" | MapColor;
+export interface BlipOptions {
+    /** Default `"destination"` for a spot (the game's yellow), `"blue"` for peds and vehicles (friendly). */
+    color?: BlipColor;
+    /**
+     * `"both"` (the default): the radar blip and the 3D marker (the cylinder at
+     * a spot, the arrow over a ped or vehicle); `"blip"` or `"marker"` alone.
+     */
+    display?: "both" | "blip" | "marker";
+    /** 1-4. */
+    scale?: number;
+    /** Dims and brightens twice a second, on the radar and the maps: a phone ringing, something urgent. */
+    pulse?: boolean;
+    /** Spots only: one of the game's radar sprites (1-63) instead of a plain blip and marker. */
+    sprite?: number;
+    /**
+     * Spots only: on the radar only near it, never on its edge, as the game's
+     * shops and garages (Pay 'n' Spray, Ammu-Nation); the pause map shows it
+     * anywhere.
+     */
+    shortRange?: boolean;
+}
+/** A blip on one player's radar (`player.hud.blip()`). */
+export declare class Blip {
+    #private;
+    readonly id: number;
+    /** @internal */
+    constructor(hud: PlayerHud, id: number, spec: NonNullable<Parameters<NativeServer["setBlip"]>[2]>, options?: BlipOptions);
+    /** Changes the options given; the others stay as they are. */
+    set(options: BlipOptions): this;
+    remove(): void;
+}
+/** A timer or counter on one player's HUD (`player.hud.counter()`, `.timer()`). */
+export declare class HudCounter {
+    #private;
+    readonly id: number;
+    /** @internal */
+    constructor(native: NativeServer, player: number, id: number, spec: NonNullable<Parameters<NativeServer["hudCounter"]>[2]>);
+    /** The number (a counter), the time left (a timer, ms), or how full (a bar). */
+    set value(value: number);
+    get value(): number;
+    /**
+     * A timer held still (showing `value`, the time left) or counting again
+     * from it.
+     */
+    setPaused(paused: boolean, value: number): void;
+    /** Changes its label. */
+    set label(label: string);
+    remove(): void;
+}
+/**
+ * One player's mission HUD: radar blips (with the game's markers),
+ * objective text, big text, timers and counters, and the mission result
+ * screen. `player.hud`.
+ */
+/** Parts of the game's HUD (`player.hud.set`): true shows, false hides. */
+export interface HudParts {
+    /** The whole HUD (the radar too). */
+    visible?: boolean;
+    radar?: boolean;
+    /** The area's name as they enter it. */
+    areaNames?: boolean;
+    /** A vehicle's name as they get in. */
+    vehicleNames?: boolean;
+    clock?: boolean;
+    /** The health bar (top right). */
+    health?: boolean;
+    /** The armour bar. */
+    armour?: boolean;
+    /** The chat (not part of `visible`, which is the game's HUD). */
+    chat?: boolean;
+}
+export declare class PlayerHud {
+    #private;
+    /** @internal */
+    constructor(native: NativeServer, player: number);
+    /**
+     * Shows or hides parts of the game's HUD for them; parts left out stay
+     * as they are. A client script can hide parts too (`sagl.hud.set`): a
+     * part shows only if neither hides it.
+     *
+     * ```ts
+     * player.hud.set({ visible: false });                 // a login screen: nothing over the shot
+     * player.hud.set({ visible: true, clock: false });    // back, without the clock
+     * ```
+     */
+    set(parts: HudParts): void;
+    /** Which parts show (as the server set them). */
+    get parts(): Required<HudParts>;
+    /** @internal */
+    send(id: number, spec: Parameters<NativeServer["setBlip"]>[2]): void;
+    /**
+     * A blip on their radar: on a spot (with the game's cylinder marker), or
+     * on a ped, vehicle or player (an arrow over them), following it.
+     */
+    blip(target: Vector3 | Ped | Vehicle | Player, options?: BlipOptions): Blip;
+    /**
+     * The objective, at the bottom of their screen in the game's mission text
+     * style, for `ms` (default: about as long as reading it takes; `Infinity`:
+     * until replaced or cleared).
+     */
+    objective(text: string, ms?: number): void;
+    /**
+     * The game's help box, top left (its hints: "Press F to ..."), for `ms`
+     * (default: about as long as reading it takes; `Infinity`: until replaced
+     * or cleared). Game codes and `gxt()` work. An interaction's prompt shows
+     * over it while one's in reach.
+     */
+    help(text: string, ms?: number): void;
+    /** Clears the help box. */
+    clearHelp(): void;
+    /** Clears the objective. */
+    clearObjective(): void;
+    /**
+     * A notice in the middle of their screen, as the game's garages and
+     * shops give ("New engine and paint job: $100"), for `ms` (default 4000).
+     * Game codes and `gxt()` work.
+     */
+    notice(text: string, ms?: number): void;
+    /**
+     * The game's own big text, in one of its seven styles, as SA-MP's
+     * GameTextForPlayer (the same numbers): 0 big in the middle (mission
+     * passed), 1 bottom right (the time, money), 2 white in the middle,
+     * 3 smaller in the middle, 4 smaller, a bit higher, 5 small white in the
+     * middle, 6 light blue at the top. Game codes (`~r~`, `~n~`...) and
+     * `gxt()` work. `ms` default 3000.
+     *
+     * ```ts
+     * player.hud.gameText("~g~Welcome~n~~w~to Los Santos", 3000, GameTextStyle.Middle);
+     * ```
+     */
+    gameText(text: string, ms?: number, style?: number): void;
+    /** Big text in the middle of their screen, for `ms`. */
+    bigText(text: string, ms?: number): void;
+    /** A counter under their money: `label  value` (`value/max` with `max`), or a bar. */
+    counter(label: string, options?: {
+        value?: number;
+        max?: number;
+        bar?: boolean;
+        color?: MapColor;
+    }): HudCounter;
+    /** A timer under their money, counting down from `ms` (or up from it, `countUp`). */
+    timer(label: string, ms: number, options?: {
+        countUp?: boolean;
+        color?: MapColor;
+    }): HudCounter;
+    /** "MISSION PASSED!" with the game's tune, and `subtitle` under it (the reward: "$2500"). */
+    missionPassed(subtitle?: string): void;
+    /** "MISSION FAILED!", and `subtitle` under it (why). */
+    missionFailed(subtitle?: string): void;
+    /** A result screen of your own: `title` ("1st place!"), and `subtitle` under it. */
+    missionResult(title: string, subtitle?: string): void;
+}