@open-core/framework 1.0.1-beta.1

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

@@ -0,0 +1,40 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NuiProcessor = void 0;
+const tsyringe_1 = require("tsyringe");
+const metadata_client_keys_1 = require("../metadata-client.keys");
+const logger_1 = require("../../../shared/logger");
+let NuiProcessor = class NuiProcessor {
+    constructor() {
+        this.metadataKey = metadata_client_keys_1.METADATA_KEYS.NUI;
+    }
+    process(target, methodName, metadata) {
+        const handler = target[methodName].bind(target);
+        const handlerName = `${target.constructor.name}.${methodName}`;
+        RegisterNuiCallbackType(metadata.eventName);
+        on(`__cfx_nui:${metadata.eventName}`, async (data, cb) => {
+            try {
+                await handler(data);
+                cb({ ok: true });
+            }
+            catch (error) {
+                logger_1.loggers.nui.error(`NUI callback error`, {
+                    event: metadata.eventName,
+                    handler: handlerName,
+                }, error);
+                cb({ ok: false, error: String(error) });
+            }
+        });
+        logger_1.loggers.nui.debug(`Registered: ${metadata.eventName} -> ${handlerName}`);
+    }
+};
+exports.NuiProcessor = NuiProcessor;
+exports.NuiProcessor = NuiProcessor = __decorate([
+    (0, tsyringe_1.injectable)()
+], NuiProcessor);

package/dist/client/system/processors/resourceLifecycle.processor.d.ts

@@ -0,0 +1,9 @@
+import { DecoratorProcessor } from '../../../system/decorator-processor';
+export declare class ResourceStartProcessor implements DecoratorProcessor {
+    readonly metadataKey: string;
+    process(target: any, methodName: string): void;
+}
+export declare class ResourceStopProcessor implements DecoratorProcessor {
+    readonly metadataKey: string;
+    process(target: any, methodName: string): void;
+}

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

@@ -0,0 +1,69 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceStopProcessor = exports.ResourceStartProcessor = void 0;
+const tsyringe_1 = require("tsyringe");
+const metadata_client_keys_1 = require("../metadata-client.keys");
+const logger_1 = require("../../../shared/logger");
+const clientLifecycle = logger_1.coreLogger.child('Lifecycle', logger_1.LogDomain.CLIENT);
+let ResourceStartProcessor = class ResourceStartProcessor {
+    constructor() {
+        this.metadataKey = metadata_client_keys_1.METADATA_KEYS.RESOURCE_START;
+    }
+    process(target, methodName) {
+        const handler = target[methodName].bind(target);
+        const handlerName = `${target.constructor.name}.${methodName}`;
+        const currentResource = GetCurrentResourceName();
+        on('onClientResourceStart', async (resourceName) => {
+            if (resourceName !== currentResource)
+                return;
+            try {
+                await handler(resourceName);
+            }
+            catch (error) {
+                clientLifecycle.error(`Resource start handler error`, {
+                    handler: handlerName,
+                    resource: resourceName,
+                }, error);
+            }
+        });
+        clientLifecycle.debug(`Registered resource start handler: ${handlerName}`);
+    }
+};
+exports.ResourceStartProcessor = ResourceStartProcessor;
+exports.ResourceStartProcessor = ResourceStartProcessor = __decorate([
+    (0, tsyringe_1.injectable)()
+], ResourceStartProcessor);
+let ResourceStopProcessor = class ResourceStopProcessor {
+    constructor() {
+        this.metadataKey = metadata_client_keys_1.METADATA_KEYS.RESOURCE_STOP;
+    }
+    process(target, methodName) {
+        const handler = target[methodName].bind(target);
+        const handlerName = `${target.constructor.name}.${methodName}`;
+        const currentResource = GetCurrentResourceName();
+        on('onClientResourceStop', async (resourceName) => {
+            if (resourceName !== currentResource)
+                return;
+            try {
+                await handler(resourceName);
+            }
+            catch (error) {
+                clientLifecycle.error(`Resource stop handler error`, {
+                    handler: handlerName,
+                    resource: resourceName,
+                }, error);
+            }
+        });
+        clientLifecycle.debug(`Registered resource stop handler: ${handlerName}`);
+    }
+};
+exports.ResourceStopProcessor = ResourceStopProcessor;
+exports.ResourceStopProcessor = ResourceStopProcessor = __decorate([
+    (0, tsyringe_1.injectable)()
+], ResourceStopProcessor);

package/dist/client/system/processors/tick.processor.d.ts

@@ -0,0 +1,5 @@
+import { DecoratorProcessor } from '../../../system/decorator-processor';
+export declare class TickProcessor implements DecoratorProcessor {
+    readonly metadataKey: string;
+    process(target: any, methodName: string): void;
+}

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

@@ -0,0 +1,37 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TickProcessor = void 0;
+const tsyringe_1 = require("tsyringe");
+const metadata_client_keys_1 = require("../metadata-client.keys");
+const logger_1 = require("../../../shared/logger");
+const clientTick = logger_1.coreLogger.child('Tick', logger_1.LogDomain.CLIENT);
+let TickProcessor = class TickProcessor {
+    constructor() {
+        this.metadataKey = metadata_client_keys_1.METADATA_KEYS.TICK;
+    }
+    process(target, methodName) {
+        const handler = target[methodName].bind(target);
+        const handlerName = `${target.constructor.name}.${methodName}`;
+        setTick(async () => {
+            try {
+                await handler();
+            }
+            catch (error) {
+                clientTick.error(`Tick handler error`, {
+                    handler: handlerName,
+                }, error);
+            }
+        });
+        clientTick.debug(`Registered: ${handlerName}`);
+    }
+};
+exports.TickProcessor = TickProcessor;
+exports.TickProcessor = TickProcessor = __decorate([
+    (0, tsyringe_1.injectable)()
+], TickProcessor);

package/dist/client/system/processors.register.d.ts

@@ -0,0 +1 @@
+export declare function registerSystemClient(): void;

package/dist/client/system/processors.register.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSystemClient = registerSystemClient;
+const client_container_1 = require("../client-container");
+const key_processor_1 = require("./processors/key.processor");
+const tick_processor_1 = require("./processors/tick.processor");
+const nui_processor_1 = require("./processors/nui.processor");
+const netEvent_processor_1 = require("./processors/netEvent.processor");
+const localEvent_processor_1 = require("./processors/localEvent.processor");
+const interval_processor_1 = require("./processors/interval.processor");
+const export_processor_1 = require("./processors/export.processor");
+const resourceLifecycle_processor_1 = require("./processors/resourceLifecycle.processor");
+const gameEvent_processor_1 = require("./processors/gameEvent.processor");
+function registerSystemClient() {
+    // Core processors
+    client_container_1.di.register('DecoratorProcessor', { useClass: key_processor_1.KeyMappingProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: tick_processor_1.TickProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: nui_processor_1.NuiProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: netEvent_processor_1.ClientNetEventProcessor });
+    // New processors
+    client_container_1.di.register('DecoratorProcessor', { useClass: localEvent_processor_1.LocalEventProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: interval_processor_1.IntervalProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: export_processor_1.ClientExportProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: resourceLifecycle_processor_1.ResourceStartProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: resourceLifecycle_processor_1.ResourceStopProcessor });
+    client_container_1.di.register('DecoratorProcessor', { useClass: gameEvent_processor_1.GameEventProcessor });
+}

package/dist/client/types/game-events.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Game Events - Native GTA V internal events captured by FiveM
+ *
+ * Documentation: https://docs.fivem.net/docs/game-references/game-events/
+ *
+ * These are low-level events from the RAGE engine. The arguments are
+ * passed as arrays from the native layer.
+ */
+export type GameEventName = 'CEventNetworkEntityDamage' | 'CEventNetworkPlayerEnteredVehicle' | 'CEventNetworkPlayerLeftVehicle' | 'CEventNetworkVehicleUndrivable' | 'CEventNetworkPlayerSpawn' | 'CEventNetworkPlayerCollectedPickup' | 'CEventNetworkPlayerCollectedAmbientPickup' | 'CEventShockingSeenPedKilled' | 'CEventShockingWeaponThreat' | 'CEventShockingGunshotFired' | 'CEventShockingExplosion' | 'CEventGunShot' | 'CEventGunShotWhizzedBy' | 'CEventExplosionHeard' | 'CEventShockingCarCrash' | 'CEventShockingBicycleCrash' | 'CEventShockingSeenCarStolen' | (string & {});
+/**
+ * CEventNetworkEntityDamage
+ * Fired when any networked entity takes damage
+ */
+export interface EntityDamageEvent {
+    /** Entity that was damaged */
+    victim: number;
+    /** Entity that caused the damage (0 if none) */
+    attacker: number;
+    /** Unknown parameter */
+    arg2: number;
+    /** Unknown parameter */
+    arg3: number;
+    /** Unknown parameter */
+    arg4: number;
+    /** Whether the victim died from this damage */
+    victimDied: boolean;
+    /** Weapon hash used */
+    weaponHash: number;
+    /** Unknown parameter */
+    arg7: number;
+    /** Unknown parameter */
+    arg8: number;
+    /** Unknown parameter - possibly damage amount related */
+    arg9: number;
+}
+/**
+ * CEventNetworkPlayerEnteredVehicle
+ * Fired when a player enters a vehicle
+ */
+export interface PlayerEnteredVehicleEvent {
+    /** Player that entered */
+    player: number;
+    /** Vehicle entered */
+    vehicle: number;
+}
+/**
+ * CEventNetworkPlayerLeftVehicle
+ * Fired when a player leaves a vehicle
+ */
+export interface PlayerLeftVehicleEvent {
+    /** Player that left */
+    player: number;
+    /** Vehicle left */
+    vehicle: number;
+}
+/**
+ * CEventShockingSeenPedKilled
+ * Fired when a ped witnesses another ped being killed
+ */
+export interface SeenPedKilledEvent {
+    /** Ped that witnessed the death */
+    witness: number;
+    /** Ped that was killed */
+    victim: number;
+}
+/**
+ * CEventGunShot
+ * Fired when a weapon is fired
+ */
+export interface GunShotEvent {
+    /** Entity that fired */
+    shooter: number;
+    /** Target coordinates */
+    coords: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/**
+ * CEventNetworkVehicleUndrivable
+ * Fired when a vehicle becomes undrivable (destroyed)
+ */
+export interface VehicleUndrivableEvent {
+    /** Vehicle that became undrivable */
+    vehicle: number;
+    /** Entity responsible (if any) */
+    attacker: number;
+    /** Weapon hash that caused it */
+    weaponHash: number;
+}
+export declare const GameEventParsers: {
+    /**
+     * Parse CEventNetworkEntityDamage arguments
+     */
+    parseEntityDamage(args: number[]): EntityDamageEvent;
+    /**
+     * Parse CEventNetworkPlayerEnteredVehicle arguments
+     */
+    parsePlayerEnteredVehicle(args: number[]): PlayerEnteredVehicleEvent;
+    /**
+     * Parse CEventNetworkPlayerLeftVehicle arguments
+     */
+    parsePlayerLeftVehicle(args: number[]): PlayerLeftVehicleEvent;
+    /**
+     * Parse CEventShockingSeenPedKilled arguments
+     */
+    parseSeenPedKilled(args: number[]): SeenPedKilledEvent;
+    /**
+     * Parse CEventNetworkVehicleUndrivable arguments
+     */
+    parseVehicleUndrivable(args: number[]): VehicleUndrivableEvent;
+    /**
+     * Parse CEventGunShot arguments
+     */
+    parseGunShot(args: number[]): GunShotEvent;
+};
+export interface GameEventMap {
+    CEventNetworkEntityDamage: EntityDamageEvent;
+    CEventNetworkPlayerEnteredVehicle: PlayerEnteredVehicleEvent;
+    CEventNetworkPlayerLeftVehicle: PlayerLeftVehicleEvent;
+    CEventShockingSeenPedKilled: SeenPedKilledEvent;
+    CEventNetworkVehicleUndrivable: VehicleUndrivableEvent;
+    CEventGunShot: GunShotEvent;
+    [key: string]: unknown;
+}

package/dist/client/types/game-events.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Game Events - Native GTA V internal events captured by FiveM
+ *
+ * Documentation: https://docs.fivem.net/docs/game-references/game-events/
+ *
+ * These are low-level events from the RAGE engine. The arguments are
+ * passed as arrays from the native layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameEventParsers = void 0;
+// ─────────────────────────────────────────────────────────────────────────────
+// Event Parsers - Convert raw args to typed objects
+// ─────────────────────────────────────────────────────────────────────────────
+exports.GameEventParsers = {
+    /**
+     * Parse CEventNetworkEntityDamage arguments
+     */
+    parseEntityDamage(args) {
+        return {
+            victim: args[0],
+            attacker: args[1],
+            arg2: args[2],
+            arg3: args[3],
+            arg4: args[4],
+            victimDied: args[5] === 1,
+            weaponHash: args[6],
+            arg7: args[7],
+            arg8: args[8],
+            arg9: args[9],
+        };
+    },
+    /**
+     * Parse CEventNetworkPlayerEnteredVehicle arguments
+     */
+    parsePlayerEnteredVehicle(args) {
+        return {
+            player: args[0],
+            vehicle: args[1],
+        };
+    },
+    /**
+     * Parse CEventNetworkPlayerLeftVehicle arguments
+     */
+    parsePlayerLeftVehicle(args) {
+        return {
+            player: args[0],
+            vehicle: args[1],
+        };
+    },
+    /**
+     * Parse CEventShockingSeenPedKilled arguments
+     */
+    parseSeenPedKilled(args) {
+        return {
+            witness: args[0],
+            victim: args[1],
+        };
+    },
+    /**
+     * Parse CEventNetworkVehicleUndrivable arguments
+     */
+    parseVehicleUndrivable(args) {
+        return {
+            vehicle: args[0],
+            attacker: args[1],
+            weaponHash: args[2],
+        };
+    },
+    /**
+     * Parse CEventGunShot arguments
+     */
+    parseGunShot(args) {
+        return {
+            shooter: args[0],
+            coords: {
+                x: args[1],
+                y: args[2],
+                z: args[3],
+            },
+        };
+    },
+};

package/dist/client/types/index.d.ts

@@ -0,0 +1 @@
+export * from './game-events';

package/dist/client/types/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./game-events"), exports);

package/dist/client/ui-bridge.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Type-safe NUI (Native UI) Bridge for client-server communication.
+ *
+ * Generic types allow for full type safety when sending/receiving messages.
+ * Define your event maps and pass them as type parameters.
+ *
+ * @example
+ * ```typescript
+ * interface ClientToUI {
+ *   'showMenu': { items: string[] }
+ *   'hideMenu': void
+ * }
+ *
+ * interface UIToClient {
+ *   'menuItemSelected': { index: number }
+ *   'menuClosed': void
+ * }
+ *
+ * const nui = new NuiBridge<ClientToUI, UIToClient>()
+ * nui.send('showMenu', { items: ['Option 1', 'Option 2'] })
+ * nui.on('menuItemSelected', async (data) => console.log(data.index))
+ * ```
+ */
+export declare class NuiBridge<TSend extends Record<string, any> = Record<string, any>, TReceive extends Record<string, any> = Record<string, any>> {
+    private _isVisible;
+    private _hasFocus;
+    private _hasCursor;
+    /**
+     * Whether the NUI frame is currently visible
+     */
+    get isVisible(): boolean;
+    /**
+     * Whether the NUI has input focus
+     */
+    get hasFocus(): boolean;
+    /**
+     * Whether the cursor is visible
+     */
+    get hasCursor(): boolean;
+    /**
+     * Send a message to the NUI (UI frame).
+     *
+     * @param action - The action/event name
+     * @param data - The data payload
+     */
+    send<K extends keyof TSend & string>(action: K, data: TSend[K]): void;
+    /**
+     * Send a raw message to the NUI without type checking.
+     *
+     * @param action - The action/event name
+     * @param data - The data payload
+     */
+    sendRaw(action: string, data: any): void;
+    /**
+     * Register a callback for NUI events from the UI.
+     *
+     * @param action - The action/event name to listen for
+     * @param handler - The callback handler
+     * @returns Cleanup function to unregister the callback
+     */
+    on<K extends keyof TReceive & string>(action: K, handler: (data: TReceive[K]) => void | Promise<void>): void;
+    /**
+     * Register a callback that expects a return value.
+     *
+     * @param action - The action/event name to listen for
+     * @param handler - The callback handler that returns data
+     */
+    onWithResponse<K extends keyof TReceive & string, R = any>(action: K, handler: (data: TReceive[K]) => R | Promise<R>): void;
+    /**
+     * Set NUI focus state.
+     *
+     * @param hasFocus - Whether the NUI should have input focus
+     * @param hasCursor - Whether to show the cursor (defaults to hasFocus value)
+     */
+    focus(hasFocus: boolean, hasCursor?: boolean): void;
+    /**
+     * Remove NUI focus (convenience method).
+     */
+    blur(): void;
+    /**
+     * Set NUI visibility state.
+     * Note: This only tracks state, you need to handle actual visibility in your UI.
+     *
+     * @param visible - Whether the NUI should be visible
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Show the NUI and optionally set focus.
+     *
+     * @param withFocus - Whether to also set focus
+     * @param withCursor - Whether to show cursor (defaults to withFocus)
+     */
+    show(withFocus?: boolean, withCursor?: boolean): void;
+    /**
+     * Hide the NUI and remove focus.
+     */
+    hide(): void;
+    /**
+     * Toggle NUI visibility.
+     *
+     * @param withFocus - Whether to set focus when showing
+     */
+    toggle(withFocus?: boolean): void;
+    /**
+     * Keep input focus but allow game input.
+     * Useful for HUDs that need to capture some keys but not all.
+     *
+     * @param keepInput - Whether to keep game input enabled
+     */
+    setKeepInput(keepInput: boolean): void;
+}
+/**
+ * Default untyped NUI instance for quick usage.
+ * For type-safe usage, create your own instance with proper generics.
+ */
+export declare const NUI: NuiBridge<Record<string, any>, Record<string, any>>;