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

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

@@ -0,0 +1,188 @@
+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
+     * Not all platforms support routing buckets.
+     * Use IPlatformCapabilities.supportsRoutingBuckets to check support.
+     *
+     * @param handle - Entity handle
+     * @param bucket - Routing bucket ID
+     */
+    abstract setRoutingBucket(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 getRoutingBucket(handle: number): number;
+    /**
+     * Gets the state bag interface for an entity.
+     *
+     * @remarks
+     * Not all platforms support state bags.
+     * Use IPlatformCapabilities.supportsStateBags to check support.
+     *
+     * @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;
+    /**
+     * Gets entity dimension (alias for getRoutingBucket).
+     *
+     * @remarks
+     * This is a cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param handle - Entity handle
+     * @returns Dimension ID
+     */
+    getDimension(handle: number): number;
+    /**
+     * Sets entity dimension (alias for setRoutingBucket).
+     *
+     * @remarks
+     * This is a cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param handle - Entity handle
+     * @param dimension - Dimension ID
+     */
+    setDimension(handle: number, dimension: 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,35 @@
+/**
+ * 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 {
+    /**
+     * Gets entity dimension (alias for getRoutingBucket).
+     *
+     * @remarks
+     * This is a cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param handle - Entity handle
+     * @returns Dimension ID
+     */
+    getDimension(handle) {
+        return this.getRoutingBucket(handle);
+    }
+    /**
+     * Sets entity dimension (alias for setRoutingBucket).
+     *
+     * @remarks
+     * This is a cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param handle - Entity handle
+     * @param dimension - Dimension ID
+     */
+    setDimension(handle, dimension) {
+        this.setRoutingBucket(handle, dimension);
+    }
+}

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,117 @@
+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;
+    /**
+     * 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
+     * Not all platforms support routing buckets.
+     * Use IPlatformCapabilities.supportsRoutingBuckets to check support.
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @param bucket - Routing bucket ID
+     */
+    abstract setRoutingBucket(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 getRoutingBucket(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[];
+    /**
+     * Gets player dimension (alias for getRoutingBucket).
+     *
+     * @remarks
+     * Cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Dimension ID
+     */
+    getDimension(playerSrc: string): number;
+    /**
+     * Sets player dimension (alias for setRoutingBucket).
+     *
+     * @remarks
+     * Cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @param dimension - Dimension ID
+     */
+    setDimension(playerSrc: string, dimension: number): void;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * 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 {
+    /**
+     * Gets player dimension (alias for getRoutingBucket).
+     *
+     * @remarks
+     * Cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @returns Dimension ID
+     */
+    getDimension(playerSrc) {
+        return this.getRoutingBucket(playerSrc);
+    }
+    /**
+     * Sets player dimension (alias for setRoutingBucket).
+     *
+     * @remarks
+     * Cross-platform alias. Some platforms call it "dimension",
+     * others call it "routing bucket" or "virtual world".
+     *
+     * @param playerSrc - Player source/client ID (as string)
+     * @param dimension - Dimension ID
+     */
+    setDimension(playerSrc, dimension) {
+        this.setRoutingBucket(playerSrc, dimension);
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Server-side vehicle operations adapter.
+ *
+ * @remarks
+ * Abstracts FiveM vehicle natives for server-side operations.
+ * Allows the runtime to work without direct FiveM dependencies.
+ */
+export declare abstract class IVehicleServer {
+    /**
+     * Creates a vehicle using server setter (server-authoritative).
+     *
+     * @param modelHash - Vehicle model hash
+     * @param vehicleType - Vehicle type string
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     * @param z - Z coordinate
+     * @param heading - Vehicle heading
+     * @returns Entity handle or 0 on failure
+     */
+    abstract createServerSetter(modelHash: number, vehicleType: string, x: number, y: number, z: number, heading: number): number;
+    /**
+     * Gets vehicle colors.
+     * @returns [primaryColor, secondaryColor]
+     */
+    abstract getColours(handle: number): [number, number];
+    /**
+     * Sets vehicle colors.
+     */
+    abstract setColours(handle: number, primary: number, secondary: number): void;
+    /**
+     * Gets vehicle number plate text.
+     */
+    abstract getNumberPlateText(handle: number): string;
+    /**
+     * Sets vehicle number plate text.
+     */
+    abstract setNumberPlateText(handle: number, text: string): void;
+    /**
+     * Sets vehicle doors locked state.
+     * @param state - 0 = unlocked, 1 = unlocked, 2 = locked, 3 = locked for player, 4 = locked for non-players
+     */
+    abstract setDoorsLocked(handle: number, state: number): void;
+    /**
+     * Gets network ID from entity handle.
+     */
+    abstract getNetworkIdFromEntity(handle: number): number;
+    /**
+     * Gets entity handle from network ID.
+     */
+    abstract getEntityFromNetworkId(networkId: number): number;
+    /**
+     * Checks if network ID exists.
+     */
+    abstract networkIdExists(networkId: number): boolean;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Server-side vehicle operations adapter.
+ *
+ * @remarks
+ * Abstracts FiveM vehicle natives for server-side operations.
+ * Allows the runtime to work without direct FiveM dependencies.
+ */
+export class IVehicleServer {
+}

package/dist/adapters/contracts/transport/context.d.ts

@@ -0,0 +1,5 @@
+export type RuntimeContext = 'server' | 'client';
+export interface EventContext {
+    clientId?: number;
+    raw?: unknown;
+}

package/dist/adapters/contracts/transport/events.api.d.ts

@@ -0,0 +1,36 @@
+import { EventContext, RuntimeContext } from './context';
+import { Player } from '../../../runtime/server/entities/player';
+type EmitArgs<C extends RuntimeContext> = C extends 'server' ? [target: Player | number | number[] | 'all', ...args: any[]] : [...args: any[]];
+/**
+ * broadcast and listen to events without relying on runtime. The adapter will be used.
+ */
+export declare abstract class EventsAPI<C extends RuntimeContext> {
+    /**
+     * Listen to an event.
+     *
+     * Server:
+     *   - triggered by clients
+     * Client:
+     *   - triggered by server
+     */
+    abstract on(event: string, handler: (ctx: EventContext, ...args: any[]) => void | Promise<void>): void;
+    /**
+     * Emit an event.
+     *  SERVER → CLIENT
+     * Server:
+     *   - sends to client(s)
+     * Client:
+     *   - sends to server, targetOrArg will be ignored
+     */
+    abstract emit(event: string, target: Player | number | number[] | 'all', ...args: any[]): void;
+    /**
+     * Emit an event.
+     *  CLIENT → SERVER
+     * Server:
+     *   - sends to client(s)
+     * Client:
+     *   - sends to server, targetOrArg will be ignored
+     */
+    abstract emit(event: string, ...args: EmitArgs<C>): void;
+}
+export {};

package/dist/adapters/contracts/transport/events.api.js

@@ -0,0 +1,5 @@
+/**
+ * broadcast and listen to events without relying on runtime. The adapter will be used.
+ */
+export class EventsAPI {
+}

package/dist/adapters/contracts/transport/messaging.transport.d.ts

@@ -0,0 +1,8 @@
+import { RuntimeContext } from './context';
+import { EventsAPI } from './events.api';
+import { RpcAPI } from './rpc.api';
+export declare abstract class MessagingTransport {
+    abstract readonly context: RuntimeContext;
+    abstract readonly events: EventsAPI<RuntimeContext>;
+    abstract readonly rpc: RpcAPI<RuntimeContext>;
+}

package/dist/adapters/contracts/transport/messaging.transport.js

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

package/dist/adapters/contracts/transport/rpc.api.d.ts

@@ -0,0 +1,66 @@
+import { EventContext, RuntimeContext } from './context';
+export interface RpcContext extends EventContext {
+    /**
+     * Unique id used to correlate request/response (and ACK when applicable).
+     */
+    requestId: string;
+}
+/**
+ * Target used when the caller wants to address one or more remote peers.
+ *
+ * @remarks
+ * Typically used on the server to call/notify one or more clients.
+ * Some transports/environments may ignore the target (e.g. in-process Node adapters).
+ */
+export type RpcTarget = number | number[] | 'all';
+export type RpcCallTarget = number | number[];
+type RpcCallArgs<C extends RuntimeContext> = C extends 'server' ? [target: RpcCallTarget, ...args: any[]] : [...args: any[]];
+type RpcNotifyArgs<C extends RuntimeContext> = C extends 'server' ? [target: RpcTarget, ...args: any[]] : [...args: any[]];
+/**
+ * Remote Procedure Call API.
+ *
+ * @remarks
+ * `RpcAPI` defines the contract for request/response style events.
+ *
+ * Direction depends on runtime:
+ * - Server runtime:
+ *   - `on()` registers handlers callable by clients.
+ *   - `call()/notify()` typically invokes handlers on clients (using {@link RpcTarget}).
+ * - Client runtime:
+ *   - `on()` registers handlers callable by server.
+ *   - `call()/notify()` typically invokes handlers on server.
+ *
+ * Transport implementations decide whether this is remote (network) or local (in-process):
+ * - FiveM transports: remote client<->server.
+ * - Node transports: often in-process (single runtime) and may ignore {@link RpcTarget}.
+ */
+export declare abstract class RpcAPI<C extends RuntimeContext> {
+    /**
+     * Register an RPC handler.
+     *
+     * Server:
+     *   - callable from clients
+     * Client:
+     *   - callable from server
+     *
+     * @remarks
+     * The handler receives a {@link RpcContext}. In server environments this usually includes
+     * the `clientId` of the caller (via {@link EventContext}).
+     */
+    abstract on<TArgs extends any[], TResult>(name: string, handler: (ctx: RpcContext, ...args: TArgs) => TResult | Promise<TResult>): void;
+    /**
+     * Call an RPC and wait for the result.
+     *
+     * @remarks
+     * Use this when you need a return value.
+     */
+    abstract call<TResult = unknown>(name: string, ...args: RpcCallArgs<C>): Promise<TResult>;
+    /**
+     * Notify an RPC and wait for ACK. (acknowledgments)
+     *
+     * @remarks
+     * Use this when you only need delivery confirmation (no return value).
+     */
+    abstract notify(name: string, ...args: RpcNotifyArgs<C>): Promise<void>;
+}
+export {};