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

package/src/Player/ElementManager.ts

@@ -1,17 +1,47 @@
-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.
      *
+     * 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. This provides a comprehensive
+     * view of the player's elemental resistances from all equipped gear.
+     * 
+     * @returns Array of element defense objects with rate and element properties
+     * 
+     * @example
      * ```ts
      * import { Armor } from '@rpgjs/server'
      *
@@ -37,19 +67,29 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
      * player.equip(FireShield)
      *
      * console.log(player.elementsDefense) // [{ rate: 1, element: 'fire' }]
+     * 
+     * // Check specific element defense
+     * const fireDefense = player.elementsDefense.find(def => def.element === 'fire');
+     * if (fireDefense) {
+     *   console.log(`Fire defense rate: ${fireDefense.rate}`);
+     * }
      * ```
-     * @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.
      *
+     * 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
+     * 
+     * @example
      * ```ts
      * import { Class } from '@rpgjs/server'
      *
@@ -71,13 +111,18 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
      * player.elementsEfficiency = [{ rate: 2, element: Elements.Ice }]
      *
      * console.log(player.elementsEfficiency) // [{ rate: 1, element: 'fire' }, { rate: 2, element: 'ice' }]
+     * 
+     * // Check for vulnerabilities
+     * const vulnerabilities = player.elementsEfficiency.filter(eff => eff.rate > 1);
+     * console.log('Vulnerable to:', vulnerabilities.map(v => v.element));
+     * 
+     * // Check for resistances
+     * const resistances = player.elementsEfficiency.filter(eff => eff.rate < 1);
+     * console.log('Resistant to:', resistances.map(r => r.element));
      * ```
-     * @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()) {
         return <any>[
           ...this._elementsEfficiency,
           ...(this._class()?.elementsEfficiency || []),
@@ -93,14 +138,30 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
     /**
      * Retrieves a array of elements assigned to the player and the elements of the weapons / armor equipped
      *
+     * 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
+     * 
+     * @example
      * ```ts
-     * console.log(player.elements)
+     * // Get all offensive elements
+     * console.log(player.elements); // [{ rate: 1.5, element: 'fire' }, { rate: 1.2, element: 'ice' }]
+     * 
+     * // Check if player can deal fire damage
+     * const hasFireElement = player.elements.some(el => el.element === 'fire');
+     * if (hasFireElement) {
+     *   console.log('Player can deal fire damage');
+     * }
+     * 
+     * // Get strongest element
+     * const strongestElement = player.elements.reduce((max, current) => 
+     *   current.rate > max.rate ? current : max
+     * );
+     * console.log(`Strongest element: ${strongestElement.element} (${strongestElement.rate})`);
      * ```
-     * @title Get Elements
-     * @prop {Array<Element>} player.elements
-     * @readonly
-     * @memberof ElementManager
-     * */
+     */
     get elements(): {
       rate: number;
       element: string;
@@ -114,8 +175,42 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
       return arrayUniq(elements);
     }
 
+    /**
+     * 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 {
-      const atkPlayerElements: any = otherPlayer.elements;
+      const atkPlayerElements: any = (otherPlayer as any).elements;
       const playerElements: any = this.elementsEfficiency;
       let coefficient = 1;
 
@@ -127,7 +222,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 +234,11 @@ export function WithElementManager<TBase extends Constructor<RpgCommonPlayer>>(
       }
       return coefficient;
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * Type helper to extract the interface from the WithElementManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IElementManager = InstanceType<ReturnType<typeof WithElementManager>>;

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

package/src/Player/GuiManager.ts

@@ -1,132 +1,45 @@
 import { RpgPlayer } from "./Player";
 import { Gui, DialogGui, MenuGui, ShopGui, NotificationGui } from "../Gui";
 import { DialogOptions, Choice } from "../Gui/DialogGui";
-import { Constructor, RpgCommonPlayer } from "@rpgjs/common";
+import { Constructor, PlayerCtor } from "@rpgjs/common";
 
-export interface IGuiManager {
-    emit: any;
-    removeGui: (guiId: string, data?: any) => void;
-  }
-
-export function WithGuiManager<TBase extends Constructor<RpgCommonPlayer>>(
+/**
+ * GUI Manager Mixin
+ *
+ * Provides graphical user interface management capabilities to any class. This mixin handles
+ * dialog boxes, menus, notifications, shops, and custom GUI components. It manages the
+ * complete GUI system including opening, closing, and data passing between client and server.
+ *
+ * @param Base - The base class to extend with GUI management
+ * @returns Extended class with GUI management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithGuiManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // GUI system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * await player.showText('Hello World!');
+ * player.callMainMenu();
+ * ```
+ */
+export function WithGuiManager<TBase extends PlayerCtor>(
   Base: TBase
-) {
-  return class extends Base implements IGuiManager {
+): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> &
+  IGuiManager {
+  class GuiManagerMixin extends Base {
     _gui: { [id: string]: Gui } = {};
 
-    /**
-     * Show a text. This is a graphical interface already built. Opens the GUI named `rpg-dialog`
-     *
-     * ```ts
-     * player.showText('Hello World')
-     * ```
-     *
-     * The method returns a promise. It is resolved when the dialog box is closed.
-     *
-     * ```ts
-     * await player.showText('Hello World')
-     * // dialog box is closed, then ...
-     * ```
-     *
-     * **Option: position**
-     *
-     * You can define how the dialog box is displayed:
-     * - top
-     * - middle
-     * - bottom
-     *
-     * (bottom by default)
-     *
-     * ```ts
-     * player.showText('Hello World', {
-     *      position: 'top'
-     * })
-     * ```
-     *
-     * **Option: fullWidth**
-     *
-     * `boolean` (true by default)
-     *
-     * Indicate that the dialog box will take the full width of the screen.
-     *
-     * ```ts
-     * player.showText('Hello World', {
-     *      fullWidth: true
-     * })
-     * ```
-     *
-     * **Option: autoClose**
-     *
-     * `boolean` (false by default)
-     *
-     * If false, the user will have to press Enter to close the dialog box.
-     *
-     *  ```ts
-     * player.showText('Hello World', {
-     *      autoClose: true
-     * })
-     * ```
-     *
-     * **Option: typewriterEffect**
-     *
-     * `boolean` (true by default)
-     *
-     * Performs a typewriter effect
-     *
-     *  ```ts
-     * player.showText('Hello World', {
-     *      typewriterEffect: false
-     * })
-     * ```
-     *
-     * **Option: talkWith**
-     *
-     * `RpgPlayer` (nothing by default)
-     *
-     * If you specify the event or another player, the other player will stop his or her movement and look in the player's direction.
-     *
-     *  ```ts
-     * // Code in an event
-     * player.showText('Hello World', {
-     *      talkWith: this
-     * })
-     * ```
-     *
-     * @title Show Text
-     * @method player.showText(text,options)
-     * @param {string} text
-     * @param {object} [options] the different options, see usage below
-     * @returns {Promise}
-     * @memberof GuiManager
-     */
     showText(msg: string, options: DialogOptions = {}): Promise<any> {
       const gui = new DialogGui(<any>this);
       this._gui[gui.id] = gui;
       return gui.openDialog(msg, options);
     }
 
-    /**
-     * Shows a dialog box with a choice. Opens the GUI named `rpg-dialog`
-     *
-     * ```ts
-     * const choice = await player.showChoices('What color do you prefer?', [
-     *      { text: 'Black', value: 'black' },
-     *      { text: 'Rather the blue', value: 'blue' },
-     *      { text: 'I don\'t have a preference!', value: 'none' }
-     * ])
-     *
-     * // If the player selects the first
-     * console.log(choice) // { text: 'Black', value: 'black' }
-     * ```
-     *
-     * @title Show Choices
-     * @method player.showChoices(text,choices)
-     * @param {string} text
-     * @param {Array<{ text: string, value: any }>} choices
-     * @param {object} [options] Same options as the openDialog method
-     * @returns {Promise<Choice | null>}
-     * @memberof GuiManager
-     */
     showChoices(
       msg: string,
       choices: Choice[],
@@ -141,19 +54,6 @@ export function WithGuiManager<TBase extends Constructor<RpgCommonPlayer>>(
       });
     }
 
-    /**
-     * Displays a notification . Opens the GUI named `rpg-notification`
-     *
-     * @title Displays a notification
-     * @method player.showNotification()
-     * @param {string} message - The message to display in the notification
-     * @param {object} options - An object containing options for the notification
-     * @param {number} options.time - The time to display the notification for (in ms). Default: 2000ms
-     * @param {string} options.icon - The icon to display in the notification. Put the identifier of the spritesheet (defined on the client side)
-     * @param {string} options.sound - The sound to play when the notification is shown. Set the sound ID (defined on the client side)
-     * @returns {void}
-     * @memberof GuiManager
-     */
     showNotification(
       message: string,
       options: { time?: number; icon?: string; sound?: string } = {}
@@ -167,14 +67,6 @@ export function WithGuiManager<TBase extends Constructor<RpgCommonPlayer>>(
       return gui.open(data);
     }
 
-    /**
-     * Calls main menu. Opens the GUI named `rpg-main-menu`
-     *
-     * @title Call Main Menu
-     * @method player.callMainMenu()
-     * @returns {void}
-     * @memberof GuiManager
-     */
     callMainMenu() {
       const gui = new MenuGui(<any>this);
       this._gui[gui.id] = gui;
@@ -253,11 +145,11 @@ export function WithGuiManager<TBase extends Constructor<RpgCommonPlayer>>(
       }
     }
 
-    private _attachedGui(players: RpgPlayer[] | RpgPlayer, display: boolean) {
+    _attachedGui(players: RpgPlayer[] | RpgPlayer, display: boolean) {
       if (!Array.isArray(players)) {
         players = [players] as RpgPlayer[];
       }
-      this.emit("gui.tooltip", {
+      (this as any).emit("gui.tooltip", {
         players: (players as RpgPlayer[]).map((player) => player.id),
         display,
       });
@@ -313,5 +205,160 @@ export function WithGuiManager<TBase extends Constructor<RpgCommonPlayer>>(
       const _players = players || this;
       this._attachedGui(_players as RpgPlayer[], false);
     }
-  };
+  }
+
+  return GuiManagerMixin as unknown as any;
+}
+
+/**
+ * Interface for GUI management capabilities
+ * Defines the methods that will be available on the player
+ */
+export interface IGuiManager {
+  /**
+   * Show a text. This is a graphical interface already built. Opens the GUI named `rpg-dialog`
+   *
+   * ```ts
+   * player.showText('Hello World')
+   * ```
+   *
+   * The method returns a promise. It is resolved when the dialog box is closed.
+   *
+   * ```ts
+   * await player.showText('Hello World')
+   * // dialog box is closed, then ...
+   * ```
+   *
+   * **Option: position**
+   *
+   * You can define how the dialog box is displayed:
+   * - top
+   * - middle
+   * - bottom
+   *
+   * (bottom by default)
+   *
+   * ```ts
+   * player.showText('Hello World', {
+   *      position: 'top'
+   * })
+   * ```
+   *
+   * **Option: fullWidth**
+   *
+   * `boolean` (true by default)
+   *
+   * Indicate that the dialog box will take the full width of the screen.
+   *
+   * ```ts
+   * player.showText('Hello World', {
+   *      fullWidth: true
+   * })
+   * ```
+   *
+   * **Option: autoClose**
+   *
+   * `boolean` (false by default)
+   *
+   * If false, the user will have to press Enter to close the dialog box.
+   *
+   *  ```ts
+   * player.showText('Hello World', {
+   *      autoClose: true
+   * })
+   * ```
+   *
+   * **Option: typewriterEffect**
+   *
+   * `boolean` (true by default)
+   *
+   * Performs a typewriter effect
+   *
+   *  ```ts
+   * player.showText('Hello World', {
+   *      typewriterEffect: false
+   * })
+   * ```
+   *
+   * **Option: talkWith**
+   *
+   * `RpgPlayer` (nothing by default)
+   *
+   * If you specify the event or another player, the other player will stop his or her movement and look in the player's direction.
+   *
+   *  ```ts
+   * // Code in an event
+   * player.showText('Hello World', {
+   *      talkWith: this
+   * })
+   * ```
+   *
+   * @title Show Text
+   * @method player.showText(text,options)
+   * @param {string} text
+   * @param {object} [options] the different options, see usage below
+   * @returns {Promise}
+   * @memberof GuiManager
+   */
+  showText(msg: string, options?: DialogOptions): Promise<any>;
+
+  /**
+   * Shows a dialog box with a choice. Opens the GUI named `rpg-dialog`
+   *
+   * ```ts
+   * const choice = await player.showChoices('What color do you prefer?', [
+   *      { text: 'Black', value: 'black' },
+   *      { text: 'Rather the blue', value: 'blue' },
+   *      { text: 'I don\'t have a preference!', value: 'none' }
+   * ])
+   *
+   * // If the player selects the first
+   * console.log(choice) // { text: 'Black', value: 'black' }
+   * ```
+   *
+   * @title Show Choices
+   * @method player.showChoices(text,choices)
+   * @param {string} text
+   * @param {Array<{ text: string, value: any }>} choices
+   * @param {object} [options] Same options as the openDialog method
+   * @returns {Promise<Choice | null>}
+   * @memberof GuiManager
+   */
+  showChoices(
+    msg: string,
+    choices: Choice[],
+    options?: DialogOptions
+  ): Promise<Choice | null>;
+
+  /**
+   * Displays a notification . Opens the GUI named `rpg-notification`
+   *
+   * @title Displays a notification
+   * @method player.showNotification()
+   * @param {string} message - The message to display in the notification
+   * @param {object} options - An object containing options for the notification
+   * @param {number} options.time - The time to display the notification for (in ms). Default: 2000ms
+   * @param {string} options.icon - The icon to display in the notification. Put the identifier of the spritesheet (defined on the client side)
+   * @param {string} options.sound - The sound to play when the notification is shown. Set the sound ID (defined on the client side)
+   * @returns {void}
+   * @memberof GuiManager
+   */
+  showNotification(
+    message: string,
+    options?: { time?: number; icon?: string; sound?: string }
+  ): Promise<any>;
+  /**
+   * Calls main menu. Opens the GUI named `rpg-main-menu`
+   *
+   * @title Call Main Menu
+   * @method player.callMainMenu()
+   * @returns {void}
+   * @memberof GuiManager
+   */
+  callMainMenu(): void;
+  callShop(items: any[]): void;
+  gui(guiId: string): Gui;
+  removeGui(guiId: string, data?: any): void;
+  showAttachedGui(players?: RpgPlayer[] | RpgPlayer): void;
+  hideAttachedGui(players?: RpgPlayer[] | RpgPlayer): void;
 }

package/src/Player/ItemFixture.ts

@@ -1,11 +1,10 @@
 import { ItemInstance } from "@rpgjs/database";
-import { RpgCommonPlayer, type Constructor } from "@rpgjs/common";
-export class ItemFixture {}
+import { PlayerCtor } from "@rpgjs/common";
 
-export function WithItemFixture<TBase extends Constructor<RpgCommonPlayer>>(
+export function WithItemFixture<TBase extends PlayerCtor>(
   Base: TBase
 ) {
-  return class extends Base implements IItemFixture {
+  return class extends Base {
     protected getFeature(name, prop): any {
       const array = {};
       for (let item of this.equipments()) {
@@ -21,7 +20,7 @@ export function WithItemFixture<TBase extends Constructor<RpgCommonPlayer>>(
       }
       return Object.values(array);
     }
-  };
+  } as unknown as TBase;
 }
 
 export interface ItemFixture {