@cybermp-community/client-types 2.5.1 → 2.5.3

package/dist/precomputed/events/cef.ts

@@ -0,0 +1,28 @@
+export type CefLoadingFailedError = {
+  /** Name of the browser frame that failed to load. */
+  frameName: string;
+  /** Human-readable error description. */
+  message: string;
+  /** Source file URL where the error occurred. */
+  source: string;
+  /** Line number in the source file. */
+  line: string;
+  /** Column offset in the source line. */
+  column: string;
+  /** Raw stack trace string. */
+  stack: string;
+};
+
+export interface MpCefEventsMap {
+  /**
+   * Triggered when the browser finishes parsing the DOM.
+   * @param name - Registration name of the browser frame.
+   */
+  domReady(name: string): void;
+
+  /**
+   * Triggered when the browser fails to load or encounters an error.
+   * @param error - Error details payload.
+   */
+  loadingFailed(error: CefLoadingFailedError): void;
+}

package/dist/precomputed/events/index.ts

@@ -1,75 +1,67 @@
-import type { MpEventsMap } from "./map";
+import type { MpCefEventsMap } from './cef';
+import type { MpEventsMap } from './map';
 
 type Args = any[];
 
 export interface MpEvents {
   /**
-   * Register a custom event listener.
-   * @param eventName Name of the event.
-   * @param callback Callback function.
+   * Subscribes a handler to a local event.
+   * @param eventName - Event name.
+   * @param callback - Handler function.
    */
-
   on<E extends keyof MpEventsMap>(eventName: E, callback: MpEventsMap[E]): void;
-  on<T extends unknown[] = Args>(
-    eventName: string,
-    callback: (...args: T) => void,
-  ): void;
+  on<T extends unknown[] = Args>(eventName: string, callback: (...args: T) => void): void;
 
   /**
-   * UnRegister a custom event listener.
-   * @param eventName Name of the event.
-   * @param callback Callback function.
+   * Removes a previously registered local event handler.
+   * @param eventName - Event name.
+   * @param callback - The handler reference to remove.
    */
-  off<T extends unknown[] = Args>(
-    eventName: string,
-    callback: (...args: T) => void,
-  ): void;
+  off<T extends unknown[] = Args>(eventName: string, callback: (...args: T) => void): void;
 
   /**
-   * Emit a previously registered custom event.
-   *
-   * @param eventName Name of the event.
-   * @param args Arguments to pass.
+   * Dispatches a local event to all registered handlers.
+   * @param eventName - Event name.
+   * @param args - Arguments passed to each handler.
    */
   emit<T extends unknown[] = Args>(eventName: string, ...args: T): void;
 
   /**
-   * Register a listener for server event on client.
+   * Subscribes a handler to an event dispatched from the server.
+   * @param eventName - Event name.
+   * @param callback - Handler function.
    */
-  onServer<T extends unknown[] = Args>(
-    eventName: string,
-    callback: (...args: T) => void,
-  ): void;
+  onServer<T extends unknown[] = Args>(eventName: string, callback: (...args: T) => void): void;
 
   /**
-   * Emit an event to the server.
+   * Sends an event to the server.
+   * @param eventName - Event name.
+   * @param args - Arguments to send.
    */
   emitServer<T extends unknown[] = Args>(eventName: string, ...args: T): void;
 
   /**
-   * Emit an event to the cef.
+   * Sends an event to the CEF web view.
+   * @param eventName - Event name.
+   * @param args - Arguments to send.
    */
   emitCef<T extends unknown[] = Args>(eventName: string, ...args: T): void;
 
   /**
-   * Register a custom cef event listener.
-   * @param eventName Name of the event.
-   * @param callback Callback function.
+   * Subscribes a typed handler to a built-in CEF lifecycle event.
+   * @template E - Key of `MpCefEventsMap`.
+   * @param eventName - The CEF lifecycle event name.
+   * @param callback - Typed handler matching the event's signature.
    */
-  onCef<T extends unknown[] = Args>(
-    eventName: string,
-    callback: (...args: T) => void,
-  ): void;
+  onCef<E extends keyof MpCefEventsMap>(eventName: E, callback: MpCefEventsMap[E]): void;
 
   /**
-   * Register a command in the client scope.
-   * @param commandName Command name without "/".
-   * @param callback Callback with id and args.
+   * Subscribes a handler to a custom CEF event.
+   * @param eventName - Event name.
+   * @param callback - Handler function.
    */
-  addCommand<T extends string[] = string[]>(
-    commandName: string,
-    callback: (id: number, args: T) => void,
-  ): void;
+  onCef<T extends unknown[] = Args>(eventName: string, callback: (...args: T) => void): void;
 }
 
-export * from "./map";
+export * from './map';
+export * from './cef';

package/dist/precomputed/events/map.ts

@@ -1,19 +1,110 @@
-export interface MpEventsMap {
-  globalMetaChange<T = any, K = T>(
-    key: string,
-    newValue: T,
-    oldValue: K,
-  ): undefined | boolean;
-  playerMetaChange<T = any, K = T>(
-    netId: number,
-    key: string,
-    newValue: T,
-    oldValue: K,
-  ): undefined | boolean;
-  entityMetaChange<T = any, K = T>(
-    netId: number,
-    key: string,
-    newValue: T,
-    oldValue: K,
-  ): undefined | boolean;
-}
+export interface MpEventsMap {
+  globalMetaChange<T = any, K = T>(key: string, newValue: T, oldValue: K): undefined | boolean;
+  playerMetaChange<T = any, K = T>(
+    netId: number,
+    key: string,
+    newValue: T,
+    oldValue: K,
+  ): undefined | boolean;
+  entityMetaChange<T = any, K = T>(
+    netId: number,
+    key: string,
+    newValue: T,
+    oldValue: K,
+  ): undefined | boolean;
+
+  /**
+   * Triggered when a local resource starts running.
+   * @param resourceName - Name of the started resource.
+   */
+  anyResourceStart(resourceName: string): void;
+
+  /**
+   * Triggered when a local resource stops or is reloaded.
+   * @param resourceName - Name of the stopped resource.
+   */
+  anyResourceStop(resourceName: string): void;
+
+  /**
+   * Triggered when the server reports that a server-side resource has started.
+   * @param resourceName - Name of the server resource.
+   */
+  anyServerResourceStart(resourceName: string): void;
+
+  /**
+   * Triggered when the server reports that a server-side resource has stopped.
+   * @param resourceName - Name of the server resource.
+   */
+  anyServerResourceStop(resourceName: string): void;
+
+  /**
+   * Triggered when this specific resource finishes loading.
+   */
+  resourceStart(): void;
+
+  /**
+   * Triggered when this specific resource is being shut down.
+   */
+  resourceStop(): void;
+
+  /**
+   * Triggered when the engine refreshes the global resource manifest.
+   */
+  resourcesRefresh(): void;
+
+  /**
+   * Triggered when a synced object leaves the local player's stream range.
+   * @param netID - Network entity ID.
+   * @param gameID - Local game engine handle.
+   */
+  objectStreamOut(netID: number, gameID: number): void;
+
+  /**
+   * Triggered when a synced object enters the local player's stream range.
+   * @param netID - Network entity ID.
+   * @param gameID - Local game engine handle.
+   */
+  objectStreamIn(netID: number, gameID: number): void;
+
+  /**
+   * Triggered when a synced ped or NPC leaves the local player's stream range.
+   * @param netID - Network entity ID.
+   * @param gameID - Local game engine handle.
+   */
+  pedStreamOut(netID: number, gameID: number): void;
+
+  /**
+   * Triggered when a synced ped or NPC enters the local player's stream range.
+   * @param netID - Network entity ID.
+   * @param gameID - Local game engine handle.
+   */
+  pedStreamIn(netID: number, gameID: number): void;
+
+  /**
+   * Triggered when a remote player leaves the local player's stream zone.
+   * @param netID - Network player ID.
+   * @param gameID - Local game engine handle.
+   */
+  remotePlayerStreamOut(netID: number, gameID: number): void;
+
+  /**
+   * Triggered when a remote player enters the local player's stream zone.
+   * @param netID - Network player ID.
+   * @param gameID - Local game engine handle.
+   */
+  remotePlayerStreamIn(netID: number, gameID: number): void;
+
+  /**
+   * Triggered when a synced vehicle leaves the local player's stream range.
+   * @param netID - Network entity ID.
+   * @param gameID - Local game engine handle.
+   */
+  vehicleStreamOut(netID: number, gameID: number): void;
+
+  /**
+   * Triggered when a synced vehicle enters the local player's stream range.
+   * @param netID - Network entity ID.
+   * @param gameID - Local game engine handle.
+   */
+  vehicleStreamIn(netID: number, gameID: number): void;
+}

package/dist/precomputed/exports.ts

@@ -1,12 +1,48 @@
-export type MpExports = MpExternalExports & MpCreateExport;
-
-interface MpExternalExports {
-  [module: string]: {
-    [name: string]: <T extends unknown[] = unknown[], R = unknown>(...args: T) => R | Promise<R>;
-  };
-}
-
-type MpCreateExport = <T extends unknown[] = unknown[], R = unknown>(
-  name: string,
-  callback: (...args: T) => R | Promise<R>,
-) => void;
+/**
+ * Interface managing cross-resource execution pipelines.
+ *
+ * This intersection type enables a dual-purpose pattern: it can be invoked directly as a
+ * function to register and expose local routines (`MpCreateExport`), or accessed as a nested
+ * directory dictionary to invoke public endpoints exposed by external resources (`MpExternalExports`).
+ * @example
+ * // in resource named "freeroam" -
+ * mp.exports('showNotification', (message) => console.log("Notification from freeroam", message))
+ * // triggering this function in any other resource -
+ * mp.exports.freeroam.showNotification('test message')
+ */
+export type MpExports = MpExternalExports & MpCreateExport;
+
+/**
+ * A dynamic index mapping representing foreign modules and their exposed public functions.
+ */
+interface MpExternalExports {
+  /**
+   * Accesses an external module's public namespace by its resource name string.
+   */
+  [module: string]: {
+    /**
+     * Invokes a specific exported method from the targeted external resource.
+     * @template T - Array type mapping the arguments passed to the external routine.
+     * @template R - The expected return value or wrapped Promise type.
+     * @param args - Arbitrary parameters forwarded directly to the target function execution context.
+     * @returns The synchronous or asynchronous output value of the foreign routine.
+     */
+    [name: string]: <T extends unknown[] = unknown[], R = unknown>(...args: T) => R | Promise<R>;
+  };
+}
+
+/**
+ * Defines a function signature used to expose a local routine to the global environment.
+ *
+ * Registers a callback execution mapping under a specific name identifier, making it
+ * discoverable and executable by separate script runtime containers.
+ *
+ * @template T - Array type mapping the callback's expected input parameters.
+ * @template R - The expected synchronous or asynchronous return layout pattern.
+ * @param name - The unique public string label assigned to this export entry point.
+ * @param callback - The underlying functional routine logic triggered upon external invocation.
+ */
+type MpCreateExport = <T extends unknown[] = unknown[], R = unknown>(
+  name: string,
+  callback: (...args: T) => R | Promise<R>,
+) => void;

package/dist/precomputed/game.d.ts

@@ -1,77 +1,180 @@
-import type { Vector3 } from "../classes.d.ts";
-import type { MpClasses } from "../mp-classes.d.ts";
-import type * as CyberEnums from "../enums";
+import type { MpClasses } from '../mp-classes.d.ts';
+import type * as CyberEnums from '../enums';
 
 // THIS CODE IS FOR PRECOMPUTED TYPES
 export type UnwrapClass<T> = T extends { new (): infer U } ? U : T;
 
+/**
+ * @internal
+ */
+export type AnyFunc = (...args: any[]) => any;
+
+/**
+ * @internal
+ */
+export type SafeMethod<I, M extends keyof I> = I[M] extends AnyFunc ? I[M] : AnyFunc;
+
+/**
+ * Defines a function signature used to completely override a method within a specified game class.
+ * The callback receives the instance (`self`), the original arguments, and the original method implementation as the final parameter.
+ * @template C - The class name key from `MpClasses`.
+ * @template I - The resolved instance type of the class.
+ * @template M - The method names available on the class instance.
+ */
 export type OverrideFunction = <
   C extends keyof MpClasses,
   I extends UnwrapClass<MpClasses[C]>,
-  M extends keyof I extends never ? string : keyof I,
+  M extends keyof I,
 >(
   className: C,
   methodName: M,
   callback: (
     self: I,
-    ...args: [...Parameters<I[M]>, origin: I[M]]
-  ) => ReturnType<I[M]>,
+    ...args: [...Parameters<SafeMethod<I, M>>, origin: SafeMethod<I, M>]
+  ) => ReturnType<SafeMethod<I, M>>,
 ) => void;
 
+/**
+ * Defines a function signature used to observe (hook into) a method within a specified game class.
+ * The callback receives the instance (`self`) and the arguments passed to the method.
+ * @template C - The class name key from `MpClasses`.
+ * @template I - The resolved instance type of the class.
+ * @template M - The method names available on the class instance.
+ */
 export type ObserveFunction = <
   C extends keyof MpClasses,
   I extends UnwrapClass<MpClasses[C]>,
-  M extends keyof I extends never ? string : keyof I,
+  M extends keyof I,
 >(
   className: C,
   methodName: M,
-  callback: (self: I, ...args: Parameters<I[M]>) => void,
+  callback: (self: I, ...args: Parameters<SafeMethod<I, M>>) => void,
 ) => void;
 
 export interface TweakDB {
+  /**
+   * Retrieves an array of records matching a specific query or record type.
+   * @template T - The expected type of the records.
+   * @param str - The TweakDB record path or type identifier.
+   * @returns An array of matching records.
+   */
   getRecords<T = any>(str: string): T[];
+
+  /**
+   * Retrieves a single record from TweakDB.
+   * @template T - The expected type of the record.
+   * @param str - The specific TweakDB ID or path string.
+   * @returns The requested record.
+   */
   getRecord<T = any>(str: string): T;
+
+  /**
+   * Queries TweakDB paths and returns matching entry keys.
+   * @param str - The search or query pattern string.
+   * @returns An array of matching string IDs.
+   */
   query(str: string): string[];
+
+  /**
+   * Retrieves a "flat" property value directly from TweakDB.
+   * @template T - The expected type of the flat property.
+   * @param str - The path to the flat property (e.g., "Items.SomeItem.someProperty").
+   * @returns The flat property value.
+   */
   getFlat<T = any>(str: string): T;
+
+  /**
+   * Overwrites an array flat property in TweakDB and updates the engine immediately.
+   * @param str - The path to the flat property.
+   * @param arr - The new array of values to assign.
+   * @returns `true` if the operation was successful, otherwise `false`.
+   */
   setFlats(str: string, arr: any[]): boolean;
+
+  /**
+   * Overwrites a single flat property value in TweakDB and updates the engine immediately.
+   * @param str - The path to the flat property.
+   * @param obj - The new value to assign.
+   * @returns `true` if the operation was successful, otherwise `false`.
+   */
   setFlat(str: string, obj: any): boolean;
+
+  /**
+   * Overwrites a flat property value in TweakDB *without* triggering an immediate engine update.
+   * Useful when batching multiple TweakDB edits before a manual refresh.
+   * @param str - The path to the flat property.
+   * @param obj - The new value to assign.
+   * @returns `true` if the operation was successful, otherwise `false`.
+   */
   setFlatNoUpdate(str: string, obj: any): boolean;
+
+  /**
+   * Forces the engine to re-read and update a specific record from its current TweakDB state.
+   * @param str - The path to the record to update.
+   * @returns `true` if the update succeeded, otherwise `false`.
+   */
   updateRecord(str: string): boolean;
+
+  /**
+   * Runtime creates a new TweakDB record.
+   * @param key - The new record identifier key.
+   * @param value - The record blueprint or type definition key.
+   * @returns `true` if creation succeeded, otherwise `false`.
+   */
   createRecord(key: string, value: string): boolean;
 }
 
-export interface CyberMP {
+export interface MpGameHashes {
+  /**
+   * Converts a TweakDB record string path into its unique TweakDBID hash signature format.
+   * @param name - The text record path string (e.g., `"Items.money"`).
+   * @returns The resolved TweakDBID hash string reference.
+   */
+  toTweakdbid(name: string): string;
+
+  /**
+   * Resolves an internal TweakDBID hash signature string back into its original readable record path string.
+   * @param hash - The native TweakDBID hash layout signature.
+   * @returns The readable path text description string if found, otherwise an empty or fallback string representation.
+   */
+  fromTweakdbid(hash: string): string;
+
   /**
-   * Removes game object classes (e.g., T extends gameObject, playerPuppet, NpcPuppet) from the map.
-   * @param objectClassMap Array of class names to delete.
+   * Resolves a resource file route or asset system address string into its designated numeric/hexadecimal Resource Reference (`ResRef`) signature hash.
+   * @param name - The full system asset path string (e.g., `"base\\characters\\main_npc\\jackie.ent"`).
+   * @returns The matching native ResRef serialization target hash key.
    */
-  DeclareDeletedObjects(objectClassMap: Array<keyof MpClasses>): void;
+  toResref(name: string): string;
 
   /**
-   * Removes game objects by their unique hashes from the map.
-   * @param objectHashMap Array of unique game object hashes to delete.
+   * Translates a native game engine Resource Reference (`ResRef`) asset identifier string back into its readable raw directory path string.
+   * @param hash - The target ResRef hash format token layout string.
+   * @returns The verified asset resource string path.
    */
-  DeletedObjectsByUniqueHash(objectHashMap: string[]): void;
+  fromResref(hash: string): string;
 
   /**
-   * Enables or disables synchronization of default effects, as defined by the CyberMP platform.
-   * @param value Whether to use the default effects.
+   * Converts a standard text identifier string into its corresponding internal engine unique 64-bit string identifier (`CName`) hash representation.
+   * @param name - The plaintext string label configuration name to translate.
+   * @returns The matching numeric engine structure string token representation.
    */
-  UseDefaultEffectsByPlatform(value: boolean): void;
+  toCname(name: string): string;
 
-  SetDefaultSpawnPosition(position: Vector3, yaw: number): void;
+  /**
+   * Reverses a native engine 64-bit name identification token identifier (`CName`) back into its human-readable plaintext string label.
+   * @param hash - The string representation of the target CName identifier.
+   * @returns The corresponding unhashed string literal value.
+   */
+  fromCname(hash: string): string;
 }
 
-declare module "../game.d.ts" {
+declare module '../game.d.ts' {
   export interface MpGame {
-    CyberMP: CyberMP;
     TweakDB: TweakDB;
+    hashes: MpGameHashes;
 
     onInputKeyEvent(
-      callback: (
-        action: CyberEnums.EInputAction,
-        key: CyberEnums.EInputKey,
-      ) => void,
+      callback: (action: CyberEnums.EInputAction, key: CyberEnums.EInputKey) => void,
     ): void;
 
     getDisplayResolution(): [width: number, height: number];
@@ -106,28 +209,6 @@ declare module "../game.d.ts" {
      */
     AddToInventory(itemName: string, count: number): void;
 
-    /**
-     * Returns model hash convertable to number.
-     * @param name Model name
-     * @param type Model name type
-     * @returns Model hash
-     */
-    getHashFromName(
-      name: string,
-      type: "tweakdbid" | "cname" | "resref",
-    ): string;
-
-    /**
-     * Returns model name.
-     * @param name Model hash
-     * @param type Model hash type
-     * @returns Model name
-     */
-    getNameFromHash(
-      hash: string,
-      type: "tweakdbid" | "cname" | "resref",
-    ): string;
-
     /**
      * Overrides method function inside selected class.
      * @param className Class name
@@ -186,7 +267,21 @@ declare module "../game.d.ts" {
      */
     observeRaw: ObserveFunction;
 
+    /**
+     * Serializes a JavaScript runtime payload object structural value into a native engine container format (`Variant`).
+     * @template R - The expected return typing output blueprint shape.
+     * @param obj - Target entity object structure to convert.
+     * @param str - Native structural reflection mapping blueprint name string.
+     * @returns The wrapped engine reference asset layout structure.
+     */
     toVariant<R = Record<string, unknown>>(obj: any, str: string): R;
+
+    /**
+     * Deserializes a native engine container structure layout (`Variant`) back into raw accessible JavaScript object values.
+     * @template R - The expected target JavaScript shape format.
+     * @param obj - Variant payload container input from the game engine.
+     * @returns The unwrapped JavaScript object structure data.
+     */
     fromVariant<R = any>(obj: any): R;
   }
 }

package/dist/precomputed/index.ts

@@ -7,3 +7,4 @@ export type * from './local-storage';
 export type * from './meta';
 export type * from './mp';
 export type * from './voice-chat';
+export type * from './enums';

package/dist/precomputed/local-storage.ts

@@ -1,9 +1,36 @@
+/**
+ * Persistent key-value storage on the client.
+ * Survives resource restarts and server reconnections.
+ */
 export interface MpLocalStorage {
+  /**
+   * Stores a string value under the given key, overwriting any existing entry.
+   * @param key - Storage key.
+   * @param value - String value to store.
+   */
   set(key: string, value: string): void;
+
+  /**
+   * Returns the value associated with the given key.
+   * @param key - Storage key to look up.
+   * @returns The stored string, or an empty string if the key doesn't exist.
+   */
   get(key: string): string;
 
+  /**
+   * Deletes a specific entry from storage.
+   * @param key - Storage key to remove.
+   */
   delete(key: string): void;
+
+  /**
+   * Clears all entries from this resource's local storage.
+   */
   deleteAll(): void;
 
+  /**
+   * Flushes in-memory storage to disk.
+   * Call this if you need to guarantee data is not lost on a client crash.
+   */
   save(): void;
 }