@open-core/framework 0.2.9 → 0.3.1

package/dist/runtime/server/entities/player.d.ts

@@ -1,8 +1,11 @@
 import { IPlayerInfo } from '../../../adapters';
-import { IEntityServer } from '../../../adapters/contracts/IEntityServer';
 import { INetTransport } from '../../../adapters/contracts/INetTransport';
-import { IPlayerServer } from '../../../adapters/contracts/IPlayerServer';
-import { Vector3 } from '../../../kernel/utils';
+import { IEntityServer } from '../../../adapters/contracts/server/IEntityServer';
+import { IPlayerServer } from '../../../adapters/contracts/server/IPlayerServer';
+import type { PlayerIdentifier } from '../../../adapters/contracts/types/identifier';
+import { Vector3 } from '../../../kernel/utils/vector3';
+import { BaseEntity } from '../../core/entity';
+import { Spatial } from '../../core/spatial';
 import { LinkedID } from '../services/types/linked-id';
 import { PlayerSession } from '../services/types/player-session.object';
 import { SerializedPlayerData } from '../types/core-exports';
@@ -19,17 +22,20 @@ export interface PlayerAdapters {
 /**
  * Core-level representation of a connected player on the server.
  *
- * This class wraps FiveM natives and session information.
+ * @remarks
+ * This class wraps platform natives and session information.
  * It serves as an abstraction layer to interact with the connected client
  * (kicking, teleporting, emitting events) without dealing with raw IDs everywhere.
  *
- * ⚠️ **Design Note:** This class does NOT contain gameplay logic (money, jobs, inventory).
+ * **Design Note:** This class does NOT contain gameplay logic (money, jobs, inventory).
  * Domain logic should live in your modules' services/models (e.g., `EconomyService`, `JobModel`).
+ *
+ * This class is platform-agnostic and works across different game engines
+ * (FiveM, RageMP, alt:V, etc.) through the adapter pattern.
  */
-export declare class Player {
+export declare class Player extends BaseEntity implements Spatial {
     private readonly session;
     private readonly adapters;
-    private states;
     private position;
     /**
      * Creates a new Player entity instance.
@@ -40,64 +46,81 @@ export declare class Player {
      */
     constructor(session: PlayerSession, adapters: PlayerAdapters);
     /**
-     * The numeric FiveM Server ID (Source) of the player.
-     * Useful for internal logic and array indexing.
+     * The numeric client/server ID of the player.
+     * This is the platform-specific player identifier used for native calls.
      */
     get clientID(): number;
-    /**
-     * The FiveM Server ID as a string.
-     * Required by most FiveM native functions (e.g., `GetPlayerName`, `DropPlayer`).
-     */
-    get clientIDStr(): string;
     /**
      * The persistent Account ID linked to this session, if the player is authenticated.
      * Returns `undefined` if the player has not logged in yet.
      */
     get accountID(): string | undefined;
     /**
-     * The display name of the player (Steam name or FiveM username).
+     * The display name of the player.
      */
     get name(): string;
-    getPosition(): Vector3 | undefined;
+    getPosition(): Vector3;
     /**
-     * Retrieves all platform identifiers associated with the player (steam, license, discord, ip, etc.).
+     * Sets the player position using the platform-agnostic API.
      *
+     * @param vector - The target coordinates (x, y, z).
+     */
+    setPosition(vector: Vector3): void;
+    /**
+     * Retrieves all platform identifiers associated with the player.
+     *
+     * @deprecated Use getPlayerIdentifiers() for structured identifier data.
      * @returns An array of identifier strings (e.g., `['steam:11000...', 'license:2332...']`).
      */
     getIdentifiers(): string[];
     /**
-     * FiveM license
+     * Retrieves all identifiers as structured objects.
+     *
+     * @returns An array of PlayerIdentifier objects with type, value, and raw fields.
+     */
+    getPlayerIdentifiers(): PlayerIdentifier[];
+    /**
+     * Gets a specific identifier by type.
+     *
+     * @param identifierType - The type of identifier (e.g., 'steam', 'license', 'discord')
+     * @returns The identifier string or undefined if not found
+     */
+    getIdentifier(identifierType: string): string | undefined;
+    /**
+     * Gets the player's license identifier.
+     * @deprecated Use getIdentifier('license') for cross-platform compatibility.
      */
     getLicense(): string | undefined;
-    getIdentifier(identifier: string): string | undefined;
     /**
-     * Sends a network event exclusively to this specific player (Client-side).
-     * Wrapper for `emitNet` ensuring the correct target Source ID is used.
+     * Sends a network event exclusively to this specific player (client-side).
      *
      * @param eventName - The name of the event to trigger on the client.
      * @param args - Data to send to the client.
      */
     emit(eventName: string, ...args: any[]): void;
-    /** used to send a private message to the player */
-    send(message: string, type?: 'chat' | 'error' | 'success' | 'warning'): void;
     /**
-     * Teleports the player to a given position using Server-Side natives.
+     * Sends a private message to the player.
      *
-     * **Note:** This forces the entity position on the server. For smoother gameplay transitions
-     * (e.g., inside interiors or across the map), consider using `teleportClient`.
-     *
-     * @param vector - The target coordinates (x, y, z).
+     * @param message - The message text
+     * @param type - Message type for styling
      */
-    teleport(vector: Vector3): void;
+    send(message: string, type?: 'chat' | 'error' | 'success' | 'warning'): void;
     /**
-     * Requests the Client to teleport itself via the Core Spawner system.
+     * Requests the client to teleport via the spawner system.
      *
+     * @remarks
      * This method is preferred for gameplay logic as it allows the client to handle
      * loading screens, fading, and collision loading gracefully.
      *
      * @param vector - The target coordinates (x, y, z).
      */
-    teleportClient(vector: Vector3): void;
+    teleport(vector: Vector3): void;
+    /**
+     * Spawns the player at a position with a specific model.
+     *
+     * @param vector - The spawn coordinates
+     * @param model - The ped model to use (default: 'mp_m_freemode_01')
+     */
     spawn(vector: Vector3, model?: string): void;
     /**
      * Disconnects the player from the server.
@@ -106,12 +129,24 @@ export declare class Player {
      */
     kick(reason?: string): void;
     /**
-     * Sets the routing bucket (virtual world / dimension) for the player.
+     * Sets the routing bucket (virtual world/dimension) for the player.
      * Players in different buckets cannot see or interact with each other.
      *
      * @param bucket - The bucket ID (0 is the default shared world).
      */
     setRoutingBucket(bucket: number): void;
+    /**
+     * Gets the current routing bucket.
+     */
+    getRoutingBucket(): number;
+    /**
+     * Sets the player dimension (alias for setRoutingBucket).
+     */
+    set dimension(value: number);
+    /**
+     * Gets the player dimension (alias for getRoutingBucket).
+     */
+    get dimension(): number;
     /**
      * Stores arbitrary transient metadata for this player's session.
      * Useful for flags like `isDead`, `isInRaid`, `lastLocation`, etc.
@@ -119,11 +154,10 @@ export declare class Player {
      * @param key - The unique key for the metadata.
      * @param value - The value to store.
      */
-    setMeta(key: string, value: unknown): void;
+    setMeta<T = unknown>(key: string, value: T): void;
     /**
      * Retrieves metadata previously stored in the session.
      *
-     * @template T - The expected type of the value.
      * @param key - The metadata key.
      * @returns The value cast to T, or `undefined` if not set.
      */
@@ -132,24 +166,22 @@ export declare class Player {
      * Links a persistent Account ID to the current session.
      * Should be called after successful authentication.
      *
-     * @param accountID - The unique ID from the database.
+     * @param accountID - The unique ID from the persistent storage.
      */
     linkAccount(accountID: LinkedID): void;
+    /**
+     * Unlinks the account from the current session.
+     */
     unlinkAccount(): void;
     /**
      * Checks if the player currently possesses a specific state flag.
      *
      * @param state - The unique string identifier of the state (e.g., 'dead', 'cuffed').
-     * @returns `true` if the state is active, `false` otherwise.
      */
     hasState(state: string): boolean;
     /**
      * Applies a state flag to the player.
      *
-     * @remarks
-     * Since states are stored in a `Set`, adding an existing state has no effect (idempotent).
-     * Ideally, this should trigger a sync event to the client if needed.
-     *
      * @param state - The state key to add.
      */
     addState(state: string): void;
@@ -163,48 +195,32 @@ export declare class Player {
      * Toggles the presence of a state flag.
      *
      * @param state - The state key to toggle.
-     * @param force - If provided, forces the state to be added (`true`) or removed (`false`) regardless of its current status.
-     *
-     * @returns The final status of the state (`true` if active, `false` if inactive).
-     *
-     * @example
-     * ```ts
-     * // Standard toggle
-     * player.toggleState('duty'); // turns on if off, off if on
-     *
-     * // Force enable (equivalent to addState but returns boolean)
-     * player.toggleState('duty', true); // always results in true
-     * ```
+     * @param force - If provided, forces the state to be added or removed.
+     * @returns The final status of the state.
      */
     toggleState(state: string, force?: boolean): boolean;
     /**
-     * Retrieves a snapshot of all currently active state flags for this player.
-     *
-     * @returns An array containing all active state keys.
+     * Retrieves all currently active state flags.
      */
     getStates(): string[];
     /**
      * Gets the current health of the player's ped.
-     *
-     * @returns Current health value (0-200, where 100 is dead).
      */
     getHealth(): number;
     /**
      * Sets the health of the player's ped.
      *
-     * @param health - Health value to set (0-200).
+     * @param health - Health value to set (platform-specific range).
      */
     setHealth(health: number): void;
     /**
      * Gets the current armor of the player's ped.
-     *
-     * @returns Current armor value (0-100).
      */
     getArmor(): number;
     /**
      * Sets the armor of the player's ped.
      *
-     * @param armor - Armor value to set (0-100).
+     * @param armor - Armor value to set (typically 0-100).
      */
     setArmor(armor: number): void;
     /**
@@ -214,16 +230,14 @@ export declare class Player {
     /**
      * Checks if the player is alive.
      *
-     * @returns `true` if health is above 100 (dead threshold), `false` otherwise.
+     * @remarks
+     * The threshold (100) is platform-specific. In GTA V-based platforms,
+     * health below 100 means dead.
      */
     isAlive(): boolean;
     /**
      * Serializes the player data for cross-resource transfer.
      *
-     * @remarks
-     * Creates a plain object representation of the player session that can be
-     * safely transferred between resources via FiveM exports.
-     *
      * @returns Serialized player data DTO
      */
     serialize(): SerializedPlayerData;