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

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

@@ -0,0 +1,51 @@
+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);
+};
+import { loggers } from '../../../kernel/logger';
+import { Controller, OnNet } from '../decorators';
+import { SpawnService } from '../services';
+let SpawnerController = class SpawnerController {
+    spawnService;
+    constructor(spawnService) {
+        this.spawnService = spawnService;
+    }
+    async handleSpawn(data) {
+        loggers.spawn.debug('Spawn event received', data);
+        await this.spawnService.spawn(data.position, data.model);
+    }
+    async handleRespawn(position, heading = 0.0) {
+        await this.spawnService.respawn(position, heading);
+    }
+    async handleTeleport(position, heading) {
+        await this.spawnService.teleportTo(position, heading);
+    }
+};
+__decorate([
+    OnNet('opencore:spawner:spawn'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SpawnerController.prototype, "handleSpawn", null);
+__decorate([
+    OnNet('opencore:spawner:respawn'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], SpawnerController.prototype, "handleRespawn", null);
+__decorate([
+    OnNet('opencore:spawner:teleport'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Number]),
+    __metadata("design:returntype", Promise)
+], SpawnerController.prototype, "handleTeleport", null);
+SpawnerController = __decorate([
+    Controller(),
+    __metadata("design:paramtypes", [SpawnService])
+], SpawnerController);
+export { SpawnerController };

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,54 @@
+import { injectable } from 'tsyringe';
+import { getCurrentClientResourceName } from '../adapter/registry';
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+import { getClientRuntimeContext } from '../client-runtime';
+const clientControllerRegistryByResource = new Map();
+function resolveRegistryKey(resourceName) {
+    if (resourceName?.trim()) {
+        return resourceName;
+    }
+    const runtime = getClientRuntimeContext();
+    if (runtime?.resourceName?.trim()) {
+        return runtime.resourceName;
+    }
+    return getCurrentClientResourceName();
+}
+export function getClientControllerRegistry(resourceName) {
+    const key = resolveRegistryKey(resourceName);
+    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) {}
+ * }
+ * ```
+ */
+export function Controller() {
+    return (target) => {
+        injectable()(target);
+        Reflect.defineMetadata(METADATA_KEYS.CONTROLLER, { type: 'client' }, target);
+        const key = resolveRegistryKey();
+        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,26 @@
+import { METADATA_KEYS } from '../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) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function Export(name) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.EXPORT, { exportName: name || propertyKey }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,47 @@
+import { GameEventMap, GameEventName } from '../types/game-events';
+/**
+ * Decorator for handling native game events from the RAGE engine.
+ *
+ * These are low-level events triggered internally by GTA V.
+ * FiveM captures them via the 'gameEventTriggered' event.
+ *
+ * **Documentation:** https://docs.fivem.net/docs/game-references/game-events/
+ *
+ * ## Common Events:
+ *
+ * | Event | Description |
+ * |-------|-------------|
+ * | `CEventNetworkEntityDamage` | Entity receives damage |
+ * | `CEventNetworkPlayerEnteredVehicle` | Player enters vehicle |
+ * | `CEventNetworkPlayerLeftVehicle` | Player exits vehicle |
+ * | `CEventNetworkVehicleUndrivable` | Vehicle destroyed |
+ * | `CEventShockingSeenPedKilled` | Ped witnesses death |
+ * | `CEventGunShot` | Weapon fired |
+ *
+ * ## Usage:
+ *
+ * ```typescript
+ * @Controller()
+ * class CombatController {
+ *   // Raw args (array)
+ *   @OnGameEvent('CEventNetworkEntityDamage')
+ *   onDamage(args: number[]) {
+ *     const [victim, attacker] = args
+ *   }
+ *
+ *   // Or with auto-parsing (set autoParse: true)
+ *   @OnGameEvent('CEventNetworkEntityDamage', { autoParse: true })
+ *   onDamageParsed(data: EntityDamageEvent) {
+ *     console.log(data.victim, data.attacker, data.victimDied)
+ *   }
+ * }
+ * ```
+ *
+ * @param eventName - The native game event name (CEvent*)
+ * @param options - Optional configuration
+ */
+export declare function OnGameEvent<K extends GameEventName>(eventName: K, options?: {
+    autoParse?: boolean;
+}): (target: any, propertyKey: string) => void;
+export type { GameEventName, GameEventMap };
+export type { EntityDamageEvent, GunShotEvent, PlayerEnteredVehicleEvent, PlayerLeftVehicleEvent, SeenPedKilledEvent, VehicleUndrivableEvent, } from '../types/game-events';

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

@@ -0,0 +1,50 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Decorator for handling native game events from the RAGE engine.
+ *
+ * These are low-level events triggered internally by GTA V.
+ * FiveM captures them via the 'gameEventTriggered' event.
+ *
+ * **Documentation:** https://docs.fivem.net/docs/game-references/game-events/
+ *
+ * ## Common Events:
+ *
+ * | Event | Description |
+ * |-------|-------------|
+ * | `CEventNetworkEntityDamage` | Entity receives damage |
+ * | `CEventNetworkPlayerEnteredVehicle` | Player enters vehicle |
+ * | `CEventNetworkPlayerLeftVehicle` | Player exits vehicle |
+ * | `CEventNetworkVehicleUndrivable` | Vehicle destroyed |
+ * | `CEventShockingSeenPedKilled` | Ped witnesses death |
+ * | `CEventGunShot` | Weapon fired |
+ *
+ * ## Usage:
+ *
+ * ```typescript
+ * @Controller()
+ * class CombatController {
+ *   // Raw args (array)
+ *   @OnGameEvent('CEventNetworkEntityDamage')
+ *   onDamage(args: number[]) {
+ *     const [victim, attacker] = args
+ *   }
+ *
+ *   // Or with auto-parsing (set autoParse: true)
+ *   @OnGameEvent('CEventNetworkEntityDamage', { autoParse: true })
+ *   onDamageParsed(data: EntityDamageEvent) {
+ *     console.log(data.victim, data.attacker, data.victimDied)
+ *   }
+ * }
+ * ```
+ *
+ * @param eventName - The native game event name (CEvent*)
+ * @param options - Optional configuration
+ */
+export function OnGameEvent(eventName, options) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.GAME_EVENT, {
+            eventName,
+            autoParse: options?.autoParse ?? false,
+        }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,13 @@
+export * from './controller';
+export * from './export';
+export * from './gameEvent';
+export * from './interval';
+export * from './key';
+export * from './localEvent';
+export * from './onLibraryEvent';
+export * from './onRPC';
+export * from './onNet';
+export * from './onTick';
+export * from './onView';
+export * from './resourceLifecycle';
+export * from './onRPC';

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

@@ -0,0 +1,13 @@
+export * from './controller';
+export * from './export';
+export * from './gameEvent';
+export * from './interval';
+export * from './key';
+export * from './localEvent';
+export * from './onLibraryEvent';
+export * from './onRPC';
+export * from './onNet';
+export * from './onTick';
+export * from './onView';
+export * from './resourceLifecycle';
+export * from './onRPC';

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,28 @@
+import { METADATA_KEYS } from '../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() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function Interval(ms) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(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.Key('E', 'Interact')
+ *   interact() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Key(key: string, description?: string): (target: any, propertyKey: string) => void;

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

@@ -0,0 +1,28 @@
+import 'reflect-metadata';
+import { METADATA_KEYS } from '../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.Key('E', 'Interact')
+ *   interact() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function Key(key, description) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(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 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,26 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method as a listener for a local 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 function OnLocalEvent(eventName) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.LOCAL_EVENT, { eventName }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,17 @@
+import { LibraryEventName, LibraryName } from '../../core/library/types';
+export interface LibraryEventDecoratorMetadata {
+    libraryName: LibraryName;
+    eventName: LibraryEventName;
+    eventId: string;
+}
+/**
+ * Registers a method as a listener for a runtime library event.
+ *
+ * @remarks
+ * The event is emitted when a library wrapper calls `library.emit(...)`.
+ * This decorator stores metadata only; listeners are bound during bootstrap.
+ *
+ * @param libraryName - Library identifier (for example: `characters`).
+ * @param eventName - Event name emitted by the library (for example: `session:created`).
+ */
+export declare function OnLibraryEvent(libraryName: LibraryName, eventName: LibraryEventName): (target: object, propertyKey: string | symbol) => void;

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

@@ -0,0 +1,22 @@
+import { buildLibraryEventId } from '../../core/library';
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method as a listener for a runtime library event.
+ *
+ * @remarks
+ * The event is emitted when a library wrapper calls `library.emit(...)`.
+ * This decorator stores metadata only; listeners are bound during bootstrap.
+ *
+ * @param libraryName - Library identifier (for example: `characters`).
+ * @param eventName - Event name emitted by the library (for example: `session:created`).
+ */
+export function OnLibraryEvent(libraryName, eventName) {
+    return (target, propertyKey) => {
+        const metadata = {
+            libraryName,
+            eventName,
+            eventId: buildLibraryEventId(libraryName, eventName),
+        };
+        Reflect.defineMetadata(METADATA_KEYS.LIBRARY_EVENT, metadata, 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,26 @@
+import { METADATA_KEYS } from '../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) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnNet(eventName) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.NET_EVENT, { eventName }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,41 @@
+import z from 'zod';
+export type ClientRpcHandlerOptions = {
+    eventName: string;
+    schema?: z.ZodType;
+    paramTypes?: unknown[];
+};
+type ClientNetHandlerRPC<TArgs extends any[] = any[], TResult = any> = (...args: TArgs) => TResult | Promise<TResult>;
+type ClientRpcHandlerSignatureError = '❌ @Client.OnRPC handlers must be async and return a Promise';
+type EnsureValidClientRpcHandler<T> = T extends (...args: any[]) => Promise<any> ? T : ClientRpcHandlerSignatureError;
+/**
+ * Registers a method as a client-side RPC handler.
+ *
+ * @remarks
+ * Client-only decorator.
+ *
+ * This decorator is the client counterpart of the server-only `@OnRPC` decorator.
+ *
+ * - Client: the handler can be called by the server.
+ *
+ * This decorator only stores metadata. During bootstrap, the framework scans controller methods
+ * and binds them using `RpcAPI.on()`.
+ *
+ * ## Handler signature
+ * The handler receives only the RPC payload args (no `Player`).
+ *
+ * ## Validation
+ * Pass a Zod schema to validate incoming args.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiRpcController {
+ *   @Client.OnRPC('ui:ping')
+ *   async ping() {
+ *     return 'pong'
+ *   }
+ * }
+ * ```
+ */
+export declare function OnRPC<TArgs extends any[], TResult = any>(eventName: string, schemaOrOptions?: z.ZodType | Pick<ClientRpcHandlerOptions, 'schema'>): <H extends EnsureValidClientRpcHandler<ClientNetHandlerRPC<TArgs, TResult>>>(target: any, propertyKey: string, _descriptor: TypedPropertyDescriptor<H>) => void;
+export {};

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

@@ -0,0 +1,40 @@
+import z from 'zod';
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method as a client-side RPC handler.
+ *
+ * @remarks
+ * Client-only decorator.
+ *
+ * This decorator is the client counterpart of the server-only `@OnRPC` decorator.
+ *
+ * - Client: the handler can be called by the server.
+ *
+ * This decorator only stores metadata. During bootstrap, the framework scans controller methods
+ * and binds them using `RpcAPI.on()`.
+ *
+ * ## Handler signature
+ * The handler receives only the RPC payload args (no `Player`).
+ *
+ * ## Validation
+ * Pass a Zod schema to validate incoming args.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class UiRpcController {
+ *   @Client.OnRPC('ui:ping')
+ *   async ping() {
+ *     return 'pong'
+ *   }
+ * }
+ * ```
+ */
+export function OnRPC(eventName, schemaOrOptions) {
+    return (target, propertyKey, _descriptor) => {
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+        const schema = schemaOrOptions instanceof z.ZodType ? schemaOrOptions : schemaOrOptions?.schema;
+        const metadata = { eventName, schema, paramTypes };
+        Reflect.defineMetadata(METADATA_KEYS.NET_RPC, metadata, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Registers a method to be executed on every client frame.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds tick handlers to the
+ * client tick loop.
+ *
+ * Tick handlers should be lightweight and non-blocking.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class HudController {
+ *   @Client.Tick()
+ *   updateHud() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function onTick(): (target: any, propertyKey: string) => void;