@open-core/framework 0.2.8 → 0.3.0

package/README.md

@@ -1,3 +1,11 @@
+[![CI](https://github.com/newcore-network/opencore/actions/workflows/ci.yml/badge.svg)](https://github.com/newcore-network/opencore/actions/workflows/ci.yml)
+![npm](https://img.shields.io/npm/v/@open-core/framework?style=flat-square)
+![license](https://img.shields.io/github/license/newcore-network/opencore?style=flat-square)
+![typescript](https://img.shields.io/badge/TypeScript-first-blue?style=flat-square)
+[![cli](https://img.shields.io/badge/CLI-opencore--cli-purple?style=flat-square)](https://opencorejs.dev/docs/cli/introduction)
+[![website](https://img.shields.io/badge/web-opencorejs.dev-black?style=flat-square)](https://opencorejs.dev)
+
+
 # OpenCore Framework - Open Stable beta
 
 OpenCore is a TypeScript multiplayer runtime framework targeting FiveM via an adapter.
@@ -11,6 +19,8 @@ It is not a gamemode or RP framework. It provides:
 
 License: MPL-2.0
 
+[Discord Community](https://discord.gg/99g3FgvkPs) | [Website](https://opencorejs.dev) | [OpenCore CLI](https://github.com/newcore-network/opencore-cli)
+
 ## Scope
 
 This package (`@open-core/framework`) contains transversal infrastructure only.

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

@@ -0,0 +1,79 @@
+/**
+ * Platform capabilities contract.
+ *
+ * @remarks
+ * Defines what features a platform supports, allowing runtime
+ * feature detection and graceful degradation across different
+ * game engines (FiveM, RageMP, alt:V, RedM, etc.)
+ */
+export declare abstract class IPlatformCapabilities {
+    /**
+     * Unique identifier for the platform.
+     * @example 'fivem', 'ragemp', 'altv', 'redm'
+     */
+    abstract readonly platformName: string;
+    /**
+     * Human-readable display name.
+     * @example 'FiveM', 'RageMP', 'alt:V', 'RedM'
+     */
+    abstract readonly displayName: string;
+    /**
+     * Whether the platform supports routing buckets (virtual worlds/dimensions).
+     */
+    abstract readonly supportsRoutingBuckets: boolean;
+    /**
+     * Whether the platform supports state bags for entity synchronization.
+     */
+    abstract readonly supportsStateBags: boolean;
+    /**
+     * Whether the platform has native voice chat support.
+     */
+    abstract readonly supportsVoiceChat: boolean;
+    /**
+     * Whether the platform supports server-side entity creation.
+     */
+    abstract readonly supportsServerEntities: boolean;
+    /**
+     * Supported identifier types for this platform.
+     * @example ['steam', 'license', 'discord'] for FiveM
+     * @example ['socialclub', 'ip'] for RageMP
+     */
+    abstract readonly identifierTypes: readonly string[];
+    /**
+     * Maximum number of players supported by the platform.
+     * Returns undefined if unlimited or unknown.
+     */
+    abstract readonly maxPlayers: number | undefined;
+    /**
+     * Check if a specific feature is supported.
+     *
+     * @param feature - Feature identifier to check
+     * @returns true if the feature is supported
+     */
+    abstract isFeatureSupported(feature: string): boolean;
+    /**
+     * Get platform-specific configuration value.
+     *
+     * @param key - Configuration key
+     * @returns Configuration value or undefined
+     */
+    abstract getConfig<T = unknown>(key: string): T | undefined;
+}
+/**
+ * Well-known feature identifiers for cross-platform compatibility.
+ */
+export declare const PlatformFeatures: {
+    readonly ROUTING_BUCKETS: "routing_buckets";
+    readonly STATE_BAGS: "state_bags";
+    readonly VOICE_CHAT: "voice_chat";
+    readonly SERVER_ENTITIES: "server_entities";
+    readonly VEHICLE_MODS: "vehicle_mods";
+    readonly PED_APPEARANCE: "ped_appearance";
+    readonly WEAPON_COMPONENTS: "weapon_components";
+    readonly BLIPS: "blips";
+    readonly MARKERS: "markers";
+    readonly TEXT_LABELS: "text_labels";
+    readonly CHECKPOINTS: "checkpoints";
+    readonly COLSHAPES: "colshapes";
+};
+export type PlatformFeature = (typeof PlatformFeatures)[keyof typeof PlatformFeatures];

package/dist/adapters/contracts/IPlatformCapabilities.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformFeatures = exports.IPlatformCapabilities = void 0;
+/**
+ * Platform capabilities contract.
+ *
+ * @remarks
+ * Defines what features a platform supports, allowing runtime
+ * feature detection and graceful degradation across different
+ * game engines (FiveM, RageMP, alt:V, RedM, etc.)
+ */
+class IPlatformCapabilities {
+}
+exports.IPlatformCapabilities = IPlatformCapabilities;
+/**
+ * Well-known feature identifiers for cross-platform compatibility.
+ */
+exports.PlatformFeatures = {
+    ROUTING_BUCKETS: 'routing_buckets',
+    STATE_BAGS: 'state_bags',
+    VOICE_CHAT: 'voice_chat',
+    SERVER_ENTITIES: 'server_entities',
+    VEHICLE_MODS: 'vehicle_mods',
+    PED_APPEARANCE: 'ped_appearance',
+    WEAPON_COMPONENTS: 'weapon_components',
+    BLIPS: 'blips',
+    MARKERS: 'markers',
+    TEXT_LABELS: 'text_labels',
+    CHECKPOINTS: 'checkpoints',
+    COLSHAPES: 'colshapes',
+};

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

@@ -1,5 +1,5 @@
 import { Vector3 } from '../../kernel';
 export declare abstract class IPlayerInfo {
     abstract getPlayerName(clientId: number): string | null;
-    abstract getPlayerPosition(clientId: number): Vector3 | undefined;
+    abstract getPlayerPosition(clientId: number): Vector3;
 }

package/dist/adapters/contracts/{IPedAppearanceClient.d.ts → client/IPedAppearanceClient.d.ts}

@@ -1,4 +1,4 @@
-import { HeadBlendData } from '../../kernel/shared';
+import { HeadBlendData } from '../../../kernel/shared/player-appearance.types';
 /**
  * Client-side ped appearance operations adapter.
  *

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,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IEntityServer = void 0;
+/**
+ * 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.
+ */
+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);
+    }
+}
+exports.IEntityServer = IEntityServer;

package/dist/adapters/contracts/{IPlayerServer.d.ts → server/IPlayerServer.d.ts}

@@ -1,13 +1,14 @@
+import type { PlayerIdentifier } from '../types/identifier';
 /**
  * Server-side player operations adapter.
  *
  * @remarks
- * Abstracts FiveM player natives for server-side operations.
- * Allows the runtime to work without direct FiveM dependencies.
+ * 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 handle for a player.
+     * Gets the ped/character handle for a player.
      *
      * @param playerSrc - Player source/client ID (as string)
      * @returns Ped entity handle
@@ -29,12 +30,21 @@ export declare abstract class IPlayerServer {
      */
     abstract getIdentifier(playerSrc: string, identifierType: string): string | undefined;
     /**
-     * Gets all identifiers for a player.
+     * Gets all identifiers for a player as raw strings.
+     *
+     * @deprecated Use getPlayerIdentifiers() for structured identifier data.
      *
      * @param playerSrc - Player source/client ID (as string)
-     * @returns Array of identifier strings
+     * @returns Array of identifier strings (e.g., ['steam:xxx', 'license:xxx'])
      */
     abstract getIdentifiers(playerSrc: string): string[];
+    /**
+     * 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.
      *
@@ -43,14 +53,14 @@ export declare abstract class IPlayerServer {
      */
     abstract getNumIdentifiers(playerSrc: string): number;
     /**
-     * Gets player name.
+     * Gets player display name.
      *
      * @param playerSrc - Player source/client ID (as string)
      * @returns Player name
      */
     abstract getName(playerSrc: string): string;
     /**
-     * Gets player ping.
+     * Gets player ping/latency.
      *
      * @param playerSrc - Player source/client ID (as string)
      * @returns Ping in milliseconds
@@ -64,20 +74,53 @@ export declare abstract class IPlayerServer {
      */
     abstract getEndpoint(playerSrc: string): string;
     /**
-     * Sets player routing bucket.
+     * 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 to the server.
+     * 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,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IPlayerServer = void 0;
+/**
+ * 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.
+ */
+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);
+    }
+}
+exports.IPlayerServer = IPlayerServer;

package/dist/adapters/contracts/types/identifier.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Generic player identifier structure.
+ *
+ * @remarks
+ * Platform-agnostic representation of player identifiers.
+ * Different platforms use different identifier systems:
+ * - FiveM: steam, license, discord, fivem, ip
+ * - RageMP: socialclub, ip
+ * - alt:V: socialclub, hwid, ip
+ */
+export interface PlayerIdentifier {
+    /**
+     * Identifier type.
+     * @example 'steam', 'license', 'discord', 'socialclub', 'hwid'
+     */
+    type: string;
+    /**
+     * Raw identifier value (without the type prefix).
+     * @example '110000100000001' (steam ID)
+     */
+    value: string;
+    /**
+     * Full identifier string as provided by the platform.
+     * @example 'steam:110000100000001'
+     */
+    raw: string;
+}
+/**
+ * Well-known identifier types across platforms.
+ */
+export declare const IdentifierTypes: {
+    readonly STEAM: "steam";
+    readonly IP: "ip";
+    readonly LICENSE: "license";
+    readonly LICENSE2: "license2";
+    readonly DISCORD: "discord";
+    readonly FIVEM: "fivem";
+    readonly XBL: "xbl";
+    readonly LIVE: "live";
+    readonly SOCIAL_CLUB: "socialclub";
+    readonly HWID: "hwid";
+    readonly ROCKSTAR: "rockstar";
+};
+export type IdentifierType = (typeof IdentifierTypes)[keyof typeof IdentifierTypes];
+/**
+ * Parse a raw identifier string into a PlayerIdentifier.
+ *
+ * @param raw - Raw identifier string (e.g., 'steam:110000100000001')
+ * @returns Parsed identifier or null if invalid format
+ */
+export declare function parseIdentifier(raw: string): PlayerIdentifier | null;
+/**
+ * Create a raw identifier string from type and value.
+ *
+ * @param type - Identifier type
+ * @param value - Identifier value
+ * @returns Raw identifier string
+ */
+export declare function createIdentifier(type: string, value: string): string;
+/**
+ * Find an identifier by type from a list.
+ *
+ * @param identifiers - List of identifiers
+ * @param type - Type to find
+ * @returns The identifier or undefined
+ */
+export declare function findIdentifierByType(identifiers: PlayerIdentifier[], type: string): PlayerIdentifier | undefined;

package/dist/adapters/contracts/types/identifier.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentifierTypes = void 0;
+exports.parseIdentifier = parseIdentifier;
+exports.createIdentifier = createIdentifier;
+exports.findIdentifierByType = findIdentifierByType;
+/**
+ * Well-known identifier types across platforms.
+ */
+exports.IdentifierTypes = {
+    // Common across multiple platforms
+    STEAM: 'steam',
+    IP: 'ip',
+    // FiveM specific
+    LICENSE: 'license',
+    LICENSE2: 'license2',
+    DISCORD: 'discord',
+    FIVEM: 'fivem',
+    XBL: 'xbl',
+    LIVE: 'live',
+    // RageMP / alt:V specific
+    SOCIAL_CLUB: 'socialclub',
+    HWID: 'hwid',
+    // RedM specific
+    ROCKSTAR: 'rockstar',
+};
+/**
+ * Parse a raw identifier string into a PlayerIdentifier.
+ *
+ * @param raw - Raw identifier string (e.g., 'steam:110000100000001')
+ * @returns Parsed identifier or null if invalid format
+ */
+function parseIdentifier(raw) {
+    const colonIndex = raw.indexOf(':');
+    if (colonIndex === -1) {
+        return null;
+    }
+    const type = raw.substring(0, colonIndex);
+    const value = raw.substring(colonIndex + 1);
+    if (!type || !value) {
+        return null;
+    }
+    return { type, value, raw };
+}
+/**
+ * Create a raw identifier string from type and value.
+ *
+ * @param type - Identifier type
+ * @param value - Identifier value
+ * @returns Raw identifier string
+ */
+function createIdentifier(type, value) {
+    return `${type}:${value}`;
+}
+/**
+ * Find an identifier by type from a list.
+ *
+ * @param identifiers - List of identifiers
+ * @param type - Type to find
+ * @returns The identifier or undefined
+ */
+function findIdentifierByType(identifiers, type) {
+    return identifiers.find((id) => id.type === type);
+}

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

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

package/dist/{kernel/shared/appearance → adapters/contracts/types}/index.js

@@ -14,4 +14,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./appearance.interface"), exports);
+__exportStar(require("./identifier"), exports);