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

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,
@@ -22,6 +23,73 @@ import { RpgMap } from "../rooms/map";
 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;
@@ -45,6 +113,9 @@ 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
  */
@@ -134,100 +205,62 @@ 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;
+
 
   /**
-   * Gets a random direction index (0-3) using a hybrid approach for balanced randomness
+   * 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.
    * 
-   * 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 playerId - The ID of the player to clear state for
    * 
-   * @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
+   * @example
+   * ```ts
+   * // Clear state when player leaves map
+   * Move.clearPlayerState(player.id);
+   * ```
    */
-  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));
-    }
+  static clearPlayerState(playerId: string): void {
+    MoveList.playerMoveStates.delete(playerId);
+  }
 
-    return directionIndex;
+  /**
+   * 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[] {
@@ -308,41 +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 {
-      // 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
-    }
-  }
+    return new Array(repeat).fill(null).map(() => [
+        Direction.Right,
+        Direction.Left,
+        Direction.Up,
+        Direction.Down
+    ][random(0, 3)])
+}
 
   tileRight(repeat: number = 1): CallbackTileMove {
     return this.repeatTileMove('right', repeat, 'tileWidth')
@@ -362,61 +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[] = []
-      const directionFunctions: CallbackTileMove[] = [
-        this.tileRight(),
-        this.tileLeft(),
-        this.tileUp(),
-        this.tileDown()
-      ];
-      
-      for (let i = 0; i < repeat; i++) {
-        // 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);
-          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()
@@ -678,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);
     }
@@ -686,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 {
@@ -721,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;
       }
@@ -742,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)
       );
     }
 
@@ -752,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,
@@ -873,6 +1211,10 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
             this.processNextRoute();
           }
 
+          private debugLog(message: string, data?: any): void {
+            // Debug logging disabled - enable if needed for troubleshooting
+          }
+
           private processNextRoute(): void {
             // Reset frequency wait state when processing a new route
             this.waitingForFrequency = false;
@@ -880,6 +1222,7 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
 
             // 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;
@@ -897,8 +1240,7 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
               // 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.debugLog(`WAIT for promise (route ${this.routeIndex}/${this.routes.length})`);
                 this.waitingForPromise = true;
                 this.promiseStartTime = Date.now();
 
@@ -909,9 +1251,11 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
 
                 // 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();
                 });
@@ -939,6 +1283,7 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
                     break;
                 }
 
+                this.debugLog(`TURN to ${directionStr}`);
                 if (this.player.changeDirection) {
                   this.player.changeDirection(direction);
                 }
@@ -1022,6 +1367,9 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
                 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;
@@ -1114,6 +1462,7 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
               // 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 };
@@ -1201,6 +1550,7 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
                     // 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,
@@ -1209,18 +1559,36 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
 
                       if (shouldContinue === false) {
                         // Cancel the route
+                        this.debugLog('STUCK cancelled route');
                         this.finished = true;
                         this.onComplete(false);
                         body.setVelocity({ x: 0, y: 0 });
                         return;
                       }
 
-                      // Reset stuck detection to allow another check
+                      // 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;
-                      // Reset position tracking to start fresh check
-                      this.lastPosition = { ...currentPosition };
-                      this.lastDistanceToTarget = distance;
+                      this.lastPosition = null;
+                      this.lastDistanceToTarget = null;
+                      this.stuckCheckInitialized = false;
+
+                      // Advance to next route instruction immediately
+                      this.processNextRoute();
+                      return;
                     }
                   }
                 } else {
@@ -1310,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();
@@ -1358,7 +1726,6 @@ export function WithMoveManager<TBase extends PlayerCtor>(Base: TBase) {
 
   return WithMoveManagerClass as unknown as PlayerCtor;
 }
-
 /**
  * Interface for Move Manager functionality
  * 
@@ -1367,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
@@ -1425,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
@@ -1461,19 +1902,23 @@ 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
@@ -1503,3 +1948,4 @@ export interface IMoveManager {
    */
   replayRoutes(): void;
 }
+