gtac-types 0.0.1

package/src/types/vec.d.ts

@@ -0,0 +1,594 @@
+/**
+ * GTAC Vector, Matrix, and Colour Type Definitions
+ *
+ * Defines mathematical types used throughout GTA Connected: 2D and 3D vectors
+ * (`Vec2`, `Vec3`), 4x4 transformation matrices (`Matrix4x4`), colour tuples
+ * (`RGB`, `RGBA`), and network synchronisation flags (`NetFlags`).
+ *
+ * Vectors support common operations: addition, subtraction, multiplication,
+ * division (all component-wise), dot product, cross product (Vec3 only),
+ * normalization, length/magnitude, distance, and linear interpolation.
+ * Static helper objects (`vec2`, `vec3`, `matrix4x4`) provide functional-style
+ * alternatives to the class instance methods.
+ *
+ * All declarations are global — no import required.
+ *
+ * @module types/vec
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create positions and calculate distance
+ * const pos1 = new Vec3(0, 0, 10);
+ * const pos2 = new Vec3(100, 50, 10);
+ * const dist = pos1.distance(pos2);
+ * message("Distance: " + dist + " units");
+ *
+ * @example
+ * // Linear interpolation for smooth movement
+ * const start = vec3.create(0, 0, 0);
+ * const end = vec3.create(100, 0, 0);
+ * const mid = vec3.lerp(start, end, 0.5); // (50, 0, 0)
+ */
+
+// ===== Primitives =====
+
+/**
+ * Red-Green-Blue colour tuple.
+ * Each component is in the range 0–255.
+ *
+ * @example
+ * const red: RGB = [255, 0, 0];
+ */
+type RGB = [number, number, number];
+
+/**
+ * Red-Green-Blue-Alpha colour tuple.
+ * Each component is in the range 0–255, where alpha 0 = fully transparent
+ * and alpha 255 = fully opaque.
+ *
+ * @example
+ * const semiTransparentRed: RGBA = [255, 0, 0, 128];
+ */
+type RGBA = [number, number, number, number];
+
+// ===== Vec2 =====
+
+/**
+ * 2D vector with `x` and `y` components.
+ *
+ * Represents a point or direction in 2D space. Provides instance methods for
+ * arithmetic operations, magnitude calculation, normalization, and dot product.
+ * Use `vec2.create()` or `new Vec2(x, y)` to construct.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Add two 2D vectors
+ * const a = new Vec2(10, 20);
+ * const b = new Vec2(5, 15);
+ * const result = a.add(b); // Vec2(15, 35)
+ */
+declare class Vec2 {
+    /** Horizontal component. */
+    x: number;
+
+    /** Vertical component. */
+    y: number;
+
+    /**
+     * Constructs a new 2D vector.
+     *
+     * @param x - Horizontal component.
+     * @param y - Vertical component.
+     */
+    constructor(x: number, y: number);
+
+    /**
+     * Adds another Vec2 to this one, component-wise.
+     *
+     * @param other - The vector to add.
+     * @returns A new `Vec2` representing the sum.
+     */
+    add(other: Vec2): Vec2;
+
+    /**
+     * Subtracts another Vec2 from this one, component-wise.
+     *
+     * @param other - The vector to subtract.
+     * @returns A new `Vec2` representing the difference.
+     */
+    sub(other: Vec2): Vec2;
+
+    /**
+     * Multiplies this Vec2 by another, component-wise (Hadamard product).
+     * For scalar multiplication, use `mul(new Vec2(scalar, scalar))`.
+     *
+     * @param other - The vector to multiply by.
+     * @returns A new `Vec2` representing the product.
+     */
+    mul(other: Vec2): Vec2;
+
+    /**
+     * Divides this Vec2 by another, component-wise.
+     *
+     * @param other - The vector to divide by.
+     * @returns A new `Vec2` representing the quotient.
+     */
+    div(other: Vec2): Vec2;
+
+    /**
+     * Computes the Euclidean magnitude (length) of this vector.
+     *
+     * @returns The length: `sqrt(x*x + y*y)`.
+     */
+    length(): number;
+
+    /**
+     * Returns a normalized copy of this vector (unit length = 1).
+     * The direction is preserved; only the magnitude changes.
+     *
+     * @returns A new `Vec2` with the same direction and length 1.
+     */
+    normalize(): Vec2;
+
+    /**
+     * Computes the dot (scalar) product of this vector and another.
+     * Dot product is positive if vectors point in similar directions,
+     * zero if perpendicular, negative if opposite.
+     *
+     * @param other - The other vector.
+     * @returns The dot product: `x*other.x + y*other.y`.
+     */
+    dot(other: Vec2): number;
+}
+
+/**
+ * Static helper functions for `Vec2` operations.
+ *
+ * Provides functional-style alternatives to the `Vec2` instance methods.
+ * Pass two vectors to operate on, or one vector for unary operations.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * const result = vec2.add(vec2.create(1, 2), vec2.create(3, 4));
+ */
+declare var vec2: {
+    /**
+     * Creates a new `Vec2` with the given components.
+     * Equivalent to `new Vec2(x, y)`.
+     *
+     * @param x - Horizontal component.
+     * @param y - Vertical component.
+     * @returns A new `Vec2`.
+     */
+    create(x: number, y: number): Vec2;
+
+    /**
+     * Adds two Vec2s component-wise.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns A new `Vec2` representing `a + b`.
+     */
+    add(a: Vec2, b: Vec2): Vec2;
+
+    /**
+     * Subtracts `b` from `a` component-wise.
+     *
+     * @param a - First vector.
+     * @param b - Vector to subtract.
+     * @returns A new `Vec2` representing `a - b`.
+     */
+    sub(a: Vec2, b: Vec2): Vec2;
+
+    /**
+     * Multiplies two Vec2s component-wise.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns A new `Vec2` representing the Hadamard product.
+     */
+    mul(a: Vec2, b: Vec2): Vec2;
+
+    /**
+     * Divides `a` by `b` component-wise.
+     *
+     * @param a - Numerator vector.
+     * @param b - Denominator vector.
+     * @returns A new `Vec2` representing `a / b`.
+     */
+    div(a: Vec2, b: Vec2): Vec2;
+
+    /**
+     * Computes the Euclidean magnitude of a Vec2.
+     *
+     * @param v - The input vector.
+     * @returns The length: `sqrt(v.x*v.x + v.y*v.y)`.
+     */
+    length(v: Vec2): number;
+
+    /**
+     * Normalizes a Vec2 to unit length.
+     *
+     * @param v - The input vector.
+     * @returns A new `Vec2` with magnitude 1 and the same direction.
+     */
+    normalize(v: Vec2): Vec2;
+
+    /**
+     * Computes the dot product of two Vec2s.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns The dot product scalar.
+     */
+    dot(a: Vec2, b: Vec2): number;
+};
+
+// ===== Vec3 =====
+
+/**
+ * 3D vector with `x`, `y`, and `z` components.
+ *
+ * Represents a point, direction, or offset in 3D space. Supports all Vec2
+ * operations plus cross product, Euclidean distance, and linear interpolation.
+ * Accessible via numeric index as well as named properties.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Calculate cross product for surface normals
+ * const up = new Vec3(0, 0, 1);
+ * const forward = new Vec3(1, 0, 0);
+ * const right = up.cross(forward); // (0, 1, 0)
+ *
+ * @example
+ * // Smoothly interpolate between two positions
+ * const from = new Vec3(0, 0, 10);
+ * const to = new Vec3(100, 0, 10);
+ * // Move 30% of the way
+ * const step = from.lerp(to, 0.3);
+ */
+declare class Vec3 {
+    /**
+     * Numeric index access: `vec[0]` = x, `vec[1]` = y, `vec[2]` = z.
+     */
+    [index: number]: number;
+
+    /** Horizontal (east-west) component. */
+    x: number;
+
+    /** Vertical (north-south) component. */
+    y: number;
+
+    /** Elevation (up-down) component. */
+    z: number;
+
+    /**
+     * Constructs a new 3D vector.
+     *
+     * @param x - Horizontal component.
+     * @param y - Vertical component.
+     * @param z - Elevation component.
+     */
+    constructor(x: number, y: number, z: number);
+
+    /**
+     * Adds another Vec3 to this one, component-wise.
+     *
+     * @param other - The vector to add.
+     * @returns A new `Vec3` representing the sum.
+     */
+    add(other: Vec3): Vec3;
+
+    /**
+     * Subtracts another Vec3 from this one, component-wise.
+     *
+     * @param other - The vector to subtract.
+     * @returns A new `Vec3` representing the difference.
+     */
+    sub(other: Vec3): Vec3;
+
+    /**
+     * Multiplies this Vec3 by another, component-wise (Hadamard product).
+     *
+     * @param other - The vector to multiply by.
+     * @returns A new `Vec3` representing the product.
+     */
+    mul(other: Vec3): Vec3;
+
+    /**
+     * Divides this Vec3 by another, component-wise.
+     *
+     * @param other - The vector to divide by.
+     * @returns A new `Vec3` representing the quotient.
+     */
+    div(other: Vec3): Vec3;
+
+    /**
+     * Computes the Euclidean magnitude (length) of this vector.
+     *
+     * @returns The length: `sqrt(x*x + y*y + z*z)`.
+     */
+    length(): number;
+
+    /**
+     * Returns a normalized copy of this vector (unit length = 1).
+     *
+     * @returns A new `Vec3` with the same direction and magnitude 1.
+     */
+    normalize(): Vec3;
+
+    /**
+     * Computes the dot (scalar) product of this vector and another.
+     *
+     * @param other - The other vector.
+     * @returns The dot product: `x*other.x + y*other.y + z*other.z`.
+     */
+    dot(other: Vec3): number;
+
+    /**
+     * Computes the cross product of this vector and another.
+     * The result is perpendicular to both input vectors.
+     *
+     * @param other - The other vector.
+     * @returns A new `Vec3` perpendicular to both inputs.
+     */
+    cross(other: Vec3): Vec3;
+
+    /**
+     * Computes the Euclidean distance between this vector and another.
+     *
+     * @param other - The target vector to measure distance to.
+     * @returns The distance between the two vectors.
+     */
+    distance(other: Vec3): number;
+
+    /**
+     * Linearly interpolates towards another vector by a given factor.
+     *
+     * @param other - The target vector.
+     * @param t - Interpolation factor (0.0 = this vector, 1.0 = other vector).
+     * @returns A new `Vec3` representing the interpolated position.
+     */
+    lerp(other: Vec3, t: number): Vec3;
+}
+
+/**
+ * Static helper functions for `Vec3` operations.
+ *
+ * Provides functional-style alternatives to the `Vec3` instance methods.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * const midpoint = vec3.lerp(posA, posB, 0.5);
+ */
+declare var vec3: {
+    /**
+     * Creates a new `Vec3` with the given components.
+     * Equivalent to `new Vec3(x, y, z)`.
+     *
+     * @param x - Horizontal component.
+     * @param y - Vertical component.
+     * @param z - Elevation component.
+     * @returns A new `Vec3`.
+     */
+    create(x: number, y: number, z: number): Vec3;
+
+    /**
+     * Adds two Vec3s component-wise.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns A new `Vec3` representing `a + b`.
+     */
+    add(a: Vec3, b: Vec3): Vec3;
+
+    /**
+     * Subtracts `b` from `a` component-wise.
+     *
+     * @param a - First vector.
+     * @param b - Vector to subtract.
+     * @returns A new `Vec3` representing `a - b`.
+     */
+    sub(a: Vec3, b: Vec3): Vec3;
+
+    /**
+     * Multiplies two Vec3s component-wise.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns A new `Vec3` representing the Hadamard product.
+     */
+    mul(a: Vec3, b: Vec3): Vec3;
+
+    /**
+     * Divides `a` by `b` component-wise.
+     *
+     * @param a - Numerator vector.
+     * @param b - Denominator vector.
+     * @returns A new `Vec3` representing `a / b`.
+     */
+    div(a: Vec3, b: Vec3): Vec3;
+
+    /**
+     * Computes the Euclidean magnitude of a Vec3.
+     *
+     * @param v - The input vector.
+     * @returns The length.
+     */
+    length(v: Vec3): number;
+
+    /**
+     * Normalizes a Vec3 to unit length.
+     *
+     * @param v - The input vector.
+     * @returns A new `Vec3` with magnitude 1.
+     */
+    normalize(v: Vec3): Vec3;
+
+    /**
+     * Computes the dot product of two Vec3s.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns The dot product scalar.
+     */
+    dot(a: Vec3, b: Vec3): number;
+
+    /**
+     * Computes the cross product of two Vec3s.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns A new `Vec3` perpendicular to both inputs.
+     */
+    cross(a: Vec3, b: Vec3): Vec3;
+
+    /**
+     * Computes the Euclidean distance between two Vec3s.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns The distance between `a` and `b`.
+     */
+    distance(a: Vec3, b: Vec3): number;
+
+    /**
+     * Linearly interpolates between two Vec3s by factor `t`.
+     *
+     * @param a - Start vector (t = 0).
+     * @param b - End vector (t = 1).
+     * @param t - Interpolation factor (0.0 to 1.0).
+     * @returns A new `Vec3` representing the interpolated position.
+     */
+    lerp(a: Vec3, b: Vec3, t: number): Vec3;
+};
+
+// ===== Matrix4x4 =====
+
+/**
+ * 4x4 transformation matrix for 3D transformations.
+ *
+ * Used to represent combined translation, rotation, and scaling in a single
+ * mathematical structure. The internal representation is engine-defined (opaque).
+ * Use `matrix4x4` static helpers to create and manipulate matrices.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+type Matrix4x4 = {}
+
+/**
+ * Static helper functions for `Matrix4x4` creation and manipulation.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a translation matrix and apply it
+ * const trans = matrix4x4.translation(10, 0, 0);
+ * const rot = matrix4x4.rotation(0, 0, 90);
+ * const combined = matrix4x4.mul(rot, trans);
+ */
+declare var matrix4x4: {
+    /**
+     * Creates a new identity matrix (no transformation).
+     * An identity matrix has 1s on the diagonal and 0s elsewhere.
+     *
+     * @returns A new identity `Matrix4x4`.
+     */
+    create(): Matrix4x4;
+
+    /**
+     * Creates a rotation matrix from Euler angles (in degrees).
+     *
+     * @param x - Rotation around the X axis (pitch) in degrees.
+     * @param y - Rotation around the Y axis (yaw) in degrees.
+     * @param z - Rotation around the Z axis (roll) in degrees.
+     * @returns A new rotation `Matrix4x4`.
+     */
+    rotation(x: number, y: number, z: number): Matrix4x4;
+
+    /**
+     * Creates a translation (position offset) matrix.
+     *
+     * @param x - X-axis translation.
+     * @param y - Y-axis translation.
+     * @param z - Z-axis translation.
+     * @returns A new translation `Matrix4x4`.
+     */
+    translation(x: number, y: number, z: number): Matrix4x4;
+
+    /**
+     * Multiplies two matrices (applies `m2` after `m1`).
+     * Order matters: `mul(m1, m2)` = `m2 * m1` in standard math notation.
+     *
+     * @param m1 - First matrix (applied first).
+     * @param m2 - Second matrix (applied second).
+     * @returns A new `Matrix4x4` representing the product.
+     */
+    mul(m1: Matrix4x4, m2: Matrix4x4): Matrix4x4;
+
+    /**
+     * Computes the inverse of a matrix.
+     * Multiplying a matrix by its inverse yields the identity matrix.
+     *
+     * @param m - The matrix to invert.
+     * @returns The inverse `Matrix4x4`.
+     */
+    inverse(m: Matrix4x4): Matrix4x4;
+
+    /**
+     * Computes the transpose of a matrix (flips rows and columns).
+     *
+     * @param m - The matrix to transpose.
+     * @returns The transposed `Matrix4x4`.
+     */
+    transpose(m: Matrix4x4): Matrix4x4;
+
+    /**
+     * Creates a new identity matrix (same as `create()`).
+     *
+     * @returns A new identity `Matrix4x4`.
+     */
+    identity(): Matrix4x4;
+};
+
+// ===== NetFlags =====
+
+/**
+ * Network synchronisation flags for elements.
+ *
+ * Controls how an element's position, rotation, and state are synchronised
+ * between the server and connected clients. Adjust interpolation mode and
+ * sync rate to balance network bandwidth against visual smoothness.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Configure an element to sync at 50ms intervals
+ * element.netFlags.syncRate = 50;
+ * element.netFlags.interpolation = 1; // Linear interpolation
+ */
+interface NetFlags {
+    /**
+     * Bitfield of synchronisation flags.
+     * Each bit enables or disables a specific sync feature (position, rotation,
+     * velocity, etc.).
+     */
+    syncFlags: number;
+
+    /**
+     * Interpolation mode determining how positions between sync updates are smoothed.
+     * 0 = no interpolation (snap), 1 = linear interpolation, etc.
+     */
+    interpolation: number;
+
+    /**
+     * Synchronisation rate in milliseconds.
+     * Lower values = more frequent updates = smoother but more bandwidth.
+     * Higher values = less frequent = more bandwidth-efficient but potentially jittery.
+     */
+    syncRate: number;
+}