@rpgjs/server 5.0.0-alpha.25 → 5.0.0-alpha.27

package/src/Player/MoveManager.ts

@@ -14,10 +14,12 @@ 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";
 
 
@@ -43,6 +45,48 @@ type CallbackTileMove = (player: RpgPlayer, map) => Direction[]
 type CallbackTurnMove = (player: RpgPlayer, map) => string
 type Routes = (string | Promise<any> | Direction | Direction[] | Function)[]
 
+/**
+ * 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,
@@ -91,6 +135,100 @@ export enum Speed {
 * @memberof Move
 * */
 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;
+
+  /**
+   * Gets a random direction index (0-3) using a hybrid approach for balanced randomness
+   * 
+   * Uses a combination of hash-based pseudo-randomness and Perlin noise to ensure
+   * fair distribution of directions while maintaining smooth, natural-looking movement patterns.
+   * The hash function guarantees uniform distribution, while Perlin noise adds spatial/temporal coherence.
+   * 
+   * @param player - Optional player instance for coordinate-based noise
+   * @param index - Optional index for array-based calls to ensure variation
+   * @returns Direction index (0-3) corresponding to Right, Left, Up, Down
+   */
+  private getRandomDirectionIndex(player?: RpgPlayer, index?: number): number {
+    // Increment call counter for each invocation to ensure variation
+    MoveList.callCounter++;
+
+    // Generate a unique seed from multiple sources
+    let seed: number;
+    const time = Date.now() * 0.001; // Convert to seconds
+
+    if (player) {
+      // Use player coordinates combined with time and call counter
+      const playerX = typeof player.x === 'function' ? player.x() : player.x;
+      const playerY = typeof player.y === 'function' ? player.y() : player.y;
+
+      // Combine with prime multipliers for better distribution
+      seed = Math.floor(
+        (playerX * 0.1) +
+        (playerY * 0.1) +
+        (time * 1000) +
+        (MoveList.callCounter * 17) +
+        ((index ?? 0) * 31)
+      );
+    } else {
+      // Fallback for non-player contexts
+      MoveList.randomCounter++;
+      seed = Math.floor(
+        (MoveList.randomCounter * 17) +
+        (time * 1000) +
+        (MoveList.callCounter * 31) +
+        ((index ?? 0) * 47)
+      );
+    }
+
+    // Use multiple hash functions combined to ensure uniform distribution
+    // This approach guarantees fair probability across all directions
+
+    // Hash 1: Linear congruential generator
+    let hash1 = ((seed * 1103515245 + 12345) & 0x7fffffff) >>> 0;
+
+    // Hash 2: Multiply-shift hash
+    let hash2 = ((seed * 2654435761) >>> 0);
+
+    // Hash 3: XOR with rotation
+    let hash3 = seed ^ (seed >>> 16);
+    hash3 = ((hash3 * 2246822507) >>> 0);
+
+    // Combine hashes using XOR for better distribution
+    let combinedHash = (hash1 ^ hash2 ^ hash3) >>> 0;
+
+    // Convert to 0-1 range
+    const hashValue = (combinedHash % 1000000) / 1000000;
+
+    // Use Perlin noise for smooth spatial/temporal variation (10% influence only)
+    // Very low influence to avoid bias while maintaining some smoothness
+    const perlinX = seed * 0.001;
+    const perlinY = (seed * 1.618) * 0.001; // Golden ratio
+    const perlinValue = MoveList.perlinNoise.getNormalized(perlinX, perlinY, 0.3);
+
+    // Combine hash (90%) with Perlin noise (10%)
+    // Very high weight on hash ensures fair distribution, minimal Perlin for subtle smoothness
+    const finalValue = (hashValue * 0.9) + (perlinValue * 0.1);
+
+    // Map to direction index (0-3) ensuring uniform distribution
+    // Clamp finalValue to [0, 1) range to ensure valid index
+    const clampedValue = Math.max(0, Math.min(0.999999, finalValue));
+    let directionIndex = Math.floor(clampedValue * 4);
+
+    // Ensure directionIndex is always in valid range [0, 3]
+    directionIndex = Math.max(0, Math.min(3, directionIndex));
+
+    // Additional safety check: if somehow we get an invalid value (NaN, Infinity), use hash directly
+    if (!Number.isFinite(directionIndex) || directionIndex < 0 || directionIndex > 3) {
+      const fallbackIndex = Math.floor(hashValue * 4) % 4;
+      return Math.max(0, Math.min(3, fallbackIndex));
+    }
+
+    return directionIndex;
+  }
 
   repeatMove(direction: Direction, repeat: number): Direction[] {
     // Safety check for valid repeat value
@@ -186,12 +324,20 @@ class MoveList {
     }
 
     try {
-      return new Array(repeat).fill(null).map(() => [
-        Direction.Right,
-        Direction.Left,
-        Direction.Up,
-        Direction.Down
-      ][random(0, 3)]);
+      // Use Perlin noise for smooth random directions
+      // Increment counter before generating directions
+      MoveList.randomCounter += repeat;
+
+      return new Array(repeat).fill(null).map((_, index) => {
+        // Use getRandomDirectionIndex with index to ensure variation for each element
+        const directionIndex = this.getRandomDirectionIndex(undefined, index);
+        return [
+          Direction.Right,
+          Direction.Left,
+          Direction.Up,
+          Direction.Down
+        ][directionIndex];
+      });
     } catch (error) {
       console.error('Error creating random array with repeat:', repeat, error);
       return [Direction.Down]; // Return single direction as fallback
@@ -226,13 +372,31 @@ class MoveList {
       repeat = Math.floor(repeat);
 
       let directions: Direction[] = []
+      const directionFunctions: CallbackTileMove[] = [
+        this.tileRight(),
+        this.tileLeft(),
+        this.tileUp(),
+        this.tileDown()
+      ];
+      
       for (let i = 0; i < repeat; i++) {
-        const randFn: CallbackTileMove = [
-          this.tileRight(),
-          this.tileLeft(),
-          this.tileUp(),
-          this.tileDown()
-        ][random(0, 3)]
+        // Use Perlin noise with player coordinates and index for smooth random movement
+        // Passing index ensures each iteration gets a different direction
+        let directionIndex = this.getRandomDirectionIndex(player, i);
+        
+        // Ensure directionIndex is valid (0-3)
+        if (!Number.isInteger(directionIndex) || directionIndex < 0 || directionIndex > 3) {
+          console.warn('Invalid directionIndex in tileRandom:', directionIndex, 'using fallback');
+          directionIndex = Math.floor(Math.random() * 4) % 4;
+        }
+        
+        const randFn = directionFunctions[directionIndex];
+
+        // Verify that randFn is a function before calling it
+        if (typeof randFn !== 'function') {
+          console.warn('randFn is not a function in tileRandom, skipping iteration');
+          continue;
+        }
 
         try {
           const newDirections = randFn(player, map);
@@ -364,12 +528,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 {
@@ -628,9 +794,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 +805,499 @@ 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;
-
-        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;
+        // 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();
           }
 
-          // 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.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())
+                // For Move.wait(), we need to track the wait time
+                // Check if it's a wait promise by checking if it resolves after a delay
+                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.waitingForPromise = false;
+                  this.processNextRoute();
+                }).catch(() => {
+                  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;
+                }
+
+                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;
+                }
+
+                // 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;
+                }
 
-          const currentRoute = flatRoutes[routeIndex];
-          routeIndex++;
+                // 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;
+                }
 
-          if (currentRoute === undefined) {
-            executeNextRoute();
-            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 };
+                // 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 (frequencyMs > 0 && Date.now() - this.frequencyWaitStartTime >= frequencyMs * this.ratioFrequency) {
+                this.waitingForFrequency = false;
+                this.processNextRoute();
               }
+              return;
+            }
 
-              if (player.changeDirection) {
-                player.changeDirection(direction);
+            // If no target, try to process next route
+            if (!this.currentTarget) {
+              if (!this.finished) {
+                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;
+              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.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();
+                  }
                 }
-                const speed = player.speed?.() ?? 3;
-                this.addMovement(new LinearMove({ x: vx * speed, y: vy * speed }, 0.1));
-                setTimeout(executeNextRoute, 100);
                 return;
               }
-              executeNextRoute();
             } else {
-              // Unknown route type, skip
-              executeNextRoute();
+              // 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();
+                  }
+                }
+                return;
+              }
+            }
+
+            // 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
+                      const shouldContinue = this.onStuck(
+                        this.player as any,
+                        this.currentTarget,
+                        currentPosition
+                      );
+
+                      if (shouldContinue === false) {
+                        // Cancel the route
+                        this.finished = true;
+                        this.onComplete(false);
+                        body.setVelocity({ x: 0, y: 0 });
+                        return;
+                      }
+
+                      // Reset stuck detection to allow another check
+                      this.isCurrentlyStuck = false;
+                      this.stuckCheckStartTime = 0;
+                      // Reset position tracking to start fresh check
+                      this.lastPosition = { ...currentPosition };
+                      this.lastDistanceToTarget = distance;
+                    }
+                  }
+                } 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;
             }
-          } catch (error) {
-            console.warn('Error executing route:', error);
-            executeNextRoute();
+
+            // 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 {
+              cardinalDirection = this.currentDirection.y >= 0 ? Direction.Down : Direction.Up;
+            }
+
+            map.movePlayer(this.player as any, cardinalDirection)
+          }
+
+          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
+        );
 
-        executeNextRoute();
+        this.addMovement(routeStrategy);
       });
     }
 
@@ -938,9 +1479,10 @@ export interface IMoveManager {
    * 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