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

package/dist/runtime/client/player/player.js

@@ -0,0 +1,474 @@
+/**
+ * Client-side player representation with convenient accessors and methods.
+ */
+class Player {
+    meta = {};
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Core Getters
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Get the player's ped handle */
+    get ped() {
+        return PlayerPedId();
+    }
+    /** Get the player ID */
+    get id() {
+        return PlayerId();
+    }
+    /** Get the server ID (source) */
+    get serverId() {
+        return GetPlayerServerId(this.id);
+    }
+    /** Get the player's current coordinates */
+    get coords() {
+        const [x, y, z] = GetEntityCoords(this.ped, false);
+        return { x, y, z };
+    }
+    /** Get the player's current heading (rotation) */
+    get heading() {
+        return GetEntityHeading(this.ped);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Health & Status
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Get current health (0-200, 100 = dead) */
+    get health() {
+        return GetEntityHealth(this.ped);
+    }
+    /** Get max health */
+    get maxHealth() {
+        return GetEntityMaxHealth(this.ped);
+    }
+    /** Get current armor (0-100) */
+    get armor() {
+        return GetPedArmour(this.ped);
+    }
+    /** Check if the player is dead */
+    get isDead() {
+        return IsEntityDead(this.ped);
+    }
+    /** Check if player is in water */
+    get isInWater() {
+        return IsEntityInWater(this.ped);
+    }
+    /** Check if player is swimming */
+    get isSwimming() {
+        return IsPedSwimming(this.ped);
+    }
+    /** Check if player is falling */
+    get isFalling() {
+        return IsPedFalling(this.ped);
+    }
+    /** Check if player is climbing */
+    get isClimbing() {
+        return IsPedClimbing(this.ped);
+    }
+    /** Check if player is ragdolling */
+    get isRagdoll() {
+        return IsPedRagdoll(this.ped);
+    }
+    /** Check if player is parachuting */
+    get isParachuting() {
+        return IsPedInParachuteFreeFall(this.ped);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Vehicle State
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Check if player is in any vehicle */
+    get isInVehicle() {
+        return IsPedInAnyVehicle(this.ped, false);
+    }
+    /** Get current vehicle handle (or null if not in vehicle) */
+    get currentVehicle() {
+        if (!this.isInVehicle)
+            return null;
+        return GetVehiclePedIsIn(this.ped, false);
+    }
+    /** Get last vehicle the player was in */
+    get lastVehicle() {
+        const vehicle = GetVehiclePedIsIn(this.ped, true);
+        return vehicle !== 0 ? vehicle : null;
+    }
+    /** Check if player is the driver of current vehicle */
+    get isDriver() {
+        const vehicle = this.currentVehicle;
+        if (!vehicle)
+            return false;
+        return GetPedInVehicleSeat(vehicle, -1) === this.ped;
+    }
+    /** Get current vehicle seat index (-1 = driver, 0+ = passengers) */
+    get vehicleSeat() {
+        const vehicle = this.currentVehicle;
+        if (!vehicle)
+            return null;
+        for (let seat = -1; seat < GetVehicleMaxNumberOfPassengers(vehicle); seat++) {
+            if (GetPedInVehicleSeat(vehicle, seat) === this.ped) {
+                return seat;
+            }
+        }
+        return null;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Combat State
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Check if player is shooting */
+    get isShooting() {
+        return IsPedShooting(this.ped);
+    }
+    /** Check if player is aiming */
+    get isAiming() {
+        return IsPlayerFreeAiming(this.id);
+    }
+    /** Check if player is reloading */
+    get isReloading() {
+        return IsPedReloading(this.ped);
+    }
+    /** Check if player is in cover */
+    get isInCover() {
+        return IsPedInCover(this.ped, false);
+    }
+    /** Check if player is in melee combat */
+    get isInMeleeCombat() {
+        return IsPedInMeleeCombat(this.ped);
+    }
+    /** Get currently equipped weapon hash */
+    get currentWeapon() {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const [_, weaponHash] = GetCurrentPedWeapon(this.ped, true);
+        return weaponHash;
+    }
+    /** Get ammo count for current weapon */
+    get currentWeaponAmmo() {
+        return GetAmmoInPedWeapon(this.ped, this.currentWeapon);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Movement State
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Check if player is walking */
+    get isWalking() {
+        return IsPedWalking(this.ped);
+    }
+    /** Check if player is running */
+    get isRunning() {
+        return IsPedRunning(this.ped);
+    }
+    /** Check if player is sprinting */
+    get isSprinting() {
+        return IsPedSprinting(this.ped);
+    }
+    /** Check if player is on foot */
+    get isOnFoot() {
+        return IsPedOnFoot(this.ped);
+    }
+    /** Check if player is stationary */
+    get isStill() {
+        return IsPedStill(this.ped);
+    }
+    /** Get movement speed in m/s */
+    get speed() {
+        return GetEntitySpeed(this.ped);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Health & Armor Setters
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Set player health.
+     * @param value - Health value (100 = dead, 200 = full)
+     */
+    setHealth(value) {
+        SetEntityHealth(this.ped, value);
+    }
+    /**
+     * Set player armor.
+     * @param value - Armor value (0-100)
+     */
+    setArmor(value) {
+        SetPedArmour(this.ped, Math.max(0, Math.min(100, value)));
+    }
+    /**
+     * Heal the player to full health and armor.
+     */
+    heal() {
+        this.setHealth(this.maxHealth);
+        this.setArmor(100);
+    }
+    /**
+     * Revive the player at current position.
+     */
+    revive() {
+        const coords = this.coords;
+        NetworkResurrectLocalPlayer(coords.x, coords.y, coords.z, this.heading, 1, false);
+        this.heal();
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Position & Movement
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Set player coordinates.
+     * @param vector3 - Target position
+     * @param heading - Optional heading
+     */
+    setCoords(vector3, heading) {
+        SetEntityCoordsNoOffset(this.ped, vector3.x, vector3.y, vector3.z, false, false, false);
+        if (heading !== undefined) {
+            SetEntityHeading(this.ped, heading);
+        }
+    }
+    /**
+     * Set player heading/rotation.
+     * @param heading - Heading in degrees
+     */
+    setHeading(heading) {
+        SetEntityHeading(this.ped, heading);
+    }
+    /**
+     * Freeze/unfreeze the player in place.
+     * @param freeze - Whether to freeze
+     */
+    freeze(freeze) {
+        FreezeEntityPosition(this.ped, freeze);
+    }
+    /**
+     * Set player invincibility.
+     * @param invincible - Whether invincible
+     */
+    setInvincible(invincible) {
+        SetEntityInvincible(this.ped, invincible);
+    }
+    /**
+     * Set player visibility.
+     * @param visible - Whether visible
+     */
+    setVisible(visible) {
+        SetEntityVisible(this.ped, visible, false);
+    }
+    /**
+     * Set player alpha/transparency.
+     * @param alpha - Alpha value (0-255)
+     */
+    setAlpha(alpha) {
+        SetEntityAlpha(this.ped, alpha, false);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Weapons
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Give a weapon to the player.
+     * @param weapon - Weapon name (e.g., 'WEAPON_PISTOL')
+     * @param ammo - Ammo count
+     * @param equipNow - Whether to equip immediately
+     */
+    giveWeapon(weapon, ammo = 100, equipNow = true) {
+        const weaponHash = GetHashKey(weapon);
+        GiveWeaponToPed(this.ped, weaponHash, ammo, false, equipNow);
+    }
+    /**
+     * Remove a weapon from the player.
+     * @param weapon - Weapon name
+     */
+    removeWeapon(weapon) {
+        const weaponHash = GetHashKey(weapon);
+        RemoveWeaponFromPed(this.ped, weaponHash);
+    }
+    /**
+     * Remove all weapons from the player.
+     */
+    removeAllWeapons() {
+        RemoveAllPedWeapons(this.ped, true);
+    }
+    /**
+     * Set current weapon ammo.
+     * @param weapon - Weapon name
+     * @param ammo - Ammo count
+     */
+    setWeaponAmmo(weapon, ammo) {
+        const weaponHash = GetHashKey(weapon);
+        SetPedAmmo(this.ped, weaponHash, ammo);
+    }
+    /**
+     * Check if player has a specific weapon.
+     * @param weapon - Weapon name
+     */
+    hasWeapon(weapon) {
+        const weaponHash = GetHashKey(weapon);
+        return HasPedGotWeapon(this.ped, weaponHash, false);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Animations & Tasks
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Play an animation on the player.
+     * @param dict - Animation dictionary
+     * @param name - Animation name
+     * @param duration - Duration (-1 for looped)
+     * @param flags - Animation flags
+     */
+    async playAnimation(dict, name, duration = -1, flags = 1) {
+        RequestAnimDict(dict);
+        while (!HasAnimDictLoaded(dict)) {
+            await new Promise((r) => setTimeout(r, 0));
+        }
+        TaskPlayAnim(this.ped, dict, name, 8.0, -8.0, duration, flags, 0.0, false, false, false);
+    }
+    /**
+     * Stop current animation.
+     */
+    stopAnimation() {
+        ClearPedTasks(this.ped);
+    }
+    /**
+     * Stop animation immediately.
+     */
+    stopAnimationImmediately() {
+        ClearPedTasksImmediately(this.ped);
+    }
+    /**
+     * Check if player is playing a specific animation.
+     * @param dict - Animation dictionary
+     * @param name - Animation name
+     */
+    isPlayingAnimation(dict, name) {
+        return IsEntityPlayingAnim(this.ped, dict, name, 3);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Vehicle Interaction
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Warp player into a vehicle.
+     * @param vehicle - Vehicle handle
+     * @param seat - Seat index (-1 = driver)
+     */
+    warpIntoVehicle(vehicle, seat = -1) {
+        TaskWarpPedIntoVehicle(this.ped, vehicle, seat);
+    }
+    /**
+     * Task player to exit current vehicle.
+     * @param flags - Exit flags (0 = normal, 16 = immediately)
+     */
+    exitVehicle(flags = 0) {
+        const vehicle = this.currentVehicle;
+        if (vehicle) {
+            TaskLeaveVehicle(this.ped, vehicle, flags);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Ped Flags & Properties
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Set can ragdoll.
+     * @param canRagdoll - Whether player can ragdoll
+     */
+    setCanRagdoll(canRagdoll) {
+        SetPedCanRagdoll(this.ped, canRagdoll);
+    }
+    /**
+     * Set ped config flag.
+     * @param flag - Flag ID
+     * @param value - Flag value
+     */
+    setConfigFlag(flag, value) {
+        SetPedConfigFlag(this.ped, flag, value);
+    }
+    /**
+     * Get ped config flag.
+     * @param flag - Flag ID
+     */
+    getConfigFlag(flag) {
+        return GetPedConfigFlag(this.ped, flag, true);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Meta Storage
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Set a metadata value.
+     * @param key - Meta key
+     * @param value - Meta value
+     */
+    setMeta(key, value) {
+        this.meta[key] = value;
+    }
+    /**
+     * Get a metadata value.
+     * @param key - Meta key
+     */
+    getMeta(key) {
+        return this.meta[key];
+    }
+    /**
+     * Delete a metadata value.
+     * @param key - Meta key
+     */
+    deleteMeta(key) {
+        delete this.meta[key];
+    }
+    /**
+     * Get all metadata.
+     */
+    getAllMeta() {
+        return { ...this.meta };
+    }
+    /**
+     * Clear all metadata.
+     */
+    clearMeta() {
+        this.meta = {};
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Utility Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Get distance to a position.
+     * @param position - Target position
+     */
+    distanceTo(position) {
+        const coords = this.coords;
+        return Math.sqrt((coords.x - position.x) ** 2 + (coords.y - position.y) ** 2 + (coords.z - position.z) ** 2);
+    }
+    /**
+     * Check if player is within range of a position.
+     * @param position - Target position
+     * @param range - Maximum range
+     */
+    isNearPosition(position, range) {
+        return this.distanceTo(position) <= range;
+    }
+    /**
+     * Get the entity the player is looking at.
+     * @param maxDistance - Maximum detection distance
+     */
+    getEntityLookingAt(maxDistance = 10.0) {
+        const [hit, entity] = GetEntityPlayerIsFreeAimingAt(this.id);
+        if (!hit || !entity || entity === 0)
+            return null;
+        const coords = this.coords;
+        const entityCoords = GetEntityCoords(entity, true);
+        const distance = Math.sqrt((coords.x - entityCoords[0]) ** 2 +
+            (coords.y - entityCoords[1]) ** 2 +
+            (coords.z - entityCoords[2]) ** 2);
+        return distance <= maxDistance ? entity : null;
+    }
+    /**
+     * Disable a control action.
+     * @param control - Control ID
+     * @param padIndex - Pad index (usually 0)
+     */
+    disableControl(control, padIndex = 0) {
+        DisableControlAction(padIndex, control, true);
+    }
+    /**
+     * Check if a control is pressed.
+     * @param control - Control ID
+     * @param padIndex - Pad index (usually 0)
+     */
+    isControlPressed(control, padIndex = 0) {
+        return IsControlPressed(padIndex, control);
+    }
+    /**
+     * Check if a control was just pressed.
+     * @param control - Control ID
+     * @param padIndex - Pad index (usually 0)
+     */
+    isControlJustPressed(control, padIndex = 0) {
+        return IsControlJustPressed(padIndex, control);
+    }
+}
+export const ClientPlayer = new Player();

package/dist/runtime/client/player/player.loader.js

@@ -0,0 +1,18 @@
+import { coreLogger, LogDomain } from '../../../kernel/logger';
+import { Vec3 } from '../../../kernel/utils/vector3';
+import { ClientPlayer } from './player';
+const clientSession = coreLogger.child('Session', LogDomain.CLIENT);
+export const playerClientLoader = () => {
+    on('onClientResourceStart', (resourceName) => {
+        if (resourceName !== GetCurrentResourceName())
+            return;
+        clientSession.debug('Client player loader initialized');
+    });
+    onNet('core:playerSessionInit', (data) => {
+        ClientPlayer.setMeta('playerId', data.playerId);
+        clientSession.info('Player session initialized', { playerId: data.playerId });
+    });
+    onNet('core:teleportTo', (x, y, z, heading) => {
+        ClientPlayer.setCoords(Vec3.create(x, y, z), heading);
+    });
+};

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

@@ -0,0 +1,132 @@
+import { IPedAppearanceClient } from '../../../adapters/contracts/client/IPedAppearanceClient';
+import { IHasher } from '../../../adapters/contracts/IHasher';
+import { AppearanceValidationResult, PlayerAppearance } from '../../../kernel/shared';
+/**
+ * Client-side appearance management service.
+ *
+ * @remarks
+ * Handles applying and retrieving ped appearance data on the client.
+ * Uses adapters for FiveM native abstraction, enabling testability.
+ *
+ * This service is typically called in response to server events
+ * after the server has validated the appearance data.
+ *
+ * @example
+ * ```typescript
+ * // Apply appearance from server-validated data
+ * await appearanceService.applyAppearance(PlayerPedId(), validatedAppearance)
+ *
+ * // Get current appearance for saving
+ * const currentAppearance = await appearanceService.getAppearance(PlayerPedId())
+ * ```
+ */
+export declare class AppearanceService {
+    private pedAdapter;
+    private hasher;
+    constructor(pedAdapter: IPedAppearanceClient, hasher: IHasher);
+    /**
+     * Applies a complete appearance to a ped.
+     *
+     * @remarks
+     * The order of application is important:
+     * 1. HeadBlend (required before overlays/features)
+     * 2. Face features
+     * 3. Components
+     * 4. Props
+     * 5. Head overlays with colors
+     * 6. Hair color
+     * 7. Eye color
+     * 8. Tattoos
+     *
+     * @param ped - Ped entity handle
+     * @param appearance - Appearance data to apply
+     */
+    applyAppearance(ped: number, appearance: PlayerAppearance): Promise<void>;
+    /**
+     * Retrieves the current appearance of a ped.
+     *
+     * @remarks
+     * Only retrieves components and props as other data (headBlend, overlays, etc.)
+     * cannot be read back from the game.
+     *
+     * @param ped - Ped entity handle
+     * @returns Partial appearance data (components and props only)
+     */
+    getAppearance(ped: number): Promise<PlayerAppearance>;
+    /**
+     * Gets the number of available drawable variations for a component.
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @returns Number of available drawables
+     */
+    getNumComponentDrawables(ped: number, componentId: number): number;
+    /**
+     * Gets the number of available 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
+     */
+    getNumComponentTextures(ped: number, componentId: number, drawable: number): number;
+    /**
+     * Gets the number of available drawable variations for a prop.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @returns Number of available drawables
+     */
+    getNumPropDrawables(ped: number, propId: number): number;
+    /**
+     * Gets the number of available 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
+     */
+    getNumPropTextures(ped: number, propId: number, drawable: number): number;
+    /**
+     * Gets the number of available overlay variations.
+     *
+     * @param overlayId - Overlay ID (0-12)
+     * @returns Number of available variations
+     */
+    getNumOverlayValues(overlayId: number): number;
+    /**
+     * Gets the number of available hair colors.
+     *
+     * @returns Number of hair colors
+     */
+    getNumHairColors(): number;
+    /**
+     * Gets the number of available makeup colors.
+     *
+     * @returns Number of makeup colors
+     */
+    getNumMakeupColors(): number;
+    /**
+     * Validates appearance data structure.
+     *
+     * @remarks
+     * This is a client-side validation for data integrity.
+     * Server-side validation should always be performed for security.
+     *
+     * @param appearance - Appearance data to validate
+     * @returns Validation result with errors if any
+     */
+    validateAppearance(appearance: Partial<PlayerAppearance>): AppearanceValidationResult;
+    /**
+     * Sets the ped to default component variation.
+     *
+     * @param ped - Ped entity handle
+     */
+    setDefaultAppearance(ped: number): void;
+    /**
+     * Clears all tattoos from a ped.
+     *
+     * @param ped - Ped entity handle
+     */
+    clearTattoos(ped: number): void;
+}