@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.2

package/dist/runtime/server/apis/vehicles.api.js

@@ -0,0 +1,398 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'tsyringe';
+import { IHasher } from '../../../adapters/contracts/IHasher';
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { IEntityServer } from '../../../adapters/contracts/server/IEntityServer';
+import { IVehicleLifecycleServer } from '../../../adapters/contracts/server/vehicle-lifecycle/IVehicleLifecycleServer';
+import { IVehicleServer } from '../../../adapters/contracts/server/IVehicleServer';
+import { coreLogger } from '../../../kernel/logger';
+import { Vehicle } from '../entities/vehicle';
+import { Players } from '../ports/players.api-port';
+const DEFAULT_PLAYER_VEHICLE_OFFSET = { x: 0, y: 3, z: 0 };
+/**
+ * Server-side service for managing vehicle entities.
+ *
+ * This service is the central authority for all vehicle operations:
+ * - Creating vehicles server-side (prevents client-side spawning abuse)
+ * - Managing vehicle registry by Network ID
+ * - Validating permissions and positions
+ * - Synchronizing vehicle state across clients
+ *
+ * @remarks
+ * All vehicle creation MUST go through this service to ensure security.
+ * Uses CreateVehicleServerSetter for server-authoritative spawning.
+ */
+let Vehicles = class Vehicles {
+    playerDirectory;
+    entityServer;
+    vehicleServer;
+    vehicleLifecycle;
+    hasher;
+    events;
+    /**
+     * Internal registry of all managed vehicles indexed by Network ID
+     */
+    vehiclesByNetworkId = new Map();
+    /**
+     * Cached adapters bundle for Vehicle instances
+     */
+    vehicleAdapters;
+    constructor(playerDirectory, entityServer, vehicleServer, vehicleLifecycle, hasher, events) {
+        this.playerDirectory = playerDirectory;
+        this.entityServer = entityServer;
+        this.vehicleServer = vehicleServer;
+        this.vehicleLifecycle = vehicleLifecycle;
+        this.hasher = hasher;
+        this.events = events;
+        this.vehicleAdapters = {
+            entityServer: this.entityServer,
+            vehicleServer: this.vehicleServer,
+        };
+    }
+    /**
+     * Creates a new vehicle on the server.
+     *
+     * This method uses CreateVehicleServerSetter to spawn the vehicle server-side,
+     * preventing client-side spawning exploits.
+     *
+     * @param options - Vehicle creation options
+     * @returns Spawn result with network ID and handle
+     */
+    async create(options) {
+        try {
+            const { model, position, heading = 0, plate, primaryColor, secondaryColor, mods, persistent = false, ownership, metadata, routingBucket = 0, locked = false, fuel = 100.0, } = options;
+            const modelHash = typeof model === 'string' ? this.hasher.getHashKey(model) : model;
+            const { handle, networkId } = await this.vehicleLifecycle.create({
+                model: typeof model === 'string' ? model : String(model),
+                modelHash,
+                position,
+                heading,
+            });
+            if (!Number.isFinite(handle) || handle < 0) {
+                coreLogger.error('Failed to create vehicle', { model, position });
+                return {
+                    networkId: 0,
+                    handle: 0,
+                    success: false,
+                    error: 'Failed to create vehicle entity',
+                };
+            }
+            while (!this.entityServer.doesExist(handle)) {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+            const vehicleOwnership = {
+                clientID: ownership?.clientID,
+                accountID: ownership?.accountID,
+                type: ownership?.type ?? 'temporary',
+            };
+            const vehicle = new Vehicle(handle, networkId, vehicleOwnership, this.vehicleAdapters, persistent, routingBucket, model, modelHash);
+            // Server-side operations (these natives work on server)
+            if (plate) {
+                vehicle.setPlate(plate);
+            }
+            if (primaryColor !== undefined || secondaryColor !== undefined) {
+                vehicle.setColors(primaryColor, secondaryColor);
+            }
+            // Mods stored in state bag, applied client-side
+            if (mods) {
+                vehicle.setMods(mods);
+            }
+            if (metadata) {
+                for (const [key, value] of Object.entries(metadata)) {
+                    vehicle.setMetadata(key, value);
+                }
+            }
+            vehicle.setDoorsLocked(locked);
+            vehicle.setFuel(fuel);
+            if (routingBucket !== 0) {
+                vehicle.setRoutingBucket(routingBucket);
+            }
+            this.vehiclesByNetworkId.set(networkId, vehicle);
+            let ownershipComp = vehicleOwnership.type;
+            if (vehicleOwnership.type === 'player') {
+                ownershipComp = `${vehicleOwnership.type}:${ownership?.clientID}`;
+            }
+            coreLogger.info('Vehicle created', {
+                networkId,
+                model,
+                ownership: ownershipComp,
+                persistent,
+                totalVehicles: this.vehiclesByNetworkId.size,
+            });
+            this.events.emit('opencore:vehicle:created', 'all', vehicle.serialize());
+            return {
+                networkId,
+                handle,
+                success: true,
+            };
+        }
+        catch (error) {
+            const errorInfo = error instanceof Error
+                ? { message: error.message, name: error.name, stack: error.stack }
+                : { message: String(error) };
+            coreLogger.error('Error creating vehicle', { error: errorInfo, options });
+            return {
+                networkId: 0,
+                handle: 0,
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Creates a vehicle for a specific player.
+     *
+     * @param clientID - Client ID of the requesting player
+     * @param options - Vehicle creation options
+     * @returns Spawn result
+     */
+    async createForPlayer(playerOrClientID, options) {
+        const player = this.resolvePlayer(playerOrClientID);
+        if (!player) {
+            return {
+                networkId: 0,
+                handle: 0,
+                success: false,
+                error: 'Player not found',
+            };
+        }
+        const ownership = {
+            clientID: player.clientID,
+            accountID: player.accountID,
+            type: 'player',
+        };
+        const spawnPosition = this.getSpawnPositionForPlayer(player, options.offset);
+        const spawnHeading = options.heading ?? player.getHeading();
+        const result = await this.create({
+            ...options,
+            position: spawnPosition,
+            heading: spawnHeading,
+            ownership,
+        });
+        if (result.success) {
+            const seatIndex = options.seatIndex ?? -1;
+            await Promise.resolve(this.vehicleLifecycle.warpPlayerIntoVehicle({
+                playerSrc: player.clientID.toString(),
+                networkId: result.networkId,
+                seatIndex,
+            }));
+        }
+        return result;
+    }
+    resolvePlayer(playerOrClientID) {
+        return typeof playerOrClientID === 'number'
+            ? this.playerDirectory.getByClient(playerOrClientID)
+            : playerOrClientID;
+    }
+    getSpawnPositionForPlayer(player, offset = DEFAULT_PLAYER_VEHICLE_OFFSET) {
+        const position = player.getPosition();
+        const headingRadians = (player.getHeading() * Math.PI) / 180;
+        return {
+            x: position.x + Math.sin(headingRadians) * offset.y + Math.cos(headingRadians) * offset.x,
+            y: position.y + Math.cos(headingRadians) * offset.y - Math.sin(headingRadians) * offset.x,
+            z: position.z + offset.z,
+        };
+    }
+    /**
+     * Retrieves a vehicle by its Network ID.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @returns Vehicle entity or undefined
+     */
+    getByNetworkId(networkId) {
+        return this.vehiclesByNetworkId.get(networkId);
+    }
+    /**
+     * Retrieves a vehicle by its entity handle.
+     *
+     * @param handle - Entity handle
+     * @returns Vehicle entity or undefined
+     */
+    getByHandle(handle) {
+        const networkId = this.vehicleServer.getNetworkIdFromEntity(handle);
+        return this.vehiclesByNetworkId.get(networkId);
+    }
+    /**
+     * Gets all vehicles owned by a specific player.
+     *
+     * @param clientID - Client ID of the owner
+     * @returns Array of vehicles
+     */
+    getPlayerVehicles(clientID) {
+        const vehicles = [];
+        for (const vehicle of this.vehiclesByNetworkId.values()) {
+            if (vehicle.ownership.clientID === clientID) {
+                vehicles.push(vehicle);
+            }
+        }
+        return vehicles;
+    }
+    /**
+     * Gets all vehicles in a specific routing bucket.
+     *
+     * @param bucket - Routing bucket ID
+     * @returns Array of vehicles
+     */
+    getVehiclesInBucket(bucket) {
+        const vehicles = [];
+        for (const vehicle of this.vehiclesByNetworkId.values()) {
+            if (vehicle.routingBucket === bucket) {
+                vehicles.push(vehicle);
+            }
+        }
+        return vehicles;
+    }
+    /**
+     * Gets all managed vehicles.
+     *
+     * @returns Array of all vehicles
+     */
+    getAll() {
+        return Array.from(this.vehiclesByNetworkId.values());
+    }
+    /**
+     * Deletes a vehicle from the server.
+     *
+     * @param networkId - Network ID of the vehicle to delete
+     * @param requestedBy - Optional client ID for permission validation
+     * @returns Success status
+     */
+    delete(networkId, requestedBy) {
+        const vehicle = this.vehiclesByNetworkId.get(networkId);
+        if (!vehicle) {
+            return false;
+        }
+        if (requestedBy !== undefined) {
+            if (vehicle.ownership.clientID !== requestedBy) {
+                coreLogger.warn('Unauthorized vehicle deletion attempt', {
+                    networkId,
+                    requestedBy,
+                    owner: vehicle.ownership.clientID,
+                });
+                return false;
+            }
+        }
+        vehicle.delete();
+        this.vehiclesByNetworkId.delete(networkId);
+        coreLogger.info('Vehicle deleted', {
+            networkId,
+            totalVehicles: this.vehiclesByNetworkId.size,
+        });
+        this.events.emit('opencore:vehicle:deleted', 'all', networkId);
+        return true;
+    }
+    /**
+     * Deletes all vehicles owned by a player.
+     * Useful when a player disconnects.
+     *
+     * @param clientID - Client ID of the owner
+     */
+    deletePlayerVehicles(clientID) {
+        const vehicles = this.getPlayerVehicles(clientID);
+        for (const vehicle of vehicles) {
+            this.delete(vehicle.networkId);
+        }
+    }
+    /**
+     * Validates if a player can perform an action on a vehicle.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param clientID - Client ID of the player
+     * @returns True if authorized
+     */
+    validateOwnership(networkId, clientID) {
+        const vehicle = this.vehiclesByNetworkId.get(networkId);
+        if (!vehicle)
+            return false;
+        if (vehicle.ownership.type === 'server' || vehicle.ownership.type === 'shared') {
+            return true;
+        }
+        return vehicle.ownership.clientID === clientID;
+    }
+    /**
+     * Validates if a player is near a vehicle.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param clientID - Client ID of the player
+     * @param maxDistance - Maximum distance in units
+     * @returns True if within range
+     */
+    validateProximity(networkId, clientID, maxDistance = 10.0) {
+        const vehicle = this.vehiclesByNetworkId.get(networkId);
+        if (!vehicle || !vehicle.exists)
+            return false;
+        const player = this.playerDirectory.getByClient(clientID);
+        if (!player)
+            return false;
+        const playerPos = player.getPosition();
+        const vehiclePos = vehicle.position;
+        const distance = Math.sqrt((playerPos.x - vehiclePos.x) ** 2 +
+            (playerPos.y - vehiclePos.y) ** 2 +
+            (playerPos.z - vehiclePos.z) ** 2);
+        return distance <= maxDistance;
+    }
+    /**
+     * Cleans up orphaned vehicles that no longer exist.
+     */
+    cleanup() {
+        const toDelete = [];
+        for (const [networkId, vehicle] of this.vehiclesByNetworkId.entries()) {
+            if (!vehicle.exists) {
+                toDelete.push(networkId);
+            }
+        }
+        for (const networkId of toDelete) {
+            this.vehiclesByNetworkId.delete(networkId);
+            coreLogger.debug('Cleaned up orphaned vehicle', { networkId });
+        }
+        if (toDelete.length > 0) {
+            coreLogger.info('Vehicle cleanup completed', {
+                cleaned: toDelete.length,
+                remaining: this.vehiclesByNetworkId.size,
+            });
+        }
+    }
+    /**
+     * Gets the total count of managed vehicles.
+     *
+     * @returns Vehicle count
+     */
+    getCount() {
+        return this.vehiclesByNetworkId.size;
+    }
+    /**
+     * Serializes all vehicles for data transfer.
+     *
+     * @returns Array of serialized vehicle data
+     */
+    serializeAll() {
+        return Array.from(this.vehiclesByNetworkId.values()).map((v) => v.serialize());
+    }
+};
+Vehicles = __decorate([
+    injectable(),
+    __param(0, inject(Players)),
+    __param(1, inject(IEntityServer)),
+    __param(2, inject(IVehicleServer)),
+    __param(3, inject(IVehicleLifecycleServer)),
+    __param(4, inject(IHasher)),
+    __param(5, inject(EventsAPI)),
+    __metadata("design:paramtypes", [Players,
+        IEntityServer,
+        IVehicleServer,
+        IVehicleLifecycleServer,
+        IHasher,
+        EventsAPI])
+], Vehicles);
+export { Vehicles };

package/dist/runtime/server/bootstrap.d.ts

@@ -0,0 +1,21 @@
+import { type ServerRuntimeOptions } from './runtime';
+import type { PluginInstallContext, PluginRegistry } from './library/plugin';
+/**
+ * Bootstraps the OpenCore Server Application Context.
+ *
+ * This is the primary entry point for the server-side framework. It orchestrates the
+ * initialization of the Dependency Injection (DI) container and establishes the
+ * bridge between the low-level FiveM runtime and the OpenCore architecture.
+ *
+ * **Initialization Lifecycle:**
+ * 1. **Infrastructure Registration:** Registers core infrastructure services (`PlayerService`, `CommandService`, `HttpService`) as Singletons in the IoC container.
+ * 2. **Reflection & Discovery:** Scans all decorated classes (Controllers, Services) to extract metadata defined by `@Command`, `@OnNet`, etc.
+ * 3. **Runtime Binding:** Binds the discovered metadata to actual FiveM natives (e.g., `RegisterCommand`, `onNet`, `exports`).
+ * 4. **Session Management:** Activates the player session tracking system.
+ *
+ * @returns A promise that resolves when the Core is fully initialized and ready to process events.
+ */
+export declare function initServer(options: ServerRuntimeOptions, plugins?: {
+    registry: PluginRegistry;
+    context: PluginInstallContext;
+}): Promise<void>;