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

package/README.md

@@ -1,11 +1,11 @@
-# OpenCore Framework
+# OpenCore Framework - Unstable beta ❗
 
 > **The robust TypeScript Engine for FiveM.**
 > Built on strong OOP principles, Layered Architecture, and Security-first design.
 > _Stop writing scripts; start engineering gameplay._
 
 [![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
-[![Version](https://img.shields.io/badge/beta-1.0.0-orange.svg)](https://github.com/newcore-network/opencore)
+[![Version](https://img.shields.io/badge/beta-1.0.3-orange.svg)](https://github.com/newcore-network/opencore)
 ![Tests](https://img.shields.io/badge/tests-265%20passing-brightgreen)
 ![Coverage](https://img.shields.io/badge/coverage-43%25-yellow)
 ![Core Decorators](https://img.shields.io/badge/core%20decorators-100%25-brightgreen)
@@ -325,6 +325,16 @@ opencore/
 
 ---
 
+## Available Modules
+
+A module is a library belonging to the OpenCore family, where you can take advantage of its functionality if you wish, and where we provide the foundation for building a specific system.
+
+- [Open-core Identity](https://github.com/newcore-network/opencore-identity): Flexible identity and permission system for OpenCore. Provides multiple authentication strategies, role management, and permission-based authorization through the framework's Principal system. [NPM](https://www.npmjs.com/package/@open-core/identity).
+
+```bash
+pnpm add @open-core/identity
+```
+
 ## 🤝 Contributing
 
 Contributions are welcome! Please ensure:

package/dist/client/client-bootstrap.js

@@ -5,33 +5,30 @@ const metadata_scanner_1 = require("../system/metadata.scanner");
 const client_container_1 = require("./client-container");
 const decorators_1 = require("./decorators");
 const player_loader_1 = require("./player/player.loader");
+const services_1 = require("./services");
 const processors_register_1 = require("./system/processors.register");
 const ui_bridge_1 = require("./ui-bridge");
 // Services
-const core_1 = require("./services/core");
-const ui_1 = require("./services/ui");
-const world_1 = require("./services/world");
-const streaming_1 = require("./services/streaming");
-const bootServices = [core_1.Spawner];
+const bootServices = [services_1.SpawnService];
 /**
  * Basic setup for client, for configs, decorators, containers... etc
  */
 function setSingletons() {
     // Core services
-    client_container_1.di.registerSingleton(core_1.Spawner, core_1.Spawner);
+    client_container_1.di.registerSingleton(services_1.SpawnService, services_1.SpawnService);
     // NUI
     client_container_1.di.registerSingleton(ui_bridge_1.NuiBridge, ui_bridge_1.NuiBridge);
     // UI services
-    client_container_1.di.registerSingleton(ui_1.NotificationService, ui_1.NotificationService);
-    client_container_1.di.registerSingleton(ui_1.TextUIService, ui_1.TextUIService);
-    client_container_1.di.registerSingleton(ui_1.ProgressService, ui_1.ProgressService);
+    client_container_1.di.registerSingleton(services_1.NotificationService, services_1.NotificationService);
+    client_container_1.di.registerSingleton(services_1.TextUIService, services_1.TextUIService);
+    client_container_1.di.registerSingleton(services_1.ProgressService, services_1.ProgressService);
     // World services
-    client_container_1.di.registerSingleton(world_1.MarkerService, world_1.MarkerService);
-    client_container_1.di.registerSingleton(world_1.BlipService, world_1.BlipService);
-    client_container_1.di.registerSingleton(world_1.VehicleService, world_1.VehicleService);
-    client_container_1.di.registerSingleton(world_1.PedService, world_1.PedService);
+    client_container_1.di.registerSingleton(services_1.MarkerService, services_1.MarkerService);
+    client_container_1.di.registerSingleton(services_1.BlipService, services_1.BlipService);
+    client_container_1.di.registerSingleton(services_1.VehicleService, services_1.VehicleService);
+    client_container_1.di.registerSingleton(services_1.PedService, services_1.PedService);
     // Streaming services
-    client_container_1.di.registerSingleton(streaming_1.StreamingService, streaming_1.StreamingService);
+    client_container_1.di.registerSingleton(services_1.StreamingService, services_1.StreamingService);
 }
 async function bootstraper() {
     for (const Service of bootServices) {

package/dist/client/client-core.d.ts

@@ -1,18 +1 @@
-import { NuiBridge } from './ui-bridge';
-import { Spawner } from './services/core';
-import { NotificationService, TextUIService, ProgressService } from './services/ui';
-import { MarkerService, BlipService, VehicleService, PedService } from './services/world';
-import { StreamingService } from './services/streaming';
 export declare function init(): Promise<void>;
-export declare const services: {
-    readonly spawner: Spawner;
-    readonly nui: NuiBridge<Record<string, any>, Record<string, any>>;
-    readonly notifications: NotificationService;
-    readonly textUI: TextUIService;
-    readonly progress: ProgressService;
-    readonly markers: MarkerService;
-    readonly blips: BlipService;
-    readonly vehicles: VehicleService;
-    readonly peds: PedService;
-    readonly streaming: StreamingService;
-};

package/dist/client/client-core.js

@@ -1,52 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.services = void 0;
 exports.init = init;
 const client_bootstrap_1 = require("./client-bootstrap");
-const client_container_1 = require("./client-container");
-const ui_bridge_1 = require("./ui-bridge");
-// Services
-const core_1 = require("./services/core");
-const ui_1 = require("./services/ui");
-const world_1 = require("./services/world");
-const streaming_1 = require("./services/streaming");
 async function init() {
     await (0, client_bootstrap_1.initClientCore)();
 }
-exports.services = {
-    // Core
-    get spawner() {
-        return client_container_1.di.resolve(core_1.Spawner);
-    },
-    // NUI
-    get nui() {
-        return client_container_1.di.resolve(ui_bridge_1.NuiBridge);
-    },
-    // UI
-    get notifications() {
-        return client_container_1.di.resolve(ui_1.NotificationService);
-    },
-    get textUI() {
-        return client_container_1.di.resolve(ui_1.TextUIService);
-    },
-    get progress() {
-        return client_container_1.di.resolve(ui_1.ProgressService);
-    },
-    // World
-    get markers() {
-        return client_container_1.di.resolve(world_1.MarkerService);
-    },
-    get blips() {
-        return client_container_1.di.resolve(world_1.BlipService);
-    },
-    get vehicles() {
-        return client_container_1.di.resolve(world_1.VehicleService);
-    },
-    get peds() {
-        return client_container_1.di.resolve(world_1.PedService);
-    },
-    // Streaming
-    get streaming() {
-        return client_container_1.di.resolve(streaming_1.StreamingService);
-    },
-};

package/dist/client/controllers/spawner.controller.d.ts

@@ -0,0 +1,12 @@
+import { Vector3 } from '../../utils';
+import { SpawnService } from '../services';
+export declare class SpawnerController {
+    private readonly spawnService;
+    constructor(spawnService: SpawnService);
+    handleSpawn(data: {
+        position: Vector3;
+        model: string;
+    }): Promise<void>;
+    handleRespawn(position: Vector3, heading?: number): Promise<void>;
+    handleTeleport(position: Vector3, heading?: number): Promise<void>;
+}

package/dist/client/controllers/spawner.controller.js

@@ -0,0 +1,51 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpawnerController = void 0;
+const decorators_1 = require("../decorators");
+const services_1 = require("../services");
+let SpawnerController = class SpawnerController {
+    constructor(spawnService) {
+        this.spawnService = spawnService;
+    }
+    async handleSpawn(data) {
+        await this.spawnService.spawn(data.position, data.model);
+    }
+    async handleRespawn(position, heading = 0.0) {
+        await this.spawnService.respawn(position, heading);
+    }
+    async handleTeleport(position, heading) {
+        await this.spawnService.teleportTo(position, heading);
+    }
+};
+exports.SpawnerController = SpawnerController;
+__decorate([
+    (0, decorators_1.OnNet)('opencore:spawner:spawn'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SpawnerController.prototype, "handleSpawn", null);
+__decorate([
+    (0, decorators_1.OnNet)('opencore:spawner:respawn'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], SpawnerController.prototype, "handleRespawn", null);
+__decorate([
+    (0, decorators_1.OnNet)('opencore:spawner:teleport'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Number]),
+    __metadata("design:returntype", Promise)
+], SpawnerController.prototype, "handleTeleport", null);
+exports.SpawnerController = SpawnerController = __decorate([
+    (0, decorators_1.Controller)(),
+    __metadata("design:paramtypes", [services_1.SpawnService])
+], SpawnerController);

package/dist/client/index.d.ts

@@ -4,3 +4,4 @@ export * from './player/player';
 export * from './ui-bridge';
 export * from './services';
 export * from './types';
+import './controllers/spawner.controller';

package/dist/client/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./player/player"), exports);
 __exportStar(require("./ui-bridge"), exports);
 __exportStar(require("./services"), exports);
 __exportStar(require("./types"), exports);
+require("./controllers/spawner.controller");

package/dist/client/interfaces/appearance.interface.d.ts

@@ -0,0 +1,19 @@
+export interface PlayerAppearance {
+    components?: Record<number, {
+        drawable: number;
+        texture: number;
+    }>;
+    props?: Record<number, {
+        drawable: number;
+        texture: number;
+    }>;
+    faceFeatures?: Record<number, number>;
+    headBlend?: {
+        shapeFirst: number;
+        shapeSecond: number;
+        shapeMix: number;
+        skinFirst: number;
+        skinSecond: number;
+        skinMix: number;
+    };
+}

package/dist/client/interfaces/appearance.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/client/services/appearance.service.d.ts

@@ -0,0 +1,6 @@
+import { PlayerAppearance } from '../interfaces/appearance.interface';
+export declare class AppearanceService {
+    applyAppearance(ped: number, appearance: PlayerAppearance): Promise<void>;
+    getAppearance(ped: number): Promise<PlayerAppearance>;
+    validateAppearance(appearance: Partial<PlayerAppearance>): boolean;
+}

package/dist/client/services/appearance.service.js

@@ -0,0 +1,89 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppearanceService = void 0;
+const tsyringe_1 = require("tsyringe");
+let AppearanceService = class AppearanceService {
+    async applyAppearance(ped, appearance) {
+        if (appearance.components) {
+            for (const [componentId, data] of Object.entries(appearance.components)) {
+                SetPedComponentVariation(ped, parseInt(componentId), data.drawable, data.texture, 2);
+            }
+        }
+        if (appearance.props) {
+            for (const [propId, data] of Object.entries(appearance.props)) {
+                if (data.drawable === -1) {
+                    ClearPedProp(ped, parseInt(propId));
+                }
+                else {
+                    SetPedPropIndex(ped, parseInt(propId), data.drawable, data.texture, true);
+                }
+            }
+        }
+        if (appearance.faceFeatures) {
+            for (const [index, value] of Object.entries(appearance.faceFeatures)) {
+                SetPedFaceFeature(ped, parseInt(index), value);
+            }
+        }
+        if (appearance.headBlend) {
+            const { shapeFirst, shapeSecond, shapeMix, skinFirst, skinSecond, skinMix } = appearance.headBlend;
+            SetPedHeadBlendData(ped, shapeFirst, shapeSecond, 0, skinFirst, skinSecond, 0, shapeMix, skinMix, 0, false);
+        }
+    }
+    async getAppearance(ped) {
+        const appearance = {
+            components: {},
+            props: {},
+            faceFeatures: {},
+        };
+        // Components (0–11)
+        for (let i = 0; i <= 11; i++) {
+            const drawable = GetPedDrawableVariation(ped, i);
+            const texture = GetPedTextureVariation(ped, i);
+            if (drawable !== -1) {
+                appearance.components[i] = { drawable, texture };
+            }
+        }
+        // Props (0–7)
+        for (let i = 0; i <= 7; i++) {
+            const drawable = GetPedPropIndex(ped, i);
+            const texture = GetPedPropTextureIndex(ped, i);
+            if (drawable !== -1) {
+                appearance.props[i] = { drawable, texture };
+            }
+        }
+        return appearance;
+    }
+    validateAppearance(appearance) {
+        if (!appearance)
+            return false;
+        if (appearance.components) {
+            for (const [id, data] of Object.entries(appearance.components)) {
+                const componentId = parseInt(id);
+                if (isNaN(componentId) || componentId < 0 || componentId > 11)
+                    return false;
+                if (data.drawable === undefined || data.texture === undefined)
+                    return false;
+            }
+        }
+        if (appearance.props) {
+            for (const [id, data] of Object.entries(appearance.props)) {
+                const propId = parseInt(id);
+                if (isNaN(propId) || propId < 0 || propId > 7)
+                    return false;
+                if (data.drawable === undefined || data.texture === undefined)
+                    return false;
+            }
+        }
+        return true;
+    }
+};
+exports.AppearanceService = AppearanceService;
+exports.AppearanceService = AppearanceService = __decorate([
+    (0, tsyringe_1.injectable)()
+], AppearanceService);

package/dist/client/services/{world/blip.service.d.ts → blip.service.d.ts}

@@ -1,4 +1,4 @@
-import type { Vector3 } from '../../../utils';
+import type { Vector3 } from '../../utils';
 export interface BlipOptions {
     /** Blip sprite ID (icon) */
     sprite?: number;

package/dist/client/services/index.d.ts

@@ -1,4 +1,9 @@
-export * from './core';
-export * from './ui';
-export * from './world';
-export * from './streaming';
+export * from './spawn.service';
+export * from './blip.service';
+export * from './vehicle.service';
+export * from './ped.service';
+export * from './streaming.service';
+export * from './notification.service';
+export * from './progress.service';
+export * from './marker.service';
+export * from './textui.service';

package/dist/client/services/index.js

@@ -14,11 +14,12 @@ 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 });
-// Core services
-__exportStar(require("./core"), exports);
-// UI services
-__exportStar(require("./ui"), exports);
-// World services
-__exportStar(require("./world"), exports);
-// Streaming services
-__exportStar(require("./streaming"), exports);
+__exportStar(require("./spawn.service"), exports);
+__exportStar(require("./blip.service"), exports);
+__exportStar(require("./vehicle.service"), exports);
+__exportStar(require("./ped.service"), exports);
+__exportStar(require("./streaming.service"), exports);
+__exportStar(require("./notification.service"), exports);
+__exportStar(require("./progress.service"), exports);
+__exportStar(require("./marker.service"), exports);
+__exportStar(require("./textui.service"), exports);

package/dist/client/services/{world/marker.service.d.ts → marker.service.d.ts}

@@ -1,4 +1,4 @@
-import type { Vector3 } from '../../../utils';
+import type { Vector3 } from '../../utils';
 export interface MarkerOptions {
     /** Marker type (0-43) */
     type?: number;

package/dist/client/services/{world/ped.service.d.ts → ped.service.d.ts}

@@ -1,4 +1,4 @@
-import type { Vector3 } from '../../../utils';
+import type { Vector3 } from '../../utils';
 export interface PedSpawnOptions {
     /** Model name or hash */
     model: string;

package/dist/client/services/spawn.service.d.ts

@@ -0,0 +1,73 @@
+import { Vector3 } from '../../utils';
+import { AppearanceService } from './appearance.service';
+import { PlayerAppearance } from '../interfaces/appearance.interface';
+interface SpawnOptions {
+    /** Optional: Apply complete character appearance (RP clothing, face, props, tattoos...) */
+    appearance?: PlayerAppearance;
+}
+/**
+ * Handles all player spawning logic on the client.
+ *
+ * This service manages the complete lifecycle of a player spawn:
+ * - Waiting for the network session
+ * - Loading and applying the player model
+ * - Ensuring collision and world data is ready
+ * - Resurrecting the player cleanly
+ * - Applying default ped components for freemode models
+ * - Fading the screen in/out during transitions
+ *
+ * The service is designed to be robust, predictable, and safe for any gamemode.
+ */
+export declare class SpawnService {
+    private appearanceService;
+    private spawned;
+    private spawning;
+    constructor(appearanceService: AppearanceService);
+    init(): Promise<void>;
+    /**
+     * Performs the first spawn of the player.
+     *
+     * This method handles:
+     * - Fade out
+     * - Closing loading screens
+     * - Setting the player model
+     * - Ensuring the ped exists
+     * - Ensuring collision is loaded
+     * - Resurrecting the player
+     * - Preparing the ped for gameplay
+     * - Placing the player at the desired position
+     * - Fade in
+     *
+     * It should only be called once when the player joins.
+     */
+    spawn(position: Vector3, model: string, heading?: number, options?: SpawnOptions): Promise<void>;
+    /**
+     * Teleports the player instantly to a new position.
+     * Does not change the model or resurrect the player.
+     * Safe for gameplay use.
+     */
+    teleportTo(position: Vector3, heading?: number): Promise<void>;
+    /**
+     * Respawns the player after death or a gameplay event.
+     * Restores health, resurrects the player, loads collision,
+     * prepares the ped and teleports them to the desired location.
+     */
+    respawn(position: Vector3, heading?: number): Promise<void>;
+    /**
+     * Returns whether the player has completed their first spawn.
+     */
+    isSpawned(): boolean;
+    /**
+     * Allows other systems to wait until the player is fully spawned.
+     */
+    waitUntilSpawned(): Promise<void>;
+    private ensureNetworkReady;
+    private closeLoadingScreens;
+    private setPlayerModel;
+    private ensurePed;
+    private ensureCollisionAt;
+    private setupPedForGameplay;
+    private placePed;
+    private applyAppearanceIfNeeded;
+}
+export {};