@open-core/framework 1.0.5-beta.2 → 1.0.6

package/README.md

@@ -6,9 +6,9 @@
 [![website](https://img.shields.io/badge/web-opencorejs.dev-black?style=flat-square)](https://opencorejs.dev)
 
 
-# OpenCore Framework - Open Stable beta
+# OpenCore Framework - Stable v1
 
-OpenCore is a TypeScript multiplayer runtime framework targeting CitizenFX runtimes (Cfx) via adapters.
+OpenCore is a TypeScript multiplayer runtime framework targeting CitizenFX runtimes (Cfx/RageMP) via adapters.
 
 It is not a gamemode or RP framework. It provides:
 
@@ -277,12 +277,6 @@ pnpm lint:fix
 pnpm format
 ```
 
-## Ecosystem
-
-OpenCore is designed to be extended via separate packages/resources.
-
-- `@open-core/identity`: identity and permission system
-
 ## License
 
 MPL-2.0. See `LICENSE`.

package/dist/adapters/contracts/IEngineEvents.d.ts

@@ -6,8 +6,8 @@ export declare abstract class IEngineEvents {
      * @param eventName - The event name to listen for
      * @param handler - The callback to invoke when the event is emitted
      */
-    abstract on(eventName: string, handler?: (...args: any[]) => void): void;
-    onRuntime(eventName: RuntimeEventName, handler?: (...args: any[]) => void): void;
+    abstract on<TArgs extends readonly unknown[]>(eventName: string, handler?: (...args: TArgs) => void): void;
+    onRuntime<TArgs extends readonly unknown[]>(eventName: RuntimeEventName, handler?: (...args: TArgs) => void): void;
     getRuntimeEventMap(): RuntimeEventMap;
     /**
      * Emits a local event.
@@ -19,5 +19,5 @@ export declare abstract class IEngineEvents {
      * @param eventName - The event name to emit
      * @param args - Arguments to pass to event handlers
      */
-    abstract emit(eventName: string, ...args: any[]): void;
+    abstract emit<TArgs extends readonly unknown[]>(eventName: string, ...args: TArgs): void;
 }

package/dist/adapters/contracts/IExports.d.ts

@@ -1,4 +1,4 @@
 export declare abstract class IExports {
-    abstract register(exportName: string, handler: (...args: any[]) => any): void;
-    abstract getResource<T = any>(resourceName: string): T | undefined;
+    abstract register(exportName: string, handler: (...args: unknown[]) => unknown): void;
+    abstract getResource<T = unknown>(resourceName: string): T | undefined;
 }

package/dist/adapters/contracts/client/IClientLocalPlayerBridge.d.ts

@@ -1,4 +1,25 @@
 import type { Vector3 } from '../../../kernel/utils/vector3';
+/**
+ * Port describing the local player from the client perspective.
+ *
+ * Adapters expose the local player's handle and spatial context so framework
+ * services do not need to reach into low-level platform primitives.
+ */
 export declare abstract class IClientLocalPlayerBridge {
+    /**
+     * Returns the current runtime handle for the local player entity.
+     */
+    abstract getHandle(): number;
+    /**
+     * Returns the current world position for the local player.
+     */
+    abstract getPosition(): Vector3;
+    /**
+     * Returns the current heading for the local player.
+     */
+    abstract getHeading(): number;
+    /**
+     * Moves the local player to a new position and optional heading.
+     */
     abstract setPosition(position: Vector3, heading?: number): void;
 }

package/dist/adapters/contracts/client/IClientLocalPlayerBridge.js

@@ -1,2 +1,8 @@
+/**
+ * Port describing the local player from the client perspective.
+ *
+ * Adapters expose the local player's handle and spatial context so framework
+ * services do not need to reach into low-level platform primitives.
+ */
 export class IClientLocalPlayerBridge {
 }

package/dist/adapters/contracts/client/IClientRuntimeBridge.d.ts

@@ -1,18 +1,18 @@
 export declare abstract class IClientRuntimeBridge {
     abstract getCurrentResourceName(): string;
-    abstract on(eventName: string, handler: (...args: any[]) => void | Promise<void>): void;
-    abstract registerCommand(commandName: string, handler: (...args: any[]) => void, restricted: boolean): void;
+    abstract on<TArgs extends readonly unknown[]>(eventName: string, handler: (...args: TArgs) => void | Promise<void>): void;
+    abstract registerCommand(commandName: string, handler: (...args: unknown[]) => void, restricted: boolean): void;
     abstract registerKeyMapping(commandName: string, description: string, inputMapper: string, key: string): void;
     abstract setTick(handler: () => void | Promise<void>): unknown;
     abstract clearTick(handle: unknown): void;
     abstract getGameTimer(): number;
-    registerWebViewCallback(eventName: string, handler: (data: any, cb: (response: unknown) => void) => void | Promise<void>): void;
+    registerWebViewCallback(eventName: string, handler: (data: unknown, cb: (response: unknown) => void) => void | Promise<void>): void;
     sendWebViewMessage(message: string): void;
     setWebViewFocus(hasFocus: boolean, hasCursor: boolean): void;
     setWebViewInputPassthrough(enabled: boolean): void;
-    abstract registerNuiCallback(eventName: string, handler: (data: any, cb: (response: unknown) => void) => void | Promise<void>): void;
+    abstract registerNuiCallback(eventName: string, handler: (data: unknown, cb: (response: unknown) => void) => void | Promise<void>): void;
     abstract sendNuiMessage(message: string): void;
     abstract setNuiFocus(hasFocus: boolean, hasCursor: boolean): void;
     abstract setNuiFocusKeepInput(keepInput: boolean): void;
-    abstract registerExport(exportName: string, handler: (...args: any[]) => any): void;
+    abstract registerExport<TArgs extends readonly unknown[], TResult = unknown>(exportName: string, handler: (...args: TArgs) => TResult): void;
 }

package/dist/adapters/contracts/client/camera/IClientCameraPort.d.ts

@@ -0,0 +1,107 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+/**
+ * Euler rotation used by scripted camera implementations.
+ */
+export interface ClientCameraRotation {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Complete transform payload for a scripted camera.
+ */
+export interface ClientCameraTransform {
+    position: Vector3;
+    rotation?: ClientCameraRotation;
+    fov?: number;
+}
+/**
+ * Options for creating a new scripted camera.
+ */
+export interface ClientCameraCreateOptions {
+    camName?: string;
+    active?: boolean;
+    transform?: ClientCameraTransform;
+}
+/**
+ * Options for enabling or disabling camera rendering.
+ */
+export interface ClientCameraRenderOptions {
+    ease?: boolean;
+    easeTimeMs?: number;
+}
+/**
+ * Shake parameters for a scripted camera.
+ */
+export interface ClientCameraShakeOptions {
+    type: string;
+    amplitude: number;
+}
+/**
+ * Intent-oriented client camera port.
+ *
+ * The framework asks for high-level camera actions through this port and the
+ * active adapter decides how those actions are achieved for the runtime.
+ */
+export declare abstract class IClientCameraPort {
+    /**
+     * Creates a new scripted camera and returns its runtime handle.
+     */
+    abstract create(options?: ClientCameraCreateOptions): number;
+    /**
+     * Activates or deactivates a specific camera.
+     */
+    abstract setActive(camera: number, active: boolean): void;
+    /**
+     * Enables or disables scripted camera rendering.
+     */
+    abstract render(enable: boolean, options?: ClientCameraRenderOptions): void;
+    /**
+     * Destroys a single scripted camera.
+     */
+    abstract destroy(camera: number, destroyActiveCamera?: boolean): void;
+    /**
+     * Destroys every scripted camera controlled by the adapter/runtime.
+     */
+    abstract destroyAll(destroyActiveCamera?: boolean): void;
+    /**
+     * Applies a transform to a camera.
+     */
+    abstract setTransform(camera: number, transform: ClientCameraTransform): void;
+    /**
+     * Updates only the position of a camera.
+     */
+    abstract setPosition(camera: number, position: Vector3): void;
+    /**
+     * Updates only the rotation of a camera.
+     */
+    abstract setRotation(camera: number, rotation: ClientCameraRotation, rotationOrder?: number): void;
+    /**
+     * Updates only the field of view of a camera.
+     */
+    abstract setFov(camera: number, fov: number): void;
+    /**
+     * Makes the camera point at a world position.
+     */
+    abstract pointAtCoords(camera: number, position: Vector3): void;
+    /**
+     * Makes the camera point at an entity with an optional offset.
+     */
+    abstract pointAtEntity(camera: number, entity: number, offset?: Vector3): void;
+    /**
+     * Stops any pointing target on the camera.
+     */
+    abstract stopPointing(camera: number): void;
+    /**
+     * Interpolates from one camera to another.
+     */
+    abstract interpolate(fromCamera: number, toCamera: number, durationMs: number, easeLocation?: boolean, easeRotation?: boolean): void;
+    /**
+     * Starts a camera shake effect.
+     */
+    abstract shake(camera: number, options: ClientCameraShakeOptions): void;
+    /**
+     * Stops any active shake effect on a camera.
+     */
+    abstract stopShaking(camera: number, stopImmediately?: boolean): void;
+}

package/dist/adapters/contracts/client/camera/IClientCameraPort.js

@@ -0,0 +1,8 @@
+/**
+ * Intent-oriented client camera port.
+ *
+ * The framework asks for high-level camera actions through this port and the
+ * active adapter decides how those actions are achieved for the runtime.
+ */
+export class IClientCameraPort {
+}

package/dist/adapters/contracts/client/camera/index.d.ts

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

package/dist/adapters/contracts/client/camera/index.js

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

package/dist/adapters/contracts/client/index.d.ts

@@ -1,7 +1,11 @@
+export * from './camera';
 export * from './IClientLogConsole';
 export * from './IClientLocalPlayerBridge';
 export * from './IClientPlatformBridge';
 export * from './IClientRuntimeBridge';
 export * from './IGtaPedAppearanceBridge';
+export * from './ped';
+export * from './progress';
 export * from './spawn';
 export * from './ui';
+export * from './vehicle';

package/dist/adapters/contracts/client/index.js

@@ -1,7 +1,11 @@
+export * from './camera';
 export * from './IClientLogConsole';
 export * from './IClientLocalPlayerBridge';
 export * from './IClientPlatformBridge';
 export * from './IClientRuntimeBridge';
 export * from './IGtaPedAppearanceBridge';
+export * from './ped';
+export * from './progress';
 export * from './spawn';
 export * from './ui';
+export * from './vehicle';

package/dist/adapters/contracts/client/ped/IClientPedPort.d.ts

@@ -0,0 +1,62 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+/**
+ * High-level options for spawning a ped.
+ */
+export interface ClientPedSpawnOptions {
+    model: string;
+    position: Vector3;
+    heading?: number;
+    networked?: boolean;
+    missionEntity?: boolean;
+    relationshipGroup?: string;
+    blockEvents?: boolean;
+}
+/**
+ * High-level animation request for a ped.
+ */
+export interface ClientPedAnimationOptions {
+    dict: string;
+    anim: string;
+    blendInSpeed?: number;
+    blendOutSpeed?: number;
+    duration?: number;
+    flags?: number;
+    playbackRate?: number;
+}
+/**
+ * Intent-oriented client ped port.
+ */
+export declare abstract class IClientPedPort {
+    /** Spawns a ped and returns its runtime handle. */
+    abstract spawn(options: ClientPedSpawnOptions): Promise<number>;
+    /** Deletes a ped handle if it exists. */
+    abstract delete(handle: number): void;
+    /** Returns whether a ped handle exists. */
+    abstract exists(handle: number): boolean;
+    /** Plays an animation on a ped. */
+    abstract playAnimation(handle: number, options: ClientPedAnimationOptions): Promise<void>;
+    /** Stops the current animation/task on a ped. */
+    abstract stopAnimation(handle: number): void;
+    /** Stops the current animation/task immediately on a ped. */
+    abstract stopAnimationImmediately(handle: number): void;
+    /** Freezes or unfreezes a ped. */
+    abstract freeze(handle: number, freeze: boolean): void;
+    /** Sets invincibility for a ped. */
+    abstract setInvincible(handle: number, invincible: boolean): void;
+    /** Gives a weapon to a ped. */
+    abstract giveWeapon(handle: number, weapon: string, ammo?: number, hidden?: boolean, forceInHand?: boolean): void;
+    /** Removes all weapons from a ped. */
+    abstract removeAllWeapons(handle: number): void;
+    /** Returns the closest ped to the local player. */
+    abstract getClosest(radius?: number, excludeLocalPlayer?: boolean): number | null;
+    /** Returns nearby ped handles. */
+    abstract getNearby(position: Vector3, radius: number, excludeEntity?: number): number[];
+    /** Makes a ped look at an entity. */
+    abstract lookAtEntity(handle: number, entity: number, duration?: number): void;
+    /** Makes a ped look at coordinates. */
+    abstract lookAtCoords(handle: number, position: Vector3, duration?: number): void;
+    /** Makes a ped walk to coordinates. */
+    abstract walkTo(handle: number, position: Vector3, speed?: number): void;
+    /** Sets basic combat intent flags for a ped. */
+    abstract setCombatAttributes(handle: number, canFight: boolean, canUseCover?: boolean): void;
+}

package/dist/adapters/contracts/client/ped/IClientPedPort.js

@@ -0,0 +1,5 @@
+/**
+ * Intent-oriented client ped port.
+ */
+export class IClientPedPort {
+}

package/dist/adapters/contracts/client/ped/index.d.ts

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

package/dist/adapters/contracts/client/ped/index.js

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

package/dist/adapters/contracts/client/progress/IClientProgressPort.d.ts

@@ -0,0 +1,53 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+/**
+ * Progress task options used by client adapters.
+ */
+export interface ClientProgressOptions {
+    label: string;
+    duration: number;
+    useCircular?: boolean;
+    canCancel?: boolean;
+    disableControls?: boolean;
+    disableMovement?: boolean;
+    disableCombat?: boolean;
+    animation?: {
+        dict: string;
+        anim: string;
+        flags?: number;
+    };
+    prop?: {
+        model: string;
+        bone: number;
+        offset: Vector3;
+        rotation: Vector3;
+    };
+}
+/**
+ * Runtime snapshot for an active progress task.
+ */
+export interface ClientProgressState {
+    active: boolean;
+    progress: number;
+    label: string;
+    startTime: number;
+    duration: number;
+    options: ClientProgressOptions;
+}
+/**
+ * Intent-oriented client progress port.
+ *
+ * Adapters own the platform-specific implementation for task animations,
+ * props, controls, and HUD rendering while the framework exposes a stable API.
+ */
+export declare abstract class IClientProgressPort {
+    /** Starts a progress task and resolves to true when completed. */
+    abstract start(options: ClientProgressOptions): Promise<boolean>;
+    /** Cancels the active task if one exists. */
+    abstract cancel(): void;
+    /** Returns whether a task is active. */
+    abstract isActive(): boolean;
+    /** Returns the current progress percentage. */
+    abstract getProgress(): number;
+    /** Returns the active task snapshot. */
+    abstract getState(): ClientProgressState | null;
+}

package/dist/adapters/contracts/client/progress/IClientProgressPort.js

@@ -0,0 +1,8 @@
+/**
+ * Intent-oriented client progress port.
+ *
+ * Adapters own the platform-specific implementation for task animations,
+ * props, controls, and HUD rendering while the framework exposes a stable API.
+ */
+export class IClientProgressPort {
+}

package/dist/adapters/contracts/client/progress/index.d.ts

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

package/dist/adapters/contracts/client/progress/index.js

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

package/dist/adapters/contracts/client/spawn/IClientSpawnBridge.d.ts

@@ -1,7 +1,6 @@
-import type { RespawnRequest, SpawnRequest, TeleportRequest } from './types';
-export declare abstract class IClientSpawnBridge {
-    abstract waitUntilReady(timeoutMs?: number): Promise<void>;
-    abstract spawn(request: SpawnRequest): Promise<void>;
-    abstract respawn(request: RespawnRequest): Promise<void>;
-    abstract teleport(request: TeleportRequest): Promise<void>;
+import { IClientSpawnPort } from './IClientSpawnPort';
+/**
+ * @deprecated Use IClientSpawnPort for new runtime integrations.
+ */
+export declare abstract class IClientSpawnBridge extends IClientSpawnPort {
 }

package/dist/adapters/contracts/client/spawn/IClientSpawnBridge.js

@@ -1,2 +1,6 @@
-export class IClientSpawnBridge {
+import { IClientSpawnPort } from './IClientSpawnPort';
+/**
+ * @deprecated Use IClientSpawnPort for new runtime integrations.
+ */
+export class IClientSpawnBridge extends IClientSpawnPort {
 }

package/dist/adapters/contracts/client/spawn/IClientSpawnPort.d.ts

@@ -0,0 +1,19 @@
+import type { RespawnRequest, SpawnExecutionResult, SpawnRequest, TeleportRequest } from './types';
+export declare abstract class IClientSpawnPort {
+    /**
+     * Waits until the runtime reports that spawning can safely occur.
+     */
+    abstract waitUntilReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Performs a full local-player spawn.
+     */
+    abstract spawn(request: SpawnRequest): Promise<SpawnExecutionResult>;
+    /**
+     * Performs a respawn flow for the local player.
+     */
+    abstract respawn(request: RespawnRequest): Promise<SpawnExecutionResult>;
+    /**
+     * Repositions the local player without a full spawn sequence.
+     */
+    abstract teleport(request: TeleportRequest): Promise<void>;
+}

package/dist/adapters/contracts/client/spawn/IClientSpawnPort.js

@@ -0,0 +1,2 @@
+export class IClientSpawnPort {
+}

package/dist/adapters/contracts/client/spawn/index.d.ts

@@ -1,2 +1,4 @@
+export * from './IClientSpawnPort';
 export * from './IClientSpawnBridge';
 export * from './types';
+export * from './types';

package/dist/adapters/contracts/client/spawn/index.js

@@ -1,2 +1,4 @@
+export * from './IClientSpawnPort';
 export * from './IClientSpawnBridge';
 export * from './types';
+export * from './types';

package/dist/adapters/contracts/client/spawn/types.d.ts

@@ -4,6 +4,9 @@ export interface SpawnRequest {
     model: string;
     heading?: number;
 }
+export interface SpawnExecutionResult {
+    localPlayerHandle?: number;
+}
 export interface TeleportRequest {
     position: Vector3;
     heading?: number;

package/dist/adapters/contracts/client/ui/webview/IClientWebViewBridge.d.ts

@@ -8,6 +8,7 @@ export declare abstract class IClientWebViewBridge {
     abstract hide(viewId: string): void;
     abstract focus(viewId: string, options?: WebViewFocusOptions): void;
     abstract blur(viewId: string): void;
+    abstract markAsChat(viewId: string): void;
     abstract send(viewId: string, event: string, payload: unknown): void;
     abstract onMessage(handler: (message: WebViewMessage) => void | Promise<void>): () => void;
 }

package/dist/adapters/contracts/client/ui/webview/types.d.ts

@@ -5,6 +5,7 @@ export interface WebViewCapabilities {
     supportsBidirectionalMessaging: boolean;
     supportsExecute: boolean;
     supportsHeadless: boolean;
+    supportsChatMode: boolean;
 }
 export interface WebViewDefinition {
     id: string;
@@ -13,6 +14,7 @@ export interface WebViewDefinition {
     focused?: boolean;
     cursor?: boolean;
     inputPassthrough?: boolean;
+    chatMode?: boolean;
 }
 export interface WebViewFocusOptions {
     cursor?: boolean;