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

package/dist/Player/GuiManager.d.ts

@@ -1,4 +1,10 @@
-import { PlayerCtor } from '@rpgjs/common';
+import { RpgPlayer } from './Player';
+import { Gui } 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 { PlayerCtor } from '../../../common/src';
 /**
  * GUI Manager Mixin
  *
@@ -23,9 +29,231 @@ import { PlayerCtor } from '@rpgjs/common';
  * player.callMainMenu();
  * ```
  */
-export declare function WithGuiManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+export declare function WithGuiManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IGuiManager;
 /**
- * Type helper to extract the interface from the WithGuiManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for GUI management capabilities
+ * Defines the methods that will be available on the player
  */
-export type IGuiManager = InstanceType<ReturnType<typeof WithGuiManager>>;
+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;
+        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(options)
+     * @param {object} [options]
+     * @returns {void}
+     * @memberof GuiManager
+     */
+    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;
+}

package/dist/Player/ItemFixture.d.ts

@@ -1,5 +1,5 @@
 import { ItemInstance } from '@rpgjs/database';
-import { PlayerCtor } from '@rpgjs/common';
+import { PlayerCtor } from '../../../common/src';
 export declare function WithItemFixture<TBase extends PlayerCtor>(Base: TBase): TBase;
 export interface ItemFixture {
     equipments: ItemInstance[];

package/dist/Player/ItemManager.d.ts

@@ -1,4 +1,145 @@
-import { PlayerCtor } from '@rpgjs/common';
+import { Item, PlayerCtor } from '../../../common/src';
+import { ItemClass } from '@rpgjs/database';
+import { RpgPlayer } from './Player';
+/**
+ * Interface defining the hooks that can be implemented on item classes or objects
+ *
+ * These hooks are called at specific moments during the item lifecycle:
+ * - `onAdd`: When the item is added to the player's inventory
+ * - `onUse`: When the item is successfully used
+ * - `onUseFailed`: When the item usage fails (e.g., chance roll failed)
+ * - `onRemove`: When the item is removed from the inventory
+ * - `onEquip`: When the item is equipped or unequipped
+ *
+ * @example
+ * ```ts
+ * const itemHooks: ItemHooks = {
+ *   onAdd(player) {
+ *     console.log('Item added to inventory');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemHooks {
+    /**
+     * Called when the item is added to the player's inventory
+     *
+     * @param player - The player receiving the item
+     */
+    onAdd?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is successfully used
+     *
+     * @param player - The player using the item
+     */
+    onUse?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item usage fails (e.g., chance roll failed)
+     *
+     * @param player - The player attempting to use the item
+     */
+    onUseFailed?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is removed from the inventory
+     *
+     * @param player - The player losing the item
+     */
+    onRemove?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is equipped or unequipped
+     *
+     * @param player - The player equipping/unequipping the item
+     * @param equip - true if equipping, false if unequipping
+     */
+    onEquip?: (player: RpgPlayer, equip: boolean) => void | Promise<void>;
+}
+/**
+ * Base properties that can be included in an item object
+ *
+ * This interface defines the common properties that items can have.
+ * Use this as a base and extend it with specific item types.
+ *
+ * @template T - Additional properties specific to the item type
+ *
+ * @example
+ * ```ts
+ * interface PotionData extends ItemData {
+ *   hpValue: number;
+ *   mpValue: number;
+ * }
+ *
+ * const potion: ItemObject<PotionData> = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   mpValue: 0,
+ *   onUse(player) {
+ *     player.hp += this.hpValue;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemData {
+    /** Item name */
+    name?: string;
+    /** Item description */
+    description?: string;
+    /** Item price */
+    price?: number;
+    /** HP value restored when used */
+    hpValue?: number;
+    /** MP/SP value restored when used */
+    mpValue?: number;
+    /** Chance to successfully use the item (0-1) */
+    hitRate?: number;
+    /** Whether the item is consumable */
+    consumable?: boolean;
+    /** States to add when used */
+    addStates?: any[];
+    /** States to remove when used */
+    removeStates?: any[];
+    /** Elemental properties */
+    elements?: any[];
+    /** Parameter modifiers */
+    paramsModifier?: Record<string, any>;
+    /** Item type (for equipment validation) */
+    _type?: 'item' | 'weapon' | 'armor';
+}
+/**
+ * Item object type that combines data properties with hooks
+ *
+ * This type allows you to create item objects directly without needing a class.
+ * The object can contain both item data properties and lifecycle hooks.
+ *
+ * @template T - Additional properties specific to the item type (extends ItemData)
+ *
+ * @example
+ * ```ts
+ * const potion: ItemObject = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   consumable: true,
+ *   onAdd(player) {
+ *     console.log('Potion added!');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ *
+ * player.addItem(potion);
+ * ```
+ */
+export type ItemObject<T extends ItemData = ItemData> = T & ItemHooks & {
+    /** Item identifier (required if not using class or string) */
+    id?: string;
+};
 /**
  * Item Manager Mixin
  *
@@ -25,7 +166,293 @@ import { PlayerCtor } from '@rpgjs/common';
  */
 export declare function WithItemManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Type helper to extract the interface from the WithItemManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for Item Manager functionality
+ *
+ * Provides comprehensive item management capabilities including inventory management,
+ * item usage, equipment, buying/selling, and item effects. This interface defines
+ * the public API of the ItemManager mixin.
  */
-export type IItemManager = InstanceType<ReturnType<typeof WithItemManager>>;
+export interface IItemManager {
+    /**
+     * Retrieves the information of an object: the number and the instance
+     *
+     * The returned Item instance contains the quantity information accessible via `quantity()` method.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @returns Item instance containing quantity and item data
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * player.addItem(Potion, 5)
+     * const inventory = player.getItem(Potion)
+     * console.log(inventory.quantity()) // 5
+     * console.log(inventory) // <instance of Item>
+     * ```
+     */
+    getItem(itemClass: ItemClass | string): Item;
+    /**
+     * Check if the player has the item in his inventory
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @returns `true` if player has the item, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * player.hasItem(Potion) // false
+     * player.addItem(Potion, 1)
+     * player.hasItem(Potion) // true
+     * ```
+     */
+    hasItem(itemClass: ItemClass | string): boolean;
+    /**
+     * Add an item in the player's inventory
+     *
+     * You can add items using:
+     * - Item class (automatically registered in database if needed)
+     * - Item object (automatically registered in database if needed)
+     * - String ID (must be pre-registered in database)
+     *
+     * The `onAdd()` method is called on the ItemClass or ItemObject when the item is added.
+     *
+     * @param item - Item class, object, or string identifier
+     * @param nb - Number of items to add (default: 1)
+     * @returns The item instance added to inventory
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * // Add using class
+     * player.addItem(Potion, 5)
+     *
+     * // Add using string ID (must be registered in database)
+     * player.addItem('Potion', 3)
+     *
+     * // Add using object
+     * player.addItem({
+     *   id: 'custom-potion',
+     *   name: 'Custom Potion',
+     *   price: 200,
+     *   onAdd(player) {
+     *     console.log('Custom potion added!')
+     *   }
+     * }, 2)
+     * ```
+     */
+    addItem(item: ItemClass | ItemObject | string, nb?: number): Item;
+    /**
+     * Deletes an item from inventory
+     *
+     * Decreases the quantity by `nb`. If the quantity falls to 0 or below, the item is removed from the inventory.
+     * The method returns `undefined` if the item is completely removed.
+     *
+     * The `onRemove()` method is called on the ItemClass when the item is removed.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @param nb - Number of items to remove (default: 1)
+     * @returns Item instance or `undefined` if the item was completely removed
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.removeItem(Potion, 5)
+     * } catch (err) {
+     *   console.log(err) // { id: 'ITEM_NOT_INVENTORY', msg: '...' }
+     * }
+     * ```
+     */
+    removeItem(itemClass: ItemClass | string, nb?: number): Item | undefined;
+    /**
+     * Purchases an item and reduces the amount of gold
+     *
+     * The player's gold is reduced by `nb * item.price`. The item is then added to the inventory.
+     * The `onAdd()` method is called on the ItemClass when the item is added.
+     *
+     * @param item - Item class, object, or string identifier
+     * @param nb - Number of items to buy (default: 1)
+     * @returns Item instance added to inventory
+     * @throws {Object} ItemLog.haveNotPrice - If the item has no price set
+     *   - `id`: `NOT_PRICE`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notEnoughGold - If the player doesn't have enough gold
+     *   - `id`: `NOT_ENOUGH_GOLD`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.buyItem(Potion)
+     * } catch (err) {
+     *   if (err.id === 'NOT_ENOUGH_GOLD') {
+     *     console.log('Not enough gold!')
+     *   } else if (err.id === 'NOT_PRICE') {
+     *     console.log('Item has no price!')
+     *   }
+     * }
+     * ```
+     */
+    buyItem(item: ItemClass | ItemObject | string, nb?: number): Item;
+    /**
+     * Sell an item and the player wins the amount of the item divided by 2
+     *
+     * The player receives `(item.price / 2) * nbToSell` gold. The item is removed from the inventory.
+     * The `onRemove()` method is called on the ItemClass when the item is removed.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @param nbToSell - Number of items to sell (default: 1)
+     * @returns Item instance that was sold
+     * @throws {Object} ItemLog.haveNotPrice - If the item has no price set
+     *   - `id`: `NOT_PRICE`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.tooManyToSell - If trying to sell more items than available
+     *   - `id`: `TOO_MANY_ITEM_TO_SELL`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.addItem(Potion)
+     *   player.sellItem(Potion)
+     * } catch (err) {
+     *   console.log(err)
+     * }
+     * ```
+     */
+    sellItem(itemClass: ItemClass | string, nbToSell?: number): Item;
+    /**
+     * Use an object. Applies effects and states. Removes the object from the inventory
+     *
+     * When an item is used:
+     * - Effects are applied to the player (HP/MP restoration, etc.)
+     * - States are applied/removed as defined in the item
+     * - The item is removed from inventory (consumed)
+     *
+     * If the item has a `hitRate` property (0-1), there's a chance the usage might fail.
+     * If usage fails, the item is still removed and `onUseFailed()` is called instead of `onUse()`.
+     *
+     * The `onUse()` method is called on the ItemClass if the use was successful.
+     * The `onUseFailed()` method is called on the ItemClass if the chance roll failed.
+     * The `onRemove()` method is called on the ItemClass when the item is removed.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @returns Item instance that was used
+     * @throws {Object} ItemLog.restriction - If the player has the `Effect.CAN_NOT_ITEM` effect
+     *   - `id`: `RESTRICTION_ITEM`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notUseItem - If the item's `consumable` property is `false`
+     *   - `id`: `NOT_USE_ITEM`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.chanceToUseFailed - If the chance to use the item failed (hitRate roll failed)
+     *   - `id`: `USE_CHANCE_ITEM_FAILED`
+     *   - `msg`: Error message
+     *   - Note: The item is still deleted from the inventory even if usage failed
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.addItem(Potion)
+     *   player.useItem(Potion)
+     * } catch (err) {
+     *   if (err.id === 'USE_CHANCE_ITEM_FAILED') {
+     *     console.log('Item usage failed due to chance roll')
+     *   } else {
+     *     console.log(err)
+     *   }
+     * }
+     * ```
+     */
+    useItem(itemClass: ItemClass | string): Item;
+    /**
+     * Equips a weapon or armor on a player
+     *
+     * Think first to add the item in the inventory with the `addItem()` method before equipping the item,
+     * or pass `"auto"` to add the item if it is missing and equip it.
+     *
+     * The `onEquip()` method is called on the ItemClass when the item is equipped or unequipped.
+     *
+     * @param itemId - Item identifier to resolve from the database
+     * @param equip - Equip the item if `true`, unequip if `false`, or `"auto"` to add then equip (default: `true`)
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.invalidToEquiped - If the item is not a weapon or armor (item._type is "item")
+     *   - `id`: `INVALID_ITEM_TO_EQUIP`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.isAlreadyEquiped - If the item is already equipped
+     *   - `id`: `ITEM_ALREADY_EQUIPED`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * try {
+     *   player.addItem('sword')
+     *   player.equip('sword')
+     *   // Later, unequip it
+     *   player.equip('sword', false)
+     * } catch (err) {
+     *   console.log(err)
+     * }
+     * ```
+     */
+    equip(itemId: string, equip?: boolean | 'auto'): void;
+    /**
+     * Get the player's attack (sum of items equipped)
+     *
+     * Returns the total attack value from all equipped items on the player.
+     *
+     * @returns Total attack value from equipped items
+     *
+     * @example
+     * ```ts
+     * console.log(player.atk) // 150 (sum of all equipped weapons/armors attack)
+     * ```
+     */
+    readonly atk: number;
+    /**
+     * Get the player's physical defense (sum of items equipped)
+     *
+     * Returns the total physical defense value from all equipped items on the player.
+     *
+     * @returns Total physical defense value from equipped items
+     *
+     * @example
+     * ```ts
+     * console.log(player.pdef) // 80 (sum of all equipped armors physical defense)
+     * ```
+     */
+    readonly pdef: number;
+    /**
+     * Get the player's skill defense (sum of items equipped)
+     *
+     * Returns the total skill defense value from all equipped items on the player.
+     *
+     * @returns Total skill defense value from equipped items
+     *
+     * @example
+     * ```ts
+     * console.log(player.sdef) // 60 (sum of all equipped armors skill defense)
+     * ```
+     */
+    readonly sdef: number;
+}