@open-core/framework 1.0.1-beta.1 → 1.0.4-beta.1

package/dist/client/services/spawn.service.js

@@ -0,0 +1,261 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpawnService = void 0;
+const tsyringe_1 = require("tsyringe");
+const shared_1 = require("../../shared");
+const appearance_service_1 = require("./appearance.service");
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const NETWORK_TIMEOUT_MS = 15000;
+const PED_TIMEOUT_MS = 10000;
+const COLLISION_TIMEOUT_MS = 7000;
+/**
+ * Handles all player spawning logic on the client.
+ *
+ * This service manages the complete lifecycle of a player spawn:
+ * - Waiting for the network session
+ * - Loading and applying the player model
+ * - Ensuring collision and world data is ready
+ * - Resurrecting the player cleanly
+ * - Applying default ped components for freemode models
+ * - Fading the screen in/out during transitions
+ *
+ * The service is designed to be robust, predictable, and safe for any gamemode.
+ */
+let SpawnService = class SpawnService {
+    constructor(appearanceService) {
+        this.appearanceService = appearanceService;
+        this.spawned = false;
+        this.spawning = false;
+    }
+    async init() {
+        shared_1.loggers.spawn.debug('SpawnService initialized');
+    }
+    /**
+     * Performs the first spawn of the player.
+     *
+     * This method handles:
+     * - Fade out
+     * - Closing loading screens
+     * - Setting the player model
+     * - Ensuring the ped exists
+     * - Ensuring collision is loaded
+     * - Resurrecting the player
+     * - Preparing the ped for gameplay
+     * - Placing the player at the desired position
+     * - Fade in
+     *
+     * It should only be called once when the player joins.
+     */
+    async spawn(position, model, heading = 0.0, options) {
+        if (this.spawning) {
+            shared_1.loggers.spawn.warn('Spawn requested while a spawn is already in progress');
+            return;
+        }
+        this.spawning = true;
+        try {
+            await this.ensureNetworkReady();
+            if (!IsScreenFadedOut() && !IsScreenFadingOut()) {
+                DoScreenFadeOut(500);
+                while (!IsScreenFadedOut()) {
+                    await delay(0);
+                }
+            }
+            this.closeLoadingScreens();
+            await this.setPlayerModel(model);
+            const ped = await this.ensurePed();
+            await this.applyAppearanceIfNeeded(ped, options === null || options === void 0 ? void 0 : options.appearance);
+            await this.ensureCollisionAt(position, ped);
+            NetworkResurrectLocalPlayer(position.x, position.y, position.z, heading, 0, false);
+            const finalPed = await this.ensurePed();
+            await this.setupPedForGameplay(finalPed);
+            await this.placePed(finalPed, position, heading);
+            this.spawned = true;
+            if (!IsScreenFadedIn() && !IsScreenFadingIn()) {
+                DoScreenFadeIn(500);
+            }
+            shared_1.loggers.spawn.info('Player spawned successfully (first spawn)', {
+                position: { x: position.x, y: position.y, z: position.z },
+                model,
+            });
+        }
+        catch (err) {
+            shared_1.loggers.spawn.error('Failed to spawn player', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+        finally {
+            this.spawning = false;
+        }
+    }
+    /**
+     * Teleports the player instantly to a new position.
+     * Does not change the model or resurrect the player.
+     * Safe for gameplay use.
+     */
+    async teleportTo(position, heading) {
+        const ped = await this.ensurePed();
+        await this.ensureCollisionAt(position, ped);
+        FreezeEntityPosition(ped, true);
+        SetEntityCoordsNoOffset(ped, position.x, position.y, position.z, false, false, false);
+        if (heading !== undefined) {
+            SetEntityHeading(ped, heading);
+        }
+        FreezeEntityPosition(ped, false);
+        shared_1.loggers.spawn.debug('Teleported', {
+            position: { x: position.x, y: position.y, z: position.z },
+            heading,
+        });
+    }
+    /**
+     * Respawns the player after death or a gameplay event.
+     * Restores health, resurrects the player, loads collision,
+     * prepares the ped and teleports them to the desired location.
+     */
+    async respawn(position, heading = 0.0) {
+        const ped = await this.ensurePed();
+        await this.ensureCollisionAt(position, ped);
+        ClearPedTasksImmediately(ped);
+        SetEntityHealth(ped, GetEntityMaxHealth(ped));
+        NetworkResurrectLocalPlayer(position.x, position.y, position.z, heading, 0, false);
+        const finalPed = await this.ensurePed();
+        await this.setupPedForGameplay(finalPed);
+        await this.teleportTo(position, heading);
+        shared_1.loggers.spawn.info('Player respawned', {
+            position: { x: position.x, y: position.y, z: position.z },
+            heading,
+        });
+    }
+    /**
+     * Returns whether the player has completed their first spawn.
+     */
+    isSpawned() {
+        return this.spawned;
+    }
+    /**
+     * Allows other systems to wait until the player is fully spawned.
+     */
+    async waitUntilSpawned() {
+        while (!this.spawned) {
+            await delay(0);
+        }
+    }
+    async ensureNetworkReady() {
+        const start = GetGameTimer();
+        while (!NetworkIsSessionStarted()) {
+            if (GetGameTimer() - start > NETWORK_TIMEOUT_MS) {
+                shared_1.loggers.spawn.error('Network session did not start in time');
+                throw new Error('NETWORK_TIMEOUT');
+            }
+            await delay(0);
+        }
+    }
+    closeLoadingScreens() {
+        try {
+            ShutdownLoadingScreen();
+        }
+        catch (_a) { }
+        try {
+            ShutdownLoadingScreenNui();
+        }
+        catch (_b) { }
+    }
+    async setPlayerModel(model) {
+        const modelHash = GetHashKey(model);
+        if (!IsModelInCdimage(modelHash) || !IsModelValid(modelHash)) {
+            shared_1.loggers.spawn.error('Invalid model requested', { model });
+            throw new Error('MODEL_INVALID');
+        }
+        RequestModel(modelHash);
+        while (!HasModelLoaded(modelHash)) {
+            await delay(0);
+        }
+        SetPlayerModel(PlayerId(), modelHash);
+        SetModelAsNoLongerNeeded(modelHash);
+        const ped = PlayerPedId();
+        if (ped !== 0) {
+            SetPedDefaultComponentVariation(ped);
+        }
+        shared_1.loggers.spawn.debug('Player model set', { model, modelHash });
+    }
+    async ensurePed() {
+        const start = GetGameTimer();
+        let ped = PlayerPedId();
+        while (ped === 0) {
+            if (GetGameTimer() - start > PED_TIMEOUT_MS) {
+                shared_1.loggers.spawn.error('PlayerPedId() did not become valid in time');
+                throw new Error('PED_TIMEOUT');
+            }
+            await delay(0);
+            ped = PlayerPedId();
+        }
+        return ped;
+    }
+    async ensureCollisionAt(position, ped) {
+        RequestCollisionAtCoord(position.x, position.y, position.z);
+        const start = GetGameTimer();
+        while (!HasCollisionLoadedAroundEntity(ped)) {
+            if (GetGameTimer() - start > COLLISION_TIMEOUT_MS) {
+                shared_1.loggers.spawn.warn('Collision did not fully load around entity in time', {
+                    x: position.x,
+                    y: position.y,
+                    z: position.z,
+                });
+                break;
+            }
+            await delay(0);
+        }
+    }
+    async setupPedForGameplay(ped) {
+        SetEntityAsMissionEntity(ped, true, true);
+        ClearPedTasksImmediately(ped);
+        RemoveAllPedWeapons(ped, true);
+        ResetEntityAlpha(ped);
+        await delay(0);
+        SetEntityAlpha(ped, 255, false);
+        SetEntityVisible(ped, true, false);
+        SetEntityCollision(ped, true, true);
+        SetEntityInvincible(ped, false);
+        shared_1.loggers.spawn.debug('Ped prepared for gameplay', { ped });
+    }
+    async placePed(ped, position, heading) {
+        FreezeEntityPosition(ped, true);
+        SetEntityCoordsNoOffset(ped, position.x, position.y, position.z, false, false, false);
+        SetEntityHeading(ped, heading);
+        await delay(0);
+        FreezeEntityPosition(ped, false);
+    }
+    async applyAppearanceIfNeeded(ped, appearance) {
+        if (!appearance) {
+            SetPedDefaultComponentVariation(ped);
+            return;
+        }
+        if (!this.appearanceService.validateAppearance(appearance)) {
+            SetPedDefaultComponentVariation(ped);
+            return;
+        }
+        try {
+            await this.appearanceService.applyAppearance(ped, appearance);
+        }
+        catch (error) {
+            shared_1.loggers.spawn.error('Failed to apply appearance, using default variation', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            SetPedDefaultComponentVariation(ped);
+        }
+    }
+};
+exports.SpawnService = SpawnService;
+exports.SpawnService = SpawnService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [appearance_service_1.AppearanceService])
+], SpawnService);

package/dist/client/services/{ui/textui.service.d.ts → textui.service.d.ts}

@@ -1,4 +1,4 @@
-import type { Vector3 } from '../../../utils';
+import type { Vector3 } from '../../utils';
 export interface TextUIOptions {
     /** Font (0-8) */
     font?: number;

package/dist/client/services/{world/vehicle.service.d.ts → vehicle.service.d.ts}

@@ -1,4 +1,4 @@
-import type { Vector3 } from '../../../utils';
+import type { Vector3 } from '../../utils';
 export interface VehicleSpawnOptions {
     /** Model name or hash */
     model: string;

package/dist/client/system/processors/export.processor.js

@@ -18,7 +18,7 @@ let ClientExportProcessor = class ClientExportProcessor {
     process(target, methodName, metadata) {
         const handler = target[methodName].bind(target);
         const handlerName = `${target.constructor.name}.${methodName}`;
-        exports(metadata.exportName, async (...args) => {
+        globalThis.exports(metadata.exportName, async (...args) => {
             try {
                 return await handler(...args);
             }

package/dist/index.d.ts

@@ -3,5 +3,3 @@ export * as Utils from './utils';
 export * as Shared from './shared';
 export * as Server from './server';
 export * as Client from './client';
-export { LoggerService, LogLevel, LogDomain } from './shared/logger';
-export type { LogTransport, LogContext, LogEntry, LoggerConfig } from './shared/logger';

package/dist/index.js

@@ -33,14 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogDomain = exports.LogLevel = exports.LoggerService = exports.Client = exports.Server = exports.Shared = exports.Utils = void 0;
+exports.Client = exports.Server = exports.Shared = exports.Utils = void 0;
 require("reflect-metadata");
 exports.Utils = __importStar(require("./utils"));
 exports.Shared = __importStar(require("./shared"));
 exports.Server = __importStar(require("./server"));
 exports.Client = __importStar(require("./client"));
-// Re-export logger at root level for convenience
-var logger_1 = require("./shared/logger");
-Object.defineProperty(exports, "LoggerService", { enumerable: true, get: function () { return logger_1.LoggerService; } });
-Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return logger_1.LogLevel; } });
-Object.defineProperty(exports, "LogDomain", { enumerable: true, get: function () { return logger_1.LogDomain; } });

package/dist/server/bootstrap.js

@@ -7,9 +7,9 @@ const templates_1 = require("./templates");
 const metadata_scanner_1 = require("../system/metadata.scanner");
 const processors_register_1 = require("./system/processors.register");
 const registers_1 = require("./services/registers");
-const decorators_1 = require("./decorators");
 const logger_1 = require("../shared/logger");
 const auth_provider_contract_1 = require("./templates/auth/auth-provider.contract");
+const controller_1 = require("./decorators/controller");
 const check = () => {
     if (!container_1.di.isRegistered(templates_1.PrincipalProviderContract)) {
         const errorMsg = 'No Principal Provider configured. ' +
@@ -52,6 +52,6 @@ async function initServer() {
     (0, playerSession_loader_1.playerSessionLoader)();
     logger_1.loggers.bootstrap.debug('Player session loader active');
     const scanner = container_1.di.resolve(metadata_scanner_1.MetadataScanner);
-    scanner.scan(decorators_1.serverControllerRegistry);
+    scanner.scan(controller_1.serverControllerRegistry);
     logger_1.loggers.bootstrap.info('OpenCore Server initialized successfully');
 }

package/dist/server/controllers/command.controller.d.ts

@@ -3,5 +3,5 @@ import { Player } from '../entities';
 export declare class CommandNetworkController {
     private readonly commandService;
     constructor(commandService: CommandService);
-    onCommandReceived(player: Player, commandName: string, args: string[], raw: string): Promise<void>;
+    onCommandReceived(player: Player, command: string, args: string[], raw: string): Promise<void>;
 }

package/dist/server/controllers/command.controller.js

@@ -10,7 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommandNetworkController = void 0;
-const netEvent_1 = require("../decorators/netEvent");
+const onNet_1 = require("../decorators/onNet");
 const command_service_1 = require("../services/command.service");
 const entities_1 = require("../entities");
 const decorators_1 = require("../decorators");
@@ -19,16 +19,16 @@ let CommandNetworkController = class CommandNetworkController {
     constructor(commandService) {
         this.commandService = commandService;
     }
-    async onCommandReceived(player, commandName, args, raw) {
+    async onCommandReceived(player, command, args, raw) {
         try {
-            logger_1.loggers.command.trace(`Received: /${commandName}`, {
+            logger_1.loggers.command.trace(`Received: /${command}`, {
                 playerId: player.clientID,
                 playerName: player.name,
             });
-            await this.commandService.execute(player, commandName, args, raw);
+            await this.commandService.execute(player, command, args, raw);
         }
         catch (error) {
-            logger_1.loggers.command.error(`Execution failed: /${commandName}`, {
+            logger_1.loggers.command.error(`Execution failed: /${command}`, {
                 playerId: player.clientID,
             }, error);
         }
@@ -36,7 +36,7 @@ let CommandNetworkController = class CommandNetworkController {
 };
 exports.CommandNetworkController = CommandNetworkController;
 __decorate([
-    (0, netEvent_1.OnNet)('core:internal:executeCommand'),
+    (0, onNet_1.OnNet)('core:internal:executeCommand'),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [entities_1.Player, String, Array, String]),
     __metadata("design:returntype", Promise)

package/dist/server/controllers/session.controller.d.ts

@@ -0,0 +1,9 @@
+import { PlayerService } from '../services';
+import { PlayerPersistenceService } from '../services/persistence.service';
+export declare class SessionController {
+    private readonly playerManager;
+    private readonly persistance;
+    constructor(playerManager: PlayerService, persistance: PlayerPersistenceService);
+    onPlayerJoining(): Promise<void>;
+    onPlayerDropped(): Promise<void>;
+}

package/dist/server/controllers/session.controller.js

@@ -0,0 +1,70 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionController = void 0;
+const shared_1 = require("../../shared");
+const core_event_bus_1 = require("../bus/core-event-bus");
+const decorators_1 = require("../decorators");
+const onFiveMEvent_1 = require("../decorators/onFiveMEvent");
+const services_1 = require("../services");
+const persistence_service_1 = require("../services/persistence.service");
+let SessionController = class SessionController {
+    constructor(playerManager, persistance) {
+        this.playerManager = playerManager;
+        this.persistance = persistance;
+    }
+    async onPlayerJoining() {
+        var _a;
+        const clientId = source;
+        const license = (_a = GetPlayerIdentifier(clientId.toString(), 0)) !== null && _a !== void 0 ? _a : undefined;
+        const player = this.playerManager.bind(clientId, { license });
+        shared_1.loggers.session.info(`Player session created`, {
+            clientId,
+            license: license !== null && license !== void 0 ? license : 'none',
+        });
+        await this.persistance.handleSessionLoad(player);
+        (0, core_event_bus_1.emitCoreEvent)('core:playerSessionCreated', { clientId, license });
+        setImmediate(() => {
+            const currentPlayer = this.playerManager.getByClient(clientId);
+            if (!currentPlayer)
+                return;
+            (0, core_event_bus_1.emitCoreEvent)('core:playerFullyConnected', { clientId, license });
+        });
+    }
+    async onPlayerDropped() {
+        const clientId = Number(source);
+        const player = this.playerManager.getByClient(clientId);
+        if (player) {
+            await this.persistance.handleSessionSave(player);
+        }
+        this.playerManager.unbindByClient(clientId);
+        (0, core_event_bus_1.emitCoreEvent)('core:playerSessionDestroyed', { clientId });
+        shared_1.loggers.session.info(`Player session destroyed`, { clientId });
+    }
+};
+exports.SessionController = SessionController;
+__decorate([
+    (0, onFiveMEvent_1.OnFiveMEvent)('playerJoining'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "onPlayerJoining", null);
+__decorate([
+    (0, onFiveMEvent_1.OnFiveMEvent)('playerDropped'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "onPlayerDropped", null);
+exports.SessionController = SessionController = __decorate([
+    (0, decorators_1.Controller)(),
+    __metadata("design:paramtypes", [services_1.PlayerService,
+        persistence_service_1.PlayerPersistenceService])
+], SessionController);

package/dist/server/database/adapters/oxmysql.adapter.js

@@ -15,7 +15,7 @@ const database_contract_1 = require("../database.contract");
  * Get the oxmysql export from FiveM
  */
 function getOxMySQL() {
-    const ox = global.exports['oxmysql'];
+    const ox = exports['oxmysql'];
     if (!ox) {
         throw new Error('[OpenCore] oxmysql is not available. Make sure oxmysql resource is started before your resource.');
     }

package/dist/server/decorators/command.d.ts

@@ -1,19 +1,49 @@
 import type { ClassConstructor } from '../../system/class-constructor';
 import type z from 'zod';
+import type { Player } from '../entities/player';
 export interface CommandConfig {
-    name: string;
+    /**
+     * The command name (e.g. "revive", "deposit"), used in chat "/revive"
+     */
+    command: string;
+    /**
+     * The command description, maybe "/help revive"
+     */
     description?: string;
+    /**
+     * The command usage, maybe "/revive <player>"
+     */
     usage?: string;
+    /**
+     * The command schema, used to validate the arguments, validated with zod
+     * @example
+     * ```ts
+     * Server.Command({
+     *   command: 'revive',
+     *   schema: z.object({
+     *     player: z.string(),
+     *   }),
+     * })
+     * ```
+     */
     schema?: z.ZodType;
 }
 export interface CommandMetadata extends CommandConfig {
     methodName: string;
     target: ClassConstructor;
+    paramTypes?: any;
 }
+type ServerCommandHandler = (player: Player, ...args: any[]) => any;
 /**
  * Decorator used to mark a controller method as a command.
- * The metadata is collected and later bound to FiveM via RegisterCommand().
+ * This method will be registered and then executed by the command service.
+ * It will depend on the chat you have implemented following the dependency conventions.
  *
- * @param name - The command name (e.g. "revive", "deposit")
+ * @param configOrName - The command name (e.g. "revive", "deposit")
+ * @validation zod schema
+ * @handlerSignature ```ts
+ *  (player: Server.Player, args: any[]) => any
+ * ```
  */
-export declare function Command(configOrName: string | CommandConfig): (target: any, propertyKey: string) => void;
+export declare function Command(configOrName: string | CommandConfig): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export {};

package/dist/server/decorators/command.js

@@ -4,15 +4,20 @@ exports.Command = Command;
 const metadata_server_keys_1 = require("../system/metadata-server.keys");
 /**
  * Decorator used to mark a controller method as a command.
- * The metadata is collected and later bound to FiveM via RegisterCommand().
+ * This method will be registered and then executed by the command service.
+ * It will depend on the chat you have implemented following the dependency conventions.
  *
- * @param name - The command name (e.g. "revive", "deposit")
+ * @param configOrName - The command name (e.g. "revive", "deposit")
+ * @validation zod schema
+ * @handlerSignature ```ts
+ *  (player: Server.Player, args: any[]) => any
+ * ```
  */
 function Command(configOrName) {
-    return (target, propertyKey) => {
-        // Normalizamos: si pasa solo un string, creamos el objeto config
-        const config = typeof configOrName === 'string' ? { name: configOrName } : configOrName;
-        const metadata = Object.assign(Object.assign({}, config), { methodName: propertyKey, target: target.constructor });
+    return (target, propertyKey, descriptor) => {
+        const config = typeof configOrName === 'string' ? { command: configOrName } : configOrName;
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+        const metadata = Object.assign(Object.assign({}, config), { methodName: propertyKey, target: target.constructor, paramTypes });
         Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.COMMAND, metadata, target, propertyKey);
     };
 }

package/dist/server/decorators/controller.d.ts

@@ -1,3 +1,25 @@
 import type { ClassConstructor } from '../../system/class-constructor';
 export declare const serverControllerRegistry: ClassConstructor[];
+/**
+ * Class decorator used to mark a class as a Server Controller.
+ *
+ * This decorator performs the following actions:
+ * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
+ * 2. Defines metadata identifying the class as a 'server' type controller.
+ * 3. Automatically adds the class constructor to the `serverControllerRegistry`.
+ *
+ * @returns The decorator function to apply to the class.
+ *
+ * @example
+ * ```ts
+ * import { Controller } from '@core/server/decorators'
+ *
+ * @Server.Controller()
+ * export class PlayerController {
+ *   constructor(private playerService: PlayerService) {
+ *     // Dependency injection works automatically here
+ *   }
+ * }
+ * ```
+ */
 export declare function Controller(): (target: ClassConstructor) => void;

package/dist/server/decorators/controller.js

@@ -5,6 +5,28 @@ exports.Controller = Controller;
 const tsyringe_1 = require("tsyringe");
 const metadata_server_keys_1 = require("../system/metadata-server.keys");
 exports.serverControllerRegistry = [];
+/**
+ * Class decorator used to mark a class as a Server Controller.
+ *
+ * This decorator performs the following actions:
+ * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
+ * 2. Defines metadata identifying the class as a 'server' type controller.
+ * 3. Automatically adds the class constructor to the `serverControllerRegistry`.
+ *
+ * @returns The decorator function to apply to the class.
+ *
+ * @example
+ * ```ts
+ * import { Controller } from '@core/server/decorators'
+ *
+ * @Server.Controller()
+ * export class PlayerController {
+ *   constructor(private playerService: PlayerService) {
+ *     // Dependency injection works automatically here
+ *   }
+ * }
+ * ```
+ */
 function Controller() {
     return function (target) {
         (0, tsyringe_1.injectable)()(target);

package/dist/server/decorators/export.d.ts

@@ -1 +1,39 @@
+/**
+ * Export
+ * -----------------------------------------
+ * Declares a method as an externally accessible export
+ * within the FiveM environment.
+ *
+ * Methods decorated with `@Export()` are automatically
+ * registered by the framework and exposed as native
+ * FXServer exports, allowing other resources to call them
+ * using:
+ *
+ *   exports.resourceName.exportName(...)
+ *
+ * This decorator is typically used inside controller
+ * classes, where the framework’s module loader inspects
+ * metadata to register commands, events and exports
+ * consistently.
+ *
+ * @param name Optional name to expose. If omitted,
+ *             the method name is used.
+ *
+ * ```ts
+ * @Server.Controller()
+ * export class AccountController {
+ *   @Server.Export('getAccountById')
+ *   getAccount(id: string) {
+ *     return this.accountService.find(id)
+ *   }
+ * }
+ *
+ * // From another resource:
+ * // const result = exports['core-resource'].getAccountById('1234')
+ *```
+ * Internally, this decorator stores metadata used by
+ * the server bootstrap to automatically register the
+ * export through FXServer's `global.exports` API.
+ *
+ */
 export declare function Export(name?: string): (target: any, propertyKey: string) => void;