@rpgjs/server 5.0.0-alpha.2 → 5.0.0-alpha.20

package/dist/Player/SkillManager.d.ts

@@ -1,23 +1,31 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-import { RpgPlayer } from './Player';
+import { PlayerCtor } from '@rpgjs/common';
 /**
- * Interface defining dependencies from other mixins that SkillManager needs
+ * Skill Manager Mixin
+ *
+ * Provides skill management capabilities to any class. This mixin handles
+ * learning, forgetting, and using skills, including SP cost management,
+ * hit rate calculations, and skill effects application.
+ *
+ * @param Base - The base class to extend with skill management
+ * @returns Extended class with skill management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithSkillManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Skill system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.learnSkill(Fire);
+ * player.useSkill(Fire, targetPlayer);
+ * ```
  */
-interface SkillManagerDependencies {
-    sp: number;
-    skills(): any[];
-    hasEffect(effect: string): boolean;
-    databaseById(id: string): any;
-    applyStates(player: RpgPlayer, skill: any): void;
-}
+export declare function WithSkillManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Interface defining what SkillManager adds to a class
+ * Type helper to extract the interface from the WithSkillManager mixin
+ * This provides the type without duplicating method signatures
  */
-export interface IWithSkillManager {
-    getSkill(skillClass: any | string): any;
-    learnSkill(skillId: any | string): any;
-    forgetSkill(skillId: any | string): any;
-    useSkill(skillId: any | string, otherPlayer?: RpgPlayer | RpgPlayer[]): any;
-}
-export declare function WithSkillManager<TBase extends Constructor<RpgCommonPlayer & SkillManagerDependencies>>(Base: TBase): Constructor<IWithSkillManager> & TBase;
-export {};
+export type ISkillManager = InstanceType<ReturnType<typeof WithSkillManager>>;

package/dist/Player/StateManager.d.ts

@@ -1,39 +1,32 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-import { WritableArraySignal } from '@signe/reactive';
-import { RpgPlayer } from './Player';
-interface StateManagerDependencies {
-    equipments(): any[];
-    databaseById(id: string | StateClass): any;
-    addState(stateClass: StateClass | string, chance?: number): object | null;
-    removeState(stateClass: StateClass | string, chance?: number): void;
-}
+import { PlayerCtor } from '@rpgjs/common';
 /**
- * Interface defining what MoveManager adds to a class
- */
-export interface IStateManager {
-    statesDefense: {
-        rate: number;
-        state: any;
-    }[];
-    statesEfficiency: WritableArraySignal<any[]>;
-    applyStates(player: RpgPlayer, states: {
-        addStates?: any[];
-        removeStates?: any[];
-    }): void;
-    getState(stateClass: StateClass | string): any;
-    addState(stateClass: StateClass | string, chance?: number): object | null;
-    removeState(stateClass: StateClass | string, chance?: number): void;
-}
-type StateClass = {
-    new (...args: any[]): any;
-};
-/**
- * Move Manager mixin
+ * State Manager Mixin
+ *
+ * Provides state management capabilities to any class. This mixin handles
+ * player states (buffs/debuffs), state defense from equipment, and state
+ * efficiency modifiers. It manages the complete state system including
+ * application, removal, and resistance mechanics.
  *
- * Adds methods to manage player movement
+ * @param Base - The base class to extend with state management
+ * @returns Extended class with state management methods
  *
- * @param Base - The base class to extend
- * @returns A new class with move management capabilities
+ * @example
+ * ```ts
+ * class MyPlayer extends WithStateManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // State system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.addState(Paralyze);
+ * console.log(player.getState(Paralyze));
+ * ```
+ */
+export declare function WithStateManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Type helper to extract the interface from the WithStateManager mixin
+ * This provides the type without duplicating method signatures
  */
-export declare function WithStateManager<TBase extends Constructor<RpgCommonPlayer & StateManagerDependencies>>(Base: TBase): Constructor<IStateManager> & TBase;
-export {};
+export type IStateManager = InstanceType<ReturnType<typeof WithStateManager>>;

package/dist/Player/VariableManager.d.ts

@@ -0,0 +1,30 @@
+import { PlayerCtor } from '@rpgjs/common';
+/**
+ * Variable Manager Mixin
+ *
+ * Provides variable management capabilities to any class. Variables are key-value
+ * pairs that can store any type of data associated with the player, such as
+ * quest progress, game flags, inventory state, and custom game data.
+ *
+ * @param Base - The base class to extend with variable management
+ * @returns Extended class with variable management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithVariableManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Variables are automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.setVariable('questCompleted', true);
+ * ```
+ */
+export declare function WithVariableManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Type helper to extract the interface from the WithVariableManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IVariableManager = InstanceType<ReturnType<typeof WithVariableManager>>;

package/dist/RpgServer.d.ts

@@ -210,19 +210,242 @@ 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 {
     /**
@@ -492,5 +715,8 @@ export interface RpgServer {
             doChangeServer(store: IStoreState, matchMaker: RpgMatchMaker, player: RpgPlayer): Promise<boolean> | boolean;
         };
     };
+    throttleSync?: number;
+    throttleStorage?: number;
+    sessionExpiryTime?: number;
 }
 export {};

package/dist/decorators/event.d.ts

@@ -0,0 +1,46 @@
+export declare 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 declare function EventData(options: EventOptions): (target: any) => void;

package/dist/decorators/map.d.ts

@@ -0,0 +1,177 @@
+export interface MapOptions {
+    /**
+     * Map identifier. Allows to go to the map (for example with player.changeMap())
+     *
+     * @prop {string} [id]
+     * @memberof MapData
+     * */
+    id?: string;
+    /**
+    * the path to the .tmx file (Tiled Map Editor)
+    *
+    * Remember to use `require()` function
+    *
+    * ```ts
+    * import { MapData, RpgMap } from '@rpgjs/server'
+    *
+    * @MapData({
+    *      id: 'town',
+    *      file: require('./tmx/town.tmx')
+    * })
+    * class TownMap extends RpgMap { }
+    * ```
+    * @prop {string} file
+    * @memberof MapData
+    * */
+    file: any;
+    /**
+     * The name of the map.
+     * @prop {string} [name]
+     * @memberof MapData
+     * */
+    name?: string;
+    /**
+    * Map events. This is an array containing `RpgEvent` classes.
+    * You can also give an object that will indicate the positions of the event on the map.
+    *
+    * ```ts
+    * import { MapData, RpgMap, EventData, RpgEvent } from '@rpgjs/server'
+    *
+    * @EventData({
+    *      name: 'Ev-1'
+    * })
+    * class NpcEvent extends RpgEvent { }
+    *
+    * @MapData({
+    *      id: 'medieval',
+    *      file: require('./tmx/town.tmx'),
+    *      events: [NpcEvent]
+    * })
+    * class TownMap extends RpgMap {}
+    * ```
+    *
+    * If the positions are not defined, the event will be placed on a Tiled Map Editor shape ([/guide/create-event.html#position-the-event-on-the-map](Guide)). Otherwise, it will be placed at `{x:0, y:0 }`
+    *
+    * You can give positions:
+    *
+    * ```ts
+    * events: [{ event: NpcEvent, x: 10, y: 30 }]
+    * ```
+    *
+    * @prop {Class of RpgEvent[] | { event: Class RpgEvent, x: number, y: number }} [events]
+    * @memberof MapData
+    * */
+    events?: {
+        event: any;
+        x: number;
+        y: number;
+    }[] | any[];
+    /**
+     * The sounds that will be played when the map is open. Sounds must be defined on the client side. Then, put the name of the sound identifier
+     *
+     * So, it is possible to play several sounds (in loop or not) on the card. You can put a background music (BGM) and a background noise (BGS) for example
+     *
+     *  ```ts
+     * sounds: ['my-bgm', 'my-bgs']
+     * ```
+     *
+     * And client side:
+     *
+     * ```ts
+     * import { Sound } from '@rpgjs/client'
+     *
+     * @Sound({
+     *      sounds: {
+     *          'my-bgm': require('./assets/bgm.ogg'),
+     *          'my-bgs': require('./assets/bgs.ogg')
+     *      },
+     *      loop: true
+     * })
+     * export class Sounds {}
+     * ```
+     *
+     * See [https://docs.rpgjs.dev/classes/sound.html#properties](RpgSound Decorator)
+     *
+     * @prop {Array<string>} [sounds]
+     * @memberof MapData
+     * */
+    sounds?: string[];
+    /**
+     * 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
+     *
+     * You must create the schema:
+     *
+     * ```ts
+     * import { MapData, RpgMap } from '@rpgjs/server'
+     *
+     * @MapData({
+     *      id: 'medieval',
+     *      file: require('./tmx/town.tmx'),
+     *      syncSchema: {
+     *          count: Number
+     *      }
+     * })
+     * export class TownMap extends RpgMap {
+     *      count: number = 0
+     *
+     *      onLoad() {}
+     *
+     *      onJoin() {
+     *          this.count++
+     *      }
+     *
+     *      onLeave(player) {
+     *          super.onLeave(player)
+     *          this.count--
+     *      }
+     * }
+     *
+     * ```
+     *
+     * If you want to change the scheme of players and events, consider overwriting the existing scheme
+     *
+     *  ```ts
+     * import { MapData, RpgMap, RpgPlayer } from '@rpgjs/server'
+     *
+     *
+     * declare module '@rpgjs/server' {
+     *  export interface RpgPlayer {
+     *      customProp: string
+     *  }
+     * }
+     *
+     * @MapData({
+     *      id: 'medieval',
+     *      file: require('./tmx/town.tmx'),
+     *      syncSchema: {
+     *          users: [
+     *              {
+     *                  customProp: String,
+     *                  ...RpgPlayer.schemas
+     *              }
+     *          ]
+     *      }
+     * })
+     * export class TownMap extends RpgMap {}
+     * ```
+     *
+     * The properties are called `users` and `events`. Their scheme is identical and defined in `RpgPlayer.schemas`. To write schematics, refer to the [documentation of the simple-room](https://github.com/RSamaium/simple-room) module
+     *
+     * @prop {object} [syncSchema]
+     * @memberof MapData
+     * */
+    syncSchema?: any;
+    /**
+     * Decreases the RAM of the map. In this case, some instructions will be different.
+     *
+     * `map.getTileByIndex()` will not return all tiles of an index but only the tile of the highest layer
+     *
+     * > You can also use the `low-memory` property in Tiled maps
+     *
+     * @prop {boolean} [lowMemory=false]
+     * @since 3.1.0
+     * @memberof MapData
+     * */
+    lowMemory?: boolean;
+}
+export declare function MapData(options: MapOptions): (target: any) => void;

package/dist/index.d.ts

@@ -4,6 +4,10 @@ export * from './RpgServer';
 export * from './core/setup';
 export * from './core/inject';
 export * from './Player/Player';
+export * from './Player/Components';
 export * from './module';
 export * from './rooms/map';
 export * from './presets';
+export * from '@signe/reactive';
+export * from './Gui';
+export { RpgShape, RpgModule } from '@rpgjs/common';