@rpgjs/server 5.0.0-alpha.5 → 5.0.0-alpha.7

package/src/Player/StateManager.ts

@@ -1,4 +1,4 @@
-import { isInstanceOf, isString, type Constructor } from "@rpgjs/common";
+import { isInstanceOf, isString, PlayerCtor, type Constructor } from "@rpgjs/common";
 import { RpgCommonPlayer, Matter, SeekAvoid } from "@rpgjs/common";
 import { signal, type WritableArraySignal } from "@signe/reactive";
 import { ATK, PDEF, SDEF } from "../presets";
@@ -13,41 +13,51 @@ interface StateManagerDependencies {
   removeState(stateClass: StateClass | string, chance?: number): void;
 }
 
-/**
- * Interface defining what MoveManager adds to a class
- */
-export interface IStateManager {
-  statesDefense: { rate: number; state: any }[];
-  statesEfficiency: WritableArraySignal<any[]>;
-  applyStates(
-    player: RpgPlayer,
-    states: { addStates?: any[]; removeStates?: any[] }
-  ): void;
-  getState(stateClass: StateClass | string): any;
-  addState(stateClass: StateClass | string, chance?: number): object | null;
-  removeState(stateClass: StateClass | string, chance?: number): void;
-}
+
 
 type StateClass = { new (...args: any[]) };
 
 /**
- * Move Manager mixin
- *
- * Adds methods to manage player movement
- *
- * @param Base - The base class to extend
- * @returns A new class with move management capabilities
+ * State Manager Mixin
+ * 
+ * Provides state management capabilities to any class. This mixin handles
+ * player states (buffs/debuffs), state defense from equipment, and state
+ * efficiency modifiers. It manages the complete state system including
+ * application, removal, and resistance mechanics.
+ * 
+ * @param Base - The base class to extend with state management
+ * @returns Extended class with state management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithStateManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // State system is automatically initialized
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * player.addState(Paralyze);
+ * console.log(player.getState(Paralyze));
+ * ```
  */
-export function WithStateManager<
-  TBase extends Constructor<RpgCommonPlayer & StateManagerDependencies>
->(Base: TBase): Constructor<IStateManager> & TBase {
-  return class extends Base implements IStateManager {
+export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
     _statesEfficiency = signal<any[]>([]);
 
     /**
      * Recovers the player's states defense on inventory.  This list is generated from the `statesDefense` property defined on the weapons or armors equipped.
      * If several items have the same element, only the highest rate will be taken into account.
      *
+     * Gets the defensive capabilities against various states from equipped items.
+     * The system automatically consolidates multiple defensive items, keeping only
+     * the highest protection rate for each state type. This provides comprehensive
+     * protection against debuffs and negative status effects.
+     * 
+     * @returns Array of state defense objects with rate and state properties
+     * 
+     * @example
      * ```ts
      * import { Armor, State } from '@rpgjs/server'
      *
@@ -74,19 +84,29 @@ export function WithStateManager<
      * player.equip(FireShield)
      *
      * console.log(player.statesDefense) // [{ rate: 1, state: instance of Paralyze }]
+     * 
+     * // Check specific state defense
+     * const paralyzeDefense = player.statesDefense.find(def => def.state instanceof Paralyze);
+     * if (paralyzeDefense) {
+     *   console.log(`Paralyze defense rate: ${paralyzeDefense.rate}`);
+     * }
      * ```
-     * @title Get States Defense
-     * @prop {Array<{ rate: number, state: StateClass}>} player.statesDefense
-     * @readonly
-     * @memberof StateManager
-     * */
+     */
     get statesDefense(): { rate: number; state: any }[] {
-      return this.getFeature("statesDefense", "state");
+      return (this as any).getFeature("statesDefense", "state");
     }
 
     /**
      * Set or retrieves all the states where the player is vulnerable or not.
      *
+     * Manages the player's state efficiency modifiers, which determine how
+     * effective different states are against this player. Values greater than 1
+     * indicate vulnerability, while values less than 1 indicate resistance.
+     * This combines both class-based efficiency and player-specific modifiers.
+     * 
+     * @returns Array of state efficiency objects with rate and state properties
+     * 
+     * @example
      * ```ts
      * import { Class, State } from '@rpgjs/server'
      *
@@ -113,11 +133,16 @@ export function WithStateManager<
      * player.statesEfficiency = [{ rate: 2, state: Sleep }]
      *
      * console.log(player.statesEfficiency) // [{ rate: 1, state: instance of Paralyze }, { rate: 2, state: instance of Sleep }]
+     * 
+     * // Check for vulnerabilities
+     * const vulnerabilities = player.statesEfficiency.filter(eff => eff.rate > 1);
+     * console.log('Vulnerable to states:', vulnerabilities.map(v => v.state.name));
+     * 
+     * // Check for resistances
+     * const resistances = player.statesEfficiency.filter(eff => eff.rate < 1);
+     * console.log('Resistant to states:', resistances.map(r => r.state.name));
      * ```
-     * @title Set/Get States Efficiency
-     * @prop {Array<{ rate: number, state: StateClass}>} player.statesEfficiency
-     * @memberof StateManager
-     * */
+     */
     get statesEfficiency() {
       return this._statesEfficiency;
     }
@@ -126,38 +151,87 @@ export function WithStateManager<
       this._statesEfficiency = val;
     }
 
+    /**
+     * Apply states to a player from skill or item effects
+     * 
+     * Processes state application and removal based on skill or item effects.
+     * This method handles both adding beneficial states and removing negative ones,
+     * with proper chance calculation and resistance checks.
+     * 
+     * @param player - The target player to apply states to
+     * @param states - Object containing arrays of states to add or remove
+     * 
+     * @example
+     * ```ts
+     * // Apply states from a healing skill
+     * const healingStates = {
+     *   addStates: [{ state: Regeneration, rate: 0.8 }],
+     *   removeStates: [{ state: Poison, rate: 1.0 }]
+     * };
+     * player.applyStates(targetPlayer, healingStates);
+     * 
+     * // Apply debuff from an enemy attack
+     * const debuffStates = {
+     *   addStates: [
+     *     { state: Paralyze, rate: 0.3 },
+     *     { state: Slow, rate: 0.5 }
+     *   ]
+     * };
+     * player.applyStates(targetPlayer, debuffStates);
+     * ```
+     */
     applyStates(
-      player: RpgPlayer & IStateManager,
+      player: RpgPlayer,
       { addStates, removeStates }
     ) {
       if (addStates) {
         for (let { state, rate } of addStates) {
-          player.addState(state, rate);
+          (player as any).addState(state, rate);
         }
       }
       if (removeStates) {
         for (let { state, rate } of removeStates) {
-          player.removeState(state, rate);
+          (player as any).removeState(state, rate);
         }
       }
     }
 
     /**
      * Get a state to the player. Returns `null` if the state is not present on the player
+     * 
+     * Retrieves a specific state instance from the player's active states.
+     * This is useful for checking state properties, duration, or performing
+     * state-specific operations. Returns null if the state is not currently active.
+     * 
+     * @param stateClass - The state class constructor or state ID to search for
+     * @returns The state instance if found, null otherwise
+     * 
+     * @example
      * ```ts
      * import Paralyze from 'your-database/states/paralyze'
      *
-     * player.getState(Paralyze)
-     *  ```
-     *
-     * @title Get State
-     * @method player.getState(stateClass)
-     * @param {StateClass | string} stateClass or state id
-     * @returns {instance of StateClass | null}
-     * @memberof StateManager
+     * // Check if player has a specific state
+     * const paralyzeState = player.getState(Paralyze);
+     * if (paralyzeState) {
+     *   console.log('Player is paralyzed');
+     *   console.log('Remaining duration:', paralyzeState.duration);
+     * }
+     * 
+     * // Check using string ID
+     * const poisonState = player.getState('poison');
+     * if (poisonState) {
+     *   console.log('Player is poisoned');
+     * }
+     * 
+     * // Use in conditional logic
+     * if (player.getState(Sleep)) {
+     *   console.log('Player cannot act while sleeping');
+     *   return; // Skip player turn
+     * }
+     * ```
      */
     getState(stateClass: StateClass | string) {
-      if (isString(stateClass)) stateClass = this.databaseById(stateClass);
+      if (isString(stateClass)) stateClass = (this as any).databaseById(stateClass);
       return this.states().find((state) => {
         if (isString(stateClass)) {
           return state.id == stateClass;
@@ -168,37 +242,56 @@ export function WithStateManager<
 
     /**
      * Adds a state to the player. Set the chance between 0 and 1 that the state can apply
+     * 
+     * Attempts to apply a state to the player with a specified success chance.
+     * The method considers state resistance, efficiency modifiers, and random chance
+     * to determine if the state is successfully applied. If successful, the state
+     * is added to the player's active states list.
+     * 
+     * @param stateClass - The state class constructor or state ID to apply
+     * @param chance - Probability of successful application (0-1, default 1)
+     * @returns The state instance if successfully applied, null if already present
+     * @throws StateLog.addFailed if the chance roll fails
+     * 
+     * @example
      * ```ts
      * import Paralyze from 'your-database/states/paralyze'
      *
      * try {
-     *      player.addState(Paralyze)
+     *   // Attempt to apply paralyze with 100% chance
+     *   const state = player.addState(Paralyze);
+     *   if (state) {
+     *     console.log('Paralyze applied successfully');
+     *   }
+     * } catch (err) {
+     *   console.log('Failed to apply paralyze:', err.msg);
      * }
-     * catch (err) {
-     *      console.log(err)
-     * }
-     *  ```
-     *
-     * @title Add State
-     * @method player.addState(stateClass,chance=1)
-     * @param {StateClass | string} stateClass state class or state id
-     * @param {number} [chance] 1 by default
-     * @throws {StateLog} addFailed
-     * If the chance to add the state has failed (defined with the `chance` param)
-     *  ```
-     * {
-     *      id: ADD_STATE_FAILED,
-     *      msg: '...'
+     * 
+     * // Apply with reduced chance
+     * try {
+     *   player.addState(Poison, 0.3); // 30% chance
+     * } catch (err) {
+     *   console.log('Poison application failed');
      * }
+     * 
+     * // Apply multiple states with different chances
+     * const debuffs = [
+     *   { state: Slow, chance: 0.8 },
+     *   { state: Weak, chance: 0.6 }
+     * ];
+     * debuffs.forEach(({ state, chance }) => {
+     *   try {
+     *     player.addState(state, chance);
+     *   } catch (err) {
+     *     // Handle failed applications
+     *   }
+     * });
      * ```
-     * @returns {instance of StateClass}
-     * @memberof StateManager
-     * @todo
      */
     addState(stateClass: StateClass | string, chance = 1): object | null {
       const state = this.getState(stateClass);
       if (isString(stateClass)) {
-        stateClass = this.databaseById(stateClass);
+        stateClass = (this as any).databaseById(stateClass);
       }
       if (!state) {
         if (Math.random() > chance) {
@@ -215,39 +308,49 @@ export function WithStateManager<
 
     /**
      * Remove a state to the player. Set the chance between 0 and 1 that the state can be removed
+     * 
+     * Attempts to remove a state from the player with a specified success chance.
+     * This is useful for cure spells, items, or time-based state removal.
+     * The method considers removal resistance and random chance.
+     * 
+     * @param stateClass - The state class constructor or state ID to remove
+     * @param chance - Probability of successful removal (0-1, default 1)
+     * @throws StateLog.removeFailed if the chance roll fails
+     * @throws StateLog.notApplied if the state is not currently active
+     * 
+     * @example
      * ```ts
      * import Paralyze from 'your-database/states/paralyze'
      *
      * try {
-     *      player.removeState(Paralyze)
-     * }
-     * catch (err) {
-     *      console.log(err)
-     * }
-     *  ```
-     *
-     * @title Remove State
-     * @method player.removeState(stateClass,chance=1)
-     * @param {StateClass|string} stateClass class state or state id
-     * @param {number} [chance] 1 by default
-     * @throws {StateLog} removeFailed
-     * If the chance to remove the state has failed (defined with the `chance` param)
-     *  ```
-     * {
-     *      id: REMOVE_STATE_FAILED,
-     *      msg: '...'
+     *   // Attempt to remove paralyze with 100% chance
+     *   player.removeState(Paralyze);
+     *   console.log('Paralyze removed successfully');
+     * } catch (err) {
+     *   if (err.id === 'STATE_NOT_APPLIED') {
+     *     console.log('Player was not paralyzed');
+     *   } else {
+     *     console.log('Failed to remove paralyze:', err.msg);
+     *   }
      * }
-     * ```
-     * @throws {StateLog} notApplied
-     * If the status does not exist
-     *  ```
-     * {
-     *      id: STATE_NOT_APPLIED,
-     *      msg: '...'
+     * 
+     * // Remove with reduced chance (for weak cure spells)
+     * try {
+     *   player.removeState(Poison, 0.7); // 70% chance
+     * } catch (err) {
+     *   console.log('Cure failed');
      * }
+     * 
+     * // Remove all negative states (cure-all effect)
+     * const negativeStates = [Poison, Paralyze, Sleep, Slow];
+     * negativeStates.forEach(state => {
+     *   try {
+     *     player.removeState(state);
+     *   } catch (err) {
+     *     // State wasn't active, continue
+     *   }
+     * });
      * ```
-     * @returns {instance of StateClass}
-     * @memberof StateManager
      */
     removeState(stateClass: StateClass | string, chance = 1) {
       const index = this.states().findIndex((state) => {
@@ -266,10 +369,22 @@ export function WithStateManager<
       }
     }
 
-    private findStateEfficiency(stateClass) {
+    /**
+     * Find state efficiency modifier for a specific state class
+     * 
+     * @param stateClass - The state class to find efficiency for
+     * @returns The efficiency object if found, undefined otherwise
+     */
+    findStateEfficiency(stateClass) {
       return this.statesEfficiency().find((state) =>
         isInstanceOf(state.state, stateClass)
       );
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * Type helper to extract the interface from the WithStateManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IStateManager = InstanceType<ReturnType<typeof WithStateManager>>;

package/src/Player/VariableManager.ts

@@ -1,75 +1,207 @@
-import { type Constructor } from "@rpgjs/common";
-import { RpgCommonPlayer } from "@rpgjs/common";
+import { Constructor, PlayerCtor } from "@rpgjs/common";
 
 /**
- * Interface defining what MoveManager adds to a class
- */
-export interface IWithVariableManager {
-  variables: Map<string, any>
-}
-
-/**
- * Move Manager mixin
+ * Variable Manager Mixin
+ * 
+ * Provides variable management capabilities to any class. Variables are key-value
+ * pairs that can store any type of data associated with the player, such as
+ * quest progress, game flags, inventory state, and custom game data.
+ * 
+ * @param Base - The base class to extend with variable management
+ * @returns Extended class with variable management methods
  * 
- * Adds methods to manage player movement
+ * @example
+ * ```ts
+ * class MyPlayer extends WithVariableManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Variables are automatically initialized
+ *   }
+ * }
  * 
- * @param Base - The base class to extend
- * @returns A new class with move management capabilities
+ * const player = new MyPlayer();
+ * player.setVariable('questCompleted', true);
+ * ```
  */
-export function WithVariableManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase) {
-  return class extends Base implements IWithVariableManager {
-    variables: Map<string, any> = new Map()
+export function WithVariableManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
+    variables: Map<string, any> = new Map();
 
     /** 
      * Assign a variable to the player
      * 
+     * Stores a key-value pair in the player's variable map. This is useful for
+     * tracking game state, quest progress, flags, and other player-specific data.
+     * The variable system provides a flexible way to store any type of data
+     * associated with the player that persists throughout the game session.
+     * 
+     * @param key - The variable identifier (string key to reference the variable)
+     * @param val - The value to store (can be any type: boolean, number, string, object, array)
+     * @returns void
+     * 
+     * @example
      * ```ts
-     * player.setVariable('OPEN_CHEST', true)
+     * // Set different types of variables
+     * player.setVariable('CHEST_OPENED', true);
+     * player.setVariable('playerLevel', 5);
+     * player.setVariable('questProgress', { step: 1, completed: false });
+     * player.setVariable('inventory', ['sword', 'potion', 'key']);
+     * player.setVariable('lastSaveTime', new Date().toISOString());
      * ```
-     * 
-     * @title Set variable
-     * @method player.setVariable(key,val)
-     * @param {string} key
-     * @param {any} val
-     * @returns {void}
-     * @memberof VariableManager
-     * */
-    setVariable(key: string, val) {
-        this.variables.set(key, val)
+     */
+    setVariable(key: string, val: any): void {
+      this.variables.set(key, val);
     }
 
     /** 
-     * Get a variable
+     * Get a variable value
+     * 
+     * Retrieves the value associated with the given key from the player's variables.
+     * Returns undefined if the variable doesn't exist. This method is type-safe
+     * and can be used with generic types for better TypeScript support.
+     * 
+     * @param key - The variable identifier to retrieve
+     * @returns The stored value or undefined if not found
      * 
+     * @example
      * ```ts
-     * const val = player.getVariable('OPEN_CHEST')
-     * ```
+     * // Get variables with type inference
+     * const hasKey = player.getVariable('CHEST_OPENED'); // boolean | undefined
+     * const level = player.getVariable('playerLevel'); // number | undefined
+     * const quest = player.getVariable('questProgress'); // object | undefined
+     * const missing = player.getVariable('nonexistent'); // undefined
      * 
-     * @title Get variable
-     * @method player.setVariable(key,val)
-     * @param {string} key
-     * @returns {any} 
-     * @memberof VariableManager
-     * */
-    getVariable(key: string) {
-        return this.variables.get(key)
+     * // Use with default values
+     * const level = player.getVariable('playerLevel') ?? 1;
+     * const isChestOpened = player.getVariable('CHEST_OPENED') ?? false;
+     * ```
+     */
+    getVariable<U = any>(key: string): U | undefined {
+      return this.variables.get(key);
     }
 
     /** 
      * Remove a variable
      * 
+     * Deletes a variable from the player's variable map. This is useful for
+     * cleaning up temporary flags, resetting certain game states, or managing
+     * memory by removing unused variables. The method returns a boolean indicating
+     * whether the variable existed and was successfully removed.
+     * 
+     * @param key - The variable identifier to remove
+     * @returns true if a variable existed and has been removed, false if the variable does not exist
+     * 
+     * @example
+     * ```ts
+     * // Remove variables and check if they existed
+     * const removed = player.removeVariable('CHEST_OPENED'); // true if existed
+     * const notFound = player.removeVariable('nonexistent'); // false
+     * 
+     * // Clean up temporary variables
+     * player.removeVariable('tempQuestFlag');
+     * player.removeVariable('battleTempData');
+     * 
+     * // Conditional removal
+     * if (player.getVariable('questCompleted')) {
+     *   player.removeVariable('questProgress');
+     * }
+     * ```
+     */
+    removeVariable(key: string): boolean {
+      return this.variables.delete(key);
+    }
+
+    /**
+     * Check if a variable exists
+     * 
+     * Determines whether a variable with the given key exists in the player's
+     * variable map, regardless of its value (including falsy values like false, 0, '').
+     * This is useful when you need to distinguish between a variable that doesn't
+     * exist and one that has a falsy value.
+     * 
+     * @param key - The variable identifier to check
+     * @returns true if the variable exists, false otherwise
+     * 
+     * @example
      * ```ts
-     * player.removeVariable('OPEN_CHEST')
+     * // Check variable existence
+     * player.setVariable('flag', false);
+     * player.hasVariable('flag'); // true (even though value is false)
+     * player.hasVariable('missing'); // false
+     * 
+     * // Use in conditional logic
+     * if (player.hasVariable('questStarted')) {
+     *   // Quest has been started, check progress
+     *   const progress = player.getVariable('questProgress');
+     * } else {
+     *   // Quest not started yet
+     *   player.setVariable('questStarted', true);
+     * }
+     * ```
+     */
+    hasVariable(key: string): boolean {
+      return this.variables.has(key);
+    }
+
+    /**
+     * Get all variable keys
+     * 
+     * Returns an array of all variable keys currently stored for this player.
+     * This is useful for debugging, serialization, or iterating over all variables.
+     * The keys are returned in insertion order.
+     * 
+     * @returns Array of all variable keys
+     * 
+     * @example
+     * ```ts
+     * // Get all variable keys
+     * const keys = player.getVariableKeys();
+     * console.log('Player has variables:', keys);
+     * 
+     * // Iterate over all variables
+     * keys.forEach(key => {
+     *   const value = player.getVariable(key);
+     *   console.log(`${key}: ${value}`);
+     * });
+     * 
+     * // Filter specific variable types
+     * const questKeys = keys.filter(key => key.startsWith('quest_'));
      * ```
+     */
+    getVariableKeys(): string[] {
+      return Array.from(this.variables.keys());
+    }
+
+    /**
+     * Clear all variables
      * 
-     * @title Remove variable
-     * @method player.removeVariable(key)
-     * @param {string} key
-     * @returns {boolean} true if a variable existed and has been removed, or false if the variable does not exist.
-     * @memberof VariableManager
-     * */
-    removeVariable(key: string) {
-        return this.variables.delete(key)
+     * Removes all variables from the player's variable map. This is useful for
+     * resetting the player state, cleaning up before saving, or starting fresh.
+     * Use with caution as this operation cannot be undone.
+     * 
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * // Clear all variables (use with caution)
+     * player.clearVariables();
+     * 
+     * // Clear variables conditionally
+     * if (gameReset) {
+     *   player.clearVariables();
+     *   // Re-initialize essential variables
+     *   player.setVariable('gameStarted', true);
+     * }
+     * ```
+     */
+    clearVariables(): void {
+      this.variables.clear();
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * Type helper to extract the interface from the WithVariableManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IVariableManager = InstanceType<ReturnType<typeof WithVariableManager>>;