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

package/src/Player/ElementManager.ts

@@ -1,86 +1,45 @@
-import { arrayUniq, RpgCommonPlayer } from "@rpgjs/common";
+import { arrayUniq, PlayerCtor, RpgCommonPlayer } from "@rpgjs/common";
 import { Constructor } from "@rpgjs/common";
 import { RpgPlayer } from "./Player";
 
-export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
-  Base: TBase
-) {
-  return class extends Base implements IWithElementManager {
+/**
+ * Element Manager Mixin
+ * 
+ * Provides elemental management capabilities to any class. This mixin handles
+ * elemental resistances, vulnerabilities, and attack elements. It manages both
+ * defensive capabilities (elementsDefense) and offensive elements from equipment,
+ * as well as player-specific elemental efficiency modifiers.
+ * 
+ * @param Base - The base class to extend with element management
+ * @returns Extended class with element management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithElementManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     this.elementsEfficiency = [{ rate: 0.5, element: 'fire' }];
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * const fireResistance = player.elementsDefense.find(e => e.element === 'fire');
+ * ```
+ */
+export function WithElementManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
     _elementsEfficiency: { rate: number; element: any }[] = [];
 
-    /**
-     * Recovers the player's elements defense on inventory.  This list is generated from the `elementsDefense` 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 } from '@rpgjs/server'
-     *
-     * enum Elements {
-     *   Fire = 'fire'
-     * }
-     *
-     * @Armor({
-     *      name: 'Shield',
-     *      elementsDefense: [{ rate: 1, element: Elements.Fire }]
-     * })
-     * class Shield {}
-     *
-     * @Armor({
-     *      name: 'FireShield',
-     *      elementsDefense: [{ rate: 0.5, element: Elements.Fire }]
-     * })
-     * class FireShield {}
-     *
-     * player.addItem(Shield)
-     * player.addItem(FireShield)
-     * player.equip(Shield)
-     * player.equip(FireShield)
-     *
-     * console.log(player.elementsDefense) // [{ rate: 1, element: 'fire' }]
-     * ```
-     * @title Get Elements Defense
-     * @prop {Array<{ rate: number, element: Element}>} player.elementsDefense
-     * @readonly
-     * @memberof ElementManager
-     * */
     get elementsDefense(): { rate: number; element: any }[] {
-      return this.getFeature("elementsDefense", "element");
+      return (this as any).getFeature("elementsDefense", "element");
     }
 
-    /**
-     * Set or retrieves all the elements where the player is vulnerable or not.
-     *
-     * ```ts
-     * import { Class } from '@rpgjs/server'
-     *
-     * enum Elements {
-     *   Fire = 'fire',
-     *   Ice = 'ice'
-     * }
-     *
-     * @Class({
-     *      name: 'Fighter',
-     *      elementsEfficiency: [{ rate: 1, element: Elements.Fire }]
-     * })
-     * class Hero {}
-     *
-     * player.setClass(Hero)
-     *
-     * console.log(player.elementsEfficiency) // [{ rate: 1, element: 'fire' }]
-     *
-     * player.elementsEfficiency = [{ rate: 2, element: Elements.Ice }]
-     *
-     * console.log(player.elementsEfficiency) // [{ rate: 1, element: 'fire' }, { rate: 2, element: 'ice' }]
-     * ```
-     * @title Set/Get Elements Efficiency
-     * @prop {Array<{ rate: number, element: Element}>} player.elementsEfficiency
-     * @memberof ElementManager
-     * */
     get elementsEfficiency(): { rate: number; element: any }[] {
-      if (this._class) {
+      if (this._class()) {
+        const classData = this._class() as any;
         return <any>[
           ...this._elementsEfficiency,
-          ...(this._class()?.elementsEfficiency || []),
+          ...(classData?.elementsEfficiency || []),
         ];
       }
       return this._elementsEfficiency;
@@ -90,17 +49,6 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
       this._elementsEfficiency = val;
     }
 
-    /**
-     * Retrieves a array of elements assigned to the player and the elements of the weapons / armor equipped
-     *
-     * ```ts
-     * console.log(player.elements)
-     * ```
-     * @title Get Elements
-     * @prop {Array<Element>} player.elements
-     * @readonly
-     * @memberof ElementManager
-     * */
     get elements(): {
       rate: number;
       element: string;
@@ -115,7 +63,7 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
     }
 
     coefficientElements(otherPlayer: RpgPlayer): number {
-      const atkPlayerElements: any = otherPlayer.elements;
+      const atkPlayerElements: any = (otherPlayer as any).elements;
       const playerElements: any = this.elementsEfficiency;
       let coefficient = 1;
 
@@ -127,7 +75,7 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
           (el) => el.element == atkElement.element
         );
         if (!elementPlayer) continue;
-        const fn = this.getFormulas("coefficientElements");
+        const fn = (this as any).getFormulas("coefficientElements");
         if (!fn) {
           return coefficient;
         }
@@ -139,5 +87,80 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
       }
       return coefficient;
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * Interface for Element Manager functionality
+ * 
+ * Provides elemental management capabilities including resistances, vulnerabilities,
+ * and attack elements. This interface defines the public API of the ElementManager mixin.
+ */
+export interface IElementManager {
+  /**
+   * Gets the defensive capabilities against various elements from equipped items.
+   * The system automatically consolidates multiple defensive items, keeping only
+   * the highest protection rate for each element type.
+   * 
+   * @returns Array of element defense objects with rate and element properties
+   */
+  elementsDefense: { rate: number; element: any }[];
+
+  /**
+   * Manages the player's elemental efficiency modifiers, which determine how
+   * effective different elements 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 element efficiency objects with rate and element properties
+   */
+  elementsEfficiency: { rate: number; element: any }[];
+
+  /**
+   * Gets all offensive elements available to the player from equipped weapons and armor.
+   * This determines what elemental damage types the player can deal in combat.
+   * The system automatically combines elements from all equipped items and removes duplicates.
+   * 
+   * @returns Array of element objects with rate and element properties for offensive capabilities
+   */
+  elements: {
+    rate: number;
+    element: string;
+  }[];
+
+  /**
+   * Calculate elemental damage coefficient against another player
+   * 
+   * Determines the damage multiplier when this player attacks another player,
+   * taking into account the attacker's offensive elements, the defender's
+   * elemental efficiency, and elemental defense from equipment. This is used
+   * in the battle system to calculate elemental damage modifiers.
+   * 
+   * @param otherPlayer - The target player to calculate coefficient against
+   * @returns Numerical coefficient to multiply base damage by
+   * 
+   * @example
+   * ```ts
+   * // Calculate elemental damage coefficient
+   * const firePlayer = new MyPlayer();
+   * const icePlayer = new MyPlayer();
+   * 
+   * // Fire player attacks ice player (assuming ice is weak to fire)
+   * const coefficient = icePlayer.coefficientElements(firePlayer);
+   * console.log(`Damage multiplier: ${coefficient}`); // e.g., 2.0 for double damage
+   * 
+   * // Use in damage calculation
+   * const baseDamage = 100;
+   * const finalDamage = baseDamage * coefficient;
+   * console.log(`Final damage: ${finalDamage}`);
+   * 
+   * // Check for elemental advantage
+   * if (coefficient > 1) {
+   *   console.log('Attacker has elemental advantage!');
+   * } else if (coefficient < 1) {
+   *   console.log('Defender resists this element');
+   * }
+   * ```
+   */
+  coefficientElements(otherPlayer: RpgPlayer): number;
+}

package/src/Player/GoldManager.ts

@@ -1,44 +1,41 @@
-import { type Constructor } from "@rpgjs/common";
-import { RpgCommonPlayer } from "@rpgjs/common";
+import { PlayerCtor } from "@rpgjs/common";
 
-/**
- * Interface defining what MoveManager adds to a class
- */
-export interface IGoldManager {
-  
+export interface GoldManager {
+  /**
+   * You can change the game money
+   *
+   * ```ts
+   * player.gold += 100
+   * ```
+   *
+   * @title Change Gold
+   * @prop {number} player.gold
+   * @default 0
+   * @memberof GoldManager
+   * */
+  gold: number;
 }
 
-/**
- * Move Manager mixin
- * 
- * Adds methods to manage player gold
- * 
- * @param Base - The base class to extend
- * @returns A new class with gold management capabilities
- */
-export function WithGoldManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase) {
-  return class extends Base implements IGoldManager {
-    /** 
-     * You can change the game money
-     * 
-     * ```ts
-     * player.gold += 100
-     * ```
-     * 
-     * @title Change Gold
-     * @prop {number} player.gold
-     * @default 0
-     * @memberof GoldManager
-     * */
+export function WithGoldManager<TBase extends PlayerCtor>(
+  Base: TBase
+): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> &
+  GoldManager {
+  return class extends Base {
     set gold(val: number) {
-        if (val < 0) {
-            val = 0
-        }
-        this._gold.set(val)
+      if (val < 0) {
+        val = 0;
+      }
+      this._gold.set(val);
     }
 
     get gold(): number {
-        return this._gold()
+      return this._gold();
     }
-  };
+  } as unknown as any;
 }
+
+/**
+ * Type helper to extract the interface from the WithGoldManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IGoldManager = InstanceType<ReturnType<typeof WithGoldManager>>;