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

package/dist/Player/ParameterManager.d.ts

@@ -1,42 +1,371 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-export interface IWithParameterManager {
-    parameters: Map<string, any>;
+import { PlayerCtor } from '@rpgjs/common';
+/**
+ * Interface for Parameter Manager functionality
+ *
+ * Provides comprehensive parameter management including health points (HP), skill points (SP),
+ * experience and level progression, custom parameters, and parameter modifiers.
+ */
+export interface IParameterManager {
+    /**
+     * ```ts
+     * player.initialLevel = 5
+     * ```
+     *
+     * @title Set initial level
+     * @prop {number} player.initialLevel
+     * @default 1
+     * @memberof ParameterManager
+     * */
+    initialLevel: number;
+    /**
+     * ```ts
+     * player.finalLevel = 50
+     * ```
+     *
+     * @title Set final level
+     * @prop {number} player.finalLevel
+     * @default 99
+     * @memberof ParameterManager
+     * */
+    finalLevel: number;
+    /**
+     * With Object-based syntax, you can use following options:
+     * - `basis: number`
+     * - `extra: number`
+     * - `accelerationA: number`
+     * - `accelerationB: number`
+     * @title Change Experience Curve
+     * @prop {object} player.expCurve
+     * @default
+     *  ```ts
+     * {
+     *      basis: 30,
+     *      extra: 20,
+     *      accelerationA: 30,
+     *      accelerationB: 30
+     * }
+     * ```
+     * @memberof ParameterManager
+     * */
+    expCurve: {
+        basis: number;
+        extra: number;
+        accelerationA: number;
+        accelerationB: number;
+    };
+    /**
+     * Changes the health points
+     * - Cannot exceed the MaxHP parameter
+     * - Cannot have a negative value
+     * - If the value is 0, a hook named `onDead()` is called in the RpgPlayer class.
+     *
+     * ```ts
+     * player.hp = 100
+     * ```
+     * @title Change HP
+     * @prop {number} player.hp
+     * @default MaxHPValue
+     * @memberof ParameterManager
+     * */
     hp: number;
+    /**
+     * Changes the skill points
+     * - Cannot exceed the MaxSP parameter
+     * - Cannot have a negative value
+     *
+     * ```ts
+     * player.sp = 200
+     * ```
+     * @title Change SP
+     * @prop {number} player.sp
+     * @default MaxSPValue
+     * @memberof ParameterManager
+     * */
     sp: number;
+    /**
+     * Changing the player's experience.
+     * ```ts
+     * player.exp += 100
+     * ```
+     *
+     * Levels are based on the experience curve.
+     *
+     * ```ts
+     * console.log(player.level) // 1
+     * console.log(player.expForNextlevel) // 150
+     * player.exp += 160
+     * console.log(player.level) // 2
+     * ```
+     *
+     * @title Change Experience
+     * @prop {number} player.exp
+     * @default 0
+     * @memberof ParameterManager
+     * */
     exp: number;
+    /**
+     * Changing the player's level.
+     *
+     * ```ts
+     * player.level += 1
+     * ```
+     *
+     * The level will be between the initial level given by the `initialLevel` and final level given by `finalLevel`
+     *
+     * ```ts
+     * player.finalLevel = 50
+     * player.level = 60
+     * console.log(player.level) // 50
+     * ```
+     *
+     * @title Change Level
+     * @prop {number} player.level
+     * @default 1
+     * @memberof ParameterManager
+     * */
     level: number;
-    expForNextlevel: number;
-    param: {
+    /**
+     * ```ts
+     * console.log(player.expForNextlevel) // 150
+     * ```
+     * @title Experience for next level ?
+     * @prop {number} player.expForNextlevel
+     * @readonly
+     * @memberof ParameterManager
+     * */
+    readonly expForNextlevel: number;
+    /**
+     * Read the value of a parameter. Put the name of the parameter.
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * console.log(player.param[MAXHP])
+     * ```
+     *
+     * > Possible to use the `player.getParamValue(name)` method instead
+     * @title Get Param Value
+     * @prop {object} player.param
+     * @readonly
+     * @memberof ParameterManager
+     * */
+    readonly param: {
         [key: string]: number;
     };
+    /**
+     * Direct parameter modifiers (reactive signal)
+     *
+     * > It is important that these parameters have been created beforehand with the `addParameter()` method.
+     * > By default, the following settings have been created:
+     * - maxhp
+     * - maxsp
+     * - str
+     * - int
+     * - dex
+     * - agi
+     *
+     * **Object Key**
+     *
+     * The key of the object is the name of the parameter
+     *
+     * > The good practice is to retrieve the name coming from a constant
+     *
+     * **Object Value**
+     *
+     * The value of the key is an object containing:
+     * ```
+     * {
+     *   value: number,
+     *   rate: number
+     * }
+     * ```
+     *
+     * - value: Adds a number to the parameter
+     * - rate: Adds a rate to the parameter
+     *
+     * > Note that you can put both (value and rate)
+     *
+     * This property uses reactive signals - changes automatically trigger parameter recalculation.
+     * The final parameter values in `param` include aggregated modifiers from equipment, states, etc.
+     *
+     * @prop {Object} [paramsModifier]
+     * @example
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * // Set direct modifiers (reactive)
+     * player.paramsModifier = {
+     *      [MAXHP]: {
+     *          value: 100
+     *      }
+     * }
+     *
+     * // Parameters automatically recalculate
+     * console.log(player.param[MAXHP]); // Updated value
+     * ```
+     *
+     * @title Set Parameters Modifier
+     * @prop {object} paramsModifier
+     * @memberof ParameterManager
+     * */
     paramsModifier: {
         [key: string]: {
             value?: number;
             rate?: number;
         };
     };
+    /**
+     * Get or set the parameters object
+     *
+     * @prop {object} parameters
+     * @memberof ParameterManager
+     */
+    parameters: {
+        [key: string]: {
+            start: number;
+            end: number;
+        };
+    };
+    /**
+     * Get the value of a specific parameter by name
+     *
+     * @deprecated Use `player.param[name]` instead for better reactivity
+     * @param name - The name of the parameter to get
+     * @returns The calculated parameter value
+     *
+     * @example
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * // Preferred way (reactive)
+     * const maxHp = player.param[MAXHP];
+     *
+     * // Legacy way (still works)
+     * const maxHp = player.getParamValue(MAXHP);
+     * ```
+     */
+    getParamValue(name: string): number;
+    /**
+     * Give a new parameter. Give a start value and an end value.
+     * The start value will be set to the level set at `player.initialLevel` and the end value will be linked to the level set at `player.finalLevel`.
+     *
+     * ```ts
+     * const SPEED = 'speed'
+     *
+     * player.addParameter(SPEED, {
+     *     start: 10,
+     *     end: 100
+     * })
+     *
+     * player.param[SPEED] // 10
+     * player.level += 5
+     * player.param[SPEED] // 14
+     * ```
+     *
+     * @title Add custom parameters
+     * @method player.addParameter(name,curve)
+     * @param {string} name - The name of the parameter
+     * @param {object} curve - Scheme of the object: { start: number, end: number }
+     * @returns {void}
+     * @memberof ParameterManager
+     * */
+    addParameter(name: string, curve: {
+        start: number;
+        end: number;
+    }): void;
+    /**
+     * Gives back in percentage of health points to skill points
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP } = Presets
+     *
+     * console.log(player.param[MAXHP]) // 800
+     * player.hp = 100
+     * player.recovery({ hp: 0.5 }) // = 800 * 0.5
+     * console.log(player.hp) // 400
+     * ```
+     *
+     * @title Recovery HP and/or SP
+     * @method player.recovery(params)
+     * @param {object} params - Scheme of the object: { hp: number, sp: number }. The values of the numbers must be in 0 and 1
+     * @returns {void}
+     * @memberof ParameterManager
+     * */
+    recovery(params: {
+        hp?: number;
+        sp?: number;
+    }): void;
+    /**
+     * restores all HP and SP
+     *
+     * ```ts
+     * import { Presets } from '@rpgjs/server'
+     *
+     * const { MAXHP, MAXSP } = Presets
+     *
+     * console.log(player.param[MAXHP], player.param[MAXSP]) // 800, 230
+     * player.hp = 100
+     * player.sp = 0
+     * player.allRecovery()
+     * console.log(player.hp, player.sp) // 800, 230
+     * ```
+     *
+     * @title All Recovery
+     * @method player.allRecovery()
+     * @returns {void}
+     * @memberof ParameterManager
+     * */
+    allRecovery(): void;
 }
 /**
- * Mixin that adds parameter management functionality to a player class.
+ * Parameter Manager Mixin with Reactive Signals
+ *
+ * Provides comprehensive parameter management functionality using reactive signals from `@signe/reactive`.
+ * This mixin handles health points (HP), skill points (SP), experience and level progression,
+ * custom parameters, and parameter modifiers with automatic reactivity.
  *
- * This mixin provides comprehensive parameter management including:
- * - Health Points (HP) and Skill Points (SP) management
- * - Experience and level progression system
- * - Custom parameter creation and modification
- * - Parameter modifiers for temporary stat changes
+ * **Key Features:**
+ * - ✨ **Reactive Parameters**: All parameters automatically recalculate when level or modifiers change
+ * - 🚀 **Performance Optimized**: Uses computed signals to avoid unnecessary recalculations
+ * - 🔄 **Real-time Updates**: Changes propagate automatically throughout the system
+ * - 🎯 **Type Safe**: Full TypeScript support with proper type inference
  *
  * @template TBase - The base class constructor type
- * @param Base - The base class to extend
- * @returns A new class that extends the base with parameter management capabilities
+ * @param Base - The base class to extend with parameter management
+ * @returns Extended class with reactive parameter management methods
  *
  * @example
  * ```ts
  * class MyPlayer extends WithParameterManager(BasePlayer) {
  *   constructor() {
  *     super();
+ *
+ *     // Add custom parameters
  *     this.addParameter('strength', { start: 10, end: 100 });
+ *     this.addParameter('magic', { start: 5, end: 80 });
  *   }
  * }
+ *
+ * const player = new MyPlayer();
+ *
+ * // Reactive parameter updates
+ * player.level = 5;
+ * console.log(player.param.strength); // Automatically calculated for level 5
+ *
+ * // Reactive modifiers
+ * player.paramsModifier = {
+ *   [MAXHP]: { value: 100, rate: 1.2 }
+ * };
+ * console.log(player.param[MAXHP]); // Automatically includes modifiers
  * ```
  */
-export declare function WithParameterManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase): TBase & Constructor<IWithParameterManager>;
+export declare function WithParameterManager<TBase extends PlayerCtor>(Base: TBase): TBase;

package/dist/Player/Player.d.ts

@@ -1,4 +1,4 @@
-import { RpgCommonPlayer, ShowAnimationParams, Constructor, ZoneOptions } from '@rpgjs/common';
+import { Hooks, RpgCommonPlayer, Constructor, Direction, AttachShapeOptions, RpgShape } from '@rpgjs/common';
 import { IComponentManager } from './ComponentManager';
 import { RpgMap } from '../rooms/map';
 import { Context } from '@signe/di';
@@ -6,19 +6,66 @@ 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';
+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';
 declare const RpgPlayer_base: Constructor<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;
     context?: Context;
     conn: MockConnection | null;
+    touchSide: boolean;
+    /** Internal: Shapes attached to this player */
+    private _attachedShapes;
+    /** Internal: Shapes where this player is currently located */
+    private _inShapes;
+    /** Last processed client input timestamp for reconciliation */
+    lastProcessedInputTs: number;
+    /** Last processed client input frame for reconciliation with server tick */
+    _lastFramePositions: {
+        frame: number;
+        position: {
+            x: number;
+            y: number;
+            direction: Direction;
+        };
+        serverTick?: number;
+    } | null;
+    frames: {
+        x: number;
+        y: number;
+        ts: number;
+    }[];
     events: import('@signe/reactive').WritableArraySignal<RpgEvent[]>;
     constructor();
+    _onInit(): void;
+    get hooks(): Hooks;
+    applyFrames(): void;
     execMethod(method: string, methodData?: any[], target?: any): Promise<any>;
     /**
      * Change the map for this player
@@ -41,13 +88,63 @@ export declare class RpgPlayer extends RpgPlayer_base {
         y: number;
         z?: number;
     } | string): Promise<any | null | boolean>;
+    /**
+     * Auto change map when player touches map borders
+     *
+     * This method checks if the player touches the current map borders
+     * and automatically performs a change to the adjacent map if it exists.
+     *
+     * @param nextPosition - The next position of the player
+     * @returns Promise<boolean> - true if a map change occurred
+     *
+     * @example
+     * ```ts
+     * // Called automatically by the movement system
+     * const changed = await player.autoChangeMap({ x: newX, y: newY });
+     * if (changed) {
+     *   console.log('Player changed map automatically');
+     * }
+     * ```
+     */
+    autoChangeMap(nextPosition: {
+        x: number;
+        y: number;
+    }, forcedDirection?: any): Promise<boolean>;
     teleport(positions: {
         x: number;
         y: number;
     }): Promise<false | undefined>;
     getCurrentMap<T extends RpgMap = RpgMap>(): T | null;
     emit(type: string, value?: any): void;
-    showAnimation(params: ShowAnimationParams): void;
+    save(): Promise<string>;
+    load(snapshot: string): Promise<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.
@@ -60,14 +157,175 @@ export declare class RpgPlayer extends RpgPlayer_base {
     syncChanges(): void;
     databaseById(id: string): any;
     private _eventChanges;
-    attachShape(id: string, options: ZoneOptions): void;
-    broadcastEffect(id: string, params: any): void;
+    /**
+     * Attach a zone shape to this player using the physic zone system
+     *
+     * This method creates a zone attached to the player's entity in the physics engine.
+     * The zone can be circular or cone-shaped and will detect other entities (players/events)
+     * entering or exiting the zone.
+     *
+     * @param id - Optional zone identifier. If not provided, a unique ID will be generated
+     * @param options - Zone configuration options
+     *
+     * @example
+     * ```ts
+     * // Create a circular detection zone
+     * player.attachShape("vision", {
+     *   radius: 150,
+     *   angle: 360,
+     * });
+     *
+     * // Create a cone-shaped vision zone
+     * player.attachShape("vision", {
+     *   radius: 200,
+     *   angle: 120,
+     *   direction: Direction.Right,
+     *   limitedByWalls: true,
+     * });
+     *
+     * // Create a zone with width/height (radius calculated automatically)
+     * player.attachShape({
+     *   width: 100,
+     *   height: 100,
+     *   positioning: "center",
+     * });
+     * ```
+     */
+    attachShape(idOrOptions: string | AttachShapeOptions, options?: AttachShapeOptions): RpgShape | undefined;
+    /**
+     * Get all shapes attached to this player
+     *
+     * Returns all shapes that were created using `attachShape()` on this player.
+     *
+     * @returns Array of RpgShape instances attached to this player
+     *
+     * @example
+     * ```ts
+     * player.attachShape("vision", { radius: 150 });
+     * player.attachShape("detection", { radius: 100 });
+     *
+     * const shapes = player.getShapes();
+     * console.log(shapes.length); // 2
+     * ```
+     */
+    getShapes(): RpgShape[];
+    /**
+     * Get all shapes where this player is currently located
+     *
+     * Returns all shapes (from any player/event) where this player is currently inside.
+     * This is updated automatically when the player enters or exits shapes.
+     *
+     * @returns Array of RpgShape instances where this player is located
+     *
+     * @example
+     * ```ts
+     * // Another player has a detection zone
+     * otherPlayer.attachShape("detection", { radius: 200 });
+     *
+     * // Check if this player is in any shape
+     * const inShapes = player.getInShapes();
+     * if (inShapes.length > 0) {
+     *   console.log("Player is being detected!");
+     * }
+     * ```
+     */
+    getInShapes(): RpgShape[];
+    /**
+     * 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;
     showHit(text: string): void;
+    /**
+     * Play a sound on the client side for this player only
+     *
+     * This method emits an event to play a sound only for this specific player.
+     * The sound must be defined on the client side (in the client module configuration).
+     *
+     * ## Design
+     *
+     * The sound is sent only to this player's client connection, making it ideal
+     * for personal feedback sounds like UI interactions, notifications, or personal
+     * achievements. For map-wide sounds that all players should hear, use `map.playSound()` instead.
+     *
+     * @param soundId - Sound identifier, defined on the client side
+     * @param options - Optional sound configuration
+     * @param options.volume - Volume level (0.0 to 1.0, default: 1.0)
+     * @param options.loop - Whether the sound should loop (default: false)
+     *
+     * @example
+     * ```ts
+     * // Play a sound for this player only (default behavior)
+     * player.playSound("item-pickup");
+     *
+     * // Play a sound with volume and loop
+     * player.playSound("background-music", {
+     *   volume: 0.5,
+     *   loop: true
+     * });
+     *
+     * // Play a notification sound at low volume
+     * player.playSound("notification", { volume: 0.3 });
+     * ```
+     */
+    playSound(soundId: string, options?: {
+        volume?: number;
+        loop?: boolean;
+    }): void;
+    /**
+     * Stop a sound that is currently playing for this player
+     *
+     * This method stops a sound that was previously started with `playSound()`.
+     * The sound must be defined on the client side.
+     *
+     * @param soundId - Sound identifier to stop
+     *
+     * @example
+     * ```ts
+     * // Start a looping background music
+     * player.playSound("background-music", { loop: true });
+     *
+     * // Later, stop it
+     * player.stopSound("background-music");
+     * ```
+     */
+    stopSound(soundId: string): void;
+    /**
+     * Set the sync schema for the map
+     * @param schema - The schema to set
+     */
+    setSync(schema: any): 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 {};