@open-core/framework 0.2.9 → 0.3.0

package/dist/runtime/server/devmode/player-simulator.service.js

@@ -10,7 +10,7 @@ exports.PlayerSimulatorService = void 0;
 const tsyringe_1 = require("tsyringe");
 const INetTransport_1 = require("../../../adapters/contracts/INetTransport");
 const container_1 = require("../../../kernel/di/container");
-const logger_1 = require("../../../kernel/shared/logger");
+const logger_1 = require("../../../kernel/logger");
 const player_session_lifecycle_port_1 = require("../services/ports/player-session-lifecycle.port");
 /**
  * Service for simulating player connections during development.
@@ -24,10 +24,10 @@ let PlayerSimulatorService = class PlayerSimulatorService {
         this.clientIdCounter = 90000; // Start high to avoid conflicts with real players
     }
     get transport() {
-        return container_1.di.resolve(INetTransport_1.INetTransport);
+        return container_1.GLOBAL_CONTAINER.resolve(INetTransport_1.INetTransport);
     }
     get sessionLifecycle() {
-        return container_1.di.resolve(player_session_lifecycle_port_1.PlayerSessionLifecyclePort);
+        return container_1.GLOBAL_CONTAINER.resolve(player_session_lifecycle_port_1.PlayerSessionLifecyclePort);
     }
     /**
      * Connects a simulated player.

package/dist/runtime/server/devmode/state-inspector.service.js

@@ -27,7 +27,7 @@ let StateInspectorService = class StateInspectorService extends IDevModeInspecto
         this.fiveMEventHandlers = new Map();
     }
     get players() {
-        return container_1.di.resolve(player_directory_port_1.PlayerDirectoryPort);
+        return container_1.GLOBAL_CONTAINER.resolve(player_directory_port_1.PlayerDirectoryPort);
     }
     captureSnapshot() {
         const ctx = (0, runtime_1.getRuntimeContext)();
@@ -64,7 +64,7 @@ let StateInspectorService = class StateInspectorService extends IDevModeInspecto
         // Note: This is a simplified implementation
         // The actual implementation depends on tsyringe internals
         try {
-            const container = container_1.di;
+            const container = container_1.GLOBAL_CONTAINER;
             if (container._registry) {
                 for (const [token, registration] of container._registry) {
                     const tokenName = typeof token === 'function' ? token.name : String(token);

package/dist/runtime/server/devmode/types.d.ts

@@ -29,96 +29,131 @@ export interface DevEvent {
 }
 /**
  * Message sent through the DevMode bridge.
+ *
+ * @remarks
+ * The bridge acts as a telemetry and control tunnel between the OpenCore runtime
+ * and the external CLI. It allows for real-time log streaming and state inspection.
  */
 export interface BridgeMessage {
-    type: 'log' | 'event' | 'state' | 'command' | 'reload' | 'ping' | 'pong';
+    /**
+     * Message type:
+     * - 'log': Real-time server log streaming
+     * - 'event': Notification of a captured event (net, command, etc)
+     * - 'state': Runtime state snapshot response
+     * - 'command': Control command from CLI (e.g. trigger simulation)
+     * - 'ping'/'pong': Connection heartbeat
+     */
+    type: 'log' | 'event' | 'state' | 'command' | 'ping' | 'pong';
+    /** Data associated with the message */
     payload: unknown;
 }
 /**
  * Snapshot of the runtime state.
+ *
+ * @remarks
+ * Used by the CLI to visualize the current state of the framework without
+ * requiring game access.
  */
 export interface RuntimeSnapshot {
     /** Capture timestamp */
     timestamp: number;
-    /** Current framework mode */
+    /** Current framework mode (CORE, RESOURCE, STANDALONE) */
     mode: FrameworkMode;
-    /** Enabled features */
+    /** Enabled features and their status */
     features: Record<string, boolean>;
-    /** Player information */
+    /** Player information (simulated and real) */
     players: {
         count: number;
         ids: number[];
     };
-    /** Registered handlers */
+    /** Registered handlers for discovery */
     handlers: {
         commands: string[];
         netEvents: string[];
         exports: string[];
         fiveMEvents: string[];
     };
-    /** DI container info */
+    /** DI container information */
     diContainer: {
         registrations: number;
         singletons: string[];
     };
 }
-/**
- * Hot reload configuration.
- */
-export interface HotReloadOptions {
-    /** Enable hot reload server */
-    enabled: boolean;
-    /** HTTP port for reload endpoint */
-    port: number;
-    /** Resources allowed to trigger reload (empty = all) */
-    allowedResources?: string[];
-}
 /**
  * Bridge configuration for CLI connection.
+ *
+ * @remarks
+ * The bridge enables advanced development features like log streaming to CLI
+ * and state inspection. It does NOT handle resource restarts (txAdmin handles that).
  */
 export interface BridgeOptions {
-    /** WebSocket URL to connect to */
+    /**
+     * WebSocket URL of the OpenCore CLI bridge.
+     * @defaultValue 'ws://localhost:3848'
+     */
     url: string;
-    /** Auto-connect on dev mode start */
+    /**
+     * Whether to connect to the bridge automatically on startup.
+     * @defaultValue false
+     */
     autoConnect: boolean;
-    /** Reconnect on disconnect */
+    /** Whether to attempt reconnection if connection is lost */
     reconnect?: boolean;
-    /** Reconnect interval in milliseconds */
+    /** Delay between reconnection attempts in milliseconds */
     reconnectInterval?: number;
 }
 /**
  * Event interceptor configuration.
+ *
+ * @remarks
+ * The interceptor captures and records all incoming/outgoing events (Net, Commands, etc.)
+ * for debugging purposes.
  */
 export interface InterceptorOptions {
     /** Enable event interception */
     enabled: boolean;
-    /** Record event history */
+    /** Whether to keep a history of events in memory */
     recordHistory: boolean;
-    /** Maximum events to keep in history */
+    /** Maximum number of events to keep in the history buffer */
     maxHistorySize: number;
 }
 /**
  * Player simulator configuration.
+ *
+ * @remarks
+ * The simulator allows for creating "virtual" players that the framework
+ * treats as real, enabling testing of permissions, economy, and logic without game clients.
  */
 export interface SimulatorOptions {
-    /** Enable player simulation */
+    /** Enable player simulation features */
     enabled: boolean;
-    /** Number of players to auto-connect on start */
+    /** Number of virtual players to connect automatically on startup */
     autoConnectPlayers: number;
 }
 /**
  * Main DevMode configuration.
+ *
+ * @remarks
+ * Development mode provides tools for debugging, inspection, and simulation.
+ * It is dynamically loaded and should be disabled in production.
  */
 export interface DevModeOptions {
-    /** Enable dev mode */
+    /**
+     * Master switch for development mode.
+     * If false, no dev tools will be loaded.
+     */
     enabled: boolean;
-    /** Hot reload configuration */
-    hotReload?: HotReloadOptions;
-    /** Bridge configuration */
+    /**
+     * CLI Bridge configuration for telemetry and logs.
+     */
     bridge?: BridgeOptions;
-    /** Interceptor configuration */
+    /**
+     * Event interceptor for debugging network/command flow.
+     */
     interceptor?: InterceptorOptions;
-    /** Simulator configuration */
+    /**
+     * Virtual player simulator for offline testing.
+     */
     simulator?: SimulatorOptions;
 }
 /**
@@ -157,5 +192,6 @@ export interface SimulatedPlayer {
 }
 /**
  * Default DevMode configuration.
+ * Centered on telemetry and simulation, delegating resource management to CLI/txAdmin.
  */
 export declare const DEFAULT_DEVMODE_OPTIONS: DevModeOptions;

package/dist/runtime/server/devmode/types.js

@@ -3,13 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_DEVMODE_OPTIONS = void 0;
 /**
  * Default DevMode configuration.
+ * Centered on telemetry and simulation, delegating resource management to CLI/txAdmin.
  */
 exports.DEFAULT_DEVMODE_OPTIONS = {
     enabled: false,
-    hotReload: {
-        enabled: true,
-        port: 3847,
-    },
     bridge: {
         url: 'ws://localhost:3848',
         autoConnect: false,

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;