@rpgjs/server 5.0.0-alpha.26 → 5.0.0-alpha.28

package/src/Player/MoveManager.ts

@@ -2,6 +2,7 @@ import { PlayerCtor, ProjectileType } from "@rpgjs/common";
 import { RpgCommonPlayer, Direction, Entity } from "@rpgjs/common";
 import {
   MovementStrategy,
+  MovementOptions,
   LinearMove,
   Dash,
   Knockback,
@@ -14,12 +15,81 @@ import {
   ProjectileMovement,
   random,
   isFunction,
-  capitalize
+  capitalize,
+  PerlinNoise2D
 } from "@rpgjs/common";
+import type { MovementBody } from "@rpgjs/physic";
 import { RpgMap } from "../rooms/map";
-import { Observable, Subscription, takeUntil, Subject, tap, switchMap, of, from } from 'rxjs';
+import { Observable, Subscription, takeUntil, Subject, tap, switchMap, of, from, take } from 'rxjs';
 import { RpgPlayer } from "./Player";
 
+/**
+ * Additive knockback strategy that **adds** an impulse-like velocity on top of the
+ * current velocity, instead of overwriting it.
+ *
+ * This is designed for A-RPG gameplay where the player should keep control during
+ * knockback. Inputs keep setting the base velocity, and this strategy adds a decaying
+ * impulse each physics step for a short duration.
+ *
+ * ## Design
+ *
+ * - The built-in physics `Knockback` strategy overwrites velocity every frame.
+ *   When inputs also change velocity, the two systems compete and can cause visible jitter.
+ * - This strategy avoids the "tug of war" by reading the current velocity and adding
+ *   the knockback impulse on top.
+ * - When finished, it does **not** force velocity to zero, so player input remains responsive.
+ *
+ * @example
+ * ```ts
+ * // Add a short impulse to the right, while player can still steer
+ * await player.addMovement(new AdditiveKnockback({ x: 1, y: 0 }, 5, 0.3));
+ * ```
+ */
+class AdditiveKnockback implements MovementStrategy {
+  private readonly direction: { x: number; y: number };
+  private elapsed = 0;
+  private currentSpeed: number;
+
+  constructor(
+    direction: { x: number; y: number },
+    initialSpeed: number,
+    private readonly duration: number,
+    private readonly decayFactor = 0.35
+  ) {
+    const magnitude = Math.hypot(direction.x, direction.y);
+    this.direction = magnitude > 0
+      ? { x: direction.x / magnitude, y: direction.y / magnitude }
+      : { x: 1, y: 0 };
+    this.currentSpeed = initialSpeed;
+  }
+
+  update(body: MovementBody, dt: number): void {
+    this.elapsed += dt;
+    if (this.elapsed > this.duration) {
+      return;
+    }
+
+    const impulseX = this.direction.x * this.currentSpeed;
+    const impulseY = this.direction.y * this.currentSpeed;
+
+    body.setVelocity({
+      x: body.velocity.x + impulseX,
+      y: body.velocity.y + impulseY,
+    });
+
+    const decay = Math.max(0, Math.min(1, this.decayFactor));
+    if (decay === 0) {
+      this.currentSpeed = 0;
+    } else if (decay !== 1) {
+      this.currentSpeed *= Math.pow(decay, dt);
+    }
+  }
+
+  isFinished(): boolean {
+    return this.elapsed >= this.duration;
+  }
+}
+
 
 interface PlayerWithMixins extends RpgCommonPlayer {
   getCurrentMap(): RpgMap;
@@ -43,6 +113,51 @@ type CallbackTileMove = (player: RpgPlayer, map) => Direction[]
 type CallbackTurnMove = (player: RpgPlayer, map) => string
 type Routes = (string | Promise<any> | Direction | Direction[] | Function)[]
 
+// Re-export MovementOptions from @rpgjs/common for convenience
+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 }, currentPosition: { x: number; y: number }) => 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;
+}
+
 export enum Frequency {
   Lowest = 600,
   Lower = 400,
@@ -90,7 +205,63 @@ export enum Speed {
 * Move.turnTowardPlayer(player) | Turns in the direction of the designated player
 * @memberof Move
 * */
+/**
+ * Tracks player state for stuck detection in random movement
+ * 
+ * Stores the last known position and direction for each player to detect
+ * when they are stuck (position hasn't changed) and need a different direction.
+ */
+interface PlayerMoveState {
+  lastX: number;
+  lastY: number;
+  lastDirection: number;
+  stuckCount: number;
+}
+
 class MoveList {
+  // Shared Perlin noise instance for smooth random movement
+  private static perlinNoise: PerlinNoise2D = new PerlinNoise2D();
+  private static randomCounter: number = 0;
+  // Instance counter for each call to ensure variation
+  private static callCounter: number = 0;
+  // Track player positions and directions to detect stuck state
+  private static playerMoveStates: Map<string, PlayerMoveState> = new Map();
+  // Threshold for considering a player as "stuck" (in pixels)
+  private static readonly STUCK_THRESHOLD = 2;
+
+
+  /**
+   * 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 {
+    MoveList.playerMoveStates.delete(playerId);
+  }
+
+  /**
+   * 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 {
+    MoveList.playerMoveStates.clear();
+  }
 
   repeatMove(direction: Direction, repeat: number): Direction[] {
     // Safety check for valid repeat value
@@ -170,33 +341,13 @@ class MoveList {
   }
 
   random(repeat: number = 1): Direction[] {
-    // Safety check for valid repeat value
-    if (!Number.isFinite(repeat) || repeat < 0 || repeat > 10000) {
-      console.warn('Invalid repeat value in random:', repeat, 'using default value 1');
-      repeat = 1;
-    }
-
-    // Ensure repeat is an integer
-    repeat = Math.floor(repeat);
-
-    // Additional safety check - ensure repeat is a safe integer
-    if (repeat < 0 || repeat > Number.MAX_SAFE_INTEGER || !Number.isSafeInteger(repeat)) {
-      console.warn('Unsafe repeat value in random:', repeat, 'using default value 1');
-      repeat = 1;
-    }
-
-    try {
-      return new Array(repeat).fill(null).map(() => [
+    return new Array(repeat).fill(null).map(() => [
         Direction.Right,
         Direction.Left,
         Direction.Up,
         Direction.Down
-      ][random(0, 3)]);
-    } catch (error) {
-      console.error('Error creating random array with repeat:', repeat, error);
-      return [Direction.Down]; // Return single direction as fallback
-    }
-  }
+    ][random(0, 3)])
+}
 
   tileRight(repeat: number = 1): CallbackTileMove {
     return this.repeatTileMove('right', repeat, 'tileWidth')
@@ -216,43 +367,22 @@ class MoveList {
 
   tileRandom(repeat: number = 1): CallbackTileMove {
     return (player: RpgPlayer, map): Direction[] => {
-      // Safety check for valid repeat value
-      if (!Number.isFinite(repeat) || repeat < 0 || repeat > 1000) {
-        console.warn('Invalid repeat value in tileRandom:', repeat, 'using default value 1');
-        repeat = 1;
-      }
-
-      // Ensure repeat is an integer
-      repeat = Math.floor(repeat);
-
-      let directions: Direction[] = []
-      for (let i = 0; i < repeat; i++) {
-        const randFn: CallbackTileMove = [
-          this.tileRight(),
-          this.tileLeft(),
-          this.tileUp(),
-          this.tileDown()
-        ][random(0, 3)]
-
-        try {
-          const newDirections = randFn(player, map);
-          if (Array.isArray(newDirections)) {
-            directions = [...directions, ...newDirections];
-          }
-        } catch (error) {
-          console.warn('Error in tileRandom iteration:', error);
-          // Continue with next iteration instead of breaking
-        }
-
-        // Safety check to prevent excessive array growth
-        if (directions.length > 10000) {
-          console.warn('tileRandom generated too many directions, truncating');
-          break;
+        let directions: Direction[] = []
+        for (let i = 0; i < repeat; i++) {
+            const randFn: CallbackTileMove = [
+                this.tileRight(),
+                this.tileLeft(),
+                this.tileUp(),
+                this.tileDown()
+            ][random(0, 3)]
+            directions = [
+                ...directions,
+                ...randFn(player, map)
+            ]
         }
-      }
-      return directions
+        return directions
     }
-  }
+}
 
   private _awayFromPlayerDirection(player: RpgPlayer, otherPlayer: RpgPlayer): Direction {
     const directionOtherPlayer = otherPlayer.getDirection()
@@ -364,12 +494,14 @@ class MoveList {
   }
 
   turnRandom(): string {
+    // Use Perlin noise for smooth random turn direction with guaranteed variation
+    const directionIndex = this.getRandomDirectionIndex();
     return [
       this.turnRight(),
       this.turnLeft(),
       this.turnUp(),
       this.turnDown()
-    ][random(0, 3)]
+    ][directionIndex]
   }
 
   turnAwayFromPlayer(otherPlayer: RpgPlayer): CallbackTurnMove {
@@ -512,6 +644,14 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
       return this._through();
     }
 
+    set throughEvent(value: boolean) {
+      this._throughEvent.set(value);
+    }
+
+    get throughEvent(): boolean {
+      return this._throughEvent();
+    }
+
     set frequency(value: number) {
       this._frequency.set(value);
     }
@@ -520,25 +660,70 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
       return this._frequency();
     }
 
-    addMovement(strategy: MovementStrategy): void {
+    set directionFixed(value: boolean) {
+      (this as any)._directionFixed.set(value);
+    }
+
+    get directionFixed(): boolean {
+      return (this as any)._directionFixed();
+    }
+
+    set animationFixed(value: boolean) {
+      (this as any)._animationFixed.set(value);
+    }
+
+    get animationFixed(): boolean {
+      return (this as any)._animationFixed();
+    }
+
+    /**
+     * Add a movement strategy to this entity
+     * 
+     * Returns a Promise that resolves when the movement completes (when `isFinished()` returns true).
+     * If the strategy doesn't implement `isFinished()`, the Promise resolves immediately.
+     * 
+     * @param strategy - The movement strategy to add
+     * @param options - Optional callbacks for start and completion events
+     * @returns Promise that resolves when the movement completes
+     * 
+     * @example
+     * ```ts
+     * // Fire and forget
+     * player.addMovement(new LinearMove({ x: 1, y: 0 }, 200));
+     * 
+     * // Wait for completion
+     * await player.addMovement(new Dash(10, { x: 1, y: 0 }, 200));
+     * console.log('Dash completed!');
+     * 
+     * // With callbacks
+     * await player.addMovement(new Knockback({ x: -1, y: 0 }, 5, 300), {
+     *   onStart: () => console.log('Knockback started'),
+     *   onComplete: () => console.log('Knockback completed')
+     * });
+     * ```
+     */
+    addMovement(strategy: MovementStrategy, options?: MovementOptions): Promise<void> {
       const map = (this as unknown as PlayerWithMixins).getCurrentMap() as any;
-      if (!map) return;
+      if (!map) return Promise.resolve();
 
-      map.moveManager.add((this as unknown as PlayerWithMixins).id, strategy);
+      const playerId = (this as unknown as PlayerWithMixins).id;
+      return map.moveManager.add(playerId, strategy, options);
     }
 
     removeMovement(strategy: MovementStrategy): boolean {
       const map = (this as unknown as PlayerWithMixins).getCurrentMap() as any;
       if (!map) return false;
 
-      return map.moveManager.remove((this as unknown as PlayerWithMixins).id, strategy);
+      const playerId = (this as unknown as PlayerWithMixins).id;
+      return map.moveManager.remove(playerId, strategy);
     }
 
     clearMovements(): void {
       const map = (this as unknown as PlayerWithMixins).getCurrentMap() as any;
       if (!map) return;
 
-      map.moveManager.clear((this as unknown as PlayerWithMixins).id);
+      const playerId = (this as unknown as PlayerWithMixins).id;
+      map.moveManager.clear(playerId);
     }
 
     hasActiveMovements(): boolean {
@@ -555,17 +740,59 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
       return map.moveManager.getStrategies((this as unknown as PlayerWithMixins).id);
     }
 
+    /**
+     * Move toward a target player or position using AI pathfinding
+     * 
+     * Uses the `SeekAvoid` strategy to navigate toward the target while avoiding obstacles.
+     * The movement speed is based on the player's current `speed` property, scaled appropriately.
+     * 
+     * @param target - Target player or position `{ x, y }` to move toward
+     * 
+     * @example
+     * ```ts
+     * // Move toward another player
+     * player.moveTo(otherPlayer);
+     * 
+     * // Move toward a specific position
+     * player.moveTo({ x: 200, y: 150 });
+     * ```
+     */
     moveTo(target: RpgCommonPlayer | { x: number, y: number }): void {
       const map = (this as unknown as PlayerWithMixins).getCurrentMap() as any;
       if (!map) return;
 
+      const playerId = (this as unknown as PlayerWithMixins).id;
       const engine = map.physic;
 
+      // Calculate maxSpeed based on player's speed
+      // Original values: 180 for player target, 80 for position target (with default speed=4)
+      // Factor: 45 for player (180/4), 20 for position (80/4)
+      const playerSpeed = (this as any).speed();
+
+      // Remove ALL movement strategies that could interfere with SeekAvoid
+      // This includes SeekAvoid, Dash, Knockback, and LinearRepulsion
+      const existingStrategies = this.getActiveMovements();
+      const conflictingStrategies = existingStrategies.filter(s => 
+        s instanceof SeekAvoid || 
+        s instanceof Dash || 
+        s instanceof Knockback || 
+        s instanceof LinearRepulsion
+      );
+      
+      if (conflictingStrategies.length > 0) {
+        conflictingStrategies.forEach(s => this.removeMovement(s));
+      }
+
       if ('id' in target) {
-        const targetProvider = () => (map as any).getBody(target.id) ?? null;
+        const targetProvider = () => {
+          const body = (map as any).getBody(target.id) ?? null;
+          return body;
+        };
+        // Factor 45: with speed=4 gives 180 (original value)
+        const maxSpeed = playerSpeed * 45;
         map.moveManager.add(
-          (this as unknown as PlayerWithMixins).id,
-          new SeekAvoid(engine, targetProvider, 180, 140, 80, 48)
+          playerId,
+          new SeekAvoid(engine, targetProvider, maxSpeed, 140, 80, 48)
         );
         return;
       }
@@ -576,9 +803,11 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
       });
       staticTarget.freeze();
 
+      // Factor 20: with speed=4 gives 80 (original value)
+      const maxSpeed = playerSpeed * 20;
       map.moveManager.add(
-        (this as unknown as PlayerWithMixins).id,
-        new SeekAvoid(engine, () => staticTarget, 80, 140, 80, 48)
+        playerId,
+        new SeekAvoid(engine, () => staticTarget, maxSpeed, 140, 80, 48)
       );
     }
 
@@ -586,35 +815,310 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
       const map = (this as unknown as PlayerWithMixins).getCurrentMap() as any;
       if (!map) return;
 
+      const playerId = (this as unknown as PlayerWithMixins).id;
       const strategies = this.getActiveMovements();
-      strategies.forEach(strategy => {
-        if (strategy instanceof SeekAvoid || strategy instanceof LinearRepulsion) {
+      const toRemove = strategies.filter(s => s instanceof SeekAvoid || s instanceof LinearRepulsion);
+      
+      if (toRemove.length > 0) {
+        toRemove.forEach(strategy => {
           this.removeMovement(strategy);
-        }
-      });
+        });
+      }
     }
 
-    dash(direction: { x: number, y: number }, speed: number = 8, duration: number = 200): void {
-      this.addMovement(new Dash(speed, direction, duration));
+    /**
+     * Perform a dash movement in the specified direction
+     * 
+     * Creates a burst of velocity for a fixed duration. The total speed is calculated
+     * by adding the player's base speed (`this.speed()`) to the additional dash speed.
+     * This ensures faster players also dash faster proportionally.
+     * 
+     * With default speed=4 and additionalSpeed=4: total = 8 (same as original default)
+     * 
+     * @param direction - Normalized direction vector `{ x, y }` for the dash
+     * @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 events
+     * @returns Promise that resolves when the dash completes
+     * 
+     * @example
+     * ```ts
+     * // Dash to the right and wait for completion
+     * await player.dash({ x: 1, y: 0 });
+     * 
+     * // Powerful dash with callbacks
+     * await player.dash({ x: 0, y: -1 }, 12, 300, {
+     *   onStart: () => console.log('Dash started!'),
+     *   onComplete: () => console.log('Dash finished!')
+     * });
+     * ```
+     */
+    dash(direction: { x: number, y: number }, additionalSpeed: number = 4, duration: number = 200, options?: MovementOptions): Promise<void> {
+      const playerSpeed = (this as any).speed();
+      // Total dash speed = base speed + additional speed
+      // With speed=4, additionalSpeed=4: gives 8 (original default value)
+      const totalSpeed = playerSpeed + additionalSpeed;
+      // Physic strategies expect seconds (dt is in seconds), while the server API exposes milliseconds
+      const durationSeconds = duration / 1000;
+      return this.addMovement(new Dash(totalSpeed, direction, durationSeconds), options);
     }
 
-    knockback(direction: { x: number, y: number }, force: number = 5, duration: number = 300): void {
-      this.addMovement(new Knockback(direction, force, duration));
+    /**
+     * Apply knockback effect in the specified direction
+     * 
+     * Pushes the entity with an initial force that decays over time.
+     * Returns a Promise that resolves when the knockback completes **or is cancelled**.
+     * 
+     * ## Design notes
+     * - The underlying physics `MovementManager` can cancel strategies via `remove()`, `clear()`,
+     *   or `stopMovement()` **without resolving the Promise** returned by `add()`.
+     * - For this reason, this method considers the knockback finished when either:
+     *   - the `add()` promise resolves (normal completion), or
+     *   - the strategy is no longer present in the active movements list (cancellation).
+     * - When multiple knockbacks overlap, `directionFixed` and `animationFixed` are restored
+     *   only after **all** knockbacks have finished (including cancellations).
+     * 
+     * @param direction - Normalized direction vector `{ x, y }` for the knockback
+     * @param force - Initial knockback force (default: 5)
+     * @param duration - Duration in milliseconds (default: 300)
+     * @param options - Optional callbacks for movement events
+     * @returns Promise that resolves when the knockback completes or is cancelled
+     * 
+     * @example
+     * ```ts
+     * // Simple knockback (await is optional)
+     * await player.knockback({ x: 1, y: 0 }, 5, 300);
+     *
+     * // Overlapping knockbacks: flags are restored only after the last one ends
+     * player.knockback({ x: -1, y: 0 }, 5, 300);
+     * player.knockback({ x: 0, y: 1 }, 3, 200);
+     *
+     * // Cancellation (e.g. map change) will still restore fixed flags
+     * // even if the underlying movement strategy promise is never resolved.
+     * ```
+     */
+    async knockback(direction: { x: number, y: number }, force: number = 5, duration: number = 300, options?: MovementOptions): Promise<void> {
+      const durationSeconds = duration / 1000;
+      const selfAny = this as any;
+      const lockKey = '__rpg_knockback_lock__';
+
+      type KnockbackLockState = {
+        prevDirectionFixed: boolean;
+        prevAnimationFixed: boolean;
+        prevAnimationName?: string;
+      };
+
+      const getLock = (): KnockbackLockState | undefined => selfAny[lockKey];
+      const setLock = (lock: KnockbackLockState): void => {
+        selfAny[lockKey] = lock;
+      };
+      const clearLock = (): void => {
+        delete selfAny[lockKey];
+      };
+
+      const hasActiveKnockback = (): boolean =>
+        this.getActiveMovements().some(s => s instanceof Knockback || s instanceof AdditiveKnockback);
+
+      const setAnimationName = (name: string): void => {
+        if (typeof selfAny.setAnimation === 'function') {
+          selfAny.setAnimation(name);
+          return;
+        }
+        const animSignal = selfAny.animationName;
+        if (animSignal && typeof animSignal === 'object' && typeof animSignal.set === 'function') {
+          animSignal.set(name);
+        }
+      };
+
+      const getAnimationName = (): string | undefined => {
+        const animSignal = selfAny.animationName;
+        if (typeof animSignal === 'function') {
+          try {
+            return animSignal();
+          } catch {
+            return undefined;
+          }
+        }
+        return undefined;
+      };
+
+      const restore = (): void => {
+        const lock = getLock();
+        if (!lock) return;
+
+        this.directionFixed = lock.prevDirectionFixed;
+
+        const prevAnimFixed = lock.prevAnimationFixed;
+        this.animationFixed = false; // temporarily unlock so we can restore animation
+        if (!prevAnimFixed && lock.prevAnimationName) {
+          setAnimationName(lock.prevAnimationName);
+        }
+        this.animationFixed = prevAnimFixed;
+
+        clearLock();
+      };
+
+      const ensureLockInitialized = (): void => {
+        if (getLock()) return;
+
+        setLock({
+          prevDirectionFixed: this.directionFixed,
+          prevAnimationFixed: this.animationFixed,
+          prevAnimationName: getAnimationName(),
+        });
+
+        this.directionFixed = true;
+        setAnimationName('stand');
+        this.animationFixed = true;
+      };
+
+      const waitUntilRemovedOrTimeout = (strategy: MovementStrategy): Promise<void> => {
+        return new Promise<void>((resolve) => {
+          const start = Date.now();
+          const maxMs = Math.max(0, duration + 1000);
+
+          const intervalId = setInterval(() => {
+            const active = this.getActiveMovements();
+            if (!active.includes(strategy) || (Date.now() - start > maxMs)) {
+              clearInterval(intervalId);
+              resolve();
+            }
+          }, 16);
+        });
+      };
+
+      // First knockback creates the lock and freezes direction/animation.
+      // Next knockbacks reuse the lock and keep the fixed flags enabled.
+      ensureLockInitialized();
+
+      // Use additive knockback to avoid jitter with player inputs
+      const strategy = new AdditiveKnockback(direction, force, durationSeconds);
+      const addPromise = this.addMovement(strategy, options);
+
+      try {
+        await Promise.race([addPromise, waitUntilRemovedOrTimeout(strategy)]);
+      } finally {
+        // Restore only when ALL knockbacks are done (including cancellations).
+        if (!hasActiveKnockback()) {
+          restore();
+        }
+      }
     }
 
-    followPath(waypoints: Array<{ x: number, y: number }>, speed: number = 2, loop: boolean = false): void {
+    /**
+     * Follow a sequence of waypoints
+     * 
+     * Makes the entity move through a list of positions at a speed calculated
+     * from the player's base speed. The `speedMultiplier` allows adjusting
+     * the travel speed relative to the player's normal movement speed.
+     * 
+     * With default speed=4 and multiplier=0.5: speed = 2 (same as original default)
+     * 
+     * @param waypoints - Array of `{ x, y }` positions to follow in order
+     * @param speedMultiplier - Multiplier applied to base speed (default: 0.5)
+     * @param loop - Whether to loop back to start after reaching the end (default: false)
+     * 
+     * @example
+     * ```ts
+     * // Follow a patrol path at normal speed
+     * const patrol = [
+     *   { x: 100, y: 100 },
+     *   { x: 200, y: 100 },
+     *   { x: 200, y: 200 }
+     * ];
+     * player.followPath(patrol, 1, true); // Loop at full speed
+     * 
+     * // Slow walk through waypoints
+     * player.followPath(waypoints, 0.25, false);
+     * ```
+     */
+    followPath(waypoints: Array<{ x: number, y: number }>, speedMultiplier: number = 0.5, loop: boolean = false): void {
+      const playerSpeed = (this as any).speed();
+      // Path follow speed = player base speed * multiplier
+      // With speed=4, multiplier=0.5: gives 2 (original default value)
+      const speed = playerSpeed * speedMultiplier;
       this.addMovement(new PathFollow(waypoints, speed, loop));
     }
 
+    /**
+     * Apply oscillating movement pattern
+     * 
+     * Creates a back-and-forth movement along the specified axis. The movement
+     * oscillates sinusoidally between -amplitude and +amplitude from the starting position.
+     * 
+     * @param direction - Primary oscillation axis (normalized direction vector)
+     * @param amplitude - Maximum distance from center in pixels (default: 50)
+     * @param period - Time for a complete cycle in milliseconds (default: 2000)
+     * 
+     * @example
+     * ```ts
+     * // Horizontal oscillation
+     * player.oscillate({ x: 1, y: 0 }, 100, 3000);
+     * 
+     * // Diagonal bobbing motion
+     * player.oscillate({ x: 1, y: 1 }, 30, 1000);
+     * ```
+     */
     oscillate(direction: { x: number, y: number }, amplitude: number = 50, period: number = 2000): void {
       this.addMovement(new Oscillate(direction, amplitude, period));
     }
 
-    applyIceMovement(direction: { x: number, y: number }, maxSpeed: number = 4): void {
+    /**
+     * Apply ice movement physics
+     * 
+     * Simulates slippery surface physics where the entity accelerates gradually
+     * and has difficulty stopping. The maximum speed is based on the player's
+     * base speed multiplied by a speed factor.
+     * 
+     * With default speed=4 and factor=1: maxSpeed = 4 (same as original default)
+     * 
+     * @param direction - Target movement direction `{ x, y }`
+     * @param speedFactor - Factor multiplied with base speed for max speed (default: 1.0)
+     * 
+     * @example
+     * ```ts
+     * // Normal ice physics
+     * player.applyIceMovement({ x: 1, y: 0 });
+     * 
+     * // Fast ice sliding
+     * player.applyIceMovement({ x: 0, y: 1 }, 1.5);
+     * ```
+     */
+    applyIceMovement(direction: { x: number, y: number }, speedFactor: number = 1): void {
+      const playerSpeed = (this as any).speed();
+      // Max ice speed = player base speed * factor
+      // With speed=4, factor=1: gives 4 (original default value)
+      const maxSpeed = playerSpeed * speedFactor;
       this.addMovement(new IceMovement(direction, maxSpeed));
     }
 
-    shootProjectile(type: ProjectileType, direction: { x: number, y: number }, speed: number = 200): void {
+    /**
+     * Shoot a projectile in the specified direction
+     * 
+     * Creates a projectile with ballistic trajectory. The speed is calculated
+     * from the player's base speed multiplied by a speed factor.
+     * 
+     * With default speed=4 and factor=50: speed = 200 (same as original default)
+     * 
+     * @param type - Type of projectile trajectory (`Straight`, `Arc`, or `Bounce`)
+     * @param direction - Normalized direction vector `{ x, y }`
+     * @param speedFactor - Factor multiplied with base speed (default: 50)
+     * 
+     * @example
+     * ```ts
+     * // Straight projectile
+     * player.shootProjectile(ProjectileType.Straight, { x: 1, y: 0 });
+     * 
+     * // Fast arc projectile
+     * player.shootProjectile(ProjectileType.Arc, { x: 1, y: -0.5 }, 75);
+     * ```
+     */
+    shootProjectile(type: ProjectileType, direction: { x: number, y: number }, speedFactor: number = 50): void {
+      const playerSpeed = (this as any).speed();
+      // Projectile speed = player base speed * factor
+      // With speed=4, factor=50: gives 200 (original default value)
+      const speed = playerSpeed * speedFactor;
+
       const config = {
         speed,
         direction,
@@ -628,9 +1132,7 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
       this.addMovement(new ProjectileMovement(type, config));
     }
 
-    moveRoutes(routes: Routes): Promise<boolean> {
-      let count = 0;
-      let frequence = 0;
+    moveRoutes(routes: Routes, options?: MoveRoutesOptions): Promise<boolean> {
       const player = this as unknown as PlayerWithMixins;
 
       // Break any existing route movement
@@ -641,122 +1143,529 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
         this._finishRoute = resolve;
 
         // Process function routes first
-        const processedRoutes = routes.map((route: any) => {
-          if (typeof route === 'function') {
-            const map = player.getCurrentMap() as any;
-            if (!map) {
-              return undefined;
+        const processedRoutes = await Promise.all(
+          routes.map(async (route: any) => {
+            if (typeof route === 'function') {
+              const map = player.getCurrentMap() as any;
+              if (!map) {
+                return undefined;
+              }
+              return route.apply(route, [player, map]);
             }
-            return route.apply(route, [player, map]);
-          }
-          return route;
-        });
+            return route;
+          })
+        );
 
         // Flatten nested arrays
-        const flatRoutes = this.flattenRoutes(processedRoutes);
-        let routeIndex = 0;
+        // Note: We keep promises in the routes array and handle them in the strategy
+        const finalRoutes = this.flattenRoutes(processedRoutes);
+
+        // Create a movement strategy that handles all routes
+        class RouteMovementStrategy implements MovementStrategy {
+          private routeIndex = 0;
+          private currentTarget: { x: number; y: number } | null = null; // Center position for physics
+          private currentTargetTopLeft: { x: number; y: number } | null = null; // Top-left position for player.x() comparison
+          private currentDirection: { x: number; y: number } = { x: 0, y: 0 };
+          private finished = false;
+          private waitingForPromise = false;
+          private promiseStartTime = 0;
+          private promiseDuration = 0;
+          private readonly routes: Routes;
+          private readonly player: PlayerWithMixins;
+          private readonly onComplete: (success: boolean) => void;
+          private readonly tileSize: number;
+          private readonly tolerance: number;
+          private readonly onStuck?: MoveRoutesOptions['onStuck'];
+          private readonly stuckTimeout: number;
+          private readonly stuckThreshold: number;
+
+          // Frequency wait state
+          private waitingForFrequency = false;
+          private frequencyWaitStartTime = 0;
+          private ratioFrequency = 15;
+
+          // Stuck detection state
+          private lastPosition: { x: number; y: number } | null = null;
+          private lastPositionTime: number = 0;
+          private stuckCheckStartTime: number = 0;
+          private lastDistanceToTarget: number | null = null;
+          private isCurrentlyStuck: boolean = false;
+          private stuckCheckInitialized: boolean = false;
+
+          constructor(
+            routes: Routes,
+            player: PlayerWithMixins,
+            onComplete: (success: boolean) => void,
+            options?: MoveRoutesOptions
+          ) {
+            this.routes = routes;
+            this.player = player;
+            this.onComplete = onComplete;
+            this.tileSize = player.nbPixelInTile || 32;
+            this.tolerance = 0.5; // Tolerance in pixels for reaching target (reduced for precision)
+            this.onStuck = options?.onStuck;
+            this.stuckTimeout = options?.stuckTimeout ?? 500; // Default 500ms
+            this.stuckThreshold = options?.stuckThreshold ?? 1; // Default 1 pixel
+
+            // Process initial route
+            this.processNextRoute();
+          }
 
-        const executeNextRoute = async (): Promise<void> => {
-          // Check if player still exists and is on a map
-          if (!player || !player.getCurrentMap()) {
-            this._finishRoute = null;
-            resolve(false);
-            return;
+          private debugLog(message: string, data?: any): void {
+            // Debug logging disabled - enable if needed for troubleshooting
           }
 
-          // Handle frequency timing
-          if (count >= (player.nbPixelInTile || 32)) {
-            if (frequence < (player.frequency || 0)) {
-              frequence++;
-              setTimeout(executeNextRoute, 16); // ~60fps timing
+          private processNextRoute(): void {
+            // Reset frequency wait state when processing a new route
+            this.waitingForFrequency = false;
+            this.frequencyWaitStartTime = 0;
+
+            // Check if we've completed all routes
+            if (this.routeIndex >= this.routes.length) {
+              this.debugLog('COMPLETE all routes finished');
+              this.finished = true;
+              this.onComplete(true);
               return;
             }
-          }
 
-          frequence = 0;
-          count++;
+            const currentRoute = this.routes[this.routeIndex];
+            this.routeIndex++;
 
-          // Check if we've completed all routes
-          if (routeIndex >= flatRoutes.length) {
-            this._finishRoute = null;
-            resolve(true);
-            return;
-          }
+            if (currentRoute === undefined) {
+              this.processNextRoute();
+              return;
+            }
+
+            try {
+              // Handle different route types
+              if (typeof currentRoute === 'object' && 'then' in currentRoute) {
+                // Handle Promise (like Move.wait())
+                this.debugLog(`WAIT for promise (route ${this.routeIndex}/${this.routes.length})`);
+                this.waitingForPromise = true;
+                this.promiseStartTime = Date.now();
+
+                // Try to get duration from promise if possible (for Move.wait())
+                // Move.wait() creates a promise that resolves after a delay
+                // We'll use a default duration and let the promise resolve naturally
+                this.promiseDuration = 1000; // Default 1 second, will be updated when promise resolves
+
+                // Set up promise resolution handler
+                (currentRoute as Promise<any>).then(() => {
+                  this.debugLog('WAIT promise resolved');
+                  this.waitingForPromise = false;
+                  this.processNextRoute();
+                }).catch(() => {
+                  this.debugLog('WAIT promise rejected');
+                  this.waitingForPromise = false;
+                  this.processNextRoute();
+                });
+              } else if (typeof currentRoute === 'string' && currentRoute.startsWith('turn-')) {
+                // Handle turn commands - just change direction, no movement
+                const directionStr = currentRoute.replace('turn-', '');
+                let direction: Direction = Direction.Down;
+
+                switch (directionStr) {
+                  case 'up':
+                  case Direction.Up:
+                    direction = Direction.Up;
+                    break;
+                  case 'down':
+                  case Direction.Down:
+                    direction = Direction.Down;
+                    break;
+                  case 'left':
+                  case Direction.Left:
+                    direction = Direction.Left;
+                    break;
+                  case 'right':
+                  case Direction.Right:
+                    direction = Direction.Right;
+                    break;
+                }
 
-          const currentRoute = flatRoutes[routeIndex];
-          routeIndex++;
+                this.debugLog(`TURN to ${directionStr}`);
+                if (this.player.changeDirection) {
+                  this.player.changeDirection(direction);
+                }
+                // Turn is instant, continue immediately
+                this.processNextRoute();
+              } else if (typeof currentRoute === 'number' || typeof currentRoute === 'string') {
+                // Handle Direction enum values (number or string) - calculate target position
+                const moveDirection = currentRoute as unknown as Direction;
+                const map = this.player.getCurrentMap() as any;
+                if (!map) {
+                  this.finished = true;
+                  this.onComplete(false);
+                  return;
+                }
 
-          if (currentRoute === undefined) {
-            executeNextRoute();
-            return;
+                // Get current position (top-left from player, which is what player.x() returns)
+                // We calculate target based on top-left position to match player.x() expectations
+                const currentTopLeftX = typeof this.player.x === 'function' ? this.player.x() : this.player.x;
+                const currentTopLeftY = typeof this.player.y === 'function' ? this.player.y() : this.player.y;
+
+                // Get player speed
+                let playerSpeed = this.player.speed()
+
+                // Use player speed as distance, not tile size
+                let distance = playerSpeed;
+
+                // Merge consecutive routes of same direction
+                const initialDistance = distance;
+                const initialRouteIndex = this.routeIndex;
+                while (this.routeIndex < this.routes.length) {
+                  const nextRoute = this.routes[this.routeIndex];
+                  if (nextRoute === currentRoute) {
+                    distance += playerSpeed;
+                    this.routeIndex++;
+                  } else {
+                    break;
+                  }
+                }
+
+                // Calculate target top-left position
+                let targetTopLeftX = currentTopLeftX;
+                let targetTopLeftY = currentTopLeftY;
+
+                switch (moveDirection) {
+                  case Direction.Right:
+                  case 'right' as any:
+                    targetTopLeftX = currentTopLeftX + distance;
+                    break;
+                  case Direction.Left:
+                  case 'left' as any:
+                    targetTopLeftX = currentTopLeftX - distance;
+                    break;
+                  case Direction.Down:
+                  case 'down' as any:
+                    targetTopLeftY = currentTopLeftY + distance;
+                    break;
+                  case Direction.Up:
+                  case 'up' as any:
+                    targetTopLeftY = currentTopLeftY - distance;
+                    break;
+                }
+
+                // Convert target top-left to center position for physics engine
+                // Get entity to access hitbox dimensions
+                const entity = map.physic.getEntityByUUID(this.player.id);
+                if (!entity) {
+                  this.finished = true;
+                  this.onComplete(false);
+                  return;
+                }
+
+                // Get hitbox dimensions for conversion
+                const hitbox = this.player.hitbox();
+                const hitboxWidth = hitbox?.w ?? 32;
+                const hitboxHeight = hitbox?.h ?? 32;
+
+                // Convert top-left to center: center = topLeft + (size / 2)
+                const targetX = targetTopLeftX + hitboxWidth / 2;
+                const targetY = targetTopLeftY + hitboxHeight / 2;
+
+                this.currentTarget = { x: targetX, y: targetY }; // Center position for physics engine
+                this.currentTargetTopLeft = { x: targetTopLeftX, y: targetTopLeftY }; // Top-left position for player.x() comparison
+                this.currentDirection = { x: 0, y: 0 };
+                
+                this.debugLog(`MOVE direction=${moveDirection} from=(${currentTopLeftX.toFixed(1)}, ${currentTopLeftY.toFixed(1)}) to=(${targetTopLeftX.toFixed(1)}, ${targetTopLeftY.toFixed(1)}) dist=${distance.toFixed(1)}`);
+                
+                // Reset stuck detection when starting a new movement
+                this.lastPosition = null;
+                this.isCurrentlyStuck = false;
+                this.stuckCheckStartTime = 0;
+                this.lastDistanceToTarget = null;
+                this.stuckCheckInitialized = false;
+                // Reset frequency wait state when starting a new movement
+                this.waitingForFrequency = false;
+                this.frequencyWaitStartTime = 0;
+              } else if (Array.isArray(currentRoute)) {
+                // Handle array of directions - insert them into routes
+                for (let i = currentRoute.length - 1; i >= 0; i--) {
+                  this.routes.splice(this.routeIndex, 0, currentRoute[i]);
+                }
+                this.processNextRoute();
+              } else {
+                // Unknown route type, skip
+                this.processNextRoute();
+              }
+            } catch (error) {
+              console.warn('Error processing route:', error);
+              this.processNextRoute();
+            }
           }
 
-          try {
-            // Handle different route types
-            if (typeof currentRoute === 'object' && 'then' in currentRoute) {
-              // Handle Promise
-              await currentRoute;
-              executeNextRoute();
-            } else if (typeof currentRoute === 'string' && currentRoute.startsWith('turn-')) {
-              // Handle turn commands
-              const directionStr = currentRoute.replace('turn-', '');
-              let direction: Direction = Direction.Down;
-
-              // Convert string direction to Direction enum
-              switch (directionStr) {
-                case 'up':
-                case Direction.Up:
-                  direction = Direction.Up;
-                  break;
-                case 'down':
-                case Direction.Down:
-                  direction = Direction.Down;
-                  break;
-                case 'left':
-                case Direction.Left:
-                  direction = Direction.Left;
-                  break;
-                case 'right':
-                case Direction.Right:
-                  direction = Direction.Right;
-                  break;
+          update(body: MovementBody, dt: number): void {
+            // Don't process if waiting for promise
+            if (this.waitingForPromise) {
+              body.setVelocity({ x: 0, y: 0 });
+              // Check if promise wait time has elapsed (fallback)
+              if (Date.now() - this.promiseStartTime > this.promiseDuration) {
+                this.waitingForPromise = false;
+                this.processNextRoute();
               }
+              return;
+            }
+
+            // Don't process if waiting for frequency delay
+            if (this.waitingForFrequency) {
+              body.setVelocity({ x: 0, y: 0 });
+              const playerFrequency = this.player.frequency;
+              const frequencyMs = playerFrequency || 0;
 
-              if (player.changeDirection) {
-                player.changeDirection(direction);
+              if (frequencyMs > 0 && Date.now() - this.frequencyWaitStartTime >= frequencyMs * this.ratioFrequency) {
+                this.waitingForFrequency = false;
+                this.processNextRoute();
               }
-              executeNextRoute();
-            } else if (typeof currentRoute === 'number') {
-              // Handle Direction enum values
-              if (player.moveByDirection) {
-                await player.moveByDirection(currentRoute as unknown as Direction, 1);
-              } else {
-                // Fallback to movement strategy - use direction as velocity components
-                let vx = 0, vy = 0;
-                const direction = currentRoute as unknown as Direction;
-                switch (direction) {
-                  case Direction.Right: vx = 1; break;
-                  case Direction.Left: vx = -1; break;
-                  case Direction.Down: vy = 1; break;
-                  case Direction.Up: vy = -1; break;
+              return;
+            }
+
+            // If no target, try to process next route
+            if (!this.currentTarget) {
+              if (!this.finished) {
+                this.processNextRoute();
+              }
+              if (!this.currentTarget) {
+                body.setVelocity({ x: 0, y: 0 });
+                // Reset stuck detection when no target
+                this.lastPosition = null;
+                this.isCurrentlyStuck = false;
+                this.lastDistanceToTarget = null;
+                this.stuckCheckInitialized = false;
+                this.currentTargetTopLeft = null;
+                return;
+              }
+            }
+
+            const entity = body.getEntity?.();
+            if (!entity) {
+              this.finished = true;
+              this.onComplete(false);
+              return;
+            }
+
+            const currentPosition = { x: entity.position.x, y: entity.position.y };
+            const currentTime = Date.now();
+
+            // Check distance using player's top-left position (what player.x() returns)
+            // This ensures we match the test expectations which compare player.x()
+            const currentTopLeftX = this.player.x();
+            const currentTopLeftY = this.player.y()
+
+            // Calculate direction and distance using top-left position if available
+            let dx: number, dy: number, distance: number;
+            if (this.currentTargetTopLeft) {
+              dx = this.currentTargetTopLeft.x - currentTopLeftX;
+              dy = this.currentTargetTopLeft.y - currentTopLeftY;
+              distance = Math.hypot(dx, dy);
+
+              // Check if we've reached the target (using top-left position)
+              if (distance <= this.tolerance) {
+                // Target reached, wait for frequency before processing next route
+                this.debugLog(`TARGET reached at (${currentTopLeftX.toFixed(1)}, ${currentTopLeftY.toFixed(1)})`);
+                this.currentTarget = null;
+                this.currentTargetTopLeft = null;
+                this.currentDirection = { x: 0, y: 0 };
+                body.setVelocity({ x: 0, y: 0 });
+                // Reset stuck detection
+                this.lastPosition = null;
+                this.isCurrentlyStuck = false;
+                this.lastDistanceToTarget = null;
+                this.stuckCheckInitialized = false;
+
+                // Wait for frequency before processing next route
+                if (!this.finished) {
+                  const playerFrequency = this.player.frequency;
+                  if (playerFrequency && playerFrequency > 0) {
+                    this.waitingForFrequency = true;
+                    this.frequencyWaitStartTime = Date.now();
+                  } else {
+                    // No frequency delay, process immediately
+                    this.processNextRoute();
+                  }
+                }
+                return;
+              }
+            } else {
+              // Fallback: use center position distance if top-left target not available
+              dx = this.currentTarget.x - currentPosition.x;
+              dy = this.currentTarget.y - currentPosition.y;
+              distance = Math.hypot(dx, dy);
+
+              // Check if we've reached the target (using center position as fallback)
+              if (distance <= this.tolerance) {
+                // Target reached, wait for frequency before processing next route
+                this.currentTarget = null;
+                this.currentTargetTopLeft = null;
+                this.currentDirection = { x: 0, y: 0 };
+                body.setVelocity({ x: 0, y: 0 });
+                // Reset stuck detection
+                this.lastPosition = null;
+                this.isCurrentlyStuck = false;
+                this.lastDistanceToTarget = null;
+                this.stuckCheckInitialized = false;
+
+                // Wait for frequency before processing next route
+                if (!this.finished) {
+                  const playerFrequency = player.frequency;
+                  if (playerFrequency && playerFrequency > 0) {
+                    this.waitingForFrequency = true;
+                    this.frequencyWaitStartTime = Date.now();
+                  } else {
+                    // No frequency delay, process immediately
+                    this.processNextRoute();
+                  }
                 }
-                const speed = player.speed?.() ?? 3;
-                this.addMovement(new LinearMove({ x: vx * speed, y: vy * speed }, 0.1));
-                setTimeout(executeNextRoute, 100);
                 return;
               }
-              executeNextRoute();
+            }
+
+            // Stuck detection: check if player is making progress
+            if (this.onStuck && this.currentTarget) {
+              // Initialize tracking on first update
+              if (!this.stuckCheckInitialized) {
+                this.lastPosition = { ...currentPosition };
+                this.lastDistanceToTarget = distance;
+                this.stuckCheckInitialized = true;
+                // Update tracking and continue (don't return early)
+                this.lastPositionTime = currentTime;
+              } else if (this.lastPosition && this.lastDistanceToTarget !== null) {
+                // We have a target, so we're trying to move (regardless of current velocity,
+                // which may be zero due to physics engine collision handling)
+                const positionChanged = Math.hypot(
+                  currentPosition.x - this.lastPosition.x,
+                  currentPosition.y - this.lastPosition.y
+                ) > this.stuckThreshold;
+
+                const distanceImproved = distance < (this.lastDistanceToTarget - this.stuckThreshold);
+
+                // Player is stuck if: not moving AND not getting closer to target
+                if (!positionChanged && !distanceImproved) {
+                  // Player is not making progress
+                  if (!this.isCurrentlyStuck) {
+                    // Start stuck timer
+                    this.stuckCheckStartTime = currentTime;
+                    this.isCurrentlyStuck = true;
+                  } else {
+                    // Check if stuck timeout has elapsed
+                    if (currentTime - this.stuckCheckStartTime >= this.stuckTimeout) {
+                      // Player is stuck, call onStuck callback
+                      this.debugLog(`STUCK detected at (${currentPosition.x.toFixed(1)}, ${currentPosition.y.toFixed(1)}) target=(${this.currentTarget.x.toFixed(1)}, ${this.currentTarget.y.toFixed(1)})`);
+                      const shouldContinue = this.onStuck(
+                        this.player as any,
+                        this.currentTarget,
+                        currentPosition
+                      );
+
+                      if (shouldContinue === false) {
+                        // Cancel the route
+                        this.debugLog('STUCK cancelled route');
+                        this.finished = true;
+                        this.onComplete(false);
+                        body.setVelocity({ x: 0, y: 0 });
+                        return;
+                      }
+
+                      // Continue route: abandon the current target and move on.
+                      //
+                      // ## Why?
+                      // When random movement hits an obstacle, the physics engine can keep the entity
+                      // at the same position while this strategy keeps trying to reach the same target,
+                      // resulting in an infinite "stuck loop". By dropping the current target here,
+                      // we allow the route to advance and (in the common case of `infiniteMoveRoute`)
+                      // re-evaluate `Move.tileRandom()` on the next cycle, producing a new direction.
+                      this.currentTarget = null;
+                      this.currentTargetTopLeft = null;
+                      this.currentDirection = { x: 0, y: 0 };
+                      body.setVelocity({ x: 0, y: 0 });
+
+                      // Reset stuck detection to start fresh on the next target
+                      this.isCurrentlyStuck = false;
+                      this.stuckCheckStartTime = 0;
+                      this.lastPosition = null;
+                      this.lastDistanceToTarget = null;
+                      this.stuckCheckInitialized = false;
+
+                      // Advance to next route instruction immediately
+                      this.processNextRoute();
+                      return;
+                    }
+                  }
+                } else {
+                  // Player is making progress, reset stuck detection
+                  this.isCurrentlyStuck = false;
+                  this.stuckCheckStartTime = 0;
+                }
+
+                // Update tracking variables
+                this.lastPosition = { ...currentPosition };
+                this.lastPositionTime = currentTime;
+                this.lastDistanceToTarget = distance;
+              }
+            }
+
+            // Get speed scalar from map (default 50 if not found)
+            const map = this.player.getCurrentMap() as any;
+            const speedScalar = map?.speedScalar ?? 50;
+
+            // Calculate direction and speed
+            // Use the distance calculated above (from top-left if available, center otherwise)
+            if (distance > 0) {
+              this.currentDirection = { x: dx / distance, y: dy / distance };
+            } else {
+              // If distance is 0 or negative, we've reached or passed the target
+              this.currentTarget = null;
+              this.currentTargetTopLeft = null;
+              this.currentDirection = { x: 0, y: 0 };
+              body.setVelocity({ x: 0, y: 0 });
+              if (!this.finished) {
+                const playerFrequency = typeof this.player.frequency === 'function' ? this.player.frequency() : this.player.frequency;
+                if (playerFrequency && playerFrequency > 0) {
+                  this.waitingForFrequency = true;
+                  this.frequencyWaitStartTime = Date.now();
+                } else {
+                  // No frequency delay, process immediately
+                  this.processNextRoute();
+                }
+              }
+              return;
+            }
+
+            // Convert vector direction to cardinal direction (like moveBody does)
+            const absX = Math.abs(this.currentDirection.x);
+            const absY = Math.abs(this.currentDirection.y);
+            let cardinalDirection: Direction;
+
+            if (absX >= absY) {
+              cardinalDirection = this.currentDirection.x >= 0 ? Direction.Right : Direction.Left;
             } else {
-              // Unknown route type, skip
-              executeNextRoute();
+              cardinalDirection = this.currentDirection.y >= 0 ? Direction.Down : Direction.Up;
             }
-          } catch (error) {
-            console.warn('Error executing route:', error);
-            executeNextRoute();
+
+            map.movePlayer(this.player as any, cardinalDirection)
           }
-        };
 
-        executeNextRoute();
+          isFinished(): boolean {
+            return this.finished;
+          }
+
+          onFinished(): void {
+            this.onComplete(true);
+          }
+        }
+
+        // Create and add the route movement strategy
+        const routeStrategy = new RouteMovementStrategy(
+          finalRoutes,
+          player,
+          (success: boolean) => {
+            this._finishRoute = null;
+            resolve(success);
+          },
+          options
+        );
+
+        this.addMovement(routeStrategy);
       });
     }
 
@@ -769,14 +1678,14 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
       }, []);
     }
 
-    infiniteMoveRoute(routes: Routes): void {
+    infiniteMoveRoute(routes: Routes, options?: MoveRoutesOptions): void {
       this._infiniteRoutes = routes;
       this._isInfiniteRouteActive = true;
 
       const executeInfiniteRoute = (isBreaking: boolean = false) => {
         if (isBreaking || !this._isInfiniteRouteActive) return;
 
-        this.moveRoutes(routes).then((completed) => {
+        this.moveRoutes(routes, options).then((completed) => {
           // Only continue if the route completed successfully and we're still active
           if (completed && this._isInfiniteRouteActive) {
             executeInfiniteRoute();
@@ -817,7 +1726,6 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
 
   return WithMoveManagerClass as unknown as PlayerCtor;
 }
-
 /**
  * Interface for Move Manager functionality
  * 
@@ -826,21 +1734,83 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
  * This interface defines the public API of the MoveManager mixin.
  */
 export interface IMoveManager {
-  /** Whether the player passes through other players */
+  /** 
+   * 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 events or other players */
+  /** 
+   * 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): void;
+  addMovement(strategy: MovementStrategy, options?: MovementOptions): Promise<void>;
 
   /**
    * Remove a specific movement strategy from this entity
@@ -884,29 +1854,41 @@ export interface IMoveManager {
   /**
    * 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 speed - Movement speed (default: 8)
+   * @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 }, speed?: number, duration?: number): void;
+  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 - Initial knockback force (default: 5)
+   * @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): void;
+  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 speed - Movement speed (default: 2)
+   * @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 }>, speed?: number, loop?: boolean): void;
+  followPath(waypoints: Array<{ x: number, y: number }>, speedMultiplier?: number, loop?: boolean): void;
 
   /**
    * Apply oscillating movement pattern
@@ -920,27 +1902,32 @@ export interface IMoveManager {
   /**
    * Apply ice movement physics
    * 
+   * Max speed is calculated from the player's base speed multiplied by the speedFactor.
+   * 
    * @param direction - Target movement direction
-   * @param maxSpeed - Maximum speed when fully accelerated (default: 4)
+   * @param speedFactor - Factor multiplied with base speed for max speed (default: 1.0)
    */
-  applyIceMovement(direction: { x: number, y: number }, maxSpeed?: number): void;
+  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 speed - Projectile speed (default: 200)
+   * @param speedFactor - Factor multiplied with base speed (default: 50)
    */
-  shootProjectile(type: ProjectileType, direction: { x: number, y: number }, speed?: number): void;
+  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): Promise<boolean>;
+  moveRoutes(routes: Routes, options?: MoveRoutesOptions): Promise<boolean>;
 
   /**
    * Give a path that repeats itself in a loop to a character
@@ -961,3 +1948,4 @@ export interface IMoveManager {
    */
   replayRoutes(): void;
 }
+