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

package/dist/runtime/client/webview.service.js

@@ -17,6 +17,7 @@ const FALLBACK_CAPABILITIES = {
     supportsBidirectionalMessaging: true,
     supportsExecute: false,
     supportsHeadless: false,
+    supportsChatMode: false,
 };
 function createFallbackBridge() {
     const runtime = di.resolve(IClientRuntimeBridge);
@@ -34,6 +35,7 @@ function createFallbackBridge() {
             runtime.setWebViewInputPassthrough(options?.inputPassthrough ?? false);
         },
         blur: () => runtime.setWebViewFocus(false, false),
+        markAsChat: () => { },
         send: (viewId, event, payload) => {
             runtime.sendWebViewMessage(JSON.stringify({ __opencoreWebView: true, viewId, action: event, data: payload }));
         },
@@ -85,6 +87,9 @@ let WebViewService = class WebViewService {
     blur(viewId) {
         this.bridge.blur(viewId);
     }
+    markAsChat(viewId) {
+        this.bridge.markAsChat(viewId);
+    }
     send(viewId, event, payload) {
         this.bridge.send(viewId, event, payload);
     }

package/dist/runtime/server/adapter/node-player-appearance-lifecycle-server.js

@@ -16,6 +16,7 @@ import { IPedAppearanceServer } from '../../../adapters/contracts/server/IPedApp
 import { IPlayerAppearanceLifecycleServer } from '../../../adapters/contracts/server/player-appearance/IPlayerAppearanceLifecycleServer';
 import { IPlayerServer } from '../../../adapters/contracts/server/IPlayerServer';
 import { Players } from '../ports/players.api-port';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 let NodePlayerAppearanceLifecycleServer = class NodePlayerAppearanceLifecycleServer extends IPlayerAppearanceLifecycleServer {
     pedAdapter;
     playerServer;
@@ -38,7 +39,7 @@ let NodePlayerAppearanceLifecycleServer = class NodePlayerAppearanceLifecycleSer
         if (!target) {
             return { success: false, errors: ['Player not found'] };
         }
-        this.events.emit('opencore:appearance:apply', target, appearance);
+        this.events.emit(SYSTEM_EVENTS.appearance.apply, target, appearance);
         return { success: true, appearance };
     }
     applyClothing(playerSrc, appearance) {
@@ -56,7 +57,7 @@ let NodePlayerAppearanceLifecycleServer = class NodePlayerAppearanceLifecycleSer
         const target = this.resolveTarget(playerSrc);
         if (!target)
             return false;
-        this.events.emit('opencore:appearance:reset', target);
+        this.events.emit(SYSTEM_EVENTS.appearance.reset, target);
         return true;
     }
     resolveTarget(playerSrc) {

package/dist/runtime/server/adapter/node-player-lifecycle-server.js

@@ -13,6 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { inject, injectable } from 'tsyringe';
 import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
 import { IPlayerLifecycleServer } from '../../../adapters/contracts/server/player-lifecycle/IPlayerLifecycleServer';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 let NodePlayerLifecycleServer = class NodePlayerLifecycleServer extends IPlayerLifecycleServer {
     events;
     constructor(events) {
@@ -23,7 +24,7 @@ let NodePlayerLifecycleServer = class NodePlayerLifecycleServer extends IPlayerL
         const target = this.resolveTarget(playerSrc);
         if (!target)
             return;
-        this.events.emit('opencore:spawner:spawn', target, {
+        this.events.emit(SYSTEM_EVENTS.spawner.spawn, target, {
             position: request.position,
             model: request.model,
             heading: request.heading,
@@ -34,13 +35,13 @@ let NodePlayerLifecycleServer = class NodePlayerLifecycleServer extends IPlayerL
         const target = this.resolveTarget(playerSrc);
         if (!target)
             return;
-        this.events.emit('opencore:spawner:teleport', target, request.position, request.heading);
+        this.events.emit(SYSTEM_EVENTS.spawner.teleport, target, request.position, request.heading);
     }
     respawn(playerSrc, request) {
         const target = this.resolveTarget(playerSrc);
         if (!target)
             return;
-        this.events.emit('opencore:spawner:respawn', target, request.position, request.heading);
+        this.events.emit(SYSTEM_EVENTS.spawner.respawn, target, request.position, request.heading);
     }
     resolveTarget(playerSrc) {
         const clientId = Number(playerSrc);

package/dist/runtime/server/adapter/node-vehicle-lifecycle-server.js

@@ -15,6 +15,7 @@ import { IVehicleLifecycleServer } from '../../../adapters/contracts/server/vehi
 import { IPlatformContext } from '../../../adapters/contracts/IPlatformContext';
 import { IVehicleServer } from '../../../adapters/contracts/server/IVehicleServer';
 import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 let NodeVehicleLifecycleServer = class NodeVehicleLifecycleServer extends IVehicleLifecycleServer {
     vehicleServer;
     platformContext;
@@ -42,7 +43,7 @@ let NodeVehicleLifecycleServer = class NodeVehicleLifecycleServer extends IVehic
         const clientId = Number(request.playerSrc);
         if (Number.isNaN(clientId))
             return;
-        this.events.emit('opencore:vehicle:warpInto', clientId, request.networkId, request.seatIndex);
+        this.events.emit(SYSTEM_EVENTS.vehicle.warpInto, clientId, request.networkId, request.seatIndex);
     }
 };
 NodeVehicleLifecycleServer = __decorate([

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

@@ -12,6 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from 'tsyringe';
 import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 import { Players } from '../ports/players.api-port';
 /**
  * Service for sending chat messages to players.
@@ -35,7 +36,7 @@ let Chat = class Chat {
      * @param color - Message color (RGB). Defaults to white.
      */
     broadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
-        this.events.emit('core:chat:message', 'all', {
+        this.events.emit(SYSTEM_EVENTS.chat.message, 'all', {
             args: [author, message],
             color: color,
         });
@@ -49,7 +50,7 @@ let Chat = class Chat {
      * @param color - Message color (RGB).
      */
     sendPrivate(player, message, author = 'Private', color = { r: 200, g: 200, b: 200 }) {
-        this.events.emit('core:chat:addMessage', player.clientID, {
+        this.events.emit(SYSTEM_EVENTS.chat.addMessage, player.clientID, {
             args: [author, message],
             color: color,
         });
@@ -60,7 +61,7 @@ let Chat = class Chat {
      * @param player - Target player.
      */
     clearChat(player) {
-        this.events.emit('core:chat:clear', player.clientID);
+        this.events.emit(SYSTEM_EVENTS.chat.clear, player.clientID);
     }
     /**
      * Send a chat message to multiple players.
@@ -72,7 +73,7 @@ let Chat = class Chat {
      */
     sendMany(players, message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
         const targetIds = players.map((p) => (typeof p === 'number' ? p : p.clientID));
-        this.events.emit('core:chat:addMessage', targetIds, {
+        this.events.emit(SYSTEM_EVENTS.chat.addMessage, targetIds, {
             args: [author, message],
             color: color,
         });
@@ -116,7 +117,7 @@ let Chat = class Chat {
      * Clear chat for all connected players.
      */
     clearChatAll() {
-        this.events.emit('core:chat:clear', 'all');
+        this.events.emit(SYSTEM_EVENTS.chat.clear, 'all');
     }
 };
 Chat = __decorate([

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

@@ -19,6 +19,7 @@ import { INpcLifecycleServer } from '../../../adapters/contracts/server/npc-life
 import { IPedServer } from '../../../adapters/contracts/server/IPedServer';
 import { coreLogger } from '../../../kernel/logger';
 import { WorldContext } from '../../core/world';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 import { NPC } from '../entities/npc';
 /**
  * Server-side API responsible for the full NPC (ped) lifecycle:
@@ -311,7 +312,7 @@ let Npcs = class Npcs {
             netId: npc.netId,
             remainingNpcs: this.npcById.size,
         });
-        this.events.emit('opencore:npc:deleted', 'all', npc.npcId);
+        this.events.emit(SYSTEM_EVENTS.npc.deleted, 'all', npc.npcId);
         return true;
     }
     /**

package/dist/runtime/server/apis/parallel-compute.api.js

@@ -4,6 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { performance } from 'node:perf_hooks';
 import { injectable } from 'tsyringe';
 import { v4 as uuid } from 'uuid';
 import { WorkerPool } from '../services/parallel/worker-pool';

package/dist/runtime/server/apis/vehicle-modification.api.js

@@ -10,9 +10,11 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { inject, injectable } from 'tsyringe';
+import { inject } from 'tsyringe';
 import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
 import { coreLogger } from '../../../kernel/logger';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
+import { Bind } from '../decorators/bind';
 import { Vehicles } from './vehicles.api';
 /**
  * Service for handling vehicle modifications with validation.
@@ -73,7 +75,7 @@ let VehicleModification = class VehicleModification {
             requestedBy,
             mods: Object.keys(validatedMods),
         });
-        this.events.emit('opencore:vehicle:modified', 'all', {
+        this.events.emit(SYSTEM_EVENTS.vehicle.modified, 'all', {
             networkId,
             mods: validatedMods,
         });
@@ -200,7 +202,7 @@ let VehicleModification = class VehicleModification {
             windowTint: 0,
         };
         coreLogger.info('Vehicle modifications reset', { networkId, requestedBy });
-        this.events.emit('opencore:vehicle:modified', 'all', {
+        this.events.emit(SYSTEM_EVENTS.vehicle.modified, 'all', {
             networkId,
             mods: defaultMods,
         });
@@ -304,7 +306,7 @@ let VehicleModification = class VehicleModification {
     }
 };
 VehicleModification = __decorate([
-    injectable(),
+    Bind('singleton'),
     __param(0, inject(Vehicles)),
     __param(1, inject(EventsAPI)),
     __metadata("design:paramtypes", [Vehicles,

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

@@ -10,15 +10,17 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { inject, injectable } from 'tsyringe';
+import { inject } 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 { SYSTEM_EVENTS } from '../../shared/types/system-types';
 import { Vehicle } from '../entities/vehicle';
 import { Players } from '../ports/players.api-port';
+import { Bind } from '../decorators/bind';
 const DEFAULT_PLAYER_VEHICLE_OFFSET = { x: 0, y: 3, z: 0 };
 /**
  * Server-side service for managing vehicle entities.
@@ -130,7 +132,7 @@ let Vehicles = class Vehicles {
                 persistent,
                 totalVehicles: this.vehiclesByNetworkId.size,
             });
-            this.events.emit('opencore:vehicle:created', 'all', vehicle.serialize());
+            this.events.emit(SYSTEM_EVENTS.vehicle.created, 'all', vehicle.serialize());
             return {
                 networkId,
                 handle,
@@ -178,6 +180,7 @@ let Vehicles = class Vehicles {
             ...options,
             position: spawnPosition,
             heading: spawnHeading,
+            plate: ownership.type === 'player' ? player.name : 'anom',
             ownership,
         });
         if (result.success) {
@@ -289,7 +292,7 @@ let Vehicles = class Vehicles {
             networkId,
             totalVehicles: this.vehiclesByNetworkId.size,
         });
-        this.events.emit('opencore:vehicle:deleted', 'all', networkId);
+        this.events.emit(SYSTEM_EVENTS.vehicle.deleted, 'all', networkId);
         return true;
     }
     /**
@@ -381,7 +384,7 @@ let Vehicles = class Vehicles {
     }
 };
 Vehicles = __decorate([
-    injectable(),
+    Bind('singleton'),
     __param(0, inject(Players)),
     __param(1, inject(IEntityServer)),
     __param(2, inject(IVehicleServer)),

package/dist/runtime/server/bootstrap.js

@@ -12,6 +12,7 @@ import { getFrameworkModeScope, setRuntimeContext, validateRuntimeOptions, } fro
 import { BinaryProcessManager } from './system/managers/binary-process.manager';
 import { SessionRecoveryService } from './services/session-recovery.local';
 import { registerServicesServer } from './services/services.register';
+import { SYSTEM_EVENTS } from '../shared/types/system-types';
 import { METADATA_KEYS } from './system/metadata-server.keys';
 import { registerSystemServer } from './system/processors.register';
 const CORE_WAIT_TIMEOUT = 10000;
@@ -163,13 +164,13 @@ export async function initServer(options, plugins) {
         const engineEvents = GLOBAL_CONTAINER.resolve(IEngineEvents);
         const events = GLOBAL_CONTAINER.resolve(EventsAPI);
         // 1. Broadast to resources already running
-        engineEvents.emit('core:ready');
-        events.emit('core:ready', 'all');
-        // 2. Listen for 'core:request-ready' for resources starting late (hot-reload)
-        engineEvents.on('core:request-ready', () => {
-            engineEvents.emit('core:ready');
+        engineEvents.emit(SYSTEM_EVENTS.core.ready);
+        events.emit(SYSTEM_EVENTS.core.ready, 'all');
+        // 2. Listen for '_systemcore:request-ready' for resources starting late (hot-reload)
+        engineEvents.on(SYSTEM_EVENTS.core.requestReady, () => {
+            engineEvents.emit(SYSTEM_EVENTS.core.ready);
         });
-        loggers.bootstrap.info(`'core:ready' logic initialized and broadcasted`);
+        loggers.bootstrap.info(`'${SYSTEM_EVENTS.core.ready}' logic initialized and broadcasted`);
     }
     const logLevelLabel = LogLevelLabels[getLogLevel()];
     loggers.bootstrap.info(`LogLevel Setted: ${logLevelLabel}`);
@@ -192,13 +193,13 @@ function createCoreDependency(coreName) {
         const exportsService = GLOBAL_CONTAINER.resolve(IExports);
         const onReady = () => {
             if (!resolved) {
-                loggers.bootstrap.debug(`Core '${coreName}' detected via 'core:ready' event!`);
+                loggers.bootstrap.debug(`Core '${coreName}' detected via '${SYSTEM_EVENTS.core.ready}' event!`);
                 cleanup();
                 resolve();
             }
         };
-        engineEvents.on('core:ready', onReady);
-        loggers.bootstrap.debug(`Listening for 'core:ready' event from Core`);
+        engineEvents.on(SYSTEM_EVENTS.core.ready, onReady);
+        loggers.bootstrap.debug(`Listening for '${SYSTEM_EVENTS.core.ready}' event from Core`);
         // 2. Check if already ready via export (Polling)
         const checkReady = () => {
             if (resolved)
@@ -223,15 +224,15 @@ function createCoreDependency(coreName) {
         // 3. Request status (for hot-reload cases where Core is already up)
         // This is sent AFTER registering the listener so we can receive the response
         if (!resolved) {
-            loggers.bootstrap.debug(`Requesting Core status via 'core:request-ready' event`);
-            engineEvents.emit('core:request-ready');
+            loggers.bootstrap.debug(`Requesting Core status via '${SYSTEM_EVENTS.core.requestReady}' event`);
+            engineEvents.emit(SYSTEM_EVENTS.core.requestReady);
         }
         // 4. Timeout protection
         timeout = setTimeout(() => {
             if (!resolved) {
                 loggers.bootstrap.warn(`Timeout waiting for Core '${coreName}' after ${CORE_WAIT_TIMEOUT}ms`);
                 cleanup();
-                reject(new Error(`[OpenCore] Timeout waiting for CORE '${coreName}'. The Core did not emit 'core:ready' or expose 'isCoreReady' within ${CORE_WAIT_TIMEOUT}ms.`));
+                reject(new Error(`[OpenCore] Timeout waiting for CORE '${coreName}'. The Core did not emit '${SYSTEM_EVENTS.core.ready}' or expose 'isCoreReady' within ${CORE_WAIT_TIMEOUT}ms.`));
             }
         }, CORE_WAIT_TIMEOUT);
     });

package/dist/runtime/server/controllers/command-export.controller.js

@@ -11,9 +11,11 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { inject } from 'tsyringe';
+import { z } from 'zod';
 import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
 import { AppError, SecurityError } from '../../../kernel/error';
 import { loggers } from '../../../kernel/logger';
+import { buildRemoteCommandExecuteEventName, SYSTEM_EVENTS } from '../../shared/types/system-types';
 import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
 import { Controller, Export, Public } from '../decorators';
 import { OnNet } from '../decorators/onNet';
@@ -211,7 +213,7 @@ let CommandExportController = class CommandExportController {
             // Validate security BEFORE delegating to resource
             await this.validateSecurity(player, commandName, remoteEntry.metadata.security);
             // Delegate to resource via local event (server-to-server, not network)
-            const eventName = `opencore:command:execute:${remoteEntry.resourceName}`;
+            const eventName = buildRemoteCommandExecuteEventName(remoteEntry.resourceName);
             this.engineEvents.emit(eventName, clientID, commandName, args);
             loggers.command.debug(`Delegated remote command execution to ${remoteEntry.resourceName}`, {
                 command: commandName,
@@ -294,7 +296,7 @@ let CommandExportController = class CommandExportController {
 };
 __decorate([
     Public(),
-    OnNet('core:execute-command'),
+    OnNet(SYSTEM_EVENTS.command.execute, z.tuple([z.string().min(1), z.array(z.string())])),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Player, String, Array]),
     __metadata("design:returntype", Promise)

package/dist/runtime/server/controllers/remote-command-execution.controller.js

@@ -14,6 +14,7 @@ import { inject } from 'tsyringe';
 import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
 import { IResourceInfo } from '../../../adapters/contracts/IResourceInfo';
 import { loggers } from '../../../kernel/logger';
+import { buildRemoteCommandExecuteEventName } from '../../shared/types/system-types';
 import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
 import { Controller } from '../decorators';
 import { normalizeToAppError } from '../helpers/normalize-app-error';
@@ -73,7 +74,7 @@ let RemoteCommandExecutionController = class RemoteCommandExecutionController {
      */
     registerEventHandler() {
         const resourceName = this.resourceInfo.getCurrentResourceName();
-        const eventName = `opencore:command:execute:${resourceName}`;
+        const eventName = buildRemoteCommandExecuteEventName(resourceName);
         this.engineEvents.on(eventName, async (clientID, commandName, args) => {
             await this.handleCommandExecution(clientID, commandName, args);
         });

package/dist/runtime/server/controllers/vehicle.controller.js

@@ -12,6 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject } from 'tsyringe';
 import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 import { Controller, OnNet } from '../decorators';
 import { Player } from '../entities/player';
 import { Vehicles } from '../apis/vehicles.api';
@@ -34,11 +35,11 @@ let VehicleController = class VehicleController {
     handleGetData(player, networkId) {
         const vehicle = this.vehicleService.getByNetworkId(networkId);
         if (!vehicle) {
-            this.events.emit('opencore:vehicle:dataResult', player.clientID, null);
+            this.events.emit(SYSTEM_EVENTS.vehicle.dataResult, player.clientID, null);
             return null;
         }
         const data = vehicle.serialize();
-        this.events.emit('opencore:vehicle:dataResult', player.clientID, data);
+        this.events.emit(SYSTEM_EVENTS.vehicle.dataResult, player.clientID, data);
         return data;
     }
     /**
@@ -47,18 +48,18 @@ let VehicleController = class VehicleController {
     handleGetPlayerVehicles(player) {
         const vehicles = this.vehicleService.getPlayerVehicles(player.clientID);
         const serialized = vehicles.map((v) => v.serialize());
-        this.events.emit('opencore:vehicle:playerVehiclesResult', player.clientID, serialized);
+        this.events.emit(SYSTEM_EVENTS.vehicle.playerVehiclesResult, player.clientID, serialized);
         return serialized;
     }
 };
 __decorate([
-    OnNet('opencore:vehicle:getData'),
+    OnNet(SYSTEM_EVENTS.vehicle.getData),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Player, Number]),
     __metadata("design:returntype", void 0)
 ], VehicleController.prototype, "handleGetData", null);
 __decorate([
-    OnNet('opencore:vehicle:getPlayerVehicles'),
+    OnNet(SYSTEM_EVENTS.vehicle.getPlayerVehicles),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Player]),
     __metadata("design:returntype", void 0)

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

@@ -36,6 +36,8 @@ export interface CommandMetadata extends CommandConfig {
     security?: SecurityMetadata;
     /** True if the last parameter uses the spread operator (...args) */
     hasSpreadParam?: boolean;
+    /** True when a parameter defines a JS default value. */
+    defaultParams?: boolean[];
 }
 type ServerCommandHandler = (() => any) | ((player: Player, ...args: any[]) => any);
 /**

package/dist/runtime/server/decorators/command.js

@@ -1,5 +1,5 @@
 import { Player } from '../entities/player';
-import { getParameterNames, getSpreadParameterIndices } from '../helpers/function-helper';
+import { getDefaultParameterIndices, getParameterNames, getSpreadParameterIndices, } from '../helpers/function-helper';
 import { METADATA_KEYS } from '../system/metadata-server.keys';
 // Implementation
 export function Command(configOrName, schema) {
@@ -20,6 +20,7 @@ export function Command(configOrName, schema) {
             throw new Error(`@Command '${config.command}': first parameter must be Player if parameters are present`);
         }
         const paramNames = getParameterNames(descriptor.value);
+        const defaultParams = getDefaultParameterIndices(descriptor.value);
         const spreadIndices = getSpreadParameterIndices(descriptor.value);
         const hasSpreadParam = spreadIndices.length > 0 && spreadIndices[spreadIndices.length - 1];
         const metadata = {
@@ -30,6 +31,7 @@ export function Command(configOrName, schema) {
             paramNames,
             expectsPlayer,
             hasSpreadParam,
+            defaultParams,
         };
         Reflect.defineMetadata(METADATA_KEYS.COMMAND, metadata, target, propertyKey);
     };

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

@@ -1,4 +1,3 @@
-import { NativeHandle } from 'src/runtime/core/nativehandle';
 import { IEntityServer } from '../../../adapters/contracts/server/IEntityServer';
 import { INpcLifecycleServer } from '../../../adapters/contracts/server/npc-lifecycle/INpcLifecycleServer';
 import { IPedServer } from '../../../adapters/contracts/server/IPedServer';
@@ -6,6 +5,7 @@ import { Vector3 } from '../../../kernel/utils/vector3';
 import { BaseEntity } from '../../core/entity';
 import { Spatial } from '../../core/spatial';
 import { SerializedNpcData } from '../types/npc.types';
+import { NativeHandle } from '../../core';
 export interface NpcAdapters {
     entityServer: IEntityServer;
     pedServer: IPedServer;

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

@@ -11,7 +11,7 @@ import { Spatial } from '../../core/spatial';
 import { LinkedID } from '../types/linked-id';
 import { PlayerSession } from '../types/player-session.types';
 import { SerializedPlayerData } from '../types/core-exports.types';
-import { NativeHandle } from 'src/runtime/core/nativehandle';
+import { NativeHandle } from '../../core';
 /**
  * Adapter bundle for player operations.
  * Passed to Player instances by PlayerDirectory.

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

@@ -1,5 +1,6 @@
 import { loggers } from '../../../kernel/logger';
 import { BaseEntity } from '../../core/entity';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 /**
  * Core-level representation of a connected player on the server.
  *
@@ -30,10 +31,16 @@ export class Player extends BaseEntity {
         this._position = adapters.playerInfo.getPlayerPosition(session.clientID);
     }
     getHeading() {
-        return this.adapters.entityServer.getHeading(this.clientID);
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        if (!ped || ped === 0)
+            return 0;
+        return this.adapters.entityServer.getHeading(ped);
     }
     setHeading(heading) {
-        this.adapters.entityServer.setHeading(this.clientID, heading);
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        if (!ped || ped === 0)
+            return;
+        this.adapters.entityServer.setHeading(ped, heading);
     }
     getHandle() {
         return this.clientID;
@@ -120,7 +127,7 @@ export class Player extends BaseEntity {
      * @param type - Message type for styling
      */
     send(message, type = 'chat') {
-        this.emit('core:chat:send', message, type);
+        this.emit(SYSTEM_EVENTS.chat.send, message, type);
     }
     // ─────────────────────────────────────────────────────────────────
     // Spawning / Teleporting

package/dist/runtime/server/helpers/command-validation.helper.js

@@ -4,17 +4,21 @@ import { generateSchemaFromTypes } from '../system/schema-generator';
 import { processTupleSchema } from '../../shared/helpers/process-tuple-schema';
 export async function validateAndExecuteCommand(meta, player, args, handler) {
     const paramNames = meta.expectsPlayer ? meta.paramNames.slice(1) : meta.paramNames;
+    const defaultParams = meta.expectsPlayer
+        ? (meta.defaultParams ?? []).slice(1)
+        : (meta.defaultParams ?? []);
     let schema = meta.schema;
     if (!meta.expectsPlayer) {
         if (args.length > 0) {
-            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
-                usage: meta.usage,
+            const usage = resolveCommandUsage(meta, paramNames, defaultParams);
+            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${usage}`, 'client', {
+                usage,
             });
         }
         return await handler();
     }
     if (!schema) {
-        schema = generateSchemaFromTypes(meta.paramTypes);
+        schema = generateSchemaFromTypes(meta.paramTypes, meta.defaultParams);
         if (!schema) {
             if (paramNames.length > 0) {
                 throw new AppError('SCHEMA:MISMATCH', `Command '${meta.command}' has parameters ${paramNames.join(', ')} but no schema was provided.`, 'core');
@@ -39,8 +43,9 @@ export async function validateAndExecuteCommand(meta, player, args, handler) {
             inputObj[paramNames[i]] = args[i];
         }
         const validated = await schema.parseAsync(inputObj).catch(() => {
-            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
-                usage: meta.usage,
+            const usage = resolveCommandUsage(meta, paramNames, defaultParams);
+            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${usage}`, 'client', {
+                usage,
             });
         });
         const obj = validated;
@@ -51,8 +56,9 @@ export async function validateAndExecuteCommand(meta, player, args, handler) {
     if (schema instanceof z.ZodTuple) {
         const processedArgs = processTupleSchema(schema, args);
         const validated = await schema.parseAsync(processedArgs).catch(() => {
-            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
-                usage: meta.usage,
+            const usage = resolveCommandUsage(meta, paramNames, defaultParams);
+            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${usage}`, 'client', {
+                usage,
             });
         });
         const finalArgs = validated;
@@ -71,3 +77,10 @@ export async function validateAndExecuteCommand(meta, player, args, handler) {
     // fallback
     return await handler(player);
 }
+function resolveCommandUsage(meta, paramNames, defaultParams) {
+    if (meta.usage?.trim()) {
+        return meta.usage;
+    }
+    const renderedParams = paramNames.map((name, index) => defaultParams[index] ? `[${name}]` : `<${name}>`);
+    return `/${meta.command}${renderedParams.length > 0 ? ` ${renderedParams.join(' ')}` : ''}`;
+}

package/dist/runtime/server/helpers/function-helper.d.ts

@@ -1,4 +1,5 @@
 export declare function getParameterNames(func: (...args: any[]) => any): string[];
+export declare function getDefaultParameterIndices(func: (...args: any[]) => any): boolean[];
 /**
  * Detects which parameter indices use the spread operator (...args).
  * Returns an array of booleans where true means the parameter at that index is a spread parameter.

package/dist/runtime/server/helpers/function-helper.js

@@ -1,14 +1,10 @@
 export function getParameterNames(func) {
-    const stripped = func
-        .toString()
-        .replace(/\/\/.*$/gm, '')
-        .replace(/\/\*[\s\S]*?\*\//gm, '');
-    const args = stripped
-        .slice(stripped.indexOf('(') + 1, stripped.indexOf(')'))
-        .split(',')
+    return parseParameterTokens(func)
         .map((arg) => arg.replace(/=[\s\S]*/, '').trim())
         .filter(Boolean);
-    return args;
+}
+export function getDefaultParameterIndices(func) {
+    return parseParameterTokens(func).map((arg) => arg.includes('='));
 }
 /**
  * Detects which parameter indices use the spread operator (...args).
@@ -26,3 +22,14 @@ export function getSpreadParameterIndices(func) {
         .filter(Boolean);
     return args.map((arg) => arg.startsWith('...'));
 }
+function parseParameterTokens(func) {
+    const stripped = func
+        .toString()
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//gm, '');
+    return stripped
+        .slice(stripped.indexOf('(') + 1, stripped.indexOf(')'))
+        .split(',')
+        .map((arg) => arg.trim())
+        .filter(Boolean);
+}

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

@@ -1,5 +1,5 @@
 import { EventsAPI } from '../../../../adapters/contracts/transport/events.api';
-import { RGB } from 'src/kernel';
+import { RGB } from '../../../../kernel/utils';
 import { Player } from '../../entities';
 import { Channels } from '../../ports/channel.api-port';
 import { IChannelValidator, ChannelMetadata, ChannelType } from '../../types';