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

package/dist/index.js

@@ -9906,8 +9906,81 @@ class RpgCommonPlayer {
     this.isConnected = signal(false);
     // Store intended movement direction (not synced, only used locally)
     this._intendedDirection = null;
+    // Direction and animation locking (server-side only, not synced)
+    this._directionFixed = signal(false);
+    this._animationFixed = signal(false);
     this.pendingInputs = [];
   }
+  /**
+   * Get whether direction changes are locked
+   * 
+   * @returns True if direction is locked and cannot be changed automatically
+   * 
+   * @example
+   * ```ts
+   * if (player.directionFixed) {
+   *   // Direction is locked, won't change automatically
+   * }
+   * ```
+   */
+  get directionFixed() {
+    return this._directionFixed();
+  }
+  /**
+   * Set whether direction changes are locked
+   * 
+   * When set to true, the player's direction will not change automatically
+   * during movement or from physics engine callbacks.
+   * 
+   * @param value - True to lock direction, false to allow automatic changes
+   * 
+   * @example
+   * ```ts
+   * // Lock direction during a special animation
+   * player.directionFixed = true;
+   * player.setAnimation('attack');
+   * // ... later
+   * player.directionFixed = false;
+   * ```
+   */
+  set directionFixed(value) {
+    this._directionFixed.set(value);
+  }
+  /**
+   * Get whether animation changes are locked
+   * 
+   * @returns True if animation is locked and cannot be changed automatically
+   * 
+   * @example
+   * ```ts
+   * if (player.animationFixed) {
+   *   // Animation is locked, won't change automatically
+   * }
+   * ```
+   */
+  get animationFixed() {
+    return this._animationFixed();
+  }
+  /**
+   * Set whether animation changes are locked
+   * 
+   * When set to true, the player's animation will not change automatically
+   * during movement or from physics engine callbacks.
+   * 
+   * @param value - True to lock animation, false to allow automatic changes
+   * 
+   * @example
+   * ```ts
+   * // Lock animation during a special skill
+   * player.animationFixed = true;
+   * player.setAnimation('skill');
+   * // ... later
+   * player.animationFixed = false;
+   * ```
+   */
+  set animationFixed(value) {
+    this._animationFixed.set(value);
+  }
   /**
    * Change the player's facing direction
    *
@@ -9915,6 +9988,8 @@ class RpgCommonPlayer {
    * and directional abilities. This should be called when the player
    * intends to move in a specific direction, not when they are pushed
    * by physics or sliding.
+   * 
+   * If `directionFixed` is true, this method will not change the direction.
    *
    * @param direction - The new direction to face
    *
@@ -9922,9 +9997,16 @@ class RpgCommonPlayer {
    * ```ts
    * // Player presses right arrow key
    * player.changeDirection(Direction.Right);
+   * 
+   * // Lock direction to prevent automatic changes
+   * player.directionFixed = true;
+   * player.changeDirection(Direction.Up); // This will be ignored
    * ```
    */
   changeDirection(direction) {
+    if (this._directionFixed()) {
+      return;
+    }
     this.direction.set(direction);
   }
   /**
@@ -10759,6 +10841,8 @@ class Entity {
     this.enterTileHandlers = /* @__PURE__ */ new Set();
     this.leaveTileHandlers = /* @__PURE__ */ new Set();
     this.canEnterTileHandlers = /* @__PURE__ */ new Set();
+    this.collisionFilterHandlers = /* @__PURE__ */ new Set();
+    this.resolutionFilterHandlers = /* @__PURE__ */ new Set();
     this.wasMoving = this.velocity.lengthSquared() > MOVEMENT_EPSILON_SQ;
   }
   /**
@@ -11305,9 +11389,46 @@ class Entity {
       this.angularVelocity = Math.sign(this.angularVelocity) * this.maxAngularVelocity;
     }
   }
+  /**
+   * Adds a collision filter to this entity
+   * 
+   * Collision filters allow dynamic, conditional collision filtering beyond static bitmasks.
+   * Each filter is called when checking if this entity can collide with another.
+   * If any filter returns `false`, the collision is ignored.
+   * 
+   * This enables scenarios like:
+   * - Players passing through other players (`throughOtherPlayer`)
+   * - Entities passing through all characters (`through`)
+   * - Custom game-specific collision rules
+   * 
+   * @param filter - Function that returns `true` to allow collision, `false` to ignore
+   * @returns Unsubscribe function to remove the filter
+   * 
+   * @example
+   * ```typescript
+   * // Allow entity to pass through other players
+   * const unsubscribe = entity.addCollisionFilter((self, other) => {
+   *   const otherOwner = (other as any).owner;
+   *   if (otherOwner?.type === 'player') {
+   *     return false; // No collision with players
+   *   }
+   *   return true; // Collide with everything else
+   * });
+   * 
+   * // Later, remove the filter
+   * unsubscribe();
+   * ```
+   */
+  addCollisionFilter(filter) {
+    this.collisionFilterHandlers.add(filter);
+    return () => this.collisionFilterHandlers.delete(filter);
+  }
   /**
    * Checks if this entity can collide with another entity
    * 
+   * First checks collision masks (bitmask filtering), then executes all registered
+   * collision filters. If any filter returns `false`, the collision is ignored.
+   * 
    * @param other - Other entity to check
    * @returns True if collision is possible
    */
@@ -11316,7 +11437,77 @@ class Entity {
     const maskA = this.collisionMask;
     const categoryB = other.collisionCategory;
     const maskB = other.collisionMask;
-    return (categoryA & maskB) !== 0 && (categoryB & maskA) !== 0;
+    if ((categoryA & maskB) === 0 || (categoryB & maskA) === 0) {
+      return false;
+    }
+    for (const filter of this.collisionFilterHandlers) {
+      if (!filter(this, other)) {
+        return false;
+      }
+    }
+    for (const filter of other.collisionFilterHandlers) {
+      if (!filter(other, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Adds a resolution filter to this entity
+   * 
+   * Resolution filters determine whether a collision should be **resolved** (blocking)
+   * or just **detected** (notification only). Unlike collision filters which prevent
+   * detection entirely, resolution filters allow collision events to fire while
+   * optionally skipping the physical blocking.
+   * 
+   * This enables scenarios like:
+   * - Players passing through other players but still triggering touch events
+   * - Entities passing through characters but still calling onPlayerTouch hooks
+   * - Ghost mode where collisions are detected but not resolved
+   * 
+   * @param filter - Function that returns `true` to resolve (block), `false` to skip
+   * @returns Unsubscribe function to remove the filter
+   * 
+   * @example
+   * ```typescript
+   * // Allow entity to pass through players but still trigger events
+   * const unsubscribe = entity.addResolutionFilter((self, other) => {
+   *   const otherOwner = (other as any).owner;
+   *   if (otherOwner?.type === 'player') {
+   *     return false; // Pass through but events still fire
+   *   }
+   *   return true; // Block other entities
+   * });
+   * 
+   * // Later, remove the filter
+   * unsubscribe();
+   * ```
+   */
+  addResolutionFilter(filter) {
+    this.resolutionFilterHandlers.add(filter);
+    return () => this.resolutionFilterHandlers.delete(filter);
+  }
+  /**
+   * Checks if this entity should resolve (block) a collision with another entity
+   * 
+   * This is called by the CollisionResolver to determine if the collision should
+   * result in physical blocking or just notification.
+   * 
+   * @param other - Other entity to check
+   * @returns True if collision should be resolved (blocking), false to pass through
+   */
+  shouldResolveCollisionWith(other) {
+    for (const filter of this.resolutionFilterHandlers) {
+      if (!filter(this, other)) {
+        return false;
+      }
+    }
+    for (const filter of other.resolutionFilterHandlers) {
+      if (!filter(other, this)) {
+        return false;
+      }
+    }
+    return true;
   }
   /**
    * @internal
@@ -12967,6 +13158,9 @@ class CollisionResolver {
    * Resolves a collision
    * 
    * Separates entities and applies collision response.
+   * First checks if the collision should be resolved using resolution filters.
+   * If any entity has a resolution filter that returns false, the collision
+   * is skipped (entities pass through) but events are still fired.
    * 
    * @param collision - Collision information to resolve
    */
@@ -12975,6 +13169,9 @@ class CollisionResolver {
     if (depth < this.config.minPenetrationDepth) {
       return;
     }
+    if (!entityA.shouldResolveCollisionWith(entityB)) {
+      return;
+    }
     this.separateEntities(entityA, entityB, normal, depth);
     this.resolveVelocities(entityA, entityB, normal);
   }
@@ -14118,20 +14315,64 @@ let MovementManager$1 = class MovementManager {
   }
   /**
    * Adds a movement strategy to an 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 after adding.
    *
    * @param target - Entity instance or entity UUID when a resolver is configured
    * @param strategy - Strategy to execute
+   * @param options - Optional callbacks for movement lifecycle events
+   * @returns Promise that resolves when the movement completes
+   * 
+   * @example
+   * ```typescript
+   * // Simple usage - fire and forget
+   * manager.add(player, new Dash(8, { x: 1, y: 0 }, 200));
+   * 
+   * // Wait for completion
+   * await manager.add(player, new Dash(8, { x: 1, y: 0 }, 200));
+   * console.log('Dash finished!');
+   * 
+   * // With callbacks
+   * await manager.add(player, new Knockback({ x: -1, y: 0 }, 5, 300), {
+   *   onStart: () => {
+   *     player.directionFixed = true;
+   *     player.animationFixed = true;
+   *   },
+   *   onComplete: () => {
+   *     player.directionFixed = false;
+   *     player.animationFixed = false;
+   *   }
+   * });
+   * ```
    */
-  add(target, strategy) {
+  add(target, strategy, options) {
     const body = this.resolveTarget(target);
     const key = body.id;
     if (!this.entries.has(key)) {
       this.entries.set(key, { body, strategies: [] });
     }
-    this.entries.get(key).strategies.push(strategy);
+    if (!strategy.isFinished) {
+      const entry = { strategy, started: false };
+      if (options) {
+        entry.options = options;
+      }
+      this.entries.get(key).strategies.push(entry);
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const entry = { strategy, resolve, started: false };
+      if (options) {
+        entry.options = options;
+      }
+      this.entries.get(key).strategies.push(entry);
+    });
   }
   /**
    * Removes a specific strategy from an entity.
+   * 
+   * Note: This will NOT trigger the onComplete callback or resolve the Promise.
+   * Use this when you want to cancel a movement without completion.
    *
    * @param target - Entity instance or identifier
    * @param strategy - Strategy instance to remove
@@ -14143,7 +14384,7 @@ let MovementManager$1 = class MovementManager {
     if (!entry) {
       return false;
     }
-    const index = entry.strategies.indexOf(strategy);
+    const index = entry.strategies.findIndex((e) => e.strategy === strategy);
     if (index === -1) {
       return false;
     }
@@ -14222,13 +14463,21 @@ let MovementManager$1 = class MovementManager {
   getStrategies(target) {
     const body = this.resolveTarget(target);
     const entry = this.entries.get(body.id);
-    return entry ? [...entry.strategies] : [];
+    return entry ? entry.strategies.map((e) => e.strategy) : [];
   }
   /**
    * Updates all registered strategies.
    *
    * Call this method once per frame before `PhysicsEngine.step()` so that the
    * physics simulation integrates the velocities that strategies configure.
+   * 
+   * This method handles the movement lifecycle:
+   * - Triggers `onStart` callback on first update
+   * - Calls `strategy.update()` each frame
+   * - When `isFinished()` returns true:
+   *   - Calls `strategy.onFinished()` if defined
+   *   - Triggers `onComplete` callback
+   *   - Resolves the Promise returned by `add()`
    *
    * @param dt - Time delta in seconds
    */
@@ -14240,14 +14489,22 @@ let MovementManager$1 = class MovementManager {
         continue;
       }
       for (let i = strategies.length - 1; i >= 0; i -= 1) {
-        const current = strategies[i];
-        if (!current) {
+        const strategyEntry = strategies[i];
+        if (!strategyEntry) {
           continue;
         }
-        current.update(body, dt);
-        if (current.isFinished?.()) {
+        const { strategy, options, resolve } = strategyEntry;
+        if (!strategyEntry.started) {
+          strategyEntry.started = true;
+          options?.onStart?.();
+        }
+        strategy.update(body, dt);
+        const isFinished = strategy.isFinished?.();
+        if (isFinished) {
           strategies.splice(i, 1);
-          current.onFinished?.();
+          strategy.onFinished?.();
+          options?.onComplete?.();
+          resolve?.();
         }
       }
       if (strategies.length === 0) {
@@ -15770,8 +16027,16 @@ class MovementManager {
   get core() {
     return this.physicProvider().getMovementManager();
   }
-  add(id, strategy) {
-    this.core.add(id, strategy);
+  /**
+   * Adds a movement strategy and returns a Promise that resolves when it completes.
+   * 
+   * @param id - Entity identifier
+   * @param strategy - Movement strategy to add
+   * @param options - Optional callbacks for movement lifecycle events
+   * @returns Promise that resolves when the movement completes
+   */
+  add(id, strategy, options) {
+    return this.core.add(id, strategy, options);
   }
   remove(id, strategy) {
     return this.core.remove(id, strategy);
@@ -16624,11 +16889,14 @@ class RpgCommonMap {
       const owner2 = entity.owner;
       if (!owner2) return;
       if (cardinalDirection === "idle") return;
+      if (owner2.directionFixed) return;
       owner2.changeDirection(cardinalDirection);
     });
     entity.onMovementChange(({ isMoving, intensity }) => {
+      if (!("$send" in this)) return;
       const owner2 = entity.owner;
       if (!owner2) return;
+      if (owner2.animationFixed) return;
       const LOW_INTENSITY_THRESHOLD = 10;
       const hasSetAnimation = typeof owner2.setAnimation === "function";
       const animationNameSignal = owner2.animationName;
@@ -16665,6 +16933,56 @@ class RpgCommonMap {
         owner.applyFrames?.();
       }
     });
+    entity.addResolutionFilter((self, other) => {
+      const selfOwner = self.owner;
+      const otherOwner = other.owner;
+      if (!selfOwner || !otherOwner) {
+        return true;
+      }
+      if (selfOwner.z() !== otherOwner.z()) {
+        return false;
+      }
+      if (typeof selfOwner._through === "function") {
+        try {
+          if (selfOwner._through() === true) {
+            return false;
+          }
+        } catch {
+        }
+      } else if (selfOwner.through === true) {
+        return false;
+      }
+      const playersMap = this.players();
+      const eventsMap = this.events();
+      const isSelfPlayer = !!playersMap[self.uuid];
+      const isOtherPlayer = !!playersMap[other.uuid];
+      const isOtherEvent = !!eventsMap[other.uuid];
+      if (isSelfPlayer && isOtherPlayer) {
+        if (typeof selfOwner._throughOtherPlayer === "function") {
+          try {
+            if (selfOwner._throughOtherPlayer() === true) {
+              return false;
+            }
+          } catch {
+          }
+        } else if (selfOwner.throughOtherPlayer === true) {
+          return false;
+        }
+      }
+      if (isSelfPlayer && isOtherEvent) {
+        if (typeof selfOwner._throughEvent === "function") {
+          try {
+            if (selfOwner._throughEvent() === true) {
+              return false;
+            }
+          } catch {
+          }
+        } else if (selfOwner.throughEvent === true) {
+          return false;
+        }
+      }
+      return true;
+    });
     return id;
   }
   /**
@@ -18232,6 +18550,37 @@ class Gui {
   }
 }
 
+class AdditiveKnockback {
+  constructor(direction, initialSpeed, duration, decayFactor = 0.35) {
+    this.duration = duration;
+    this.decayFactor = decayFactor;
+    this.elapsed = 0;
+    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, dt) {
+    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() {
+    return this.elapsed >= this.duration;
+  }
+}
 function wait(sec) {
   return new Promise((resolve) => {
     setTimeout(resolve, sec * 1e3);
@@ -18269,51 +18618,44 @@ class MoveList {
     // Instance counter for each call to ensure variation
     this.callCounter = 0;
   }
+  static {
+    // Track player positions and directions to detect stuck state
+    this.playerMoveStates = /* @__PURE__ */ new Map();
+  }
+  static {
+    // Threshold for considering a player as "stuck" (in pixels)
+    this.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);
+   * ```
    */
-  getRandomDirectionIndex(player, index) {
-    MoveList.callCounter++;
-    let seed;
-    const time = Date.now() * 1e-3;
-    if (player) {
-      const playerX = typeof player.x === "function" ? player.x() : player.x;
-      const playerY = typeof player.y === "function" ? player.y() : player.y;
-      seed = Math.floor(
-        playerX * 0.1 + playerY * 0.1 + time * 1e3 + MoveList.callCounter * 17 + (index ?? 0) * 31
-      );
-    } else {
-      MoveList.randomCounter++;
-      seed = Math.floor(
-        MoveList.randomCounter * 17 + time * 1e3 + MoveList.callCounter * 31 + (index ?? 0) * 47
-      );
-    }
-    let hash1 = (seed * 1103515245 + 12345 & 2147483647) >>> 0;
-    let hash2 = seed * 2654435761 >>> 0;
-    let hash3 = seed ^ seed >>> 16;
-    hash3 = hash3 * 2246822507 >>> 0;
-    let combinedHash = (hash1 ^ hash2 ^ hash3) >>> 0;
-    const hashValue = combinedHash % 1e6 / 1e6;
-    const perlinX = seed * 1e-3;
-    const perlinY = seed * 1.618 * 1e-3;
-    const perlinValue = MoveList.perlinNoise.getNormalized(perlinX, perlinY, 0.3);
-    const finalValue = hashValue * 0.9 + perlinValue * 0.1;
-    const clampedValue = Math.max(0, Math.min(0.999999, finalValue));
-    let directionIndex = Math.floor(clampedValue * 4);
-    directionIndex = Math.max(0, Math.min(3, directionIndex));
-    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;
+  static clearPlayerState(playerId) {
+    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() {
+    MoveList.playerMoveStates.clear();
   }
   repeatMove(direction, repeat) {
     if (!Number.isFinite(repeat) || repeat < 0 || repeat > 1e4) {
@@ -18372,30 +18714,12 @@ class MoveList {
     return wait(sec);
   }
   random(repeat = 1) {
-    if (!Number.isFinite(repeat) || repeat < 0 || repeat > 1e4) {
-      console.warn("Invalid repeat value in random:", repeat, "using default value 1");
-      repeat = 1;
-    }
-    repeat = Math.floor(repeat);
-    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 {
-      MoveList.randomCounter += repeat;
-      return new Array(repeat).fill(null).map((_, index) => {
-        const directionIndex = this.getRandomDirectionIndex(void 0, 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 new Array(repeat).fill(null).map(() => [
+      Direction.Right,
+      Direction.Left,
+      Direction.Up,
+      Direction.Down
+    ][random(0, 3)]);
   }
   tileRight(repeat = 1) {
     return this.repeatTileMove("right", repeat, "tileWidth");
@@ -18411,41 +18735,18 @@ class MoveList {
   }
   tileRandom(repeat = 1) {
     return (player, map) => {
-      if (!Number.isFinite(repeat) || repeat < 0 || repeat > 1e3) {
-        console.warn("Invalid repeat value in tileRandom:", repeat, "using default value 1");
-        repeat = 1;
-      }
-      repeat = Math.floor(repeat);
       let directions = [];
-      const directionFunctions = [
-        this.tileRight(),
-        this.tileLeft(),
-        this.tileUp(),
-        this.tileDown()
-      ];
       for (let i = 0; i < repeat; i++) {
-        let directionIndex = this.getRandomDirectionIndex(player, i);
-        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];
-        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);
-        }
-        if (directions.length > 1e4) {
-          console.warn("tileRandom generated too many directions, truncating");
-          break;
-        }
+        const randFn = [
+          this.tileRight(),
+          this.tileLeft(),
+          this.tileUp(),
+          this.tileDown()
+        ][random(0, 3)];
+        directions = [
+          ...directions,
+          ...randFn(player, map)
+        ];
       }
       return directions;
     };
@@ -18603,26 +18904,73 @@ function WithMoveManager(Base) {
     get through() {
       return this._through();
     }
+    set throughEvent(value) {
+      this._throughEvent.set(value);
+    }
+    get throughEvent() {
+      return this._throughEvent();
+    }
     set frequency(value) {
       this._frequency.set(value);
     }
     get frequency() {
       return this._frequency();
     }
-    addMovement(strategy) {
+    set directionFixed(value) {
+      this._directionFixed.set(value);
+    }
+    get directionFixed() {
+      return this._directionFixed();
+    }
+    set animationFixed(value) {
+      this._animationFixed.set(value);
+    }
+    get animationFixed() {
+      return this._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, options) {
       const map = this.getCurrentMap();
-      if (!map) return;
-      map.moveManager.add(this.id, strategy);
+      if (!map) return Promise.resolve();
+      const playerId = this.id;
+      return map.moveManager.add(playerId, strategy, options);
     }
     removeMovement(strategy) {
       const map = this.getCurrentMap();
       if (!map) return false;
-      return map.moveManager.remove(this.id, strategy);
+      const playerId = this.id;
+      return map.moveManager.remove(playerId, strategy);
     }
     clearMovements() {
       const map = this.getCurrentMap();
       if (!map) return;
-      map.moveManager.clear(this.id);
+      const playerId = this.id;
+      map.moveManager.clear(playerId);
     }
     hasActiveMovements() {
       const map = this.getCurrentMap();
@@ -18634,15 +18982,45 @@ function WithMoveManager(Base) {
       if (!map) return [];
       return map.moveManager.getStrategies(this.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) {
       const map = this.getCurrentMap();
       if (!map) return;
+      const playerId = this.id;
       const engine = map.physic;
+      const playerSpeed = this.speed();
+      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.getBody(target.id) ?? null;
+        const targetProvider = () => {
+          const body = map.getBody(target.id) ?? null;
+          return body;
+        };
+        const maxSpeed2 = playerSpeed * 45;
         map.moveManager.add(
-          this.id,
-          new SeekAvoid(engine, targetProvider, 180, 140, 80, 48)
+          playerId,
+          new SeekAvoid(engine, targetProvider, maxSpeed2, 140, 80, 48)
         );
         return;
       }
@@ -18651,37 +19029,275 @@ function WithMoveManager(Base) {
         mass: Infinity
       });
       staticTarget.freeze();
+      const maxSpeed = playerSpeed * 20;
       map.moveManager.add(
-        this.id,
-        new SeekAvoid(engine, () => staticTarget, 80, 140, 80, 48)
+        playerId,
+        new SeekAvoid(engine, () => staticTarget, maxSpeed, 140, 80, 48)
       );
     }
     stopMoveTo() {
       const map = this.getCurrentMap();
       if (!map) return;
+      this.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, speed = 8, duration = 200) {
-      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, additionalSpeed = 4, duration = 200, options) {
+      const playerSpeed = this.speed();
+      const totalSpeed = playerSpeed + additionalSpeed;
+      const durationSeconds = duration / 1e3;
+      return this.addMovement(new Dash(totalSpeed, direction, durationSeconds), options);
     }
-    knockback(direction, force = 5, duration = 300) {
-      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, force = 5, duration = 300, options) {
+      const durationSeconds = duration / 1e3;
+      const selfAny = this;
+      const lockKey = "__rpg_knockback_lock__";
+      const getLock = () => selfAny[lockKey];
+      const setLock = (lock) => {
+        selfAny[lockKey] = lock;
+      };
+      const clearLock = () => {
+        delete selfAny[lockKey];
+      };
+      const hasActiveKnockback = () => this.getActiveMovements().some((s) => s instanceof Knockback || s instanceof AdditiveKnockback);
+      const setAnimationName = (name) => {
+        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 = () => {
+        const animSignal = selfAny.animationName;
+        if (typeof animSignal === "function") {
+          try {
+            return animSignal();
+          } catch {
+            return void 0;
+          }
+        }
+        return void 0;
+      };
+      const restore = () => {
+        const lock = getLock();
+        if (!lock) return;
+        this.directionFixed = lock.prevDirectionFixed;
+        const prevAnimFixed = lock.prevAnimationFixed;
+        this.animationFixed = false;
+        if (!prevAnimFixed && lock.prevAnimationName) {
+          setAnimationName(lock.prevAnimationName);
+        }
+        this.animationFixed = prevAnimFixed;
+        clearLock();
+      };
+      const ensureLockInitialized = () => {
+        if (getLock()) return;
+        setLock({
+          prevDirectionFixed: this.directionFixed,
+          prevAnimationFixed: this.animationFixed,
+          prevAnimationName: getAnimationName()
+        });
+        this.directionFixed = true;
+        setAnimationName("stand");
+        this.animationFixed = true;
+      };
+      const waitUntilRemovedOrTimeout = (strategy2) => {
+        return new Promise((resolve) => {
+          const start = Date.now();
+          const maxMs = Math.max(0, duration + 1e3);
+          const intervalId = setInterval(() => {
+            const active = this.getActiveMovements();
+            if (!active.includes(strategy2) || Date.now() - start > maxMs) {
+              clearInterval(intervalId);
+              resolve();
+            }
+          }, 16);
+        });
+      };
+      ensureLockInitialized();
+      const strategy = new AdditiveKnockback(direction, force, durationSeconds);
+      const addPromise = this.addMovement(strategy, options);
+      try {
+        await Promise.race([addPromise, waitUntilRemovedOrTimeout(strategy)]);
+      } finally {
+        if (!hasActiveKnockback()) {
+          restore();
+        }
+      }
     }
-    followPath(waypoints, speed = 2, loop = false) {
+    /**
+     * 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, speedMultiplier = 0.5, loop = false) {
+      const playerSpeed = this.speed();
+      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, amplitude = 50, period = 2e3) {
       this.addMovement(new Oscillate(direction, amplitude, period));
     }
-    applyIceMovement(direction, maxSpeed = 4) {
+    /**
+     * 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, speedFactor = 1) {
+      const playerSpeed = this.speed();
+      const maxSpeed = playerSpeed * speedFactor;
       this.addMovement(new IceMovement(direction, maxSpeed));
     }
-    shootProjectile(type, direction, speed = 200) {
+    /**
+     * 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, direction, speedFactor = 50) {
+      const playerSpeed = this.speed();
+      const speed = playerSpeed * speedFactor;
       const config = {
         speed,
         direction,
@@ -18744,10 +19360,13 @@ function WithMoveManager(Base) {
             this.stuckThreshold = options2?.stuckThreshold ?? 1;
             this.processNextRoute();
           }
+          debugLog(message, data) {
+          }
           processNextRoute() {
             this.waitingForFrequency = false;
             this.frequencyWaitStartTime = 0;
             if (this.routeIndex >= this.routes.length) {
+              this.debugLog("COMPLETE all routes finished");
               this.finished = true;
               this.onComplete(true);
               return;
@@ -18760,13 +19379,16 @@ function WithMoveManager(Base) {
             }
             try {
               if (typeof currentRoute === "object" && "then" in currentRoute) {
+                this.debugLog(`WAIT for promise (route ${this.routeIndex}/${this.routes.length})`);
                 this.waitingForPromise = true;
                 this.promiseStartTime = Date.now();
                 this.promiseDuration = 1e3;
                 currentRoute.then(() => {
+                  this.debugLog("WAIT promise resolved");
                   this.waitingForPromise = false;
                   this.processNextRoute();
                 }).catch(() => {
+                  this.debugLog("WAIT promise rejected");
                   this.waitingForPromise = false;
                   this.processNextRoute();
                 });
@@ -18791,6 +19413,7 @@ function WithMoveManager(Base) {
                     direction = Direction.Right;
                     break;
                 }
+                this.debugLog(`TURN to ${directionStr}`);
                 if (this.player.changeDirection) {
                   this.player.changeDirection(direction);
                 }
@@ -18852,6 +19475,7 @@ function WithMoveManager(Base) {
                 this.currentTarget = { x: targetX, y: targetY };
                 this.currentTargetTopLeft = { x: targetTopLeftX, y: targetTopLeftY };
                 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)}`);
                 this.lastPosition = null;
                 this.isCurrentlyStuck = false;
                 this.stuckCheckStartTime = 0;
@@ -18921,6 +19545,7 @@ function WithMoveManager(Base) {
               dy = this.currentTargetTopLeft.y - currentTopLeftY;
               distance = Math.hypot(dx, dy);
               if (distance <= this.tolerance) {
+                this.debugLog(`TARGET reached at (${currentTopLeftX.toFixed(1)}, ${currentTopLeftY.toFixed(1)})`);
                 this.currentTarget = null;
                 this.currentTargetTopLeft = null;
                 this.currentDirection = { x: 0, y: 0 };
@@ -18983,21 +19608,30 @@ function WithMoveManager(Base) {
                     this.isCurrentlyStuck = true;
                   } else {
                     if (currentTime - this.stuckCheckStartTime >= this.stuckTimeout) {
+                      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,
                         this.currentTarget,
                         currentPosition
                       );
                       if (shouldContinue === false) {
+                        this.debugLog("STUCK cancelled route");
                         this.finished = true;
                         this.onComplete(false);
                         body.setVelocity({ x: 0, y: 0 });
                         return;
                       }
+                      this.currentTarget = null;
+                      this.currentTargetTopLeft = null;
+                      this.currentDirection = { x: 0, y: 0 };
+                      body.setVelocity({ x: 0, y: 0 });
                       this.isCurrentlyStuck = false;
                       this.stuckCheckStartTime = 0;
-                      this.lastPosition = { ...currentPosition };
-                      this.lastDistanceToTarget = distance;
+                      this.lastPosition = null;
+                      this.lastDistanceToTarget = null;
+                      this.stuckCheckInitialized = false;
+                      this.processNextRoute();
+                      return;
                     }
                   }
                 } else {
@@ -19066,12 +19700,12 @@ function WithMoveManager(Base) {
         return acc.concat(item);
       }, []);
     }
-    infiniteMoveRoute(routes) {
+    infiniteMoveRoute(routes, options) {
       this._infiniteRoutes = routes;
       this._isInfiniteRouteActive = true;
       const executeInfiniteRoute = (isBreaking = false) => {
         if (isBreaking || !this._isInfiniteRouteActive) return;
-        this.moveRoutes(routes).then((completed) => {
+        this.moveRoutes(routes, options).then((completed) => {
           if (completed && this._isInfiniteRouteActive) {
             executeInfiniteRoute();
           }
@@ -20362,64 +20996,208 @@ function WithElementManager(Base) {
 
 function WithSkillManager(Base) {
   return class extends Base {
-    _getSkillIndex(skillClass) {
+    /**
+     * Find the index of a skill in the skills array
+     * 
+     * Searches by ID for both string inputs and object/class inputs.
+     * 
+     * @param skillInput - Skill ID, class, or object to find
+     * @returns Index of the skill or -1 if not found
+     */
+    _getSkillIndex(skillInput) {
+      let searchId = "";
+      if (isString(skillInput)) {
+        searchId = skillInput;
+      } else if (typeof skillInput === "function") {
+        searchId = skillInput.id || skillInput.name;
+      } else {
+        searchId = skillInput.id || "";
+      }
       return this.skills().findIndex((skill) => {
-        if (isString(skill)) {
-          return skill.id == skillClass;
-        }
-        if (isString(skillClass)) {
-          return skillClass == (skill.id || skill);
-        }
-        return isInstanceOf(skill, skillClass);
+        const skillId = skill.id || skill.name || "";
+        return skillId === searchId;
       });
     }
-    getSkill(skillClass) {
-      const index = this._getSkillIndex(skillClass);
+    /**
+     * Retrieves a learned skill
+     * 
+     * Searches the player's learned skills by ID, class, or object.
+     * 
+     * @param skillInput - Skill ID, class, or object to find
+     * @returns The skill data if found, null otherwise
+     * 
+     * @example
+     * ```ts
+     * const skill = player.getSkill('fire');
+     * if (skill) {
+     *   console.log(`Fire skill costs ${skill.spCost} SP`);
+     * }
+     * ```
+     */
+    getSkill(skillInput) {
+      const index = this._getSkillIndex(skillInput);
       return this.skills()[index] ?? null;
     }
-    learnSkill(skillId) {
+    /**
+     * Learn a new skill
+     * 
+     * Adds a skill to the player's skill list. Supports three input formats:
+     * - **String ID**: Retrieves the skill from the database
+     * - **Class**: Creates an instance and adds to database if needed
+     * - **Object**: Uses directly and adds to database if needed
+     * 
+     * @param skillInput - Skill ID, class, or object to learn
+     * @returns The learned skill data
+     * @throws SkillLog.alreadyLearned if the skill is already known
+     * 
+     * @example
+     * ```ts
+     * // From database
+     * player.learnSkill('fire');
+     * 
+     * // From class
+     * player.learnSkill(FireSkill);
+     * 
+     * // From object
+     * player.learnSkill({
+     *   id: 'custom-skill',
+     *   name: 'Custom Skill',
+     *   spCost: 20,
+     *   onLearn(player) {
+     *     console.log('Learned custom skill!');
+     *   }
+     * });
+     * ```
+     */
+    learnSkill(skillInput) {
+      const map = this.getCurrentMap() || this.map;
+      let skillId = "";
+      let skillData;
+      if (isString(skillInput)) {
+        skillId = skillInput;
+        skillData = this.databaseById(skillId);
+      } else if (typeof skillInput === "function") {
+        const SkillClassCtor = skillInput;
+        skillId = SkillClassCtor.id || SkillClassCtor.name;
+        const existingData = map?.database()?.[skillId];
+        if (existingData) {
+          skillData = existingData;
+        } else if (map) {
+          map.addInDatabase(skillId, SkillClassCtor);
+          skillData = SkillClassCtor;
+        } else {
+          skillData = SkillClassCtor;
+        }
+        const skillInstance = new SkillClassCtor();
+        skillData = { ...skillData, ...skillInstance, id: skillId };
+      } else {
+        const skillObj = skillInput;
+        skillId = skillObj.id || `skill-${Date.now()}`;
+        skillObj.id = skillId;
+        const existingData = map?.database()?.[skillId];
+        if (existingData) {
+          skillData = { ...existingData, ...skillObj };
+          if (map) {
+            map.addInDatabase(skillId, skillData, { force: true });
+          }
+        } else if (map) {
+          map.addInDatabase(skillId, skillObj);
+          skillData = skillObj;
+        } else {
+          skillData = skillObj;
+        }
+      }
       if (this.getSkill(skillId)) {
-        throw SkillLog.alreadyLearned(skillId);
+        throw SkillLog.alreadyLearned(skillData);
       }
-      const instance = this.databaseById(skillId);
-      this.skills().push(instance);
-      this["execMethod"]("onLearn", [this], instance);
-      return instance;
+      this.skills().push(skillData);
+      this["execMethod"]("onLearn", [this], skillData);
+      return skillData;
     }
-    forgetSkill(skillId) {
-      if (isString(skillId)) skillId = this.databaseById(skillId);
-      const index = this._getSkillIndex(skillId);
-      if (index == -1) {
-        throw SkillLog.notLearned(skillId);
+    /**
+     * Forget a learned skill
+     * 
+     * Removes a skill from the player's skill list.
+     * 
+     * @param skillInput - Skill ID, class, or object to forget
+     * @returns The forgotten skill data
+     * @throws SkillLog.notLearned if the skill is not known
+     * 
+     * @example
+     * ```ts
+     * player.forgetSkill('fire');
+     * // or
+     * player.forgetSkill(FireSkill);
+     * ```
+     */
+    forgetSkill(skillInput) {
+      const index = this._getSkillIndex(skillInput);
+      if (index === -1) {
+        let skillData2 = skillInput;
+        if (isString(skillInput)) {
+          try {
+            skillData2 = this.databaseById(skillInput);
+          } catch {
+            skillData2 = { name: skillInput, id: skillInput };
+          }
+        } else if (typeof skillInput === "function") {
+          skillData2 = { name: skillInput.name, id: skillInput.id || skillInput.name };
+        }
+        throw SkillLog.notLearned(skillData2);
       }
-      const instance = this.skills()[index];
+      const skillData = this.skills()[index];
       this.skills().splice(index, 1);
-      this["execMethod"]("onForget", [this], instance);
-      return instance;
+      this["execMethod"]("onForget", [this], skillData);
+      return skillData;
     }
-    useSkill(skillId, otherPlayer) {
-      const skill = this.getSkill(skillId);
+    /**
+     * Use a learned skill
+     * 
+     * Executes a skill, consuming SP and applying effects to targets.
+     * The skill must be learned and the player must have enough SP.
+     * 
+     * @param skillInput - Skill ID, class, or object to use
+     * @param otherPlayer - Optional target player(s) to apply skill effects to
+     * @returns The used skill data
+     * @throws SkillLog.restriction if player has CAN_NOT_SKILL effect
+     * @throws SkillLog.notLearned if skill is not known
+     * @throws SkillLog.notEnoughSp if not enough SP
+     * @throws SkillLog.chanceToUseFailed if hit rate check fails
+     * 
+     * @example
+     * ```ts
+     * // Use skill without target
+     * player.useSkill('fire');
+     * 
+     * // Use skill on a target
+     * player.useSkill('fire', enemy);
+     * 
+     * // Use skill on multiple targets
+     * player.useSkill('fire', [enemy1, enemy2]);
+     * ```
+     */
+    useSkill(skillInput, otherPlayer) {
+      const skill = this.getSkill(skillInput);
       if (this.hasEffect(Effect.CAN_NOT_SKILL)) {
-        throw SkillLog.restriction(skillId);
+        throw SkillLog.restriction(skill || skillInput);
       }
       if (!skill) {
-        throw SkillLog.notLearned(skillId);
+        throw SkillLog.notLearned(skillInput);
       }
-      if (skill.spCost > this.sp) {
-        throw SkillLog.notEnoughSp(skillId, skill.spCost, this.sp);
+      const spCost = skill.spCost || 0;
+      if (spCost > this.sp) {
+        throw SkillLog.notEnoughSp(skill, spCost, this.sp);
       }
-      this.sp -= skill.spCost / (this.hasEffect(Effect.HALF_SP_COST) ? 2 : 1);
+      const costMultiplier = this.hasEffect(Effect.HALF_SP_COST) ? 2 : 1;
+      this.sp -= spCost / costMultiplier;
       const hitRate = skill.hitRate ?? 1;
       if (Math.random() > hitRate) {
         this["execMethod"]("onUseFailed", [this, otherPlayer], skill);
-        throw SkillLog.chanceToUseFailed(skillId);
+        throw SkillLog.chanceToUseFailed(skill);
       }
       if (otherPlayer) {
-        let players = otherPlayer;
-        if (!isArray(players)) {
-          players = [otherPlayer];
-        }
-        for (let player of players) {
+        const players = isArray(otherPlayer) ? otherPlayer : [otherPlayer];
+        for (const player of players) {
           this.applyStates(player, skill);
           player.applyDamage(this, skill);
         }
@@ -20941,6 +21719,8 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
    * When `nbTimes` is set to a finite number, the animation will play that many times
    * before returning to the previous animation state.
    * 
+   * If `animationFixed` is true, this method will not change the animation.
+   * 
    * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
    * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
    * 
@@ -20952,14 +21732,18 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
    * // Play attack animation 3 times then return to previous state
    * player.setAnimation('attack', 3);
    * 
-   * // Play skill animation once
-   * player.setAnimation('skill', 1);
+   * // Lock animation to prevent automatic changes
+   * player.animationFixed = true;
+   * player.setAnimation('skill'); // This will be ignored
    * 
    * // Set idle/stand animation
    * player.setAnimation('stand');
    * ```
    */
   setAnimation(animationName, nbTimes = Infinity) {
+    if (this.animationFixed) {
+      return;
+    }
     const map2 = this.getCurrentMap();
     if (!map2) return;
     if (nbTimes === Infinity) {
@@ -21559,9 +22343,16 @@ class RpgEvent extends RpgPlayer {
     const ret = instance[methodName](...methodData);
     return ret;
   }
+  /**
+   * Remove this event from the map
+   * 
+   * Stops all movements before removing to prevent "unable to resolve entity" errors
+   * from the MovementManager when the entity is destroyed while moving.
+   */
   remove() {
     const map2 = this.getCurrentMap();
     if (!map2) return;
+    this.stopMoveTo();
     map2.removeEvent(this.id);
   }
   isEvent() {
@@ -25983,9 +26774,17 @@ let RpgMap = class extends RpgCommonMap {
   setupCollisionDetection() {
     const activeCollisions = /* @__PURE__ */ new Set();
     const activeShapeCollisions = /* @__PURE__ */ new Set();
+    const hasDifferentZ = (entityA, entityB) => {
+      const zA = entityA.owner.z();
+      const zB = entityB.owner.z();
+      return zA !== zB;
+    };
     this.physic.getEvents().onCollisionEnter((collision) => {
       const entityA = collision.entityA;
       const entityB = collision.entityB;
+      if (hasDifferentZ(entityA, entityB)) {
+        return;
+      }
       const collisionKey = entityA.uuid < entityB.uuid ? `${entityA.uuid}-${entityB.uuid}` : `${entityB.uuid}-${entityA.uuid}`;
       if (activeCollisions.has(collisionKey)) {
         return;
@@ -26025,6 +26824,9 @@ let RpgMap = class extends RpgCommonMap {
     this.physic.getEvents().onCollisionExit((collision) => {
       const entityA = collision.entityA;
       const entityB = collision.entityB;
+      if (hasDifferentZ(entityA, entityB)) {
+        return;
+      }
       const collisionKey = entityA.uuid < entityB.uuid ? `${entityA.uuid}-${entityB.uuid}` : `${entityB.uuid}-${entityA.uuid}`;
       const shapeA = this._shapeEntities.get(entityA.uuid);
       const shapeB = this._shapeEntities.get(entityB.uuid);