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

package/src/Player/ParameterManager.ts

@@ -1,59 +1,536 @@
-import { Constructor, isString, RpgCommonPlayer } from "@rpgjs/common";
-import { MAXHP, MAXSP } from "../presets";
-
-export interface IWithParameterManager {
-  parameters: Map<string, any>
-  hp: number
-  sp: number
-  exp: number
-  level: number
-  expForNextlevel: number
-  param: { [key: string]: number }
-  paramsModifier: { [key: string]: { value?: number, rate?: number } }
+import { isString, PlayerCtor } from "@rpgjs/common";
+import { signal, computed, WritableSignal, ComputedSignal } from "@signe/reactive";
+import { MAXHP, MAXSP } from "@rpgjs/common";
+import { type } from "@signe/sync";
+
+export type ExpCurve = {
+  basis: number;
+  extra: number;
+  accelerationA: number;
+  accelerationB: number;
+};
+
+const DEFAULT_EXP_CURVE: ExpCurve = {
+  basis: 30,
+  extra: 20,
+  accelerationA: 30,
+  accelerationB: 30
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
 }
 
-interface PlayerWithMixins extends RpgCommonPlayer {
-    databaseById?(id: string): any;  
+function toValidNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function normalizeExpCurve(value: unknown): ExpCurve {
+  if (!isObject(value)) return DEFAULT_EXP_CURVE;
+
+  return {
+    basis: toValidNumber(value.basis, DEFAULT_EXP_CURVE.basis),
+    extra: toValidNumber(value.extra, DEFAULT_EXP_CURVE.extra),
+    accelerationA: toValidNumber(value.accelerationA, DEFAULT_EXP_CURVE.accelerationA),
+    accelerationB: toValidNumber(value.accelerationB, DEFAULT_EXP_CURVE.accelerationB)
+  };
 }
 
 /**
- * Mixin that adds parameter management functionality to a player class.
+ * Interface for Parameter Manager functionality
  * 
- * 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 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;
+
+  /** 
+   * ```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 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.
+ * 
+ * **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 function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>(
-  Base: TBase
-): TBase & Constructor<IWithParameterManager> {
-  return class extends Base implements IWithParameterManager {
-    private _paramsModifier: {
+export function WithParameterManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
+    /**
+     * 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 = type(signal<{
         [key: string]: {
             value?: number,
             rate?: number
         }
-    } = {}
+    }>({}) as any, '_paramsModifierSignal', { persist: true }, this as any)
 
-    private _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 = type(signal<{
+        [key: string]: {
+            start: number,
+            end: number
+        }
+    }>({}) as any, '_parametersSignal', { persist: true }, this as any)
+
+    /**
+     * 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 allModifiers = this._getAggregatedModifiers()
+        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
+            
+            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
@@ -98,11 +575,22 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
      * ```
      * @memberof ParameterManager
      * */
-    public expCurve: { 
-        basis: number,
-        extra: number,
-        accelerationA: number
-        accelerationB: number
+    public _expCurveSignal = type(signal<string>(JSON.stringify(DEFAULT_EXP_CURVE)) as any, '_expCurveSignal', { persist: true }, this as any)
+
+    get expCurve(): ExpCurve { 
+        const raw = this._expCurveSignal()
+        if (!raw) return DEFAULT_EXP_CURVE
+
+        try {
+            return normalizeExpCurve(JSON.parse(raw))
+        }
+        catch {
+            return DEFAULT_EXP_CURVE
+        }
+    }
+
+    set expCurve(val: ExpCurve) {
+        this._expCurveSignal.set(JSON.stringify(val)) 
     }
     
     /** 
@@ -127,11 +615,11 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
             this['execMethod']('onDead') 
             val = 0
         }
-        this._hp.set(val)
+        this.hpSignal.set(val)
     }
 
     get hp(): number {
-        return this._hp()
+        return this.hpSignal()
     }
 
     /** 
@@ -151,12 +639,12 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
         if (val > this.param[MAXSP]) {
             val = this.param[MAXSP]
         }
-        this._sp.set(val)
+        this.spSignal.set(val)
     }
 
     get sp(): number {
-        return this._sp()
-    }
+        return this.spSignal()
+    }   
 
     /** 
      * Changing the player's experience. 
@@ -236,7 +724,6 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
     get level(): number {
         return this._level()
     }
-
      /** 
      * ```ts
      * console.log(player.expForNextlevel) // 150
@@ -268,43 +755,11 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
      * @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()
     }
 
     /** 
@@ -370,15 +825,15 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
             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 {
@@ -391,23 +846,8 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
         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]
     }
 
     /** 
@@ -429,15 +869,17 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
      * 
      * @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]
@@ -465,7 +907,7 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
      * 
      * @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
      * */
@@ -497,5 +939,5 @@ export function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>
     allRecovery(): void {
         this.recovery({ hp: 1, sp: 1 })
     }
-  }
-}
+  } as unknown as TBase;
+}