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

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

@@ -0,0 +1,330 @@
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'tsyringe';
+import { IPedAppearanceClient } from '../../../adapters/contracts/client/IPedAppearanceClient';
+import { IHasher } from '../../../adapters/contracts/IHasher';
+/**
+ * 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())
+ * ```
+ */
+let AppearanceService = class AppearanceService {
+    pedAdapter;
+    hasher;
+    constructor(pedAdapter, hasher) {
+        this.pedAdapter = pedAdapter;
+        this.hasher = hasher;
+    }
+    /**
+     * 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
+     */
+    async applyAppearance(ped, appearance) {
+        // 1. HeadBlend must be set first (required for overlays and face features)
+        if (appearance.headBlend) {
+            this.pedAdapter.setHeadBlendData(ped, appearance.headBlend);
+        }
+        // 2. Face features (requires headBlend)
+        if (appearance.faceFeatures) {
+            for (const [index, value] of Object.entries(appearance.faceFeatures)) {
+                this.pedAdapter.setFaceFeature(ped, parseInt(index, 10), value);
+            }
+        }
+        // 3. Components (clothing, hair, etc.)
+        if (appearance.components) {
+            for (const [componentId, data] of Object.entries(appearance.components)) {
+                this.pedAdapter.setComponentVariation(ped, parseInt(componentId, 10), data.drawable, data.texture, 2);
+            }
+        }
+        // 4. Props (hats, glasses, etc.)
+        if (appearance.props) {
+            for (const [propId, data] of Object.entries(appearance.props)) {
+                if (data.drawable === -1) {
+                    this.pedAdapter.clearProp(ped, parseInt(propId, 10));
+                }
+                else {
+                    this.pedAdapter.setPropIndex(ped, parseInt(propId, 10), data.drawable, data.texture, true);
+                }
+            }
+        }
+        // 5. Head overlays with colors (requires headBlend)
+        if (appearance.headOverlays) {
+            for (const [overlayId, overlay] of Object.entries(appearance.headOverlays)) {
+                const id = parseInt(overlayId, 10);
+                this.pedAdapter.setHeadOverlay(ped, id, overlay.index, overlay.opacity);
+                if (overlay.colorType !== undefined && overlay.colorId !== undefined) {
+                    this.pedAdapter.setHeadOverlayColor(ped, id, overlay.colorType, overlay.colorId, overlay.secondColorId ?? overlay.colorId);
+                }
+            }
+        }
+        // 6. Hair color
+        if (appearance.hairColor) {
+            this.pedAdapter.setHairColor(ped, appearance.hairColor.colorId, appearance.hairColor.highlightColorId);
+        }
+        // 7. Eye color
+        if (appearance.eyeColor !== undefined) {
+            this.pedAdapter.setEyeColor(ped, appearance.eyeColor);
+        }
+        // 8. Tattoos
+        if (appearance.tattoos && appearance.tattoos.length > 0) {
+            this.pedAdapter.clearDecorations(ped);
+            for (const tattoo of appearance.tattoos) {
+                const collectionHash = this.hasher.getHashKey(tattoo.collection);
+                const overlayHash = this.hasher.getHashKey(tattoo.overlay);
+                this.pedAdapter.addDecoration(ped, collectionHash, overlayHash);
+            }
+        }
+    }
+    /**
+     * 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)
+     */
+    async getAppearance(ped) {
+        const appearance = {
+            components: {},
+            props: {},
+        };
+        if (!appearance.components)
+            appearance.components = {};
+        if (!appearance.props)
+            appearance.props = {};
+        // Components (0-11)
+        for (let i = 0; i <= 11; i++) {
+            const drawable = this.pedAdapter.getDrawableVariation(ped, i);
+            const texture = this.pedAdapter.getTextureVariation(ped, i);
+            if (drawable !== -1) {
+                appearance.components[i] = { drawable, texture };
+            }
+        }
+        // Props (0-7)
+        for (let i = 0; i <= 7; i++) {
+            const drawable = this.pedAdapter.getPropIndex(ped, i);
+            const texture = this.pedAdapter.getPropTextureIndex(ped, i);
+            if (drawable !== -1) {
+                appearance.props[i] = { drawable, texture };
+            }
+        }
+        return appearance;
+    }
+    /**
+     * 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, componentId) {
+        return this.pedAdapter.getNumDrawableVariations(ped, componentId);
+    }
+    /**
+     * 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, componentId, drawable) {
+        return this.pedAdapter.getNumTextureVariations(ped, componentId, drawable);
+    }
+    /**
+     * 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, propId) {
+        return this.pedAdapter.getNumPropDrawableVariations(ped, propId);
+    }
+    /**
+     * 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, propId, drawable) {
+        return this.pedAdapter.getNumPropTextureVariations(ped, propId, drawable);
+    }
+    /**
+     * Gets the number of available overlay variations.
+     *
+     * @param overlayId - Overlay ID (0-12)
+     * @returns Number of available variations
+     */
+    getNumOverlayValues(overlayId) {
+        return this.pedAdapter.getNumOverlayValues(overlayId);
+    }
+    /**
+     * Gets the number of available hair colors.
+     *
+     * @returns Number of hair colors
+     */
+    getNumHairColors() {
+        return this.pedAdapter.getNumHairColors();
+    }
+    /**
+     * Gets the number of available makeup colors.
+     *
+     * @returns Number of makeup colors
+     */
+    getNumMakeupColors() {
+        return this.pedAdapter.getNumMakeupColors();
+    }
+    /**
+     * 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) {
+        const errors = [];
+        if (!appearance) {
+            return { valid: false, errors: ['Appearance data is null or undefined'] };
+        }
+        // Validate components (0-11)
+        if (appearance.components) {
+            for (const [id, data] of Object.entries(appearance.components)) {
+                const componentId = parseInt(id, 10);
+                if (Number.isNaN(componentId) || componentId < 0 || componentId > 11) {
+                    errors.push(`Invalid component ID: ${id}`);
+                }
+                if (data.drawable === undefined || data.texture === undefined) {
+                    errors.push(`Missing drawable or texture for component ${id}`);
+                }
+            }
+        }
+        // Validate props (0-7)
+        if (appearance.props) {
+            for (const [id, data] of Object.entries(appearance.props)) {
+                const propId = parseInt(id, 10);
+                if (Number.isNaN(propId) || propId < 0 || propId > 7) {
+                    errors.push(`Invalid prop ID: ${id}`);
+                }
+                if (data.drawable === undefined || data.texture === undefined) {
+                    errors.push(`Missing drawable or texture for prop ${id}`);
+                }
+            }
+        }
+        // Validate faceFeatures (0-19, values -1.0 to 1.0)
+        if (appearance.faceFeatures) {
+            for (const [id, value] of Object.entries(appearance.faceFeatures)) {
+                const index = parseInt(id, 10);
+                if (Number.isNaN(index) || index < 0 || index > 19) {
+                    errors.push(`Invalid face feature index: ${id}`);
+                }
+                if (value < -1.0 || value > 1.0) {
+                    errors.push(`Face feature ${id} value out of range: ${value}`);
+                }
+            }
+        }
+        // Validate headBlend
+        if (appearance.headBlend) {
+            const hb = appearance.headBlend;
+            if (hb.shapeFirst < 0 || hb.shapeFirst > 45)
+                errors.push('Invalid shapeFirst (0-45)');
+            if (hb.shapeSecond < 0 || hb.shapeSecond > 45)
+                errors.push('Invalid shapeSecond (0-45)');
+            if (hb.skinFirst < 0 || hb.skinFirst > 45)
+                errors.push('Invalid skinFirst (0-45)');
+            if (hb.skinSecond < 0 || hb.skinSecond > 45)
+                errors.push('Invalid skinSecond (0-45)');
+            if (hb.shapeMix < 0 || hb.shapeMix > 1)
+                errors.push('Invalid shapeMix (0.0-1.0)');
+            if (hb.skinMix < 0 || hb.skinMix > 1)
+                errors.push('Invalid skinMix (0.0-1.0)');
+        }
+        // Validate headOverlays (0-12)
+        if (appearance.headOverlays) {
+            for (const [id, overlay] of Object.entries(appearance.headOverlays)) {
+                const overlayId = parseInt(id, 10);
+                if (Number.isNaN(overlayId) || overlayId < 0 || overlayId > 12) {
+                    errors.push(`Invalid overlay ID: ${id}`);
+                }
+                if (overlay.opacity < 0 || overlay.opacity > 1) {
+                    errors.push(`Invalid overlay opacity for ID ${id}`);
+                }
+            }
+        }
+        // Validate eyeColor (0-31)
+        if (appearance.eyeColor !== undefined) {
+            if (appearance.eyeColor < 0 || appearance.eyeColor > 31) {
+                errors.push(`Invalid eye color: ${appearance.eyeColor} (0-31)`);
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    /**
+     * Sets the ped to default component variation.
+     *
+     * @param ped - Ped entity handle
+     */
+    setDefaultAppearance(ped) {
+        this.pedAdapter.setDefaultComponentVariation(ped);
+    }
+    /**
+     * Clears all tattoos from a ped.
+     *
+     * @param ped - Ped entity handle
+     */
+    clearTattoos(ped) {
+        this.pedAdapter.clearDecorations(ped);
+    }
+};
+AppearanceService = __decorate([
+    injectable(),
+    __param(0, inject(IPedAppearanceClient)),
+    __param(1, inject(IHasher)),
+    __metadata("design:paramtypes", [IPedAppearanceClient,
+        IHasher])
+], AppearanceService);
+export { AppearanceService };

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

@@ -0,0 +1,112 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+export interface BlipOptions {
+    /** Blip sprite ID (icon) */
+    sprite?: number;
+    /** Blip color ID */
+    color?: number;
+    /** Blip scale */
+    scale?: number;
+    /** Short range blip (only visible nearby) */
+    shortRange?: boolean;
+    /** Blip label/name */
+    label?: string;
+    /** Display category (affects visibility on map) */
+    display?: number;
+    /** Blip category */
+    category?: number;
+    /** Flash the blip */
+    flash?: boolean;
+    /** Blip alpha (0-255) */
+    alpha?: number;
+    /** Route to this blip */
+    route?: boolean;
+    /** Route color */
+    routeColor?: number;
+}
+export interface ManagedBlip {
+    id: string;
+    handle: number;
+    position: Vector3;
+    options: BlipOptions;
+}
+/**
+ * Service for creating and managing map blips.
+ */
+export declare class BlipService {
+    private blips;
+    private idCounter;
+    /**
+     * Create a blip at a world position.
+     *
+     * @param position - World position
+     * @param options - Blip options
+     * @returns The blip ID
+     */
+    create(position: Vector3, options?: BlipOptions): string;
+    /**
+     * Create a blip attached to an entity.
+     *
+     * @param entity - Entity handle
+     * @param options - Blip options
+     * @returns The blip ID
+     */
+    createForEntity(entity: number, options?: BlipOptions): string;
+    /**
+     * Create a blip for a radius/area.
+     *
+     * @param position - Center position
+     * @param radius - Radius of the area
+     * @param options - Blip options
+     * @returns The blip ID
+     */
+    createForRadius(position: Vector3, radius: number, options?: BlipOptions): string;
+    /**
+     * Remove a blip by ID.
+     *
+     * @param id - The blip ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Remove all managed blips.
+     */
+    removeAll(): void;
+    /**
+     * Update blip options.
+     *
+     * @param id - The blip ID
+     * @param options - New options to apply
+     */
+    update(id: string, options: Partial<BlipOptions>): boolean;
+    /**
+     * Set blip position.
+     *
+     * @param id - The blip ID
+     * @param position - New position
+     */
+    setPosition(id: string, position: Vector3): boolean;
+    /**
+     * Set whether a route should be drawn to the blip.
+     *
+     * @param id - The blip ID
+     * @param enabled - Whether to show the route
+     * @param color - Optional route color
+     */
+    setRoute(id: string, enabled: boolean, color?: number): boolean;
+    /**
+     * Get blip by ID.
+     */
+    get(id: string): ManagedBlip | undefined;
+    /**
+     * Get all managed blips.
+     */
+    getAll(): ManagedBlip[];
+    /**
+     * Get the native blip handle by ID.
+     */
+    getHandle(id: string): number | undefined;
+    /**
+     * Check if a blip still exists in the game world.
+     */
+    exists(id: string): boolean;
+    private applyOptions;
+}

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

@@ -0,0 +1,209 @@
+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';
+const DEFAULT_OPTIONS = {
+    sprite: 1,
+    color: 1,
+    scale: 1.0,
+    shortRange: true,
+    display: 4,
+    category: 0,
+    flash: false,
+    alpha: 255,
+    route: false,
+};
+/**
+ * Service for creating and managing map blips.
+ */
+let BlipService = class BlipService {
+    blips = new Map();
+    idCounter = 0;
+    /**
+     * Create a blip at a world position.
+     *
+     * @param position - World position
+     * @param options - Blip options
+     * @returns The blip ID
+     */
+    create(position, options = {}) {
+        const id = `blip_${++this.idCounter}`;
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const handle = AddBlipForCoord(position.x, position.y, position.z);
+        this.applyOptions(handle, opts);
+        this.blips.set(id, { id, handle, position, options: opts });
+        return id;
+    }
+    /**
+     * Create a blip attached to an entity.
+     *
+     * @param entity - Entity handle
+     * @param options - Blip options
+     * @returns The blip ID
+     */
+    createForEntity(entity, options = {}) {
+        const id = `blip_${++this.idCounter}`;
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const handle = AddBlipForEntity(entity);
+        this.applyOptions(handle, opts);
+        const [x, y, z] = GetEntityCoords(entity, true);
+        this.blips.set(id, { id, handle, position: { x, y, z }, options: opts });
+        return id;
+    }
+    /**
+     * Create a blip for a radius/area.
+     *
+     * @param position - Center position
+     * @param radius - Radius of the area
+     * @param options - Blip options
+     * @returns The blip ID
+     */
+    createForRadius(position, radius, options = {}) {
+        const id = `blip_${++this.idCounter}`;
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const handle = AddBlipForRadius(position.x, position.y, position.z, radius);
+        this.applyOptions(handle, opts);
+        this.blips.set(id, { id, handle, position, options: opts });
+        return id;
+    }
+    /**
+     * Remove a blip by ID.
+     *
+     * @param id - The blip ID
+     */
+    remove(id) {
+        const blip = this.blips.get(id);
+        if (!blip)
+            return false;
+        if (DoesBlipExist(blip.handle)) {
+            RemoveBlip(blip.handle);
+        }
+        this.blips.delete(id);
+        return true;
+    }
+    /**
+     * Remove all managed blips.
+     */
+    removeAll() {
+        for (const blip of this.blips.values()) {
+            if (DoesBlipExist(blip.handle)) {
+                RemoveBlip(blip.handle);
+            }
+        }
+        this.blips.clear();
+    }
+    /**
+     * Update blip options.
+     *
+     * @param id - The blip ID
+     * @param options - New options to apply
+     */
+    update(id, options) {
+        const blip = this.blips.get(id);
+        if (!blip || !DoesBlipExist(blip.handle))
+            return false;
+        blip.options = { ...blip.options, ...options };
+        this.applyOptions(blip.handle, blip.options);
+        return true;
+    }
+    /**
+     * Set blip position.
+     *
+     * @param id - The blip ID
+     * @param position - New position
+     */
+    setPosition(id, position) {
+        const blip = this.blips.get(id);
+        if (!blip || !DoesBlipExist(blip.handle))
+            return false;
+        SetBlipCoords(blip.handle, position.x, position.y, position.z);
+        blip.position = position;
+        return true;
+    }
+    /**
+     * Set whether a route should be drawn to the blip.
+     *
+     * @param id - The blip ID
+     * @param enabled - Whether to show the route
+     * @param color - Optional route color
+     */
+    setRoute(id, enabled, color) {
+        const blip = this.blips.get(id);
+        if (!blip || !DoesBlipExist(blip.handle))
+            return false;
+        SetBlipRoute(blip.handle, enabled);
+        if (color !== undefined) {
+            SetBlipRouteColour(blip.handle, color);
+        }
+        return true;
+    }
+    /**
+     * Get blip by ID.
+     */
+    get(id) {
+        return this.blips.get(id);
+    }
+    /**
+     * Get all managed blips.
+     */
+    getAll() {
+        return Array.from(this.blips.values());
+    }
+    /**
+     * Get the native blip handle by ID.
+     */
+    getHandle(id) {
+        return this.blips.get(id)?.handle;
+    }
+    /**
+     * Check if a blip still exists in the game world.
+     */
+    exists(id) {
+        const blip = this.blips.get(id);
+        return blip ? DoesBlipExist(blip.handle) : false;
+    }
+    applyOptions(handle, options) {
+        if (options.sprite !== undefined) {
+            SetBlipSprite(handle, options.sprite);
+        }
+        if (options.color !== undefined) {
+            SetBlipColour(handle, options.color);
+        }
+        if (options.scale !== undefined) {
+            SetBlipScale(handle, options.scale);
+        }
+        if (options.shortRange !== undefined) {
+            SetBlipAsShortRange(handle, options.shortRange);
+        }
+        if (options.label) {
+            BeginTextCommandSetBlipName('STRING');
+            AddTextComponentString(options.label);
+            EndTextCommandSetBlipName(handle);
+        }
+        if (options.display !== undefined) {
+            SetBlipDisplay(handle, options.display);
+        }
+        if (options.category !== undefined) {
+            SetBlipCategory(handle, options.category);
+        }
+        if (options.flash !== undefined) {
+            SetBlipFlashes(handle, options.flash);
+        }
+        if (options.alpha !== undefined) {
+            SetBlipAlpha(handle, options.alpha);
+        }
+        if (options.route !== undefined) {
+            SetBlipRoute(handle, options.route);
+            if (options.routeColor !== undefined) {
+                SetBlipRouteColour(handle, options.routeColor);
+            }
+        }
+    }
+};
+BlipService = __decorate([
+    injectable()
+], BlipService);
+export { BlipService };