@rpgjs/server 5.0.0-alpha.9 → 5.0.0-beta.1

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, type MapPhysicsInitContext, type MapPhysicsEntityContext } 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
     * 
@@ -420,6 +456,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 +511,116 @@ 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
+
+    /**
+     * Called when the map physics world is initialized.
+     *
+     * This hook runs each time `loadPhysic()` prepares the physics world, after static
+     * map hitboxes are created and before dynamic player/event bodies are hydrated.
+     *
+     * @param {RpgMap} map - The map instance
+     * @param {MapPhysicsInitContext} context - Physics initialization context
+     * @returns {any}
+     * @memberof RpgMapHooks
+     */
+    onPhysicsInit?: (map: RpgMap, context: MapPhysicsInitContext) => any
+
+    /**
+     * Called when a dynamic character physics body is added to the map.
+     *
+     * @param {RpgMap} map - The map instance
+     * @param {MapPhysicsEntityContext} context - Added entity context
+     * @returns {any}
+     * @memberof RpgMapHooks
+     */
+    onPhysicsEntityAdd?: (map: RpgMap, context: MapPhysicsEntityContext) => any
+
+    /**
+     * Called when a dynamic character physics body is removed from the map.
+     *
+     * @param {RpgMap} map - The map instance
+     * @param {MapPhysicsEntityContext} context - Removed entity context
+     * @returns {any}
+     * @memberof RpgMapHooks
+     */
+    onPhysicsEntityRemove?: (map: RpgMap, context: MapPhysicsEntityContext) => any
+
+    /**
+     * Called when the map physics world is reset (before reload).
+     *
+     * @param {RpgMap} map - The map instance
+     * @returns {any}
+     * @memberof RpgMapHooks
+     */
+    onPhysicsReset?: (map: RpgMap) => any
 }
 
 export interface RpgServer {
@@ -485,14 +634,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 +681,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 +704,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 +713,9 @@ export interface RpgServer {
      *      }
      * }
      * 
-     * @RpgModule<RpgServer>({
+     * export default defineModule<RpgServer>({
      *      player
      * })
-     * class RpgServerEngine { } 
      * ``` 
      * 
      * @prop {RpgClassPlayer<RpgPlayer>} [player]
@@ -578,28 +727,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'),
@@ -607,18 +758,29 @@ export interface RpgServer {
      * })
      * class TownMap extends RpgMap { }
      * 
-     * @RpgModule<RpgServer>({
+     * // Or a simple class without extending RpgMap
+     * @MapData({
+     *      id: 'map',
+     *      file: '',
+     *      events: [{ x: 100, y: 150, 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 +789,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 +863,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 +943,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 +957,6 @@ export interface RpgServer {
      *          }
      *      }
      * })
-     * class RpgServerEngine { } 
      * ```
      * @prop {object} damageFormulas
      * @memberof RpgServer
@@ -745,6 +968,10 @@ export interface RpgServer {
         coefficientElements?: (a, b, bDef) => number
     }
 
+    /*
+    * Scalability configuration for the server
+    * @deprecated
+    */
     scalability?: {
         matchMaker: MatchMakerOption,
         stateStore: IStoreState
@@ -753,4 +980,8 @@ export interface RpgServer {
             doChangeServer(store: IStoreState, matchMaker: RpgMatchMaker, player: RpgPlayer): Promise<boolean> | boolean
         }
     }
+
+    throttleSync?: number
+    throttleStorage?: number
+    sessionExpiryTime?: number
 }

package/src/decorators/event.ts

@@ -0,0 +1,61 @@
+export enum EventMode {
+    Shared = 'shared',
+    Scenario = 'scenario'
+}
+
+export interface EventOptions {
+    /** 
+     * The mode of the event, shared evening or scenario
+     * 
+     * The scenario mode allows you to have events specific to the player. Thus, the graphics, the positions of the event will be different for each player. Beware of performance! The event is duplicated by each player.
+     * 
+     * `shared` mode by default
+     * 
+     * ```ts
+     * import { RpgEvent, EventData, RpgPlayer, EventMode } from '@rpgjs/server'
+     * @EventData({
+     *      name: 'EV-1',
+     *      mode: EventMode.Scenario // or EventMode.Shared
+     * })
+     * export class CharaEvent extends RpgEvent { }
+     * ```
+     * 
+     * @prop {string} [mode] Either "shared" or "scenario".
+     * @memberof EventData
+     * */
+    mode?: EventMode,
+
+    width?: number,
+    height?: number,
+
+    /** 
+     * The hitbox of the event. By default, this is the size of the tile of the map
+     * 
+     * @prop { { width: number, height: number }} [hitbox]
+     * @memberof EventData
+     * */
+    hitbox?: {
+        width?: number,
+        height?: number
+    },
+
+    /** 
+     * Name of the event. This is its identifier. it allows you to retrieve an event and place it on the map
+     * 
+     * @prop {string} name
+     * @memberof EventData
+     * */
+    name: string
+}
+
+export function EventData(options: EventOptions) {
+    return (target) => {
+        target.mode = options.mode || EventMode.Shared
+        target.width = options.width
+        target.height = options.height
+        target.hitbox = options.hitbox
+        target._name = options.name
+        target.prototype._name = options.name
+        target.prototype.mode = target.mode
+    }
+}