@rpgjs/server 5.0.0-alpha.4 → 5.0.0-alpha.40

package/src/RpgServer.ts

@@ -1,17 +1,45 @@
+import { MapOptions } from "./decorators/map"
 import { RpgPlayer } from "./Player/Player"
 import { type RpgMap } from "./rooms/map"
 import { RpgServerEngine } from "./RpgServerEngine"
+import { WorldMapConfig, RpgShape } from "@rpgjs/common"
+import { RpgEvent } from "./Player/Player"
 
-type RpgShape = any
-type RpgClassMap<T> = any
-type RpgClassEvent<T> = any
-type RpgEvent = any
+type RpgClassMap<T> = new () => T
+type RpgClassEvent<T> = RpgEvent
 type MatchMakerOption = any
 type RpgMatchMaker = any
 type IStoreState = any
-type TiledMap = any
-type WorldMap = any
-type MapOptions = any
+
+/**
+ * Interface for world map configuration
+ * 
+ * Represents a world that contains multiple maps with their spatial relationships.
+ * This is typically used with Tiled Map Editor's world files.
+ * 
+ * @interface WorldMap
+ * @example
+ * ```ts
+ * const worldMap: WorldMap = {
+ *   id: 'my-world',
+ *   maps: [
+ *     { id: 'map1', worldX: 0, worldY: 0, width: 800, height: 600 },
+ *     { id: 'map2', worldX: 800, worldY: 0, width: 800, height: 600 }
+ *   ]
+ * }
+ * ```
+ */
+export interface WorldMap {
+  /** Optional world identifier */
+  id?: string;
+  /** Array of map configurations that belong to this world */
+  maps: WorldMapConfig[];
+  /** Only show adjacent maps (used by Tiled Map Editor) */
+  onlyShowAdjacentMaps?: boolean;
+  /** Type identifier (used by Tiled Map Editor, should be 'world') */
+  type?: 'world';
+}
+
 
 export interface RpgServerEngineHooks {
     /**
@@ -150,6 +178,14 @@ export interface RpgPlayerHooks {
     */
     onConnected?: (player: RpgPlayer) => any
 
+    /**
+    *  When the player starts the game from the lobby
+    * 
+    * @prop { (player: RpgPlayer) => any } [onStart]
+    * @memberof RpgPlayerHooks
+    */
+    onStart?: (player: RpgPlayer) => any
+
     /**
     *  When the player presses a key on the client side
     * 
@@ -227,20 +263,322 @@ 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
+ * 
+ * These hooks are global hooks that apply to all maps in the game.
+ * They are defined in the RpgModule configuration and executed for every map instance.
+ * 
+ * @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>
+
+    /**
+     * Called when a map is loaded and initialized
+     * 
+     * This hook is executed once when the map data is loaded and ready.
+     * It applies to all maps globally. Use this to initialize map-specific properties
+     * or setup that should happen for every map.
+     * 
+     * @param {RpgMap} map - The map instance that was loaded
+     * @returns {any}
+     * @memberof RpgMapHooks
+     * @example
+     * ```ts
+     * const mapHooks: RpgMapHooks = {
+     *     onLoad(map: RpgMap) {
+     *         console.log(`Map ${map.id} loaded`)
+     *         // Initialize global map properties
+     *     }
+     * }
+     * ```
+     */
+    onLoad?: (map: RpgMap) => any
+
+    /**
+     * Called when a player joins any map
+     * 
+     * This hook is executed each time a player joins any map in the game.
+     * It applies globally to all maps. Use this to perform actions that should
+     * happen whenever a player enters any map.
+     * 
+     * @param {RpgPlayer} player - The player joining the map
+     * @param {RpgMap} map - The map instance the player joined
+     * @returns {any}
+     * @memberof RpgMapHooks
+     * @example
+     * ```ts
+     * const mapHooks: RpgMapHooks = {
+     *     onJoin(player: RpgPlayer, map: RpgMap) {
+     *         console.log(`${player.name} joined map ${map.id}`)
+     *         // Perform global actions when player joins any map
+     *     }
+     * }
+     * ```
+     */
+    onJoin?: (player: RpgPlayer, map: RpgMap) => any
+
+    /**
+     * Called when a player leaves any map
+     * 
+     * This hook is executed each time a player leaves any map in the game.
+     * It applies globally to all maps. Use this to perform cleanup or actions
+     * that should happen whenever a player exits any map.
+     * 
+     * @param {RpgPlayer} player - The player leaving the map
+     * @param {RpgMap} map - The map instance the player left
+     * @returns {any}
+     * @memberof RpgMapHooks
+     * @example
+     * ```ts
+     * const mapHooks: RpgMapHooks = {
+     *     onLeave(player: RpgPlayer, map: RpgMap) {
+     *         console.log(`${player.name} left map ${map.id}`)
+     *         // Perform global cleanup when player leaves any map
+     *     }
+     * }
+     * ```
+     */
+    onLeave?: (player: RpgPlayer, map: RpgMap) => any
 }
 
 export interface RpgServer {
@@ -254,14 +592,14 @@ export interface RpgServer {
      * @example
      * 
      * ```ts
-     * import { RpgServer, RpgModule } from '@rpgjs/server'
+     * import { RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
      * 
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *     hooks: {
      *        player: ['onAuth']
      *    }
      * })
-     * class RpgServerEngine { }
      * ```
      * 
      * Emit the hook:
@@ -301,18 +639,18 @@ export interface RpgServer {
      * Object containing the hooks concerning the engine
      * 
      * ```ts
-     * import { RpgServerEngine, RpgServerEngineHooks, RpgModule, RpgClient } from '@rpgjs/server'
+     * import { RpgServerEngine, RpgServerEngineHooks, RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
      * 
-     * const engine: RpgEngineHooks = {
+     * const engine: RpgServerEngineHooks = {
      *      onStart(server: RpgServerEngine) {
      *          console.log('server is started')
      *      }
      * }
      * 
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *      engine
      * })
-     * class RpgServerModule {}
      * ```
      * 
      * @prop {RpgServerEngineHooks} [engine]
@@ -324,7 +662,8 @@ export interface RpgServer {
      * Give the `player` object hooks. Each time a player connects, an instance of `RpgPlayer` is created.
      * 
      * ```ts
-     * import { RpgPlayer, RpgServer, RpgPlayerHooks, RpgModule } from '@rpgjs/server'
+     * import { RpgPlayer, RpgServer, RpgPlayerHooks } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
      * 
      * const player: RpgPlayerHooks = {
      *      onConnected(player: RpgPlayer) {
@@ -332,10 +671,9 @@ export interface RpgServer {
      *      }
      * }
      * 
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *      player
      * })
-     * class RpgServerEngine { } 
      * ``` 
      * 
      * @prop {RpgClassPlayer<RpgPlayer>} [player]
@@ -347,28 +685,30 @@ export interface RpgServer {
      * References all data in the server. it is mainly used to retrieve data according to their identifier
      * 
      * ```ts
-     * import { RpgServer, RpgModule } from '@rpgjs/server'
+     * import { RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
      * import { Potion } from 'my-database/items/potion'
      * 
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *      database: {
      *          Potion
      *      }
      * })
-     * class RpgServerEngine { } 
      * ``` 
      * 
-     * @prop { { [dataName]: data } } [database]
+     * @prop { { [dataName]: data } | (engine: RpgMap) => { [dataName]: data } | Promise<{ [dataName]: data }> } [database]
      * @memberof RpgServer
      * */
-    database?: object | any[],
+    database?: object | any[] | ((engine: RpgMap) => object | any[] | Promise<object | any[]>),
 
     /** 
-     * Array of all maps. Each element is an `RpgMap` class
+     * Array of all maps. Each element can be either a class (decorated with `@MapData` or not) or a `MapOptions` object
      * 
      * ```ts
-     * import { RpgMap, MapData, RpgServer, RpgModule } from '@rpgjs/server'
+     * import { RpgMap, MapData, RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
      * 
+     * // Class that extends RpgMap (optional)
      * @MapData({
      *      id: 'town',
      *      file: require('./tmx/mymap.tmx'),
@@ -376,18 +716,29 @@ export interface RpgServer {
      * })
      * class TownMap extends RpgMap { }
      * 
-     * @RpgModule<RpgServer>({
+     * // Or a simple class without extending RpgMap
+     * @MapData({
+     *      id: 'map',
+     *      file: '',
+     *      events: [{ event: Event() }]
+     * })
+     * class SimpleMap {}
+     * 
+     * export default defineModule<RpgServer>({
      *      maps: [
-     *          TownMap
+     *          TownMap,
+     *          SimpleMap
      *      ]
      * })
-     * class RpgServerEngine { } 
      * ``` 
      * 
      * It is possible to just give the object as well
      * 
      * ```ts
-     * @RpgModule<RpgServer>({
+     * import { RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
+     * 
+     * export default defineModule<RpgServer>({
      *      maps: [
      *          {
      *              id: 'town',
@@ -396,25 +747,65 @@ export interface RpgServer {
      *          }
      *      ]
      * })
-     * class RpgServerEngine { } 
      * ``` 
      * 
      * Since version 3.0.0-beta.8, you can just pass the path to the file. The identifier will then be the name of the file
      * 
      *  ```ts
-     * @RpgModule<RpgServer>({
+     * import { RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
+     * 
+     * export default defineModule<RpgServer>({
      *      maps: [
      *          require('./tmx/mymap.tmx') // id is "mymap"
      *      ]
      * })
-     * class RpgServerEngine { } 
      * ``` 
      * 
-     * @prop {RpgClassMap<RpgMap>[]} [maps]
+     * @prop {(new () => any) | MapOptions)[]} [maps]
      * @memberof RpgServer
      * */
-    maps?: RpgClassMap<RpgMap>[] | MapOptions[] | string[] | TiledMap[],
+    maps?: ((new () => any) | MapOptions)[],
 
+    /** 
+     * Global map hooks that apply to all maps in the game
+     * 
+     * These hooks are executed for every map instance and allow you to define
+     * global behavior that should happen for all maps. They are different from
+     * map-specific hooks defined in `@MapData` which only apply to a specific map class.
+     * 
+     * ```ts
+     * import { RpgServer, RpgMapHooks, RpgMap, RpgPlayer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
+     * 
+     * const mapHooks: RpgMapHooks = {
+     *     onLoad(map: RpgMap) {
+     *         console.log(`Map ${map.id} loaded`)
+     *         // Initialize global map properties
+     *     },
+     *     onJoin(player: RpgPlayer, map: RpgMap) {
+     *         console.log(`${player.name} joined map ${map.id}`)
+     *         // Perform global actions when player joins any map
+     *     },
+     *     onLeave(player: RpgPlayer, map: RpgMap) {
+     *         console.log(`${player.name} left map ${map.id}`)
+     *         // Perform global cleanup when player leaves any map
+     *     },
+     *     onBeforeUpdate(mapData, map) {
+     *         // Modify map data before update
+     *         return map
+     *     }
+     * }
+     * 
+     * export default defineModule<RpgServer>({
+     *     map: mapHooks
+     * })
+     * ```
+     * 
+     * @prop {RpgMapHooks} [map]
+     * @memberof RpgServer
+     * @since 4.0.0
+     * */
     map?: RpgMapHooks
 
     event?: RpgEventHooks
@@ -430,41 +821,62 @@ export interface RpgServer {
     events?: RpgClassEvent<RpgEvent>[]
 
     /**
-     * Loads the content of a `.world` file from Tiled Map Editor into the map scene
+     * Array of world map configurations
      * 
-     * > Note, that if the map already exists (i.e. you have already defined an RpgMap), the world will retrieve the already existing map. Otherwise it will create a new map
+     * Loads the content of a `.world` file from Tiled Map Editor into the map scene.
+     * Each world contains multiple maps with their spatial relationships.
      * 
-     * @prop {object[]} [worldMaps]
-     * object is 
-     * ```ts
-     * {
-     *  id?: string
-     *  maps: {
-     *      id?: string
-     *      properties?: object
-     *      fileName: string;
-            height: number;
-            width: number;
-            x: number;
-            y: number;
-     *  }[],
-        onlyShowAdjacentMaps: boolean, // only for Tiled Map Editor
-        type: 'world' // only for Tiled Map Editor
-     * }
-     * ```
+     * > Note: If a map already exists (i.e. you have already defined an RpgMap), 
+     * > the world will retrieve the already existing map. Otherwise it will create a new map.
+     * 
+     * @prop {WorldMap[]} [worldMaps]
      * @since 3.0.0-beta.8
+     * @memberof RpgServer
      * @example
      * ```ts
+     * import { RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
      * import myworld from 'myworld.world'
      * 
-     * @RpgModule<RpgServer>({
-     *      worldMaps: [
-     *          myworld
-     *      ]
+     * export default defineModule<RpgServer>({
+     *     worldMaps: [
+     *         myworld
+     *     ]
+     * })
+     * ```
+     * 
+     * @example
+     * ```ts
+     * import { RpgServer } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
+     * 
+     * // Manual world configuration
+     * export default defineModule<RpgServer>({
+     *     worldMaps: [
+     *         {
+     *             id: 'my-world',
+     *             maps: [
+     *                 {
+     *                     id: 'map1',
+     *                     worldX: 0,
+     *                     worldY: 0,
+     *                     width: 800,
+     *                     height: 600,
+     *                     tileWidth: 32,
+     *                     tileHeight: 32
+     *                 },
+     *                 {
+     *                     id: 'map2',
+     *                     worldX: 800,
+     *                     worldY: 0,
+     *                     width: 800,
+     *                     height: 600
+     *                 }
+     *             ]
+     *         }
+     *     ]
      * })
-     * class RpgServerEngine { } 
      * ```
-     * @memberof RpgServer
      */
     worldMaps?: WorldMap[]
 
@@ -489,11 +901,12 @@ export interface RpgServer {
      * Example:
      * 
      * ```ts
-     * import { RpgModule, RpgServer, Presets } from '@rpgjs/server'
+     * import { RpgServer, Presets } from '@rpgjs/server'
+     * import { defineModule } from '@rpgjs/common'
      * 
      * const { ATK, PDEF } = Presets
      * 
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *      damageFormulas: {
      *          damagePhysic(a, b) {
      *              let damage = a[ATK] - b[PDEF]
@@ -502,7 +915,6 @@ export interface RpgServer {
      *          }
      *      }
      * })
-     * class RpgServerEngine { } 
      * ```
      * @prop {object} damageFormulas
      * @memberof RpgServer
@@ -514,6 +926,10 @@ export interface RpgServer {
         coefficientElements?: (a, b, bDef) => number
     }
 
+    /*
+    * Scalability configuration for the server
+    * @deprecated
+    */
     scalability?: {
         matchMaker: MatchMakerOption,
         stateStore: IStoreState
@@ -522,4 +938,8 @@ export interface RpgServer {
             doChangeServer(store: IStoreState, matchMaker: RpgMatchMaker, player: RpgPlayer): Promise<boolean> | boolean
         }
     }
+
+    throttleSync?: number
+    throttleStorage?: number
+    sessionExpiryTime?: number
 }