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

package/src/Player/BattleManager.ts

@@ -1,4 +1,4 @@
-import { Constructor, RpgCommonPlayer } from "@rpgjs/common";
+import { Constructor, PlayerCtor, RpgCommonPlayer } from "@rpgjs/common";
 import { RpgPlayer } from "./Player";
 import { ATK, PDEF, SDEF } from "../presets";
 import { Effect } from "./EffectManager";
@@ -9,41 +9,68 @@ interface PlayerWithMixins extends RpgCommonPlayer {
   hasEffect(effect: string): boolean;
   coefficientElements(attackerPlayer: RpgPlayer): number;
   hp: number;
-  getFormulas(name: string): any;
-  hasEffect(effect: string): boolean; 
-}
-
-export interface IBattleManager {
-  applyDamage(attackerPlayer: RpgPlayer, skill?: any): {
-    damage: number;
-    critical: boolean;
-    elementVulnerable: boolean;
-    guard: boolean;
-    superGuard: boolean;
-  };
+  getCurrentMap(): any;
 }
 
-export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
-  Base: TBase
-): Constructor<IBattleManager> & TBase {
-  return class extends Base implements IBattleManager {
+/**
+ * Battle Manager Mixin
+ * 
+ * Provides battle management capabilities to any class. This mixin handles
+ * damage calculation, critical hits, elemental vulnerabilities, and guard effects.
+ * It implements a comprehensive battle system with customizable formulas and effects.
+ * 
+ * @param Base - The base class to extend with battle management
+ * @returns Extended class with battle management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithBattleManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Battle system is automatically initialized
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * const attacker = new MyPlayer();
+ * const result = player.applyDamage(attacker);
+ * console.log(`Damage dealt: ${result.damage}`);
+ * ```
+ */
+export function WithBattleManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
     /**
      * Apply damage. Player will lose HP. the `attackerPlayer` parameter is the other player, the one who attacks.
      *
      * If you don't set the skill parameter, it will be a physical attack.
-     * The attack formula is already defined but you can customize it in the server options
+     * The attack formula is already defined but you can customize it in the server options.
+     * This method handles all aspects of damage calculation including critical hits,
+     * elemental vulnerabilities, guard effects, and applies the final damage to HP.
      *
+     * @param attackerPlayer - The attacking player who deals the damage
+     * @param skill - Optional skill object for magical attacks, if not provided uses physical attack
+     * @returns Object containing damage details and special effects that occurred
+     * 
+     * @example
      * ```ts
-     * player.applyDamage(attackerPlayer) // returns { damage: number }
+     * // Physical attack
+     * const result = player.applyDamage(attackerPlayer);
+     * console.log(`Physical damage: ${result.damage}, Critical: ${result.critical}`);
+     * 
+     * // Magical attack with skill
+     * const fireSkill = { id: 'fire', power: 50, element: 'fire' };
+     * const magicResult = player.applyDamage(attackerPlayer, fireSkill);
+     * console.log(`Magic damage: ${magicResult.damage}, Vulnerable: ${magicResult.elementVulnerable}`);
+     * 
+     * // Check for guard effects
+     * if (result.guard) {
+     *   console.log('Attack was partially blocked!');
+     * }
+     * if (result.superGuard) {
+     *   console.log('Attack was heavily reduced by super guard!');
+     * }
      * ```
-     *
-     * @title Apply Damage
-     * @method player.applyDamage(attackerPlayer,skill)
-     * @param {RpgPlayer} attackerPlayer The attacking player
-     * @param {any} [skill]
-     * @returns {object}
-     * @memberof BattleManager
-     * */
+     */
     applyDamage(
       attackerPlayer: RpgPlayer,
       skill?: any
@@ -56,13 +83,13 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
     } {
       const getParam = (player: RpgPlayer) => {
         const params = {};
-        this.parameters.forEach((val, key) => {
-          params[key] = player.param[key];
+        (this as any).parameters.forEach((val, key) => {
+          params[key] = (player as any).param[key];
         });
         return {
-          [ATK]: player.atk,
-          [PDEF]: player.pdef,
-          [SDEF]: player.sdef,
+          [ATK]: (player as any).atk,
+          [PDEF]: (player as any).pdef,
+          [SDEF]: (player as any).sdef,
           ...params,
         };
       };
@@ -87,7 +114,7 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
           throw new Error("Physic Formulas not exists");
         }
         damage = fn(paramA, paramB);
-        const coef = this.coefficientElements(attackerPlayer);
+        const coef = (this as any).coefficientElements(attackerPlayer);
         if (coef >= 2) {
           elementVulnerable = true;
         }
@@ -101,7 +128,7 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
           damage = newDamage;
         }
       }
-      if (this.hasEffect(Effect.GUARD)) {
+      if ((this as any).hasEffect(Effect.GUARD)) {
         fn = this.getFormulas("damageGuard");
         if (fn) {
           let newDamage = fn(damage, paramA, paramB);
@@ -111,11 +138,11 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
           damage = newDamage;
         }
       }
-      if (this.hasEffect(Effect.SUPER_GUARD)) {
+      if ((this as any).hasEffect(Effect.SUPER_GUARD)) {
         damage /= 4;
         superGuard = true;
       }
-      this.hp -= damage;
+      (this as any).hp -= damage;
       return {
         damage,
         critical,
@@ -125,9 +152,41 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
       };
     }
 
+    /**
+     * Get damage formulas from the current map
+     * 
+     * Retrieves the damage calculation formulas defined in the current map's configuration.
+     * These formulas are used to calculate different types of damage including physical,
+     * magical, critical hits, and guard effects. The formulas provide flexibility in
+     * customizing the battle system's damage calculations.
+     * 
+     * @param name - The name of the formula to retrieve (e.g., 'damagePhysic', 'damageSkill')
+     * @returns The formula function or undefined if not found
+     * 
+     * @example
+     * ```ts
+     * // Get physical damage formula
+     * const physicFormula = player.getFormulas('damagePhysic');
+     * if (physicFormula) {
+     *   const damage = physicFormula(attackerParams, defenderParams);
+     * }
+     * 
+     * // Get critical damage formula
+     * const criticalFormula = player.getFormulas('damageCritical');
+     * if (criticalFormula) {
+     *   const criticalDamage = criticalFormula(baseDamage, attackerParams, defenderParams);
+     * }
+     * ```
+     */
     getFormulas(name: string) {
-      const map = this.getCurrentMap(); 
+      const map = (this as any).getCurrentMap(); 
       return map.damageFormulas[name];
     }
-  };
+  } as unknown as TBase
 }
+
+/**
+ * Type helper to extract the interface from the WithBattleManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IBattleManager = InstanceType<ReturnType<typeof WithBattleManager>>;

package/src/Player/ClassManager.ts

@@ -1,4 +1,4 @@
-import { Constructor, isString, RpgCommonPlayer } from "@rpgjs/common";
+import { Constructor, isString, PlayerCtor, RpgCommonPlayer } from "@rpgjs/common";
 
 type ClassClass = any;
 type ActorClass = any;
@@ -10,69 +10,129 @@ interface PlayerWithMixins extends RpgCommonPlayer {
   equip(item: any, equip: boolean): void;
 }
 
-export interface IClassManager {
-  setClass(_class: ClassClass | string): ClassClass;
-  setActor(actorClass: ActorClass | string): ActorClass;
-}
-
-export function WithClassManager<TBase extends Constructor<PlayerWithMixins>>(
-  Base: TBase
-): Constructor<IClassManager> & TBase {
-  return class extends Base implements IClassManager {
+/**
+ * Class Manager Mixin
+ * 
+ * Provides class and actor management capabilities to any class. This mixin handles
+ * character class assignment and actor setup, including automatic parameter configuration,
+ * starting equipment, and skill progression based on class definitions.
+ * 
+ * @param Base - The base class to extend with class management
+ * @returns Extended class with class management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithClassManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Class system is automatically initialized
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * player.setClass(Fighter);
+ * player.setActor(Hero);
+ * ```
+ */
+export function WithClassManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
 
     /**
      * Assign a class to the player
      *
+     * Sets the player's class, which defines their combat abilities, stat growth,
+     * and available skills. The class system provides the foundation for character
+     * progression and specialization. When a class is set, it automatically triggers
+     * the class's onSet method for any additional initialization.
+     * 
+     * @param _class - The class constructor or class ID to assign to the player
+     * @returns The instantiated class object
+     * 
+     * @example
      * ```ts
      * import { Fighter } from 'my-database/classes/fighter'
      *
-     * player.setClass(Fighter)
+     * // Set class using constructor
+     * const fighterClass = player.setClass(Fighter);
+     * console.log('Class set:', fighterClass.name);
+     * 
+     * // Set class using string ID
+     * player.setClass('fighter');
+     * 
+     * // Class affects available skills and stats
+     * console.log('Available skills:', player.skills);
+     * console.log('Class bonuses applied to stats');
+     * 
+     * // Class determines level progression
+     * player.level = 5;
+     * // Skills may be automatically learned based on class definition
      * ```
-     *
-     * @title Set Class
-     * @method player.setClass(ClassClass)
-     * @param {ClassClass | string} class class or id
-     * @returns {instance of ClassClass}
-     * @memberof ClassManager
-     * */
+     */
     setClass(_class: ClassClass | string) {
-      if (isString(_class)) _class = this.databaseById(_class);
+      if (isString(_class)) _class = (this as any).databaseById(_class);
       const classInstance = new (_class as ClassClass)();
-      this["execMethod"]("onSet", [this], classInstance);
+      (this as any)["execMethod"]("onSet", [this], classInstance);
       return classInstance;
     }
 
     /**
      * Allows to give a set of already defined properties to the player (default equipment, or a list of skills to learn according to the level)
      *
+     * Sets up the player as a specific actor archetype, which includes predefined
+     * characteristics like starting equipment, parameters, level ranges, and associated class.
+     * This is typically used for creating pre-configured character templates or NPCs
+     * with specific roles and equipment loadouts.
+     * 
+     * @param actorClass - The actor constructor or actor ID to assign to the player
+     * @returns The instantiated actor object
+     * 
+     * @example
      * ```ts
      * import { Hero } from 'my-database/classes/hero'
      *
-     * player.setActor(Hero)
+     * // Set up player as Hero actor
+     * const heroActor = player.setActor(Hero);
+     * console.log('Actor configured:', heroActor.name);
+     * 
+     * // Actor automatically sets up:
+     * // - Starting equipment (sword, armor, etc.)
+     * console.log('Starting equipment:', player.equipments());
+     * 
+     * // - Parameter ranges and growth
+     * console.log('Level range:', player.initialLevel, '-', player.finalLevel);
+     * 
+     * // - Associated class
+     * console.log('Assigned class:', player.class);
+     * 
+     * // - Experience curve
+     * console.log('EXP curve:', player.expCurve);
+     * 
+     * // Actor setup is comprehensive
+     * player.setActor('hero'); // Can also use string ID
      * ```
-     *
-     * @title Set Actor
-     * @method player.setActor(ActorClass)
-     * @param {ActorClass | string} actorClass actor class or id
-     * @returns {instance of ActorClass}
-     * @memberof ClassManager
-     * */
+     */
     setActor(actorClass: ActorClass | string) {
-      if (isString(actorClass)) actorClass = this.databaseById(actorClass);
+      if (isString(actorClass)) actorClass = (this as any).databaseById(actorClass);
       const actor = new (actorClass as ActorClass)();
       ["name", "initialLevel", "finalLevel", "expCurve"].forEach((key) => {
-        if (actor[key]) this[key] = actor[key];
+        if (actor[key]) (this as any)[key] = actor[key];
       });
       for (let param in actor.parameters) {
-        this.addParameter(param, actor.parameters[param]);
+        (this as any).addParameter(param, actor.parameters[param]);
       }
       for (let item of actor.startingEquipment) {
-        this.addItem(item);
-        this.equip(item, true);
+        (this as any).addItem(item);
+        (this as any).equip(item, true);
       }
       if (actor.class) this.setClass(actor.class);
-      this["execMethod"]("onSet", [this], actor);
+      (this as any)["execMethod"]("onSet", [this], actor);
       return actor;
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * Type helper to extract the interface from the WithClassManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IClassManager = InstanceType<ReturnType<typeof WithClassManager>>;