@open-core/framework 0.1.0-alpha.1 → 0.2.1-beta.1

package/dist/runtime/client/decorators/resourceLifecycle.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Registers a method to be called when the current resource starts (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStart()
+ *   onStart() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnResourceStart(): (target: any, propertyKey: string) => void;
+/**
+ * Registers a method to be called when the current resource is stopping (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * Use this for cleanup operations.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStop()
+ *   onStop() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnResourceStop(): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/resourceLifecycle.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnResourceStart = OnResourceStart;
+exports.OnResourceStop = OnResourceStop;
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Registers a method to be called when the current resource starts (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStart()
+ *   onStart() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function OnResourceStart() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.RESOURCE_START, {}, target, propertyKey);
+    };
+}
+/**
+ * Registers a method to be called when the current resource is stopping (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * Use this for cleanup operations.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStop()
+ *   onStop() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function OnResourceStop() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.RESOURCE_STOP, {}, target, propertyKey);
+    };
+}

package/dist/runtime/client/decorators/tick.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Registers a method to be executed on every client frame.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds tick handlers to the
+ * client tick loop.
+ *
+ * Tick handlers should be lightweight and non-blocking.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class HudController {
+ *   @Client.Tick()
+ *   updateHud() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Tick(): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/tick.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tick = Tick;
+const metadata_client_keys_1 = require("../system/metadata-client.keys");
+/**
+ * Registers a method to be executed on every client frame.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds tick handlers to the
+ * client tick loop.
+ *
+ * Tick handlers should be lightweight and non-blocking.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class HudController {
+ *   @Client.Tick()
+ *   updateHud() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function Tick() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.TICK, {}, target, propertyKey);
+    };
+}

package/dist/{client → runtime/client}/index.d.ts

@@ -1,7 +1,7 @@
 export * from './client-core';
+export * from './client-runtime';
 export * from './decorators';
 export * from './player/player';
-export * from './ui-bridge';
 export * from './services';
 export * from './types';
-import './controllers/spawner.controller';
+export * from './ui-bridge';

package/dist/{client → runtime/client}/index.js

@@ -15,9 +15,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./client-core"), exports);
+__exportStar(require("./client-runtime"), exports);
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./player/player"), exports);
-__exportStar(require("./ui-bridge"), exports);
 __exportStar(require("./services"), exports);
 __exportStar(require("./types"), exports);
-require("./controllers/spawner.controller");
+__exportStar(require("./ui-bridge"), exports);
+// NOTE: Controllers are NOT imported here anymore
+// They are conditionally imported in client-bootstrap.ts based on mode

package/dist/runtime/client/interfaces/appearance.interface.d.ts

@@ -0,0 +1,25 @@
+export interface PlayerAppearance {
+  components?: Record<
+    number,
+    {
+      drawable: number
+      texture: number
+    }
+  >
+  props?: Record<
+    number,
+    {
+      drawable: number
+      texture: number
+    }
+  >
+  faceFeatures?: Record<number, number>
+  headBlend?: {
+    shapeFirst: number
+    shapeSecond: number
+    shapeMix: number
+    skinFirst: number
+    skinSecond: number
+    skinMix: number
+  }
+}

package/dist/runtime/client/interfaces/appearance.interface.js

@@ -0,0 +1,2 @@
+'use strict'
+Object.defineProperty(exports, '__esModule', { value: true })

package/dist/{client → runtime/client}/player/player.d.ts

@@ -1,4 +1,4 @@
-import type { Vector3 } from '../../utils';
+import { Vector3 } from '../../../kernel/utils';
 interface PlayerSessionMeta {
     playerId?: string;
     [key: string]: unknown;

package/dist/{client → runtime/client}/player/player.js

@@ -137,6 +137,7 @@ class Player {
     }
     /** Get currently equipped weapon hash */
     get currentWeapon() {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         const [_, weaponHash] = GetCurrentPedWeapon(this.ped, true);
         return weaponHash;
     }
@@ -425,9 +426,7 @@ class Player {
      */
     distanceTo(position) {
         const coords = this.coords;
-        return Math.sqrt(Math.pow(coords.x - position.x, 2) +
-            Math.pow(coords.y - position.y, 2) +
-            Math.pow(coords.z - position.z, 2));
+        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.
@@ -447,9 +446,9 @@ class Player {
             return null;
         const coords = this.coords;
         const entityCoords = GetEntityCoords(entity, true);
-        const distance = Math.sqrt(Math.pow(coords.x - entityCoords[0], 2) +
-            Math.pow(coords.y - entityCoords[1], 2) +
-            Math.pow(coords.z - entityCoords[2], 2));
+        const distance = Math.sqrt((coords.x - entityCoords[0]) ** 2 +
+            (coords.y - entityCoords[1]) ** 2 +
+            (coords.z - entityCoords[2]) ** 2);
         return distance <= maxDistance ? entity : null;
     }
     /**

package/dist/{client → runtime/client}/player/player.loader.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.playerClientLoader = void 0;
-const utils_1 = require("../../utils");
+const logger_1 = require("../../../kernel/shared/logger");
+const utils_1 = require("../../../kernel/utils");
 const player_1 = require("./player");
-const logger_1 = require("../../shared/logger");
 const clientSession = logger_1.coreLogger.child('Session', logger_1.LogDomain.CLIENT);
 const playerClientLoader = () => {
     on('onClientResourceStart', (resourceName) => {

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

@@ -0,0 +1,132 @@
+import { IHasher } from '../../../adapters/contracts/IHasher';
+import { IPedAppearanceClient } from '../../../adapters/contracts/IPedAppearanceClient';
+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;
+}