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

package/dist/adapters/cfx/cfx-platform.js

@@ -0,0 +1,85 @@
+import { IEngineEvents } from '../contracts/IEngineEvents';
+import { IExports } from '../contracts/IExports';
+import { IHasher } from '../contracts/IHasher';
+import { IPlatformCapabilities } from '../contracts/IPlatformCapabilities';
+import { IPlayerInfo } from '../contracts/IPlayerInfo';
+import { IResourceInfo } from '../contracts/IResourceInfo';
+import { ITick } from '../contracts/ITick';
+import { IEntityServer } from '../contracts/server/IEntityServer';
+import { IPedServer } from '../contracts/server/IPedServer';
+import { IPedAppearanceServer } from '../contracts/server/IPedAppearanceServer';
+import { IPlayerServer } from '../contracts/server/IPlayerServer';
+import { IVehicleServer } from '../contracts/server/IVehicleServer';
+import { EventsAPI } from '../contracts/transport/events.api';
+import { MessagingTransport } from '../contracts/transport/messaging.transport';
+import { RpcAPI } from '../contracts/transport/rpc.api';
+import { detectCfxGameProfile, isCfxRuntime } from './runtime-profile';
+export const CfxPlatform = {
+    name: 'cfx',
+    priority: 100,
+    detect() {
+        return isCfxRuntime();
+    },
+    async register(container) {
+        const profile = detectCfxGameProfile();
+        const [{ FiveMMessagingTransport }, { FiveMEngineEvents }, { FiveMExports }, { FiveMResourceInfo }, { FiveMTick }, { FiveMPlayerInfo }, { FiveMEntityServer }, { FiveMPedServer }, { FiveMVehicleServer }, { FiveMPlayerServer }, { FiveMHasher }, { FiveMPedAppearanceServerAdapter }, { NodePedAppearanceServer }, { CfxCapabilities },] = await Promise.all([
+            import('../fivem/transport/adapter'),
+            import('../fivem/fivem-engine-events'),
+            import('../fivem/fivem-exports'),
+            import('../fivem/fivem-resourceinfo'),
+            import('../fivem/fivem-tick'),
+            import('../fivem/fivem-playerinfo'),
+            import('../fivem/fivem-entity-server'),
+            import('../fivem/fivem-ped-server'),
+            import('../fivem/fivem-vehicle-server'),
+            import('../fivem/fivem-player-server'),
+            import('../fivem/fivem-hasher'),
+            import('../fivem/fivem-ped-appearance-server'),
+            import('../node/node-ped-appearance-server'),
+            import('./cfx-capabilities'),
+        ]);
+        if (!container.isRegistered(IPlatformCapabilities)) {
+            container.registerSingleton(IPlatformCapabilities, CfxCapabilities);
+        }
+        if (!container.isRegistered(MessagingTransport)) {
+            const transport = new FiveMMessagingTransport();
+            container.registerInstance(MessagingTransport, transport);
+            container.registerInstance(EventsAPI, transport.events);
+            container.registerInstance(RpcAPI, transport.rpc);
+        }
+        if (!container.isRegistered(IEngineEvents)) {
+            container.registerSingleton(IEngineEvents, FiveMEngineEvents);
+        }
+        if (!container.isRegistered(IExports)) {
+            container.registerSingleton(IExports, FiveMExports);
+        }
+        if (!container.isRegistered(IResourceInfo)) {
+            container.registerSingleton(IResourceInfo, FiveMResourceInfo);
+        }
+        if (!container.isRegistered(ITick)) {
+            container.registerSingleton(ITick, FiveMTick);
+        }
+        if (!container.isRegistered(IPlayerInfo)) {
+            container.registerSingleton(IPlayerInfo, FiveMPlayerInfo);
+        }
+        if (!container.isRegistered(IEntityServer)) {
+            container.registerSingleton(IEntityServer, FiveMEntityServer);
+        }
+        if (!container.isRegistered(IPedServer)) {
+            container.registerSingleton(IPedServer, FiveMPedServer);
+        }
+        if (!container.isRegistered(IVehicleServer)) {
+            container.registerSingleton(IVehicleServer, FiveMVehicleServer);
+        }
+        if (!container.isRegistered(IPlayerServer)) {
+            container.registerSingleton(IPlayerServer, FiveMPlayerServer);
+        }
+        if (!container.isRegistered(IHasher)) {
+            container.registerSingleton(IHasher, FiveMHasher);
+        }
+        if (!container.isRegistered(IPedAppearanceServer)) {
+            const appearanceImpl = profile === 'rdr3' ? NodePedAppearanceServer : FiveMPedAppearanceServerAdapter;
+            container.registerSingleton(IPedAppearanceServer, appearanceImpl);
+        }
+    },
+};

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

@@ -0,0 +1,3 @@
+export { CfxCapabilities } from './cfx-capabilities';
+export { CfxPlatform } from './cfx-platform';
+export { detectCfxGameProfile, isCfxRuntime } from './runtime-profile';

package/dist/adapters/cfx/index.js

@@ -0,0 +1,3 @@
+export { CfxCapabilities } from './cfx-capabilities';
+export { CfxPlatform } from './cfx-platform';
+export { detectCfxGameProfile, isCfxRuntime } from './runtime-profile';

package/dist/adapters/cfx/runtime-profile.d.ts

@@ -0,0 +1,3 @@
+export type CfxGameProfile = 'gta5' | 'rdr3' | 'common';
+export declare function isCfxRuntime(): boolean;
+export declare function detectCfxGameProfile(): CfxGameProfile;

package/dist/adapters/cfx/runtime-profile.js

@@ -0,0 +1,37 @@
+const RDR3_HINTS = ['rdr3', 'redm', 'rdr'];
+const GTA5_HINTS = ['gta5', 'fivem', 'gta'];
+function normalizeGameName(value) {
+    if (typeof value !== 'string')
+        return '';
+    return value.trim().toLowerCase();
+}
+function detectFromName(gameName) {
+    if (!gameName)
+        return 'common';
+    if (RDR3_HINTS.some((hint) => gameName.includes(hint)))
+        return 'rdr3';
+    if (GTA5_HINTS.some((hint) => gameName.includes(hint)))
+        return 'gta5';
+    return 'common';
+}
+export function isCfxRuntime() {
+    return typeof globalThis.GetCurrentResourceName === 'function';
+}
+export function detectCfxGameProfile() {
+    const convar = globalThis.GetConvar;
+    if (typeof convar === 'function') {
+        const override = normalizeGameName(convar('opencore:gameProfile', ''));
+        const profile = detectFromName(override);
+        if (profile !== 'common') {
+            return profile;
+        }
+    }
+    const getGameName = globalThis.GetGameName;
+    if (typeof getGameName === 'function') {
+        const profile = detectFromName(normalizeGameName(getGameName()));
+        if (profile !== 'common') {
+            return profile;
+        }
+    }
+    return 'common';
+}

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

@@ -0,0 +1,20 @@
+export declare abstract class IEngineEvents {
+    /**
+     * Registers a handler for a local (server-side) event.
+     *
+     * @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;
+    /**
+     * Emits a local event.
+     *
+     * @remarks
+     * This is for server-to-server communication (between resources).
+     * For client-server communication, use EventsAPI instead.
+     *
+     * @param eventName - The event name to emit
+     * @param args - Arguments to pass to event handlers
+     */
+    abstract emit(eventName: string, ...args: any[]): void;
+}

package/dist/adapters/contracts/IEngineEvents.js

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

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

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

package/dist/adapters/contracts/IExports.js

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

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

@@ -0,0 +1,15 @@
+/**
+ * Hash utility adapter.
+ *
+ * @remarks
+ * Abstracts hash functions like GetHashKey.
+ */
+export declare abstract class IHasher {
+    /**
+     * Gets the hash key for a string (joaat hash).
+     *
+     * @param str - String to hash
+     * @returns Hash value
+     */
+    abstract getHashKey(str: string): number;
+}

package/dist/adapters/contracts/IHasher.js

@@ -0,0 +1,8 @@
+/**
+ * Hash utility adapter.
+ *
+ * @remarks
+ * Abstracts hash functions like GetHashKey.
+ */
+export class IHasher {
+}

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 (CitizenFX, RageMP, alt:V, etc.)
+ */
+export declare abstract class IPlatformCapabilities {
+    /**
+     * Unique identifier for the platform.
+     * @example 'cfx', 'ragemp', 'altv', 'redm'
+     */
+    abstract readonly platformName: string;
+    /**
+     * Human-readable display name.
+     * @example 'CitizenFX', '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,27 @@
+/**
+ * Platform capabilities contract.
+ *
+ * @remarks
+ * Defines what features a platform supports, allowing runtime
+ * feature detection and graceful degradation across different
+ * game engines (CitizenFX, RageMP, alt:V, etc.)
+ */
+export class IPlatformCapabilities {
+}
+/**
+ * Well-known feature identifiers for cross-platform compatibility.
+ */
+export const 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

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

package/dist/adapters/contracts/IPlayerInfo.js

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

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

@@ -0,0 +1,4 @@
+export declare abstract class IResourceInfo {
+    abstract getCurrentResourceName(): string;
+    abstract getCurrentResourcePath(): string;
+}

package/dist/adapters/contracts/IResourceInfo.js

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

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

@@ -0,0 +1,10 @@
+/**
+ * Platform-agnostic tick/interval abstraction
+ */
+export declare abstract class ITick {
+    /**
+     * Registers a recurring handler that executes on each tick/interval
+     * @param handler - The function to execute
+     */
+    abstract setTick(handler: () => void | Promise<void>): void;
+}

package/dist/adapters/contracts/ITick.js

@@ -0,0 +1,5 @@
+/**
+ * Platform-agnostic tick/interval abstraction
+ */
+export class ITick {
+}

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

@@ -0,0 +1,206 @@
+import { HeadBlendData } from '../../../kernel/shared/player-appearance.types';
+/**
+ * Client-side ped appearance operations adapter.
+ *
+ * @remarks
+ * Abstracts FiveM ped appearance natives for client-side operations.
+ * Allows the runtime to work without direct FiveM dependencies.
+ *
+ * Most appearance natives are client-only (headBlend, faceFeatures, overlays, tattoos).
+ * This adapter provides a unified interface for all appearance operations.
+ */
+export declare abstract class IPedAppearanceClient {
+    /**
+     * 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;
+    /**
+     * Sets the ped's head blend data for facial structure.
+     *
+     * @remarks
+     * This must be called before setting face features, overlays, or overlay colors.
+     *
+     * @param ped - Ped entity handle
+     * @param data - Head blend configuration
+     */
+    abstract setHeadBlendData(ped: number, data: HeadBlendData): void;
+    /**
+     * Sets a face feature morph value.
+     *
+     * @remarks
+     * SetPedHeadBlendData must be called before this.
+     *
+     * @param ped - Ped entity handle
+     * @param index - Feature index (0-19)
+     * @param scale - Scale value (-1.0 to 1.0)
+     */
+    abstract setFaceFeature(ped: number, index: number, scale: number): void;
+    /**
+     * Sets a head overlay (makeup, facial hair, etc.).
+     *
+     * @remarks
+     * SetPedHeadBlendData must be called before this.
+     *
+     * @param ped - Ped entity handle
+     * @param overlayId - Overlay ID (0-12)
+     * @param index - Overlay variation index (255 to disable)
+     * @param opacity - Opacity (0.0-1.0)
+     */
+    abstract setHeadOverlay(ped: number, overlayId: number, index: number, opacity: number): void;
+    /**
+     * Sets the color for a head overlay.
+     *
+     * @remarks
+     * Must be called after SetPedHeadOverlay.
+     *
+     * @param ped - Ped entity handle
+     * @param overlayId - Overlay ID (0-12)
+     * @param colorType - Color type (0: default, 1: hair, 2: makeup)
+     * @param colorId - Primary color ID
+     * @param secondColorId - Secondary color ID
+     */
+    abstract setHeadOverlayColor(ped: number, overlayId: number, colorType: number, colorId: number, secondColorId: number): void;
+    /**
+     * Sets the ped's hair color.
+     *
+     * @param ped - Ped entity handle
+     * @param colorId - Primary hair color ID
+     * @param highlightColorId - Highlight color ID
+     */
+    abstract setHairColor(ped: number, colorId: number, highlightColorId: number): void;
+    /**
+     * Sets the ped's eye color.
+     *
+     * @param ped - Ped entity handle
+     * @param index - Eye color index (0-31)
+     */
+    abstract setEyeColor(ped: number, index: number): void;
+    /**
+     * Adds a decoration (tattoo) to the ped.
+     *
+     * @param ped - Ped entity handle
+     * @param collectionHash - Collection name hash
+     * @param overlayHash - Overlay name hash
+     */
+    abstract addDecoration(ped: number, collectionHash: number, overlayHash: number): void;
+    /**
+     * Clears all decorations (tattoos) from the ped.
+     *
+     * @param ped - Ped entity handle
+     */
+    abstract clearDecorations(ped: number): void;
+    /**
+     * Gets the drawable variation for a component.
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @returns Drawable index
+     */
+    abstract getDrawableVariation(ped: number, componentId: number): number;
+    /**
+     * Gets the texture variation for a component.
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @returns Texture index
+     */
+    abstract getTextureVariation(ped: number, componentId: number): number;
+    /**
+     * Gets the prop index for a prop slot.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @returns Prop drawable index (-1 if none)
+     */
+    abstract getPropIndex(ped: number, propId: number): number;
+    /**
+     * Gets the prop texture index.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @returns Prop texture index
+     */
+    abstract getPropTextureIndex(ped: number, propId: number): number;
+    /**
+     * Gets the number of drawable variations for a component.
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @returns Number of available drawables
+     */
+    abstract getNumDrawableVariations(ped: number, componentId: number): number;
+    /**
+     * Gets the number of texture variations for a component drawable.
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @param drawable - Drawable index
+     * @returns Number of available textures
+     */
+    abstract getNumTextureVariations(ped: number, componentId: number, drawable: number): number;
+    /**
+     * Gets the number of drawable variations for a prop.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @returns Number of available prop drawables
+     */
+    abstract getNumPropDrawableVariations(ped: number, propId: number): number;
+    /**
+     * Gets the number of texture variations for a prop drawable.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @param drawable - Drawable index
+     * @returns Number of available textures
+     */
+    abstract getNumPropTextureVariations(ped: number, propId: number, drawable: number): number;
+    /**
+     * Gets the number of overlay values for an overlay type.
+     *
+     * @param overlayId - Overlay ID (0-12)
+     * @returns Number of available overlay variations
+     */
+    abstract getNumOverlayValues(overlayId: number): number;
+    /**
+     * Gets the number of hair colors available.
+     *
+     * @returns Number of hair colors
+     */
+    abstract getNumHairColors(): number;
+    /**
+     * Gets the number of makeup colors available.
+     *
+     * @returns Number of makeup colors
+     */
+    abstract getNumMakeupColors(): number;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Client-side ped appearance operations adapter.
+ *
+ * @remarks
+ * Abstracts FiveM ped appearance natives for client-side operations.
+ * Allows the runtime to work without direct FiveM dependencies.
+ *
+ * Most appearance natives are client-only (headBlend, faceFeatures, overlays, tattoos).
+ * This adapter provides a unified interface for all appearance operations.
+ */
+export class IPedAppearanceClient {
+}

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

@@ -0,0 +1,2 @@
+export * from './transport/events.api';
+export * from './transport/rpc.api';

package/dist/adapters/contracts/index.js

@@ -0,0 +1,3 @@
+// Transport API
+export * from './transport/events.api';
+export * from './transport/rpc.api';