gtac-types 0.0.1

package/src/types/client/functions.d.ts

@@ -0,0 +1,715 @@
+/**
+ * GTAC Client-Side Function Declarations
+ *
+ * Defines all client-side global functions and interfaces available in the
+ * GTA Connected client runtime. Includes player queries, element management,
+ * GUI creation, audio playback, font rendering, key binding, command handlers,
+ * file I/O, network events, and the `lucasFont` rendering API.
+ *
+ * All declarations are global — no import required.
+ *
+ * @module types/client/functions
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Get the local player and print their name
+ * console.log("I am: " + localPlayer.name);
+ *
+ * @example
+ * // Create a GUI window
+ * const window = gui.createWindow("My Window");
+ * window.visible = true;
+ * window.size = new Vec2(400, 300);
+ */
+
+// ===== Player & Client References =====
+
+/**
+ * Reference to the local player element controlled by this client.
+ * This is the player character the user sees and controls.
+ *
+ * @example
+ * localPlayer.health = 100;
+ * localPlayer.giveWeapon(22, 50, true);
+ */
+declare var localPlayer: Player;
+
+/**
+ * Reference to this client's own `Client` object.
+ * Use this for local client identification in network events.
+ */
+declare var localClient: Client;
+
+// ===== Client Queries =====
+
+/**
+ * Returns all connected `Client` objects (including `localClient`).
+ *
+ * @returns Array of all `Client` instances currently connected to the server.
+ */
+declare function getClients(): Client[];
+
+/**
+ * Finds a client by their display name.
+ *
+ * @param name - The client's display name to search for.
+ * @returns The matching `Client`, or `null` if no client has that name.
+ */
+declare function getClient(name: string): Client | null;
+
+/**
+ * Gets the `Client` associated with a specific `Player` element.
+ *
+ * @param player - The `Player` element to look up.
+ * @returns The `Client` controlling that player.
+ */
+declare function getClientFromPlayerElement(player: Player): Client;
+
+// ===== Element Counting & Querying =====
+
+/** Returns the total number of `Player` elements on the server. */
+declare function getPlayerCount(): number;
+
+/** Returns all `Player` elements. @returns Array of `Player`. */
+declare function getPlayers(): Player[];
+
+/** Returns all `Vehicle` elements. @returns Array of `Vehicle`. */
+declare function getVehicles(): Vehicle[];
+
+/** Returns the total number of `Vehicle` elements. */
+declare function getVehicleCount(): number;
+
+/** Returns all `Ped` elements. @returns Array of `Ped`. */
+declare function getPeds(): Ped[];
+
+/** Returns the total number of `Ped` elements. */
+declare function getPedCount(): number;
+
+/** Returns all `Blip` elements. @returns Array of `Blip`. */
+declare function getBlips(): Blip[];
+
+/** Returns the total number of `Blip` elements. */
+declare function getBlipCount(): number;
+
+/** Returns all `Pickup` elements. @returns Array of `Pickup`. */
+declare function getPickups(): Pickup[];
+
+/** Returns the total number of `Pickup` elements. */
+declare function getPickupCount(): number;
+
+/** Returns all `Object` elements. @returns Array of `Object`. */
+declare function getObjects(): Object[];
+
+/** Returns the total number of `Object` elements. */
+declare function getObjectCount(): number;
+
+/** Returns all `Building` elements. @returns Array of `Building`. */
+declare function getBuildings(): Building[];
+
+/** Returns the total number of `Building` elements. */
+declare function getBuildingCount(): number;
+
+/**
+ * Gets all elements matching a given type string.
+ *
+ * @param type - The element type string (e.g. `"player"`, `"vehicle"`, `"blip"`).
+ * @returns Array of `Element` of the specified type.
+ */
+declare function getElementsByType(type: string): Element[];
+
+/**
+ * Finds an element by its numeric ID.
+ *
+ * @param id - The element's unique ID.
+ * @returns The matching `Element`, or `null` if no element has that ID.
+ */
+declare function getElementFromId(id: number): Element | null;
+
+/**
+ * Finds an element by its display name.
+ *
+ * @param name - The element name to search for.
+ * @returns The matching `Element`, or `null` if no element has that name.
+ */
+declare function getElementFromName(name: string): Element | null;
+
+// ===== Element Management =====
+
+/**
+ * Destroys an element, removing it from the game world.
+ * Safely accepts `null` — passing `null` is a no-op, which supports guarded
+ * destruction patterns without null checks.
+ *
+ * @param element - The element to destroy, or `null` (no-op).
+ *
+ * @example
+ * // Safe destruction pattern
+ * destroyElement(myBlip); // works
+ * destroyElement(null);   // no error, no-op
+ *
+ * @example
+ * // Guarded destruction
+ * const blip = gta.createBlip(pos, 0);
+ * destroyElement(blip);
+ * destroyElement(blip); // safe — blip is already destroyed but no crash
+ */
+declare function destroyElement(element: Element | null): void;
+
+/**
+ * Cancels the current event within an event handler.
+ * Equivalent to calling `event.preventDefault()` on a `CancellableEvent`,
+ * but usable from any event handler context without explicit event access.
+ */
+declare function cancelEvent(): void;
+
+/**
+ * Displays a message in the game's chat window or on-screen messaging area.
+ *
+ * @param text - The message text to display.
+ */
+declare function message(text: string): void;
+
+/**
+ * Returns the current screen resolution as a 2D vector.
+ *
+ * @returns A `Vec2` where `x` = screen width in pixels, `y` = screen height in pixels.
+ */
+declare function getScreenResolution(): Vec2;
+
+/**
+ * Converts individual RGBA components into a single packed colour number.
+ *
+ * @param r - Red component (0–255).
+ * @param g - Green component (0–255).
+ * @param b - Blue component (0–255).
+ * @param a - Alpha component (0–255, where 0 = fully transparent, 255 = fully opaque).
+ * @returns A single packed colour number (format: ARGB).
+ */
+declare function toColour(r: number, g: number, b: number, a: number): number;
+
+/**
+ * Constant identifying the current game as GTA Vice City.
+ * Used for runtime game-type checks to determine which game is running.
+ */
+declare var GAME_GTA_VC: number;
+
+// ===== File I/O =====
+
+/**
+ * Opens a file and returns an object with `read()` and `close()` methods.
+ * Simplified file API for quick reading without the full FileObject workflow.
+ *
+ * @param path - File path (relative to resource root).
+ * @returns An object with `read` and `close` methods, or `null` if the file cannot be opened.
+ *
+ * @example
+ * const file = openFile("config.txt");
+ * if (file) {
+ *     const content = file.read();
+ *     console.log(content);
+ *     file.close();
+ * }
+ */
+declare function openFile(path: string): {
+    read(size?: number): string;
+    close(): void;
+} | null;
+
+/** Checks if a file exists on disk. @param path - File path. @returns `true` if the file exists. */
+declare function fileExists(path: string): boolean;
+
+/** Opens a file for reading/writing. @param path - File path. @returns `FileObject` handle or `null` on failure. */
+declare function fileOpen(path: string): FileObject | null;
+
+/** Closes an open file. @param file - The `FileObject` to close. */
+declare function fileClose(file: FileObject): void;
+
+/** Reads the entire content of an open file. @param file - The `FileObject` to read from. @returns File content as a string. */
+declare function fileRead(file: FileObject): string;
+
+/** Writes data to an open file. @param file - The `FileObject` to write to. @param data - The string data to write. */
+declare function fileWrite(file: FileObject, data: string): void;
+
+/** Deletes a file from disk. @param path - File path. @returns `true` on success, `false` on failure. */
+declare function fileDelete(path: string): boolean;
+
+/** Gets the size of an open file in bytes. @param file - The `FileObject`. @returns File size in bytes. */
+declare function fileGetSize(file: FileObject): number;
+
+/** Gets the absolute path of an open file. @param file - The `FileObject`. @returns The absolute file path string. */
+declare function fileGetPath(file: FileObject): string;
+
+// ===== Key Binding =====
+
+/**
+ * Binds a key to a handler function. The handler receives a `KeyEvent`
+ * with information about press/release and the key code.
+ *
+ * @param key - The key name to bind (e.g. `"F1"`, `"Escape"`, `"T"`).
+ * @param handler - Callback invoked with a `KeyEvent` when the key is pressed or released.
+ *
+ * @example
+ * bindKey("F5", function(event) {
+ *     if (!event.isUp()) {
+ *         message("F5 pressed!");
+ *     }
+ * });
+ */
+declare function bindKey(
+    key: string,
+    handler: (keyEvent: KeyEvent) => void
+): void;
+
+/**
+ * Unbinds a previously bound key, removing its handler.
+ *
+ * @param key - The key name to unbind.
+ */
+declare function unbindKey(key: string): void;
+
+// ===== Command Handlers =====
+
+/**
+ * Registers a handler for a chat command (e.g. `/help`).
+ * The handler is invoked when a player types the command in chat.
+ *
+ * @param name - Command name without the leading slash (e.g. `"help"`).
+ * @param handler - Callback receiving the command name and the full text after the command.
+ *
+ * @example
+ * addCommandHandler("heal", function(cmd, text) {
+ *     localPlayer.health = 100;
+ *     message("You have been healed!");
+ * });
+ */
+declare function addCommandHandler(
+    name: string,
+    handler: (cmd: string, text: string) => void
+): void;
+
+/** Checks whether a command handler exists for the given command name. @param name - Command name. @returns `true` if registered. */
+declare function hasCommandHandler(name: string): boolean;
+
+/** Removes a previously registered command handler. @param name - Command name to remove. */
+declare function removeCommandHandler(name: string): void;
+
+// ===== Network Events =====
+
+/**
+ * Registers a handler for a custom network event triggered by the server.
+ *
+ * @param name - The network event name to listen for.
+ * @param handler - Callback receiving any number of arguments from the server.
+ *
+ * @example
+ * addNetworkHandler("onWeatherChange", function(weatherId) {
+ *     gta.setWeather(weatherId);
+ * });
+ */
+declare function addNetworkHandler(
+    name: string,
+    handler: (...args: any[]) => void
+): void;
+
+/**
+ * Sends a custom network event to the server.
+ *
+ * @param name - The network event name.
+ * @param args - Any number of arguments to send with the event.
+ *
+ * @example
+ * triggerNetworkEvent("onPlayerReady", localPlayer.name);
+ */
+declare function triggerNetworkEvent(name: string, ...args: any[]): void;
+
+/**
+ * Removes a previously registered network event handler.
+ *
+ * @param name - The network event name.
+ * @param handler - The handler function to remove (must be the same function reference).
+ */
+declare function removeNetworkHandler(
+    name: string,
+    handler: (...args: any[]) => void
+): void;
+
+// ===== Chat =====
+
+/** Enables or disables the chat input box. @param enabled - `true` to show, `false` to hide. */
+declare function chatInputEnabled(enabled: boolean): void;
+
+/** Enables or disables the chat window (message display area). @param enabled - `true` to show, `false` to hide. */
+declare function chatWindowEnabled(enabled: boolean): void;
+
+/** Alias for `chatWindowEnabled`. Enables or disables the chat window display. */
+declare function setChatWindowEnabled(enabled: boolean): void;
+
+// ===== Screen =====
+
+/**
+ * Screen dimension information and utility.
+ */
+declare var screen: {
+    /** Screen width in pixels. */
+    width: number;
+    /** Screen height in pixels. */
+    height: number;
+    /** Returns the current screen dimensions. @returns Object with `width` and `height`. */
+    getSize(): { width: number; height: number };
+};
+
+// ===== Audio =====
+
+/**
+ * Represents a playable sound instance.
+ * Sounds can be created from local files or URLs and support playback control
+ * (play, pause, stop, seek, volume, loop).
+ */
+interface Sound {
+    /** Starts or resumes playback of the sound. */
+    play(): void;
+    /** Pauses playback. Can be resumed with `play()`. */
+    pause(): void;
+    /** Stops playback and resets position to the beginning. */
+    stop(): void;
+    /** Sets the volume level. @param vol - Volume (0.0 = mute, 1.0 = full). */
+    setVolume(vol: number): void;
+    /** Gets the current volume level. @returns Volume (0.0 to 1.0). */
+    getVolume(): number;
+    /** Sets the playback position. @param pos - Position in seconds. */
+    setPosition(pos: number): void;
+    /** Gets the current playback position. @returns Position in seconds. */
+    getPosition(): number;
+    /** Enables or disables looping. @param loop - `true` to loop the sound. */
+    setLooping(loop: boolean): void;
+    /** Checks if the sound is set to loop. @returns `true` if looping. */
+    isLooping(): boolean;
+    /** Checks if the sound is currently playing. @returns `true` if playing. */
+    isPlaying(): boolean;
+    /** Stops and permanently destroys the sound instance, freeing memory and resources. */
+    destroy(): void;
+}
+
+/**
+ * Audio creation and management API.
+ * Use this to create sound instances from local files or remote URLs.
+ *
+ * @example
+ * // Create and play a looping background music
+ * const bgm = audio.createSound("music/main_theme.ogg");
+ * bgm.setLooping(true);
+ * bgm.setVolume(0.5);
+ * bgm.play();
+ */
+declare var audio: {
+    /**
+     * Creates a sound from a local file path.
+     * @param path - Path to the audio file (relative to resource root).
+     * @returns A new `Sound` instance.
+     */
+    createSound(path: string): Sound;
+    /**
+     * Creates a sound from a remote URL (downloads and plays the file).
+     * @param url - The URL of the audio file to download.
+     * @returns A new `Sound` instance.
+     */
+    createSoundFromURL(url: string): Sound;
+};
+
+// ===== Font =====
+
+/**
+ * Represents a loaded font object for text rendering.
+ * Created via `font.create()` with a family name, size, and optional bold/italic styles.
+ */
+interface FontObject {
+    /** Font family name (e.g. "Arial", "Tahoma"). */
+    name: string;
+    /** Font size in points. */
+    size: number;
+    /** Whether the font weight is bold. */
+    bold: boolean;
+    /** Whether the font style is italic. */
+    italic: boolean;
+}
+
+/**
+ * Font creation API for loading and using fonts.
+ *
+ * @example
+ * const titleFont = font.create("Arial", 24, true, false);
+ */
+declare var font: {
+    /**
+     * Creates a new font object with the specified properties.
+     *
+     * @param name - Font family name (e.g. `"Arial"`, `"Tahoma"`).
+     * @param size - Font size in points.
+     * @param bold - Whether the font should be bold weight (optional, default `false`).
+     * @param italic - Whether the font should be italic style (optional, default `false`).
+     * @returns A new `FontObject` instance.
+     */
+    create(
+        name: string,
+        size: number,
+        bold?: boolean,
+        italic?: boolean
+    ): FontObject;
+};
+
+// ===== GUI =====
+
+/**
+ * Base GUI element representing any UI component (label, button, window, etc.).
+ * GUI elements are positioned in screen space and have visual properties
+ * (colour, opacity, border, size) plus a generic key/value property store.
+ */
+interface GUIElement {
+    /** Whether the element is visible on screen. */
+    visible: boolean;
+    /** Screen position of the element as a `Vec2` (x, y in pixels). */
+    position: Vec2;
+    /** Dimensions of the element as a `Vec2` (width, height in pixels). */
+    size: Vec2;
+    /** Text content displayed in the element. */
+    text: string;
+    /** Font name used for text rendering within this element. */
+    font: string;
+    /** Text colour as an RGBA tuple (0–255 each component). */
+    color: RGBA;
+    /** Background fill colour as an RGBA tuple. */
+    backgroundColor: RGBA;
+    /** Border stroke colour as an RGBA tuple. */
+    borderColor: RGBA;
+    /** Border stroke width in pixels. */
+    borderWidth: number;
+    /** Border corner radius in pixels (0 = sharp square corners). */
+    borderRadius: number;
+    /** Opacity of the element (0.0 = fully transparent, 1.0 = fully opaque). */
+    opacity: number;
+    /** Z-index controlling draw order (higher values render on top). */
+    zIndex: number;
+    /**
+     * Sets a custom property on the GUI element (generic key/value store).
+     * @param name - Property name to set.
+     * @param value - Property value (any type).
+     */
+    setProperty(name: string, value: any): void;
+    /**
+     * Gets a custom property value from the GUI element.
+     * @param name - Property name to retrieve.
+     * @returns The stored value, or `undefined` if not set.
+     */
+    getProperty(name: string): any;
+}
+
+/**
+ * A GUI element capable of rendering HTML content.
+ * Extends `GUIElement` with HTML/URL properties and the ability to
+ * execute JavaScript within the embedded HTML view.
+ */
+interface GUIHtmlElement extends GUIElement {
+    /** Raw HTML content string to display inline. */
+    html: string;
+    /** URL to load HTML content from. */
+    url: string;
+    /** Reloads the HTML content from the URL. */
+    reload(): void;
+    /**
+     * Executes JavaScript code within the context of the embedded HTML view/iframe.
+     * @param code - JavaScript code string to execute.
+     */
+    executeJavaScript(code: string): void;
+}
+
+/**
+ * A dedicated HTML view container for displaying web content.
+ * Similar to `GUIHtmlElement` but intended as a standalone viewport
+ * rather than an embedded element.
+ */
+interface GUIHtmlView {
+    /** Raw HTML content string to display. */
+    html: string;
+    /** URL to load HTML content from. */
+    url: string;
+    /** Reloads the HTML content from the URL. */
+    reload(): void;
+    /**
+     * Executes JavaScript code within the context of the HTML view.
+     * @param code - JavaScript code string to execute.
+     */
+    executeJavaScript(code: string): void;
+}
+
+/**
+ * A GUI page grouping multiple elements together.
+ * Pages allow organizing elements into logical screens that can be
+ * shown or hidden as a single unit.
+ */
+interface GUIPage {
+    /** Page title (optional, for display purposes). */
+    title: string;
+    /** Array of all `GUIElement` instances belonging to this page. */
+    elements: GUIElement[];
+    /**
+     * Adds an element to this page.
+     * @param el - The `GUIElement` to add to the page.
+     */
+    addElement(el: GUIElement): void;
+    /**
+     * Removes an element from this page.
+     * @param el - The `GUIElement` to remove from the page.
+     */
+    removeElement(el: GUIElement): void;
+}
+
+/**
+ * A resizable, movable GUI window with a title bar and standard window controls.
+ * Extends `GUIElement` with window-specific behaviour: resize handles,
+ * title bar dragging, close/minimize/maximize buttons.
+ */
+interface GUIWindow extends GUIElement {
+    /** Window title displayed in the title bar. */
+    title: string;
+    /** Whether the user can resize the window by dragging its edges/corners. */
+    resizable: boolean;
+    /** Whether the user can move the window by dragging its title bar. */
+    movable: boolean;
+    /** Whether the window displays a close (X) button. */
+    closable: boolean;
+    /** Whether the window displays a minimize button. */
+    minimizable: boolean;
+    /** Whether the window displays a maximize button. */
+    maximizable: boolean;
+}
+
+/**
+ * GUI creation and management API.
+ * Provides factory methods for creating GUI elements, windows, pages,
+ * HTML views, and controlling cursor visibility.
+ *
+ * @example
+ * // Create a simple label
+ * const label = gui.createElement("label");
+ * label.text = "Hello World";
+ * label.position = new Vec2(100, 100);
+ * label.visible = true;
+ *
+ * @example
+ * // Create and configure a window
+ * const win = gui.createWindow("Settings");
+ * win.size = new Vec2(400, 300);
+ * win.movable = true;
+ * win.visible = true;
+ */
+declare var gui: {
+    /**
+     * Creates a new GUI element of the specified type.
+     * @param type - Element type string (e.g. `"label"`, `"button"`, `"edit"`).
+     * @returns A new `GUIElement` instance.
+     */
+    createElement(type: string): GUIElement;
+    /**
+     * Creates a GUI element that renders HTML content from a URL.
+     * @param url - URL of the HTML content to load.
+     * @returns A new `GUIHtmlElement` instance.
+     */
+    createHtmlElement(url: string): GUIHtmlElement;
+    /**
+     * Creates a dedicated HTML viewport from a URL.
+     * @param url - URL of the HTML content to load.
+     * @returns A new `GUIHtmlView` instance.
+     */
+    createHtmlView(url: string): GUIHtmlView;
+    /**
+     * Creates a new GUI page for grouping elements.
+     * @returns A new `GUIPage` instance.
+     */
+    createPage(): GUIPage;
+    /**
+     * Creates a new GUI window with the given title.
+     * @param title - Window title text.
+     * @returns A new `GUIWindow` instance.
+     */
+    createWindow(title: string): GUIWindow;
+    /**
+     * Shows or hides the mouse cursor.
+     * @param visible - `true` to show the cursor, `false` to hide it.
+     */
+    setCursorVisible(visible: boolean): void;
+    /**
+     * Checks whether the mouse cursor is currently visible.
+     * @returns `true` if the cursor is visible, `false` if hidden.
+     */
+    isCursorVisible(): boolean;
+};
+
+// ===== Lucas Font =====
+
+/**
+ * LucasFont — a custom bitmap font renderer.
+ * Provides low-level text measurement and rendering using a Lucas font stream.
+ * Use `lucasFont.createFont()` to create instances from a data stream.
+ */
+interface LucasFont {
+    /**
+     * Measures the dimensions of a character string rendered with this font.
+     * @param char - The character or string to measure.
+     * @param arg1 - Unknown parameter (engine-specific).
+     * @param arg2 - Unknown parameter (engine-specific).
+     * @param arg3 - Unknown parameter (engine-specific).
+     * @param size - Font size for measurement.
+     * @returns A `Vec2` containing the width and height of the rendered text.
+     */
+    measure(
+        char: string,
+        arg1: number,
+        arg2: number,
+        arg3: number,
+        size: number
+    ): Vec2;
+    /**
+     * Renders a character or string at a screen position.
+     * @param char - The character or string to render.
+     * @param position - Screen position as a `Vec2`.
+     * @param arg3 - Unknown parameter (engine-specific).
+     * @param arg4 - Unknown parameter (engine-specific).
+     * @param arg5 - Unknown parameter (engine-specific).
+     * @param size - Font size for rendering.
+     * @param colour - Packed colour number (ARGB format).
+     */
+    render(
+        char: string,
+        position: Vec2,
+        arg3: number,
+        arg4: number,
+        arg5: number,
+        size: number,
+        colour: number
+    ): void;
+}
+
+/**
+ * Font type alias — `LucasFont` is the primary font implementation.
+ */
+type Font = LucasFont;
+
+/**
+ * LucasFont creation API.
+ * Provides a factory method for creating `LucasFont` instances from
+ * font data streams.
+ *
+ * @example
+ * // Create and use a Lucas font
+ * const lf = lucasFont.createFont(fontStream, 16);
+ * lf.render("Hello", new Vec2(100, 100), 0, 0, 0, 16, 0xFFFFFFFF);
+ */
+declare var lucasFont: {
+    /**
+     * Creates a new `LucasFont` instance from a font data stream.
+     * @param stream - Font data stream (binary font file data).
+     * @param size - Default font size for rendering.
+     * @returns A new `LucasFont` instance.
+     */
+    createFont(stream: unknown, size: number): LucasFont;
+};