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

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

@@ -0,0 +1,26 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * 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 function onTick() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.TICK, {}, target, propertyKey);
+    };
+}

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

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

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

@@ -0,0 +1,26 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method as an onView callback handler. View are equal to NUI
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the decorated method
+ * to the NUI callback event name.
+ *
+ * @param eventName - onView callback name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class SettingsController {
+ *   @Client.onView('settings:save')
+ *   saveSettings(payload: unknown) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnView(eventName) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.VIEW, { eventName }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Registers a method to be called when the current resource starts (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStart()
+ *   onStart() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnResourceStart(): (target: any, propertyKey: string) => void;
+/**
+ * Registers a method to be called when the current resource is stopping (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * Use this for cleanup operations.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStop()
+ *   onStop() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnResourceStop(): (target: any, propertyKey: string) => void;

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

@@ -0,0 +1,49 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method to be called when the current resource starts (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStart()
+ *   onStart() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnResourceStart() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.RESOURCE_START, {}, target, propertyKey);
+    };
+}
+/**
+ * Registers a method to be called when the current resource is stopping (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * Use this for cleanup operations.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStop()
+ *   onStop() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnResourceStop() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.RESOURCE_STOP, {}, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,4 @@
+export * from './api';
+export { Client, createClientRuntime } from './client-api-runtime';
+export type { ClientApi } from './client-api-runtime';
+export type { ClientPluginApi, OpenCoreClientPlugin, PluginInstallContext as ClientPluginInstallContext, } from './library/plugin';

package/dist/runtime/client/index.js

@@ -0,0 +1,2 @@
+export * from './api';
+export { Client, createClientRuntime } from './client-api-runtime';

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

@@ -0,0 +1,13 @@
+import { OpenCoreClientLibrary } from '../../core/library/types';
+/**
+ * Creates a client-side OpenCore library wrapper.
+ *
+ * @remarks
+ * - Internal events use the local in-memory library bus.
+ * - `emitServer` sends a namespaced net event to server following
+ *   `opencore:<libName>:<eventName>` (or custom namespace).
+ * - For request/response patterns, prefer RPC.
+ */
+export declare function createClientLibrary(name: string, opts?: {
+    namespace?: string;
+}): OpenCoreClientLibrary;

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

@@ -0,0 +1,45 @@
+import { coreLogger } from '../../../kernel/logger';
+import { buildLibraryEventId, createLibraryBase, createLibraryConfigAccessor, } from '../../core/library';
+import { emitLibraryEvent } from '../bus/library-event.bus';
+/**
+ * Creates a client-side OpenCore library wrapper.
+ *
+ * @remarks
+ * - Internal events use the local in-memory library bus.
+ * - `emitServer` sends a namespaced net event to server following
+ *   `opencore:<libName>:<eventName>` (or custom namespace).
+ * - For request/response patterns, prefer RPC.
+ */
+export function createClientLibrary(name, opts) {
+    const base = createLibraryBase(name, opts);
+    const logger = coreLogger.client(`Library:${base.name}`);
+    const emitInternal = base.emit;
+    return {
+        ...base,
+        side: 'client',
+        emit(eventName, payload) {
+            emitInternal(eventName, payload);
+            const eventId = buildLibraryEventId(base.name, eventName);
+            const envelope = {
+                payload,
+                meta: {
+                    libraryName: base.name,
+                    eventName,
+                    eventId,
+                    namespace: base.namespace,
+                    side: 'client',
+                },
+            };
+            emitLibraryEvent(eventId, envelope);
+        },
+        emitServer(eventName, payload) {
+            emitNet(base.buildEventName(eventName), payload);
+        },
+        getLogger() {
+            return logger;
+        },
+        getConfig() {
+            return createLibraryConfigAccessor(base.namespace);
+        },
+    };
+}

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

@@ -0,0 +1,4 @@
+export { createClientLibrary } from './create-client-library';
+export { buildLibraryEventId } from '../../core/library';
+export type { ClientPluginApi, OpenCoreClientPlugin, PluginInstallContext as ClientPluginInstallContext, } from './plugin';
+export type { LibraryEventEnvelope, LibraryEventId, LibraryEventName, LibraryEventMetadata, LibraryName, LibraryNamespace, OpenCoreClientLibrary, OpenCoreLibraryBase, OpenCoreLibraryConfigAccessor, } from '../../core/library/types';

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

@@ -0,0 +1,2 @@
+export { createClientLibrary } from './create-client-library';
+export { buildLibraryEventId } from '../../core/library';

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

@@ -0,0 +1,5 @@
+/**
+ * Empty interface for module augmentation.
+ */
+export interface ClientPluginApi {
+}

package/dist/runtime/client/library/plugin/index.d.ts

@@ -0,0 +1,4 @@
+export * from './client-plugin-api';
+export * from './plugin-context';
+export * from './plugin.interface';
+export * from './plugin-registry';

package/dist/runtime/client/library/plugin/index.js

@@ -0,0 +1,4 @@
+export * from './client-plugin-api';
+export * from './plugin-context';
+export * from './plugin.interface';
+export * from './plugin-registry';

package/dist/runtime/client/library/plugin/install-client-plugins.d.ts

@@ -0,0 +1,3 @@
+import type { ClientInitOptions } from '../../client-runtime';
+import type { OpenCoreClientPlugin } from './plugin.interface';
+export declare function installClientPlugins(plugins: OpenCoreClientPlugin[], options: ClientInitOptions): Promise<void>;

package/dist/runtime/client/library/plugin/install-client-plugins.js

@@ -0,0 +1,35 @@
+import { di } from '../../client-container';
+import { Client } from '../../client-api-runtime';
+import { PluginRegistry } from './plugin-registry';
+function createConfigAccessor(options) {
+    const runtimeOptions = {
+        mode: options.mode ?? 'CORE',
+    };
+    return {
+        get(key) {
+            const segments = key.split('.').filter(Boolean);
+            let current = runtimeOptions;
+            for (const segment of segments) {
+                if (typeof current !== 'object' || current === null) {
+                    return undefined;
+                }
+                current = current[segment];
+            }
+            return current;
+        },
+    };
+}
+export async function installClientPlugins(plugins, options) {
+    if (plugins.length === 0)
+        return;
+    const registry = new PluginRegistry();
+    await registry.installAll(plugins, {
+        client: Client,
+        di: {
+            register(token, value) {
+                di.registerInstance(token, value);
+            },
+        },
+        config: createConfigAccessor(options),
+    });
+}

package/dist/runtime/client/library/plugin/plugin-context.d.ts

@@ -0,0 +1,10 @@
+import type { ClientApi } from '../../client-api-runtime';
+export interface PluginInstallContext {
+    readonly client: ClientApi;
+    readonly di: {
+        register(token: any, value: any): void;
+    };
+    readonly config: {
+        get<T = any>(key: string): T | undefined;
+    };
+}

package/dist/runtime/client/library/plugin/plugin-registry.d.ts

@@ -0,0 +1,6 @@
+import type { PluginInstallContext } from './plugin-context';
+import type { OpenCoreClientPlugin } from './plugin.interface';
+export declare class PluginRegistry {
+    private readonly installed;
+    installAll(plugins: OpenCoreClientPlugin[], ctx: PluginInstallContext): Promise<void>;
+}

package/dist/runtime/client/library/plugin/plugin-registry.js

@@ -0,0 +1,12 @@
+export class PluginRegistry {
+    installed = new Map();
+    async installAll(plugins, ctx) {
+        for (const plugin of plugins) {
+            if (this.installed.has(plugin.name)) {
+                throw new Error(`Plugin "${plugin.name}" already installed`);
+            }
+            await plugin.install(ctx);
+            this.installed.set(plugin.name, plugin);
+        }
+    }
+}

package/dist/runtime/client/library/plugin/plugin.interface.d.ts

@@ -0,0 +1,11 @@
+import type { PluginInstallContext } from './plugin-context';
+export interface OpenCoreClientPlugin {
+    /**
+     * Unique plugin name.
+     */
+    readonly name: string;
+    /**
+     * Called during Client.init().
+     */
+    install(ctx: PluginInstallContext): void | Promise<void>;
+}

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

@@ -0,0 +1,262 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+interface PlayerSessionMeta {
+    playerId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Client-side player representation with convenient accessors and methods.
+ */
+declare class Player {
+    private meta;
+    /** Get the player's ped handle */
+    get ped(): number;
+    /** Get the player ID */
+    get id(): number;
+    /** Get the server ID (source) */
+    get serverId(): number;
+    /** Get the player's current coordinates */
+    get coords(): Vector3;
+    /** Get the player's current heading (rotation) */
+    get heading(): number;
+    /** Get current health (0-200, 100 = dead) */
+    get health(): number;
+    /** Get max health */
+    get maxHealth(): number;
+    /** Get current armor (0-100) */
+    get armor(): number;
+    /** Check if the player is dead */
+    get isDead(): boolean;
+    /** Check if player is in water */
+    get isInWater(): boolean;
+    /** Check if player is swimming */
+    get isSwimming(): boolean;
+    /** Check if player is falling */
+    get isFalling(): boolean;
+    /** Check if player is climbing */
+    get isClimbing(): boolean;
+    /** Check if player is ragdolling */
+    get isRagdoll(): boolean;
+    /** Check if player is parachuting */
+    get isParachuting(): boolean;
+    /** Check if player is in any vehicle */
+    get isInVehicle(): boolean;
+    /** Get current vehicle handle (or null if not in vehicle) */
+    get currentVehicle(): number | null;
+    /** Get last vehicle the player was in */
+    get lastVehicle(): number | null;
+    /** Check if player is the driver of current vehicle */
+    get isDriver(): boolean;
+    /** Get current vehicle seat index (-1 = driver, 0+ = passengers) */
+    get vehicleSeat(): number | null;
+    /** Check if player is shooting */
+    get isShooting(): boolean;
+    /** Check if player is aiming */
+    get isAiming(): boolean;
+    /** Check if player is reloading */
+    get isReloading(): boolean;
+    /** Check if player is in cover */
+    get isInCover(): boolean;
+    /** Check if player is in melee combat */
+    get isInMeleeCombat(): boolean;
+    /** Get currently equipped weapon hash */
+    get currentWeapon(): number;
+    /** Get ammo count for current weapon */
+    get currentWeaponAmmo(): number;
+    /** Check if player is walking */
+    get isWalking(): boolean;
+    /** Check if player is running */
+    get isRunning(): boolean;
+    /** Check if player is sprinting */
+    get isSprinting(): boolean;
+    /** Check if player is on foot */
+    get isOnFoot(): boolean;
+    /** Check if player is stationary */
+    get isStill(): boolean;
+    /** Get movement speed in m/s */
+    get speed(): number;
+    /**
+     * Set player health.
+     * @param value - Health value (100 = dead, 200 = full)
+     */
+    setHealth(value: number): void;
+    /**
+     * Set player armor.
+     * @param value - Armor value (0-100)
+     */
+    setArmor(value: number): void;
+    /**
+     * Heal the player to full health and armor.
+     */
+    heal(): void;
+    /**
+     * Revive the player at current position.
+     */
+    revive(): void;
+    /**
+     * Set player coordinates.
+     * @param vector3 - Target position
+     * @param heading - Optional heading
+     */
+    setCoords(vector3: Vector3, heading?: number): void;
+    /**
+     * Set player heading/rotation.
+     * @param heading - Heading in degrees
+     */
+    setHeading(heading: number): void;
+    /**
+     * Freeze/unfreeze the player in place.
+     * @param freeze - Whether to freeze
+     */
+    freeze(freeze: boolean): void;
+    /**
+     * Set player invincibility.
+     * @param invincible - Whether invincible
+     */
+    setInvincible(invincible: boolean): void;
+    /**
+     * Set player visibility.
+     * @param visible - Whether visible
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Set player alpha/transparency.
+     * @param alpha - Alpha value (0-255)
+     */
+    setAlpha(alpha: number): void;
+    /**
+     * Give a weapon to the player.
+     * @param weapon - Weapon name (e.g., 'WEAPON_PISTOL')
+     * @param ammo - Ammo count
+     * @param equipNow - Whether to equip immediately
+     */
+    giveWeapon(weapon: string, ammo?: number, equipNow?: boolean): void;
+    /**
+     * Remove a weapon from the player.
+     * @param weapon - Weapon name
+     */
+    removeWeapon(weapon: string): void;
+    /**
+     * Remove all weapons from the player.
+     */
+    removeAllWeapons(): void;
+    /**
+     * Set current weapon ammo.
+     * @param weapon - Weapon name
+     * @param ammo - Ammo count
+     */
+    setWeaponAmmo(weapon: string, ammo: number): void;
+    /**
+     * Check if player has a specific weapon.
+     * @param weapon - Weapon name
+     */
+    hasWeapon(weapon: string): boolean;
+    /**
+     * Play an animation on the player.
+     * @param dict - Animation dictionary
+     * @param name - Animation name
+     * @param duration - Duration (-1 for looped)
+     * @param flags - Animation flags
+     */
+    playAnimation(dict: string, name: string, duration?: number, flags?: number): Promise<void>;
+    /**
+     * Stop current animation.
+     */
+    stopAnimation(): void;
+    /**
+     * Stop animation immediately.
+     */
+    stopAnimationImmediately(): void;
+    /**
+     * Check if player is playing a specific animation.
+     * @param dict - Animation dictionary
+     * @param name - Animation name
+     */
+    isPlayingAnimation(dict: string, name: string): boolean;
+    /**
+     * Warp player into a vehicle.
+     * @param vehicle - Vehicle handle
+     * @param seat - Seat index (-1 = driver)
+     */
+    warpIntoVehicle(vehicle: number, seat?: number): void;
+    /**
+     * Task player to exit current vehicle.
+     * @param flags - Exit flags (0 = normal, 16 = immediately)
+     */
+    exitVehicle(flags?: number): void;
+    /**
+     * Set can ragdoll.
+     * @param canRagdoll - Whether player can ragdoll
+     */
+    setCanRagdoll(canRagdoll: boolean): void;
+    /**
+     * Set ped config flag.
+     * @param flag - Flag ID
+     * @param value - Flag value
+     */
+    setConfigFlag(flag: number, value: boolean): void;
+    /**
+     * Get ped config flag.
+     * @param flag - Flag ID
+     */
+    getConfigFlag(flag: number): boolean;
+    /**
+     * Set a metadata value.
+     * @param key - Meta key
+     * @param value - Meta value
+     */
+    setMeta(key: string, value: unknown): void;
+    /**
+     * Get a metadata value.
+     * @param key - Meta key
+     */
+    getMeta<T = unknown>(key: string): T | undefined;
+    /**
+     * Delete a metadata value.
+     * @param key - Meta key
+     */
+    deleteMeta(key: string): void;
+    /**
+     * Get all metadata.
+     */
+    getAllMeta(): PlayerSessionMeta;
+    /**
+     * Clear all metadata.
+     */
+    clearMeta(): void;
+    /**
+     * Get distance to a position.
+     * @param position - Target position
+     */
+    distanceTo(position: Vector3): number;
+    /**
+     * Check if player is within range of a position.
+     * @param position - Target position
+     * @param range - Maximum range
+     */
+    isNearPosition(position: Vector3, range: number): boolean;
+    /**
+     * Get the entity the player is looking at.
+     * @param maxDistance - Maximum detection distance
+     */
+    getEntityLookingAt(maxDistance?: number): number | null;
+    /**
+     * Disable a control action.
+     * @param control - Control ID
+     * @param padIndex - Pad index (usually 0)
+     */
+    disableControl(control: number, padIndex?: number): void;
+    /**
+     * Check if a control is pressed.
+     * @param control - Control ID
+     * @param padIndex - Pad index (usually 0)
+     */
+    isControlPressed(control: number, padIndex?: number): boolean;
+    /**
+     * Check if a control was just pressed.
+     * @param control - Control ID
+     * @param padIndex - Pad index (usually 0)
+     */
+    isControlJustPressed(control: number, padIndex?: number): boolean;
+}
+export declare const ClientPlayer: Player;
+export {};