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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgjs/server",
-  "version": "5.0.0-alpha.7",
+  "version": "5.0.0-alpha.9",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "publishConfig": {
@@ -11,7 +11,7 @@
   "license": "MIT",
   "description": "",
   "dependencies": {
-    "@rpgjs/common": "5.0.0-alpha.7",
+    "@rpgjs/common": "5.0.0-alpha.9",
     "@rpgjs/database": "^4.3.0",
     "@signe/di": "^2.3.2",
     "@signe/reactive": "^2.3.2",

package/src/Player/ComponentManager.ts

@@ -24,9 +24,24 @@ import { RpgCommonPlayer } from "@rpgjs/common";
  * player.setGraphic(["hero_idle", "hero_walk"]);
  * ```
  */
-export function WithComponentManager<TBase extends PlayerCtor>(Base: TBase) {
+export function WithComponentManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IComponentManager {
   return class extends Base {
-    /**
+    setGraphic(graphic: string | string[]): void {
+       if (Array.isArray(graphic)) {
+         this.graphics.set(graphic);
+       } else {
+         this.graphics.set([graphic]);
+       }
+     }
+  } as unknown as any;
+}
+
+/**
+ * Interface for component management capabilities
+ * Defines the method signature that will be available on the player
+ */
+export interface IComponentManager {
+  /**
      * Set the graphic(s) for this player
      *
      * Allows setting either a single graphic or multiple graphics for the player.
@@ -54,18 +69,5 @@ export function WithComponentManager<TBase extends PlayerCtor>(Base: TBase) {
      * player.setGraphic(["mage_cast_1", "mage_cast_2", "mage_cast_3"]);
      * ```
      */
-         setGraphic(graphic: string | string[]): void {
-       if (Array.isArray(graphic)) {
-         this.graphics.set(graphic);
-       } else {
-         this.graphics.set([graphic]);
-       }
-     }
-  } as unknown as TBase;
+  setGraphic(graphic: string | string[]): void;
 }
-
-/**
- * Type helper to extract the interface from the WithComponentManager mixin
- * This provides the type without duplicating method signatures
- */
-export type IComponentManager = InstanceType<ReturnType<typeof WithComponentManager>>;

package/src/Player/GuiManager.ts

@@ -1,18 +1,18 @@
 import { RpgPlayer } from "./Player";
 import { Gui, DialogGui, MenuGui, ShopGui, NotificationGui } from "../Gui";
 import { DialogOptions, Choice } from "../Gui/DialogGui";
-import { PlayerCtor } from "@rpgjs/common";
+import { Constructor, 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) {
@@ -21,129 +21,25 @@ import { PlayerCtor } from "@rpgjs/common";
  *     // 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 {
+export function WithGuiManager<TBase extends PlayerCtor>(
+  Base: TBase
+): 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[],
@@ -158,19 +54,6 @@ export function WithGuiManager<TBase extends PlayerCtor>(Base: TBase) {
       });
     }
 
-    /**
-     * 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 } = {}
@@ -184,14 +67,6 @@ export function WithGuiManager<TBase extends PlayerCtor>(Base: TBase) {
       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;
@@ -330,11 +205,160 @@ export function WithGuiManager<TBase extends PlayerCtor>(Base: TBase) {
       const _players = players || this;
       this._attachedGui(_players as RpgPlayer[], false);
     }
-  } as unknown as TBase;
+  }
+
+  return GuiManagerMixin as unknown as any;
 }
 
 /**
- * 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/src/RpgServer.ts

@@ -227,20 +227,251 @@ 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/src/core/context.ts

@@ -1,3 +1,4 @@
 import { Context } from "@signe/di";
 
 export const context = new Context();
+context['side'] = 'server'