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

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,111 +13,112 @@ 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[]>([]);
 
+    private _getStateMap(required: boolean = true) {
+      // Use this.map directly to support both RpgMap and LobbyRoom
+      const map = (this as any).getCurrentMap?.() || (this as any).map;
+      if (required && (!map || !map.database)) {
+        throw new Error('Player must be on a map to resolve states');
+      }
+      return map;
+    }
+
+    private _resolveStateInput(
+      stateInput: StateClass | string,
+      databaseByIdOverride?: (id: string) => any
+    ) {
+      if (isString(stateInput)) {
+        return databaseByIdOverride
+          ? databaseByIdOverride(stateInput)
+          : (this as any).databaseById(stateInput);
+      }
+      return stateInput;
+    }
+
+    private _createStateInstance(stateClass: StateClass) {
+      return new (stateClass as StateClass)();
+    }
+
     /**
-     * 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.
-     *
-     * ```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 }]
-     * ```
-     * @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");
+     * Create a state instance without side effects.
+     */
+    createStateInstance(stateInput: StateClass | string) {
+      const stateClass = this._resolveStateInput(stateInput);
+      const instance = this._createStateInstance(stateClass as StateClass);
+      return { stateClass, instance };
     }
 
     /**
-     * Set or retrieves all the states where the player is vulnerable or not.
-     *
-     * ```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 }]
-     * ```
-     * @title Set/Get States Efficiency
-     * @prop {Array<{ rate: number, state: StateClass}>} player.statesEfficiency
-     * @memberof StateManager
-     * */
+     * Resolve state snapshot entries into state instances without side effects.
+     */
+    resolveStatesSnapshot(snapshot: { states?: any[] }, mapOverride?: any) {
+      if (!snapshot || !Array.isArray(snapshot.states)) {
+        return snapshot;
+      }
+
+      const map = mapOverride ?? this._getStateMap(false);
+      if (!map || !map.database) {
+        return snapshot;
+      }
+
+      const databaseByIdOverride = (id: string) => {
+        const data = map.database()[id];
+        if (!data) {
+          throw new Error(
+            `The ID=${id} data is not found in the database. Add the data in the property "database"`
+          );
+        }
+        return data;
+      };
+
+      const states = snapshot.states.map((entry: any) => {
+        const stateId = isString(entry) ? entry : entry?.id;
+        if (!stateId) {
+          return entry;
+        }
+        const stateClass = this._resolveStateInput(stateId, databaseByIdOverride);
+        return this._createStateInstance(stateClass as StateClass);
+      });
+
+      return { ...snapshot, states };
+    }
+
+    get statesDefense(): { rate: number; state: any }[] {
+      return (this as any).getFeature("statesDefense", "state");
+    }
+
     get statesEfficiency() {
       return this._statesEfficiency;
     }
@@ -127,37 +128,23 @@ export function WithStateManager<
     }
 
     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
-     * ```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
-     */
     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;
@@ -166,46 +153,17 @@ export function WithStateManager<
       });
     }
 
-    /**
-     * Adds a state to the player. Set the chance between 0 and 1 that the state can apply
-     * ```ts
-     * import Paralyze from 'your-database/states/paralyze'
-     *
-     * try {
-     *      player.addState(Paralyze)
-     * }
-     * 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: '...'
-     * }
-     * ```
-     * @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) {
           throw StateLog.addFailed(stateClass);
         }
         //const efficiency = this.findStateEfficiency(stateClass)
-        const instance = new (stateClass as StateClass)();
+        const instance = this._createStateInstance(stateClass as StateClass);
         this.states().push(instance);
         this.applyStates(<any>this, instance);
         return instance;
@@ -213,42 +171,6 @@ export function WithStateManager<
       return null;
     }
 
-    /**
-     * Remove a state to the player. Set the chance between 0 and 1 that the state can be removed
-     * ```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: '...'
-     * }
-     * ```
-     * @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) => {
         if (isString(stateClass)) {
@@ -266,10 +188,76 @@ export function WithStateManager<
       }
     }
 
-    private findStateEfficiency(stateClass) {
+    findStateEfficiency(stateClass) {
       return this.statesEfficiency().find((state) =>
         isInstanceOf(state.state, stateClass)
       );
     }
-  };
+  } as unknown as TBase;
+}
+
+/**
+ * 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 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

@@ -1,75 +1,113 @@
-import { type Constructor } from "@rpgjs/common";
-import { RpgCommonPlayer } from "@rpgjs/common";
+import { Constructor, PlayerCtor } from "@rpgjs/common";
+import { signal } from "@signe/reactive";
+import { type } from "@signe/sync";
 
 /**
- * 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 = type(signal<Record<string, any>>({}) as any, 'variables', { persist: true }, this as any);
+
+    setVariable(key: string, val: any): void {
+      this.variables()[key] = val;
+    }
+
+    getVariable<U = any>(key: string): U | undefined {
+      return this.variables()[key];
+    }
+
+    removeVariable(key: string): boolean {
+      delete this.variables()[key];
+      return true;
+    }
 
-    /** 
-     * Assign a variable to the player
-     * 
-     * ```ts
-     * player.setVariable('OPEN_CHEST', true)
-     * ```
-     * 
-     * @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)
+    hasVariable(key: string): boolean {
+      return key in this.variables();
     }
 
-    /** 
-     * Get a variable
-     * 
-     * ```ts
-     * const val = player.getVariable('OPEN_CHEST')
-     * ```
-     * 
-     * @title Get variable
-     * @method player.setVariable(key,val)
-     * @param {string} key
-     * @returns {any} 
-     * @memberof VariableManager
-     * */
-    getVariable(key: string) {
-        return this.variables.get(key)
+    getVariableKeys(): string[] {
+      return Object.keys(this.variables());
     }
 
-    /** 
-     * Remove a variable
-     * 
-     * ```ts
-     * player.removeVariable('OPEN_CHEST')
-     * ```
-     * 
-     * @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)
+    clearVariables(): void {
+      this.variables.set({});
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * 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 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;
+}