@rpgjs/common 4.2.1 → 5.0.0-alpha.0

package/src/movement/MovementManager.ts

@@ -0,0 +1,142 @@
+import * as Matter from 'matter-js';
+import { MovementStrategy } from './MovementStrategy';
+import { RpgCommonPhysic } from '../Physic';
+
+/**
+ * Manager for entity movement strategies
+ * 
+ * Handles the execution and lifecycle of all movement strategies
+ * for entities in the game world.
+ * 
+ * @example
+ * ```ts
+ * // In game loop
+ * const movementManager = new MovementManager();
+ * 
+ * // Add dash movement to player
+ * movementManager.add('player1', new Dash(200, { x: 1, y: 0 }, 300));
+ * 
+ * // Update in game loop
+ * function gameLoop(dt) {
+ *   movementManager.update(dt, physic);
+ *   physic.update(dt);
+ * }
+ * ```
+ */
+export class MovementManager {
+  /** Map of entity IDs to their active movement strategies */
+  private strategies: Map<string, MovementStrategy[]> = new Map();
+
+  /**
+   * Add a movement strategy to an entity
+   * 
+   * @param id - Entity ID
+   * @param strategy - Movement strategy to apply
+   */
+  add(id: string, strategy: MovementStrategy): void {
+    if (!this.strategies.has(id)) {
+      this.strategies.set(id, []);
+    }
+    
+    this.strategies.get(id)!.push(strategy);
+  }
+
+  /**
+   * Remove a specific movement strategy from an entity
+   * 
+   * @param id - Entity ID
+   * @param strategy - The strategy instance to remove
+   * @returns True if the strategy was found and removed
+   */
+  remove(id: string, strategy: MovementStrategy): boolean {
+    const entityStrategies = this.strategies.get(id);
+    if (!entityStrategies) return false;
+    
+    const index = entityStrategies.indexOf(strategy);
+    if (index === -1) return false;
+    
+    entityStrategies.splice(index, 1);
+    return true;
+  }
+
+  /**
+   * Remove all movement strategies from an entity
+   * 
+   * @param id - Entity ID
+   */
+  clear(id: string): void {
+    this.strategies.delete(id);
+  }
+
+  /**
+   * Check if an entity has any active movement strategies
+   * 
+   * @param id - Entity ID
+   * @returns True if entity has active strategies
+   * 
+   * @example
+   * ```ts
+   * // Check if player has active movements
+   * if (movementManager.hasActiveStrategies('player1')) {
+   *   // Don't accept input while movements are active
+   * }
+   * ```
+   */
+  hasActiveStrategies(id: string): boolean {
+    const entityStrategies = this.strategies.get(id);
+    return Boolean(entityStrategies && entityStrategies.length > 0);
+  }
+
+  /**
+   * Get all active movement strategies for an entity
+   * 
+   * @param id - Entity ID
+   * @returns Array of active strategies or empty array if none
+   * 
+   * @example
+   * ```ts
+   * // Get all player movements
+   * const movements = movementManager.getStrategies('player1');
+   * ```
+   */
+  getStrategies(id: string): MovementStrategy[] {
+    return this.strategies.get(id) || [];
+  }
+
+  /**
+   * Update all movement strategies
+   * Must be called BEFORE physics.update()
+   * 
+   * @param dt - Time delta in milliseconds
+   * @param physic - Physics system to get bodies from
+   */
+  update(dt: number, physic: RpgCommonPhysic): void {
+    for (const [id, strategies] of this.strategies.entries()) {
+      // Skip if no strategies
+      if (strategies.length === 0) {
+        this.strategies.delete(id);
+        continue;
+      }
+      
+      // Get the body for this entity
+      const body = physic.getBody(id);
+      if (!body) continue;
+      
+      // Update each strategy and remove finished ones
+      for (let i = strategies.length - 1; i >= 0; i--) {
+        const strategy = strategies[i];
+        
+        // Apply the movement logic
+        strategy.update(body, dt);
+        
+        // Check if movement is finished
+        if (strategy.isFinished?.()) {
+          strategies.splice(i, 1);
+          
+          // Trigger onFinished callback if present
+          strategy.onFinished?.();
+        }
+      }
+    }
+  }
+} 

package/src/movement/MovementStrategy.ts

@@ -0,0 +1,42 @@
+import * as Matter from 'matter-js';
+
+/**
+ * Interface defining the contract for movement strategies
+ * 
+ * Movement strategies are responsible for calculating how a body should move
+ * each frame without directly modifying the physics engine.
+ * 
+ * @example
+ * ```ts
+ * class SimpleMove implements MovementStrategy {
+ *   constructor(private vx: number, private vy: number) {}
+ *   
+ *   update(body: Matter.Body, dt: number): void {
+ *     Matter.Body.setVelocity(body, { x: this.vx, y: this.vy });
+ *   }
+ * }
+ * ```
+ */
+export interface MovementStrategy {
+  /**
+   * Called each frame BEFORE the physics engine update
+   * Calculates and applies movement to the provided body
+   * 
+   * @param body - The Matter.js body to move
+   * @param dt - Time delta in milliseconds
+   */
+  update(body: Matter.Body, dt: number): void;
+  
+  /**
+   * Returns true when the movement is finished (optional)
+   * If implemented, the strategy will be automatically removed
+   * from the movement manager when it returns true
+   */
+  isFinished?(): boolean;
+  
+  /**
+   * Event triggered when the movement completes (optional)
+   * Useful for chaining movements
+   */
+  onFinished?(): void;
+} 

package/src/movement/index.ts

@@ -0,0 +1,15 @@
+// Movement system core
+export * from './MovementStrategy';
+export * from './MovementManager';
+
+// Movement strategies
+export * from './strategies/LinearMove';
+export * from './strategies/Dash';
+export * from './strategies/Knockback';
+export * from './strategies/PathFollow';
+export * from './strategies/Oscillate';
+export * from './strategies/CompositeMovement';
+export * from './strategies/SeekAvoid';
+export * from './strategies/LinearRepulsion';
+export * from './strategies/IceMovement';
+export * from './strategies/ProjectileMovement'; 

package/src/movement/strategies/CompositeMovement.ts

@@ -0,0 +1,173 @@
+import * as Matter from 'matter-js';
+import { MovementStrategy } from '../MovementStrategy';
+
+/**
+ * Combines multiple movement strategies into a single movement
+ * 
+ * Allows composition of movement patterns by either:
+ * - Running multiple strategies in parallel (adding their effects)
+ * - Running strategies in sequence (one after another)
+ * 
+ * @example
+ * ```ts
+ * // Parallel movement (oscillate while following a path)
+ * const composite = new CompositeMovement('parallel', [
+ *   new PathFollow(waypoints, 2),
+ *   new Oscillate({ x: 0, y: 1 }, 10, 1000)
+ * ]);
+ * 
+ * // Sequential movement (dash, then knockback)
+ * const sequence = new CompositeMovement('sequence', [
+ *   new Dash(8, { x: 1, y: 0 }, 200),
+ *   new Knockback({ x: -0.5, y: 0 }, 3, 300)
+ * ]);
+ * 
+ * movementManager.add('entity1', composite);
+ * ```
+ */
+export class CompositeMovement implements MovementStrategy {
+  private currentStrategyIndex: number = 0;
+  
+  /**
+   * Create a composite movement
+   * 
+   * @param mode - How to combine strategies ('parallel' or 'sequence')
+   * @param strategies - Array of movement strategies to combine
+   */
+  constructor(
+    private mode: 'parallel' | 'sequence',
+    private strategies: MovementStrategy[]
+  ) {}
+  
+  /**
+   * Apply the composite movement
+   * 
+   * @param body - Matter.js body to move
+   * @param dt - Time delta in milliseconds
+   */
+  update(body: Matter.Body, dt: number): void {
+    if (this.strategies.length === 0) return;
+    
+    if (this.mode === 'parallel') {
+      // Update all strategies simultaneously
+      // Their effects will be combined by the physics engine
+      this.updateParallel(body, dt);
+    } else {
+      // Update strategies in sequence
+      this.updateSequence(body, dt);
+    }
+  }
+  
+  /**
+   * Update all strategies in parallel
+   */
+  private updateParallel(body: Matter.Body, dt: number): void {
+    // Make a copy of the array since we might remove elements during iteration
+    const currentStrategies = [...this.strategies];
+    
+    // Track original velocity to combine movement effects
+    const originalVelocity = { x: body.velocity.x, y: body.velocity.y };
+    let velocitiesApplied = 0;
+    
+    // Apply each strategy
+    for (let i = currentStrategies.length - 1; i >= 0; i--) {
+      const strategy = currentStrategies[i];
+      
+      // Store velocity before strategy update
+      const beforeVx = body.velocity.x;
+      const beforeVy = body.velocity.y;
+      
+      // Apply the strategy
+      strategy.update(body, dt);
+      
+      // Track if velocity was changed
+      if (beforeVx !== body.velocity.x || beforeVy !== body.velocity.y) {
+        velocitiesApplied++;
+      }
+      
+      // Remove finished strategies
+      if (strategy.isFinished?.()) {
+        this.strategies.splice(this.strategies.indexOf(strategy), 1);
+        strategy.onFinished?.();
+      }
+    }
+    
+    // If multiple strategies applied velocities, calculate the average
+    if (velocitiesApplied > 1) {
+      Matter.Body.setVelocity(body, {
+        x: (body.velocity.x + originalVelocity.x) / 2,
+        y: (body.velocity.y + originalVelocity.y) / 2
+      });
+    }
+  }
+  
+  /**
+   * Update strategies in sequence
+   */
+  private updateSequence(body: Matter.Body, dt: number): void {
+    if (this.currentStrategyIndex >= this.strategies.length) {
+      return;
+    }
+    
+    const currentStrategy = this.strategies[this.currentStrategyIndex];
+    
+    // Apply the current strategy
+    currentStrategy.update(body, dt);
+    
+    // Check if current strategy is finished
+    if (currentStrategy.isFinished?.()) {
+      // Trigger completion callback
+      currentStrategy.onFinished?.();
+      
+      // Move to next strategy
+      this.currentStrategyIndex++;
+    }
+  }
+  
+  /**
+   * Check if all strategies have finished
+   * 
+   * @returns True if all strategies are completed
+   */
+  isFinished(): boolean {
+    if (this.strategies.length === 0) return true;
+    
+    if (this.mode === 'parallel') {
+      // In parallel mode, we're finished when all strategies are finished
+      return this.strategies.length === 0;
+    } else {
+      // In sequence mode, we're finished when we've gone through all strategies
+      return this.currentStrategyIndex >= this.strategies.length;
+    }
+  }
+  
+  /**
+   * Add a new strategy to the composite
+   * 
+   * @param strategy - Movement strategy to add
+   */
+  add(strategy: MovementStrategy): void {
+    this.strategies.push(strategy);
+  }
+  
+  /**
+   * Remove a strategy from the composite
+   * 
+   * @param strategy - Movement strategy to remove
+   * @returns True if the strategy was found and removed
+   */
+  remove(strategy: MovementStrategy): boolean {
+    const index = this.strategies.indexOf(strategy);
+    if (index === -1) return false;
+    
+    this.strategies.splice(index, 1);
+    return true;
+  }
+  
+  /**
+   * Reset the composite to start from the beginning
+   */
+  reset(): void {
+    this.currentStrategyIndex = 0;
+  }
+} 

package/src/movement/strategies/Dash.ts

@@ -0,0 +1,82 @@
+import * as Matter from 'matter-js';
+import { MovementStrategy } from '../MovementStrategy';
+
+/**
+ * Implements a dash movement in a specified direction for a limited time
+ * 
+ * Dash applies high velocity movement in a direction for a short duration
+ * 
+ * @example
+ * ```ts
+ * // Dash right for 200ms at speed 10
+ * movementManager.add('player1', new Dash(10, { x: 1, y: 0 }, 200));
+ * 
+ * // Dash diagonally (normalized)
+ * movementManager.add('player1', new Dash(8, { x: 0.7071, y: 0.7071 }, 150));
+ * ```
+ */
+export class Dash implements MovementStrategy {
+  private elapsed: number = 0;
+  private finished: boolean = false;
+  
+  /**
+   * Create a dash movement
+   * 
+   * @param speed - Movement speed (pixels per frame)
+   * @param direction - Normalized direction vector { x, y }
+   * @param duration - Duration in milliseconds
+   */
+  constructor(
+    private speed: number,
+    private direction: { x: number, y: number },
+    private duration: number
+  ) {
+    // Normalize direction vector if not already normalized
+    const magnitude = Math.sqrt(direction.x * direction.x + direction.y * direction.y);
+    if (magnitude !== 0 && magnitude !== 1) {
+      this.direction = {
+        x: direction.x / magnitude,
+        y: direction.y / magnitude
+      };
+    }
+  }
+  
+  /**
+   * Apply dash movement to the body
+   * 
+   * @param body - Matter.js body to move
+   * @param dt - Time delta in milliseconds
+   */
+  update(body: Matter.Body, dt: number): void {
+    this.elapsed += dt;
+    
+    if (this.elapsed <= this.duration) {
+      // Apply dash velocity
+      Matter.Body.setVelocity(body, {
+        x: this.direction.x * this.speed,
+        y: this.direction.y * this.speed
+      });
+    } else {
+      // Stop the body when dash is complete
+      Matter.Body.setVelocity(body, { x: 0, y: 0 });
+      this.finished = true;
+    }
+  }
+  
+  /**
+   * Check if dash duration has elapsed
+   * 
+   * @returns True if dash is complete
+   */
+  isFinished(): boolean {
+    return this.finished;
+  }
+  
+  /**
+   * Optional callback for when dash completes
+   * Can be used to chain into another movement
+   */
+  onFinished(): void {
+    // Optional event hook for dash completion
+  }
+} 

package/src/movement/strategies/IceMovement.ts

@@ -0,0 +1,158 @@
+import * as Matter from 'matter-js';
+import { MovementStrategy } from '../MovementStrategy';
+
+/**
+ * Implements a slippery movement for icy surfaces
+ * 
+ * Creates a realistic ice-physics effect with:
+ * - Slow acceleration when starting to move
+ * - Slippery inertia when stopping
+ * - Gradual turning with momentum
+ * 
+ * @example
+ * ```ts
+ * // Apply ice movement to player on ice terrain
+ * movementManager.add('player1', new IceMovement({ x: 1, y: 0 }, 5));
+ * 
+ * // Update direction when player changes direction
+ * iceMovement.setTargetDirection({ x: 0, y: 1 });
+ * ```
+ */
+export class IceMovement implements MovementStrategy {
+  // Current velocity components
+  private currentVx: number = 0;
+  private currentVy: number = 0;
+  
+  // Flags
+  private stopped: boolean = false;
+  private elapsed: number = 0;
+  
+  /**
+   * Create an ice movement behavior
+   * 
+   * @param targetDirection - Desired movement direction (normalized vector)
+   * @param maxSpeed - Maximum speed when fully accelerated
+   * @param acceleration - Acceleration rate (0-1, lower = more slippery start)
+   * @param friction - Friction rate (0-1, lower = more slippery stop)
+   * @param duration - Optional duration limit for the movement
+   */
+  constructor(
+    private targetDirection: { x: number, y: number },
+    private maxSpeed: number = 4,
+    private acceleration: number = 0.15,
+    private friction: number = 0.05,
+    private duration?: number
+  ) {
+    // Normalize direction
+    this.normalizeDirection();
+  }
+  
+  /**
+   * Update the ice movement physics
+   * 
+   * @param body - Matter.js body to move
+   * @param dt - Time delta in milliseconds
+   */
+  update(body: Matter.Body, dt: number): void {
+    // Update elapsed time if duration is set
+    if (this.duration !== undefined) {
+      this.elapsed += dt;
+      if (this.elapsed >= this.duration) {
+        this.stopped = true;
+      }
+    }
+    
+    // Handle acceleration and friction physics
+    if (!this.stopped) {
+      // Accelerate gradually toward target speed in target direction
+      this.currentVx += (this.targetDirection.x * this.maxSpeed - this.currentVx) * this.acceleration;
+      this.currentVy += (this.targetDirection.y * this.maxSpeed - this.currentVy) * this.acceleration;
+    } else {
+      // Apply friction to gradually slow down
+      this.currentVx *= (1 - this.friction);
+      this.currentVy *= (1 - this.friction);
+    }
+    
+    // Apply the calculated velocity
+    Matter.Body.setVelocity(body, {
+      x: this.currentVx,
+      y: this.currentVy
+    });
+  }
+  
+  /**
+   * Check if movement is finished
+   * (movement is considered finished when almost stopped)
+   * 
+   * @returns True if movement is effectively stopped
+   */
+  isFinished(): boolean {
+    const speed = Math.hypot(this.currentVx, this.currentVy);
+    
+    // Movement is finished when:
+    // 1. We're in stopped state AND 
+    // 2. Speed is negligible (< 0.05)
+    return this.stopped && speed < 0.05;
+  }
+  
+  /**
+   * Stop the movement (will start applying friction)
+   */
+  stop(): void {
+    this.stopped = true;
+  }
+  
+  /**
+   * Resume movement in the current direction
+   */
+  resume(): void {
+    this.stopped = false;
+  }
+  
+  /**
+   * Set a new target direction
+   * The actual movement will gradually change toward this direction
+   * 
+   * @param direction - New target direction
+   */
+  setTargetDirection(direction: { x: number, y: number }): void {
+    this.targetDirection = direction;
+    this.normalizeDirection();
+    
+    // If we were stopped, resume movement
+    this.stopped = false;
+  }
+  
+  /**
+   * Set movement parameters
+   * 
+   * @param maxSpeed - New maximum speed
+   * @param acceleration - New acceleration rate
+   * @param friction - New friction rate
+   */
+  setParameters(maxSpeed?: number, acceleration?: number, friction?: number): void {
+    if (maxSpeed !== undefined) this.maxSpeed = maxSpeed;
+    if (acceleration !== undefined) this.acceleration = acceleration;
+    if (friction !== undefined) this.friction = friction;
+  }
+  
+  /**
+   * Normalize the direction vector
+   */
+  private normalizeDirection(): void {
+    const magnitude = Math.sqrt(
+      this.targetDirection.x * this.targetDirection.x + 
+      this.targetDirection.y * this.targetDirection.y
+    );
+    
+    if (magnitude > 0) {
+      this.targetDirection = {
+        x: this.targetDirection.x / magnitude,
+        y: this.targetDirection.y / magnitude
+      };
+    } else {
+      // Default to no direction
+      this.targetDirection = { x: 0, y: 0 };
+    }
+  }
+} 

package/src/movement/strategies/Knockback.ts

@@ -0,0 +1,81 @@
+import * as Matter from 'matter-js';
+import { MovementStrategy } from '../MovementStrategy';
+
+/**
+ * Implements a knockback effect with decreasing force over time
+ * 
+ * Applies an initial velocity that gradually decreases to simulate
+ * being pushed back by an impact
+ * 
+ * @example
+ * ```ts
+ * // Knockback player to the left with force 8 for 300ms
+ * movementManager.add('player1', new Knockback({ x: -1, y: 0 }, 8, 300));
+ * 
+ * // Knockback with decay (resistance)
+ * movementManager.add('enemy1', new Knockback({ x: 0, y: 1 }, 5, 200, 0.9));
+ * ```
+ */
+export class Knockback implements MovementStrategy {
+  private elapsed: number = 0;
+  private currentSpeed: number;
+  
+  /**
+   * Create a knockback movement
+   * 
+   * @param direction - Normalized direction vector { x, y }
+   * @param force - Initial force of the knockback
+   * @param duration - Duration in milliseconds
+   * @param decayFactor - Speed decay multiplier per frame (0.8-0.95 typical)
+   */
+  constructor(
+    private direction: { x: number, y: number },
+    private force: number,
+    private duration: number,
+    private decayFactor: number = 0.9
+  ) {
+    this.currentSpeed = force;
+    
+    // Normalize direction vector
+    const magnitude = Math.sqrt(direction.x * direction.x + direction.y * direction.y);
+    if (magnitude !== 0 && magnitude !== 1) {
+      this.direction = {
+        x: direction.x / magnitude,
+        y: direction.y / magnitude
+      };
+    }
+  }
+  
+  /**
+   * Apply knockback movement with decreasing force
+   * 
+   * @param body - Matter.js body to move
+   * @param dt - Time delta in milliseconds
+   */
+  update(body: Matter.Body, dt: number): void {
+    this.elapsed += dt;
+    
+    if (this.elapsed <= this.duration) {
+      // Apply decreasing velocity
+      Matter.Body.setVelocity(body, {
+        x: this.direction.x * this.currentSpeed,
+        y: this.direction.y * this.currentSpeed
+      });
+      
+      // Decay the speed
+      this.currentSpeed *= this.decayFactor;
+    } else {
+      // Stop movement when knockback is complete
+      Matter.Body.setVelocity(body, { x: 0, y: 0 });
+    }
+  }
+  
+  /**
+   * Check if knockback duration has elapsed
+   * 
+   * @returns True if knockback is complete
+   */
+  isFinished(): boolean {
+    return this.elapsed >= this.duration;
+  }
+}