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

package/src/Player/StateManager.ts

@@ -1,4 +1,4 @@
-import { isInstanceOf, isString, PlayerCtor, type Constructor } from "@rpgjs/common";
+import { isInstanceOf, isString, 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,51 +13,41 @@ 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[]) };
 
 /**
- * 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));
- * ```
+ * Move Manager mixin
+ *
+ * Adds methods to manage player movement
+ *
+ * @param Base - The base class to extend
+ * @returns A new class with move management capabilities
  */
-export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
-  return class extends Base {
+export function WithStateManager<
+  TBase extends Constructor<RpgCommonPlayer & StateManagerDependencies>
+>(Base: TBase): Constructor<IStateManager> & TBase {
+  return class extends Base implements IStateManager {
     _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'
      *
@@ -84,29 +74,19 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
      * 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 as any).getFeature("statesDefense", "state");
+      return this.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'
      *
@@ -133,16 +113,11 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
      * 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;
     }
@@ -151,87 +126,38 @@ 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,
+      player: RpgPlayer & IStateManager,
       { addStates, removeStates }
     ) {
       if (addStates) {
         for (let { state, rate } of addStates) {
-          (player as any).addState(state, rate);
+          player.addState(state, rate);
         }
       }
       if (removeStates) {
         for (let { state, rate } of removeStates) {
-          (player as any).removeState(state, rate);
+          player.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'
      *
-     * // 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
-     * }
-     * ```
+     * player.getState(Paralyze)
+     *  ```
+     *
+     * @title Get State
+     * @method player.getState(stateClass)
+     * @param {StateClass | string} stateClass or state id
+     * @returns {instance of StateClass | null}
+     * @memberof StateManager
      */
     getState(stateClass: StateClass | string) {
-      if (isString(stateClass)) stateClass = (this as any).databaseById(stateClass);
+      if (isString(stateClass)) stateClass = this.databaseById(stateClass);
       return this.states().find((state) => {
         if (isString(stateClass)) {
           return state.id == stateClass;
@@ -242,56 +168,37 @@ 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);
+     *      player.addState(Paralyze)
      * }
-     * 
-     * // Apply with reduced chance
-     * try {
-     *   player.addState(Poison, 0.3); // 30% chance
-     * } catch (err) {
-     *   console.log('Poison application failed');
+     * 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 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 as any).databaseById(stateClass);
+        stateClass = this.databaseById(stateClass);
       }
       if (!state) {
         if (Math.random() > chance) {
@@ -308,49 +215,39 @@ export function WithStateManager<TBase extends PlayerCtor>(Base: TBase) {
 
     /**
      * 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);
-     *   }
+     *      player.removeState(Paralyze)
      * }
-     * 
-     * // Remove with reduced chance (for weak cure spells)
-     * try {
-     *   player.removeState(Poison, 0.7); // 70% chance
-     * } catch (err) {
-     *   console.log('Cure failed');
+     * 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: '...'
      * }
-     * 
-     * // 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
-     *   }
-     * });
      * ```
+     * @throws {StateLog} notApplied
+     * If the status does not exist
+     *  ```
+     * {
+     *      id: STATE_NOT_APPLIED,
+     *      msg: '...'
+     * }
+     * ```
+     * @returns {instance of StateClass}
+     * @memberof StateManager
      */
     removeState(stateClass: StateClass | string, chance = 1) {
       const index = this.states().findIndex((state) => {
@@ -369,22 +266,10 @@ 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) {
+    private 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,207 +1,75 @@
-import { Constructor, PlayerCtor } from "@rpgjs/common";
+import { type Constructor } from "@rpgjs/common";
+import { RpgCommonPlayer } from "@rpgjs/common";
 
 /**
- * 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
+ * Interface defining what MoveManager adds to a class
+ */
+export interface IWithVariableManager {
+  variables: Map<string, any>
+}
+
+/**
+ * Move Manager mixin
  * 
- * @example
- * ```ts
- * class MyPlayer extends WithVariableManager(BasePlayer) {
- *   constructor() {
- *     super();
- *     // Variables are automatically initialized
- *   }
- * }
+ * Adds methods to manage player movement
  * 
- * const player = new MyPlayer();
- * player.setVariable('questCompleted', true);
- * ```
+ * @param Base - The base class to extend
+ * @returns A new class with move management capabilities
  */
-export function WithVariableManager<TBase extends PlayerCtor>(Base: TBase) {
-  return class extends Base {
-    variables: Map<string, any> = new Map();
+export function WithVariableManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase) {
+  return class extends Base implements IWithVariableManager {
+    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());
+     * player.setVariable('OPEN_CHEST', true)
      * ```
-     */
-    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);
+     * @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)
     }
 
     /** 
-     * Remove a variable
+     * Get 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');
-     * }
+     * const val = player.getVariable('OPEN_CHEST')
      * ```
-     */
-    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);
+     * @title Get variable
+     * @method player.setVariable(key,val)
+     * @param {string} key
+     * @returns {any} 
+     * @memberof VariableManager
+     * */
+    getVariable(key: string) {
+        return this.variables.get(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
+    /** 
+     * Remove a variable
      * 
-     * @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_'));
+     * player.removeVariable('OPEN_CHEST')
      * ```
-     */
-    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();
+     * @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)
     }
-  } 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>>;