@open-core/framework 0.1.0-alpha.1 → 0.2.1-beta.1

package/dist/{server → runtime/server}/entities/player.js

@@ -17,10 +17,13 @@ class Player {
      * 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) {
+    constructor(session, adapters) {
         this.session = session;
+        this.adapters = adapters;
         this.states = new Set();
+        this.position = adapters.playerInfo.getPlayerPosition(session.clientID);
     }
     /**
      * The numeric FiveM Server ID (Source) of the player.
@@ -48,7 +51,13 @@ class Player {
      * The display name of the player (Steam name or FiveM username).
      */
     get name() {
-        return GetPlayerName(this.clientIDStr);
+        var _a;
+        return (_a = this.adapters.playerInfo.getPlayerName(this.clientID)) !== null && _a !== void 0 ? _a : `Player#${this.clientID}`;
+    }
+    getPosition() {
+        // re-set last position
+        this.position = this.adapters.playerInfo.getPlayerPosition(this.clientID);
+        return this.position;
     }
     /**
      * Retrieves all platform identifiers associated with the player (steam, license, discord, ip, etc.).
@@ -56,14 +65,7 @@ class Player {
      * @returns An array of identifier strings (e.g., `['steam:11000...', 'license:2332...']`).
      */
     getIdentifiers() {
-        const ids = [];
-        for (let i = 0;; i++) {
-            const id = GetPlayerIdentifier(this.clientIDStr, i);
-            if (!id)
-                break;
-            ids.push(id);
-        }
-        return ids;
+        return this.adapters.playerServer.getIdentifiers(this.clientIDStr);
     }
     /**
      * Sends a network event exclusively to this specific player (Client-side).
@@ -73,7 +75,11 @@ class Player {
      * @param args - Data to send to the client.
      */
     emit(eventName, ...args) {
-        emitNet(eventName, this.clientID, ...args);
+        this.adapters.netTransport.emitNet(eventName, this.clientID, ...args);
+    }
+    /** used to send a private message to the player */
+    send(message, type = 'chat') {
+        this.adapters.netTransport.emitNet('core:chat:send', this.clientID, message, type);
     }
     /**
      * Teleports the player to a given position using Server-Side natives.
@@ -84,7 +90,8 @@ class Player {
      * @param vector - The target coordinates (x, y, z).
      */
     teleport(vector) {
-        SetEntityCoords(GetPlayerPed(this.clientIDStr), vector.x, vector.y, vector.z, false, false, false, true);
+        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        this.adapters.entityServer.setCoords(ped, vector.x, vector.y, vector.z, false, false, false, true);
     }
     /**
      * Requests the Client to teleport itself via the Core Spawner system.
@@ -97,13 +104,16 @@ class Player {
     teleportClient(vector) {
         this.emit('opencore:spawner:teleport', vector);
     }
+    spawn(vector, model = 'mp_m_freemode_01') {
+        this.emit('opencore:spawner:spawn', { position: vector, model });
+    }
     /**
      * Disconnects the player from the server.
      *
      * @param reason - The message displayed to the player upon disconnection.
      */
     kick(reason = 'Kicked from server') {
-        DropPlayer(this.clientID.toString(), reason);
+        this.adapters.playerServer.drop(this.clientIDStr, reason);
     }
     /**
      * Sets the routing bucket (virtual world / dimension) for the player.
@@ -112,7 +122,7 @@ class Player {
      * @param bucket - The bucket ID (0 is the default shared world).
      */
     setRoutingBucket(bucket) {
-        SetPlayerRoutingBucket(this.clientID.toString(), bucket);
+        this.adapters.playerServer.setRoutingBucket(this.clientIDStr, bucket);
     }
     /**
      * Stores arbitrary transient metadata for this player's session.
@@ -213,5 +223,73 @@ class Player {
     getStates() {
         return Array.from(this.states);
     }
+    /**
+     * Gets the current health of the player's ped.
+     *
+     * @returns Current health value (0-200, where 100 is dead).
+     */
+    getHealth() {
+        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        return this.adapters.entityServer.getHealth(ped);
+    }
+    /**
+     * Sets the health of the player's ped.
+     *
+     * @param health - Health value to set (0-200).
+     */
+    setHealth(health) {
+        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        this.adapters.entityServer.setHealth(ped, health);
+    }
+    /**
+     * Gets the current armor of the player's ped.
+     *
+     * @returns Current armor value (0-100).
+     */
+    getArmor() {
+        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        return this.adapters.entityServer.getArmor(ped);
+    }
+    /**
+     * Sets the armor of the player's ped.
+     *
+     * @param armor - Armor value to set (0-100).
+     */
+    setArmor(armor) {
+        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        this.adapters.entityServer.setArmor(ped, armor);
+    }
+    /**
+     * Kills the player by setting health to 0.
+     */
+    kill() {
+        this.setHealth(0);
+    }
+    /**
+     * Checks if the player is alive.
+     *
+     * @returns `true` if health is above 100 (dead threshold), `false` otherwise.
+     */
+    isAlive() {
+        return this.getHealth() > 100;
+    }
+    /**
+     * 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() {
+        return {
+            clientID: this.clientID,
+            accountID: this.accountID,
+            identifiers: this.session.identifiers,
+            meta: Object.assign({}, this.session.meta),
+            states: this.getStates(),
+        };
+    }
 }
 exports.Player = Player;

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

@@ -0,0 +1,160 @@
+import { IEntityServer } from '../../../adapters/contracts/IEntityServer';
+import { IVehicleServer } from '../../../adapters/contracts/IVehicleServer';
+import { Vector3 } from '../../../kernel/utils';
+import { SerializedVehicleData, VehicleMetadata, VehicleMods, VehicleOwnership } from '../types/vehicle.types';
+/**
+ * Adapter bundle for vehicle operations.
+ * Passed to Vehicle instances by VehicleService.
+ */
+export interface VehicleAdapters {
+    entityServer: IEntityServer;
+    vehicleServer: IVehicleServer;
+}
+/**
+ * Server-side representation of a vehicle entity.
+ *
+ * This class wraps FiveM server-side vehicle natives and manages vehicle state.
+ * All vehicle creation and modification should go through this entity
+ * to ensure proper synchronization and security.
+ *
+ * ⚠️ **Design Note:** Vehicles are created server-side using CreateVehicleServerSetter
+ * to prevent client-side spawning abuse. Network IDs are used for cross-client references.
+ *
+ * ⚠️ **Important:** Visual modifications (mods, repairs, fuel) are stored in state bags
+ * and must be applied client-side. The server only stores the desired state.
+ */
+export declare class Vehicle {
+    private readonly _networkId;
+    private readonly _handle;
+    private readonly _adapters;
+    private readonly _model;
+    private readonly _modelHash;
+    private _ownership;
+    private _mods;
+    private _metadata;
+    private _persistent;
+    private _routingBucket;
+    /**
+     * Creates a new Vehicle entity instance.
+     * This should only be instantiated by VehicleService after server-side creation.
+     *
+     * @param handle - The server-side entity handle
+     * @param networkId - The network ID for cross-client reference
+     * @param ownership - Ownership information
+     * @param adapters - Platform adapters for entity/vehicle operations
+     * @param persistent - Whether the vehicle should persist
+     * @param routingBucket - The routing bucket the vehicle belongs to
+     */
+    constructor(handle: number, networkId: number, ownership: VehicleOwnership, adapters: VehicleAdapters, persistent: boolean | undefined, routingBucket: number | undefined, model: string, modelHash: number);
+    get handle(): number;
+    get networkId(): number;
+    get ownership(): VehicleOwnership;
+    get mods(): VehicleMods;
+    get metadata(): VehicleMetadata;
+    get persistent(): boolean;
+    get routingBucket(): number;
+    get exists(): boolean;
+    get model(): string;
+    get modelHash(): number;
+    get position(): Vector3;
+    get heading(): number;
+    get plate(): string;
+    /**
+     * Updates the ownership of the vehicle.
+     *
+     * @param ownership - New ownership information
+     */
+    setOwnership(ownership: Partial<VehicleOwnership>): void;
+    /**
+     * Stores modifications in state bag for client-side application.
+     *
+     * @remarks
+     * Mods are stored server-side and synced via state bags.
+     * The client must read and apply these modifications locally.
+     *
+     * @param mods - Modifications to store
+     */
+    setMods(mods: Partial<VehicleMods>): void;
+    /**
+     * Sets custom metadata for the vehicle.
+     *
+     * @param key - Metadata key
+     * @param value - Metadata value
+     */
+    setMetadata(key: string, value: any): void;
+    /**
+     * Gets metadata value by key.
+     *
+     * @param key - Metadata key
+     * @returns The metadata value or undefined
+     */
+    getMetadata<T = any>(key: string): T | undefined;
+    /**
+     * Sets the routing bucket for the vehicle.
+     *
+     * @param bucket - Routing bucket ID
+     */
+    setRoutingBucket(bucket: number): void;
+    /**
+     * Sets the license plate text.
+     *
+     * @param plate - Plate text (max 8 characters)
+     */
+    setPlate(plate: string): void;
+    /**
+     * Sets the vehicle colors (server-side native).
+     *
+     * @param primaryColor - Primary color index
+     * @param secondaryColor - Secondary color index
+     */
+    setColors(primaryColor?: number, secondaryColor?: number): void;
+    /**
+     * Marks vehicle for repair (client applies the actual repair).
+     *
+     * @remarks
+     * Sets a state bag flag that clients should watch to apply repair locally.
+     */
+    markForRepair(): void;
+    /**
+     * Sets the fuel level (stored in metadata, applied client-side).
+     *
+     * @param level - Fuel level (0–100)
+     */
+    setFuel(level: number): void;
+    /**
+     * Gets the stored fuel level from metadata.
+     *
+     * @returns Fuel level (0-100) or 100 if not set
+     */
+    getFuel(): number;
+    /**
+     * Sets the vehicle doors locked state (server-side native).
+     *
+     * @param locked - Whether doors should be locked
+     */
+    setDoorsLocked(locked: boolean): void;
+    /**
+     * Teleports the vehicle to a position.
+     *
+     * @param position - Target position
+     * @param heading - Optional heading
+     */
+    teleport(position: Vector3, heading?: number): void;
+    /**
+     * Deletes the vehicle from the server.
+     */
+    delete(): void;
+    /**
+     * Syncs data to the vehicle's state bag for client access.
+     *
+     * @param key - State bag key
+     * @param value - Value to sync
+     */
+    private syncStateBag;
+    /**
+     * Serializes the vehicle data for network transfer.
+     *
+     * @returns Serialized vehicle data
+     */
+    serialize(): SerializedVehicleData;
+}

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

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Vehicle = void 0;
+/**
+ * Server-side representation of a vehicle entity.
+ *
+ * This class wraps FiveM server-side vehicle natives and manages vehicle state.
+ * All vehicle creation and modification should go through this entity
+ * to ensure proper synchronization and security.
+ *
+ * ⚠️ **Design Note:** Vehicles are created server-side using CreateVehicleServerSetter
+ * to prevent client-side spawning abuse. Network IDs are used for cross-client references.
+ *
+ * ⚠️ **Important:** Visual modifications (mods, repairs, fuel) are stored in state bags
+ * and must be applied client-side. The server only stores the desired state.
+ */
+class Vehicle {
+    /**
+     * Creates a new Vehicle entity instance.
+     * This should only be instantiated by VehicleService after server-side creation.
+     *
+     * @param handle - The server-side entity handle
+     * @param networkId - The network ID for cross-client reference
+     * @param ownership - Ownership information
+     * @param adapters - Platform adapters for entity/vehicle operations
+     * @param persistent - Whether the vehicle should persist
+     * @param routingBucket - The routing bucket the vehicle belongs to
+     */
+    constructor(handle, networkId, ownership, adapters, persistent = false, routingBucket = 0, model, modelHash) {
+        this._mods = {};
+        this._metadata = {};
+        this._handle = handle;
+        this._networkId = networkId;
+        this._ownership = ownership;
+        this._adapters = adapters;
+        this._persistent = persistent;
+        this._routingBucket = routingBucket;
+        this._model = model;
+        this._modelHash = modelHash;
+        if (persistent) {
+            this._adapters.entityServer.setOrphanMode(handle, 2);
+        }
+        this._metadata.createdAt = Date.now();
+    }
+    get handle() {
+        return this._handle;
+    }
+    get networkId() {
+        return this._networkId;
+    }
+    get ownership() {
+        return Object.assign({}, this._ownership);
+    }
+    get mods() {
+        return Object.assign({}, this._mods);
+    }
+    get metadata() {
+        return Object.assign({}, this._metadata);
+    }
+    get persistent() {
+        return this._persistent;
+    }
+    get routingBucket() {
+        return this._routingBucket;
+    }
+    get exists() {
+        return this._adapters.entityServer.doesExist(this._handle);
+    }
+    get model() {
+        return this._model;
+    }
+    get modelHash() {
+        return this._modelHash;
+    }
+    get position() {
+        return this._adapters.entityServer.getCoords(this._handle);
+    }
+    get heading() {
+        return this._adapters.entityServer.getHeading(this._handle);
+    }
+    get plate() {
+        return this._adapters.vehicleServer.getNumberPlateText(this._handle);
+    }
+    /**
+     * Updates the ownership of the vehicle.
+     *
+     * @param ownership - New ownership information
+     */
+    setOwnership(ownership) {
+        this._ownership = Object.assign(Object.assign({}, this._ownership), ownership);
+        this.syncStateBag('ownership', this._ownership);
+    }
+    /**
+     * Stores modifications in state bag for client-side application.
+     *
+     * @remarks
+     * Mods are stored server-side and synced via state bags.
+     * The client must read and apply these modifications locally.
+     *
+     * @param mods - Modifications to store
+     */
+    setMods(mods) {
+        if (!this.exists)
+            return;
+        this._mods = Object.assign(Object.assign({}, this._mods), mods);
+        this._metadata.modifiedAt = Date.now();
+        // Sync to state bag for client-side application
+        this.syncStateBag('mods', this._mods);
+    }
+    /**
+     * Sets custom metadata for the vehicle.
+     *
+     * @param key - Metadata key
+     * @param value - Metadata value
+     */
+    setMetadata(key, value) {
+        this._metadata[key] = value;
+        this.syncStateBag(`meta_${key}`, value);
+    }
+    /**
+     * Gets metadata value by key.
+     *
+     * @param key - Metadata key
+     * @returns The metadata value or undefined
+     */
+    getMetadata(key) {
+        return this._metadata[key];
+    }
+    /**
+     * Sets the routing bucket for the vehicle.
+     *
+     * @param bucket - Routing bucket ID
+     */
+    setRoutingBucket(bucket) {
+        if (!this.exists)
+            return;
+        this._adapters.entityServer.setRoutingBucket(this._handle, bucket);
+        this._routingBucket = bucket;
+    }
+    /**
+     * Sets the license plate text.
+     *
+     * @param plate - Plate text (max 8 characters)
+     */
+    setPlate(plate) {
+        if (!this.exists)
+            return;
+        this._adapters.vehicleServer.setNumberPlateText(this._handle, plate.substring(0, 8));
+    }
+    /**
+     * Sets the vehicle colors (server-side native).
+     *
+     * @param primaryColor - Primary color index
+     * @param secondaryColor - Secondary color index
+     */
+    setColors(primaryColor, secondaryColor) {
+        if (!this.exists)
+            return;
+        const [currentPrimary, currentSecondary] = this._adapters.vehicleServer.getColours(this._handle);
+        this._adapters.vehicleServer.setColours(this._handle, primaryColor !== null && primaryColor !== void 0 ? primaryColor : currentPrimary, secondaryColor !== null && secondaryColor !== void 0 ? secondaryColor : currentSecondary);
+    }
+    /**
+     * Marks vehicle for repair (client applies the actual repair).
+     *
+     * @remarks
+     * Sets a state bag flag that clients should watch to apply repair locally.
+     */
+    markForRepair() {
+        if (!this.exists)
+            return;
+        this._metadata.needsRepair = true;
+        this._metadata.repairRequestedAt = Date.now();
+        this.syncStateBag('needsRepair', true);
+    }
+    /**
+     * Sets the fuel level (stored in metadata, applied client-side).
+     *
+     * @param level - Fuel level (0–100)
+     */
+    setFuel(level) {
+        if (!this.exists)
+            return;
+        const clampedLevel = Math.max(0, Math.min(100, level));
+        this._metadata.fuel = clampedLevel;
+        this.syncStateBag('fuel', clampedLevel);
+    }
+    /**
+     * Gets the stored fuel level from metadata.
+     *
+     * @returns Fuel level (0-100) or 100 if not set
+     */
+    getFuel() {
+        var _a;
+        return (_a = this._metadata.fuel) !== null && _a !== void 0 ? _a : 100;
+    }
+    /**
+     * Sets the vehicle doors locked state (server-side native).
+     *
+     * @param locked - Whether doors should be locked
+     */
+    setDoorsLocked(locked) {
+        if (!this.exists)
+            return;
+        this._adapters.vehicleServer.setDoorsLocked(this._handle, locked ? 2 : 1);
+        this.syncStateBag('locked', locked);
+    }
+    /**
+     * Teleports the vehicle to a position.
+     *
+     * @param position - Target position
+     * @param heading - Optional heading
+     */
+    teleport(position, heading) {
+        if (!this.exists)
+            return;
+        this._adapters.entityServer.setCoords(this._handle, position.x, position.y, position.z, false, false, false, true);
+        if (heading !== undefined) {
+            this._adapters.entityServer.setHeading(this._handle, heading);
+        }
+    }
+    /**
+     * Deletes the vehicle from the server.
+     */
+    delete() {
+        if (!this.exists)
+            return;
+        this._adapters.entityServer.delete(this._handle);
+    }
+    /**
+     * Syncs data to the vehicle's state bag for client access.
+     *
+     * @param key - State bag key
+     * @param value - Value to sync
+     */
+    syncStateBag(key, value) {
+        const stateBag = this._adapters.entityServer.getStateBag(this._handle);
+        stateBag.set(key, value, true);
+    }
+    /**
+     * Serializes the vehicle data for network transfer.
+     *
+     * @returns Serialized vehicle data
+     */
+    serialize() {
+        return {
+            networkId: this._networkId,
+            handle: this._handle,
+            modelHash: this.modelHash,
+            model: this.model,
+            position: this.position,
+            heading: this.heading,
+            plate: this.plate,
+            ownership: this.ownership,
+            mods: this.mods,
+            metadata: this.metadata,
+            routingBucket: this._routingBucket,
+            persistent: this._persistent,
+        };
+    }
+}
+exports.Vehicle = Vehicle;

package/dist/{server → runtime/server}/error-handler.d.ts

@@ -1,2 +1,2 @@
-import type { CommandMetadata } from './decorators/command';
+import { CommandMetadata } from './decorators/command';
 export declare function handleCommandError(error: unknown, meta: CommandMetadata, playerId: number | null): void;

package/dist/{server → runtime/server}/error-handler.js

@@ -1,16 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleCommandError = handleCommandError;
-const utils_1 = require("../utils");
-const logger_1 = require("../shared/logger");
+const logger_1 = require("../../kernel/shared/logger");
+const utils_1 = require("../../kernel/utils");
 function normalizeError(error, origin) {
     if ((0, utils_1.isAppError)(error)) {
         return error;
     }
     if (error instanceof Error) {
-        return new utils_1.AppError('UNKNOWN', error.message, origin, { stack: error.stack });
+        return new utils_1.AppError('COMMON:UNKNOWN', error.message, origin, { stack: error.stack });
     }
-    return new utils_1.AppError('UNKNOWN', String(error), origin, { raw: error });
+    return new utils_1.AppError('COMMON:UNKNOWN', String(error), origin, { raw: error });
 }
 function handleCommandError(error, meta, playerId) {
     const appError = normalizeError(error, 'server');
@@ -25,10 +25,9 @@ function handleCommandError(error, meta, playerId) {
     });
     if (playerId !== null) {
         switch (appError.code) {
-            case 'VALIDATION_ERROR':
-            case 'INSUFFICIENT_FUNDS':
-            case 'PERMISSION_DENIED':
-            case 'UNAUTHORIZED':
+            case 'ECONOMY:INSUFFICIENT_FUNDS':
+            case 'AUTH:PERMISSION_DENIED':
+            case 'AUTH:UNAUTHORIZED':
                 emitNet('chat:addMessage', playerId, {
                     args: ['^1Error', appError.message],
                 });

package/dist/runtime/server/helpers/command-validation.helper.d.ts

@@ -0,0 +1,6 @@
+import { CommandMetadata } from '../decorators/command';
+import { Player } from '../entities';
+/**
+ * Centraliza validación de argumentos de comandos.
+ */
+export declare function validateAndExecuteCommand(meta: CommandMetadata, player: Player, args: string[], handler: Function): Promise<any>;