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

package/dist/Player.d.ts

@@ -94,6 +94,70 @@ export declare abstract class RpgCommonPlayer {
     componentsRight: import('@signe/reactive').WritableSignal<string | null>;
     isConnected: import('@signe/reactive').WritableSignal<boolean>;
     private _intendedDirection;
+    private _directionFixed;
+    private _animationFixed;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: boolean);
+    /**
+     * 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(): boolean;
+    /**
+     * 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: boolean);
     pendingInputs: any[];
     /**
      * Change the player's facing direction
@@ -103,12 +167,18 @@ export declare abstract class RpgCommonPlayer {
      * 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
      *
      * @example
      * ```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: Direction): void;

package/dist/index.js

@@ -2542,8 +2542,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
    *
@@ -2551,6 +2624,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
    *
@@ -2558,9 +2633,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);
   }
   /**
@@ -3633,6 +3715,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;
   }
   /**
@@ -4179,9 +4263,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
    */
@@ -4190,7 +4311,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
@@ -6344,6 +6535,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
    */
@@ -6352,6 +6546,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);
   }
@@ -7515,20 +7712,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
@@ -7540,7 +7781,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;
     }
@@ -7619,13 +7860,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
    */
@@ -7637,14 +7886,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) {
@@ -9449,8 +9706,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);
@@ -10303,11 +10568,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;
@@ -10344,6 +10612,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;
   }
   /**