@rpgjs/server 5.0.0-alpha.9 → 5.0.0-beta.1

package/src/Player/ElementManager.ts

@@ -30,102 +30,16 @@ 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'
-     *
-     * 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' }]
-     * 
-     * // Check specific element defense
-     * const fireDefense = player.elementsDefense.find(def => def.element === 'fire');
-     * if (fireDefense) {
-     *   console.log(`Fire defense rate: ${fireDefense.rate}`);
-     * }
-     * ```
-     */
     get elementsDefense(): { rate: number; element: any }[] {
       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'
-     *
-     * 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' }]
-     * 
-     * // 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));
-     * ```
-     */
     get elementsEfficiency(): { rate: number; element: any }[] {
       if (this._class()) {
+        const classData = this._class() as any;
         return <any>[
           ...this._elementsEfficiency,
-          ...(this._class()?.elementsEfficiency || []),
+          ...(classData?.elementsEfficiency || []),
         ];
       }
       return this._elementsEfficiency;
@@ -135,33 +49,6 @@ export function WithElementManager<TBase extends PlayerCtor>(Base: TBase) {
       this._elementsEfficiency = val;
     }
 
-    /**
-     * 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
-     * // 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})`);
-     * ```
-     */
     get elements(): {
       rate: number;
       element: string;
@@ -175,40 +62,6 @@ export function WithElementManager<TBase extends PlayerCtor>(Base: TBase) {
       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 as any).elements;
       const playerElements: any = this.elementsEfficiency;
@@ -238,7 +91,76 @@ export function WithElementManager<TBase extends PlayerCtor>(Base: TBase) {
 }
 
 /**
- * Type helper to extract the interface from the WithElementManager mixin
- * This provides the type without duplicating method signatures
+ * 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 type IElementManager = InstanceType<ReturnType<typeof WithElementManager>>;
+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/GuiManager.ts

@@ -1,6 +1,9 @@
 import { RpgPlayer } from "./Player";
-import { Gui, DialogGui, MenuGui, ShopGui, NotificationGui } from "../Gui";
+import { Gui, DialogGui, MenuGui, ShopGui, NotificationGui, SaveLoadGui, GameoverGui } from "../Gui";
 import { DialogOptions, Choice } from "../Gui/DialogGui";
+import { SaveLoadOptions, SaveSlot } from "../Gui/SaveLoadGui";
+import { MenuGuiOptions } from "../Gui/MenuGui";
+import { GameoverGuiOptions, GameoverGuiSelection } from "../Gui/GameoverGui";
 import { Constructor, PlayerCtor } from "@rpgjs/common";
 
 /**
@@ -56,21 +59,42 @@ export function WithGuiManager<TBase extends PlayerCtor>(
 
     showNotification(
       message: string,
-      options: { time?: number; icon?: string; sound?: string } = {}
+      options: { time?: number; icon?: string; sound?: string; type?: "info" | "warn" | "error" } = {}
     ): Promise<any> {
-      const gui = new NotificationGui(<any>this);
-      this._gui[gui.id] = gui;
-      const data = {
+      this.emit('notification', {
         message,
         ...options,
-      };
-      return gui.open(data);
+      });
+      return Promise.resolve(true);
     }
 
-    callMainMenu() {
+    callMainMenu(options: MenuGuiOptions = {}) {
       const gui = new MenuGui(<any>this);
       this._gui[gui.id] = gui;
-      return gui.open();
+      return gui.open(options);
+    }
+
+    callGameover(options: GameoverGuiOptions = {}): Promise<GameoverGuiSelection | null> {
+      const gui = new GameoverGui(<any>this);
+      this._gui[gui.id] = gui;
+      return gui.open(options);
+    }
+
+    showSaveLoad(slots: SaveSlot[] = [], options: SaveLoadOptions = {}): Promise<number | null> {
+      const gui = new SaveLoadGui(<any>this);
+      this._gui[gui.id] = gui;
+      return gui.open(slots, options).then((index) => {
+        if (typeof index !== 'number') return null;
+        return index;
+      });
+    }
+
+    showSave(slots: SaveSlot[] = [], options: SaveLoadOptions = {}): Promise<number | null> {
+      return this.showSaveLoad(slots, { ...options, mode: 'save' });
+    }
+
+    showLoad(slots: SaveSlot[] = [], options: SaveLoadOptions = {}): Promise<number | null> {
+      return this.showSaveLoad(slots, { ...options, mode: 'load' });
     }
 
     /**
@@ -81,7 +105,13 @@ export function WithGuiManager<TBase extends PlayerCtor>(
      * @returns {void}
      * @memberof GuiManager
      */
-    callShop(items: any[]) {
+    callShop(items: any[] | {
+      items: any[]
+      sell?: Record<string, number> | Array<{ id: string; multiplier: number }>
+      sellMultiplier?: number
+      message?: string
+      face?: { id: string; expression?: string }
+    }) {
       const gui = new ShopGui(<any>this);
       this._gui[gui.id] = gui;
       return gui.open(items);
@@ -128,6 +158,10 @@ export function WithGuiManager<TBase extends PlayerCtor>(
       return gui;
     }
 
+    getGui(guiId: string) {
+      return this._gui[guiId];
+    }
+
     /**
      * Closes the GUI and removes it from memory
      *
@@ -345,19 +379,96 @@ export interface IGuiManager {
    */
   showNotification(
     message: string,
-    options?: { time?: number; icon?: string; sound?: string }
+    options?: { time?: number; icon?: string; sound?: string; type?: "info" | "warn" | "error" }
   ): Promise<any>;
+
+  /**
+   * Display a save/load slots screen. Opens the GUI named `rpg-save`
+   *
+   * ```ts
+   * const index = await player.showSaveLoad(slots, { mode: 'save' })
+   * ```
+   *
+   * @title Show Save/Load
+   * @method player.showSaveLoad(slots,options)
+   * @param {Array<object>} slots
+   * @param {object} [options]
+   * @returns {Promise<number | null>}
+   * @memberof GuiManager
+   */
+  showSaveLoad(slots?: SaveSlot[], options?: SaveLoadOptions): Promise<number | null>;
+
+  /**
+   * Display a save slots screen. Opens the GUI named `rpg-save`
+   *
+   * ```ts
+   * const index = await player.showSave(slots)
+   * ```
+   *
+   * @title Show Save
+   * @method player.showSave(slots,options)
+   * @param {Array<object>} slots
+   * @param {object} [options]
+   * @returns {Promise<number | null>}
+   * @memberof GuiManager
+   */
+  showSave(slots?: SaveSlot[], options?: SaveLoadOptions): Promise<number | null>;
+
+  /**
+   * Display a load slots screen. Opens the GUI named `rpg-save`
+   *
+   * ```ts
+   * const index = await player.showLoad(slots)
+   * ```
+   *
+   * @title Show Load
+   * @method player.showLoad(slots,options)
+   * @param {Array<object>} slots
+   * @param {object} [options]
+   * @returns {Promise<number | null>}
+   * @memberof GuiManager
+   */
+  showLoad(slots?: SaveSlot[], options?: SaveLoadOptions): Promise<number | null>;
   /**
    * Calls main menu. Opens the GUI named `rpg-main-menu`
    *
    * @title Call Main Menu
-   * @method player.callMainMenu()
+   * @method player.callMainMenu(options)
+   * @param {object} [options]
    * @returns {void}
    * @memberof GuiManager
    */
-  callMainMenu(): void;
-  callShop(items: any[]): void;
+  callMainMenu(options?: MenuGuiOptions): void;
+
+  /**
+   * Calls game over menu. Opens the GUI named `rpg-gameover`
+   *
+   * ```ts
+   * const selection = await player.callGameover()
+   * if (selection?.id === 'title') {
+   *     await player.gui('rpg-title-screen').open()
+   * }
+   * if (selection?.id === 'load') {
+   *     await player.showLoad()
+   * }
+   * ```
+   *
+   * @title Call Game Over Menu
+   * @method player.callGameover(options)
+   * @param {object} [options]
+   * @returns {Promise<GameoverGuiSelection | null>}
+   * @memberof GuiManager
+   */
+  callGameover(options?: GameoverGuiOptions): Promise<GameoverGuiSelection | null>;
+  callShop(items: any[] | {
+    items: any[]
+    sell?: Record<string, number> | Array<{ id: string; multiplier: number }>
+    sellMultiplier?: number
+    message?: string
+    face?: { id: string; expression?: string }
+  }): void;
   gui(guiId: string): Gui;
+  getGui(guiId: string): Gui;
   removeGui(guiId: string, data?: any): void;
   showAttachedGui(players?: RpgPlayer[] | RpgPlayer): void;
   hideAttachedGui(players?: RpgPlayer[] | RpgPlayer): void;