@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

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

@@ -0,0 +1,239 @@
+import { IPlayerInfo } from '../../../adapters';
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+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 '../types/linked-id';
+import { PlayerSession } from '../types/player-session.types';
+import { SerializedPlayerData } from '../types/core-exports.types';
+import { NativeHandle } from 'src/runtime/core/nativehandle';
+/**
+ * Adapter bundle for player operations.
+ * Passed to Player instances by PlayerDirectory.
+ */
+export interface PlayerAdapters {
+    playerInfo: IPlayerInfo;
+    playerServer: IPlayerServer;
+    entityServer: IEntityServer;
+    events: EventsAPI<'server'>;
+    defaultSpawnModel: string;
+}
+/**
+ * Core-level representation of a connected player on the server.
+ *
+ * @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).
+ * Domain logic should live in your modules' services/models (e.g., `EconomyService`, `JobModel`).
+ */
+export declare class Player extends BaseEntity implements Spatial, NativeHandle {
+    private readonly session;
+    private readonly adapters;
+    private _position;
+    /**
+     * Creates a new Player entity instance.
+     * This is typically instantiated by the `PlayerService` upon connection.
+     *
+     * @param session - The internal session data structure holding ID and metadata.
+     * @param adapters - Platform adapters for player operations.
+     */
+    constructor(session: PlayerSession, adapters: PlayerAdapters);
+    getHeading(): number;
+    setHeading(heading: number): void;
+    getHandle(): number;
+    /**
+     * The numeric client/server ID of the player.
+     * This is the platform-specific player identifier used for native calls.
+     */
+    get clientID(): number;
+    /**
+     * 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.
+     */
+    get name(): string;
+    getPosition(): Vector3;
+    /**
+     * Sets the player position using the platform-agnostic API.
+     *
+     * @param vector - The target coordinates (x, y, z).
+     */
+    setPosition(vector: Vector3): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Sends a private message to the player.
+     *
+     * @param message - The message text
+     * @param type - Message type for styling
+     */
+    send(message: string, type?: 'chat' | 'error' | 'success' | 'warning'): void;
+    /**
+     * 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).
+     */
+    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 from platform capabilities)
+     */
+    spawn(vector: Vector3, model?: string): void;
+    /**
+     * Disconnects the player from the server.
+     *
+     * @param reason - The message displayed to the player upon disconnection.
+     */
+    kick(reason?: string): void;
+    /**
+     * 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.
+     *
+     * @param key - The unique key for the metadata.
+     * @param value - The value to store.
+     */
+    setMeta<T = unknown>(key: string, value: T): void;
+    /**
+     * Retrieves metadata previously stored in the session.
+     *
+     * @param key - The metadata key.
+     * @returns The value cast to T, or `undefined` if not set.
+     */
+    getMeta<T = unknown>(key: string): T | undefined;
+    /**
+     * Links a persistent Account ID to the current session.
+     * Should be called after successful authentication.
+     *
+     * @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').
+     */
+    hasState(state: string): boolean;
+    /**
+     * Applies a state flag to the player.
+     *
+     * @param state - The state key to add.
+     */
+    addState(state: string): void;
+    /**
+     * Removes a specific state flag from the player.
+     *
+     * @param state - The state key to remove.
+     */
+    removeState(state: string): void;
+    /**
+     * Toggles the presence of a state flag.
+     *
+     * @param state - The state key to toggle.
+     * @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 all currently active state flags.
+     */
+    getStates(): string[];
+    /**
+     * Gets the current health of the player's ped.
+     */
+    getHealth(): number;
+    /**
+     * Sets the health of the player's ped.
+     *
+     * @param health - Health value to set (platform-specific range).
+     */
+    setHealth(health: number): void;
+    /**
+     * Gets the current armor of the player's ped.
+     */
+    getArmor(): number;
+    /**
+     * Sets the armor of the player's ped.
+     *
+     * @param armor - Armor value to set (typically 0-100).
+     */
+    setArmor(armor: number): void;
+    /**
+     * Kills the player by setting health to 0.
+     */
+    kill(): void;
+    /**
+     * Checks if the player is alive.
+     *
+     * @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.
+     *
+     * @returns Serialized player data DTO
+     */
+    serialize(): SerializedPlayerData;
+}

package/dist/runtime/server/entities/player.js

@@ -0,0 +1,340 @@
+import { BaseEntity } from '../../core/entity';
+/**
+ * Core-level representation of a connected player on the server.
+ *
+ * @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).
+ * Domain logic should live in your modules' services/models (e.g., `EconomyService`, `JobModel`).
+ */
+export class Player extends BaseEntity {
+    session;
+    adapters;
+    _position;
+    /**
+     * Creates a new Player entity instance.
+     * This is typically instantiated by the `PlayerService` upon connection.
+     *
+     * @param session - The internal session data structure holding ID and metadata.
+     * @param adapters - Platform adapters for player operations.
+     */
+    constructor(session, adapters) {
+        super(`player:${session.clientID}`);
+        this.session = session;
+        this.adapters = adapters;
+        this._position = adapters.playerInfo.getPlayerPosition(session.clientID);
+    }
+    getHeading() {
+        return this.adapters.entityServer.getHeading(this.clientID);
+    }
+    setHeading(heading) {
+        this.adapters.entityServer.setHeading(this.clientID, heading);
+    }
+    getHandle() {
+        return this.clientID;
+    }
+    /**
+     * The numeric client/server ID of the player.
+     * This is the platform-specific player identifier used for native calls.
+     */
+    get clientID() {
+        return this.session.clientID;
+    }
+    /**
+     * 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() {
+        return this.session.accountID?.toString();
+    }
+    /**
+     * The display name of the player.
+     */
+    get name() {
+        return this.adapters.playerInfo.getPlayerName(this.clientID) ?? `Player#${this.clientID}`;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Position / Spatial
+    // ─────────────────────────────────────────────────────────────────
+    getPosition() {
+        this._position = this.adapters.playerInfo.getPlayerPosition(this.clientID);
+        return this._position;
+    }
+    /**
+     * Sets the player position using the platform-agnostic API.
+     *
+     * @param vector - The target coordinates (x, y, z).
+     */
+    setPosition(vector) {
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        this.adapters.entityServer.setPosition(ped, vector, { clearArea: true });
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Identifiers
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Retrieves all identifiers as structured objects.
+     *
+     * @returns An array of PlayerIdentifier objects with type, value, and raw fields.
+     */
+    getPlayerIdentifiers() {
+        return this.adapters.playerServer.getPlayerIdentifiers(this.clientID.toString());
+    }
+    /**
+     * 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) {
+        return this.adapters.playerServer.getIdentifier(this.clientID.toString(), identifierType);
+    }
+    /**
+     * Gets the player's license identifier.
+     * @deprecated Use getIdentifier('license') for cross-platform compatibility.
+     */
+    getLicense() {
+        return this.getIdentifier('license');
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Network Communication
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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, ...args) {
+        this.adapters.events.emit(eventName, this.clientID, ...args);
+    }
+    /**
+     * Sends a private message to the player.
+     *
+     * @param message - The message text
+     * @param type - Message type for styling
+     */
+    send(message, type = 'chat') {
+        this.emit('core:chat:send', message, type);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Spawning / Teleporting
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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).
+     */
+    teleport(vector) {
+        this.emit('opencore:spawner:teleport', vector);
+    }
+    /**
+     * Spawns the player at a position with a specific model.
+     *
+     * @param vector - The spawn coordinates
+     * @param model - The ped model to use (default from platform capabilities)
+     */
+    spawn(vector, model = this.adapters.defaultSpawnModel) {
+        this.emit('opencore:spawner:spawn', { position: vector, model });
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Connection Management
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Disconnects the player from the server.
+     *
+     * @param reason - The message displayed to the player upon disconnection.
+     */
+    kick(reason = 'Kicked from server') {
+        this.adapters.playerServer.drop(this.clientID.toString(), reason);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Dimension / Routing Bucket
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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) {
+        this.adapters.playerServer.setRoutingBucket(this.clientID.toString(), bucket);
+        this._dimension = bucket;
+    }
+    /**
+     * Gets the current routing bucket.
+     */
+    getRoutingBucket() {
+        return this.adapters.playerServer.getRoutingBucket(this.clientID.toString());
+    }
+    /**
+     * Sets the player dimension (alias for setRoutingBucket).
+     */
+    set dimension(value) {
+        this.setRoutingBucket(value);
+    }
+    /**
+     * Gets the player dimension (alias for getRoutingBucket).
+     */
+    get dimension() {
+        return this.getRoutingBucket();
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Session Metadata (Transient)
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Stores arbitrary transient metadata for this player's session.
+     * Useful for flags like `isDead`, `isInRaid`, `lastLocation`, etc.
+     *
+     * @param key - The unique key for the metadata.
+     * @param value - The value to store.
+     */
+    setMeta(key, value) {
+        this.session.meta[key] = value;
+    }
+    /**
+     * Retrieves metadata previously stored in the session.
+     *
+     * @param key - The metadata key.
+     * @returns The value cast to T, or `undefined` if not set.
+     */
+    getMeta(key) {
+        return this.session.meta[key];
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Account Linking
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Links a persistent Account ID to the current session.
+     * Should be called after successful authentication.
+     *
+     * @param accountID - The unique ID from the persistent storage.
+     */
+    linkAccount(accountID) {
+        this.session.accountID = accountID;
+    }
+    /**
+     * Unlinks the account from the current session.
+     */
+    unlinkAccount() {
+        this.session.accountID = undefined;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // State Flags
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Checks if the player currently possesses a specific state flag.
+     *
+     * @param state - The unique string identifier of the state (e.g., 'dead', 'cuffed').
+     */
+    hasState(state) {
+        return super.has(state);
+    }
+    /**
+     * Applies a state flag to the player.
+     *
+     * @param state - The state key to add.
+     */
+    addState(state) {
+        super.add(state);
+    }
+    /**
+     * Removes a specific state flag from the player.
+     *
+     * @param state - The state key to remove.
+     */
+    removeState(state) {
+        super.delete(state);
+    }
+    /**
+     * Toggles the presence of a state flag.
+     *
+     * @param state - The state key to toggle.
+     * @param force - If provided, forces the state to be added or removed.
+     * @returns The final status of the state.
+     */
+    toggleState(state, force) {
+        return super.toggle(state, force);
+    }
+    /**
+     * Retrieves all currently active state flags.
+     */
+    getStates() {
+        return super.all();
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Health & Armor
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Gets the current health of the player's ped.
+     */
+    getHealth() {
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        return this.adapters.entityServer.getHealth(ped);
+    }
+    /**
+     * Sets the health of the player's ped.
+     *
+     * @param health - Health value to set (platform-specific range).
+     */
+    setHealth(health) {
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        this.adapters.entityServer.setHealth(ped, health);
+    }
+    /**
+     * Gets the current armor of the player's ped.
+     */
+    getArmor() {
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        return this.adapters.entityServer.getArmor(ped);
+    }
+    /**
+     * Sets the armor of the player's ped.
+     *
+     * @param armor - Armor value to set (typically 0-100).
+     */
+    setArmor(armor) {
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        this.adapters.entityServer.setArmor(ped, armor);
+    }
+    /**
+     * Kills the player by setting health to 0.
+     */
+    kill() {
+        this.setHealth(0);
+    }
+    /**
+     * Checks if the player is alive.
+     *
+     * @remarks
+     * The threshold (100) is platform-specific. In GTA V-based platforms,
+     * health below 100 means dead.
+     */
+    isAlive() {
+        return this.getHealth() > 100;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Serialization
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Serializes the player data for cross-resource transfer.
+     *
+     * @returns Serialized player data DTO
+     */
+    serialize() {
+        return {
+            clientID: this.clientID,
+            accountID: this.accountID,
+            identifiers: this.session.identifiers,
+            meta: { ...this.session.meta },
+            states: this.getStates(),
+        };
+    }
+}

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

@@ -0,0 +1,113 @@
+import { IEntityServer } from '../../../adapters/contracts/server/IEntityServer';
+import { IVehicleServer } from '../../../adapters/contracts/server/IVehicleServer';
+import { Vector3 } from '../../../kernel/utils/vector3';
+import { BaseEntity } from '../../core/entity';
+import { NativeHandle } from '../../core/nativehandle';
+import { Spatial } from '../../core/spatial';
+import { SerializedVehicleData, VehicleMetadata, VehicleMods, VehicleOwnership } from '../types/vehicle.types';
+/**
+ * Adapter bundle used by {@link Vehicle} to call platform-specific natives.
+ */
+export interface VehicleAdapters {
+    entityServer: IEntityServer;
+    vehicleServer: IVehicleServer;
+}
+/**
+ * Runtime representation of a server-managed vehicle entity.
+ *
+ * @remarks
+ * This class stores ownership/mod/metadata state and delegates native calls through
+ * framework adapters. Most mutating methods are no-ops when the entity no longer exists.
+ */
+export declare class Vehicle extends BaseEntity implements Spatial, NativeHandle {
+    private readonly session;
+    private readonly adapters;
+    private ownershipData;
+    private modsData;
+    private metadataData;
+    /**
+     * Creates a new vehicle entity wrapper.
+     *
+     * @param handle - Native entity handle.
+     * @param networkId - Network ID for cross-client references.
+     * @param ownership - Initial ownership descriptor.
+     * @param adapters - Entity/vehicle adapters.
+     * @param persistent - Whether orphan mode should keep this entity alive.
+     * @param routingBucket - Initial routing bucket.
+     * @param model - Resolved model string.
+     * @param modelHash - Spawn model hash.
+     */
+    constructor(handle: number, networkId: number, ownership: VehicleOwnership, adapters: VehicleAdapters, persistent: boolean | undefined, routingBucket: number | undefined, model: string, modelHash: number);
+    /** Returns the native entity handle. */
+    getHandle(): number;
+    /** Returns current world coordinates. */
+    getPosition(): Vector3;
+    /** Teleports the entity to a target position. */
+    setPosition(position: Vector3): void;
+    /** Returns current heading (yaw). */
+    getHeading(): number;
+    /** Sets heading (yaw) in degrees. */
+    setHeading(heading: number): void;
+    /** Native handle shortcut. */
+    get handle(): number;
+    /** Stable network ID. */
+    get networkId(): number;
+    /** Resolved model identifier. */
+    get model(): string;
+    /** Model hash used at spawn time. */
+    get modelHash(): number;
+    /** Whether the vehicle is configured as persistent. */
+    get persistent(): boolean;
+    /** Current routing bucket/dimension. */
+    get routingBucket(): number;
+    /** Dimension alias for routing bucket. */
+    get dimension(): number;
+    /** Dimension alias for routing bucket. */
+    set dimension(value: number);
+    /** Snapshot of ownership data. */
+    get ownership(): VehicleOwnership;
+    /** Snapshot of stored mods. */
+    get mods(): VehicleMods;
+    /** Snapshot of metadata values. */
+    get metadata(): VehicleMetadata;
+    /** True when the underlying native entity exists. */
+    get exists(): boolean;
+    /** Position shorthand using {@link getPosition}. */
+    get position(): Vector3;
+    /** Heading shorthand using {@link getHeading}. */
+    get heading(): number;
+    /** Current license plate text. */
+    get plate(): string;
+    /** Merges ownership data and replicates it to state bag. */
+    setOwnership(ownership: Partial<VehicleOwnership>): void;
+    /** Merges vehicle mod state and updates modification timestamp. */
+    setMods(mods: Partial<VehicleMods>): void;
+    /** Stores custom metadata and replicates it to state bag. */
+    setMetadata(key: string, value: unknown): void;
+    /** Reads one metadata value by key. */
+    getMetadata<T = unknown>(key: string): T | undefined;
+    /** Reads current routing bucket, using cached value if entity no longer exists. */
+    getRoutingBucket(): number;
+    /** Sets routing bucket and updates local dimension snapshot. */
+    setRoutingBucket(bucket: number): void;
+    /** Sets plate text (trimmed to 8 chars). */
+    setPlate(plate: string): void;
+    /** Sets primary/secondary vehicle colors. */
+    setColors(primaryColor?: number, secondaryColor?: number): void;
+    /** Flags this vehicle for repair through replicated metadata. */
+    markForRepair(): void;
+    /** Sets fuel level in range 0-100. */
+    setFuel(level: number): void;
+    /** Gets stored fuel level, defaulting to 100. */
+    getFuel(): number;
+    /** Locks or unlocks doors and replicates lock state. */
+    setDoorsLocked(locked: boolean): void;
+    /** Teleports vehicle and optionally sets heading. */
+    teleport(position: Vector3, heading?: number): void;
+    /** Deletes the underlying entity. */
+    delete(): void;
+    /** Serializes this vehicle state for transport. */
+    serialize(): SerializedVehicleData;
+    /** Writes one replicated value to entity state bag. */
+    private syncStateBag;
+}