gtac-types 0.0.1

package/src/types/event.d.ts

@@ -0,0 +1,100 @@
+/**
+ * GTAC Event Type Definitions
+ *
+ * Defines the base event system types used throughout GTA Connected.
+ * Events are dispatched by the engine when in-game actions occur (key presses,
+ * player connections, element creation, etc.). Some events can be cancelled
+ * to prevent their default behaviour.
+ *
+ * @module types/event
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Listen for a key press and cancel it if it's the escape key
+ * bindKey("Escape", function(event: KeyEvent) {
+ *     if (event.key === 27) {
+ *         message("Escape was pressed!");
+ *     }
+ * });
+ */
+
+// ===== Events =====
+
+/**
+ * Base event type — all specific event interfaces extend this type.
+ *
+ * This is the root of the event hierarchy. It carries no properties of its own
+ * but serves as the common type for event-related overloads and generic handlers.
+ */
+type Event = {}
+
+/**
+ * An event whose default behaviour can be cancelled.
+ *
+ * Cancellable events allow handlers to call `preventDefault()` to stop the
+ * engine from performing its built-in response. For example, cancelling a
+ * `OnPedWasted` event can prevent the ped from actually dying.
+ *
+ * @extends Event
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Prevent a player from dying
+ * addEventHandler("OnPedWasted", function(event: CancellableEvent, ped: Ped) {
+ *     if (isImportantPed(ped)) {
+ *         event.preventDefault(); // Ped will not die
+ *     }
+ * });
+ */
+interface CancellableEvent extends Event {
+    /**
+     * Has this event's default behaviour been prevented?
+     *
+     * @returns `true` if `preventDefault()` has been called on this event.
+     */
+    isDefaultPrevented(): boolean;
+
+    /**
+     * Prevents the engine's default behaviour for this event.
+     *
+     * After calling this, the engine will not perform the action it normally would.
+     * For example, preventing the `OnPedWasted` default stops the ped from dying.
+     * Does not prevent other event handlers from running.
+     */
+    preventDefault(): void;
+}
+
+/**
+ * A keyboard key event dispatched when a bound key is pressed or released.
+ *
+ * Key events carry the key code and whether the event is a key-up (release)
+ * or key-down (press). Use `bindKey()` to register key bindings that will
+ * fire these events.
+ *
+ * @extends Event
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Toggle the chat window with the T key
+ * bindKey("T", function(event: KeyEvent) {
+ *     if (event.isUp()) return; // Only handle key-down
+ *     chatWindowEnabled(!isChatOpen);
+ * });
+ */
+interface KeyEvent extends Event {
+    /**
+     * Determines whether this event represents a key release (key-up) as
+     * opposed to a key press (key-down).
+     *
+     * @returns `true` if the key was released (key-up event), `false` if pressed.
+     */
+    isUp(): boolean;
+
+    /**
+     * The numeric key code identifying which key triggered this event.
+     *
+     * Key codes correspond to the standard virtual key codes:
+     * 27 = Escape, 13 = Enter, 32 = Space, etc.
+     */
+    key: number;
+}

package/src/types/misc.d.ts

@@ -0,0 +1,256 @@
+/**
+ * GTAC Shared Constant Defines
+ *
+ * Predefined numeric constants available globally in every GTA Connected script.
+ * These cover common colours, element type identifiers, GTA entity types,
+ * chat message types, and camera fade directions.
+ *
+ * All constants are declared as `var` globals — no import required.
+ *
+ * @module types/misc
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Check if an element is a player
+ * if (element.type === ELEMENT_PLAYER) {
+ *     message("Found a player!");
+ * }
+ *
+ * @example
+ * // Fade the camera in using a predefined constant
+ * gta.fadeCamera(FADE_IN, 1000);
+ */
+
+// ===== Shared Defines =====
+
+// ===== Colour Constants =====
+
+/**
+ * ARGB colour constant: fully transparent (alpha = 0).
+ * Useful for creating invisible elements or clearing colour values.
+ */
+declare var COLOUR_TRANSPARENT: number;
+
+/**
+ * ARGB colour constant: solid red (0xFFFF0000).
+ */
+declare var COLOUR_RED: number;
+
+/**
+ * ARGB colour constant: solid green (0xFF00FF00).
+ */
+declare var COLOUR_GREEN: number;
+
+/**
+ * ARGB colour constant: solid lime green (0xFF00FF00).
+ */
+declare var COLOUR_LIME: number;
+
+/**
+ * ARGB colour constant: solid blue (0xFF0000FF).
+ */
+declare var COLOUR_BLUE: number;
+
+/**
+ * ARGB colour constant: solid aqua/cyan (0xFF00FFFF).
+ */
+declare var COLOUR_AQUA: number;
+
+/**
+ * ARGB colour constant: solid fuchsia/magenta (0xFFFF00FF).
+ */
+declare var COLOUR_FUCHSIA: number;
+
+/**
+ * ARGB colour constant: solid yellow (0xFFFFFF00).
+ */
+declare var COLOUR_YELLOW: number;
+
+/**
+ * ARGB colour constant: solid orange (0xFFFFA500).
+ */
+declare var COLOUR_ORANGE: number;
+
+/**
+ * ARGB colour constant: solid white (0xFFFFFFFF).
+ */
+declare var COLOUR_WHITE: number;
+
+/**
+ * ARGB colour constant: solid black (0xFF000000).
+ */
+declare var COLOUR_BLACK: number;
+
+/**
+ * ARGB colour constant: silver/grey (0xFFC0C0C0).
+ */
+declare var COLOUR_SILVER: number;
+
+/**
+ * ARGB colour constant: sky blue (0xFF87CEEB).
+ */
+declare var COLOUR_SKYBLUE: number;
+
+// ===== Element Type Constants =====
+
+/**
+ * Generic/base element type constant.
+ * Used to identify the root `Element` type — all elements are at least this type.
+ */
+declare var ELEMENT_ELEMENT: number;
+
+/**
+ * Transformable element type constant.
+ * Elements that can be transformed (moved/rotated/scaled) fall under this category.
+ */
+declare var ELEMENT_TRANSFORMABLE: number;
+
+/**
+ * Entity element type constant.
+ * Identifies `Entity` instances — elements with heading, bounding volumes, and collision data.
+ */
+declare var ELEMENT_ENTITY: number;
+
+/**
+ * Physical element type constant.
+ * Identifies `Physical` instances — entities with mass, velocity, gravity, and physics.
+ */
+declare var ELEMENT_PHYSICAL: number;
+
+/**
+ * Ped element type constant.
+ * Identifies `Ped` instances — character entities with health, armour, and vehicle occupancy.
+ */
+declare var ELEMENT_PED: number;
+
+/**
+ * Civilian ped element type constant.
+ * Identifies `Ped` instances that are specifically civilian (non-player, non-cop) characters.
+ */
+declare var ELEMENT_CIVILIAN: number;
+
+/**
+ * Player element type constant.
+ * Identifies `Player` instances — peds controlled by connected clients.
+ */
+declare var ELEMENT_PLAYER: number;
+
+/**
+ * Vehicle element type constant.
+ * Identifies `Vehicle` instances — driveable vehicle entities.
+ */
+declare var ELEMENT_VEHICLE: number;
+
+/**
+ * Blip element type constant.
+ * Identifies `Blip` instances — radar/minimap icons.
+ */
+declare var ELEMENT_BLIP: number;
+
+/**
+ * Object element type constant.
+ * Identifies `Object` instances — placeable physical items with a model.
+ */
+declare var ELEMENT_OBJECT: number;
+
+/**
+ * Train element type constant.
+ * Identifies `Train` instances — vehicles constrained to rail tracks.
+ */
+declare var ELEMENT_TRAIN: number;
+
+/**
+ * Pickup element type constant.
+ * Identifies `Pickup` instances — collectible items in the world.
+ */
+declare var ELEMENT_PICKUP: number;
+
+/**
+ * Marker element type constant.
+ * Identifies `Marker` instances — 3D world markers (checkpoints, arrows).
+ */
+declare var ELEMENT_MARKER: number;
+
+/**
+ * Building element type constant.
+ * Identifies `Building` instances — static world geometry elements.
+ */
+declare var ELEMENT_BUILDING: number;
+
+// ===== GTA Entity Type Constants =====
+
+/**
+ * GTA entity type: building.
+ * Low-level engine classification for building/static geometry entities.
+ */
+declare var ENTITYTYPE_BUILDING: number;
+
+/**
+ * GTA entity type: vehicle.
+ * Low-level engine classification for vehicle entities.
+ */
+declare var ENTITYTYPE_VEHICLE: number;
+
+/**
+ * GTA entity type: ped.
+ * Low-level engine classification for pedestrian/character entities.
+ */
+declare var ENTITYTYPE_PED: number;
+
+/**
+ * GTA entity type: object.
+ * Low-level engine classification for dynamic object entities.
+ */
+declare var ENTITYTYPE_OBJECT: number;
+
+/**
+ * GTA entity type: object LOD (Level of Detail).
+ * Low-detail version of an object used for distant rendering.
+ */
+declare var ENTITYTYPE_OBJECT_LOD: number;
+
+// ===== Chat Type Constants =====
+
+/**
+ * Chat message type: none/unknown.
+ * Used when the chat message type is not explicitly set.
+ */
+declare var CHAT_TYPE_NONE: number;
+
+/**
+ * Chat message type: chat.
+ * Standard chat message sent by a player. Appears in the chat window.
+ */
+declare var CHAT_TYPE_CHAT: number;
+
+/**
+ * Chat message type: info.
+ * Informational system message. Typically styled differently from chat messages.
+ */
+declare var CHAT_TYPE_INFO: number;
+
+/**
+ * Chat message type: debug.
+ * Debug-level message used for development and troubleshooting output.
+ */
+declare var CHAT_TYPE_DEBUG: number;
+
+// ===== Camera Fade Constants =====
+
+/**
+ * Camera fade direction: fade out (scene goes dark).
+ *
+ * @example
+ * // Fade the screen to black over 2 seconds
+ * gta.fadeCamera(FADE_OUT, 2000);
+ */
+declare var FADE_OUT: number;
+
+/**
+ * Camera fade direction: fade in (scene becomes visible).
+ *
+ * @example
+ * // Reveal the screen from black over 1.5 seconds
+ * gta.fadeCamera(FADE_IN, 1500);
+ */
+declare var FADE_IN: number;

package/src/types/resource.d.ts

@@ -0,0 +1,252 @@
+/**
+ * GTAC Resource, Timer, and Runtime Type Definitions
+ *
+ * Defines the types for GTA Connected resources (loaded scripts), timers
+ * (scheduling), streams, reflected functions, and the global console API.
+ * These types bridge the SpiderMonkey JS engine with GTAC-specific runtime
+ * concepts.
+ *
+ * All declarations are global — no import/export required.
+ *
+ * @module types/resource
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Access the current resource's info
+ * console.log("Running resource: " + thisResource.name);
+ * console.log("Resource path: " + thisResource.path);
+ */
+
+// ===== Resource =====
+
+/**
+ * A loaded GTA Connected resource (script package).
+ *
+ * Resources are defined by a `meta.xml` manifest and contain server-side
+ * and/or client-side scripts. Each resource has a name, filesystem path,
+ * and a lifecycle state (running, stopped). Resources can be started, stopped,
+ * and restarted programmatically.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+interface Resource {
+    /**
+     * Resource name as defined in `meta.xml`.
+     * This is the unique identifier used to reference the resource.
+     */
+    name: string;
+
+    /**
+     * Absolute filesystem path to the resource's root directory.
+     * Use this to locate resource-local files.
+     */
+    path: string;
+
+    /**
+     * Current lifecycle state of the resource.
+     * Possible states: running, stopped, starting, stopping.
+     */
+    state: number;
+
+    /**
+     * Starts the resource if it is currently stopped.
+     * Has no effect if the resource is already running.
+     */
+    start(): void;
+
+    /**
+     * Stops the resource if it is currently running.
+     * Has no effect if the resource is already stopped.
+     */
+    stop(): void;
+
+    /**
+     * Restarts the resource (stops then starts it).
+     * Equivalent to calling `stop()` followed by `start()`.
+     */
+    restart(): void;
+}
+
+/**
+ * Global reference to the currently executing resource.
+ *
+ * Provides access to the `Resource` instance for the script currently running.
+ * Use this to get the resource's name, path, or to trigger lifecycle actions.
+ *
+ * @example
+ * console.log("Current resource: " + thisResource.name);
+ */
+declare var thisResource: Resource;
+
+// ===== Timer / Stream =====
+
+/**
+ * A native GTAC timer created via `setTimer()`.
+ *
+ * Unlike JavaScript's built-in `setInterval`/`setTimeout` which return numeric IDs,
+ * GTAC's `setTimer()` returns a `Timer` object that can be destroyed to stop the
+ * timer permanently.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a timer that fires 5 times, then stops
+ * const timer = setTimer(function() {
+ *     message("Tick!");
+ * }, 1000, 5);
+ *
+ * // Manually destroy it early
+ * timer.destroy();
+ */
+interface Timer {
+    /**
+     * Stops and permanently destroys the timer.
+     * After calling this, the timer's callback will never fire again.
+     */
+    destroy(): void;
+}
+
+/**
+ * A data stream handle (opaque type).
+ *
+ * Streams are used for binary data I/O and serialization.
+ * The internal structure is engine-defined and not directly accessible.
+ */
+type Stream = {}
+
+// ===== ReflectedFunction =====
+
+/**
+ * A function reference obtained via the reflection API (opaque type).
+ *
+ * ReflectedFunctions allow scripts to dynamically call functions by name
+ * or reference, supporting meta-programming patterns.
+ * The internal structure is engine-defined.
+ */
+type ReflectedFunction = {}
+
+// ===== Timer Functions =====
+
+/**
+ * Creates a repeating interval timer (mirrors the JavaScript standard API).
+ *
+ * The provided callback function will be called every `ms` milliseconds
+ * until `clearInterval()` is called with the returned timer ID.
+ *
+ * @param fn - Callback function invoked on each tick.
+ * @param ms - Interval duration in milliseconds between invocations.
+ * @returns A numeric timer ID for use with `clearInterval()`.
+ *
+ * @example
+ * // Log a message every 5 seconds
+ * const intervalId = setInterval(function() {
+ *     console.log("5 seconds passed");
+ * }, 5000);
+ *
+ * // Later, stop the interval
+ * clearInterval(intervalId);
+ */
+declare function setInterval(fn: () => void, ms: number): number;
+
+/**
+ * Creates a one-shot timer (mirrors the JavaScript standard API).
+ *
+ * The provided callback function will be called once after `ms` milliseconds.
+ *
+ * @param fn - Callback function to invoke after the delay.
+ * @param ms - Delay duration in milliseconds before invocation.
+ * @returns A numeric timer ID for use with `clearTimeout()`.
+ *
+ * @example
+ * // Show a message after 3 seconds
+ * setTimeout(function() {
+ *     message("Three seconds have passed!");
+ * }, 3000);
+ */
+declare function setTimeout(fn: () => void, ms: number): number;
+
+/**
+ * Clears a repeating interval previously created with `setInterval()`.
+ *
+ * @param id - The timer ID returned by `setInterval()`.
+ *
+ * @example
+ * const id = setInterval(myFn, 1000);
+ * clearInterval(id); // Stops the interval
+ */
+declare function clearInterval(id: number): void;
+
+/**
+ * Clears a one-shot timeout previously created with `setTimeout()`.
+ * Has no effect if the timeout has already fired.
+ *
+ * @param id - The timer ID returned by `setTimeout()`.
+ *
+ * @example
+ * const id = setTimeout(myFn, 5000);
+ * clearTimeout(id); // Cancels the timeout before it fires
+ */
+declare function clearTimeout(id: number): void;
+
+/**
+ * Creates a native GTAC timer that fires a specified number of times.
+ *
+ * Unlike `setInterval`, this returns a `Timer` object and supports a finite
+ * fire count. Set `count` to `0` for infinite repetition.
+ *
+ * @param func - Callback function invoked on each tick.
+ * @param interval - Interval in milliseconds between ticks.
+ * @param count - Number of times to fire (`0` = infinite).
+ * @returns A `Timer` object that can be destroyed with `killTimer()`.
+ *
+ * @example
+ * // Create a timer that fires exactly 10 times
+ * const timer = setTimer(function() {
+ *     message("Fire!");
+ * }, 500, 10);
+ *
+ * @example
+ * // Create an infinite timer (like setInterval but returns Timer)
+ * const timer = setTimer(function() {
+ *     updateGame();
+ * }, 16, 0);
+ */
+declare function setTimer(
+    func: () => void,
+    interval: number,
+    count: number
+): Timer;
+
+/**
+ * Destroys a native GTAC timer created with `setTimer()`.
+ *
+ * @param timer - The `Timer` object to destroy.
+ *
+ * @example
+ * const timer = setTimer(myFn, 1000, 0);
+ * // Later...
+ * killTimer(timer);
+ */
+declare function killTimer(timer: Timer): void;
+
+// ===== Console =====
+
+/**
+ * Server/client console logging API.
+ *
+ * Provides a `log()` method for printing messages to the server console
+ * or client debug output. Mirrors the standard JavaScript `console.log` API.
+ *
+ * @example
+ * console.log("Hello, GTAC!");
+ * console.log("Player count:", getPlayerCount());
+ */
+declare var console: {
+    /**
+     * Logs one or more values to the console output.
+     * Values are coerced to strings and joined with spaces.
+     *
+     * @param args - Any number of values to log.
+     */
+    log(...args: unknown[]): void;
+};