@rpgjs/server 5.0.0-alpha.4 → 5.0.0-alpha.41

package/dist/Player/MoveManager.d.ts

@@ -1,48 +1,54 @@
-import { Constructor, RpgCommonPlayer, Direction, MovementStrategy, ProjectileType } from '@rpgjs/common';
+import { PlayerCtor, ProjectileType, RpgCommonPlayer, Direction, MovementStrategy, MovementOptions } from '../../../common/src';
 import { RpgPlayer } from './Player';
-export interface IMoveManager {
-    addMovement(strategy: MovementStrategy): void;
-    removeMovement(strategy: MovementStrategy): boolean;
-    clearMovements(): void;
-    hasActiveMovements(): boolean;
-    getActiveMovements(): MovementStrategy[];
-    moveTo(target: RpgCommonPlayer | {
-        x: number;
-        y: number;
-    }): void;
-    stopMoveTo(): void;
-    dash(direction: {
-        x: number;
-        y: number;
-    }, speed?: number, duration?: number): void;
-    knockback(direction: {
-        x: number;
-        y: number;
-    }, force?: number, duration?: number): void;
-    followPath(waypoints: Array<{
-        x: number;
-        y: number;
-    }>, speed?: number, loop?: boolean): void;
-    oscillate(direction: {
-        x: number;
-        y: number;
-    }, amplitude?: number, period?: number): void;
-    applyIceMovement(direction: {
+type CallbackTileMove = (player: RpgPlayer, map: any) => Direction[];
+type CallbackTurnMove = (player: RpgPlayer, map: any) => string;
+type Routes = (string | Promise<any> | Direction | Direction[] | Function)[];
+export type { MovementOptions };
+/**
+ * Options for moveRoutes method
+ */
+export interface MoveRoutesOptions {
+    /**
+     * Callback function called when the player gets stuck (cannot move towards target)
+     *
+     * This callback is triggered when the player is trying to move but cannot make progress
+     * towards the target position, typically due to obstacles or collisions.
+     *
+     * @param player - The player instance that is stuck
+     * @param target - The target position the player was trying to reach
+     * @param currentPosition - The current position of the player
+     * @returns If true, the route will continue; if false, the route will be cancelled
+     *
+     * @example
+     * ```ts
+     * await player.moveRoutes([Move.right()], {
+     *   onStuck: (player, target, currentPos) => {
+     *     console.log('Player is stuck!');
+     *     return false; // Cancel the route
+     *   }
+     * });
+     * ```
+     */
+    onStuck?: (player: RpgPlayer, target: {
         x: number;
         y: number;
-    }, maxSpeed?: number): void;
-    shootProjectile(type: ProjectileType, direction: {
+    }, currentPosition: {
         x: number;
         y: number;
-    }, speed?: number): void;
-    moveRoutes(routes: Routes): Promise<boolean>;
-    infiniteMoveRoute(routes: Routes): void;
-    breakRoutes(force?: boolean): void;
-    replayRoutes(): void;
+    }) => boolean | void;
+    /**
+     * Time in milliseconds to wait before considering the player stuck (default: 500ms)
+     *
+     * The player must be unable to make progress for this duration before onStuck is called.
+     */
+    stuckTimeout?: number;
+    /**
+     * Minimum distance change in pixels to consider movement progress (default: 1 pixel)
+     *
+     * If the player moves less than this distance over the stuckTimeout period, they are considered stuck.
+     */
+    stuckThreshold?: number;
 }
-type CallbackTileMove = (player: RpgPlayer, map: any) => Direction[];
-type CallbackTurnMove = (player: RpgPlayer, map: any) => string;
-type Routes = (string | Promise<any> | Direction | Direction[] | Function)[];
 export declare enum Frequency {
     Lowest = 600,
     Lower = 400,
@@ -61,34 +67,39 @@ export declare enum Speed {
     Faster = 7,
     Fastest = 10
 }
-/**
-* @title Move
-* @enum {Object}
-*
-* Move.right(repeat=1) | Movement of a number of pixels on the right
-* Move.left(repeat=1) | Movement of a number of pixels on the left
-* Move.up(repeat=1) | Movement of a number of pixels on the up
-* Move.down(repeat=1) | Movement of a number of pixels on the down
-* Move.random(repeat=1) | Movement of a number of pixels in a random direction
-* Move.towardPlayer(player, repeat=1) | Moves a number of pixels in the direction of the designated player
-* Move.awayFromPlayer(player, repeat=1) | Moves a number of pixels in the opposite direction of the designated player
-* Move.tileRight(repeat=1) | Movement of a number of tiles on the right
-* Move.tileLeft(repeat=1) | Movement of a number of tiles on the left
-* Move.tileUp(repeat=1) | Movement of a number of tiles on the up
-* Move.tileDown(repeat=1) | Movement of a number of tiles on the down
-* Move.tileRandom(repeat=1) | Movement of a number of tiles in a random direction
-* Move.tileTowardPlayer(player, repeat=1) | Moves a number of tiles in the direction of the designated player
-* Move.tileAwayFromPlayer(player, repeat=1) | Moves a number of tiles in the opposite direction of the designated player
-* Move.turnRight() | Turn to the right
-* Move.turnLeft() | Turn to the left
-* Move.turnUp() | Turn to the up
-* Move.turnDown() | Turn to the down
-* Move.turnRandom() | Turn to random direction
-* Move.turnAwayFromPlayer(player) | Turns in the opposite direction of the designated player
-* Move.turnTowardPlayer(player) | Turns in the direction of the designated player
-* @memberof Move
-* */
 declare class MoveList {
+    private static perlinNoise;
+    private static randomCounter;
+    private static callCounter;
+    private static playerMoveStates;
+    private static readonly STUCK_THRESHOLD;
+    /**
+     * Clears the movement state for a specific player
+     *
+     * Should be called when a player changes map or is destroyed to prevent
+     * memory leaks and stale stuck detection data.
+     *
+     * @param playerId - The ID of the player to clear state for
+     *
+     * @example
+     * ```ts
+     * // Clear state when player leaves map
+     * Move.clearPlayerState(player.id);
+     * ```
+     */
+    static clearPlayerState(playerId: string): void;
+    /**
+     * Clears all player movement states
+     *
+     * Useful for cleanup during server shutdown or when resetting game state.
+     *
+     * @example
+     * ```ts
+     * // Clear all states on server shutdown
+     * Move.clearAllPlayerStates();
+     * ```
+     */
+    static clearAllPlayerStates(): void;
     repeatMove(direction: Direction, repeat: number): Direction[];
     private repeatTileMove;
     right(repeat?: number): Direction[];
@@ -129,7 +140,7 @@ export declare const Move: MoveList;
  * - **Strategy Management**: Add, remove, and query movement strategies
  * - **Predefined Movements**: Quick access to common movement patterns
  * - **Composite Movements**: Combine multiple strategies
- * - **Physics Integration**: Seamless integration with Matter.js physics
+ * - **Physics Integration**: Seamless integration with the deterministic @rpgjs/physic engine
  *
  * ## Available Movement Strategies
  * - `LinearMove`: Constant velocity movement
@@ -173,5 +184,249 @@ export declare const Move: MoveList;
  * }
  * ```
  */
-export declare function WithMoveManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase): Constructor<IMoveManager> & TBase;
-export {};
+/**
+ * Move Manager Mixin
+ *
+ * Provides comprehensive movement management capabilities to any class. This mixin handles
+ * various types of movement including pathfinding, physics-based movement, route following,
+ * and advanced movement strategies like dashing, knockback, and projectile movement.
+ *
+ * @param Base - The base class to extend with movement management
+ * @returns Extended class with movement management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithMoveManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     this.frequency = Frequency.High;
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.moveTo({ x: 100, y: 100 });
+ * player.dash({ x: 1, y: 0 }, 8, 200);
+ * ```
+ */
+export declare function WithMoveManager<TBase extends PlayerCtor>(Base: TBase): PlayerCtor;
+/**
+ * Interface for Move Manager functionality
+ *
+ * Provides comprehensive movement management capabilities including pathfinding,
+ * physics-based movement, route following, and advanced movement strategies.
+ * This interface defines the public API of the MoveManager mixin.
+ */
+export interface IMoveManager {
+    /**
+     * Whether the player passes through other players
+     *
+     * When `true`, the player can walk through other player entities without collision.
+     * This is useful for busy areas where players shouldn't block each other.
+     *
+     * @default true
+     *
+     * @example
+     * ```ts
+     * // Disable player-to-player collision
+     * player.throughOtherPlayer = true;
+     *
+     * // Enable player-to-player collision
+     * player.throughOtherPlayer = false;
+     * ```
+     */
+    throughOtherPlayer: boolean;
+    /**
+     * Whether the player goes through all characters (players and events)
+     *
+     * When `true`, the player can walk through all character entities (both players and events)
+     * without collision. Walls and obstacles still block movement.
+     * This takes precedence over `throughOtherPlayer` and `throughEvent`.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // Enable ghost mode - pass through all characters
+     * player.through = true;
+     *
+     * // Disable ghost mode
+     * player.through = false;
+     * ```
+     */
+    through: boolean;
+    /**
+     * Whether the player passes through events (NPCs, objects)
+     *
+     * When `true`, the player can walk through event entities without collision.
+     * This is useful for NPCs that shouldn't block player movement.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // Allow passing through events
+     * player.throughEvent = true;
+     *
+     * // Block passage through events
+     * player.throughEvent = false;
+     * ```
+     */
+    throughEvent: boolean;
+    /** Frequency for movement timing (milliseconds between movements) */
+    frequency: number;
+    /** Whether direction changes are locked (prevents automatic direction changes) */
+    directionFixed: boolean;
+    /** Whether animation changes are locked (prevents automatic animation changes) */
+    animationFixed: boolean;
+    /**
+     * Add a custom movement strategy to this entity
+     *
+     * Returns a Promise that resolves when the movement completes.
+     *
+     * @param strategy - The movement strategy to add
+     * @param options - Optional callbacks for movement lifecycle events
+     * @returns Promise that resolves when the movement completes
+     */
+    addMovement(strategy: MovementStrategy, options?: MovementOptions): Promise<void>;
+    /**
+     * Remove a specific movement strategy from this entity
+     *
+     * @param strategy - The strategy instance to remove
+     * @returns True if the strategy was found and removed
+     */
+    removeMovement(strategy: MovementStrategy): boolean;
+    /**
+     * Remove all active movement strategies from this entity
+     */
+    clearMovements(): void;
+    /**
+     * Check if this entity has any active movement strategies
+     *
+     * @returns True if entity has active movements
+     */
+    hasActiveMovements(): boolean;
+    /**
+     * Get all active movement strategies for this entity
+     *
+     * @returns Array of active movement strategies
+     */
+    getActiveMovements(): MovementStrategy[];
+    /**
+     * Move toward a target player or position using AI pathfinding
+     *
+     * @param target - Target player or position to move toward
+     */
+    moveTo(target: RpgCommonPlayer | {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Stop the current moveTo behavior
+     */
+    stopMoveTo(): void;
+    /**
+     * Perform a dash movement in the specified direction
+     *
+     * The total speed is calculated by adding the player's base speed to the additional speed.
+     * Returns a Promise that resolves when the dash completes.
+     *
+     * @param direction - Normalized direction vector
+     * @param additionalSpeed - Extra speed added on top of base speed (default: 4)
+     * @param duration - Duration in milliseconds (default: 200)
+     * @param options - Optional callbacks for movement lifecycle events
+     * @returns Promise that resolves when the dash completes
+     */
+    dash(direction: {
+        x: number;
+        y: number;
+    }, additionalSpeed?: number, duration?: number, options?: MovementOptions): Promise<void>;
+    /**
+     * Apply knockback effect in the specified direction
+     *
+     * The force is scaled by the player's base speed for consistent behavior.
+     * Returns a Promise that resolves when the knockback completes.
+     *
+     * @param direction - Normalized direction vector
+     * @param force - Force multiplier applied to base speed (default: 5)
+     * @param duration - Duration in milliseconds (default: 300)
+     * @param options - Optional callbacks for movement lifecycle events
+     * @returns Promise that resolves when the knockback completes
+     */
+    knockback(direction: {
+        x: number;
+        y: number;
+    }, force?: number, duration?: number, options?: MovementOptions): Promise<void>;
+    /**
+     * Follow a sequence of waypoints
+     *
+     * Speed is calculated from the player's base speed multiplied by the speedMultiplier.
+     *
+     * @param waypoints - Array of x,y positions to follow
+     * @param speedMultiplier - Multiplier applied to base speed (default: 0.5)
+     * @param loop - Whether to loop back to start (default: false)
+     */
+    followPath(waypoints: Array<{
+        x: number;
+        y: number;
+    }>, speedMultiplier?: number, loop?: boolean): void;
+    /**
+     * Apply oscillating movement pattern
+     *
+     * @param direction - Primary oscillation axis (normalized)
+     * @param amplitude - Maximum distance from center (default: 50)
+     * @param period - Time for complete cycle in ms (default: 2000)
+     */
+    oscillate(direction: {
+        x: number;
+        y: number;
+    }, amplitude?: number, period?: number): void;
+    /**
+     * Apply ice movement physics
+     *
+     * Max speed is calculated from the player's base speed multiplied by the speedFactor.
+     *
+     * @param direction - Target movement direction
+     * @param speedFactor - Factor multiplied with base speed for max speed (default: 1.0)
+     */
+    applyIceMovement(direction: {
+        x: number;
+        y: number;
+    }, speedFactor?: number): void;
+    /**
+     * Shoot a projectile in the specified direction
+     *
+     * Speed is calculated from the player's base speed multiplied by the speedFactor.
+     *
+     * @param type - Type of projectile trajectory
+     * @param direction - Normalized direction vector
+     * @param speedFactor - Factor multiplied with base speed (default: 50)
+     */
+    shootProjectile(type: ProjectileType, direction: {
+        x: number;
+        y: number;
+    }, speedFactor?: number): void;
+    /**
+     * Give an itinerary to follow using movement strategies
+     *
+     * @param routes - Array of movement instructions to execute
+     * @param options - Optional configuration including onStuck callback
+     * @returns Promise that resolves when all routes are completed
+     */
+    moveRoutes(routes: Routes, options?: MoveRoutesOptions): Promise<boolean>;
+    /**
+     * Give a path that repeats itself in a loop to a character
+     *
+     * @param routes - Array of movement instructions to repeat infinitely
+     */
+    infiniteMoveRoute(routes: Routes): void;
+    /**
+     * Stop an infinite movement
+     *
+     * @param force - Forces the stop of the infinite movement immediately
+     */
+    breakRoutes(force?: boolean): void;
+    /**
+     * Replay an infinite movement
+     */
+    replayRoutes(): void;
+}