gtac-types 0.0.1

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

@@ -0,0 +1,724 @@
+/**
+ * GTAC Client Game, Platform, and Natives Declarations
+ *
+ * Defines the client-side `gta` global object (the primary API for interacting
+ * with the GTA game world), the `game` object (engine-level controls), the
+ * `platform` object (timing information), and the `natives` reference
+ * (low-level game opcode functions).
+ *
+ * The `gta` object provides methods for controlling AI, buildings, camera,
+ * cheats, controls, drawing, entities, cutscenes, messages, radar, HUD,
+ * IPL loading, and world creation (markers, objects, peds, pickups, vehicles,
+ * blips, spheres), as well as time, weather, and world physics.
+ *
+ * All declarations are global — no import required.
+ *
+ * @module types/client/gta
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Change the weather and time
+ * gta.setWeather(0); // Sunny
+ * gta.setTime(12, 0); // Noon
+ *
+ * @example
+ * // Spawn a vehicle at the player's position
+ * const pos = localPlayer.position;
+ * const car = gta.createVehicle(141, pos.x, pos.y, pos.z, 0);
+ */
+
+// ===== Game (gta) =====
+
+/**
+ * Primary GTA game world manipulation API.
+ * Provides methods and properties for controlling nearly every aspect of
+ * the game world: AI, buildings, camera, cheats, controls, rendering,
+ * entities, cutscenes, messages, radar, HUD, IPL loading, creation of game
+ * objects (markers, objects, peds, pickups, vehicles, blips, spheres),
+ * time/weather management, and world physics.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+declare var gta: {
+    // -- AI --
+
+    /**
+     * Enables or disables the spawning of civilian peds.
+     * @param enabled - `true` to allow civilians, `false` to prevent civilian spawning.
+     */
+    setCiviliansEnabled(enabled: boolean): void;
+
+    /**
+     * Enables or disables airplane traffic.
+     * @param enabled - `true` to allow planes, `false` to disable plane traffic.
+     */
+    setPlanesEnabled(enabled: boolean): void;
+
+    /**
+     * Enables or disables general vehicle traffic.
+     * When disabled, no AI-controlled vehicles will spawn on roads.
+     * @param enabled - `true` to allow traffic, `false` to disable.
+     */
+    setTrafficEnabled(enabled: boolean): void;
+
+    /**
+     * Sets the density of vehicle traffic.
+     * @param density - Traffic density value (0.0 = none, 1.0 = normal, higher = denser).
+     */
+    trafficDensity(density: number): void;
+
+    // -- Building --
+
+    /**
+     * Swaps the nearest building model within a radius with a new model.
+     * Useful for dynamic world modification (e.g. replacing a building with another).
+     *
+     * @param oldModel - The existing building model ID to replace.
+     * @param newModel - The new building model ID to use.
+     * @param x - X coordinate of the search centre.
+     * @param y - Y coordinate of the search centre.
+     * @param z - Z coordinate of the search centre.
+     * @param radius - Search radius in world units.
+     */
+    swapNearestBuildingModel(
+        oldModel: number,
+        newModel: number,
+        x: number,
+        y: number,
+        z: number,
+        radius: number
+    ): void;
+
+    /**
+     * Reverts all building model swaps, restoring original models.
+     */
+    undoBuildingSwaps(): void;
+
+    // -- Camera --
+
+    /**
+     * Current camera interior ID.
+     * 0 = exterior, other values correspond to specific interiors.
+     */
+    cameraInterior: number;
+
+    /**
+     * Current camera transformation matrix.
+     * Represents the camera's position and orientation as a 4x4 matrix.
+     */
+    cameraMatrix: Matrix4x4;
+
+    /**
+     * The `Entity` the camera is currently looking at/targeting.
+     */
+    cameraTarget: Entity;
+
+    /**
+     * Fades the camera in or out over a specified duration.
+     *
+     * @param fade - Fade direction: `FADE_IN` (show) or `FADE_OUT` (hide).
+     * @param duration - Duration of the fade in milliseconds.
+     * @param args - Additional arguments (e.g. colour).
+     */
+    fadeCamera(fade: number, duration: number, ...args: any[]): void;
+
+    /**
+     * Whether the camera is currently in the middle of a fade transition.
+     */
+    fading: boolean;
+
+    /**
+     * Restores the camera to its default position (behind the player).
+     */
+    restoreCamera(): void;
+
+    /**
+     * Points the camera to look at a specific world coordinate.
+     *
+     * @param x - Target X coordinate.
+     * @param y - Target Y coordinate.
+     * @param z - Target Z coordinate.
+     */
+    setCameraLookAt(x: number, y: number, z: number): void;
+
+    /**
+     * Points the camera to look at a specific entity, following it.
+     *
+     * @param entity - The `Entity` to point the camera at.
+     */
+    setCameraLookAtEntity(entity: Entity): void;
+
+    /**
+     * Positions and orients the camera using a matrix.
+     *
+     * @param x - Camera X position.
+     * @param y - Camera Y position.
+     * @param z - Camera Z position.
+     * @param rx - Camera X rotation (pitch).
+     * @param ry - Camera Y rotation (yaw).
+     * @param rz - Camera Z rotation (roll).
+     */
+    setCameraMatrix(
+        x: number,
+        y: number,
+        z: number,
+        rx: number,
+        ry: number,
+        rz: number
+    ): void;
+
+    /**
+     * Sets the camera to target/follow a specific entity.
+     *
+     * @param entity - The `Entity` for the camera to target.
+     */
+    setCameraTarget(entity: Entity): void;
+
+    /**
+     * Toggles whether cars are generated around the camera position.
+     * @param enabled - `true` to generate cars around the camera.
+     */
+    setGenerateCarsAroundCamera(enabled: boolean): void;
+
+    /**
+     * Forces a camera update, applying any pending changes immediately.
+     */
+    updateCamera(): void;
+
+    // -- Cheat --
+
+    /**
+     * Checks whether a specific cheat is currently active.
+     *
+     * @param cheat - Cheat ID constant (e.g. `CHEAT_FASTTIME`).
+     * @returns `true` if the cheat is enabled.
+     */
+    isCheatEnabled(cheat: number): boolean;
+
+    /**
+     * Enables or disables a specific cheat.
+     *
+     * @param cheat - Cheat ID constant.
+     * @param enabled - `true` to enable, `false` to disable.
+     */
+    setCheatEnabled(cheat: number, enabled: boolean): void;
+
+    // -- Control --
+
+    /**
+     * Enables or disables the standard game controls for the local player.
+     * When disabled, the player cannot move, jump, shoot, etc.
+     *
+     * @param enabled - `true` to enable standard controls, `false` to freeze input.
+     */
+    standardControls(enabled: boolean): void;
+
+    // -- Drawing --
+
+    /**
+     * Draws a 2D rectangle on screen using a texture.
+     *
+     * Arguments are variadic to match the `drawRectangle` opcode:
+     * `(texture, position: Vec2, size: Vec2, centre: boolean, rotation: number, colour, source: Vec2, sourceSize: Vec2)`.
+     *
+     * @param args - Variadic parameters as documented for the drawRectangle opcode.
+     */
+    drawRectangle(...args: any[]): void;
+
+    // -- Entity --
+
+    /**
+     * Undoes all entity invisibility settings, restoring visibility defaults.
+     */
+    undoEntityInvisibilitySettings(): void;
+
+    // -- Cutscene --
+
+    /**
+     * Loads a cutscene by name for later playback.
+     * @param name - The cutscene name/identifier to load.
+     */
+    loadCutscene(name: string): void;
+
+    /**
+     * Plays the currently loaded cutscene.
+     */
+    playCutscene(): void;
+
+    /**
+     * Stops any currently playing cutscene.
+     */
+    stopCutscene(): void;
+
+    // -- Message / Text --
+
+    /**
+     * Displays styled text at screen coordinates.
+     * @param x - Screen X position (pixels).
+     * @param y - Screen Y position (pixels).
+     * @param text - Text string to display.
+     */
+    displayText(x: number, y: number, text: string): void;
+
+    /**
+     * Displays styled text with a number embedded, at screen coordinates.
+     * @param x - Screen X position.
+     * @param y - Screen Y position.
+     * @param text - Text string (use `~1~` as placeholder for the number).
+     * @param num - The number to insert into the text.
+     */
+    displayTextWithNumber(x: number, y: number, text: string, num: number): void;
+
+    /**
+     * Clears all displayed text from the screen.
+     */
+    clearText(): void;
+
+    /**
+     * Displays help text (the small text area in the top-left of the HUD).
+     * @param text - Help text string to display.
+     */
+    displayHelpText(text: string): void;
+
+    /**
+     * Clears the currently displayed help text.
+     */
+    clearHelpText(): void;
+
+    // -- Radar --
+
+    /**
+     * Whether the radar/minimap is currently enabled.
+     */
+    radarEnabled: boolean;
+
+    /**
+     * Enables or disables the radar/minimap display.
+     * @param enabled - `true` to show radar, `false` to hide.
+     */
+    setRadarEnabled(enabled: boolean): void;
+
+    /**
+     * Gets the current radar enabled state.
+     * @returns `true` if the radar is enabled.
+     */
+    getRadarEnabled(): boolean;
+
+    // -- HUD --
+
+    /**
+     * Shows or hides the entire HUD (health, armour, weapon, radar, etc.).
+     * @param visible - `true` to show HUD, `false` to hide entirely.
+     */
+    setHUDVisible(visible: boolean): void;
+
+    /**
+     * Checks whether the HUD is currently visible.
+     * @returns `true` if the HUD is visible.
+     */
+    isHUDVisible(): boolean;
+
+    /**
+     * Shows or hides a specific HUD component.
+     * @param component - HUD component ID.
+     * @param visible - `true` to show, `false` to hide.
+     */
+    setHUDComponentVisible(component: number, visible: boolean): void;
+
+    /**
+     * Checks whether a specific HUD component is visible.
+     * @param component - HUD component ID.
+     * @returns `true` if the component is visible.
+     */
+    isHUDComponentVisible(component: number): boolean;
+
+    // -- IPL --
+
+    /**
+     * Loads an IPL (Item Placement) file, adding its buildings/objects to the world.
+     * @param name - IPL file name without extension.
+     */
+    loadIPL(name: string): void;
+
+    /**
+     * Unloads an IPL file, removing its buildings/objects from the world.
+     * @param name - IPL file name without extension.
+     */
+    unloadIPL(name: string): void;
+
+    /**
+     * Checks whether an IPL file is currently loaded.
+     * @param name - IPL file name.
+     * @returns `true` if the IPL is loaded.
+     */
+    isIPLLoaded(name: string): boolean;
+
+    // -- Markers --
+
+    /**
+     * Creates a 3D world marker at the specified position.
+     *
+     * @param x - X coordinate.
+     * @param y - Y coordinate.
+     * @param z - Z coordinate.
+     * @param type - Marker type ID (cylinder, arrow, etc.).
+     * @param size - Marker size/diameter.
+     * @param r - Red colour component (0–255).
+     * @param g - Green colour component (0–255).
+     * @param b - Blue colour component (0–255).
+     * @param a - Alpha/opacity component (0–255, 255 = fully opaque).
+     * @returns The created `Marker`.
+     */
+    createMarker(
+        x: number,
+        y: number,
+        z: number,
+        type: number,
+        size: number,
+        r: number,
+        g: number,
+        b: number,
+        a: number
+    ): Marker;
+
+    // -- Objects --
+
+    /**
+     * Creates a placeable object with a given model at the specified position and rotation.
+     *
+     * @param model - GTA model ID.
+     * @param x - X position.
+     * @param y - Y position.
+     * @param z - Z position.
+     * @param rx - X rotation (pitch) in degrees.
+     * @param ry - Y rotation (roll) in degrees.
+     * @param rz - Z rotation (yaw) in degrees.
+     * @returns The created `Object`.
+     */
+    createObject(
+        model: number,
+        x: number,
+        y: number,
+        z: number,
+        rx: number,
+        ry: number,
+        rz: number
+    ): Object;
+
+    // -- Peds --
+
+    /**
+     * Creates a pedestrian (AI character) at the specified position.
+     *
+     * @param model - Ped model/skin ID (see PedSkin enum).
+     * @param x - X position.
+     * @param y - Y position.
+     * @param z - Z position.
+     * @param rz - Z rotation (heading) in degrees.
+     * @returns The created `Ped`.
+     */
+    createPed(model: number, x: number, y: number, z: number, rz: number): Ped;
+
+    // -- Pickups --
+
+    /**
+     * Creates a collectible pickup in the world.
+     *
+     * @param model - Pickup model ID (see PickupModel enum).
+     * @param position - World position as a `Vec3`.
+     * @param type - Pickup type constant.
+     * @returns The created `Pickup`, or `null` on failure.
+     */
+    createPickup(model: number, position: Vec3, type: number): Pickup | null;
+
+    // -- Vehicles --
+
+    /**
+     * Creates a vehicle at the specified position.
+     *
+     * @param model - Vehicle model ID (see VehicleModel enum).
+     * @param x - X position.
+     * @param y - Y position.
+     * @param z - Z position.
+     * @param rz - Z rotation (heading) in degrees.
+     * @param c1 - Primary colour ID (optional).
+     * @param c2 - Secondary colour ID (optional).
+     * @returns The created `Vehicle`.
+     */
+    createVehicle(
+        model: number,
+        x: number,
+        y: number,
+        z: number,
+        rz: number,
+        c1?: number,
+        c2?: number
+    ): Vehicle;
+
+    // -- Blips --
+
+    /**
+     * Creates a radar blip at a fixed world position.
+     *
+     * @param position - World position as a `Vec3`.
+     * @param icon - Blip icon ID (see Icon enum).
+     * @param size - Blip size on radar (optional, default 2).
+     * @param colour - Blip colour as 0xRRGGBB hex (optional, default 0). Example: `0xFFD700` for yellow.
+     * @returns The created `Blip`.
+     */
+    createBlip(
+        position: Vec3,
+        icon: number,
+        size?: number,
+        colour?: number
+    ): Blip;
+
+    /**
+     * Creates a radar blip attached to an element, following its position.
+     *
+     * @param element - The element to attach the blip to, or `null`.
+     * @param icon - Blip icon ID (see Icon enum).
+     * @param size - Blip size on radar (optional, default 2).
+     * @param colour - Blip colour as 0xRRGGBB hex (optional, default 0).
+     * @param blip - Whether to show a radar blip (optional, default `true`).
+     * @param marker - Whether to show a 3D world marker (optional, default `false`).
+     * @returns The created `Blip`.
+     */
+    createBlipAttachedTo(
+        element: Element | null,
+        icon: number,
+        size?: number,
+        colour?: number,
+        blip?: boolean,
+        marker?: boolean
+    ): Blip;
+
+    // -- Time --
+
+    /**
+     * Gets the real-time duration of one in-game minute in milliseconds.
+     * Default is 1000ms (one real second = one game minute).
+     *
+     * @returns Duration in milliseconds.
+     */
+    getMinuteDuration(): number;
+
+    /**
+     * Sets the real-time duration of one in-game minute.
+     * Lower values = faster in-game clock.
+     *
+     * @param ms - Duration per game minute in milliseconds.
+     */
+    setMinuteDuration(ms: number): void;
+
+    /**
+     * Gets the current in-game time.
+     *
+     * @returns Object with `hour` (0–23) and `minute` (0–59).
+     */
+    getTime(): { hour: number; minute: number };
+
+    /**
+     * Sets the current in-game time.
+     *
+     * @param h - Hour (0–23).
+     * @param m - Minute (0–59).
+     */
+    setTime(h: number, m: number): void;
+
+    // -- Weather --
+
+    /**
+     * Gets the current weather ID.
+     * @returns Weather ID (0 = sunny, 1 = cloudy, 2 = rainy, 3 = foggy, etc.).
+     */
+    getWeather(): number;
+
+    /**
+     * Sets the current weather immediately.
+     * @param weather - Weather ID to apply.
+     */
+    setWeather(weather: number): void;
+
+    /**
+     * Smoothly blends between two weather states over time.
+     *
+     * @param w1 - Source weather ID.
+     * @param w2 - Target weather ID.
+     * @param percent - Blend percentage (0.0 = all source, 1.0 = all target).
+     */
+    setWeatherBlend(w1: number, w2: number, percent: number): void;
+
+    // -- World --
+
+    /**
+     * Gets the current gravity multiplier.
+     * @returns Gravity value (default ~0.008).
+     */
+    getGravity(): number;
+
+    /**
+     * Sets the gravity multiplier for the game world.
+     * @param g - Gravity value (0.008 = normal; 0.002 = moon-like; negative = reverse).
+     */
+    setGravity(g: number): void;
+
+    /**
+     * Gets the current game speed multiplier.
+     * @returns Game speed value (1.0 = normal).
+     */
+    getGameSpeed(): number;
+
+    /**
+     * Sets the game speed multiplier.
+     * @param speed - Speed value (1.0 = normal; 2.0 = double speed; 0.5 = slow motion).
+     */
+    setGameSpeed(speed: number): void;
+
+    // -- Existing Extensions --
+
+    /**
+     * Whether the game is currently paused.
+     */
+    paused: boolean;
+
+    /**
+     * Whether the player is currently on a mission.
+     */
+    onMission: boolean;
+
+    /**
+     * Game screen width in pixels.
+     */
+    width: number;
+
+    /**
+     * Game screen height in pixels.
+     */
+    height: number;
+
+    /**
+     * Current weather ID (property — use `getWeather()` and `setWeather()` for function access).
+     */
+    weather: number;
+
+    /**
+     * Current in-game time as `{ hour, minute }`.
+     */
+    time: { hour: number; minute: number };
+
+    /**
+     * Sets a custom GXT (game text) key to a new value.
+     * GXT keys are used by the game for displaying localized text.
+     *
+     * @param key - The GXT key name.
+     * @param text - The new text value to assign.
+     */
+    setCustomText(key: string, text: string): void;
+
+    /**
+     * Starts a game mission by ID.
+     * @param id - Mission ID to start.
+     */
+    startMission(id: number): void;
+
+    /**
+     * Cancels the currently active mission.
+     * @param instant - If `true`, stop instantly; otherwise transition out.
+     */
+    cancelMission(instant?: boolean): void;
+
+    /**
+     * Creates an invisible trigger sphere at a position with a given radius.
+     *
+     * @param position - World position as a `Vec3`.
+     * @param radius - Sphere radius in world units.
+     * @returns The created `Sphere`.
+     */
+    createSphere(position: Vec3, radius: number): Sphere;
+
+    /**
+     * Gets a list of all currently active game script names.
+     * @returns Array of script name strings.
+     */
+    getActiveScripts(): string[];
+
+    /**
+     * Terminates a game script by its name.
+     * @param name - The script name to terminate.
+     */
+    terminateScript(name: string): void;
+};
+
+// ===== Game Control =====
+
+/**
+ * Engine-level game control and state API.
+ * Provides low-level access to game tick count, player control toggling,
+ * camera fading, and interior IDs.
+ */
+declare var game: {
+    /**
+     * Game type identifier (e.g. `GAME_GTA_VC`).
+     */
+    game: number;
+
+    /**
+     * Enables or disables player control (movement, actions).
+     * @param enabled - `true` to allow player input, `false` to freeze.
+     */
+    setPlayerControl(enabled: boolean): void;
+
+    /**
+     * Fades the camera in or out.
+     * @param state - `true` = fade in, `false` = fade out.
+     * @param duration - Fade duration in milliseconds.
+     */
+    fadeCamera(state: boolean, duration: number): void;
+
+    /**
+     * Fades the camera in or out with a custom fade colour.
+     * @param state - `true` = fade in, `false` = fade out.
+     * @param duration - Fade duration in milliseconds.
+     * @param colour - Packed ARGB colour for the fade.
+     */
+    fadeCamera(state: boolean, duration: number, colour: number): void;
+
+    /**
+     * Current game tick counter (increments every frame).
+     */
+    tick: number;
+
+    /**
+     * Current camera interior ID.
+     */
+    cameraInterior: number;
+
+    /**
+     * Current player interior ID.
+     */
+    interior: number;
+};
+
+// ===== Platform =====
+
+/**
+ * Platform-level timing information.
+ */
+declare var platform: {
+    /**
+     * High-resolution tick count in milliseconds since the client started.
+     * Use for delta-time calculations and performance measurement.
+     */
+    ticks: number;
+};
+
+// ===== Natives =====
+
+/**
+ * Reference to the low-level game native functions (opcode interface).
+ * Provides direct access to all GTA Vice City game script opcodes.
+ *
+ * @see `types/client/natives.d.ts` for the full function list.
+ */
+declare var natives: Natives;