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

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

@@ -0,0 +1,7 @@
+export * from './IClientLogConsole';
+export * from './IClientLocalPlayerBridge';
+export * from './IClientPlatformBridge';
+export * from './IClientRuntimeBridge';
+export * from './IGtaPedAppearanceBridge';
+export * from './spawn';
+export * from './ui';

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

@@ -0,0 +1,7 @@
+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>;
+}

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

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

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

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

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

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

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

@@ -0,0 +1,14 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+export interface SpawnRequest {
+    position: Vector3;
+    model: string;
+    heading?: number;
+}
+export interface TeleportRequest {
+    position: Vector3;
+    heading?: number;
+}
+export interface RespawnRequest {
+    position: Vector3;
+    heading?: number;
+}

package/dist/adapters/contracts/client/ui/IClientBlipBridge.d.ts

@@ -0,0 +1,25 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+export interface ClientBlipOptions {
+    icon?: number;
+    sprite?: number;
+    color?: number;
+    scale?: number;
+    shortRange?: boolean;
+    label?: string;
+    alpha?: number;
+    route?: boolean;
+    routeColor?: number;
+    visible?: boolean;
+}
+export interface ClientBlipDefinition extends ClientBlipOptions {
+    position?: Vector3;
+    entity?: number;
+    radius?: number;
+}
+export declare abstract class IClientBlipBridge {
+    abstract create(id: string, definition: ClientBlipDefinition): void;
+    abstract update(id: string, patch: Partial<ClientBlipDefinition>): boolean;
+    abstract exists(id: string): boolean;
+    abstract remove(id: string): boolean;
+    abstract clear(): void;
+}

package/dist/adapters/contracts/client/ui/IClientBlipBridge.js

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

package/dist/adapters/contracts/client/ui/IClientMarkerBridge.d.ts

@@ -0,0 +1,31 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+export interface ClientMarkerOptions {
+    variant?: number;
+    type?: number;
+    size?: Vector3;
+    scale?: Vector3;
+    visible?: boolean;
+    bob?: boolean;
+    bobUpAndDown?: boolean;
+    faceCamera?: boolean;
+    rotate?: boolean;
+    drawOnEnts?: boolean;
+    color?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+}
+export interface ClientMarkerDefinition extends ClientMarkerOptions {
+    position: Vector3;
+    rotation?: Vector3;
+}
+export declare abstract class IClientMarkerBridge {
+    abstract create(id: string, definition: ClientMarkerDefinition): void;
+    abstract update(id: string, patch: Partial<ClientMarkerDefinition>): boolean;
+    abstract remove(id: string): boolean;
+    abstract exists(id: string): boolean;
+    abstract clear(): void;
+    abstract draw(definition: ClientMarkerDefinition): void;
+}

package/dist/adapters/contracts/client/ui/IClientMarkerBridge.js

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

package/dist/adapters/contracts/client/ui/IClientNotificationBridge.d.ts

@@ -0,0 +1,21 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+export type ClientNotificationKind = 'feed' | 'typed' | 'advanced' | 'help' | 'subtitle' | 'floating';
+export interface ClientNotificationDefinition {
+    kind: ClientNotificationKind;
+    message: string;
+    title?: string;
+    subtitle?: string;
+    type?: 'info' | 'success' | 'warning' | 'error';
+    blink?: boolean;
+    duration?: number;
+    beep?: boolean;
+    looped?: boolean;
+    flash?: boolean;
+    saveToBrief?: boolean;
+    backgroundColor?: number;
+    worldPosition?: Vector3;
+}
+export declare abstract class IClientNotificationBridge {
+    abstract show(definition: ClientNotificationDefinition): void;
+    abstract clear(scope?: 'help' | 'subtitle' | 'all'): void;
+}

package/dist/adapters/contracts/client/ui/IClientNotificationBridge.js

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

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

@@ -0,0 +1,4 @@
+export * from './IClientBlipBridge';
+export * from './IClientMarkerBridge';
+export * from './IClientNotificationBridge';
+export * from './webview';

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

@@ -0,0 +1,4 @@
+export * from './IClientBlipBridge';
+export * from './IClientMarkerBridge';
+export * from './IClientNotificationBridge';
+export * from './webview';

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

@@ -0,0 +1,13 @@
+import type { WebViewCapabilities, WebViewDefinition, WebViewFocusOptions, WebViewMessage } from './types';
+export declare abstract class IClientWebViewBridge {
+    abstract getCapabilities(): WebViewCapabilities;
+    abstract create(definition: WebViewDefinition): void;
+    abstract destroy(viewId: string): void;
+    abstract exists(viewId: string): boolean;
+    abstract show(viewId: string): void;
+    abstract hide(viewId: string): void;
+    abstract focus(viewId: string, options?: WebViewFocusOptions): void;
+    abstract blur(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/IClientWebViewBridge.js

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

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

@@ -0,0 +1,2 @@
+export * from './IClientWebViewBridge';
+export * from './types';

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

@@ -0,0 +1,2 @@
+export * from './IClientWebViewBridge';
+export * from './types';

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

@@ -0,0 +1,25 @@
+export interface WebViewCapabilities {
+    supportsFocus: boolean;
+    supportsCursor: boolean;
+    supportsInputPassthrough: boolean;
+    supportsBidirectionalMessaging: boolean;
+    supportsExecute: boolean;
+    supportsHeadless: boolean;
+}
+export interface WebViewDefinition {
+    id: string;
+    url: string;
+    visible?: boolean;
+    focused?: boolean;
+    cursor?: boolean;
+    inputPassthrough?: boolean;
+}
+export interface WebViewFocusOptions {
+    cursor?: boolean;
+    inputPassthrough?: boolean;
+}
+export interface WebViewMessage {
+    viewId: string;
+    event: string;
+    payload: unknown;
+}

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

@@ -0,0 +1,4 @@
+export * from './IHasher';
+export * from './types';
+export * from './transport';
+export * from './runtime';

package/dist/adapters/contracts/index.js

@@ -0,0 +1,4 @@
+export * from './IHasher';
+export * from './types';
+export * from './transport';
+export * from './runtime';

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

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

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

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

package/dist/adapters/contracts/runtime/runtime-events.d.ts

@@ -0,0 +1,9 @@
+export declare const RUNTIME_EVENTS: {
+    readonly playerJoining: "playerJoining";
+    readonly playerDropped: "playerDropped";
+    readonly serverResourceStop: "onServerResourceStop";
+    readonly playerCommand: "playerCommand";
+};
+export type RuntimeEventName = (typeof RUNTIME_EVENTS)[keyof typeof RUNTIME_EVENTS];
+export type RuntimeEventMap = Record<RuntimeEventName, string>;
+export declare const DEFAULT_RUNTIME_EVENT_MAP: RuntimeEventMap;

package/dist/adapters/contracts/runtime/runtime-events.js

@@ -0,0 +1,7 @@
+export const RUNTIME_EVENTS = {
+    playerJoining: 'playerJoining',
+    playerDropped: 'playerDropped',
+    serverResourceStop: 'onServerResourceStop',
+    playerCommand: 'playerCommand',
+};
+export const DEFAULT_RUNTIME_EVENT_MAP = Object.fromEntries(Object.values(RUNTIME_EVENTS).map((e) => [e, e]));

package/dist/adapters/contracts/server/IEntityServer.d.ts

@@ -0,0 +1,164 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+/**
+ * Options for setting entity position.
+ *
+ * @remarks
+ * Platform-specific options can be passed via the `platformOptions` field.
+ * Each platform adapter interprets these options according to its capabilities.
+ */
+export interface SetPositionOptions {
+    /**
+     * Whether to keep the entity alive during teleport.
+     * @default false
+     */
+    keepAlive?: boolean;
+    /**
+     * Whether to clear the area around the new position.
+     * @default true
+     */
+    clearArea?: boolean;
+    /**
+     * Platform-specific options.
+     * @example { ragdollFlag: false, deadFlag: false } for FiveM
+     */
+    platformOptions?: Record<string, unknown>;
+}
+/**
+ * Server-side entity operations adapter.
+ *
+ * @remarks
+ * Abstracts entity natives for server-side operations across different platforms.
+ * Allows the runtime to work without direct platform dependencies.
+ */
+export declare abstract class IEntityServer {
+    /**
+     * Checks if an entity exists.
+     * @param handle - Entity handle
+     */
+    abstract doesExist(handle: number): boolean;
+    /**
+     * Gets entity coordinates.
+     * @param handle - Entity handle
+     */
+    abstract getCoords(handle: number): Vector3;
+    /**
+     * Sets entity coordinates using the new simplified API.
+     *
+     * @param handle - Entity handle
+     * @param position - Target position
+     * @param options - Optional positioning options
+     */
+    abstract setPosition(handle: number, position: Vector3, options?: SetPositionOptions): void;
+    /**
+     * Sets entity coordinates.
+     *
+     * @deprecated Use setPosition() instead for cross-platform compatibility.
+     * This method is kept for backward compatibility and FiveM-specific use cases.
+     *
+     * @param handle - Entity handle
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     * @param z - Z coordinate
+     * @param alive - Keep alive flag (FiveM specific)
+     * @param deadFlag - Dead flag (FiveM specific)
+     * @param ragdollFlag - Ragdoll flag (FiveM specific)
+     * @param clearArea - Clear area flag
+     */
+    abstract setCoords(handle: number, x: number, y: number, z: number, alive?: boolean, deadFlag?: boolean, ragdollFlag?: boolean, clearArea?: boolean): void;
+    /**
+     * Gets entity heading (rotation on Z axis).
+     * @param handle - Entity handle
+     */
+    abstract getHeading(handle: number): number;
+    /**
+     * Sets entity heading (rotation on Z axis).
+     * @param handle - Entity handle
+     * @param heading - Heading in degrees (0-360)
+     */
+    abstract setHeading(handle: number, heading: number): void;
+    /**
+     * Gets entity model hash.
+     * @param handle - Entity handle
+     */
+    abstract getModel(handle: number): number;
+    /**
+     * Deletes an entity.
+     * @param handle - Entity handle
+     */
+    abstract delete(handle: number): void;
+    /**
+     * Sets entity orphan mode (what happens when script stops).
+     *
+     * @param handle - Entity handle
+     * @param mode - Orphan mode (platform-specific values)
+     *   - FiveM: 0 = delete, 1 = keep, 2 = keep until restart
+     */
+    abstract setOrphanMode(handle: number, mode: number): void;
+    /**
+     * Sets entity routing bucket (virtual world/dimension).
+     *
+     * @remarks
+     * Platform-specific behavior may vary.
+     *
+     * @param handle - Entity handle
+     * @param bucket - Routing bucket ID
+     */
+    abstract setDimension(handle: number, bucket: number): void;
+    /**
+     * Gets entity routing bucket (virtual world/dimension).
+     * @param handle - Entity handle
+     * @returns Routing bucket ID (0 is default world)
+     */
+    abstract getDimension(handle: number): number;
+    /**
+     * Gets the state bag interface for an entity.
+     *
+     * @remarks
+     * Platform-specific behavior may vary.
+     *
+     * @param handle - Entity handle
+     */
+    abstract getStateBag(handle: number): EntityStateBag;
+    /**
+     * Gets entity health.
+     * @param handle - Entity handle
+     * @returns Health value (platform-specific range)
+     */
+    abstract getHealth(handle: number): number;
+    /**
+     * Sets entity health.
+     * @param handle - Entity handle
+     * @param health - Health value
+     */
+    abstract setHealth(handle: number, health: number): void;
+    /**
+     * Gets entity armor.
+     * @param handle - Entity handle
+     * @returns Armor value (typically 0-100)
+     */
+    abstract getArmor(handle: number): number;
+    /**
+     * Sets entity armor.
+     * @param handle - Entity handle
+     * @param armor - Armor value
+     */
+    abstract setArmor(handle: number, armor: number): void;
+}
+/**
+ * State bag interface for entity state synchronization.
+ */
+export interface EntityStateBag {
+    /**
+     * Sets a value in the state bag.
+     *
+     * @param key - State key
+     * @param value - Value to set
+     * @param replicated - Whether to replicate to clients (default: true)
+     */
+    set(key: string, value: unknown, replicated?: boolean): void;
+    /**
+     * Gets a value from the state bag.
+     * @param key - State key
+     */
+    get(key: string): unknown;
+}

package/dist/adapters/contracts/server/IEntityServer.js

@@ -0,0 +1,9 @@
+/**
+ * Server-side entity operations adapter.
+ *
+ * @remarks
+ * Abstracts entity natives for server-side operations across different platforms.
+ * Allows the runtime to work without direct platform dependencies.
+ */
+export class IEntityServer {
+}

package/dist/adapters/contracts/server/IPedAppearanceServer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Server-side ped appearance operations adapter.
+ *
+ * @remarks
+ * Abstracts FiveM ped appearance natives for server-side operations.
+ * Server-side has limited appearance control compared to client.
+ *
+ * Only components and props can be set from the server.
+ * HeadBlend, face features, overlays, and tattoos must be applied client-side.
+ */
+export declare abstract class IPedAppearanceServer {
+    /**
+     * Sets a ped's component variation (clothing, hair, etc.).
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @param drawable - Drawable index
+     * @param texture - Texture index
+     * @param palette - Palette ID (usually 2)
+     */
+    abstract setComponentVariation(ped: number, componentId: number, drawable: number, texture: number, palette: number): void;
+    /**
+     * Sets a ped's prop (hat, glasses, etc.).
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @param drawable - Drawable index
+     * @param texture - Texture index
+     * @param attach - Whether to attach the prop
+     */
+    abstract setPropIndex(ped: number, propId: number, drawable: number, texture: number, attach: boolean): void;
+    /**
+     * Clears a ped's prop.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID to clear (0-7)
+     */
+    abstract clearProp(ped: number, propId: number): void;
+    /**
+     * Sets the ped to default component variation.
+     *
+     * @param ped - Ped entity handle
+     */
+    abstract setDefaultComponentVariation(ped: number): void;
+}

package/dist/adapters/contracts/server/IPedAppearanceServer.js

@@ -0,0 +1,12 @@
+/**
+ * Server-side ped appearance operations adapter.
+ *
+ * @remarks
+ * Abstracts FiveM ped appearance natives for server-side operations.
+ * Server-side has limited appearance control compared to client.
+ *
+ * Only components and props can be set from the server.
+ * HeadBlend, face features, overlays, and tattoos must be applied client-side.
+ */
+export class IPedAppearanceServer {
+}

package/dist/adapters/contracts/server/IPedServer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-side ped operations adapter.
+ *
+ * @remarks
+ * Provides a platform-agnostic contract to spawn and manage NPC peds.
+ */
+export declare abstract class IPedServer {
+    /**
+     * Creates a server-side ped.
+     *
+     * @param pedType - Platform ped type.
+     * @param modelHash - Ped model hash.
+     * @param x - X world position.
+     * @param y - Y world position.
+     * @param z - Z world position.
+     * @param heading - Heading in degrees.
+     * @param networked - Whether the ped should be networked.
+     * @returns Entity handle or 0 on failure.
+     */
+    abstract create(pedType: number, modelHash: number, x: number, y: number, z: number, heading: number, networked: boolean): number;
+    /** Deletes a ped entity. */
+    abstract delete(handle: number): void;
+    /** Returns the network id for an entity handle. */
+    abstract getNetworkIdFromEntity(handle: number): number;
+    /** Returns the entity handle for a network id. */
+    abstract getEntityFromNetworkId(networkId: number): number;
+    /** Checks whether a network id is currently valid. */
+    abstract networkIdExists(networkId: number): boolean;
+}

package/dist/adapters/contracts/server/IPedServer.js

@@ -0,0 +1,8 @@
+/**
+ * Server-side ped operations adapter.
+ *
+ * @remarks
+ * Provides a platform-agnostic contract to spawn and manage NPC peds.
+ */
+export class IPedServer {
+}

package/dist/adapters/contracts/server/IPlayerServer.d.ts

@@ -0,0 +1,98 @@
+import type { PlayerIdentifier } from '../types/identifier';
+/**
+ * Server-side player operations adapter.
+ *
+ * @remarks
+ * Abstracts player natives for server-side operations across different platforms.
+ * Allows the runtime to work without direct platform dependencies.
+ */
+export declare abstract class IPlayerServer {
+    /**
+     * Gets the ped/character handle for a player.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Ped entity handle
+     */
+    abstract getPed(playerSrc: string): number;
+    /**
+     * Drops (kicks) a player from the server.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @param reason - Kick reason message
+     */
+    abstract drop(playerSrc: string, reason: string): void;
+    /**
+     * Sets the active player model when the runtime supports it.
+     */
+    abstract setModel(playerSrc: string, model: string): void;
+    /**
+     * Gets a player identifier by type.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @param identifierType - Identifier type (e.g., 'license', 'steam', 'discord')
+     * @returns Identifier string or undefined
+     */
+    abstract getIdentifier(playerSrc: string, identifierType: string): string | undefined;
+    /**
+     * Gets all identifiers for a player as structured objects.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Array of PlayerIdentifier objects
+     */
+    abstract getPlayerIdentifiers(playerSrc: string): PlayerIdentifier[];
+    /**
+     * Gets the number of player identifiers.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Number of identifiers
+     */
+    abstract getNumIdentifiers(playerSrc: string): number;
+    /**
+     * Gets player display name.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Player name
+     */
+    abstract getName(playerSrc: string): string;
+    /**
+     * Gets player ping/latency.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Ping in milliseconds
+     */
+    abstract getPing(playerSrc: string): number;
+    /**
+     * Gets player endpoint (IP:port).
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Endpoint string
+     */
+    abstract getEndpoint(playerSrc: string): string;
+    /**
+     * Sets player routing bucket (virtual world/dimension).
+     *
+     * @remarks
+     * Platform-specific behavior may vary.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @param bucket - Routing bucket ID
+     */
+    abstract setDimension(playerSrc: string, bucket: number): void;
+    /**
+     * Gets player routing bucket (virtual world/dimension).
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Routing bucket ID (0 is default world)
+     */
+    abstract getDimension(playerSrc: string): number;
+    /**
+     * Gets all currently connected player sources.
+     *
+     * @remarks
+     * Returns the source IDs (as strings) of all players currently connected.
+     * Used for session recovery after resource restarts.
+     *
+     * @returns Array of player source strings
+     */
+    abstract getConnectedPlayers(): string[];
+}

package/dist/adapters/contracts/server/IPlayerServer.js

@@ -0,0 +1,9 @@
+/**
+ * Server-side player operations adapter.
+ *
+ * @remarks
+ * Abstracts player natives for server-side operations across different platforms.
+ * Allows the runtime to work without direct platform dependencies.
+ */
+export class IPlayerServer {
+}