@open-core/framework 0.1.0-alpha.1 → 0.2.1-beta.1

package/dist/runtime/client/client-core.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const client_bootstrap_1 = require("./client-bootstrap");
+/**
+ * Initialize the OpenCore client framework
+ *
+ * @param options - Client initialization options
+ *
+ * @example
+ * ```ts
+ * // Core resource (initializes all services)
+ * await Client.init({ mode: 'CORE' })
+ *
+ * // Resource mode (only registers controllers)
+ * await Client.init({ mode: 'RESOURCE' })
+ *
+ * // Standalone mode (only registers controllers)
+ * await Client.init({ mode: 'STANDALONE' })
+ * ```
+ */
+async function init(options = {}) {
+    await (0, client_bootstrap_1.initClientCore)(options);
+}

package/dist/runtime/client/client-runtime.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Client Runtime Configuration
+ *
+ * Defines initialization modes and configuration for the client-side framework.
+ */
+export type ClientMode = 'CORE' | 'RESOURCE' | 'STANDALONE';
+/**
+ * Client initialization options
+ *
+ * @remarks
+ * - **CORE**: Initializes all framework services (SpawnService, NotificationService, etc.)
+ *   and scans controllers. Should only be used by the main core resource.
+ *
+ * - **RESOURCE**: Only scans controllers from this resource. Does NOT initialize services.
+ *   Used when a resource extends the core with additional functionality.
+ *
+ * - **STANDALONE**: Same as RESOURCE - only scans controllers. Services must be registered
+ *   manually if needed. Use for independent resources or testing.
+ *
+ * @example
+ * ```ts
+ * // Core resource
+ * await Client.init({ mode: 'CORE' })
+ *
+ * // Chat resource (extends core)
+ * await Client.init({ mode: 'RESOURCE' })
+ * ```
+ */
+export interface ClientInitOptions {
+    /**
+     * The client initialization mode.
+     *
+     * Defaults to 'CORE' if not specified (for backwards compatibility).
+     */
+    mode?: ClientMode;
+}
+/**
+ * Client runtime context
+ */
+export interface ClientRuntimeContext {
+    mode: ClientMode;
+    resourceName: string;
+    isInitialized: boolean;
+}
+/**
+ * Get the current client runtime context
+ */
+export declare function getClientRuntimeContext(): ClientRuntimeContext | null;
+/**
+ * Set the client runtime context
+ *
+ * @internal
+ */
+export declare function setClientRuntimeContext(ctx: ClientRuntimeContext): void;
+/**
+ * Check if the client has been initialized
+ */
+export declare function isClientInitialized(): boolean;

package/dist/runtime/client/client-runtime.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Client Runtime Configuration
+ *
+ * Defines initialization modes and configuration for the client-side framework.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClientRuntimeContext = getClientRuntimeContext;
+exports.setClientRuntimeContext = setClientRuntimeContext;
+exports.isClientInitialized = isClientInitialized;
+let runtimeContext = null;
+/**
+ * Get the current client runtime context
+ */
+function getClientRuntimeContext() {
+    return runtimeContext;
+}
+/**
+ * Set the client runtime context
+ *
+ * @internal
+ */
+function setClientRuntimeContext(ctx) {
+    runtimeContext = ctx;
+}
+/**
+ * Check if the client has been initialized
+ */
+function isClientInitialized() {
+    var _a;
+    return (_a = runtimeContext === null || runtimeContext === void 0 ? void 0 : runtimeContext.isInitialized) !== null && _a !== void 0 ? _a : false;
+}

package/dist/runtime/client/controllers/appearance.controller.d.ts

@@ -0,0 +1,8 @@
+import { PlayerAppearance } from '../../../kernel/shared';
+import { AppearanceService } from '../services/appearance.service';
+export declare class AppearanceTestClientController {
+    private readonly appearanceService;
+    constructor(appearanceService: AppearanceService);
+    onApply(appearance: PlayerAppearance): Promise<void>;
+    onReset(): void;
+}

package/dist/runtime/client/controllers/appearance.controller.js

@@ -0,0 +1,50 @@
+"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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppearanceTestClientController = void 0;
+const tsyringe_1 = require("tsyringe");
+const decorators_1 = require("../decorators");
+const appearance_service_1 = require("../services/appearance.service");
+let AppearanceTestClientController = class AppearanceTestClientController {
+    constructor(appearanceService) {
+        this.appearanceService = appearanceService;
+    }
+    async onApply(appearance) {
+        const ped = PlayerPedId();
+        await this.appearanceService.applyAppearance(ped, appearance);
+    }
+    onReset() {
+        const ped = PlayerPedId();
+        this.appearanceService.setDefaultAppearance(ped);
+        this.appearanceService.clearTattoos(ped);
+    }
+};
+exports.AppearanceTestClientController = AppearanceTestClientController;
+__decorate([
+    (0, decorators_1.OnNet)('opencore:appearance:apply'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AppearanceTestClientController.prototype, "onApply", null);
+__decorate([
+    (0, decorators_1.OnNet)('opencore:appearance:reset'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], AppearanceTestClientController.prototype, "onReset", null);
+exports.AppearanceTestClientController = AppearanceTestClientController = __decorate([
+    (0, decorators_1.Controller)(),
+    __param(0, (0, tsyringe_1.inject)(appearance_service_1.AppearanceService)),
+    __metadata("design:paramtypes", [appearance_service_1.AppearanceService])
+], AppearanceTestClientController);

package/dist/runtime/client/controllers/player-sync.controller.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Client-side service that syncs player health and armor from server state bags.
+ *
+ * @remarks
+ * Listens to state bag changes from the server and applies them to the local player ped.
+ * This allows the server to control player health and armor through simple state bag updates.
+ */
+export declare class PlayerSyncController {
+    constructor();
+    private registerStateBagHandlers;
+}

package/dist/runtime/client/controllers/player-sync.controller.js

@@ -0,0 +1,54 @@
+"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.PlayerSyncController = void 0;
+const decorators_1 = require("../decorators");
+/**
+ * Client-side service that syncs player health and armor from server state bags.
+ *
+ * @remarks
+ * Listens to state bag changes from the server and applies them to the local player ped.
+ * This allows the server to control player health and armor through simple state bag updates.
+ */
+let PlayerSyncController = class PlayerSyncController {
+    constructor() {
+        this.registerStateBagHandlers();
+    }
+    registerStateBagHandlers() {
+        // Sync health from server state bag to local ped
+        AddStateBagChangeHandler('health', '', (bagName, _key, value) => {
+            const entity = GetEntityFromStateBagName(bagName);
+            if (entity === 0)
+                return;
+            const playerPed = PlayerPedId();
+            if (entity !== playerPed)
+                return;
+            // Apply health to local ped
+            SetEntityHealth(entity, value);
+        });
+        // Sync armor from server state bag to local ped
+        AddStateBagChangeHandler('armor', '', (bagName, _key, value) => {
+            const entity = GetEntityFromStateBagName(bagName);
+            if (entity === 0)
+                return;
+            const playerPed = PlayerPedId();
+            if (entity !== playerPed)
+                return;
+            // Apply armor to local ped
+            SetPedArmour(entity, value);
+        });
+    }
+};
+exports.PlayerSyncController = PlayerSyncController;
+exports.PlayerSyncController = PlayerSyncController = __decorate([
+    (0, decorators_1.Controller)(),
+    __metadata("design:paramtypes", [])
+], PlayerSyncController);

package/dist/{client → runtime/client}/controllers/spawner.controller.d.ts

@@ -1,4 +1,4 @@
-import { Vector3 } from '../../utils';
+import { Vector3 } from '../../../kernel/utils';
 import { SpawnService } from '../services';
 export declare class SpawnerController {
     private readonly spawnService;

package/dist/runtime/client/decorators/controller.d.ts

@@ -0,0 +1,20 @@
+import { ClassConstructor } from '../../../kernel/di/class-constructor';
+export declare function getClientControllerRegistry(resourceName?: string): ClassConstructor[];
+/**
+ * Marks a class as a Client Controller.
+ *
+ * @remarks
+ * This decorator:
+ * - Marks the class as `@injectable()` (tsyringe) for dependency injection.
+ * - Stores controller metadata identifying it as a `client` controller.
+ * - Adds the class to an internal registry so the runtime can discover it during bootstrap.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class HudController {
+ *   constructor(private readonly notifications: NotificationService) {}
+ * }
+ * ```
+ */
+export declare function Controller(): (target: ClassConstructor) => void;

package/dist/runtime/client/decorators/controller.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClientControllerRegistry = getClientControllerRegistry;
+exports.Controller = Controller;
+const tsyringe_1 = require("tsyringe");
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+const clientControllerRegistryByResource = new Map();
+function getCurrentResourceNameSafe() {
+    const fn = globalThis.GetCurrentResourceName;
+    if (typeof fn === 'function') {
+        const name = fn();
+        if (typeof name === 'string' && name.trim())
+            return name;
+    }
+    return 'default';
+}
+function getClientControllerRegistry(resourceName) {
+    const key = resourceName !== null && resourceName !== void 0 ? resourceName : getCurrentResourceNameSafe();
+    let registry = clientControllerRegistryByResource.get(key);
+    if (!registry) {
+        registry = new Set();
+        clientControllerRegistryByResource.set(key, registry);
+    }
+    return Array.from(registry);
+}
+/**
+ * Marks a class as a Client Controller.
+ *
+ * @remarks
+ * This decorator:
+ * - Marks the class as `@injectable()` (tsyringe) for dependency injection.
+ * - Stores controller metadata identifying it as a `client` controller.
+ * - Adds the class to an internal registry so the runtime can discover it during bootstrap.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class HudController {
+ *   constructor(private readonly notifications: NotificationService) {}
+ * }
+ * ```
+ */
+function Controller() {
+    return (target) => {
+        (0, tsyringe_1.injectable)()(target);
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.CONTROLLER, { type: 'client' }, target);
+        const key = getCurrentResourceNameSafe();
+        let registry = clientControllerRegistryByResource.get(key);
+        if (!registry) {
+            registry = new Set();
+            clientControllerRegistryByResource.set(key, registry);
+        }
+        registry.add(target);
+    };
+}

package/dist/runtime/client/decorators/export.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Exposes a method as a FiveM client export.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers the export so that
+ * other resources can call it via `exports['resourceName'][exportName](...)`.
+ *
+ * @param name - Optional export name. If omitted, the method name is used.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiExports {
+ *   @Client.Export('setHudVisible')
+ *   setHudVisible(visible: boolean) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Export(name?: string): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/export.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Export = Export;
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Exposes a method as a FiveM client export.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers the export so that
+ * other resources can call it via `exports['resourceName'][exportName](...)`.
+ *
+ * @param name - Optional export name. If omitted, the method name is used.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiExports {
+ *   @Client.Export('setHudVisible')
+ *   setHudVisible(visible: boolean) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function Export(name) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.EXPORT, { exportName: name || propertyKey }, target, propertyKey);
+    };
+}

package/dist/{client → runtime/client}/decorators/gameEvent.d.ts

@@ -1,4 +1,4 @@
-import type { GameEventName, GameEventMap } from '../types/game-events';
+import { GameEventMap, GameEventName } from '../types/game-events';
 /**
  * Decorator for handling native game events from the RAGE engine.
  *
@@ -44,4 +44,4 @@ export declare function OnGameEvent<K extends GameEventName>(eventName: K, optio
     autoParse?: boolean;
 }): (target: any, propertyKey: string) => void;
 export type { GameEventName, GameEventMap };
-export type { EntityDamageEvent, PlayerEnteredVehicleEvent, PlayerLeftVehicleEvent, SeenPedKilledEvent, VehicleUndrivableEvent, GunShotEvent, } from '../types/game-events';
+export type { EntityDamageEvent, GunShotEvent, PlayerEnteredVehicleEvent, PlayerLeftVehicleEvent, SeenPedKilledEvent, VehicleUndrivableEvent, } from '../types/game-events';

package/dist/runtime/client/decorators/interval.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Registers a method to be executed at a fixed interval (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework schedules the method
+ * using the configured interval.
+ *
+ * Unlike {@link Tick} (every frame), `@Interval()` runs at a slower, fixed cadence.
+ *
+ * @param ms - Interval in milliseconds between executions.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class SyncController {
+ *   @Client.Interval(1000)
+ *   syncOncePerSecond() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Interval(ms: number): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/interval.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Interval = Interval;
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Registers a method to be executed at a fixed interval (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework schedules the method
+ * using the configured interval.
+ *
+ * Unlike {@link Tick} (every frame), `@Interval()` runs at a slower, fixed cadence.
+ *
+ * @param ms - Interval in milliseconds between executions.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class SyncController {
+ *   @Client.Interval(1000)
+ *   syncOncePerSecond() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function Interval(ms) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.INTERVAL, { interval: ms }, target, propertyKey);
+    };
+}

package/dist/runtime/client/decorators/key.d.ts

@@ -0,0 +1,23 @@
+import 'reflect-metadata';
+/**
+ * Registers a method as a key mapping handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers key mappings
+ * and binds the decorated method to the configured key.
+ *
+ * @param key - Key identifier (depends on the key-mapping layer used by the runtime).
+ * @param description - Human-friendly description (typically used in key mapping UIs).
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class InteractionController {
+ *   @Client.KeyMapping('E', 'Interact')
+ *   interact() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function KeyMapping(key: string, description: string): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/key.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyMapping = KeyMapping;
+require("reflect-metadata");
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Registers a method as a key mapping handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers key mappings
+ * and binds the decorated method to the configured key.
+ *
+ * @param key - Key identifier (depends on the key-mapping layer used by the runtime).
+ * @param description - Human-friendly description (typically used in key mapping UIs).
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class InteractionController {
+ *   @Client.KeyMapping('E', 'Interact')
+ *   interact() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function KeyMapping(key, description) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.KEY, { key, description }, target, propertyKey);
+    };
+}

package/dist/runtime/client/decorators/localEvent.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Registers a method as a listener for a local (non-networked) client event.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * local event name.
+ *
+ * @param eventName - Local event name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiController {
+ *   @Client.OnLocalEvent('ui:toggle')
+ *   toggleUi() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnLocalEvent(eventName: string): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/localEvent.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnLocalEvent = OnLocalEvent;
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Registers a method as a listener for a local (non-networked) client event.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * local event name.
+ *
+ * @param eventName - Local event name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiController {
+ *   @Client.OnLocalEvent('ui:toggle')
+ *   toggleUi() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function OnLocalEvent(eventName) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.LOCAL_EVENT, { eventName }, target, propertyKey);
+    };
+}

package/dist/runtime/client/decorators/nui.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Registers a method as an NUI callback handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the decorated method
+ * to the NUI callback event name.
+ *
+ * @param eventName - NUI callback name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class SettingsController {
+ *   @Client.NuiCallback('settings:save')
+ *   saveSettings(payload: unknown) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function NuiCallback(eventName: string): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/nui.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NuiCallback = NuiCallback;
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Registers a method as an NUI callback handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the decorated method
+ * to the NUI callback event name.
+ *
+ * @param eventName - NUI callback name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class SettingsController {
+ *   @Client.NuiCallback('settings:save')
+ *   saveSettings(payload: unknown) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function NuiCallback(eventName) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.NUI, { eventName }, target, propertyKey);
+    };
+}

package/dist/runtime/client/decorators/onNet.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Registers a method as a client-side network event handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework scans controller methods
+ * and binds them to client net events.
+ *
+ * @param eventName - Network event name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiController {
+ *   @Client.OnNet('ui:setVisible')
+ *   setVisible(isVisible: boolean) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnNet(eventName: string): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/onNet.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnNet = OnNet;
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Registers a method as a client-side network event handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework scans controller methods
+ * and binds them to client net events.
+ *
+ * @param eventName - Network event name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiController {
+ *   @Client.OnNet('ui:setVisible')
+ *   setVisible(isVisible: boolean) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function OnNet(eventName) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.NET_EVENT, { eventName }, target, propertyKey);
+    };
+}