@rpgjs/server 5.0.0-alpha.0 → 5.0.0-alpha.10

package/dist/Player/Player.d.ts

@@ -1,4 +1,4 @@
-import { RpgCommonPlayer, ShowAnimationParams, Constructor, ZoneOptions } from '@rpgjs/common';
+import { RpgCommonPlayer } from '@rpgjs/common';
 import { IComponentManager } from './ComponentManager';
 import { RpgMap } from '../rooms/map';
 import { Context } from '@signe/di';
@@ -6,12 +6,43 @@ import { IGuiManager } from './GuiManager';
 import { MockConnection } from '@signe/room';
 import { IMoveManager } from './MoveManager';
 import { IGoldManager } from './GoldManager';
-import { IWithVariableManager } from './VariableManager';
-import { IWithParameterManager } from './ParameterManager';
-import { IWithSkillManager } from './SkillManager';
-declare const RpgPlayer_base: Constructor<RpgCommonPlayer>;
+import { IVariableManager } from './VariableManager';
+import { IParameterManager } from './ParameterManager';
+import { IItemManager } from './ItemManager';
+import { IEffectManager } from './EffectManager';
+import { IElementManager } from './ElementManager';
+import { ISkillManager } from './SkillManager';
+import { IBattleManager } from './BattleManager';
+import { IClassManager } from './ClassManager';
+import { IStateManager } from './StateManager';
+interface ZoneOptions {
+    x?: number;
+    y?: number;
+    radius: number;
+    angle?: number;
+    direction?: any;
+    linkedTo?: string;
+    limitedByWalls?: boolean;
+}
+declare const RpgPlayer_base: typeof RpgCommonPlayer;
 /**
  * RPG Player class with component management capabilities
+ *
+ * Combines all player mixins to provide a complete player implementation
+ * with graphics, movement, inventory, skills, and battle capabilities.
+ *
+ * @example
+ * ```ts
+ * // Create a new player
+ * const player = new RpgPlayer();
+ *
+ * // Set player graphics
+ * player.setGraphic("hero");
+ *
+ * // Add parameters and items
+ * player.addParameter("strength", { start: 10, end: 100 });
+ * player.addItem(sword);
+ * ```
  */
 export declare class RpgPlayer extends RpgPlayer_base {
     map: RpgMap | null;
@@ -47,7 +78,33 @@ export declare class RpgPlayer extends RpgPlayer_base {
     }): Promise<false | undefined>;
     getCurrentMap<T extends RpgMap = RpgMap>(): T | null;
     emit(type: string, value?: any): void;
-    showAnimation(params: ShowAnimationParams): void;
+    /**
+     * Set the current animation of the player's sprite
+     *
+     * This method changes the animation state of the player's current sprite.
+     * It's used to trigger character animations like attack, skill, or custom movements.
+     * When `nbTimes` is set to a finite number, the animation will play that many times
+     * before returning to the previous animation state.
+     *
+     * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+     * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+     *
+     * @example
+     * ```ts
+     * // Set continuous walk animation
+     * player.setAnimation('walk');
+     *
+     * // Play attack animation 3 times then return to previous state
+     * player.setAnimation('attack', 3);
+     *
+     * // Play skill animation once
+     * player.setAnimation('skill', 1);
+     *
+     * // Set idle/stand animation
+     * player.setAnimation('stand');
+     * ```
+     */
+    setAnimation(animationName: string, nbTimes?: number): void;
     /**
      * Run the change detection cycle. Normally, as soon as a hook is called in a class, the cycle is started. But you can start it manually
      * The method calls the `onChanges` method on events and synchronizes all map data with the client.
@@ -61,13 +118,71 @@ export declare class RpgPlayer extends RpgPlayer_base {
     databaseById(id: string): any;
     private _eventChanges;
     attachShape(id: string, options: ZoneOptions): void;
-    broadcastEffect(id: string, params: any): void;
+    /**
+     * Show a temporary component animation on this player
+     *
+     * This method broadcasts a component animation to all clients, allowing
+     * temporary visual effects like hit indicators, spell effects, or status animations
+     * to be displayed on the player.
+     *
+     * @param id - The ID of the component animation to display
+     * @param params - Parameters to pass to the component animation
+     *
+     * @example
+     * ```ts
+     * // Show a hit animation with damage text
+     * player.showComponentAnimation("hit", {
+     *   text: "150",
+     *   color: "red"
+     * });
+     *
+     * // Show a heal animation
+     * player.showComponentAnimation("heal", {
+     *   amount: 50
+     * });
+     * ```
+     */
+    showComponentAnimation(id: string, params: any): void;
+    /**
+     * Display a spritesheet animation on the player
+     *
+     * This method displays a temporary visual animation using a spritesheet.
+     * The animation can either be displayed as an overlay on the player or replace
+     * the player's current graphic temporarily. This is useful for spell effects,
+     * transformations, or other visual feedback that uses predefined spritesheets.
+     *
+     * @param graphic - The ID of the spritesheet to use for the animation
+     * @param animationName - The name of the animation within the spritesheet (default: 'default')
+     * @param replaceGraphic - Whether to replace the player's sprite with the animation (default: false)
+     *
+     * @example
+     * ```ts
+     * // Show explosion animation as overlay on player
+     * player.showAnimation("explosion");
+     *
+     * // Show specific spell effect animation
+     * player.showAnimation("spell-effects", "fireball");
+     *
+     * // Transform player graphic temporarily with animation
+     * player.showAnimation("transformation", "werewolf", true);
+     *
+     * // Show healing effect on player
+     * player.showAnimation("healing-effects", "holy-light");
+     * ```
+     */
+    showAnimation(graphic: string, animationName?: string, replaceGraphic?: boolean): void;
     showHit(text: string): void;
 }
 export declare class RpgEvent extends RpgPlayer {
     execMethod(methodName: string, methodData?: any[], instance?: this): Promise<any>;
     remove(): void;
 }
-export interface RpgPlayer extends RpgCommonPlayer, IComponentManager, IGuiManager, IMoveManager, IGoldManager, IWithVariableManager, IWithParameterManager, IWithSkillManager {
+/**
+ * Interface extension for RpgPlayer
+ *
+ * Extends the RpgPlayer class with additional interfaces from mixins.
+ * This provides proper TypeScript support for all mixin methods and properties.
+ */
+export interface RpgPlayer extends IVariableManager, IMoveManager, IGoldManager, IComponentManager, IGuiManager, IItemManager, IEffectManager, IParameterManager, IElementManager, ISkillManager, IBattleManager, IClassManager, IStateManager {
 }
 export {};

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 {
     /**