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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgjs/server",
-  "version": "5.0.0-alpha.5",
+  "version": "5.0.0-alpha.7",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "publishConfig": {
@@ -11,7 +11,7 @@
   "license": "MIT",
   "description": "",
   "dependencies": {
-    "@rpgjs/common": "5.0.0-alpha.5",
+    "@rpgjs/common": "5.0.0-alpha.7",
     "@rpgjs/database": "^4.3.0",
     "@signe/di": "^2.3.2",
     "@signe/reactive": "^2.3.2",

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>>;

package/src/Player/ComponentManager.ts

@@ -1,29 +1,71 @@
-import { type Constructor } from "@rpgjs/common";
+import { Constructor, PlayerCtor } from "@rpgjs/common";
 import { RpgCommonPlayer } from "@rpgjs/common";
 
 /**
- * Interface defining what ComponentManager adds to a class
+ * Component Manager Mixin
+ * 
+ * Provides graphic management capabilities to any class. This mixin allows
+ * setting single or multiple graphics for player representation, enabling
+ * dynamic visual changes and animation sequences.
+ * 
+ * @param Base - The base class to extend with component management
+ * @returns Extended class with component management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithComponentManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     this.setGraphic("hero");
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * player.setGraphic(["hero_idle", "hero_walk"]);
+ * ```
  */
-export interface IComponentManager {
-  setGraphic(graphic: string | string[]): void;
+export function WithComponentManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
+    /**
+     * Set the graphic(s) for this player
+     *
+     * Allows setting either a single graphic or multiple graphics for the player.
+     * When multiple graphics are provided, they are used for animation sequences.
+     * The graphics system provides flexible visual representation that can be
+     * dynamically changed during gameplay for different states, equipment, or animations.
+     *
+     * @param graphic - Single graphic name or array of graphic names for animation sequences
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * // Set a single graphic for static representation
+     * player.setGraphic("hero");
+     *
+     * // Set multiple graphics for animation sequences
+     * player.setGraphic(["hero_idle", "hero_walk", "hero_run"]);
+     * 
+     * // Dynamic graphic changes based on equipment
+     * if (player.hasArmor('platemail')) {
+     *   player.setGraphic("hero_armored");
+     * }
+     * 
+     * // Animation sequences for different actions
+     * player.setGraphic(["mage_cast_1", "mage_cast_2", "mage_cast_3"]);
+     * ```
+     */
+         setGraphic(graphic: string | string[]): void {
+       if (Array.isArray(graphic)) {
+         this.graphics.set(graphic);
+       } else {
+         this.graphics.set([graphic]);
+       }
+     }
+  } as unknown as TBase;
 }
 
 /**
- * Component Manager mixin
- * 
- * Adds methods to manage player graphics
- * 
- * @param Base - The base class to extend
- * @returns A new class with component management capabilities
+ * Type helper to extract the interface from the WithComponentManager mixin
+ * This provides the type without duplicating method signatures
  */
-export function WithComponentManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase) {
-  return class extends Base implements IComponentManager {
-    setGraphic(graphic: string | string[]) {
-      if (Array.isArray(graphic)) {
-        this.graphics.set(graphic);
-      } else {
-        this.graphics.set([graphic]);
-      }
-    }
-  };
-}
+export type IComponentManager = InstanceType<ReturnType<typeof WithComponentManager>>;

package/src/Player/EffectManager.ts

@@ -2,13 +2,10 @@ import {
   arrayFlat,
   arrayUniq,
   Constructor,
+  PlayerCtor,
   RpgCommonPlayer,
 } from "@rpgjs/common";
 
-export interface IWithEffectManager {
-  effects: any[];
-}
-
 export enum Effect {
   CAN_NOT_SKILL = 'CAN_NOT_SKILL',
   CAN_NOT_ITEM = 'CAN_NOT_ITEM',
@@ -19,23 +16,64 @@ export enum Effect {
   SUPER_GUARD = 'SUPER_GUARD'
 }
 
-export function WithEffectManager<TBase extends Constructor<RpgCommonPlayer>>(
-  Base: TBase
-) {
-  return class extends Base implements IWithEffectManager {
+/**
+ * Effect Manager Mixin
+ * 
+ * Provides effect management capabilities to any class. This mixin handles
+ * player effects including restrictions, buffs, and debuffs. Effects can come
+ * from various sources like states, equipment, and temporary conditions.
+ * 
+ * @param Base - The base class to extend with effect management
+ * @returns Extended class with effect management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithEffectManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Effect system is automatically initialized
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * player.effects = [Effect.GUARD];
+ * console.log(player.hasEffect(Effect.GUARD)); // true
+ * ```
+ */
+export function WithEffectManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
     /**
+     * Check if the player has a specific effect
+     * 
+     * Determines whether the player currently has the specified effect active.
+     * This includes effects from states, equipment, and temporary conditions.
+     * The effect system provides a flexible way to apply various gameplay
+     * restrictions and enhancements to the player.
+     * 
+     * @param effect - The effect identifier to check for
+     * @returns true if the player has the effect, false otherwise
+     * 
+     * @example
      * ```ts
      * import { Effect } from '@rpgjs/database'
      *
-     * const bool = player.hasEffect(Effect.CAN_NOT_SKILL)
+     * // Check for skill restriction
+     * const cannotUseSkills = player.hasEffect(Effect.CAN_NOT_SKILL);
+     * if (cannotUseSkills) {
+     *   console.log('Player cannot use skills right now');
+     * }
+     * 
+     * // Check for guard effect
+     * const isGuarding = player.hasEffect(Effect.GUARD);
+     * if (isGuarding) {
+     *   console.log('Player is in guard stance');
+     * }
+     * 
+     * // Check for cost reduction
+     * const halfCost = player.hasEffect(Effect.HALF_SP_COST);
+     * const actualCost = skillCost / (halfCost ? 2 : 1);
      * ```
-     *
-     * @title Has Effect
-     * @method player.hasEffect(effect)
-     * @param {string} effect
-     * @returns {boolean}
-     * @memberof EffectManager
-     * */
+     */
     hasEffect(effect: string): boolean {
       return this.effects.includes(effect);
     }
@@ -43,13 +81,31 @@ export function WithEffectManager<TBase extends Constructor<RpgCommonPlayer>>(
     /**
      * Retrieves a array of effects assigned to the player, state effects and effects of weapons and armors equipped with the player's own weapons.
      *
+     * Gets all currently active effects on the player from multiple sources:
+     * - Direct effects assigned to the player
+     * - Effects from active states (buffs/debuffs)
+     * - Effects from equipped weapons and armor
+     * The returned array contains unique effects without duplicates.
+     * 
+     * @returns Array of all active effects on the player
+     * 
+     * @example
      * ```ts
-     * console.log(player.effects)
+     * // Get all active effects
+     * console.log(player.effects); // ['GUARD', 'HALF_SP_COST', ...]
+     * 
+     * // Check multiple effects
+     * const effects = player.effects;
+     * const hasRestrictions = effects.some(effect => 
+     *   effect.startsWith('CAN_NOT_')
+     * );
+     * 
+     * // Count beneficial effects
+     * const beneficialEffects = effects.filter(effect => 
+     *   ['GUARD', 'SUPER_GUARD', 'HALF_SP_COST'].includes(effect)
+     * );
      * ```
-     * @title Get Effects
-     * @prop {Array<Effect>} player.effects
-     * @memberof EffectManager
-     * */
+     */
     get effects(): any[] {
       const getEffects = (prop) => {
         return arrayFlat(this[prop]().map((el) => el.effects || []));
@@ -64,17 +120,44 @@ export function WithEffectManager<TBase extends Constructor<RpgCommonPlayer>>(
     /**
      * Assigns effects to the player. If you give a array, it does not change the effects of the player's states and armor/weapons equipped.
      *
+     * Sets the direct effects on the player. This only affects the player's own effects
+     * and does not modify effects from states or equipment. The total effects will be
+     * the combination of these direct effects plus any effects from states and equipment.
+     * 
+     * @param val - Array of effect identifiers to assign to the player
+     * 
+     * @example
      * ```ts
      * import { Effect } from '@rpgjs/database'
      *
-     * player.effects = [Effect.CAN_NOT_SKILL]
+     * // Set direct player effects
+     * player.effects = [Effect.CAN_NOT_SKILL];
+     * 
+     * // Add multiple effects
+     * player.effects = [
+     *   Effect.GUARD,
+     *   Effect.HALF_SP_COST,
+     *   Effect.CAN_NOT_ITEM
+     * ];
+     * 
+     * // Clear direct effects (equipment/state effects remain)
+     * player.effects = [];
+     * 
+     * // Temporary effect application
+     * const originalEffects = player.effects;
+     * player.effects = [...originalEffects, Effect.SUPER_GUARD];
+     * // Later restore
+     * player.effects = originalEffects;
      * ```
-     * @title Set Effects
-     * @prop {Array<Effect>} player.effects
-     * @memberof EffectManager
-     * */
+     */
     set effects(val) {
       this._effects.set(val);
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * Type helper to extract the interface from the WithEffectManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IEffectManager = InstanceType<ReturnType<typeof WithEffectManager>>;