@rpgjs/server 5.0.0-alpha.4 → 5.0.0-alpha.41

package/dist/Player/ParameterManager.d.ts

@@ -1,42 +1,372 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-export interface IWithParameterManager {
-    parameters: Map<string, any>;
+import { PlayerCtor } from '../../../common/src';
+export type ExpCurve = {
+    basis: number;
+    extra: number;
+    accelerationA: number;
+    accelerationB: number;
+};
+/**
+ * Interface for Parameter Manager functionality
+ *
+ * Provides comprehensive parameter management including health points (HP), skill points (SP),
+ * experience and level progression, custom parameters, and parameter modifiers.
+ */
+export interface IParameterManager {
+    /**
+     * ```ts
+     * player.initialLevel = 5
+     * ```
+     *
+     * @title Set initial level
+     * @prop {number} player.initialLevel
+     * @default 1
+     * @memberof ParameterManager
+     * */
+    initialLevel: number;
+    /**
+     * ```ts
+     * player.finalLevel = 50
+     * ```
+     *
+     * @title Set final level
+     * @prop {number} player.finalLevel
+     * @default 99
+     * @memberof ParameterManager
+     * */
+    finalLevel: number;
+    /**
+     * With Object-based syntax, you can use following options:
+     * - `basis: number`
+     * - `extra: number`
+     * - `accelerationA: number`
+     * - `accelerationB: number`
+     * @title Change Experience Curve
+     * @prop {object} player.expCurve
+     * @default
+     *  ```ts
+     * {
+     *      basis: 30,
+     *      extra: 20,
+     *      accelerationA: 30,
+     *      accelerationB: 30
+     * }
+     * ```
+     * @memberof ParameterManager
+     * */
+    expCurve: ExpCurve;
+    /**
+     * Changes the health points
+     * - Cannot exceed the MaxHP parameter
+     * - Cannot have a negative value
+     * - If the value is 0, a hook named `onDead()` is called in the RpgPlayer class.
+     *
+     * ```ts
+     * player.hp = 100
+     * ```
+     * @title Change HP
+     * @prop {number} player.hp
+     * @default MaxHPValue
+     * @memberof ParameterManager
+     * */
     hp: number;
+    /**
+     * Changes the skill points
+     * - Cannot exceed the MaxSP parameter
+     * - Cannot have a negative value
+     *
+     * ```ts
+     * player.sp = 200
+     * ```
+     * @title Change SP
+     * @prop {number} player.sp
+     * @default MaxSPValue
+     * @memberof ParameterManager
+     * */
     sp: number;
+    /**
+     * Changing the player's experience.
+     * ```ts
+     * player.exp += 100
+     * ```
+     *
+     * Levels are based on the experience curve.
+     *
+     * ```ts
+     * console.log(player.level) // 1
+     * console.log(player.expForNextlevel) // 150
+     * player.exp += 160
+     * console.log(player.level) // 2
+     * ```
+     *
+     * @title Change Experience
+     * @prop {number} player.exp
+     * @default 0
+     * @memberof ParameterManager
+     * */
     exp: number;
+    /**
+     * Changing the player's level.
+     *
+     * ```ts
+     * player.level += 1
+     * ```
+     *
+     * The level will be between the initial level given by the `initialLevel` and final level given by `finalLevel`
+     *
+     * ```ts
+     * player.finalLevel = 50
+     * player.level = 60
+     * console.log(player.level) // 50
+     * ```
+     *
+     * @title Change Level
+     * @prop {number} player.level
+     * @default 1
+     * @memberof ParameterManager
+     * */
     level: number;
-    expForNextlevel: number;
-    param: {
+    /**
+     * ```ts
+     * console.log(player.expForNextlevel) // 150
+     * ```
+     * @title Experience for next level ?
+     * @prop {number} player.expForNextlevel
+     * @readonly
+     * @memberof ParameterManager
+     * */
+    readonly expForNextlevel: number;
+    /**
+     * Read the value of a parameter. Put the name of the parameter.
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * console.log(player.param[MAXHP])
+     * ```
+     *
+     * > Possible to use the `player.getParamValue(name)` method instead
+     * @title Get Param Value
+     * @prop {object} player.param
+     * @readonly
+     * @memberof ParameterManager
+     * */
+    readonly param: {
         [key: string]: number;
     };
+    /**
+     * Direct parameter modifiers (reactive signal)
+     *
+     * > It is important that these parameters have been created beforehand with the `addParameter()` method.
+     * > By default, the following settings have been created:
+     * - maxhp
+     * - maxsp
+     * - str
+     * - int
+     * - dex
+     * - agi
+     *
+     * **Object Key**
+     *
+     * The key of the object is the name of the parameter
+     *
+     * > The good practice is to retrieve the name coming from a constant
+     *
+     * **Object Value**
+     *
+     * The value of the key is an object containing:
+     * ```
+     * {
+     *   value: number,
+     *   rate: number
+     * }
+     * ```
+     *
+     * - value: Adds a number to the parameter
+     * - rate: Adds a rate to the parameter
+     *
+     * > Note that you can put both (value and rate)
+     *
+     * This property uses reactive signals - changes automatically trigger parameter recalculation.
+     * The final parameter values in `param` include aggregated modifiers from equipment, states, etc.
+     *
+     * @prop {Object} [paramsModifier]
+     * @example
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * // Set direct modifiers (reactive)
+     * player.paramsModifier = {
+     *      [MAXHP]: {
+     *          value: 100
+     *      }
+     * }
+     *
+     * // Parameters automatically recalculate
+     * console.log(player.param[MAXHP]); // Updated value
+     * ```
+     *
+     * @title Set Parameters Modifier
+     * @prop {object} paramsModifier
+     * @memberof ParameterManager
+     * */
     paramsModifier: {
         [key: string]: {
             value?: number;
             rate?: number;
         };
     };
+    /**
+     * Get or set the parameters object
+     *
+     * @prop {object} parameters
+     * @memberof ParameterManager
+     */
+    parameters: {
+        [key: string]: {
+            start: number;
+            end: number;
+        };
+    };
+    /**
+     * Get the value of a specific parameter by name
+     *
+     * @deprecated Use `player.param[name]` instead for better reactivity
+     * @param name - The name of the parameter to get
+     * @returns The calculated parameter value
+     *
+     * @example
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * // Preferred way (reactive)
+     * const maxHp = player.param[MAXHP];
+     *
+     * // Legacy way (still works)
+     * const maxHp = player.getParamValue(MAXHP);
+     * ```
+     */
+    getParamValue(name: string): number;
+    /**
+     * Give a new parameter. Give a start value and an end value.
+     * The start value will be set to the level set at `player.initialLevel` and the end value will be linked to the level set at `player.finalLevel`.
+     *
+     * ```ts
+     * const SPEED = 'speed'
+     *
+     * player.addParameter(SPEED, {
+     *     start: 10,
+     *     end: 100
+     * })
+     *
+     * player.param[SPEED] // 10
+     * player.level += 5
+     * player.param[SPEED] // 14
+     * ```
+     *
+     * @title Add custom parameters
+     * @method player.addParameter(name,curve)
+     * @param {string} name - The name of the parameter
+     * @param {object} curve - Scheme of the object: { start: number, end: number }
+     * @returns {void}
+     * @memberof ParameterManager
+     * */
+    addParameter(name: string, curve: {
+        start: number;
+        end: number;
+    }): void;
+    /**
+     * Gives back in percentage of health points to skill points
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * console.log(player.param[MAXHP]) // 800
+     * player.hp = 100
+     * player.recovery({ hp: 0.5 }) // = 800 * 0.5
+     * console.log(player.hp) // 400
+     * ```
+     *
+     * @title Recovery HP and/or SP
+     * @method player.recovery(params)
+     * @param {object} params - Scheme of the object: { hp: number, sp: number }. The values of the numbers must be in 0 and 1
+     * @returns {void}
+     * @memberof ParameterManager
+     * */
+    recovery(params: {
+        hp?: number;
+        sp?: number;
+    }): void;
+    /**
+     * restores all HP and SP
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP, MAXSP } = Presets
+     *
+     * console.log(player.param[MAXHP], player.param[MAXSP]) // 800, 230
+     * player.hp = 100
+     * player.sp = 0
+     * player.allRecovery()
+     * console.log(player.hp, player.sp) // 800, 230
+     * ```
+     *
+     * @title All Recovery
+     * @method player.allRecovery()
+     * @returns {void}
+     * @memberof ParameterManager
+     * */
+    allRecovery(): void;
 }
 /**
- * Mixin that adds parameter management functionality to a player class.
+ * Parameter Manager Mixin with Reactive Signals
  *
- * This mixin provides comprehensive parameter management including:
- * - Health Points (HP) and Skill Points (SP) management
- * - Experience and level progression system
- * - Custom parameter creation and modification
- * - Parameter modifiers for temporary stat changes
+ * Provides comprehensive parameter management functionality using reactive signals from `@signe/reactive`.
+ * This mixin handles health points (HP), skill points (SP), experience and level progression,
+ * custom parameters, and parameter modifiers with automatic reactivity.
+ *
+ * **Key Features:**
+ * - ✨ **Reactive Parameters**: All parameters automatically recalculate when level or modifiers change
+ * - 🚀 **Performance Optimized**: Uses computed signals to avoid unnecessary recalculations
+ * - 🔄 **Real-time Updates**: Changes propagate automatically throughout the system
+ * - 🎯 **Type Safe**: Full TypeScript support with proper type inference
  *
  * @template TBase - The base class constructor type
- * @param Base - The base class to extend
- * @returns A new class that extends the base with parameter management capabilities
+ * @param Base - The base class to extend with parameter management
+ * @returns Extended class with reactive parameter management methods
  *
  * @example
  * ```ts
  * class MyPlayer extends WithParameterManager(BasePlayer) {
  *   constructor() {
  *     super();
+ *
+ *     // Add custom parameters
  *     this.addParameter('strength', { start: 10, end: 100 });
+ *     this.addParameter('magic', { start: 5, end: 80 });
  *   }
  * }
+ *
+ * const player = new MyPlayer();
+ *
+ * // Reactive parameter updates
+ * player.level = 5;
+ * console.log(player.param.strength); // Automatically calculated for level 5
+ *
+ * // Reactive modifiers
+ * player.paramsModifier = {
+ *   [MAXHP]: { value: 100, rate: 1.2 }
+ * };
+ * console.log(player.param[MAXHP]); // Automatically includes modifiers
  * ```
  */
-export declare function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase): TBase & Constructor<IWithParameterManager>;
+export declare function WithParameterManager<TBase extends PlayerCtor>(Base: TBase): TBase;