gtac-types 0.0.1

package/src/types/element.d.ts

@@ -0,0 +1,853 @@
+/**
+ * GTAC Element Hierarchy Type Definitions
+ *
+ * Defines the complete GTA Connected world-object hierarchy.
+ * All in-game objects (vehicles, peds, players, pickups, markers, blips, etc.)
+ * derive from the base `Element` interface, forming a tree structure with
+ * parent/child relationships, position, rotation, and custom data storage.
+ *
+ * @module types/element
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Check if a player is in a vehicle
+ * function isPlayerInVehicle(player: Player): boolean {
+ *     return player.vehicle !== null;
+ * }
+ *
+ * @example
+ * // Store custom data on any element
+ * element.setData("owner", "Tommy");
+ * const owner = element.getData("owner"); // "Tommy"
+ */
+
+// ===== Element Hierarchy =====
+
+/**
+ * Base element type — all GTA Connected world objects derive from Element.
+ *
+ * Every element has a unique numeric ID, a position in the world, a parent/child
+ * hierarchy, and a key/value store for custom data. Elements can be assigned
+ * to dimensions (isolated worlds that don't interact) and controlled via
+ * network synchronisation flags.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+interface Element {
+    /**
+     * Unique numeric element ID assigned by the server.
+     * Every element in the world has a distinct ID.
+     */
+    id: number;
+
+    /**
+     * Element type constant.
+     * One of: `ELEMENT_ELEMENT`, `ELEMENT_ENTITY`, `ELEMENT_PHYSICAL`,
+     * `ELEMENT_PED`, `ELEMENT_PLAYER`, `ELEMENT_VEHICLE`, `ELEMENT_BLIP`,
+     * `ELEMENT_OBJECT`, `ELEMENT_TRAIN`, `ELEMENT_PICKUP`, `ELEMENT_MARKER`,
+     * `ELEMENT_BUILDING`, `ELEMENT_CIVILIAN`, `ELEMENT_TRANSFORMABLE`.
+     */
+    type: number;
+
+    /**
+     * Displayable name for the element.
+     * Can be set at creation time and used to identify elements by name.
+     */
+    name: string;
+
+    /**
+     * Parent element in the hierarchy, or `null` if this element is a root
+     * (top-level) element. Elements attached to a parent move/rotate with it.
+     */
+    parent: Element | null;
+
+    /**
+     * Array of child elements directly attached to this element.
+     * Children inherit position/rotation from their parent.
+     */
+    children: Element[];
+
+    /**
+     * World position of this element as a 3D vector.
+     * Represented as a `Vec3` with `x`, `y`, `z` components in world units.
+     */
+    position: Vec3;
+
+    /**
+     * Rotation of this element as a 3D vector.
+     * Components represent pitch (x), yaw (y), and roll (z) in degrees.
+     */
+    rotation: Vec3;
+
+    /**
+     * Dimension ID this element belongs to.
+     * Elements in different dimensions cannot see or interact with each other.
+     * The default dimension is 0.
+     */
+    dimension: number;
+
+    /**
+     * The `Resource` that created this element, or `null` if the element
+     * was created by the engine or is a built-in element.
+     */
+    resource: Resource | null;
+
+    /**
+     * The `Client` responsible for network synchronisation of this element,
+     * or `null` if no client is the current syncer.
+     */
+    syncer: Client | null;
+
+    /**
+     * Whether this element was created on the local client (client-side only).
+     * Always `false` on the server.
+     */
+    isLocal: boolean;
+
+    /**
+     * Whether the local client is the owner of this element.
+     * Ownership is used for authority decisions (e.g. who can delete it).
+     */
+    isOwner: boolean;
+
+    /**
+     * Whether the local client is the network syncer for this element.
+     * The syncer sends position/state updates to the server.
+     */
+    isSyncer: boolean;
+
+    /**
+     * Distance (in world units) at which this element starts streaming in
+     * for clients. Elements beyond this distance are not loaded.
+     */
+    streamInDistance: number;
+
+    /**
+     * Distance (in world units) at which this element streams out for clients.
+     * When a client is farther than this distance, the element is unloaded.
+     */
+    streamOutDistance: number;
+
+    /**
+     * The `Client` this element currently exists for (is streamed in to),
+     * or `null` if the element is synced to all clients.
+     */
+    existsFor: Client | null;
+
+    /**
+     * Network synchronisation flags controlling how this element's
+     * position, rotation, and state are synced between server and clients.
+     */
+    netFlags: NetFlags;
+
+    /**
+     * Retrieves a custom data value previously stored on this element.
+     * Values are dynamically typed (SpiderMonkey engine — no static type enforcement).
+     *
+     * @param key - The string key identifying the stored data.
+     * @returns The stored value, or `undefined` if no data exists for the key.
+     */
+    getData(key: string): any;
+
+    /**
+     * Stores a custom data value on this element.
+     * Data persists for the lifetime of the element and is accessible on both
+     * server and client sides.
+     *
+     * @param key - The string key to store the data under.
+     * @param value - Any value to store (number, string, object, array, etc.).
+     */
+    setData(key: string, value: any): void;
+
+    /**
+     * Removes a custom data key and its associated value from this element.
+     *
+     * @param key - The string key to remove.
+     */
+    removeData(key: string): void;
+
+    /**
+     * Checks whether this element matches a given element type constant.
+     * Useful for type-checking elements without relying on `instanceof`.
+     *
+     * @param type - The type constant to check against (e.g. `ELEMENT_VEHICLE`).
+     * @returns `true` if this element is of the given type.
+     *
+     * @example
+     * if (element.isType(ELEMENT_PLAYER)) {
+     *     const player = element as Player;
+     *     message(player.name + " is a player!");
+     * }
+     */
+    isType(type: number): boolean;
+
+    /**
+     * Sets which `Client` is responsible for network synchronisation of this element.
+     * Changing the syncer migrates authority over position/state updates.
+     *
+     * @param client - The client to assign as the new syncer.
+     */
+    setSyncer(client: Client): void;
+}
+
+/**
+ * Entity — a positioned element with heading, interior, transformation matrix,
+ * bounding volumes, and collision data.
+ *
+ * Extends `Element` with spatial properties: orientation, bounding boxes/spheres,
+ * and collision geometry. Entities are the base for physical objects, buildings,
+ * peds, and vehicles.
+ *
+ * @extends Element
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+interface Entity extends Element {
+    /**
+     * Heading (yaw orientation) of the entity in degrees.
+     * 0° = north, 90° = east, 180° = south, 270° = west.
+     */
+    heading: number;
+
+    /**
+     * Interior ID identifying which interior (building interior) the entity is in.
+     * 0 = outside/exterior.
+     */
+    interior: number;
+
+    /**
+     * 4x4 transformation matrix combining position, rotation, and scale
+     * into a single mathematical representation.
+     */
+    matrix: Matrix4x4;
+
+    /**
+     * Visual transparency/opacity of the entity.
+     * 0 = fully transparent, 255 = fully opaque.
+     * **Client-side only** — not available on the server.
+     */
+    alpha: number;
+
+    /**
+     * Centre point of the entity's bounding box in world coordinates.
+     * **Client-side only.**
+     */
+    boundingCentre: Vec3;
+
+    /**
+     * Minimum corner of the entity's axis-aligned bounding box (AABB)
+     * in world coordinates.
+     */
+    boundingMin: Vec3;
+
+    /**
+     * Maximum corner of the entity's axis-aligned bounding box (AABB)
+     * in world coordinates.
+     */
+    boundingMax: Vec3;
+
+    /**
+     * Radius of the bounding sphere that encloses the entity's geometry.
+     * Used for distance checks and collision culling.
+     */
+    boundingRadius: number;
+
+    /**
+     * Whether collision detection is enabled for this entity.
+     * When `false`, the entity passes through other colliders.
+     */
+    collisionsEnabled: boolean;
+
+    /**
+     * Number of collision (col) boxes comprising this entity's collision mesh.
+     */
+    collisionBoxCount: number;
+
+    /**
+     * Raw collision box data array.
+     * Format/schema depends on the game engine — engine-specific.
+     */
+    collisionBoxes: any[];
+
+    /**
+     * Number of collision lines (edges) in the collision mesh.
+     */
+    collisionLineCount: number;
+
+    /**
+     * Raw collision line data array.
+     * Engine-specific format.
+     */
+    collisionLines: any[];
+
+    /**
+     * Number of collision spheres in the collision mesh.
+     */
+    collisionSphereCount: number;
+
+    /**
+     * Raw collision sphere data array.
+     * Engine-specific format.
+     */
+    collisionSpheres: any[];
+
+    /**
+     * Number of vertices in the collision mesh.
+     */
+    collisionVertexCount: number;
+
+    /**
+     * Raw collision vertex data array.
+     * Engine-specific format.
+     */
+    collisionVertices: any[];
+
+    /**
+     * Distance from the entity's centre of mass to the base of its 3D model.
+     * Used for physics and ground-clamping calculations.
+     */
+    distanceFromCentreOfMassToBaseOfModel: number;
+}
+
+/**
+ * Building — a static GTA world-geometry element.
+ *
+ * Buildings represent non-interactive world geometry (roads, buildings, terrain
+ * pieces) loaded from IPL/IDE files. They have a model index but no physics,
+ * velocity, or health properties.
+ *
+ * @extends Entity
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+interface Building extends Entity {
+    /**
+     * GTA model index identifying which visual model this building uses.
+     * Corresponds to entries in the game's IDE (Item Definition) files.
+     */
+    modelIndex: number;
+}
+
+/**
+ * Physical — an entity that interacts with the physics engine.
+ *
+ * Extends `Entity` with mass, gravity multiplier, and linear/angular velocity.
+ * Physical elements participate in collision resolution and can be affected
+ * by forces. Base for `Object`, `Ped`, and `Vehicle`.
+ *
+ * @extends Entity
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+interface Physical extends Entity {
+    /**
+     * Gravity multiplier applied to this physical entity.
+     * 1.0 = normal gravity, 0.0 = no gravity, negative = reverse gravity.
+     */
+    gravity: number;
+
+    /**
+     * Mass of the entity for physics calculations (in arbitrary game units).
+     * Heavier entities require more force to move and deal more collision damage.
+     */
+    mass: number;
+
+    /**
+     * Linear velocity vector in world units per tick.
+     * Describes the direction and speed the entity is currently moving.
+     */
+    velocity: Vec3;
+
+    /**
+     * Angular (rotational) velocity vector in radians per tick.
+     * Describes the rotation speed around each axis.
+     */
+    turnVelocity: Vec3;
+}
+
+/**
+ * Object — a placeable physical item with a GTA model.
+ *
+ * Objects are static or dynamic physical entities with a visual model.
+ * Common uses: furniture, props, barriers, weapons on the ground, etc.
+ *
+ * @extends Physical
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a barrel object
+ * const barrel = gta.createObject(1225, 0, 0, 10, 0, 0, 0);
+ * barrel.gravity = 1.0;
+ */
+interface Object extends Physical {
+    /**
+     * GTA model index identifying which visual model this object uses.
+     */
+    modelIndex: number;
+}
+
+/**
+ * Ped — a pedestrian character with health, armour, and vehicle occupancy.
+ *
+ * Peds are AI-controlled or player-controlled characters that walk, run,
+ * fight, and interact with the world. They have health/armour, can hold weapons,
+ * and can occupy vehicle seats.
+ *
+ * @extends Physical
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Check if a ped is alive
+ * function isPedAlive(ped: Ped): boolean {
+ *     return ped.health > 0;
+ * }
+ */
+interface Ped extends Physical {
+    /**
+     * Armour value (0–100).
+     * Armour absorbs damage before health is affected.
+     */
+    armour: number;
+
+    /**
+     * Whether the ped is frozen in place.
+     * Frozen peds cannot move, fall, or react to physics.
+     */
+    frozen: boolean;
+
+    /**
+     * Health value. 100 = full health, 0 = dead/wasted.
+     * Values above 100 are possible (overhealed).
+     */
+    health: number;
+
+    /**
+     * GTA model index for the ped's appearance/skin.
+     * See the PedSkin enum for human-readable constants.
+     */
+    modelIndex: number;
+
+    /**
+     * The `Vehicle` this ped is currently occupying, or `null` if on foot.
+     */
+    occupiedVehicle: Vehicle | null;
+
+    /**
+     * Seat index the ped is sitting in within their occupied vehicle.
+     * 0 = driver seat, 1 = front passenger, 2+ = rear seats.
+     */
+    occupyingSeat: number;
+}
+
+/**
+ * Player — a ped controlled by a connected client.
+ *
+ * Players extend `Ped` with multiplayer-specific properties: team, wanted level,
+ * money, weapons, and player colours. Only `Player` entities are directly
+ * controlled by human clients.
+ *
+ * @extends Ped
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Give a player money and a weapon
+ * function equipPlayer(player: Player): void {
+ *     player.money += 500;
+ *     player.giveWeapon(22, 100, true); // Pistol with 100 ammo
+ * }
+ */
+interface Player extends Ped {
+    /**
+     * Player skin/appearance ID.
+     * Determines the character model used for this player.
+     */
+    skin: number;
+
+    /**
+     * Team ID for team-based game modes.
+     * Use 0 for no team.
+     */
+    team: number;
+
+    /**
+     * Wanted level (0–6 stars).
+     * Controls police response intensity. 0 = no wanted level.
+     */
+    wantedLevel: number;
+
+    /**
+     * The `Vehicle` the player is currently inside, or `null` if on foot.
+     * Alias for `occupiedVehicle` with better naming for players.
+     */
+    vehicle: Vehicle | null;
+
+    /**
+     * Player's current money amount.
+     * Positive values represent dollars the player has.
+     */
+    money: number;
+
+    /**
+     * Whether the player is currently sitting inside a vehicle.
+     * Convenience property — equivalent to checking `vehicle !== null`.
+     */
+    isInVehicle: boolean;
+
+    /**
+     * Whether the player is invincible (cannot take damage).
+     */
+    invincible: boolean;
+
+    /**
+     * Currently equipped weapon ID.
+     * 0 = unarmed/fists. See the Weapon enum for IDs.
+     */
+    weapon: number;
+
+    /**
+     * Array of all weapon IDs the player currently owns.
+     * Does not include ammo counts — use `getWeaponAmmunition()` for that.
+     */
+    weapons: number[];
+
+    /**
+     * Primary player colour (used on the radar blip and name tag).
+     */
+    colour1: number;
+
+    /**
+     * Secondary player colour (used for the blip border).
+     */
+    colour2: number;
+
+    /**
+     * Gives a weapon to the player with the specified ammunition.
+     *
+     * @param weaponId - Weapon ID to give (see Weapon enum).
+     * @param ammo - Amount of ammunition to provide.
+     * @param equip - If `true`, the weapon is immediately equipped.
+     *
+     * @example
+     * // Give the player a loaded M4 rifle and equip it
+     * player.giveWeapon(26, 200, true);
+     */
+    giveWeapon(weaponId: number, ammo: number, equip: boolean): void;
+
+    /**
+     * Returns the remaining ammunition count for a given weapon.
+     *
+     * @param weapon - Weapon ID to query.
+     * @returns Ammo count, or `0` if the player does not own the weapon.
+     */
+    getWeaponAmmunition(weapon: number): number;
+
+    /**
+     * Sets the ammunition count for a given weapon.
+     * The player must already own the weapon.
+     *
+     * @param weapon - Weapon ID to modify.
+     * @param ammo - New ammunition count.
+     */
+    setWeaponAmmunition(weapon: number, ammo: number): void;
+
+    /**
+     * Respawns the player at their designated spawn point.
+     * If no spawn point has been set, the default spawn location is used.
+     *
+     * @example
+     * // Respawn a dead player
+     * if (player.health <= 0) {
+     *     player.health = 100;
+     *     player.spawn();
+     * }
+     */
+    spawn(): void;
+}
+
+/**
+ * Vehicle — a driveable vehicle with colours, damage states, doors, wheels,
+ * and occupant support.
+ *
+ * Vehicles are the primary transportation method in GTA. They have health,
+ * engine state, door/wheel damage, towing/trailer capabilities, and can hold
+ * multiple occupants.
+ *
+ * @extends Physical
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Lock a vehicle and turn off its engine
+ * function immobilizeVehicle(veh: Vehicle): void {
+ *     veh.isLocked = true;
+ *     veh.engineState = false;
+ * }
+ */
+interface Vehicle extends Physical {
+    /**
+     * GTA model index identifying the vehicle type (e.g. Infernus = 141).
+     * See the VehicleModel enum for named constants.
+     */
+    modelIndex: number;
+
+    /**
+     * Primary vehicle colour ID (0–255).
+     * Maps to the car colour palette defined in carcols.dat.
+     */
+    color1: number;
+
+    /**
+     * Secondary vehicle colour ID (0–255).
+     */
+    color2: number;
+
+    /**
+     * Primary vehicle colour ID (alias for `color1`).
+     */
+    colour1: number;
+
+    /**
+     * Secondary vehicle colour ID (alias for `color2`).
+     */
+    colour2: number;
+
+    /**
+     * Tertiary colour ID. Used by some vehicle models with three-colour schemes.
+     */
+    color3: number;
+
+    /**
+     * Quaternary colour ID. Used by some vehicle models with four-colour schemes.
+     */
+    color4: number;
+
+    /**
+     * Array of door state values, indexed by door position.
+     * See `AUTOMOBILEDOORSTATUS_*` constants for possible values.
+     */
+    doorStates: number[];
+
+    /**
+     * Engine health value.
+     * When this reaches 0, the engine catches fire and the vehicle explodes.
+     */
+    engineHealth: number;
+
+    /**
+     * Whether the engine is currently running.
+     * `true` = engine on, `false` = engine off.
+     */
+    engineState: boolean;
+
+    /**
+     * Yaw heading of the vehicle in degrees.
+     */
+    heading: number;
+
+    /**
+     * Vehicle body health value.
+     * 1000 = full health, 0 = destroyed. Visual damage appears below 500.
+     */
+    health: number;
+
+    /**
+     * Whether the vehicle doors are locked.
+     * Locked vehicles cannot be entered by players.
+     */
+    isLocked: boolean;
+
+    /**
+     * Whether the police siren is active.
+     */
+    isSirenOn: boolean;
+
+    /**
+     * Light state of the vehicle's headlights.
+     * 0 = off, 1 = on.
+     */
+    lights: number;
+
+    /**
+     * Number of occupants currently inside the vehicle.
+     */
+    occupantCount: number;
+
+    /**
+     * Paint job ID (for vehicles that support custom paint jobs, e.g. lowriders).
+     */
+    paintJob: number;
+
+    /**
+     * Licence plate text displayed on the vehicle.
+     * Max 8 characters.
+     */
+    plateText: string;
+
+    /**
+     * The `Vehicle` being towed by this vehicle, or `null` if not towing.
+     */
+    towingVehicle: Vehicle | null;
+
+    /**
+     * The `Vehicle` acting as a trailer attached to this vehicle, or `null`.
+     */
+    trailer: Vehicle | null;
+
+    /**
+     * Array of wheel state values, indexed by wheel position.
+     * States indicate normal, burst, or missing wheels.
+     */
+    wheelStates: number[];
+
+    /**
+     * Returns all `Player` entities currently occupying this vehicle.
+     *
+     * @returns Array of `Player` in the vehicle (includes driver and passengers).
+     *
+     * @example
+     * // Kick everyone out of a vehicle
+     * vehicle.getOccupants().forEach(p => {
+     *     p.vehicle = null;
+     * });
+     */
+    getOccupants(): Player[];
+}
+
+/**
+ * Train — a vehicle that follows train tracks with connected carriages.
+ *
+ * Trains are special vehicles constrained to rail paths. They can have multiple
+ * connected carriage elements and follow predefined track routes.
+ *
+ * @extends Vehicle
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+interface Train extends Vehicle {
+    /**
+     * Whether this vehicle is a train (always `true` for `Train` instances).
+     */
+    isTrain: boolean;
+
+    /**
+     * Array of connected train carriages attached to this train engine.
+     */
+    carriage: Train[];
+
+    /**
+     * Track ID identifying which rail route this train follows.
+     * Track definitions are loaded from the game's path files.
+     */
+    track: number;
+}
+
+/**
+ * Blip — a radar icon displayed on the minimap.
+ *
+ * Blips represent points of interest on the player's radar/minimap.
+ * They can be positioned at fixed coordinates or attached to elements.
+ *
+ * @extends Element
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a blip at some world coordinates
+ * const blip = gta.createBlip(new Vec3(100, 200, 10), 0);
+ */
+interface Blip extends Element {}
+
+/**
+ * Marker — a 3D world marker (checkpoint, arrow, cylinder, etc.).
+ *
+ * Markers are visible 3D indicators in the game world. They can be used as
+ * checkpoints, arrows pointing to locations, or navigation guides.
+ *
+ * @extends Element
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a red checkpoint marker
+ * const marker = gta.createMarker(0, 0, 10, 0, 1, 255, 0, 0, 255);
+ */
+interface Marker extends Element {
+    /**
+     * Marker colour as an RGBA tuple (red, green, blue, alpha; 0–255 each).
+     */
+    color: RGBA;
+
+    /**
+     * Target world position this marker should point toward (for arrow-type markers).
+     */
+    targetPosition: Vec3;
+
+    /**
+     * Marker type ID determining the marker's visual shape.
+     * Common types: cylinder, arrow, checkpoint ring, etc.
+     */
+    type: number;
+
+    /**
+     * Whether the marker is currently visible to players.
+     */
+    visible: boolean;
+}
+
+/**
+ * Pickup — a collectible item placed in the game world.
+ *
+ * Pickups are spawned items (weapons, health, armour, money, bribes, etc.)
+ * that are collected when a player walks over them. Some pickups respawn
+ * after a set delay.
+ *
+ * @extends Element
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a health pickup
+ * const healthPickup = gta.createPickup(366, 1, 0, 0, 10);
+ */
+interface Pickup extends Element {
+    /**
+     * Amount of ammunition or quantity provided when this pickup is collected.
+     * For weapon pickups, this is the ammo count.
+     */
+    amount: number;
+
+    /**
+     * Ammunition count provided by this pickup.
+     * Synonym for `amount` — used in weapon pickup contexts.
+     */
+    amu: number;
+
+    /**
+     * Whether this pickup respawns after being collected.
+     * `true` = respawn after a delay, `false` = one-time pickup.
+     */
+    respawns: boolean;
+
+    /**
+     * Pickup type ID determining what kind of item this is.
+     * See PickupType enum for possible values (weapon, health, armour, etc.).
+     */
+    type: number;
+
+    /**
+     * Quantity of the item provided by this pickup.
+     * For money pickups, this is the dollar amount.
+     */
+    quantity: number;
+}
+
+/**
+ * Sphere — an invisible 3D trigger zone with a position and radius.
+ *
+ * Spheres are used to detect when players/peds/vehicles enter a defined area.
+ * Created via `gta.createSphere()`. They fire enter/exit events when entities
+ * cross the sphere boundary.
+ *
+ * @extends Element
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a trigger zone and listen for entry
+ * const zone = gta.createSphere(new Vec3(0, 0, 10), 5.0);
+ * addEventHandler("OnElementStreamIn", function(el) {
+ *     message("Element entered the zone!");
+ * });
+ */
+interface Sphere extends Element {}