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

package/dist/runtime/server/implementations/local/channel.local.js

@@ -0,0 +1,185 @@
+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 { EventsAPI } from '../../../../adapters/contracts/transport/events.api';
+import { inject, injectable } from 'tsyringe';
+import { Channels } from '../../ports/channel.api-port';
+import { ChannelType } from '../../types';
+import { Players } from '../../ports/players.api-port';
+import { Channel } from '../../concepts/channel';
+let LocalChannelImplementation = class LocalChannelImplementation extends Channels {
+    playerDirectory;
+    events;
+    channels = new Map();
+    validator;
+    constructor(playerDirectory, events) {
+        super();
+        this.playerDirectory = playerDirectory;
+        this.events = events;
+    }
+    setValidator(validator) {
+        this.validator = validator;
+    }
+    create(id, metadata, maxSubscribers) {
+        if (this.channels.has(id)) {
+            throw new Error(`Channel with id '${id}' already exists`);
+        }
+        const channel = new Channel(id, metadata, maxSubscribers);
+        this.channels.set(id, channel);
+        return channel;
+    }
+    createPrivate(players, metadata) {
+        const id = `private:${Date.now()}:${Math.random().toString(36).substring(7)}`;
+        const channel = this.create(id, { ...metadata, persistent: false }, players.length);
+        for (const player of players) {
+            channel.subscribe(player);
+        }
+        return channel;
+    }
+    get(id) {
+        return this.channels.get(id);
+    }
+    delete(id) {
+        const channel = this.channels.get(id);
+        if (!channel) {
+            return false;
+        }
+        channel.clear();
+        return this.channels.delete(id);
+    }
+    exists(id) {
+        return this.channels.has(id);
+    }
+    subscribe(channelId, player, metadata) {
+        const channel = this.channels.get(channelId);
+        if (!channel) {
+            throw new Error(`Channel '${channelId}' does not exist`);
+        }
+        if (this.validator && !this.validator.canSubscribe(player, channelId)) {
+            return false;
+        }
+        return channel.subscribe(player, metadata);
+    }
+    unsubscribe(channelId, player) {
+        const channel = this.channels.get(channelId);
+        if (!channel) {
+            return false;
+        }
+        return channel.unsubscribe(player);
+    }
+    isSubscribed(channelId, player) {
+        const channel = this.channels.get(channelId);
+        if (!channel) {
+            return false;
+        }
+        return channel.isSubscribed(player);
+    }
+    broadcast(channelId, sender, message, author, color = { r: 255, g: 255, b: 255 }) {
+        const channel = this.channels.get(channelId);
+        if (!channel) {
+            throw new Error(`Channel '${channelId}' does not exist`);
+        }
+        if (this.validator && !this.validator.canBroadcast(sender, channelId)) {
+            return;
+        }
+        const subscribers = channel.getSubscribers();
+        const targetIds = subscribers.map((p) => p.clientID);
+        if (targetIds.length === 0) {
+            return;
+        }
+        this.events.emit('core:chat:addMessage', targetIds, {
+            args: [author ?? sender.name, message],
+            color: color,
+        });
+    }
+    broadcastSystem(channelId, message, author = 'SYSTEM', color = { r: 0, g: 191, b: 255 }) {
+        const channel = this.channels.get(channelId);
+        if (!channel) {
+            throw new Error(`Channel '${channelId}' does not exist`);
+        }
+        const subscribers = channel.getSubscribers();
+        const targetIds = subscribers.map((p) => p.clientID);
+        if (targetIds.length === 0) {
+            return;
+        }
+        this.events.emit('core:chat:addMessage', targetIds, {
+            args: [author, message],
+            color: color,
+        });
+    }
+    getSubscribers(channelId) {
+        const channel = this.channels.get(channelId);
+        if (!channel) {
+            return [];
+        }
+        return channel.getSubscribers();
+    }
+    getChannelsByType(type) {
+        return Array.from(this.channels.values()).filter((channel) => channel.type === type);
+    }
+    getChannelsByPlayer(player) {
+        return Array.from(this.channels.values()).filter((channel) => channel.isSubscribed(player));
+    }
+    getAllChannels() {
+        return Array.from(this.channels.values());
+    }
+    clear() {
+        for (const channel of this.channels.values()) {
+            if (!channel.isPersistent) {
+                channel.clear();
+            }
+        }
+        this.channels.clear();
+    }
+    clearNonPersistent() {
+        for (const [id, channel] of this.channels.entries()) {
+            if (!channel.isPersistent) {
+                channel.clear();
+                this.channels.delete(id);
+            }
+        }
+    }
+    createProximityChannel(originPlayer, radius, channelId) {
+        const id = channelId ?? `proximity:${originPlayer.clientID}:${Date.now()}`;
+        const originPos = originPlayer.getPosition();
+        if (!originPos) {
+            return undefined;
+        }
+        const channel = this.create(id, {
+            type: ChannelType.PROXIMITY,
+            maxRange: radius,
+            persistent: false,
+        }, undefined);
+        const allPlayers = this.playerDirectory.getAll();
+        const nearbyPlayers = allPlayers.filter((p) => {
+            const pos = p.getPosition();
+            if (!pos)
+                return false;
+            const dx = originPos.x - pos.x;
+            const dy = originPos.y - pos.y;
+            const dz = originPos.z - pos.z;
+            const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            return distance <= radius;
+        });
+        for (const player of nearbyPlayers) {
+            channel.subscribe(player);
+        }
+        return channel;
+    }
+};
+LocalChannelImplementation = __decorate([
+    injectable(),
+    __param(1, inject(EventsAPI)),
+    __metadata("design:paramtypes", [Players,
+        EventsAPI])
+], LocalChannelImplementation);
+export { LocalChannelImplementation };

package/dist/runtime/server/implementations/local/command.local.d.ts

@@ -0,0 +1,57 @@
+import { CommandMetadata } from '../../decorators/command';
+import { Player } from '../../entities';
+import { CommandExecutionPort, type CommandInfo } from '../../ports/internal/command-execution.port';
+/**
+ * Local command execution service (CORE/STANDALONE modes).
+ *
+ * @remarks
+ * Maintains an in-memory registry of command handlers and executes them with full validation.
+ * Controllers declare commands via @Command decorator. During bootstrap, the framework
+ * scans and registers handlers via CommandProcessor.
+ *
+ * Execution pipeline:
+ * - Enforces authentication (secure by default unless marked @Public)
+ * - Validates arguments using Zod schemas (explicit or auto-generated)
+ * - Coerces argument types before invoking handlers
+ */
+export declare class LocalCommandImplementation extends CommandExecutionPort {
+    private commands;
+    /**
+     * Returns decorator metadata for a registered command.
+     *
+     * @remarks
+     * Mainly used by controllers to enrich error observation (usage/description/etc.).
+     */
+    getCommandMeta(commandName: string): CommandMetadata | undefined;
+    /**
+     * Registers a command handler.
+     *
+     * @param meta - Command metadata collected from the {@link Command} decorator.
+     * @param handler - The bound method to invoke.
+     */
+    register(meta: CommandMetadata, handler: (...args: any[]) => any): void;
+    /**
+     * Executes a registered command.
+     *
+     * @remarks
+     * **Security**: Commands require authentication by default unless marked with @Public().
+     * Unauthenticated attempts are blocked by throwing an {@link AppError}.
+     * Higher-level controllers can observe the failure and decide how to notify the player.
+     *
+     * Argument parsing behavior depends on the schema:
+     * - Zod object schema: maps raw args to parameter names.
+     * - Zod tuple schema: validates positional args.
+     * - No schema: attempts to generate a schema from parameter types.
+     *
+     * @param player - Player invoking the command.
+     * @param commandName - Command name (without the leading `/`).
+     * @param args - Raw argument list (strings).
+     *
+     * @throws AppError - If the command does not exist, the schema mismatches parameters, or validation fails.
+     */
+    execute(player: Player, commandName: string, args: string[]): Promise<any>;
+    /**
+     * Returns a list of all registered commands.
+     */
+    getAllCommands(): CommandInfo[];
+}

package/dist/runtime/server/implementations/local/command.local.js

@@ -0,0 +1,110 @@
+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;
+};
+import { injectable } from 'tsyringe';
+import { AppError } from '../../../../kernel/error/app.error';
+import { loggers } from '../../../../kernel/logger';
+import { validateAndExecuteCommand } from '../../helpers/command-validation.helper';
+import { CommandExecutionPort } from '../../ports/internal/command-execution.port';
+/**
+ * Local command execution service (CORE/STANDALONE modes).
+ *
+ * @remarks
+ * Maintains an in-memory registry of command handlers and executes them with full validation.
+ * Controllers declare commands via @Command decorator. During bootstrap, the framework
+ * scans and registers handlers via CommandProcessor.
+ *
+ * Execution pipeline:
+ * - Enforces authentication (secure by default unless marked @Public)
+ * - Validates arguments using Zod schemas (explicit or auto-generated)
+ * - Coerces argument types before invoking handlers
+ */
+let LocalCommandImplementation = class LocalCommandImplementation extends CommandExecutionPort {
+    commands = new Map();
+    /**
+     * Returns decorator metadata for a registered command.
+     *
+     * @remarks
+     * Mainly used by controllers to enrich error observation (usage/description/etc.).
+     */
+    getCommandMeta(commandName) {
+        return this.commands.get(commandName.toLowerCase())?.meta;
+    }
+    /**
+     * Registers a command handler.
+     *
+     * @param meta - Command metadata collected from the {@link Command} decorator.
+     * @param handler - The bound method to invoke.
+     */
+    register(meta, handler) {
+        if (this.commands.has(meta.command.toLowerCase())) {
+            loggers.command.error(`Command '${meta.command}' is already registered. Skipped`, {
+                command: meta.command,
+            });
+        }
+        this.commands.set(meta.command.toLowerCase(), {
+            meta,
+            handler,
+            isPublic: meta.isPublic ?? false,
+        });
+        const publicFlag = meta.isPublic ? ' [Public]' : '';
+        const schemaFlag = meta.schema ? ' [Validated]' : '';
+        loggers.command.debug(`Registered: /${meta.command}${publicFlag}${schemaFlag}`);
+    }
+    /**
+     * Executes a registered command.
+     *
+     * @remarks
+     * **Security**: Commands require authentication by default unless marked with @Public().
+     * Unauthenticated attempts are blocked by throwing an {@link AppError}.
+     * Higher-level controllers can observe the failure and decide how to notify the player.
+     *
+     * Argument parsing behavior depends on the schema:
+     * - Zod object schema: maps raw args to parameter names.
+     * - Zod tuple schema: validates positional args.
+     * - No schema: attempts to generate a schema from parameter types.
+     *
+     * @param player - Player invoking the command.
+     * @param commandName - Command name (without the leading `/`).
+     * @param args - Raw argument list (strings).
+     *
+     * @throws AppError - If the command does not exist, the schema mismatches parameters, or validation fails.
+     */
+    async execute(player, commandName, args) {
+        const entry = this.commands.get(commandName.toLowerCase());
+        if (!entry)
+            throw new AppError('COMMAND:NOT_FOUND', `Command not found: ${commandName}`, 'client');
+        const { meta, handler, isPublic } = entry;
+        // ═══════════════════════════════════════════════════════════════
+        // SECURE BY DEFAULT: Require authentication unless @Public()
+        // ═══════════════════════════════════════════════════════════════
+        if (!isPublic) {
+            if (!player.accountID) {
+                loggers.security.warn(`Unauthenticated command attempt blocked`, {
+                    command: commandName,
+                    clientId: player.clientID,
+                });
+                throw new AppError('AUTH:UNAUTHORIZED', 'You must be authenticated to use this command', 'client');
+            }
+        }
+        return await validateAndExecuteCommand(meta, player, args, handler);
+    }
+    /**
+     * Returns a list of all registered commands.
+     */
+    getAllCommands() {
+        return Array.from(this.commands.values()).map((c) => ({
+            command: c.meta.command,
+            description: c.meta.description ?? '',
+            usage: c.meta.usage ?? '',
+            isPublic: c.isPublic,
+        }));
+    }
+};
+LocalCommandImplementation = __decorate([
+    injectable()
+], LocalCommandImplementation);
+export { LocalCommandImplementation };

package/dist/runtime/server/implementations/local/player.local.d.ts

@@ -0,0 +1,114 @@
+import { IPlayerInfo } from '../../../../adapters';
+import { IPlatformContext } from '../../../../adapters/contracts/IPlatformContext';
+import { EventsAPI } from '../../../../adapters/contracts/transport/events.api';
+import { IEntityServer } from '../../../../adapters/contracts/server/IEntityServer';
+import { IPlayerLifecycleServer } from '../../../../adapters/contracts/server/player-lifecycle/IPlayerLifecycleServer';
+import { IPlayerStateSyncServer } from '../../../../adapters/contracts/server/player-state/IPlayerStateSyncServer';
+import { IPlayerServer } from '../../../../adapters/contracts/server/IPlayerServer';
+import { WorldContext } from '../../../core/world';
+import { Player } from '../../entities';
+import { Players } from '../../ports/players.api-port';
+import { PlayerSessionLifecyclePort } from '../../ports/internal/player-session-lifecycle.port';
+import { PlayerSession } from '../../types/player-session.types';
+import { LinkedID } from '../../services';
+/**
+ * Service responsible for managing the lifecycle of player sessions.
+ * It acts as the central registry for all connected players, mapping FiveM client IDs
+ * to Core `Player` entities.
+ *
+ * @remarks
+ * This service is used as a singleton in the dependency container.
+ * It exposes the operations defined by {@link Players} and {@link PlayerSessionLifecyclePort}.
+ */
+export declare class LocalPlayerImplementation implements Players, PlayerSessionLifecyclePort {
+    private readonly world;
+    private readonly playerInfo;
+    private readonly playerServer;
+    private readonly playerLifecycle;
+    private readonly playerStateSync;
+    private readonly entityServer;
+    private readonly events;
+    private readonly platformContext;
+    private readonly playerAdapters;
+    constructor(world: WorldContext, playerInfo: IPlayerInfo, playerServer: IPlayerServer, playerLifecycle: IPlayerLifecycleServer, playerStateSync: IPlayerStateSyncServer, entityServer: IEntityServer, events: EventsAPI<'server'>, platformContext: IPlatformContext);
+    private isPlayer;
+    /**
+     * Initializes a new player session for a connecting client.
+     *
+     * This method is typically called during the `playerJoining` event or
+     * immediately after a successful handshake/login flow.
+     *
+     * @param clientID - The FiveM server ID (source) of the player.
+     * @param identifiers - Optional object containing platform identifiers (license, steam, etc.).
+     * @returns The newly created `Player` instance.
+     */
+    bind(clientID: number, identifiers?: PlayerSession['identifiers']): Player;
+    /**
+     * Terminates a player session and removes them from the registry.
+     *
+     * This should be called when the `playerDropped` event is triggered to ensure
+     * memory is freed and the session is closed.
+     *
+     * @param clientID - The FiveM server ID of the player disconnecting.
+     */
+    unbind(clientID: number): void;
+    /**
+     * Retrieves the `Player` entity associated with a specific FiveM client ID.
+     *
+     * @param clientID - The FiveM server ID to look up.
+     * @returns The `Player` instance if found, or `null` if the session does not exist.
+     */
+    getByClient(clientID: number): Player | undefined;
+    getMany(clientIds: number[]): Player[];
+    /**
+     * Returns a list of all currently active `Player` entities.
+     *
+     * @returns An array containing all connected players managed by this service.
+     */
+    getAll(): Player[];
+    /**
+     * Helper to retrieve the authenticated Account ID for a given client.
+     *
+     * @param clientID - The FiveM server ID to look up.
+     * @returns The bound Account ID (string/UUID) if the player is logged in, or `null` otherwise.
+     */
+    getAccountLinked(clientID: number): LinkedID | undefined;
+    /**
+     * Stores arbitrary metadata in the player's session.
+     * Useful for storing transient state like 'isDead', 'job', 'dimension', etc.
+     *
+     * @param clientID - The FiveM server ID of the player.
+     * @param key - The unique key for the metadata entry.
+     * @param value - The value to store.
+     */
+    setMeta(clientID: number, key: string, value: unknown): void;
+    /**
+     * Retrieves metadata previously stored in the player's session.
+     *
+     * @template T - The expected type of the returned value.
+     * @param clientID - The FiveM server ID of the player.
+     * @param key - The metadata key to retrieve.
+     * @returns The value cast to type `T`, or `undefined` if the key or player doesn't exist.
+     */
+    getMeta<T = unknown>(clientID: number, key: string): Promise<T | undefined>;
+    /**
+     * Retrieves a Player by their persistent account ID.
+     *
+     * @param accountId - The unique account identifier to search for.
+     * @returns The Player if found, or `undefined` if not online.
+     */
+    getByAccountId(accountId: string): Player | undefined;
+    /**
+     * Returns the current number of connected players.
+     *
+     * @returns Player count.
+     */
+    getPlayerCount(): number;
+    /**
+     * Checks if a player with the given account ID is currently online.
+     *
+     * @param accountId - The account identifier to check.
+     * @returns `true` if online, `false` otherwise.
+     */
+    isOnline(accountId: string): boolean;
+}

package/dist/runtime/server/implementations/local/player.local.js

@@ -0,0 +1,216 @@
+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 { IPlayerInfo } from '../../../../adapters';
+import { IPlatformContext } from '../../../../adapters/contracts/IPlatformContext';
+import { EventsAPI } from '../../../../adapters/contracts/transport/events.api';
+import { IEntityServer } from '../../../../adapters/contracts/server/IEntityServer';
+import { IPlayerLifecycleServer } from '../../../../adapters/contracts/server/player-lifecycle/IPlayerLifecycleServer';
+import { IPlayerStateSyncServer } from '../../../../adapters/contracts/server/player-state/IPlayerStateSyncServer';
+import { IPlayerServer } from '../../../../adapters/contracts/server/IPlayerServer';
+import { loggers } from '../../../../kernel/logger';
+import { WorldContext } from '../../../core/world';
+import { createLocalServerPlayer } from '../../adapter/registry';
+/**
+ * Service responsible for managing the lifecycle of player sessions.
+ * It acts as the central registry for all connected players, mapping FiveM client IDs
+ * to Core `Player` entities.
+ *
+ * @remarks
+ * This service is used as a singleton in the dependency container.
+ * It exposes the operations defined by {@link Players} and {@link PlayerSessionLifecyclePort}.
+ */
+let LocalPlayerImplementation = class LocalPlayerImplementation {
+    world;
+    playerInfo;
+    playerServer;
+    playerLifecycle;
+    playerStateSync;
+    entityServer;
+    events;
+    platformContext;
+    playerAdapters;
+    constructor(world, playerInfo, playerServer, playerLifecycle, playerStateSync, entityServer, events, platformContext) {
+        this.world = world;
+        this.playerInfo = playerInfo;
+        this.playerServer = playerServer;
+        this.playerLifecycle = playerLifecycle;
+        this.playerStateSync = playerStateSync;
+        this.entityServer = entityServer;
+        this.events = events;
+        this.platformContext = platformContext;
+        const defaultSpawnModel = this.platformContext.defaultSpawnModel;
+        this.playerAdapters = {
+            playerInfo: this.playerInfo,
+            playerServer: this.playerServer,
+            playerLifecycle: this.playerLifecycle,
+            playerStateSync: this.playerStateSync,
+            entityServer: this.entityServer,
+            events: this.events,
+            defaultSpawnModel,
+        };
+    }
+    isPlayer(e) {
+        return e.id.startsWith('player:');
+    }
+    /**
+     * Initializes a new player session for a connecting client.
+     *
+     * This method is typically called during the `playerJoining` event or
+     * immediately after a successful handshake/login flow.
+     *
+     * @param clientID - The FiveM server ID (source) of the player.
+     * @param identifiers - Optional object containing platform identifiers (license, steam, etc.).
+     * @returns The newly created `Player` instance.
+     */
+    bind(clientID, identifiers) {
+        const session = {
+            clientID,
+            identifiers,
+            meta: {},
+        };
+        const player = createLocalServerPlayer(session, this.playerAdapters);
+        this.world.add(player);
+        loggers.session.debug('Player session bound', {
+            clientID,
+            totalPlayers: this.world.sizeBy('player'),
+        });
+        return player;
+    }
+    /**
+     * Terminates a player session and removes them from the registry.
+     *
+     * This should be called when the `playerDropped` event is triggered to ensure
+     * memory is freed and the session is closed.
+     *
+     * @param clientID - The FiveM server ID of the player disconnecting.
+     */
+    unbind(clientID) {
+        const player = this.getByClient(clientID);
+        if (player)
+            this.world.remove(player.id);
+        loggers.session.debug('Player session unbound', {
+            clientID,
+            totalPlayers: this.world.sizeBy('player'),
+        });
+    }
+    /**
+     * Retrieves the `Player` entity associated with a specific FiveM client ID.
+     *
+     * @param clientID - The FiveM server ID to look up.
+     * @returns The `Player` instance if found, or `null` if the session does not exist.
+     */
+    getByClient(clientID) {
+        return this.world.get(`player:${clientID}`);
+    }
+    getMany(clientIds) {
+        const result = [];
+        for (const id of clientIds) {
+            const p = this.getByClient(id);
+            if (p)
+                result.push(p);
+        }
+        return result;
+    }
+    /**
+     * Returns a list of all currently active `Player` entities.
+     *
+     * @returns An array containing all connected players managed by this service.
+     */
+    getAll() {
+        return this.world.find(this.isPlayer);
+    }
+    /**
+     * Helper to retrieve the authenticated Account ID for a given client.
+     *
+     * @param clientID - The FiveM server ID to look up.
+     * @returns The bound Account ID (string/UUID) if the player is logged in, or `null` otherwise.
+     */
+    getAccountLinked(clientID) {
+        return this.getByClient(clientID)?.accountID;
+    }
+    /**
+     * Stores arbitrary metadata in the player's session.
+     * Useful for storing transient state like 'isDead', 'job', 'dimension', etc.
+     *
+     * @param clientID - The FiveM server ID of the player.
+     * @param key - The unique key for the metadata entry.
+     * @param value - The value to store.
+     */
+    setMeta(clientID, key, value) {
+        const player = this.getByClient(clientID);
+        if (!player)
+            return;
+        player.setMeta(key, value);
+    }
+    /**
+     * Retrieves metadata previously stored in the player's session.
+     *
+     * @template T - The expected type of the returned value.
+     * @param clientID - The FiveM server ID of the player.
+     * @param key - The metadata key to retrieve.
+     * @returns The value cast to type `T`, or `undefined` if the key or player doesn't exist.
+     */
+    async getMeta(clientID, key) {
+        return this.getByClient(clientID)?.getMeta(key);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Extended Query Methods
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Retrieves a Player by their persistent account ID.
+     *
+     * @param accountId - The unique account identifier to search for.
+     * @returns The Player if found, or `undefined` if not online.
+     */
+    getByAccountId(accountId) {
+        return this.world.find(this.isPlayer).find((p) => p.accountID === accountId);
+    }
+    /**
+     * Returns the current number of connected players.
+     *
+     * @returns Player count.
+     */
+    getPlayerCount() {
+        return this.world.sizeBy('player');
+    }
+    /**
+     * Checks if a player with the given account ID is currently online.
+     *
+     * @param accountId - The account identifier to check.
+     * @returns `true` if online, `false` otherwise.
+     */
+    isOnline(accountId) {
+        return !!this.getByAccountId(accountId);
+    }
+};
+LocalPlayerImplementation = __decorate([
+    injectable(),
+    __param(0, inject(WorldContext)),
+    __param(1, inject(IPlayerInfo)),
+    __param(2, inject(IPlayerServer)),
+    __param(3, inject(IPlayerLifecycleServer)),
+    __param(4, inject(IPlayerStateSyncServer)),
+    __param(5, inject(IEntityServer)),
+    __param(6, inject(EventsAPI)),
+    __param(7, inject(IPlatformContext)),
+    __metadata("design:paramtypes", [WorldContext,
+        IPlayerInfo,
+        IPlayerServer,
+        IPlayerLifecycleServer,
+        IPlayerStateSyncServer,
+        IEntityServer,
+        EventsAPI,
+        IPlatformContext])
+], LocalPlayerImplementation);
+export { LocalPlayerImplementation };