@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

package/dist/kernel/utils/rgb.d.ts

@@ -0,0 +1,17 @@
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+export declare const RED: RGB;
+export declare const GREEN: RGB;
+export declare const BLUE: RGB;
+export declare const WHITE: RGB;
+export declare const BLACK: RGB;
+export declare const GRAY: RGB;
+export declare const YELLOW: RGB;
+export declare const CYAN: RGB;
+export declare const MAGENTA: RGB;
+export declare const ORANGE: RGB;
+export declare const PURPLE: RGB;
+export declare const PINK: RGB;

package/dist/kernel/utils/rgb.js

@@ -0,0 +1,61 @@
+// Common Colors //
+export const RED = {
+    r: 255,
+    g: 0,
+    b: 0,
+};
+export const GREEN = {
+    r: 0,
+    g: 255,
+    b: 0,
+};
+export const BLUE = {
+    r: 0,
+    g: 0,
+    b: 255,
+};
+export const WHITE = {
+    r: 255,
+    g: 255,
+    b: 255,
+};
+export const BLACK = {
+    r: 0,
+    g: 0,
+    b: 0,
+};
+export const GRAY = {
+    r: 128,
+    g: 128,
+    b: 128,
+};
+export const YELLOW = {
+    r: 255,
+    g: 255,
+    b: 0,
+};
+export const CYAN = {
+    r: 0,
+    g: 255,
+    b: 255,
+};
+export const MAGENTA = {
+    r: 255,
+    g: 0,
+    b: 255,
+};
+export const ORANGE = {
+    r: 255,
+    g: 165,
+    b: 0,
+};
+export const PURPLE = {
+    r: 128,
+    g: 0,
+    b: 128,
+};
+export const PINK = {
+    r: 255,
+    g: 192,
+    b: 203,
+};

package/dist/kernel/utils/vector3.d.ts

@@ -0,0 +1,14 @@
+export type Vector3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare class Vec3 {
+    private constructor();
+    static create(x: number, y: number, z: number): Vector3;
+    static clone(v: Vector3): Vector3;
+    static add(a: Vector3, b: Vector3): Vector3;
+    static sub(a: Vector3, b: Vector3): Vector3;
+    static distance(a: Vector3, b: Vector3): number;
+    static equals(a: Vector3, b: Vector3): boolean;
+}

package/dist/kernel/utils/vector3.js

@@ -0,0 +1,24 @@
+export class Vec3 {
+    constructor() { }
+    static create(x, y, z) {
+        return { x, y, z };
+    }
+    static clone(v) {
+        return { x: v.x, y: v.y, z: v.z };
+    }
+    static add(a, b) {
+        return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+    }
+    static sub(a, b) {
+        return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+    }
+    static distance(a, b) {
+        const dx = a.x - b.x;
+        const dy = a.y - b.y;
+        const dz = a.z - b.z;
+        return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    static equals(a, b) {
+        return a.x === b.x && a.y === b.y && a.z === b.z;
+    }
+}

package/dist/runtime/client/.opencore/autoload.client.controllers.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,8 @@
+export * from './client-core';
+export * from './client-runtime';
+export * from './decorators';
+export * from './library';
+export * from './player/player';
+export * from './services';
+export * from './types';
+export * from './ui-bridge';

package/dist/runtime/client/api.js

@@ -0,0 +1,8 @@
+export * from './client-core';
+export * from './client-runtime';
+export * from './decorators';
+export * from './library';
+export * from './player/player';
+export * from './services';
+export * from './types';
+export * from './ui-bridge';

package/dist/runtime/client/bus/library-event.bus.d.ts

@@ -0,0 +1,5 @@
+import { LibraryEventEnvelope, LibraryEventId } from '../../core/library/types';
+type LibraryEventHandler = (event: LibraryEventEnvelope) => void | Promise<void>;
+export declare function onLibraryEvent(eventId: LibraryEventId, handler: LibraryEventHandler): () => void;
+export declare function emitLibraryEvent(eventId: LibraryEventId, event: LibraryEventEnvelope): void;
+export {};

package/dist/runtime/client/bus/library-event.bus.js

@@ -0,0 +1,28 @@
+import { coreLogger, LogDomain } from '../../../kernel/logger';
+const handlers = new Map();
+const libraryEventLogger = coreLogger.child('LibraryEvent', LogDomain.CLIENT);
+export function onLibraryEvent(eventId, handler) {
+    const eventHandlers = handlers.get(eventId) ?? new Set();
+    eventHandlers.add(handler);
+    handlers.set(eventId, eventHandlers);
+    return () => {
+        const current = handlers.get(eventId);
+        if (!current)
+            return;
+        current.delete(handler);
+        if (current.size === 0)
+            handlers.delete(eventId);
+    };
+}
+export function emitLibraryEvent(eventId, event) {
+    const eventHandlers = handlers.get(eventId);
+    if (!eventHandlers || eventHandlers.size === 0)
+        return;
+    for (const handler of [...eventHandlers]) {
+        Promise.resolve(handler(event)).catch((error) => {
+            libraryEventLogger.error(`Handler error in library event`, {
+                eventId,
+            }, error);
+        });
+    }
+}

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

@@ -0,0 +1,7 @@
+import * as BaseClientApi from './api';
+import type { ClientPluginApi } from './library/plugin/client-plugin-api';
+export type ClientApi = typeof BaseClientApi & ClientPluginApi & {
+    registerApiExtension(key: string, value: unknown): void;
+};
+export declare function createClientRuntime(): ClientApi;
+export declare const Client: ClientApi;

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

@@ -0,0 +1,34 @@
+import * as BaseClientApi from './api';
+const RESERVED_CLIENT_API_KEYS = new Set([
+    'registerApiExtension',
+    '__proto__',
+    'prototype',
+    'constructor',
+]);
+function assertExtensionKey(key) {
+    if (!key || key.trim().length === 0) {
+        throw new Error('Client API extension key must be a non-empty string');
+    }
+    if (RESERVED_CLIENT_API_KEYS.has(key)) {
+        throw new Error(`Client API extension key "${key}" is reserved`);
+    }
+}
+function attachApiExtensionRuntime(runtime) {
+    const dynamicApi = {};
+    runtime.registerApiExtension = (key, value) => {
+        assertExtensionKey(key);
+        if (Object.hasOwn(dynamicApi, key) || key in runtime) {
+            throw new Error(`Client API "${key}" already registered`);
+        }
+        dynamicApi[key] = value;
+        runtime[key] = value;
+    };
+    return runtime;
+}
+export function createClientRuntime() {
+    const runtime = {
+        ...BaseClientApi,
+    };
+    return attachApiExtensionRuntime(runtime);
+}
+export const Client = attachApiExtensionRuntime(BaseClientApi);

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

@@ -0,0 +1,7 @@
+import { type ClientInitOptions } from './client-runtime';
+/**
+ * Initialize the client core framework
+ *
+ * @param options - Client initialization options
+ */
+export declare function initClientCore(options?: ClientInitOptions): Promise<void>;

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

@@ -0,0 +1,160 @@
+import { registerClientCapabilities } from '../../adapters/register-client-capabilities';
+import { MetadataScanner } from '../../kernel/di/metadata.scanner';
+import { loggers } from '../../kernel/logger';
+import { di } from './client-container';
+import { getClientRuntimeContext, setClientRuntimeContext, } from './client-runtime';
+import { getClientControllerRegistry } from './decorators';
+import { playerClientLoader } from './player/player.loader';
+import { BlipService, Camera, CameraEffectsRegistry, Cinematic, MarkerService, NotificationService, PedService, ProgressService, SpawnService, StreamingService, TextUIService, VehicleClientService, VehicleService, } from './services';
+import { registerSystemClient } from './system/processors.register';
+import { NuiBridge } from './ui-bridge';
+/**
+ * Services that have an init() method which registers global runtime event listeners.
+ *
+ * These services are:
+ * - Registered in DI for ALL modes (so they can be injected and used)
+ * - Only initialized (.init() called) in CORE mode to avoid duplicate event handlers
+ */
+const SERVICES_WITH_GLOBAL_LISTENERS = [SpawnService];
+/**
+ * All client services that should be available in the DI container
+ */
+// const ALL_CLIENT_SERVICES = [
+//   SpawnService,
+//   NuiBridge,
+//   NotificationService,
+//   TextUIService,
+//   ProgressService,
+//   MarkerService,
+//   BlipService,
+//   VehicleClientService,
+//   VehicleService,
+//   PedService,
+//   StreamingService,
+// ] as const
+/**
+ * Get current resource name safely
+ */
+function getCurrentResourceNameSafe() {
+    const fn = globalThis.GetCurrentResourceName;
+    if (typeof fn === 'function') {
+        const name = fn();
+        if (typeof name === 'string' && name.trim())
+            return name;
+    }
+    return 'default';
+}
+/**
+ * Register singleton services in the DI container
+ *
+ * @remarks
+ * All services are registered in ALL modes so they can be injected and used.
+ * However, only CORE mode will call .init() on services with global listeners.
+ */
+function registerServices() {
+    // Register all client services in DI (available in all modes)
+    di.registerSingleton(SpawnService, SpawnService);
+    di.registerSingleton(NuiBridge, NuiBridge);
+    di.registerSingleton(NotificationService, NotificationService);
+    di.registerSingleton(TextUIService, TextUIService);
+    di.registerSingleton(ProgressService, ProgressService);
+    di.registerSingleton(MarkerService, MarkerService);
+    di.registerSingleton(BlipService, BlipService);
+    di.registerSingleton(Camera, Camera);
+    di.registerSingleton(CameraEffectsRegistry, CameraEffectsRegistry);
+    di.registerSingleton(Cinematic, Cinematic);
+    di.registerSingleton(VehicleClientService, VehicleClientService);
+    di.registerSingleton(VehicleService, VehicleService);
+    di.registerSingleton(PedService, PedService);
+    di.registerSingleton(StreamingService, StreamingService);
+}
+/**
+ * Bootstrap services that need initialization
+ *
+ * @remarks
+ * Only called in CORE mode to initialize services that register global event listeners.
+ * This prevents duplicate event handlers when multiple resources use the framework.
+ *
+ * @param mode - The client initialization mode
+ */
+async function bootstrapServices(mode) {
+    if (mode === 'CORE') {
+        // Initialize services with global listeners (only in CORE mode)
+        for (const Service of SERVICES_WITH_GLOBAL_LISTENERS) {
+            const instance = di.resolve(Service);
+            if (typeof instance.init === 'function') {
+                await instance.init();
+            }
+        }
+        // Instantiate VehicleClientService to register its event handlers
+        di.resolve(VehicleClientService);
+    }
+}
+async function tryImportAutoLoad() {
+    try {
+        await import('./.opencore/autoload.client.controllers');
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes('Cannot find module')) {
+            loggers.bootstrap.debug(`[Bootstrap] No client controllers autoload file found, skipping.`);
+            return;
+        }
+        throw err;
+    }
+}
+/**
+ * Initialize the client core framework
+ *
+ * @param options - Client initialization options
+ */
+export async function initClientCore(options = {}) {
+    const mode = options.mode ?? 'CORE';
+    const resourceName = getCurrentResourceNameSafe();
+    // Register system processors early (needed for MetadataScanner)
+    // These processors are safe - they just process metadata, they don't register event handlers
+    // Each resource bundle needs its own copy registered in its DI container
+    registerSystemClient();
+    // Check if already initialized
+    const existingContext = getClientRuntimeContext();
+    if (existingContext?.isInitialized) {
+        // If already initialized, only scan controllers for this resource
+        if (mode === 'RESOURCE' || mode === 'STANDALONE') {
+            await tryImportAutoLoad();
+            const scanner = di.resolve(MetadataScanner);
+            scanner.scan(getClientControllerRegistry(resourceName));
+            loggers.bootstrap.info(`Resource "${resourceName}" controllers registered`);
+            return;
+        }
+        // If trying to initialize CORE mode twice, throw error
+        throw new Error(`Client already initialized in ${existingContext.mode} mode by resource "${existingContext.resourceName}". Cannot initialize again in ${mode} mode.`);
+    }
+    // Set runtime context
+    setClientRuntimeContext({
+        mode,
+        resourceName,
+        isInitialized: true,
+    });
+    // Register client-side adapters (IPedAppearanceClient, IHasher)
+    await registerClientCapabilities();
+    // Register all services in DI (available in all modes)
+    registerServices();
+    // Bootstrap services (only in CORE mode)
+    // This is where services that register global event handlers are initialized
+    await bootstrapServices(mode);
+    // Player loader (only in CORE mode)
+    if (mode === 'CORE') {
+        playerClientLoader();
+    }
+    // Import framework controllers (only in CORE mode)
+    // These controllers listen to global events and should only be registered once
+    if (mode === 'CORE') {
+        await import('./controllers/spawner.controller');
+        await import('./controllers/appearance.controller');
+        await import('./controllers/player-sync.controller');
+    }
+    await tryImportAutoLoad();
+    // Scan and register controllers
+    const scanner = di.resolve(MetadataScanner);
+    scanner.scan(getClientControllerRegistry(resourceName));
+    loggers.bootstrap.info(`Client initialized in ${mode} mode`, { resourceName });
+}

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

@@ -0,0 +1,3 @@
+import 'reflect-metadata';
+import { container } from 'tsyringe';
+export const di = container;

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

@@ -0,0 +1,19 @@
+import { ClientInitOptions } from './client-runtime';
+/**
+ * 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' })
+ * ```
+ */
+export declare function init(options?: ClientInitOptions): Promise<void>;

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

@@ -0,0 +1,23 @@
+import { initClientCore } from './client-bootstrap';
+import { installClientPlugins } from './library/plugin/install-client-plugins';
+/**
+ * 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' })
+ * ```
+ */
+export async function init(options = {}) {
+    await installClientPlugins(options.plugins ?? [], options);
+    await initClientCore(options);
+}

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

@@ -0,0 +1,63 @@
+import type { OpenCoreClientPlugin } from './library/plugin';
+/**
+ * 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;
+    /**
+     * Optional client plugins installed before bootstrap.
+     */
+    plugins?: OpenCoreClientPlugin[];
+}
+/**
+ * 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,21 @@
+let runtimeContext = null;
+/**
+ * Get the current client runtime context
+ */
+export function getClientRuntimeContext() {
+    return runtimeContext;
+}
+/**
+ * Set the client runtime context
+ *
+ * @internal
+ */
+export function setClientRuntimeContext(ctx) {
+    runtimeContext = ctx;
+}
+/**
+ * Check if the client has been initialized
+ */
+export function isClientInitialized() {
+    return runtimeContext?.isInitialized ?? 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,48 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject } from 'tsyringe';
+import { Controller, OnNet } from '../decorators';
+import { AppearanceService } from '../services/appearance.service';
+let AppearanceTestClientController = class AppearanceTestClientController {
+    appearanceService;
+    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);
+    }
+};
+__decorate([
+    OnNet('opencore:appearance:apply'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AppearanceTestClientController.prototype, "onApply", null);
+__decorate([
+    OnNet('opencore:appearance:reset'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], AppearanceTestClientController.prototype, "onReset", null);
+AppearanceTestClientController = __decorate([
+    Controller(),
+    __param(0, inject(AppearanceService)),
+    __metadata("design:paramtypes", [AppearanceService])
+], AppearanceTestClientController);
+export { 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,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 { Controller } from '../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);
+        });
+    }
+};
+PlayerSyncController = __decorate([
+    Controller(),
+    __metadata("design:paramtypes", [])
+], PlayerSyncController);
+export { PlayerSyncController };

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

@@ -0,0 +1,12 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+import { SpawnService } from '../services';
+export declare class SpawnerController {
+    private readonly spawnService;
+    constructor(spawnService: SpawnService);
+    handleSpawn(data: {
+        position: Vector3;
+        model: string;
+    }): Promise<void>;
+    handleRespawn(position: Vector3, heading?: number): Promise<void>;
+    handleTeleport(position: Vector3, heading?: number): Promise<void>;
+}