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

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

@@ -0,0 +1,255 @@
+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);
+};
+import { injectable } from 'tsyringe';
+import { loggers } from '../../../kernel';
+import { AppearanceService } from './appearance.service';
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const NETWORK_TIMEOUT_MS = 15_000;
+const PED_TIMEOUT_MS = 10_000;
+const COLLISION_TIMEOUT_MS = 7_000;
+/**
+ * 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 {
+    appearanceService;
+    spawned = false;
+    spawning = false;
+    constructor(appearanceService) {
+        this.appearanceService = appearanceService;
+    }
+    async init() {
+        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) {
+            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?.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);
+            }
+            loggers.spawn.info('Player spawned successfully (first spawn)', {
+                position: { x: position.x, y: position.y, z: position.z },
+                model,
+            });
+        }
+        catch (err) {
+            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);
+    }
+    /**
+     * 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);
+        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) {
+                loggers.spawn.error('Network session did not start in time');
+                throw new Error('NETWORK_TIMEOUT');
+            }
+            await delay(0);
+        }
+    }
+    closeLoadingScreens() {
+        try {
+            ShutdownLoadingScreen();
+        }
+        catch { }
+        try {
+            ShutdownLoadingScreenNui();
+        }
+        catch { }
+    }
+    async setPlayerModel(model) {
+        const modelHash = GetHashKey(model);
+        if (!IsModelInCdimage(modelHash) || !IsModelValid(modelHash)) {
+            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);
+        }
+    }
+    async ensurePed() {
+        const start = GetGameTimer();
+        let ped = PlayerPedId();
+        while (ped === 0) {
+            if (GetGameTimer() - start > PED_TIMEOUT_MS) {
+                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) {
+                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);
+    }
+    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;
+        }
+        const validation = this.appearanceService.validateAppearance(appearance);
+        if (!validation.valid) {
+            loggers.spawn.warn('Invalid appearance data', { errors: validation.errors });
+            SetPedDefaultComponentVariation(ped);
+            return;
+        }
+        try {
+            await this.appearanceService.applyAppearance(ped, appearance);
+        }
+        catch (error) {
+            loggers.spawn.error('Failed to apply appearance, using default variation', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            SetPedDefaultComponentVariation(ped);
+        }
+    }
+};
+SpawnService = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [AppearanceService])
+], SpawnService);
+export { SpawnService };

package/dist/runtime/client/services/streaming.service.js

@@ -0,0 +1,331 @@
+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;
+};
+import { injectable } from 'tsyringe';
+/**
+ * Service for managing asset streaming (models, animations, particles, etc.).
+ */
+let StreamingService = class StreamingService {
+    loadedAssets = new Map();
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Model Loading
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Request and load a model.
+     *
+     * @param model - Model name or hash
+     * @param timeout - Maximum wait time in ms
+     * @returns Whether the model was loaded successfully
+     */
+    async requestModel(model, timeout = 10000) {
+        const hash = typeof model === 'string' ? GetHashKey(model) : model;
+        const key = `model:${hash}`;
+        // Already loaded
+        if (this.loadedAssets.get(key)?.loaded) {
+            return true;
+        }
+        // Check if valid
+        if (!IsModelInCdimage(hash) || !IsModelValid(hash)) {
+            return false;
+        }
+        RequestModel(hash);
+        const startTime = GetGameTimer();
+        while (!HasModelLoaded(hash)) {
+            if (GetGameTimer() - startTime > timeout) {
+                return false;
+            }
+            await new Promise((r) => setTimeout(r, 0));
+        }
+        this.loadedAssets.set(key, { type: 'model', asset: String(model), loaded: true, hash });
+        return true;
+    }
+    /**
+     * Check if a model is loaded.
+     *
+     * @param model - Model name or hash
+     */
+    isModelLoaded(model) {
+        const hash = typeof model === 'string' ? GetHashKey(model) : model;
+        return HasModelLoaded(hash);
+    }
+    /**
+     * Release a loaded model.
+     *
+     * @param model - Model name or hash
+     */
+    releaseModel(model) {
+        const hash = typeof model === 'string' ? GetHashKey(model) : model;
+        SetModelAsNoLongerNeeded(hash);
+        this.loadedAssets.delete(`model:${hash}`);
+    }
+    /**
+     * Check if a model is valid and exists in the game files.
+     *
+     * @param model - Model name or hash
+     */
+    isModelValid(model) {
+        const hash = typeof model === 'string' ? GetHashKey(model) : model;
+        return IsModelInCdimage(hash) && IsModelValid(hash);
+    }
+    /**
+     * Check if a model is a vehicle.
+     *
+     * @param model - Model name or hash
+     */
+    isModelVehicle(model) {
+        const hash = typeof model === 'string' ? GetHashKey(model) : model;
+        return IsModelAVehicle(hash);
+    }
+    /**
+     * Check if a model is a ped.
+     *
+     * @param model - Model name or hash
+     */
+    isModelPed(model) {
+        const hash = typeof model === 'string' ? GetHashKey(model) : model;
+        return IsModelAPed(hash);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Animation Dictionary Loading
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Request and load an animation dictionary.
+     *
+     * @param dict - Animation dictionary name
+     * @param timeout - Maximum wait time in ms
+     * @returns Whether the dictionary was loaded successfully
+     */
+    async requestAnimDict(dict, timeout = 10000) {
+        const key = `anim:${dict}`;
+        // Already loaded
+        if (this.loadedAssets.get(key)?.loaded) {
+            return true;
+        }
+        RequestAnimDict(dict);
+        const startTime = GetGameTimer();
+        while (!HasAnimDictLoaded(dict)) {
+            if (GetGameTimer() - startTime > timeout) {
+                return false;
+            }
+            await new Promise((r) => setTimeout(r, 0));
+        }
+        this.loadedAssets.set(key, { type: 'animDict', asset: dict, loaded: true });
+        return true;
+    }
+    /**
+     * Check if an animation dictionary is loaded.
+     *
+     * @param dict - Animation dictionary name
+     */
+    isAnimDictLoaded(dict) {
+        return HasAnimDictLoaded(dict);
+    }
+    /**
+     * Release a loaded animation dictionary.
+     *
+     * @param dict - Animation dictionary name
+     */
+    releaseAnimDict(dict) {
+        RemoveAnimDict(dict);
+        this.loadedAssets.delete(`anim:${dict}`);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Particle Effects (PTFX) Loading
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Request and load a particle effect asset.
+     *
+     * @param asset - PTFX asset name
+     * @param timeout - Maximum wait time in ms
+     * @returns Whether the asset was loaded successfully
+     */
+    async requestPtfxAsset(asset, timeout = 10000) {
+        const key = `ptfx:${asset}`;
+        // Already loaded
+        if (this.loadedAssets.get(key)?.loaded) {
+            return true;
+        }
+        RequestNamedPtfxAsset(asset);
+        const startTime = GetGameTimer();
+        while (!HasNamedPtfxAssetLoaded(asset)) {
+            if (GetGameTimer() - startTime > timeout) {
+                return false;
+            }
+            await new Promise((r) => setTimeout(r, 0));
+        }
+        this.loadedAssets.set(key, { type: 'ptfx', asset, loaded: true });
+        return true;
+    }
+    /**
+     * Check if a PTFX asset is loaded.
+     *
+     * @param asset - PTFX asset name
+     */
+    isPtfxAssetLoaded(asset) {
+        return HasNamedPtfxAssetLoaded(asset);
+    }
+    /**
+     * Release a loaded PTFX asset.
+     *
+     * @param asset - PTFX asset name
+     */
+    releasePtfxAsset(asset) {
+        RemoveNamedPtfxAsset(asset);
+        this.loadedAssets.delete(`ptfx:${asset}`);
+    }
+    /**
+     * Start a particle effect at a position.
+     *
+     * @param asset - PTFX asset name
+     * @param effectName - Effect name within the asset
+     * @param position - World position
+     * @param rotation - Rotation
+     * @param scale - Scale
+     * @param looped - Whether to loop
+     * @returns The particle effect handle
+     */
+    async startParticleEffect(asset, effectName, position, rotation = { x: 0, y: 0, z: 0 }, scale = 1.0, looped = false) {
+        await this.requestPtfxAsset(asset);
+        UseParticleFxAssetNextCall(asset);
+        if (looped) {
+            return StartParticleFxLoopedAtCoord(effectName, position.x, position.y, position.z, rotation.x, rotation.y, rotation.z, scale, false, false, false, false);
+        }
+        else {
+            return StartParticleFxNonLoopedAtCoord(effectName, position.x, position.y, position.z, rotation.x, rotation.y, rotation.z, scale, false, false, false);
+        }
+    }
+    /**
+     * Stop a looped particle effect.
+     *
+     * @param handle - Particle effect handle
+     */
+    stopParticleEffect(handle) {
+        StopParticleFxLooped(handle, false);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Texture Dictionary Loading
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Request and load a texture dictionary.
+     *
+     * @param dict - Texture dictionary name
+     * @param timeout - Maximum wait time in ms
+     * @returns Whether the dictionary was loaded successfully
+     */
+    async requestTextureDict(dict, timeout = 10000) {
+        const key = `texture:${dict}`;
+        // Already loaded
+        if (this.loadedAssets.get(key)?.loaded) {
+            return true;
+        }
+        RequestStreamedTextureDict(dict, true);
+        const startTime = GetGameTimer();
+        while (!HasStreamedTextureDictLoaded(dict)) {
+            if (GetGameTimer() - startTime > timeout) {
+                return false;
+            }
+            await new Promise((r) => setTimeout(r, 0));
+        }
+        this.loadedAssets.set(key, { type: 'texture', asset: dict, loaded: true });
+        return true;
+    }
+    /**
+     * Check if a texture dictionary is loaded.
+     *
+     * @param dict - Texture dictionary name
+     */
+    isTextureDictLoaded(dict) {
+        return HasStreamedTextureDictLoaded(dict);
+    }
+    /**
+     * Release a loaded texture dictionary.
+     *
+     * @param dict - Texture dictionary name
+     */
+    releaseTextureDict(dict) {
+        SetStreamedTextureDictAsNoLongerNeeded(dict);
+        this.loadedAssets.delete(`texture:${dict}`);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Audio Loading
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Request and load a script audio bank.
+     *
+     * @param audioBank - Audio bank name
+     * @param networked - Whether the audio should be networked
+     * @param timeout - Maximum wait time in ms
+     * @returns Whether the audio bank was loaded successfully
+     */
+    async requestAudioBank(audioBank, networked = false, _timeout = 10000) {
+        const key = `audio:${audioBank}`;
+        // Already loaded
+        if (this.loadedAssets.get(key)?.loaded) {
+            return true;
+        }
+        const success = RequestScriptAudioBank(audioBank, networked);
+        if (!success)
+            return false;
+        this.loadedAssets.set(key, { type: 'audio', asset: audioBank, loaded: true });
+        return true;
+    }
+    /**
+     * Release a loaded audio bank.
+     *
+     * @param audioBank - Audio bank name
+     */
+    releaseAudioBank(audioBank) {
+        ReleaseScriptAudioBank();
+        this.loadedAssets.delete(`audio:${audioBank}`);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Utility Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Get all currently loaded assets.
+     */
+    getLoadedAssets() {
+        return Array.from(this.loadedAssets.values());
+    }
+    /**
+     * Release all loaded assets.
+     */
+    releaseAll() {
+        for (const asset of this.loadedAssets.values()) {
+            switch (asset.type) {
+                case 'model':
+                    if (asset.hash)
+                        SetModelAsNoLongerNeeded(asset.hash);
+                    break;
+                case 'animDict':
+                    RemoveAnimDict(asset.asset);
+                    break;
+                case 'ptfx':
+                    RemoveNamedPtfxAsset(asset.asset);
+                    break;
+                case 'texture':
+                    SetStreamedTextureDictAsNoLongerNeeded(asset.asset);
+                    break;
+                case 'audio':
+                    ReleaseScriptAudioBank();
+                    break;
+            }
+        }
+        this.loadedAssets.clear();
+    }
+    /**
+     * Get hash key for a string.
+     *
+     * @param str - String to hash
+     */
+    getHash(str) {
+        return GetHashKey(str);
+    }
+};
+StreamingService = __decorate([
+    injectable()
+], StreamingService);
+export { StreamingService };

package/dist/runtime/client/services/textui.service.d.ts

@@ -0,0 +1,82 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+export interface TextUIOptions {
+    /** Font (0-8) */
+    font?: number;
+    /** Scale (0.0-1.0+) */
+    scale?: number;
+    /** Color */
+    color?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /** Text alignment (0=center, 1=left, 2=right) */
+    alignment?: number;
+    /** Drop shadow */
+    dropShadow?: boolean;
+    /** Text outline */
+    outline?: boolean;
+    /** Word wrap width (0 = no wrap) */
+    wrapWidth?: number;
+}
+export interface Text3DOptions extends TextUIOptions {
+    /** Whether to draw a background behind text */
+    background?: boolean;
+    /** Background color */
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /** Background padding */
+    backgroundPadding?: number;
+}
+/**
+ * Service for rendering text UI elements on screen and in 3D world.
+ */
+export declare class TextUIService {
+    private activeTextUI;
+    private tickHandle;
+    /**
+     * Show persistent text UI at the bottom-right of the screen.
+     *
+     * @param text - The text to display
+     * @param options - Text options
+     */
+    show(text: string, options?: TextUIOptions): void;
+    /**
+     * Hide the persistent text UI.
+     */
+    hide(): void;
+    /**
+     * Check if text UI is currently visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Draw text on screen for one frame.
+     * Call this every frame for persistent display.
+     *
+     * @param text - The text to draw
+     * @param x - Screen X position (0.0-1.0)
+     * @param y - Screen Y position (0.0-1.0)
+     * @param options - Text options
+     */
+    drawText(text: string, x: number, y: number, options?: TextUIOptions): void;
+    /**
+     * Draw 3D text in the game world.
+     *
+     * @param position - World position
+     * @param text - The text to draw
+     * @param options - Text options
+     */
+    drawText3D(position: Vector3, text: string, options?: Text3DOptions): void;
+    /**
+     * Get text width for layout calculations.
+     * Note: This is an approximation based on character count and scale.
+     */
+    getTextWidth(text: string, _font: number, scale: number): number;
+    private ensureTickRunning;
+    private stopTick;
+}