@rpgjs/server 5.0.0-alpha.7 → 5.0.0-alpha.9

package/dist/Player/ComponentManager.d.ts

@@ -22,9 +22,39 @@ import { PlayerCtor } from '@rpgjs/common';
  * player.setGraphic(["hero_idle", "hero_walk"]);
  * ```
  */
-export declare function WithComponentManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+export declare function WithComponentManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IComponentManager;
 /**
- * Type helper to extract the interface from the WithComponentManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for component management capabilities
+ * Defines the method signature that will be available on the player
  */
-export type IComponentManager = InstanceType<ReturnType<typeof WithComponentManager>>;
+export interface IComponentManager {
+    /**
+       * Set the graphic(s) for this player
+       *
+       * Allows setting either a single graphic or multiple graphics for the player.
+       * When multiple graphics are provided, they are used for animation sequences.
+       * The graphics system provides flexible visual representation that can be
+       * dynamically changed during gameplay for different states, equipment, or animations.
+       *
+       * @param graphic - Single graphic name or array of graphic names for animation sequences
+       * @returns void
+       *
+       * @example
+       * ```ts
+       * // Set a single graphic for static representation
+       * player.setGraphic("hero");
+       *
+       * // Set multiple graphics for animation sequences
+       * player.setGraphic(["hero_idle", "hero_walk", "hero_run"]);
+       *
+       * // Dynamic graphic changes based on equipment
+       * if (player.hasArmor('platemail')) {
+       *   player.setGraphic("hero_armored");
+       * }
+       *
+       * // Animation sequences for different actions
+       * player.setGraphic(["mage_cast_1", "mage_cast_2", "mage_cast_3"]);
+       * ```
+       */
+    setGraphic(graphic: string | string[]): void;
+}

package/dist/Player/GuiManager.d.ts

@@ -1,3 +1,6 @@
+import { RpgPlayer } from './Player';
+import { Gui } from '../Gui';
+import { DialogOptions, Choice } from '../Gui/DialogGui';
 import { PlayerCtor } from '@rpgjs/common';
 /**
  * GUI Manager Mixin
@@ -23,9 +26,151 @@ 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;
+    }): 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/RpgServer.d.ts

@@ -210,19 +210,242 @@ export interface RpgPlayerHooks {
     */
     canChangeMap?: (player: RpgPlayer, nextMap: RpgClassMap<RpgMap>) => boolean | Promise<boolean>;
 }
+/**
+ * Event hooks interface for handling various event lifecycle methods
+ *
+ * @interface RpgEventHooks
+ * @since 4.0.0
+ */
 export interface RpgEventHooks {
+    /**
+     * Called as soon as the event is created on the map
+     *
+     * @param {RpgEvent} event - The event instance being initialized
+     * @returns {any}
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onInit(event) {
+     *         console.log(`Event ${event.name} initialized`)
+     *         event.graphic('default-sprite')
+     *     }
+     * }
+     * ```
+     */
     onInit?: (event: RpgEvent) => any;
+    /**
+     * Called when the event collides with a player and the player presses the action key
+     *
+     * @param {RpgEvent} event - The event being interacted with
+     * @param {RpgPlayer} player - The player performing the action
+     * @returns {any}
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onAction(event, player) {
+     *         player.showText('You activated the chest!')
+     *         player.addItem('POTION', 1)
+     *     }
+     * }
+     * ```
+     */
     onAction?: (event: RpgEvent, player: RpgPlayer) => any;
+    /**
+     * Called before an event object is created and added to the map
+     * Allows modification of event properties before instantiation
+     *
+     * @param {any} object - The event object data before creation
+     * @param {RpgMap} map - The map where the event will be created
+     * @returns {any}
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onBeforeCreated(object, map) {
+     *         // Modify event properties based on map conditions
+     *         if (map.id === 'dungeon') {
+     *             object.graphic = 'monster-sprite'
+     *         }
+     *     }
+     * }
+     * ```
+     */
     onBeforeCreated?: (object: any, map: RpgMap) => any;
+    /**
+     * Called when a player or another event enters a shape attached to this event
+     *
+     * @param {RpgEvent} event - The event with the attached shape
+     * @param {RpgPlayer} player - The player entering the shape
+     * @param {RpgShape} shape - The shape being entered
+     * @returns {any}
+     * @since 4.1.0
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onDetectInShape(event, player, shape) {
+     *         console.log(`Player ${player.name} entered detection zone`)
+     *         player.showText('You are being watched...')
+     *     }
+     * }
+     * ```
+     */
     onDetectInShape?: (event: RpgEvent, player: RpgPlayer, shape: RpgShape) => any;
+    /**
+     * Called when a player or another event leaves a shape attached to this event
+     *
+     * @param {RpgEvent} event - The event with the attached shape
+     * @param {RpgPlayer} player - The player leaving the shape
+     * @param {RpgShape} shape - The shape being left
+     * @returns {any}
+     * @since 4.1.0
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onDetectOutShape(event, player, shape) {
+     *         console.log(`Player ${player.name} left detection zone`)
+     *         player.showText('You escaped the watch...')
+     *     }
+     * }
+     * ```
+     */
     onDetectOutShape?: (event: RpgEvent, player: RpgPlayer, shape: RpgShape) => any;
+    /**
+     * Called when the event enters a shape on the map
+     *
+     * @param {RpgEvent} event - The event entering the shape
+     * @param {RpgShape} shape - The shape being entered
+     * @returns {any}
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onInShape(event, shape) {
+     *         console.log(`Event entered shape: ${shape.id}`)
+     *         event.speed = 1 // Slow down in this area
+     *     }
+     * }
+     * ```
+     */
     onInShape?: (event: RpgEvent, shape: RpgShape) => any;
+    /**
+     * Called when the event leaves a shape on the map
+     *
+     * @param {RpgEvent} event - The event leaving the shape
+     * @param {RpgShape} shape - The shape being left
+     * @returns {any}
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onOutShape(event, shape) {
+     *         console.log(`Event left shape: ${shape.id}`)
+     *         event.speed = 3 // Resume normal speed
+     *     }
+     * }
+     * ```
+     */
     onOutShape?: (event: RpgEvent, shape: RpgShape) => any;
+    /**
+     * Called when the event collides with a player (without requiring action key press)
+     *
+     * @param {RpgEvent} event - The event touching the player
+     * @param {RpgPlayer} player - The player being touched
+     * @returns {any}
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onPlayerTouch(event, player) {
+     *         player.hp -= 10 // Damage on touch
+     *         player.showText('Ouch! You touched a spike!')
+     *     }
+     * }
+     * ```
+     */
     onPlayerTouch?: (event: RpgEvent, player: RpgPlayer) => any;
+    /**
+     * Called whenever any event on the map (including itself) is executed or changes state
+     * Useful for creating reactive events that respond to map state changes
+     *
+     * @param {RpgEvent} event - The event listening for changes
+     * @param {RpgPlayer} player - The player involved in the change
+     * @returns {any}
+     * @memberof RpgEventHooks
+     * @example
+     * ```ts
+     * const eventHooks: RpgEventHooks = {
+     *     onChanges(event, player) {
+     *         // Change chest graphic based on game state
+     *         if (player.getVariable('BATTLE_END')) {
+     *             event.graphic('chest-open')
+     *         } else {
+     *             event.graphic('chest-close')
+     *         }
+     *     }
+     * }
+     * ```
+     */
     onChanges?: (event: RpgEvent, player: RpgPlayer) => any;
 }
+/**
+ * Map hooks interface for handling map lifecycle events
+ *
+ * @interface RpgMapHooks
+ * @since 4.0.0
+ */
 export interface RpgMapHooks {
-    onBeforeUpdate<T = RpgMap>(mapData: any, map: T): T;
+    /**
+     * Called before a map is updated with new data
+     * Allows modification of map data before the update is applied
+     *
+     * The `mapData` parameter contains the loaded map data (retrieved from request body)
+     * You can modify the map before the update is processed
+     *
+     * @template T - Type of the incoming map data
+     * @template U - Type of the map instance (defaults to RpgMap)
+     * @param {T} mapData - The map data loaded from external source (e.g., request body)
+     * @param {U} map - The current map instance being updated
+     * @returns {U | Promise<U>} The modified map instance or a promise resolving to it
+     * @memberof RpgMapHooks
+     * @example
+     * ```ts
+     * const mapHooks: RpgMapHooks = {
+     *     onBeforeUpdate(mapData, map) {
+     *         // Modify map properties based on incoming data
+     *         if (mapData.weather === 'rain') {
+     *             map.setWeatherEffect('rain')
+     *         }
+     *
+     *         // Add custom properties from external data
+     *         map.customProperty = mapData.customValue
+     *
+     *         return map
+     *     }
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Async example with database operations
+     * const mapHooks: RpgMapHooks = {
+     *     async onBeforeUpdate(mapData, map) {
+     *         // Load additional data from database
+     *         const additionalData = await database.getMapExtras(map.id)
+     *
+     *         // Apply modifications
+     *         map.events = [...map.events, ...additionalData.events]
+     *         map.npcs = additionalData.npcs
+     *
+     *         return map
+     *     }
+     * }
+     * ```
+     */
+    onBeforeUpdate<T, U = RpgMap>(mapData: T, map: U): U | Promise<U>;
 }
 export interface RpgServer {
     /**

package/dist/index.js

@@ -25651,34 +25651,6 @@ var PrebuiltGui = /* @__PURE__ */ ((PrebuiltGui2) => {
 
 function WithComponentManager(Base) {
   return class extends Base {
-    /**
-     * Set the graphic(s) for this player
-     *
-     * Allows setting either a single graphic or multiple graphics for the player.
-     * When multiple graphics are provided, they are used for animation sequences.
-     * The graphics system provides flexible visual representation that can be
-     * dynamically changed during gameplay for different states, equipment, or animations.
-     *
-     * @param graphic - Single graphic name or array of graphic names for animation sequences
-     * @returns void
-     *
-     * @example
-     * ```ts
-     * // Set a single graphic for static representation
-     * player.setGraphic("hero");
-     *
-     * // Set multiple graphics for animation sequences
-     * player.setGraphic(["hero_idle", "hero_walk", "hero_run"]);
-     * 
-     * // Dynamic graphic changes based on equipment
-     * if (player.hasArmor('platemail')) {
-     *   player.setGraphic("hero_armored");
-     * }
-     * 
-     * // Animation sequences for different actions
-     * player.setGraphic(["mage_cast_1", "mage_cast_2", "mage_cast_3"]);
-     * ```
-     */
     setGraphic(graphic) {
       if (Array.isArray(graphic)) {
         this.graphics.set(graphic);
@@ -26990,123 +26962,16 @@ class NotificationGui extends Gui {
 }
 
 function WithGuiManager(Base) {
-  return class extends Base {
+  class GuiManagerMixin extends Base {
     constructor() {
       super(...arguments);
       this._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, options = {}) {
       const gui = new DialogGui(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, choices, options) {
       return this.showText(msg, {
         choices,
@@ -27116,19 +26981,6 @@ function WithGuiManager(Base) {
         return choices[indexSelected];
       });
     }
-    /**
-     * 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, options = {}) {
       const gui = new NotificationGui(this);
       this._gui[gui.id] = gui;
@@ -27138,14 +26990,6 @@ function WithGuiManager(Base) {
       };
       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(this);
       this._gui[gui.id] = gui;
@@ -27278,7 +27122,8 @@ function WithGuiManager(Base) {
       const _players = players || this;
       this._attachedGui(_players, false);
     }
-  };
+  }
+  return GuiManagerMixin;
 }
 
 function WithGoldManager(Base) {
@@ -29791,6 +29636,7 @@ class RpgEvent extends RpgPlayer {
 }
 
 const context$1 = new Context();
+context$1["side"] = "server";
 
 var __defProp$1 = Object.defineProperty;
 var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;