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

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

@@ -0,0 +1,333 @@
+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 { IGtaPedAppearanceBridge } from '../../../adapters/contracts/client/IGtaPedAppearanceBridge';
+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) {
+        const adapter = this.pedAdapter;
+        if (typeof adapter?.setDefaultComponentVariation === 'function') {
+            adapter.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(IGtaPedAppearanceBridge)),
+    __param(1, inject(IHasher)),
+    __metadata("design:paramtypes", [IGtaPedAppearanceBridge,
+        IHasher])
+], AppearanceService);
+export { AppearanceService };

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

@@ -0,0 +1,25 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+import { IClientBlipBridge, type ClientBlipDefinition, type ClientBlipOptions as BlipOptions } from '../../../adapters/contracts/client/ui/IClientBlipBridge';
+export interface ManagedBlip {
+    id: string;
+    definition: ClientBlipDefinition;
+}
+export declare class BlipService {
+    private readonly bridge;
+    private blips;
+    private idCounter;
+    constructor(bridge: IClientBlipBridge);
+    create(position: Vector3, options?: BlipOptions): string;
+    createForEntity(entity: number, options?: BlipOptions): string;
+    createForRadius(position: Vector3, radius: number, options?: BlipOptions): string;
+    remove(id: string): boolean;
+    removeAll(): void;
+    update(id: string, options: Partial<BlipOptions>): boolean;
+    setPosition(id: string, position: Vector3): boolean;
+    setRoute(id: string, enabled: boolean, color?: number): boolean;
+    get(id: string): ManagedBlip | undefined;
+    getAll(): ManagedBlip[];
+    exists(id: string): boolean;
+    private buildDefinition;
+    private normalizeOptions;
+}

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

@@ -0,0 +1,114 @@
+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 { IClientBlipBridge, } from '../../../adapters/contracts/client/ui/IClientBlipBridge';
+const DEFAULT_OPTIONS = {
+    icon: 1,
+    color: 1,
+    scale: 1.0,
+    shortRange: true,
+    alpha: 255,
+    route: false,
+    visible: true,
+};
+let BlipService = class BlipService {
+    bridge;
+    blips = new Map();
+    idCounter = 0;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    create(position, options = {}) {
+        const id = `blip_${++this.idCounter}`;
+        const definition = this.buildDefinition({ position }, options);
+        this.bridge.create(id, definition);
+        this.blips.set(id, { id, definition });
+        return id;
+    }
+    createForEntity(entity, options = {}) {
+        const id = `blip_${++this.idCounter}`;
+        const definition = this.buildDefinition({ entity }, options);
+        this.bridge.create(id, definition);
+        this.blips.set(id, { id, definition });
+        return id;
+    }
+    createForRadius(position, radius, options = {}) {
+        const id = `blip_${++this.idCounter}`;
+        const definition = this.buildDefinition({ position, radius }, options);
+        this.bridge.create(id, definition);
+        this.blips.set(id, { id, definition });
+        return id;
+    }
+    remove(id) {
+        const removed = this.bridge.remove(id);
+        if (removed)
+            this.blips.delete(id);
+        return removed;
+    }
+    removeAll() {
+        this.bridge.clear();
+        this.blips.clear();
+    }
+    update(id, options) {
+        const blip = this.blips.get(id);
+        if (!blip)
+            return false;
+        const patch = this.normalizeOptions(options);
+        const updated = this.bridge.update(id, patch);
+        if (!updated)
+            return false;
+        blip.definition = { ...blip.definition, ...patch };
+        return updated;
+    }
+    setPosition(id, position) {
+        const blip = this.blips.get(id);
+        if (!blip)
+            return false;
+        const updated = this.bridge.update(id, { position, entity: undefined, radius: undefined });
+        if (!updated)
+            return false;
+        blip.definition = { ...blip.definition, position, entity: undefined, radius: undefined };
+        return updated;
+    }
+    setRoute(id, enabled, color) {
+        return this.update(id, { route: enabled, routeColor: color });
+    }
+    get(id) {
+        return this.blips.get(id);
+    }
+    getAll() {
+        return Array.from(this.blips.values());
+    }
+    exists(id) {
+        return this.bridge.exists(id);
+    }
+    buildDefinition(base, options) {
+        return {
+            ...base,
+            ...this.normalizeOptions({ ...DEFAULT_OPTIONS, ...options }),
+        };
+    }
+    normalizeOptions(options) {
+        const { sprite, icon, ...rest } = options;
+        return {
+            ...rest,
+            icon: icon ?? sprite,
+        };
+    }
+};
+BlipService = __decorate([
+    injectable(),
+    __param(0, inject(IClientBlipBridge)),
+    __metadata("design:paramtypes", [IClientBlipBridge])
+], BlipService);
+export { BlipService };

package/dist/runtime/client/services/camera-effects.registry.d.ts

@@ -0,0 +1,97 @@
+import { IClientPlatformBridge } from '../adapter/platform-bridge';
+import { Camera } from './camera';
+/**
+ * Reason reported when an effect instance is finalized.
+ */
+export type EffectTeardownReason = 'completed' | 'cancelled' | 'interrupted';
+/**
+ * Shared context delivered to effect handlers.
+ */
+export interface CameraEffectContext {
+    /** Low-level camera API instance used by the cinematic runtime. */
+    camera: Camera;
+    /** Active camera handle for the running cinematic. */
+    camHandle: number;
+    /** Absolute elapsed time in milliseconds within the current shot. */
+    elapsedMs: number;
+    /** Normalized [0..1] progress inside the active effect window. */
+    normalized: number;
+    /** Delta time since previous frame in milliseconds. */
+    deltaMs: number;
+    /** Draws a subtitle line on screen for one frame. */
+    drawSubtitle(text: string): void;
+    /** Draws cinematic bars for one frame. */
+    drawLetterbox(top: number, bottom: number, alpha?: number): void;
+}
+/**
+ * A reusable effect implementation.
+ */
+export interface CameraEffectDefinition<TParams = Record<string, unknown>> {
+    /** Unique effect id. */
+    id: string;
+    /** Optional default params merged with user params. */
+    defaults?: Partial<TParams>;
+    /** Called when the effect enters its active window. */
+    setup?: (ctx: CameraEffectContext, params: TParams) => void | Promise<void>;
+    /** Called every frame while active. */
+    update?: (ctx: CameraEffectContext, params: TParams) => void | Promise<void>;
+    /** Called when the effect leaves its active window. */
+    teardown?: (ctx: CameraEffectContext, params: TParams, reason: EffectTeardownReason) => void | Promise<void>;
+}
+/**
+ * Effect reference used inside a cinematic definition.
+ */
+export interface CameraEffectReference<TParams = Record<string, unknown>> {
+    /** Effect id to load from registry. */
+    id: string;
+    /** Optional runtime params merged over effect defaults. */
+    params?: Partial<TParams>;
+    /** Optional local start timestamp in milliseconds. */
+    fromMs?: number;
+    /** Optional local end timestamp in milliseconds. */
+    toMs?: number;
+}
+/**
+ * Named collection of effects that can be reused in multiple cinematics.
+ */
+export interface CameraEffectPreset {
+    id: string;
+    effects: CameraEffectReference[];
+}
+/**
+ * Registry for built-in and custom cinematic camera effects.
+ */
+export declare class CameraEffectsRegistry {
+    private readonly platform;
+    private effects;
+    private presets;
+    constructor(platform: IClientPlatformBridge);
+    /**
+     * Registers a single effect definition.
+     */
+    register<TParams = Record<string, unknown>>(definition: CameraEffectDefinition<TParams>): void;
+    /**
+     * Registers a reusable effect preset.
+     */
+    definePreset(preset: CameraEffectPreset): void;
+    /**
+     * Returns an effect by id.
+     */
+    get(effectId: string): CameraEffectDefinition | undefined;
+    /**
+     * Returns a cloned effect list from a preset id.
+     */
+    usePreset(presetId: string): CameraEffectReference[];
+    /**
+     * Returns true when an effect id exists in the registry.
+     */
+    has(effectId: string): boolean;
+    /**
+     * Returns true when a preset id exists in the registry.
+     */
+    hasPreset(presetId: string): boolean;
+    /**
+     * Registers the framework default effect set.
+     */
+    registerBuiltins(): void;
+}