gtac-types 0.0.1

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

@@ -0,0 +1,809 @@
+/**
+ * GTAC Client-Specific Event Handler Declarations
+ *
+ * Defines typed overloads for `addEventHandler()`, `removeEventHandler()`, and
+ * `bindEventHandler()` for all client-side events dispatched by the GTA Connected
+ * engine. Each overload specifies the exact handler signature for a given event
+ * name, providing type safety and auto-completion for event-driven code.
+ *
+ * Events cover: camera processing, input (keyboard/mouse/cursor), element
+ * lifecycle (stream in/out, destroy), entity processing, GUI interactions,
+ * HUD rendering, ped actions (enter/exit vehicle, jump, crouch, weapon, death),
+ * pickup collection, vehicle explosions, resource lifecycle, and generic fallbacks.
+ *
+ * All declarations are global — no import required.
+ *
+ * @module types/client/events
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Listen for player key presses
+ * addEventHandler("OnKeyDown", function(key: number) {
+ *     console.log("Key pressed: " + key);
+ * });
+ *
+ * @example
+ * // Listen for ped entering a vehicle and check which seat
+ * addEventHandler("OnPedEnteredVehicle", function(ped, vehicle, seat) {
+ *     if (seat === 0) {
+ *         message(ped.name + " is now driving " + vehicle.name);
+ *     }
+ * });
+ */
+
+// ===== Camera Events =====
+
+/**
+ * Fired before the camera is processed each frame.
+ * Use this to override or adjust camera logic before the engine updates it.
+ *
+ * @param name - `"OnBeforeProcessCamera"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnBeforeProcessCamera",
+    handler: () => void
+): void;
+
+/**
+ * Fired each frame when the camera is processed.
+ * Use this to apply custom camera transformations.
+ *
+ * @param name - `"OnCameraProcess"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnCameraProcess",
+    handler: () => void
+): void;
+
+// ===== Chat Events =====
+
+/**
+ * Fired when a chat message is output to the chat window.
+ * Allows interception and modification of chat text before display.
+ *
+ * @param name - `"OnChatOutput"`
+ * @param handler - Callback receiving the chat text string.
+ */
+declare function addEventHandler(
+    name: "OnChatOutput",
+    handler: (text: string) => void
+): void;
+
+// ===== Cursor Events =====
+
+/**
+ * Fired when a mouse button is pressed down while the cursor is visible.
+ *
+ * @param name - `"OnCursorDown"`
+ * @param handler - Callback receiving the cursor (x, y) screen coordinates.
+ */
+declare function addEventHandler(
+    name: "OnCursorDown",
+    handler: (x: number, y: number) => void
+): void;
+
+/**
+ * Fired continuously when the cursor moves across the screen.
+ *
+ * @param name - `"OnCursorMove"`
+ * @param handler - Callback receiving the cursor (x, y) screen coordinates.
+ */
+declare function addEventHandler(
+    name: "OnCursorMove",
+    handler: (x: number, y: number) => void
+): void;
+
+/**
+ * Fired when a mouse button is released while the cursor is visible.
+ *
+ * @param name - `"OnCursorUp"`
+ * @param handler - Callback receiving the cursor (x, y) screen coordinates.
+ */
+declare function addEventHandler(
+    name: "OnCursorUp",
+    handler: (x: number, y: number) => void
+): void;
+
+// ===== Element Events =====
+
+/**
+ * Fired when any element is destroyed.
+ * Use this to clean up references or trigger effects when elements disappear.
+ *
+ * @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 (becomes visible/active) for the local client.
+ *
+ * @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 (unloads from memory) for the local client.
+ *
+ * @param name - `"OnElementStreamOut"`
+ * @param handler - Callback receiving the streamed-out `Element`.
+ */
+declare function addEventHandler(
+    name: "OnElementStreamOut",
+    handler: (element: Element) => void
+): void;
+
+// ===== Entity Events =====
+
+/**
+ * Fired each frame for every `Entity` being processed.
+ * Use for per-entity custom logic (but be mindful of performance with many entities).
+ *
+ * @param name - `"OnEntityProcess"`
+ * @param handler - Callback receiving the `Entity` being processed.
+ */
+declare function addEventHandler(
+    name: "OnEntityProcess",
+    handler: (entity: Entity) => void
+): void;
+
+// ===== Focus Events =====
+
+/**
+ * Fired when the game window gains focus (user clicks on it or alt-tabs back).
+ *
+ * @param name - `"OnFocus"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnFocus",
+    handler: () => void
+): void;
+
+/**
+ * Fired when the game window loses focus (user alt-tabs away or clicks outside).
+ *
+ * @param name - `"OnLostFocus"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnLostFocus",
+    handler: () => void
+): void;
+
+// ===== GUI Events =====
+
+/**
+ * Fired when an anchor (`<a>`) element in a GUI HTML view is clicked.
+ *
+ * @param name - `"OnGUIAnchorClick"`
+ * @param handler - Callback receiving the `GUIElement` that was clicked.
+ */
+declare function addEventHandler(
+    name: "OnGUIAnchorClick",
+    handler: (element: GUIElement) => void
+): void;
+
+/**
+ * Fired when any GUI element is clicked.
+ *
+ * @param name - `"OnGUIClick"`
+ * @param handler - Callback receiving the `GUIElement` that was clicked.
+ */
+declare function addEventHandler(
+    name: "OnGUIClick",
+    handler: (element: GUIElement) => void
+): void;
+
+// ===== HUD Events =====
+
+/**
+ * Fired before the game HUD (radar, health bar, ammo, etc.) is drawn.
+ * Use this to hide or modify HUD elements before they render.
+ *
+ * @param name - `"OnBeforeDrawHUD"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnBeforeDrawHUD",
+    handler: () => void
+): void;
+
+/**
+ * Fired while the game HUD is being drawn.
+ * Use this to overlay custom graphics on top of the standard HUD.
+ *
+ * @param name - `"OnDrawHUD"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnDrawHUD",
+    handler: () => void
+): void;
+
+/**
+ * Fired after the game HUD has finished drawing.
+ * Use this for post-HUD effects or cleanup.
+ *
+ * @param name - `"OnDrawnHUD"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnDrawnHUD",
+    handler: () => void
+): void;
+
+// ===== Character Input Events =====
+
+/**
+ * Fired when a character is typed (text input, not bound keys).
+ *
+ * @param name - `"OnCharacter"`
+ * @param handler - Callback receiving the typed character as a string.
+ */
+declare function addEventHandler(
+    name: "OnCharacter",
+    handler: (char: string) => void
+): void;
+
+// ===== Keyboard Events =====
+
+/**
+ * Fired when a key is pressed down.
+ *
+ * @param name - `"OnKeyDown"`
+ * @param handler - Callback receiving the numeric key code of the pressed key.
+ *
+ * @example
+ * addEventHandler("OnKeyDown", function(key) {
+ *     if (key === 27) console.log("Escape pressed");
+ * });
+ */
+declare function addEventHandler(
+    name: "OnKeyDown",
+    handler: (key: number) => void
+): void;
+
+/**
+ * Fired when a key is released.
+ *
+ * @param name - `"OnKeyUp"`
+ * @param handler - Callback receiving the numeric key code of the released key.
+ */
+declare function addEventHandler(
+    name: "OnKeyUp",
+    handler: (key: number) => void
+): void;
+
+// ===== Mouse Events =====
+
+/**
+ * Fired when a mouse device is connected.
+ *
+ * @param name - `"OnMouseConnected"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnMouseConnected",
+    handler: () => void
+): void;
+
+/**
+ * Fired when a mouse device is disconnected.
+ *
+ * @param name - `"OnMouseDisconnected"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnMouseDisconnected",
+    handler: () => void
+): void;
+
+/**
+ * Fired when a mouse button is pressed down.
+ *
+ * @param name - `"OnMouseDown"`
+ * @param handler - Callback receiving the button number and (x, y) screen coordinates.
+ */
+declare function addEventHandler(
+    name: "OnMouseDown",
+    handler: (button: number, x: number, y: number) => void
+): void;
+
+/**
+ * Fired when a mouse button is released.
+ *
+ * @param name - `"OnMouseUp"`
+ * @param handler - Callback receiving the button number and (x, y) screen coordinates.
+ */
+declare function addEventHandler(
+    name: "OnMouseUp",
+    handler: (button: number, x: number, y: number) => void
+): void;
+
+/**
+ * Fired continuously when the mouse moves across the screen.
+ *
+ * @param name - `"OnMouseMove"`
+ * @param handler - Callback receiving the (x, y) screen coordinates.
+ */
+declare function addEventHandler(
+    name: "OnMouseMove",
+    handler: (x: number, y: number) => void
+): void;
+
+/**
+ * Fired when the mouse cursor leaves the game window.
+ *
+ * @param name - `"OnMouseLeave"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnMouseLeave",
+    handler: () => void
+): void;
+
+/**
+ * Fired when the mouse wheel is scrolled.
+ *
+ * @param name - `"OnMouseWheel"`
+ * @param handler - Callback receiving the scroll delta (positive = scroll up, negative = scroll down).
+ */
+declare function addEventHandler(
+    name: "OnMouseWheel",
+    handler: (delta: number) => void
+): void;
+
+// ===== Connection Events =====
+
+/**
+ * Fired when the client disconnects from the server.
+ * Use this to clean up resources or show a disconnection message.
+ *
+ * @param name - `"OnDisconnect"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnDisconnect",
+    handler: () => void
+): void;
+
+// ===== Ped Events =====
+
+/**
+ * Fired when a ped is busted (arrested by police).
+ *
+ * @param name - `"OnPedBusted"`
+ * @param handler - Callback receiving the busted `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedBusted",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped changes their currently equipped weapon.
+ *
+ * @param name - `"OnPedChangeWeapon"`
+ * @param handler - Callback receiving the `Ped` and the new weapon ID.
+ */
+declare function addEventHandler(
+    name: "OnPedChangeWeapon",
+    handler: (ped: Ped, weapon: number) => void
+): void;
+
+/**
+ * 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 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 dies (reaches 0 health).
+ * Note: `OnPedWasted` is a separate event that fires on the server.
+ *
+ * @param name - `"OnPedDead"`
+ * @param handler - Callback receiving the dead `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedDead",
+    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 has fully entered a vehicle (seated).
+ *
+ * @param name - `"OnPedEnteredVehicle"`
+ * @param handler - Callback receiving the `Ped`, the `Vehicle`, and the occupied seat.
+ */
+declare function addEventHandler(
+    name: "OnPedEnteredVehicle",
+    handler: (ped: Ped, vehicle: Vehicle, seat: number) => void
+): void;
+
+/**
+ * Fired when a ped has fully exited a vehicle (standing outside).
+ *
+ * @param name - `"OnPedExitedVehicle"`
+ * @param handler - Callback receiving the `Ped` and the `Vehicle` that was exited.
+ */
+declare function addEventHandler(
+    name: "OnPedExitedVehicle",
+    handler: (ped: Ped, vehicle: Vehicle) => void
+): void;
+
+/**
+ * Fired when a ped is in the process of entering a vehicle (animation playing).
+ *
+ * @param name - `"OnPedEnteringVehicle"`
+ * @param handler - Callback receiving the `Ped`, the `Vehicle`, and the target seat.
+ */
+declare function addEventHandler(
+    name: "OnPedEnteringVehicle",
+    handler: (ped: Ped, vehicle: Vehicle, seat: number) => void
+): void;
+
+/**
+ * Fired when a ped is in the process of exiting a vehicle (animation playing).
+ *
+ * @param name - `"OnPedExitingVehicle"`
+ * @param handler - Callback receiving the `Ped` and the `Vehicle` being exited.
+ */
+declare function addEventHandler(
+    name: "OnPedExitingVehicle",
+    handler: (ped: Ped, vehicle: Vehicle) => void
+): void;
+
+/**
+ * Fired when a ped falls (loses footing and falls to 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 fires a projectile (rocket, grenade, etc.).
+ *
+ * @param name - `"OnPedFireProjectile"`
+ * @param handler - Callback receiving the `Ped` that fired.
+ */
+declare function addEventHandler(
+    name: "OnPedFireProjectile",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped inflicts damage on another ped.
+ *
+ * @param name - `"OnPedInflictDamage"`
+ * @param handler - Callback receiving the attacking `Ped`, the target `Ped`, and the damage amount.
+ */
+declare function addEventHandler(
+    name: "OnPedInflictDamage",
+    handler: (ped: Ped, target: Ped, damage: number) => 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 (appears in the world for the first time).
+ *
+ * @param name - `"OnPedSpawn"`
+ * @param handler - Callback receiving the spawned `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedSpawn",
+    handler: (ped: Ped) => void
+): void;
+
+/**
+ * Fired when a ped starts closing a vehicle door.
+ *
+ * @param name - `"OnPedStartClosingVehicleDoor"`
+ * @param handler - Callback receiving the `Ped`, the `Vehicle`, and the door index.
+ */
+declare function addEventHandler(
+    name: "OnPedStartClosingVehicleDoor",
+    handler: (ped: Ped, vehicle: Vehicle, door: number) => void
+): void;
+
+/**
+ * Fired when a ped starts a fight attack (melee or weapon).
+ *
+ * @param name - `"OnPedStartFightAttack"`
+ * @param handler - Callback receiving the attacking `Ped` and the target `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedStartFightAttack",
+    handler: (ped: Ped, target: Ped) => void
+): void;
+
+/**
+ * Fired when a ped starts defending against a fight attack.
+ *
+ * @param name - `"OnPedStartFightDefend"`
+ * @param handler - Callback receiving the defending `Ped` and the attacker `Ped`.
+ */
+declare function addEventHandler(
+    name: "OnPedStartFightDefend",
+    handler: (ped: Ped, attacker: Ped) => void
+): void;
+
+/**
+ * Fired when a ped starts opening a vehicle door.
+ *
+ * @param name - `"OnPedStartOpeningVehicleDoor"`
+ * @param handler - Callback receiving the `Ped`, the `Vehicle`, and the door index.
+ */
+declare function addEventHandler(
+    name: "OnPedStartOpeningVehicleDoor",
+    handler: (ped: Ped, vehicle: Vehicle, door: number) => void
+): void;
+
+/**
+ * Fired when a ped uses/equips a weapon.
+ *
+ * @param name - `"OnPedUseWeapon"`
+ * @param handler - Callback receiving the `Ped` and the weapon ID.
+ */
+declare function addEventHandler(
+    name: "OnPedUseWeapon",
+    handler: (ped: Ped, weapon: number) => void
+): void;
+
+/**
+ * Fired when a ped is wasted/killed.
+ * Note: this is a client-side notification. Server also has `OnPedWasted`.
+ *
+ * @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;
+
+// ===== Process/Render Events =====
+
+/**
+ * Fired every game tick (frame). Main update loop event.
+ * Use this for continuous logic that needs to run each frame.
+ *
+ * @param name - `"OnProcess"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnProcess",
+    handler: () => void
+): void;
+
+/**
+ * Fired after 3D rendering but before 2D/HUD rendering.
+ * Use this to draw custom 2D graphics that sit behind the HUD.
+ *
+ * @param name - `"OnPostRender2D"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnPostRender2D",
+    handler: () => void
+): void;
+
+/**
+ * Fired before the 3D scene is rendered.
+ * Use this to modify the scene before the engine draws it.
+ *
+ * @param name - `"OnPreRender"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnPreRender",
+    handler: () => void
+): void;
+
+/**
+ * Fired during the 3D scene rendering.
+ * Use this for custom 3D drawing (text, lines, shapes in the world).
+ *
+ * @param name - `"OnRender"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnRender",
+    handler: () => void
+): void;
+
+/**
+ * Fired during 2D rendering (screen-space graphics).
+ * Use this to draw custom UI elements on screen.
+ *
+ * @param name - `"OnRender2D"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnRender2D",
+    handler: () => void
+): void;
+
+/**
+ * Fired when visual effects are being rendered (particles, coronas, etc.).
+ * Use this to inject custom rendering effects.
+ *
+ * @param name - `"OnRenderEffects"`
+ * @param handler - Callback with no arguments.
+ */
+declare function addEventHandler(
+    name: "OnRenderEffects",
+    handler: () => void
+): void;
+
+// ===== Resource Events =====
+
+/**
+ * Fired when a resource finishes loading and is ready to use.
+ *
+ * @param name - `"OnResourceReady"`
+ * @param handler - Callback receiving the ready `Resource`.
+ */
+declare function addEventHandler(
+    name: "OnResourceReady",
+    handler: (resource: Resource) => void
+): void;
+
+/**
+ * Fired when a resource starts running.
+ *
+ * @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.
+ *
+ * @param name - `"OnResourceStop"`
+ * @param handler - Callback receiving the stopped `Resource`.
+ */
+declare function addEventHandler(
+    name: "OnResourceStop",
+    handler: (resource: Resource) => void
+): void;
+
+// ===== Vehicle Events =====
+
+/**
+ * Fired when a vehicle explodes (reaches 0 health and detonates).
+ *
+ * @param name - `"OnVehicleExplode"`
+ * @param handler - Callback receiving the exploding `Vehicle`.
+ */
+declare function addEventHandler(
+    name: "OnVehicleExplode",
+    handler: (vehicle: Vehicle) => void
+): void;
+
+// ===== Generic Fallback =====
+
+/**
+ * Generic fallback overload for any event name not explicitly typed above.
+ * Allows listening for custom or future event names with any number of arguments.
+ *
+ * @param name - The event name string.
+ * @param handler - Callback receiving any number of variadic 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 previously registered.
+ * Must be the same function object, not a copy or new closure.
+ *
+ * @example
+ * function onKeyDown(key: number) { console.log(key); }
+ * addEventHandler("OnKeyDown", onKeyDown);
+ * // Later:
+ * removeEventHandler("OnKeyDown", onKeyDown);
+ */
+declare function removeEventHandler(
+    name: string,
+    handler: (...args: any[]) => void
+): void;
+
+// ===== Bound Event Handlers =====
+
+/**
+ * Registers a handler bound to a specific resource for lifecycle events.
+ * When the resource stops, the handler is automatically removed.
+ *
+ * @param name - Event name: `"OnResourceReady"` or `"OnResourceStart"`.
+ * @param resource - The `Resource` object to bind the handler's lifetime to.
+ * @param handler - Callback receiving variadic arguments.
+ */
+declare function bindEventHandler(
+    name: "OnResourceReady" | "OnResourceStart",
+    resource: object,
+    handler: (...args: any[]) => void
+): void;