@open-core/framework 0.1.0-alpha.1

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

@@ -0,0 +1,210 @@
+"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.ProgressService = void 0;
+const tsyringe_1 = require("tsyringe");
+/**
+ * Service for displaying progress bars/indicators.
+ */
+let ProgressService = class ProgressService {
+    constructor() {
+        this.state = null;
+        this.tickHandle = null;
+        this.callback = null;
+        this.propHandle = null;
+    }
+    /**
+     * Start a progress action.
+     *
+     * @param options - Progress options
+     * @returns Promise that resolves with true if completed, false if cancelled
+     */
+    async start(options) {
+        var _a;
+        if ((_a = this.state) === null || _a === void 0 ? void 0 : _a.active) {
+            return false;
+        }
+        return new Promise((resolve) => {
+            this.state = {
+                active: true,
+                progress: 0,
+                label: options.label,
+                startTime: GetGameTimer(),
+                duration: options.duration,
+                options,
+            };
+            this.callback = resolve;
+            this.startProgress();
+        });
+    }
+    /**
+     * Cancel the current progress.
+     */
+    cancel() {
+        var _a;
+        if (!((_a = this.state) === null || _a === void 0 ? void 0 : _a.active))
+            return;
+        this.cleanup(false);
+    }
+    /**
+     * Check if a progress is currently active.
+     */
+    isActive() {
+        var _a, _b;
+        return (_b = (_a = this.state) === null || _a === void 0 ? void 0 : _a.active) !== null && _b !== void 0 ? _b : false;
+    }
+    /**
+     * Get current progress percentage (0-100).
+     */
+    getProgress() {
+        var _a, _b;
+        return (_b = (_a = this.state) === null || _a === void 0 ? void 0 : _a.progress) !== null && _b !== void 0 ? _b : 0;
+    }
+    /**
+     * Get current progress state.
+     */
+    getState() {
+        return this.state;
+    }
+    async startProgress() {
+        var _a;
+        if (!this.state)
+            return;
+        const { options } = this.state;
+        const ped = PlayerPedId();
+        // Load and play animation if specified
+        if (options.animation) {
+            await this.loadAnimDict(options.animation.dict);
+            TaskPlayAnim(ped, options.animation.dict, options.animation.anim, 8.0, -8.0, options.duration, (_a = options.animation.flags) !== null && _a !== void 0 ? _a : 1, 0.0, false, false, false);
+        }
+        // Attach prop if specified
+        if (options.prop) {
+            await this.loadModel(options.prop.model);
+            const propHash = GetHashKey(options.prop.model);
+            const coords = GetEntityCoords(ped, true);
+            this.propHandle = CreateObject(propHash, coords[0], coords[1], coords[2], true, true, true);
+            AttachEntityToEntity(this.propHandle, ped, GetPedBoneIndex(ped, options.prop.bone), options.prop.offset.x, options.prop.offset.y, options.prop.offset.z, options.prop.rotation.x, options.prop.rotation.y, options.prop.rotation.z, true, true, false, true, 1, true);
+        }
+        // Start the tick
+        this.tickHandle = setTick(() => {
+            if (!this.state)
+                return;
+            const elapsed = GetGameTimer() - this.state.startTime;
+            this.state.progress = Math.min((elapsed / this.state.duration) * 100, 100);
+            // Handle controls
+            if (options.disableControls) {
+                DisableAllControlActions(0);
+            }
+            else {
+                if (options.disableMovement) {
+                    DisableControlAction(0, 30, true); // Move LR
+                    DisableControlAction(0, 31, true); // Move UD
+                    DisableControlAction(0, 21, true); // Sprint
+                    DisableControlAction(0, 22, true); // Jump
+                }
+                if (options.disableCombat) {
+                    DisableControlAction(0, 24, true); // Attack
+                    DisableControlAction(0, 25, true); // Aim
+                    DisableControlAction(0, 47, true); // Weapon
+                    DisableControlAction(0, 58, true); // Weapon
+                    DisableControlAction(0, 263, true); // Melee
+                    DisableControlAction(0, 264, true); // Melee
+                }
+            }
+            // Check for cancel
+            if (options.canCancel && IsControlJustPressed(0, 200)) {
+                // ESC key
+                this.cancel();
+                return;
+            }
+            // Draw progress bar (native style)
+            this.drawProgressBar();
+            // Check completion
+            if (elapsed >= this.state.duration) {
+                this.cleanup(true);
+            }
+        });
+    }
+    drawProgressBar() {
+        if (!this.state)
+            return;
+        const { label, progress, options } = this.state;
+        if (options.useCircular) {
+            // Circular progress indicator
+            BeginTextCommandBusyspinnerOn('STRING');
+            AddTextComponentString(label);
+            EndTextCommandBusyspinnerOn(4);
+        }
+        else {
+            // Bar style progress
+            const barWidth = 0.15;
+            const barHeight = 0.015;
+            const x = 0.5 - barWidth / 2;
+            const y = 0.88;
+            // Background
+            DrawRect(0.5, y + barHeight / 2, barWidth, barHeight, 0, 0, 0, 180);
+            // Progress fill
+            const fillWidth = (barWidth * progress) / 100;
+            DrawRect(x + fillWidth / 2, y + barHeight / 2, fillWidth, barHeight, 255, 255, 255, 255);
+            // Label
+            SetTextFont(4);
+            SetTextScale(0.35, 0.35);
+            SetTextColour(255, 255, 255, 255);
+            SetTextCentre(true);
+            BeginTextCommandDisplayText('STRING');
+            AddTextComponentString(`${label} (${Math.floor(progress)}%)`);
+            EndTextCommandDisplayText(0.5, y - 0.03);
+        }
+    }
+    cleanup(completed) {
+        var _a, _b;
+        const ped = PlayerPedId();
+        // Stop animation
+        if ((_a = this.state) === null || _a === void 0 ? void 0 : _a.options.animation) {
+            StopAnimTask(ped, this.state.options.animation.dict, this.state.options.animation.anim, 1.0);
+        }
+        // Remove prop
+        if (this.propHandle) {
+            DeleteEntity(this.propHandle);
+            this.propHandle = null;
+        }
+        // Clear tick
+        if (this.tickHandle !== null) {
+            clearTick(this.tickHandle);
+            this.tickHandle = null;
+        }
+        // Clear busy spinner
+        if ((_b = this.state) === null || _b === void 0 ? void 0 : _b.options.useCircular) {
+            BusyspinnerOff();
+        }
+        // Reset state
+        this.state = null;
+        // Invoke callback
+        if (this.callback) {
+            this.callback(completed);
+            this.callback = null;
+        }
+    }
+    async loadAnimDict(dict) {
+        RequestAnimDict(dict);
+        while (!HasAnimDictLoaded(dict)) {
+            await new Promise((r) => setTimeout(r, 0));
+        }
+    }
+    async loadModel(model) {
+        const hash = GetHashKey(model);
+        RequestModel(hash);
+        while (!HasModelLoaded(hash)) {
+            await new Promise((r) => setTimeout(r, 0));
+        }
+    }
+};
+exports.ProgressService = ProgressService;
+exports.ProgressService = ProgressService = __decorate([
+    (0, tsyringe_1.injectable)()
+], ProgressService);

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 {};

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

@@ -0,0 +1,261 @@
+"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.SpawnService = void 0;
+const tsyringe_1 = require("tsyringe");
+const shared_1 = require("../../shared");
+const appearance_service_1 = require("./appearance.service");
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const NETWORK_TIMEOUT_MS = 15000;
+const PED_TIMEOUT_MS = 10000;
+const COLLISION_TIMEOUT_MS = 7000;
+/**
+ * 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.
+ */
+let SpawnService = class SpawnService {
+    constructor(appearanceService) {
+        this.appearanceService = appearanceService;
+        this.spawned = false;
+        this.spawning = false;
+    }
+    async init() {
+        shared_1.loggers.spawn.debug('SpawnService initialized');
+    }
+    /**
+     * 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.
+     */
+    async spawn(position, model, heading = 0.0, options) {
+        if (this.spawning) {
+            shared_1.loggers.spawn.warn('Spawn requested while a spawn is already in progress');
+            return;
+        }
+        this.spawning = true;
+        try {
+            await this.ensureNetworkReady();
+            if (!IsScreenFadedOut() && !IsScreenFadingOut()) {
+                DoScreenFadeOut(500);
+                while (!IsScreenFadedOut()) {
+                    await delay(0);
+                }
+            }
+            this.closeLoadingScreens();
+            await this.setPlayerModel(model);
+            const ped = await this.ensurePed();
+            await this.applyAppearanceIfNeeded(ped, options === null || options === void 0 ? void 0 : options.appearance);
+            await this.ensureCollisionAt(position, ped);
+            NetworkResurrectLocalPlayer(position.x, position.y, position.z, heading, 0, false);
+            const finalPed = await this.ensurePed();
+            await this.setupPedForGameplay(finalPed);
+            await this.placePed(finalPed, position, heading);
+            this.spawned = true;
+            if (!IsScreenFadedIn() && !IsScreenFadingIn()) {
+                DoScreenFadeIn(500);
+            }
+            shared_1.loggers.spawn.info('Player spawned successfully (first spawn)', {
+                position: { x: position.x, y: position.y, z: position.z },
+                model,
+            });
+        }
+        catch (err) {
+            shared_1.loggers.spawn.error('Failed to spawn player', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+        finally {
+            this.spawning = false;
+        }
+    }
+    /**
+     * Teleports the player instantly to a new position.
+     * Does not change the model or resurrect the player.
+     * Safe for gameplay use.
+     */
+    async teleportTo(position, heading) {
+        const ped = await this.ensurePed();
+        await this.ensureCollisionAt(position, ped);
+        FreezeEntityPosition(ped, true);
+        SetEntityCoordsNoOffset(ped, position.x, position.y, position.z, false, false, false);
+        if (heading !== undefined) {
+            SetEntityHeading(ped, heading);
+        }
+        FreezeEntityPosition(ped, false);
+        shared_1.loggers.spawn.debug('Teleported', {
+            position: { x: position.x, y: position.y, z: position.z },
+            heading,
+        });
+    }
+    /**
+     * 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.
+     */
+    async respawn(position, heading = 0.0) {
+        const ped = await this.ensurePed();
+        await this.ensureCollisionAt(position, ped);
+        ClearPedTasksImmediately(ped);
+        SetEntityHealth(ped, GetEntityMaxHealth(ped));
+        NetworkResurrectLocalPlayer(position.x, position.y, position.z, heading, 0, false);
+        const finalPed = await this.ensurePed();
+        await this.setupPedForGameplay(finalPed);
+        await this.teleportTo(position, heading);
+        shared_1.loggers.spawn.info('Player respawned', {
+            position: { x: position.x, y: position.y, z: position.z },
+            heading,
+        });
+    }
+    /**
+     * Returns whether the player has completed their first spawn.
+     */
+    isSpawned() {
+        return this.spawned;
+    }
+    /**
+     * Allows other systems to wait until the player is fully spawned.
+     */
+    async waitUntilSpawned() {
+        while (!this.spawned) {
+            await delay(0);
+        }
+    }
+    async ensureNetworkReady() {
+        const start = GetGameTimer();
+        while (!NetworkIsSessionStarted()) {
+            if (GetGameTimer() - start > NETWORK_TIMEOUT_MS) {
+                shared_1.loggers.spawn.error('Network session did not start in time');
+                throw new Error('NETWORK_TIMEOUT');
+            }
+            await delay(0);
+        }
+    }
+    closeLoadingScreens() {
+        try {
+            ShutdownLoadingScreen();
+        }
+        catch (_a) { }
+        try {
+            ShutdownLoadingScreenNui();
+        }
+        catch (_b) { }
+    }
+    async setPlayerModel(model) {
+        const modelHash = GetHashKey(model);
+        if (!IsModelInCdimage(modelHash) || !IsModelValid(modelHash)) {
+            shared_1.loggers.spawn.error('Invalid model requested', { model });
+            throw new Error('MODEL_INVALID');
+        }
+        RequestModel(modelHash);
+        while (!HasModelLoaded(modelHash)) {
+            await delay(0);
+        }
+        SetPlayerModel(PlayerId(), modelHash);
+        SetModelAsNoLongerNeeded(modelHash);
+        const ped = PlayerPedId();
+        if (ped !== 0) {
+            SetPedDefaultComponentVariation(ped);
+        }
+        shared_1.loggers.spawn.debug('Player model set', { model, modelHash });
+    }
+    async ensurePed() {
+        const start = GetGameTimer();
+        let ped = PlayerPedId();
+        while (ped === 0) {
+            if (GetGameTimer() - start > PED_TIMEOUT_MS) {
+                shared_1.loggers.spawn.error('PlayerPedId() did not become valid in time');
+                throw new Error('PED_TIMEOUT');
+            }
+            await delay(0);
+            ped = PlayerPedId();
+        }
+        return ped;
+    }
+    async ensureCollisionAt(position, ped) {
+        RequestCollisionAtCoord(position.x, position.y, position.z);
+        const start = GetGameTimer();
+        while (!HasCollisionLoadedAroundEntity(ped)) {
+            if (GetGameTimer() - start > COLLISION_TIMEOUT_MS) {
+                shared_1.loggers.spawn.warn('Collision did not fully load around entity in time', {
+                    x: position.x,
+                    y: position.y,
+                    z: position.z,
+                });
+                break;
+            }
+            await delay(0);
+        }
+    }
+    async setupPedForGameplay(ped) {
+        SetEntityAsMissionEntity(ped, true, true);
+        ClearPedTasksImmediately(ped);
+        RemoveAllPedWeapons(ped, true);
+        ResetEntityAlpha(ped);
+        await delay(0);
+        SetEntityAlpha(ped, 255, false);
+        SetEntityVisible(ped, true, false);
+        SetEntityCollision(ped, true, true);
+        SetEntityInvincible(ped, false);
+        shared_1.loggers.spawn.debug('Ped prepared for gameplay', { ped });
+    }
+    async placePed(ped, position, heading) {
+        FreezeEntityPosition(ped, true);
+        SetEntityCoordsNoOffset(ped, position.x, position.y, position.z, false, false, false);
+        SetEntityHeading(ped, heading);
+        await delay(0);
+        FreezeEntityPosition(ped, false);
+    }
+    async applyAppearanceIfNeeded(ped, appearance) {
+        if (!appearance) {
+            SetPedDefaultComponentVariation(ped);
+            return;
+        }
+        if (!this.appearanceService.validateAppearance(appearance)) {
+            SetPedDefaultComponentVariation(ped);
+            return;
+        }
+        try {
+            await this.appearanceService.applyAppearance(ped, appearance);
+        }
+        catch (error) {
+            shared_1.loggers.spawn.error('Failed to apply appearance, using default variation', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            SetPedDefaultComponentVariation(ped);
+        }
+    }
+};
+exports.SpawnService = SpawnService;
+exports.SpawnService = SpawnService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [appearance_service_1.AppearanceService])
+], SpawnService);