@rpgjs/server 5.0.0-alpha.10 → 5.0.0-alpha.12

package/src/Player/ParameterManager.ts

@@ -1,67 +1,509 @@
 import { isString, PlayerCtor } from "@rpgjs/common";
+import { signal, computed, WritableSignal, ComputedSignal } from "@signe/reactive";
 import { MAXHP, MAXSP } from "../presets";
-
+import { sync, type } from "@signe/sync";
 
 /**
- * Mixin that adds parameter management functionality to a player class.
- * 
- * 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
+ * Interface for Parameter Manager functionality
  * 
- * @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
- * 
- * @example
- * ```ts
- * class MyPlayer extends WithParameterManager(BasePlayer) {
- *   constructor() {
- *     super();
- *     this.addParameter('strength', { start: 10, end: 100 });
- *   }
- * }
- * ```
+ * 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: { 
+    basis: number,
+    extra: number,
+    accelerationA: number
+    accelerationB: number
+  };
+
+  /** 
+   * 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;
+
+  /** 
+   * ```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;
+}
+
 /**
- * Parameter Manager Mixin
+ * Parameter Manager Mixin with Reactive Signals
+ * 
+ * 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.
  * 
- * Provides comprehensive parameter management functionality to any class. This mixin handles
- * health points (HP), skill points (SP), experience and level progression, custom parameters,
- * and parameter modifiers for temporary stat changes.
+ * **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 with parameter management
- * @returns Extended class with parameter management methods
+ * @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();
- * player.hp = 100;
+ * 
+ * // 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 function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
   return class extends Base {
-    _paramsModifier: {
+    /**
+     * Signal for parameter modifiers - allows reactive updates when modifiers change
+     * 
+     * This signal tracks temporary parameter modifications from equipment, states, etc.
+     * When updated, it automatically triggers recalculation of all computed parameters.
+     * 
+     * @example
+     * ```ts
+     * // Set modifier that adds 100 to MaxHP
+     * player.paramsModifier = {
+     *   [MAXHP]: { value: 100 }
+     * };
+     * 
+     * // Parameters automatically recalculate
+     * console.log(player.param[MAXHP]); // Updated value
+     * ```
+     */
+    private _paramsModifierSignal = signal<{
         [key: string]: {
             value?: number,
             rate?: number
         }
-    } = {}
+    }>({})
 
-    _parameters: Map<string, {
-        start: number,
-        end: number
-    }> = new Map()
+    /**
+     * Signal for base parameters configuration
+     * 
+     * Stores the start and end values for each parameter's level curve.
+     * Changes to this signal trigger recalculation of all parameter values.
+     */
+    private _parametersSignal = signal<{
+        [key: string]: {
+            start: number,
+            end: number
+        }
+    }>({})
+
+    /**
+     * Computed signal for all parameter values
+     * 
+     * Automatically recalculates all parameter values when level or modifiers change.
+     * This provides reactive parameter updates throughout the system.
+     * 
+     * @example
+     * ```ts
+     * // Access reactive parameters
+     * const maxHp = player.param[MAXHP]; // Always current value
+     * 
+     * // Parameters update automatically when level changes
+     * player.level = 10;
+     * console.log(player.param[MAXHP]); // New calculated value
+     * ```
+     */
+    _param = type(computed(() => {
+        const obj = {}
+        const parameters = this._parametersSignal()
+        const level = this._level()
+        
+        for (const [name, paramConfig] of Object.entries(parameters)) {
+            let curveVal = Math.floor((paramConfig.end - paramConfig.start) * ((level - 1) / (this.finalLevel - this.initialLevel))) + paramConfig.start
+            
+            // Apply modifiers from equipment, states, etc.
+            const allModifiers = this._getAggregatedModifiers()
+            const modifier = allModifiers[name]
+            if (modifier) {
+                if (modifier.rate) curveVal *= modifier.rate
+                if (modifier.value) curveVal += modifier.value
+            }
+            
+            obj[name] = curveVal
+        }
+        
+        return obj
+    }) as any, '_param', {}, this as any) 
+
+    /**
+     * Aggregates parameter modifiers from all sources (direct modifiers, states, equipment)
+     * 
+     * This method combines modifiers from multiple sources and calculates the final
+     * modifier values for each parameter. It handles both value and rate modifiers.
+     * 
+     * @returns Aggregated parameter modifiers
+     * 
+     * @example
+     * ```ts
+     * // Internal usage - gets modifiers from all sources
+     * const modifiers = this._getAggregatedModifiers();
+     * console.log(modifiers[MAXHP]); // { value: 100, rate: 1.2 }
+     * ```
+     */
+    private _getAggregatedModifiers(): { [key: string]: { value?: number, rate?: number } } {
+        const params = {}
+        const paramsAvg = {}
+        
+        const changeParam = (paramsModifier) => {
+            for (let key in paramsModifier) {
+                const { rate, value } = paramsModifier[key]
+                if (!params[key]) params[key] = { rate: 0, value: 0 }
+                if (!paramsAvg[key]) paramsAvg[key] = 0
+                if (value) params[key].value += value
+                if (rate !== undefined) params[key].rate += rate
+                paramsAvg[key]++
+            }
+        }
+        
+        const getModifier = (prop) => {
+            if (!isString(prop)) {
+                changeParam(prop)
+                return
+            }
+            for (let el of this[prop]()) {
+                if (!el.paramsModifier) continue
+                changeParam(el.paramsModifier)
+            }
+        }
+        
+        // Aggregate modifiers from all sources
+        getModifier(this._paramsModifierSignal())
+        getModifier('states')
+        getModifier('equipments')
+        
+        // Average the rates
+        for (let key in params) {
+            params[key].rate /= paramsAvg[key]
+        }
+        
+        return params
+    }
 
      /** 
      * ```ts
@@ -135,12 +577,9 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
             this['execMethod']('onDead') 
             val = 0
         }
-        (this as any)._hp.set(val)
+        this.hpSignal.set(val)
     }
 
-    get hp(): number {
-        return (this as any)._hp()
-    }
 
     /** 
      * Changes the skill points
@@ -159,12 +598,10 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
         if (val > this.param[MAXSP]) {
             val = this.param[MAXSP]
         }
-        this._sp.set(val)
+        this.spSignal.set(val)
     }
 
-    get sp(): number {
-        return this._sp()
-    }
+   
 
     /** 
      * Changing the player's experience. 
@@ -276,43 +713,11 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
      * @memberof ParameterManager
      * */
     get param() {
-        const obj = {}
-        this._parameters.forEach((val, name) => {
-            obj[name] = this.getParamValue(name)
-        })
-        return obj
+        return this._param()
     }
 
     get paramsModifier() {
-        const params = {}
-        const paramsAvg = {}
-        const changeParam = (paramsModifier) => {
-            for (let key in paramsModifier) {
-                const { rate, value } = paramsModifier[key]
-                if (!params[key]) params[key] = { rate: 0, value: 0 }
-                if (!paramsAvg[key]) paramsAvg[key] = 0
-                if (value) params[key].value += value
-                if (rate !== undefined) params[key].rate += rate
-                paramsAvg[key]++
-            }
-        }
-        const getModifier = (prop) => {
-            if (!isString(prop)) {
-                changeParam(prop)
-                return
-            }
-            for (let el of this[prop]()) {
-                if (!el.paramsModifier) continue
-                changeParam(el.paramsModifier)
-            }
-        }
-        getModifier(this._paramsModifier)
-        getModifier('states')
-        getModifier('equipments')
-        for (let key in params) {
-            params[key].rate /= paramsAvg[key]
-        }
-        return params
+        return this._paramsModifierSignal()
     }
 
     /** 
@@ -378,15 +783,15 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
             rate?: number
         }
     }) {
-        this._paramsModifier = val
+        this._paramsModifierSignal.set(val)
     }
 
     get parameters() {
-        return this._parameters
+        return this._parametersSignal()
     }
 
     set parameters(val) {
-        this._parameters = val
+        this._parametersSignal.set(val)
     }
 
     private _expForLevel(level: number): number {
@@ -399,23 +804,8 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
         return Math.round(basis * (Math.pow(level - 1, 0.9 + accelerationA / 250)) * level * (level + 1) / (6 + Math.pow(level, 2) / 50 / accelerationB) + (level - 1) * extra)
     }
 
-    private getParam(name: string) {
-        const features = this._parameters.get(name)
-        if (!features) {
-            throw `Parameter ${name} not exists. Please use addParameter() before`
-        }
-        return features
-    }
-
     getParamValue(name: string): number | never {
-        const features = this.getParam(name)
-        let curveVal = Math.floor((features.end - features.start) * ((this.level-1) / (this.finalLevel - this.initialLevel))) + features.start
-        const modifier = this.paramsModifier[name]
-        if (modifier) {
-            if (modifier.rate) curveVal *= modifier.rate
-            if (modifier.value) curveVal += modifier.value
-        }
-        return curveVal
+        return this.param[name]
     }
 
     /** 
@@ -437,15 +827,17 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
      * 
      * @title Add custom parameters
      * @method player.addParameter(name,curve)
-     * @param {name} name 
-     * @param {object} curve Scheme of the object: { start: number, end: number }
+     * @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, { start, end }: { start: number, end: number }): void {
-        this._parameters.set(name, {
-            start,
-            end
+        this._parametersSignal.mutate(parameters => {
+            parameters[name] = {
+                start,
+                end
+            }
         })
         const maxHp = this.param[MAXHP]
         const maxSp = this.param[MAXSP]
@@ -473,7 +865,7 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
      * 
      * @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
+     * @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
      * */
@@ -506,6 +898,4 @@ export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
         this.recovery({ hp: 1, sp: 1 })
     }
   } as unknown as TBase;
-}
-
-export type IParameterManager = InstanceType<ReturnType<typeof WithParameterManager>>;
+}