@cybermp/client-types 2.2.1 → 2.3.1

package/precomputed/local-storage.d.ts

@@ -1,9 +1,37 @@
-export interface MpLocalStorage {
-  set(key: string, value: string): void;
-  get(key: string): string;
-
-  delete(key: string): void;
-  deleteAll(): void;
-
-  save(): void;
-}
+/**
+ * Interface providing access to persistent client-side key-value storage.
+ * Data saved here remains available across different game sessions and server reconnections.
+ */
+export interface MpLocalStorage {
+  /**
+   * Associates a string value with a specific key in the storage database.
+   * If the key already exists, its value will be overwritten.
+   * @param key - The unique identifier name for the storage entry.
+   * @param value - The plaintext string data payload to be stored.
+   */
+  set(key: string, value: string): void;
+
+  /**
+   * Retrieves the stored string value associated with the specified key.
+   * @param key - The unique identifier name of the entry to fetch.
+   * @returns The stored string value, or an empty string/null if the key does not exist.
+   */
+  get(key: string): string;
+
+  /**
+   * Permanently removes a specific key-value entry from the storage map.
+   * @param key - The unique identifier name of the entry to delete.
+   */
+  delete(key: string): void;
+
+  /**
+   * Clears all keys and values currently held in this resource's local storage instance.
+   */
+  deleteAll(): void;
+
+  /**
+   * Explicitly flushes the current state of the in-memory storage data down to the physical disk.
+   * Use this to ensure volatile data isn't lost if the game client unexpectedly crashes.
+   */
+  save(): void;
+}

package/precomputed/local.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Manages local player lifecycle operations and the creation of client-side entities.
+ */
+export interface MpLocal {
+  /**
+   * Spawns local player
+   * @param x - Horizontal grid position coordinate value.
+   * @param y - Vertical grid position coordinate value.
+   * @param z - Height grid elevation coordinate value.
+   * @param yaw - The horizontal rotation layout angle in degrees.
+   * @returns `true` if the spawn lifecycle sequence initiated successfully, otherwise `false`.
+   */
+  spawnPlayer(x: number, y: number, z: number, yaw: number): boolean;
+
+  /**
+   * Instantiates a localized ped entity.
+   * This entity remains completely un-synchronized and invisible to other remote clients.
+   * @param skinHash - Asset model signature key hash.
+   * @param appHash - Visual appearance setup key components variation hash.
+   * @param x - Horizontal coordinate space.
+   * @param y - Vertical coordinate space.
+   * @param z - Elevation height space coordinate.
+   * @param yaw - Rotational alignment facing angle.
+   * @param streaming - Controls if engine virtualization automatically handles streaming boundaries tracking.
+   * @returns The resulting unique local game entity handle ID.
+   */
+  spawnPed(
+    skinHash: number | bigint,
+    appHash: number | bigint,
+    x: number,
+    y: number,
+    z: number,
+    yaw: number,
+    streaming: boolean,
+  ): number;
+
+  /**
+   * Instantiates a localized vehicle entity inside the engine environment.
+   * This entity remains completely un-synchronized and invisible to other remote clients.
+   * @param skinHash - Asset model signature key hash.
+   * @param appHash - Visual appearance setup key components variation hash.
+   * @param x - Horizontal coordinate space.
+   * @param y - Vertical coordinate space.
+   * @param z - Elevation height space coordinate.
+   * @param roll - Longitudinal rotation axis orientation angle.
+   * @param pitch - Lateral rotation axis orientation angle.
+   * @param yaw - Directional heading alignment angle.
+   * @param streaming - Controls if engine virtualization automatically handles streaming boundaries tracking.
+   * @returns The resulting unique local game entity handle ID.
+   */
+  spawnVehicle(
+    skinHash: number | bigint,
+    appHash: number | bigint,
+    x: number,
+    y: number,
+    z: number,
+    roll: number,
+    pitch: number,
+    yaw: number,
+    streaming: boolean,
+  ): number;
+
+  /**
+   * Instantiates a localized world object or dynamic prop entity inside the engine environment.
+   * This entity remains completely un-synchronized and invisible to other remote clients.
+   * @param skinHash - Asset model signature key hash.
+   * @param appHash - Visual appearance setup key components variation hash.
+   * @param x - Horizontal coordinate space.
+   * @param y - Vertical coordinate space.
+   * @param z - Elevation height space coordinate.
+   * @param roll - Longitudinal rotation axis orientation angle.
+   * @param pitch - Lateral rotation axis orientation angle.
+   * @param yaw - Directional heading alignment angle.
+   * @param streaming - Controls if engine virtualization automatically handles streaming boundaries tracking.
+   * @returns The resulting unique local game entity handle ID.
+   */
+  spawnObject(
+    skinHash: bigint | number,
+    appHash: bigint | number,
+    x: number,
+    y: number,
+    z: number,
+    roll: number,
+    pitch: number,
+    yaw: number,
+    streaming: boolean,
+  ): number;
+
+  /**
+   * Forces immediate engine de-allocation and cleanup deletion maps targeting an isolated local pedestrian.
+   * @param hash - Unique local game engine entity instance handle to clear.
+   */
+  despawnPed(hash: number): void;
+
+  /**
+   * Forces immediate engine de-allocation and cleanup deletion maps targeting an isolated local vehicle.
+   * @param hash - Unique local game engine entity instance handle to clear.
+   */
+  despawnVehicle(hash: number): void;
+
+  /**
+   * Forces immediate engine de-allocation and cleanup deletion maps targeting an isolated local object.
+   * @param hash - Unique local game engine entity instance handle to clear.
+   */
+  despawnObject(hash: number): void;
+}

package/precomputed/meta.d.ts

@@ -1,18 +1,78 @@
-export interface MpMeta {
-  setGlobalMeta(key: string, value: any, sync?: boolean): void;
-  getGlobalMeta<T = any>(key: string): T;
-
-  setPlayerMeta(
-    playerId: number,
-    key: string,
-    value: any,
-    sync?: boolean,
-  ): void;
-  getPlayerMeta<T = any>(playerId: number, key: string): T;
-
-  setLocalPlayerMeta(key: string, value: any, sync?: boolean): void;
-  getLocalPlayerMeta<T = any>(key: string): T;
-
-  setEntityMeta(netId: number, key: string, value: any, sync?: boolean): void;
-  getEntityMeta<T = any>(netId: number, key: string): T;
-}
+/**
+ * Interface managing cross-resource and synchronized state metadata across the network layer.
+ * Allows attaching arbitrary data structures to globals, specific players, the local player, or synchronized network entities.
+ */
+export interface MpMeta {
+  /**
+   * Sets a global metadata value accessible across the entire runtime environment.
+   * @param key - The unique identifier string for the metadata entry.
+   * @param value - The data payload to store (can be any serializable object or primitive).
+   * @param sync - Optional flag. If `true`, synchronizes this metadata across the network to all other clients.
+   */
+  setGlobalMeta(key: string, value: any, sync?: boolean): void;
+
+  /**
+   * Retrieves a global metadata value by its key.
+   * @template T - The expected type of the returned metadata value.
+   * @param key - The unique identifier string of the metadata entry to look up.
+   * @returns The stored global metadata value cast to type T, or undefined if it does not exist.
+   */
+  getGlobalMeta<T = any>(key: string): T;
+
+  /**
+   * Assigns a metadata value to a specific remote player using their unique player network ID.
+   * @param playerId - The network identification integer of the target player.
+   * @param key - The unique identifier string for this player's metadata entry.
+   * @param value - The data payload to attach to the player.
+   * @param sync - Optional flag. If `true`, syncs this change to all other connected clients over the network.
+   */
+  setPlayerMeta(
+    playerId: number,
+    key: string,
+    value: any,
+    sync?: boolean,
+  ): void;
+
+  /**
+   * Retrieves a metadata value attached to a specific remote player.
+   * @template T - The expected type of the returned metadata value.
+   * @param playerId - The network identification integer of the target player.
+   * @param key - The unique identifier string of the player's metadata entry.
+   * @returns The stored metadata value cast to type T, or undefined if it does not exist.
+   */
+  getPlayerMeta<T = any>(playerId: number, key: string): T;
+
+  /**
+   * Sets a metadata value restricted or assigned specifically to the local player instance.
+   * @param key - The unique identifier string for the local player's metadata entry.
+   * @param value - The data payload to store.
+   * @param sync - Optional flag. If `true`, relays this local metadata state out to the server and other clients.
+   */
+  setLocalPlayerMeta(key: string, value: any, sync?: boolean): void;
+
+  /**
+   * Retrieves a metadata value attached specifically to the local player instance.
+   * @template T - The expected type of the returned metadata value.
+   * @param key - The unique identifier string of the local player's metadata entry.
+   * @returns The stored metadata value cast to type T, or undefined if it does not exist.
+   */
+  getLocalPlayerMeta<T = any>(key: string): T;
+
+  /**
+   * Attaches a metadata state payload to any synchronized network entity (e.g., vehicles, props, peds) using its network ID.
+   * @param netId - The network-assigned unique identifier tracking the target entity.
+   * @param key - The unique identifier string for the entity's metadata entry.
+   * @param value - The data payload to attach to the entity.
+   * @param sync - Optional flag. If `true`, synchronizes this entity metadata property to all clients tracking this object.
+   */
+  setEntityMeta(netId: number, key: string, value: any, sync?: boolean): void;
+
+  /**
+   * Retrieves a metadata value associated with a synchronized network entity.
+   * @template T - The expected type of the returned metadata value.
+   * @param netId - The network-assigned unique identifier tracking the target entity.
+   * @param key - The unique identifier string of the entity's metadata entry.
+   * @returns The stored metadata value cast to type T, or undefined if it does not exist.
+   */
+  getEntityMeta<T = any>(netId: number, key: string): T;
+}

package/precomputed/mp.d.ts

@@ -1,137 +1,106 @@
-import type { MpGame } from '../out/game';
-import type { MpCef } from './cef';
-import type { MpDiscord } from './discord';
-import type { MpEvents } from './events';
-import type { MpLocalStorage } from './local-storage';
-import type { MpMeta } from './meta';
-import type { MpVoiceChat } from './voice-chat';
-
-type ServerVector3 = [number, number, number];
-type ServerVector4 = [number, number, number, number];
-
-export interface MpClient {
-  game: MpGame;
-  events: MpEvents;
-  meta: MpMeta;
-  voiceChat: MpVoiceChat;
-  cef: MpCef;
-  discord: MpDiscord;
-  localStorage: MpLocalStorage;
-
-  getStreamedPool(
-    objName: 'CVehicle' | 'CPed' | 'CPickup' | 'CObject',
-  ): number[];
-  getStreamedPlayers(): number[];
-
-  /**
-   * Mapping between network and game IDs.
-   */
-  getVehicleGameIdByNetworkId(id: number): number;
-
-  getPlayerGameIdByNetworkId(id: number): number;
-
-  getObjectGameIdByNetworkId(id: number): number;
-
-  getVehicleNetworkIdByGameId(hash: number): number;
-
-  getPlayerNetworkIdByGameId(hash: number): number;
-
-  getObjectNetworkIdByGameId(hash: number): number;
-
-  getPedNetworkIdByGameId(hash: number): number;
-
-  getPedGameIdByNetworkId(hash: number): number;
-
-  /**
-   * Local player spawning API.
-   */
-  setSpawnDataLocalPlayer(x: number, y: number, z: number, yaw: number): void;
-
-  spawnLocalPlayer(): boolean;
-
-  /**
-   * Spawn local-only entities (not synced).
-   */
-  spawnLocalPed(
-    skinHash: number | bigint,
-    appHash: number | bigint,
-    x: number,
-    y: number,
-    z: number,
-    yaw: number,
-    streaming: boolean,
-  ): number;
-
-  spawnLocalVehicle(
-    skinHash: number | bigint,
-    appHash: number | bigint,
-    x: number,
-    y: number,
-    z: number,
-    roll: number,
-    pitch: number,
-    yaw: number,
-    streaming: boolean,
-  ): number;
-
-  spawnLocalObject(
-    skinHash: bigint | number,
-    appHash: bigint | number,
-    x: number,
-    y: number,
-    z: number,
-    roll: number,
-    pitch: number,
-    yaw: number,
-    streaming: boolean,
-  ): number;
-
-  despawnLocalPed(hash: number): void;
-
-  despawnLocalVehicle(hash: number): void;
-
-  despawnLocalObject(hash: number): void;
-
-  /**
-   * Get Discord token via game SDK (unstable).
-   */
-  getDiscordOAuth2Token(discordAppId: string): string;
-
-  /**
-   * Get Discord auth code (preferred).
-   */
-  getDiscordCodeAuthorization(discordAppId: string, scopes: string): string;
-
-  /**
-   * Returns current server IP:PORT string.
-   */
-  getCurrentServerEndpoint(): string;
-
-  /**
-   * Get server ID from player hash.
-   */
-  getPlayerServerId(playerHash: number): number;
-
-  /**
-   * Get src variable value as string.
-   */
-  getVar(varName: string): string;
-
-  /**
-   * Get console variable value as integer.
-   */
-  getVarInt(varName: string): number;
-
-  /**
-   * Returns time in ms since game start.
-   */
-  getGameTimer(): number;
-
-  getLauncherSettingsJSON(): string;
-
-  getLauncherSettings(): any;
-
-  setTick(cb: () => any): number;
-
-  clearTick(tickId: number): void;
-}
+import type { MpClasses, MpGlobals } from '../out/game';
+import type { MpCef } from './cef';
+import type { MpDiscord } from './discord';
+import type { MpEvents } from './events';
+import type { MpGame } from './game';
+import type { MpLocal } from './local';
+import type { MpLocalStorage } from './local-storage';
+import type { MpMeta } from './meta';
+import type { MpNetwork } from './network';
+import type { MpVoiceChat } from './voice-chat';
+
+type ServerVector3 = [number, number, number];
+type ServerVector4 = [number, number, number, number];
+
+/**
+ * The main client-side manager interface for CyberMP.
+ * Aggregates all core subsystems, network synchronization mappers, local entity spawning arrays, and game-level APIs.
+ */
+export interface MpClient {
+  /**
+   * Access interface for native game engines, classes, and global engine parameters.
+   */
+  game: MpGame & MpGlobals & MpClasses;
+
+  /**
+   * The client event communication system bridge.
+   */
+  events: MpEvents;
+
+  /**
+   * Metadata state synchronization manager across entities and network profiles.
+   */
+  meta: MpMeta;
+
+  /**
+   * Integrated structural client voice communication management interface.
+   */
+  voiceChat: MpVoiceChat;
+
+  /**
+   * Controls and interfaces with the embedded Chromium Embedded Framework web views.
+   */
+  cef: MpCef;
+
+  /**
+   * Provides access to Discord rich presence and authentications integration layers.
+   */
+  discord: MpDiscord;
+
+  /**
+   * Provides networking and entity synchronization utilities
+   */
+  network: MpNetwork;
+
+  local: MpLocal;
+
+  /**
+   * Provides access to local key-value data storage states spanning resource restarts.
+   */
+  localStorage: MpLocalStorage;
+
+  /**
+   * Queries environment configuration arrays to fetch string system variable values defined inside config manifest structures.
+   * @param varName - Target environmental variable path identifier name key string.
+   * @returns The corresponding variable value matching that name string.
+   */
+  getVar(varName: string): string;
+
+  /**
+   * Queries environment configuration arrays to fetch integer variable values defined inside config manifest structures.
+   * @param varName - Target environmental variable path identifier name key string.
+   * @returns The variable evaluation value parsed into a numerical integer.
+   */
+  getVarInt(varName: string): number;
+
+  /**
+   * Retrieves total execution duration elapsed since initialization of the master game engine shell layer tracking loops.
+   * @returns Calculated time tracker measurement value in milliseconds.
+   */
+  getGameTimer(): number;
+
+  /**
+   * Fetches raw unparsed configurations mapping platform launcher operational states.
+   * @returns Unparsed JSON payload string representing client settings configurations.
+   */
+  getLauncherSettingsJSON(): string;
+
+  /**
+   * Fetches parsed layout profiles tracking core client options configurations.
+   * @returns Object tracking client properties choices.
+   */
+  getLauncherSettings(): any;
+
+  /**
+   * Registers a callback execution function that runs continuously on every game engine render frame.
+   * @param cb - The logic routine executed on every render cycle.
+   * @returns An execution identifier handle index required to disable the execution loop later.
+   */
+  setTick(cb: () => any): number;
+
+  /**
+   * Removes and unbinds an active rendering cycle tracking loop execution block.
+   * @param tickId - The original registration index key returned by {@link setTick}.
+   */
+  clearTick(tickId: number): void;
+}

package/precomputed/network.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Provides networking and entity synchronization utilities
+ */
+export interface MpNetwork {
+  /**
+   * Returns the endpoint address configuration tracking string of the current server session.
+   * @returns Endpoint routing connection destination details string (e.g., `"127.0.0.1:4430"`).
+   */
+  getServerAddress(): string;
+
+  /**
+   * Returns an array of game engine handling entities currently within the local player's streaming radius.
+   * @param objName - The engine pool target class filter type to look up.
+   * @returns An array containing the local runtime engine IDs matching the target pool.
+   */
+  getStreamedPool(
+    objName: 'CVehicle' | 'CPed' | 'CPickup' | 'CObject',
+  ): number[];
+
+  /**
+   * Gets an array containing all active remote network players currently streaming inside the local user's zone.
+   * @returns An array of native game engine entity IDs.
+   */
+  getStreamedPlayers(): number[];
+
+  /**
+   * Resolves a network sync ID into its corresponding local native game engine entity reference handle for a vehicle.
+   * @param networkId - The unique synchronization network ID assigned by the server host.
+   * @returns The corresponding local native game engine vehicle handle ID.
+   */
+  getVehicleGameId(networkId: number): number;
+
+  /**
+   * Translates a native vehicle game handle into its global shared replication network sync ID.
+   * @param gameId - The local native game engine entity instance handle.
+   * @returns The synchronized network ID assigned to that vehicle.
+   */
+  getVehicleId(gameId: number): number;
+
+  /**
+   * Translates a native pedestrian/NPC handle into its global shared replication network sync ID.
+   * @param gameId - The local native game engine entity instance handle.
+   * @returns The synchronized network ID assigned to that pedestrian.
+   */
+  getPedId(gameId: number): number;
+
+  /**
+   * Resolves a network sync ID into its corresponding local native game engine entity reference handle for a pedestrian.
+   * @param networkId - The unique synchronization network ID assigned by the server host.
+   * @returns The corresponding local native game engine pedestrian handle ID.
+   */
+  getPedGameId(networkId: number): number;
+
+  /**
+   * Resolves a network sync ID into its corresponding local native game engine entity reference handle for a static object.
+   * @param networkId - The unique synchronization network ID assigned by the server host.
+   * @returns The corresponding local native game engine object handle ID.
+   */
+  getObjectGameId(networkId: number): number;
+
+  /**
+   * Translates a native object or entity prop handle into its global shared replication network sync ID.
+   * @param gameId - The local native game engine entity instance handle.
+   * @returns The synchronized network ID assigned to that object.
+   */
+  getObjectId(gameId: number): number;
+
+  /**
+   * Resolves a network sync ID into its corresponding local native game engine entity reference handle for a player.
+   * @param networkId - The unique synchronization network ID assigned by the server host.
+   * @returns The corresponding local native game engine player handle ID.
+   */
+  getPlayerGameId(networkId: number): number;
+
+  /**
+   * Translates a native player character entity handle into its global shared replication network sync ID.
+   * @param gameId - The local native game engine entity instance handle.
+   * @returns The synchronized network ID assigned to that player.
+   */
+  getPlayerId(gameId: number): number;
+}