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

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 {
     /**
@@ -420,6 +448,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
  */
@@ -472,6 +503,74 @@ 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 {
@@ -485,14 +584,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:
@@ -532,18 +631,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]
@@ -555,7 +654,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) {
@@ -563,10 +663,9 @@ export interface RpgServer {
      *      }
      * }
      * 
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *      player
      * })
-     * class RpgServerEngine { } 
      * ``` 
      * 
      * @prop {RpgClassPlayer<RpgPlayer>} [player]
@@ -578,15 +677,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]
@@ -595,11 +694,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'),
@@ -607,18 +708,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',
@@ -627,25 +739,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
@@ -661,41 +813,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[]
 
@@ -720,11 +893,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]
@@ -733,7 +907,6 @@ export interface RpgServer {
      *          }
      *      }
      * })
-     * class RpgServerEngine { } 
      * ```
      * @prop {object} damageFormulas
      * @memberof RpgServer
@@ -745,6 +918,10 @@ export interface RpgServer {
         coefficientElements?: (a, b, bDef) => number
     }
 
+    /*
+    * Scalability configuration for the server
+    * @deprecated
+    */
     scalability?: {
         matchMaker: MatchMakerOption,
         stateStore: IStoreState

package/src/decorators/map.ts

@@ -24,7 +24,7 @@ export interface MapOptions {
     * @prop {string} file
     * @memberof MapData
     * */
-    file: any,
+    file?: any,
 
     /** 
      * The name of the map.
@@ -97,6 +97,29 @@ export interface MapOptions {
      * */
     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
      * 
@@ -175,6 +198,75 @@ 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 function MapData(options: MapOptions) {
@@ -187,6 +279,7 @@ export function MapData(options: MapOptions) {
         target.prototype.id = options.id
         target.prototype.sounds = options.sounds
         target.prototype.lowMemory = options.lowMemory
+        target.prototype.stopAllSoundsBeforeJoin = options.stopAllSoundsBeforeJoin
 
         target.prototype.$schema = {}
 
@@ -194,5 +287,16 @@ export function MapData(options: MapOptions) {
             target.prototype.$schema = options.syncSchema
         }
         target.prototype._events = options.events
+        
+        // Store hooks on prototype
+        if (options.onLoad) {
+            target.prototype.onLoad = options.onLoad
+        }
+        if (options.onJoin) {
+            target.prototype.onJoin = options.onJoin
+        }
+        if (options.onLeave) {
+            target.prototype.onLeave = options.onLeave
+        }
     }
 }

package/src/module.ts

@@ -3,12 +3,66 @@ import { FactoryProvider } from "@signe/di";
 import { RpgServerEngine } from "./RpgServerEngine";
 import { RpgMap } from "./rooms/map";
 import { RpgPlayer } from "./Player/Player";
+import { RpgServer } from "./RpgServer";
 
-export function provideServerModules(modules: any[]): FactoryProvider {
+/**
+ * Type for server modules that can be either:
+ * - An object implementing RpgServer interface
+ * - A class decorated with @RpgModule decorator
+ */
+export type RpgServerModule = RpgServer | (new () => any);
+
+/**
+ * Provides server modules configuration to Angular Dependency Injection
+ * 
+ * This function accepts an array of server modules that can be either:
+ * - Objects implementing the RpgServer interface
+ * - Classes decorated with the @RpgModule decorator (which will be instantiated)
+ * 
+ * @param modules - Array of server modules (objects or classes)
+ * @returns FactoryProvider configuration for Angular DI
+ * @example
+ * ```ts
+ * // Using an object
+ * provideServerModules([
+ *   {
+ *     player: {
+ *       onConnected(player) {
+ *         console.log('Player connected')
+ *       }
+ *     }
+ *   }
+ * ])
+ * 
+ * // Using a decorated class
+ * @RpgModule<RpgServer>({
+ *   engine: {
+ *     onStart(server) {
+ *       console.log('Server started')
+ *     }
+ *   }
+ * })
+ * class MyServerModule {}
+ * 
+ * provideServerModules([MyServerModule])
+ * ```
+ */
+export function provideServerModules(modules: RpgServerModule[]): FactoryProvider {
   return provideModules(modules, "server", (modules, context) => {
     const mainModuleServer = findModules(context, 'Server')
     modules = [...mainModuleServer, ...modules]
     modules = modules.map((module) => {
+      // If module is a class (constructor function), instantiate it
+      // The RpgModule decorator adds properties to the prototype, which will be accessible via the instance
+      if (typeof module === 'function') {
+        const instance = new module() as any;
+        // Copy all enumerable properties (including from prototype) to a plain object
+        const moduleObj: any = {};
+        for (const key in instance) {
+          moduleObj[key] = instance[key];
+        }
+        module = moduleObj;
+      }
       if ('server' in module) {
         module = module.server as any;
       }
@@ -29,7 +83,32 @@ export function provideServerModules(modules: any[]): FactoryProvider {
           maps: {
             load: (engine: RpgMap) => {
               maps.forEach((map) => {
-                engine.maps.push(map);
+                // If map is a class (constructor function), extract properties from class and prototype
+                // Otherwise, use the object directly
+                let mapInstance: any;
+                if (typeof map === 'function') {
+                  // Extract properties from the class (static properties set by @MapData decorator)
+                  // and from the prototype (instance properties like _events)
+                  // The decorator sets properties on both the class and prototype, so we check both
+                  const MapClass = map as any;
+                  mapInstance = {
+                    id: MapClass.prototype?.id ?? MapClass.id,
+                    file: MapClass.prototype?.file ?? MapClass.file,
+                    type: MapClass.type,
+                    name: MapClass.prototype?.name,
+                    sounds: MapClass.prototype?.sounds,
+                    lowMemory: MapClass.prototype?.lowMemory,
+                    stopAllSoundsBeforeJoin: MapClass.prototype?.stopAllSoundsBeforeJoin,
+                    events: MapClass.prototype?._events,
+                    syncSchema: MapClass.prototype?.$schema,
+                    onLoad: MapClass.prototype?.onLoad,
+                    onJoin: MapClass.prototype?.onJoin,
+                    onLeave: MapClass.prototype?.onLeave,
+                  };
+                } else {
+                  mapInstance = map;
+                }
+                engine.maps.push(mapInstance);
               });
             },
           }