gtac-types 0.0.1

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

@@ -0,0 +1,144 @@
+/**
+ * GTAC Client Connection Type (Server-Side)
+ *
+ * Defines the `Client` interface used server-side to represent a connected
+ * player's network session. Each connected player has a `Client` object
+ * with properties for identification (name, IP, ping, game version),
+ * permissions (admin, console access), and methods for data storage,
+ * player management, and disconnection.
+ *
+ * All declarations are global — no import required.
+ *
+ * @module types/server/client
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Handle a new player connecting
+ * addEventHandler("OnPlayerConnect", function(client) {
+ *     console.log(client.name + " connected from " + client.ip);
+ *     client.setData("joinTime", Date.now());
+ * });
+ */
+
+/**
+ * Represents a network client connection (a connected player).
+ *
+ * The `Client` interface provides access to connection metadata (IP, ping,
+ * game version), permissions (admin, console), and associated player element.
+ * Custom data can be stored on the client using `setData()`/`getData()`,
+ * which persists for the lifetime of the connection.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+interface Client {
+    /**
+     * Whether this client has server administrator privileges.
+     * Admin clients can execute server commands and have elevated permissions.
+     */
+    administrator: boolean;
+
+    /**
+     * Whether this client has access to the server console.
+     * Console access allows viewing logs and running console commands.
+     */
+    console: boolean;
+
+    /**
+     * Game identifier string indicating which game the client connected with.
+     * Example values: `"gta:vc"`, `"gta:iii"`, `"gta:sa"`.
+     */
+    game: string;
+
+    /**
+     * Full game version string reported by the client (e.g. `"1.0.0"`).
+     */
+    gameVersion: string;
+
+    /**
+     * Numeric client index assigned by the server.
+     * Unique identifier for this connection within the current server instance.
+     */
+    index: number;
+
+    /**
+     * Client's IP address as a string (e.g. `"192.168.1.100"`).
+     */
+    ip: string;
+
+    /**
+     * Client's display name.
+     * This is the name shown in chat and player lists.
+     */
+    name: string;
+
+    /**
+     * Client's current network latency/ping in milliseconds.
+     * Higher values indicate a slower connection.
+     */
+    ping: number;
+
+    /**
+     * The `Player` element associated with this client, or `null` if the
+     * client has not yet spawned a player character.
+     */
+    player: Player | null;
+
+    /**
+     * The camera interior ID for this client's view.
+     * 0 = exterior/world, other values = specific interiors.
+     */
+    cameraInterior: number;
+
+    /**
+     * Retrieves a custom data value previously stored on this client.
+     * Data is dynamically typed (SpiderMonkey engine) and persists until
+     * the client disconnects or the key is removed.
+     *
+     * @param key - The string key identifying the stored data.
+     * @returns The stored value, or `undefined` if no data exists for the key.
+     *
+     * @example
+     * const joinTime = client.getData("joinTime");
+     * console.log("Player joined at: " + new Date(joinTime));
+     */
+    getData(key: string): any;
+
+    /**
+     * Stores a custom data value on this client.
+     * The data persists until removed or until the client disconnects.
+     *
+     * @param key - The string key to store the data under.
+     * @param value - Any value to store (number, string, object, array, etc.).
+     *
+     * @example
+     * client.setData("score", 100);
+     * client.setData("lastAction", "jump");
+     */
+    setData(key: string, value: any): void;
+
+    /**
+     * Removes a custom data key and its associated value from this client.
+     *
+     * @param key - The string key to remove.
+     */
+    removeData(key: string): void;
+
+    /**
+     * Despawns the client's player, removing them from the world visually
+     * but keeping the connection alive. The player can be respawned later.
+     */
+    despawnPlayer(): void;
+
+    /**
+     * Disconnects the client from the server.
+     * The connection is terminated and the player element is destroyed.
+     *
+     * @example
+     * // Kick an abusive player
+     * if (isAbusive(client)) {
+     *     messageClient("You have been kicked.", client, COLOUR_RED);
+     *     client.disconnect();
+     * }
+     */
+    disconnect(): void;
+}

package/src/types/server/events.d.ts

@@ -0,0 +1,407 @@
+/**
+ * GTAC Server-Side Event Handler Declarations
+ *
+ * Defines typed overloads for `addEventHandler()` for all server-side events
+ * dispatched by the GTA Connected server engine. Each overload specifies the
+ * exact handler signature for a given event name, providing type safety and
+ * auto-completion for server event-driven code.
+ *
+ * Events cover: element lifecycle (destroy, stream in/out), ped actions
+ * (crouch, uncrouch, enter/exit vehicle, fall, jump, spawn, wasted),
+ * pickup collection, player chat/commands, client connection lifecycle
+ * (connect, join, joined, quit), server ticks (OnProcess), resource
+ * lifecycle (start, stop), server startup, and deprecated IV-only events.
+ * Generic fallback overloads handle custom/unknown events.
+ *
+ * All declarations are global — no import required.
+ *
+ * @module types/server/events
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Handle player chat messages
+ * addEventHandler("OnPlayerChat", function(client, text) {
+ *     console.log(client.name + ": " + text);
+ * });
+ *
+ * @example
+ * // Run code every server tick
+ * addEventHandler("OnProcess", function() {
+ *     // Update game state...
+ * });
+ */
+
+// ===== Element Events =====
+
+/**
+ * Fired when any element is destroyed on the server.
+ * Use this to clean up associated data or trigger effects.
+ *
+ * @param name - `"OnElementDestroy"`
+ * @param handler - Callback receiving the destroyed `Element`.
+ */
+declare function addEventHandler(
+    name: "OnElementDestroy",
+    handler: (element: Element) => void
+): void;
+
+/**
+ * Fired when an element streams in for a specific client.
+ * Use this to send client-specific data or trigger effects when
+ * an element becomes visible to a player.
+ *
+ * @param name - `"OnElementStreamIn"`
+ * @param handler - Callback receiving the streamed-in `Element`.
+ */
+declare function addEventHandler(
+    name: "OnElementStreamIn",
+    handler: (element: Element) => void
+): void;
+
+/**
+ * Fired when an element streams out for a specific client.
+ * Use this to clean up client-specific state when an element is
+ * no longer relevant to a player.
+ *
+ * @param name - `"OnElementStreamOut"`
+ * @param handler - Callback receiving the streamed-out `Element`.
+ */
+declare function addEventHandler(
+    name: "OnElementStreamOut",
+    handler: (element: Element) => void
+): void;
+
+// ===== Ped Events =====
+
+/**
+ * Fired when a ped crouches.
+ *
+ * @param name - `"OnPedCrouch"`
+ * @param handler - Callback receiving the `Ped` that crouched.
+ */
+declare function addEventHandler(
+    name: "OnPedCrouch",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped starts entering a vehicle (opening door, climbing in).
+ *
+ * @param name - `"OnPedEnterVehicle"`
+ * @param handler - Callback receiving the `Ped`, the `Vehicle`, and the target seat number.
+ */
+declare function addEventHandler(
+    name: "OnPedEnterVehicle",
+    handler: (ped: Ped, vehicle: Vehicle, seat: number) => void
+): void;
+
+/**
+ * Fired when a ped starts exiting a vehicle.
+ *
+ * @param name - `"OnPedExitVehicle"`
+ * @param handler - Callback receiving the `Ped` and the `Vehicle` being exited.
+ */
+declare function addEventHandler(
+    name: "OnPedExitVehicle",
+    handler: (ped: Ped, vehicle: Vehicle) => void
+): void;
+
+/**
+ * Fired when a ped falls (loses footing and hits the ground).
+ *
+ * @param name - `"OnPedFall"`
+ * @param handler - Callback receiving the fallen `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedFall",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped jumps.
+ *
+ * @param name - `"OnPedJump"`
+ * @param handler - Callback receiving the jumping `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedJump",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped spawns in the game world.
+ *
+ * @param name - `"OnPedSpawn"`
+ * @param handler - Callback receiving the spawned `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedSpawn",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped uncrouches (stands back up).
+ *
+ * @param name - `"OnPedUncrouch"`
+ * @param handler - Callback receiving the `Ped` that uncrouched.
+ */
+declare function addEventHandler(
+    name: "OnPedUncrouch",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped is wasted (killed, reaches 0 health).
+ *
+ * @param name - `"OnPedWasted"`
+ * @param handler - Callback receiving the wasted `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedWasted",
+    handler: (ped: Ped) => void
+): void;
+
+// ===== Pickup Events =====
+
+/**
+ * Fired when a pickup is collected by a player.
+ *
+ * @param name - `"OnPickupCollected"`
+ * @param handler - Callback receiving the collected `Pickup` and the `Player` who collected it.
+ */
+declare function addEventHandler(
+    name: "OnPickupCollected",
+    handler: (pickup: Pickup, player: Player) => void
+): void;
+
+// ===== Player Events =====
+
+/**
+ * Fired when a player sends a chat message.
+ *
+ * @param name - `"OnPlayerChat"`
+ * @param handler - Callback receiving the sending `Client` and the chat text string.
+ *
+ * @example
+ * addEventHandler("OnPlayerChat", function(client, text) {
+ *     message(client.name + ": " + text);
+ * });
+ */
+declare function addEventHandler(
+    name: "OnPlayerChat",
+    handler: (client: Client, text: string) => void
+): void;
+
+/**
+ * Fired when a player sends a command (e.g. /help, /kill).
+ * Note: use `addCommandHandler()` for a more convenient command API.
+ *
+ * @param name - `"OnPlayerCommand"`
+ * @param handler - Callback receiving the `Client`, the command name, and arguments string.
+ */
+declare function addEventHandler(
+    name: "OnPlayerCommand",
+    handler: (client: Client, cmd: string, args: string) => void
+): void;
+
+/**
+ * Fired when a client establishes a connection to the server (before joining).
+ * Use this for authentication or pre-join checks.
+ *
+ * @param name - `"OnPlayerConnect"`
+ * @param handler - Callback receiving the connecting `Client`.
+ *
+ * @example
+ * addEventHandler("OnPlayerConnect", function(client) {
+ *     console.log(client.name + " is connecting...");
+ *     client.setData("connectTime", Date.now());
+ * });
+ */
+declare function addEventHandler(
+    name: "OnPlayerConnect",
+    handler: (client: Client) => void
+): void;
+
+/**
+ * Fired when a client has completed the join process and is fully in-game.
+ * This is the standard event for initializing a player's state.
+ *
+ * @param name - `"OnPlayerJoin"`
+ * @param handler - Callback receiving the joined `Client`.
+ */
+declare function addEventHandler(
+    name: "OnPlayerJoin",
+    handler: (client: Client) => void
+): void;
+
+/**
+ * Fired when a client has joined. Similar to `OnPlayerJoin` but the handler
+ * also receives the event name as the first argument.
+ *
+ * @param name - `"OnPlayerJoined"`
+ * @param handler - Callback receiving the event name string and the `Client`.
+ */
+declare function addEventHandler(
+    name: "OnPlayerJoined",
+    handler: (event: string, client: Client) => void
+): void;
+
+/**
+ * Fired when a player quits or disconnects from the server.
+ * Use this to clean up the player's state, save data, and broadcast departure.
+ *
+ * @param name - `"OnPlayerQuit"`
+ * @param handler - Callback receiving the event name and the `Client` who quit.
+ *
+ * @example
+ * addEventHandler("OnPlayerQuit", function(event, client) {
+ *     message(client.name + " has left the server.");
+ * });
+ */
+declare function addEventHandler(
+    name: "OnPlayerQuit",
+    handler: (event: string, client: Client) => void
+): void;
+
+// ===== Process Event =====
+
+/**
+ * Fired every server tick (frame). This is the main server update loop.
+ * Use this for continuous game logic: AI updates, position checks, timer logic.
+ * Be mindful of performance — avoid heavy operations in the OnProcess handler.
+ *
+ * @param name - `"OnProcess"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnProcess",
+    handler: () => void
+): void;
+
+// ===== Resource Events =====
+
+/**
+ * Fired when a resource starts running.
+ * This includes the current resource when the server starts.
+ *
+ * @param name - `"OnResourceStart"`
+ * @param handler - Callback receiving the started `Resource`.
+ */
+declare function addEventHandler(
+    name: "OnResourceStart",
+    handler: (resource: Resource) => void
+): void;
+
+/**
+ * Fired when a resource stops running.
+ * Use this to clean up any elements or state created by the resource.
+ *
+ * @param name - `"OnResourceStop"`
+ * @param handler - Callback receiving the stopped `Resource`.
+ */
+declare function addEventHandler(
+    name: "OnResourceStop",
+    handler: (resource: Resource) => void
+): void;
+
+// ===== Server Event =====
+
+/**
+ * Fired when the server starts up.
+ * Use this to initialize global state, load configuration, and start
+ * background processes.
+ *
+ * @param name - `"OnServerStart"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnServerStart",
+    handler: () => void
+): void;
+
+// ===== Deprecated IV Events =====
+
+/**
+ * **Deprecated:** GTA IV only! Fired when an IV network event is added.
+ * Not usable with GTA Vice City.
+ *
+ * @param name - `"OnAddIVNetworkEvent"`
+ * @param handler - Callback receiving variadic arguments.
+ * @deprecated This event is for GTA IV only and has no effect in GTA VC.
+ */
+declare function addEventHandler(
+    name: "OnAddIVNetworkEvent",
+    handler: (...args: any[]) => void
+): void;
+
+/**
+ * **Deprecated:** GTA IV only! Fired on a session request.
+ * Not usable with GTA Vice City.
+ *
+ * @param name - `"OnRequestSession"`
+ * @param handler - Callback receiving variadic arguments.
+ * @deprecated This event is for GTA IV only and has no effect in GTA VC.
+ */
+declare function addEventHandler(
+    name: "OnRequestSession",
+    handler: (...args: any[]) => void
+): void;
+
+// ===== Generic Fallbacks =====
+
+/**
+ * Generic fallback: Registers a handler for any named server-side event
+ * where the handler receives the event name and a client as arguments.
+ *
+ * @param name - The event name.
+ * @param handler - Callback receiving the event name string and `Client`.
+ */
+declare function addEventHandler(
+    name: string,
+    handler: (event: string, client: Client) => void
+): void;
+
+/**
+ * Fully generic fallback: Registers a handler for any named server-side event
+ * with any number of variadic arguments.
+ *
+ * @param name - The event name.
+ * @param handler - Callback receiving any number and type of arguments.
+ */
+declare function addEventHandler(
+    name: string,
+    handler: (...args: any[]) => void
+): void;
+
+// ===== Event Unregistration =====
+
+/**
+ * Removes a previously registered event handler.
+ *
+ * @param name - The event name to stop listening to.
+ * @param handler - The exact handler function reference that was registered.
+ * Must be the same function object, not a copy or new closure.
+ *
+ * @example
+ * function onPlayerChat(client, text) { ... }
+ * addEventHandler("OnPlayerChat", onPlayerChat);
+ * // Later:
+ * removeEventHandler("OnPlayerChat", onPlayerChat);
+ */
+declare function removeEventHandler(
+    name: string,
+    handler: (...args: any[]) => void
+): void;
+
+// ===== Network Event Unregistration =====
+
+/**
+ * Removes a previously registered network event handler.
+ *
+ * @param name - The network event name.
+ * @param handler - The handler function to remove (must be the same reference).
+ */
+declare function removeNetworkHandler(
+    name: string,
+    handler: (...args: any[]) => void
+): void;