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

package/dist/RpgServer.d.ts

@@ -1,16 +1,41 @@
-import { RpgPlayer } from './Player/Player';
+import { MapOptions } from './decorators/map';
+import { RpgPlayer, RpgEvent } from './Player/Player';
 import { RpgMap } from './rooms/map';
 import { RpgServerEngine } from './RpgServerEngine';
-type RpgShape = any;
-type RpgClassMap<T> = any;
-type RpgClassEvent<T> = any;
-type RpgEvent = any;
+import { WorldMapConfig, RpgShape } from '@rpgjs/common';
+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 {
     /**
      *  When the server starts
@@ -394,6 +419,9 @@ export interface RpgEventHooks {
 /**
  * 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
  */
@@ -446,6 +474,71 @@ export interface RpgMapHooks {
      * ```
      */
     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 {
     /**
@@ -458,14 +551,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:
@@ -504,18 +597,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]
@@ -526,7 +619,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) {
@@ -534,10 +628,9 @@ export interface RpgServer {
      *      }
      * }
      *
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *      player
      * })
-     * class RpgServerEngine { }
      * ```
      *
      * @prop {RpgClassPlayer<RpgPlayer>} [player]
@@ -548,15 +641,15 @@ 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]
@@ -564,11 +657,13 @@ export interface RpgServer {
      * */
     database?: 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'),
@@ -576,18 +671,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',
@@ -596,24 +702,64 @@ 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?: ((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
      * */
-    maps?: RpgClassMap<RpgMap>[] | MapOptions[] | string[] | TiledMap[];
     map?: RpgMapHooks;
     event?: RpgEventHooks;
     /**
@@ -626,41 +772,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[];
     /**
@@ -683,11 +850,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]
@@ -696,7 +864,6 @@ export interface RpgServer {
      *          }
      *      }
      * })
-     * class RpgServerEngine { }
      * ```
      * @prop {object} damageFormulas
      * @memberof RpgServer

package/dist/decorators/map.d.ts

@@ -23,7 +23,7 @@ export interface MapOptions {
     * @prop {string} file
     * @memberof MapData
     * */
-    file: any;
+    file?: any;
     /**
      * The name of the map.
      * @prop {string} [name]
@@ -96,6 +96,28 @@ export interface MapOptions {
      * @memberof MapData
      * */
     sounds?: string[];
+    /**
+     * Whether to stop all sounds before playing the map sounds when a player joins.
+     *
+     * If set to `true`, all currently playing sounds will be stopped before playing the new map sounds.
+     * This prevents sound overlap when changing maps.
+     *
+     * By default, this is `false`, meaning sounds from the previous map will continue playing.
+     *
+     * ```ts
+     * @MapData({
+     *     id: 'battle-map',
+     *     sounds: ['battle-theme'],
+     *     stopAllSoundsBeforeJoin: true // Stop all sounds before playing battle theme
+     * })
+     * class BattleMap extends RpgMap {}
+     * ```
+     *
+     * @prop {boolean} [stopAllSoundsBeforeJoin=false]
+     * @memberof MapData
+     * @since 5.0.0
+     * */
+    stopAllSoundsBeforeJoin?: boolean;
     /**
      * Specify which properties will be synchronized with the client. On the client side, you can retrieve the values synchronized with the valueChanges property on the scene
      *
@@ -173,5 +195,71 @@ export interface MapOptions {
      * @memberof MapData
      * */
     lowMemory?: boolean;
+    /**
+     * Called when the map is loaded and initialized
+     *
+     * This hook is executed once when the map data is loaded and ready.
+     * Use this to initialize map-specific properties or setup.
+     *
+     * @prop { () => any } [onLoad]
+     * @memberof MapData
+     * @example
+     * ```ts
+     * @MapData({
+     *     id: 'town',
+     *     file: require('./tmx/town.tmx'),
+     *     onLoad() {
+     *         console.log('Town map loaded')
+     *         // Initialize map properties
+     *     }
+     * })
+     * class TownMap extends RpgMap {}
+     * ```
+     * */
+    onLoad?: () => any;
+    /**
+     * Called when a player joins the map
+     *
+     * This hook is executed each time a player joins the map.
+     * Use this to perform actions when a player enters the map.
+     *
+     * @prop { (player: RpgPlayer) => any } [onJoin]
+     * @memberof MapData
+     * @example
+     * ```ts
+     * @MapData({
+     *     id: 'town',
+     *     file: require('./tmx/town.tmx'),
+     *     onJoin(player: RpgPlayer) {
+     *         console.log(`${player.name} joined the town`)
+     *         // Perform actions when player joins
+     *     }
+     * })
+     * class TownMap extends RpgMap {}
+     * ```
+     * */
+    onJoin?: (player: RpgPlayer) => any;
+    /**
+     * Called when a player leaves the map
+     *
+     * This hook is executed each time a player leaves the map.
+     * Use this to perform cleanup or actions when a player exits the map.
+     *
+     * @prop { (player: RpgPlayer) => any } [onLeave]
+     * @memberof MapData
+     * @example
+     * ```ts
+     * @MapData({
+     *     id: 'town',
+     *     file: require('./tmx/town.tmx'),
+     *     onLeave(player: RpgPlayer) {
+     *         console.log(`${player.name} left the town`)
+     *         // Perform cleanup when player leaves
+     *     }
+     * })
+     * class TownMap extends RpgMap {}
+     * ```
+     * */
+    onLeave?: (player: RpgPlayer) => any;
 }
 export declare function MapData(options: MapOptions): (target: any) => void;