@rpgjs/server 5.0.0-alpha.21 → 5.0.0-alpha.23

package/src/Player/StateManager.ts

@@ -46,103 +46,10 @@ 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'
-     *
-     * @State({
-     *      name: 'Paralyze'
-     * })
-     * class Paralyze {}
-     *
-     * @Armor({
-     *      name: 'Shield',
-     *      statesDefense: [{ rate: 1, state: Paralyze }]
-     * })
-     * class Shield {}
-     *
-     * @Armor({
-     *      name: 'FireShield',
-     *      statesDefense: [{ rate: 0.5, state: Paralyze }]
-     * })
-     * class FireShield {}
-     *
-     * player.addItem(Shield)
-     * player.addItem(FireShield)
-     * player.equip(Shield)
-     * 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}`);
-     * }
-     * ```
-     */
     get statesDefense(): { rate: number; state: any }[] {
       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'
-     *
-     * @State({
-     *      name: 'Paralyze'
-     * })
-     * class Paralyze {}
-     *
-     * @State({
-     *      name: 'Sleep'
-     * })
-     * class Sleep {}
-     *
-     * @Class({
-     *      name: 'Fighter',
-     *      statesEfficiency: [{ rate: 1, state: Paralyze }]
-     * })
-     * class Hero {}
-     *
-     * player.setClass(Hero)
-     *
-     * console.log(player.statesEfficiency) // [{ rate: 1, instance of Paralyze }]
-     *
-     * 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));
-     * ```
-     */
     get statesEfficiency() {
       return this._statesEfficiency;
     }
@@ -151,35 +58,6 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
       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,
       { addStates, removeStates }
@@ -196,40 +74,6 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
       }
     }
 
-    /**
-     * 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'
-     *
-     * // 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 as any).databaseById(stateClass);
       return this.states().find((state) => {
@@ -240,54 +84,6 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
       });
     }
 
-    /**
-     * 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 {
-     *   // 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);
-     * }
-     * 
-     * // 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
-     *   }
-     * });
-     * ```
-     */
     addState(stateClass: StateClass | string, chance = 1): object | null {
       const state = this.getState(stateClass);
       if (isString(stateClass)) {
@@ -306,52 +102,6 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
       return null;
     }
 
-    /**
-     * 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 {
-     *   // 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);
-     *   }
-     * }
-     * 
-     * // 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
-     *   }
-     * });
-     * ```
-     */
     removeState(stateClass: StateClass | string, chance = 1) {
       const index = this.states().findIndex((state) => {
         if (isString(stateClass)) {
@@ -369,12 +119,6 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
       }
     }
 
-    /**
-     * 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)
@@ -384,7 +128,67 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
 }
 
 /**
- * Type helper to extract the interface from the WithStateManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for State Manager functionality
+ * 
+ * Provides state management capabilities including state defense, efficiency modifiers,
+ * and state application/removal. This interface defines the public API of the StateManager mixin.
  */
-export type IStateManager = InstanceType<ReturnType<typeof WithStateManager>>;
+export interface IStateManager {
+  /**
+   * Gets the defensive capabilities against various states from equipped items
+   * 
+   * @returns Array of state defense objects with rate and state properties
+   */
+  statesDefense: { rate: number; state: any }[];
+
+  /**
+   * Manages the player's state efficiency modifiers
+   * 
+   * @returns Signal containing array of state efficiency objects
+   */
+  statesEfficiency: any;
+
+  /**
+   * Apply states to a player from skill or item effects
+   * 
+   * @param player - The target player to apply states to
+   * @param states - Object containing arrays of states to add or remove
+   */
+  applyStates(player: RpgPlayer, states: { addStates?: Array<{ state: any; rate: number }>; removeStates?: Array<{ state: any; rate: number }> }): void;
+
+  /**
+   * Get a state to the player. Returns null if the state is not present
+   * 
+   * @param stateClass - The state class constructor or state ID to search for
+   * @returns The state instance if found, null otherwise
+   */
+  getState(stateClass: StateClass | string): any | null;
+
+  /**
+   * Adds a state to the player
+   * 
+   * @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
+   */
+  addState(stateClass: StateClass | string, chance?: number): object | null;
+
+  /**
+   * Remove a state to the player
+   * 
+   * @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
+   */
+  removeState(stateClass: StateClass | string, chance?: number): void;
+
+  /**
+   * 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: any): any | undefined;
+}

package/src/Player/VariableManager.ts

@@ -27,173 +27,26 @@ 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
-     * // 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());
-     * ```
-     */
     setVariable(key: string, val: any): void {
       this.variables.set(key, val);
     }
 
-    /** 
-     * 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
-     * // 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
-     * 
-     * // 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
-     * // 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
-     * 
-     * 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();
     }
@@ -201,7 +54,57 @@ export function WithVariableManager<TBase extends PlayerCtor>(Base: TBase) {
 }
 
 /**
- * Type helper to extract the interface from the WithVariableManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for Variable Manager functionality
+ * 
+ * Provides variable management capabilities including storing, retrieving, and managing
+ * key-value pairs for player-specific data. This interface defines the public API
+ * of the VariableManager mixin.
  */
-export type IVariableManager = InstanceType<ReturnType<typeof WithVariableManager>>;
+export interface IVariableManager {
+  /** Map storing all player variables */
+  variables: Map<string, any>;
+
+  /**
+   * Assign a variable to the player
+   * 
+   * @param key - The variable identifier
+   * @param val - The value to store
+   */
+  setVariable(key: string, val: any): void;
+
+  /**
+   * Get a variable value
+   * 
+   * @param key - The variable identifier to retrieve
+   * @returns The stored value or undefined if not found
+   */
+  getVariable<U = any>(key: string): U | undefined;
+
+  /**
+   * Remove a variable
+   * 
+   * @param key - The variable identifier to remove
+   * @returns true if a variable existed and has been removed, false otherwise
+   */
+  removeVariable(key: string): boolean;
+
+  /**
+   * Check if a variable exists
+   * 
+   * @param key - The variable identifier to check
+   * @returns true if the variable exists, false otherwise
+   */
+  hasVariable(key: string): boolean;
+
+  /**
+   * Get all variable keys
+   * 
+   * @returns Array of all variable keys
+   */
+  getVariableKeys(): string[];
+
+  /**
+   * Clear all variables
+   */
+  clearVariables(): void;
+}