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

package/dist/Player/GuiManager.d.ts

@@ -0,0 +1,176 @@
+import { RpgPlayer } from './Player';
+import { Gui } from '../Gui';
+import { DialogOptions, Choice } from '../Gui/DialogGui';
+import { PlayerCtor } from '@rpgjs/common';
+/**
+ * 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 declare function WithGuiManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IGuiManager;
+/**
+ * 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/dist/Player/ItemFixture.d.ts

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

package/dist/Player/ItemManager.d.ts

@@ -1,17 +1,171 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-import { ItemClass } from '@rpgjs/database';
+import { PlayerCtor } from '@rpgjs/common';
+import { RpgPlayer } from './Player';
 /**
- * Interface defining what MoveManager adds to a class
+ * 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 IItemManager {
-    databaseById(id: string): ItemClass;
+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';
 }
 /**
- * Move Manager mixin
+ * 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.
  *
- * Adds methods to manage player movement
+ * @template T - Additional properties specific to the item type (extends ItemData)
  *
- * @param Base - The base class to extend
- * @returns A new class with move management capabilities
+ * @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
+ *
+ * Provides comprehensive item management capabilities to any class. This mixin handles
+ * inventory management, item usage, equipment, buying/selling, and item effects.
+ * It manages the complete item system including restrictions, transactions, and equipment.
+ *
+ * @param Base - The base class to extend with item management
+ * @returns Extended class with item management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithItemManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Item system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.addItem('potion', 5);
+ * player.useItem('potion');
+ * ```
+ */
+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
  */
-export declare function WithItemManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase): Constructor<IItemManager> & TBase;
+export type IItemManager = InstanceType<ReturnType<typeof WithItemManager>>;

package/dist/Player/MoveManager.d.ts

@@ -1,48 +1,7 @@
-import { Constructor, RpgCommonPlayer, Direction, MovementStrategy, ProjectileType } from '@rpgjs/common';
+import { PlayerCtor, Direction } from '@rpgjs/common';
 import { RpgPlayer } from './Player';
-export interface IMoveManager {
-    addMovement(strategy: MovementStrategy): void;
-    removeMovement(strategy: MovementStrategy): boolean;
-    clearMovements(): void;
-    hasActiveMovements(): boolean;
-    getActiveMovements(): MovementStrategy[];
-    moveTo(target: RpgCommonPlayer | {
-        x: number;
-        y: number;
-    }): void;
-    stopMoveTo(): void;
-    dash(direction: {
-        x: number;
-        y: number;
-    }, speed?: number, duration?: number): void;
-    knockback(direction: {
-        x: number;
-        y: number;
-    }, force?: number, duration?: number): void;
-    followPath(waypoints: Array<{
-        x: number;
-        y: number;
-    }>, speed?: number, loop?: boolean): void;
-    oscillate(direction: {
-        x: number;
-        y: number;
-    }, amplitude?: number, period?: number): void;
-    applyIceMovement(direction: {
-        x: number;
-        y: number;
-    }, maxSpeed?: number): void;
-    shootProjectile(type: ProjectileType, direction: {
-        x: number;
-        y: number;
-    }, speed?: number): void;
-    moveRoutes(routes: Routes): Promise<boolean>;
-    infiniteMoveRoute(routes: Routes): void;
-    breakRoutes(force?: boolean): void;
-    replayRoutes(): void;
-}
 type CallbackTileMove = (player: RpgPlayer, map: any) => Direction[];
 type CallbackTurnMove = (player: RpgPlayer, map: any) => string;
-type Routes = (string | Promise<any> | Direction | Direction[] | Function)[];
 export declare enum Frequency {
     Lowest = 600,
     Lower = 400,
@@ -129,7 +88,7 @@ export declare const Move: MoveList;
  * - **Strategy Management**: Add, remove, and query movement strategies
  * - **Predefined Movements**: Quick access to common movement patterns
  * - **Composite Movements**: Combine multiple strategies
- * - **Physics Integration**: Seamless integration with Matter.js physics
+ * - **Physics Integration**: Seamless integration with the deterministic @rpgjs/physic engine
  *
  * ## Available Movement Strategies
  * - `LinearMove`: Constant velocity movement
@@ -173,5 +132,34 @@ export declare const Move: MoveList;
  * }
  * ```
  */
-export declare function WithMoveManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase): Constructor<IMoveManager> & TBase;
+/**
+ * Move Manager Mixin
+ *
+ * Provides comprehensive movement management capabilities to any class. This mixin handles
+ * various types of movement including pathfinding, physics-based movement, route following,
+ * and advanced movement strategies like dashing, knockback, and projectile movement.
+ *
+ * @param Base - The base class to extend with movement management
+ * @returns Extended class with movement management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithMoveManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     this.frequency = Frequency.High;
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.moveTo({ x: 100, y: 100 });
+ * player.dash({ x: 1, y: 0 }, 8, 200);
+ * ```
+ */
+export declare function WithMoveManager<TBase extends PlayerCtor>(Base: TBase): PlayerCtor;
+/**
+ * Type helper to extract the interface from the WithMoveManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IMoveManager = InstanceType<ReturnType<typeof WithMoveManager>>;
 export {};