@caperjs/plugin-crunch 0.1.0

package/src/Group.ts

@@ -0,0 +1,181 @@
+import { Actor } from './Actor';
+import { Entity } from './Entity';
+import { Sensor } from './Sensor';
+import { Solid } from './Solid';
+import { EntityData, PhysicsEntityType } from './types';
+
+/**
+ * A container for managing collections of physics entities that move together.
+ * Groups are useful for creating compound objects, moving platforms with riders,
+ * and other scenarios where multiple entities need to move as one unit.
+ *
+ * Features:
+ * - Maintains relative positioning of child entities
+ * - Supports actors, solids, and sensors as children
+ * - Preserves world positions when adding entities
+ * - Provides type-safe access to children by entity type
+ *
+ * @typeParam T - Application type, defaults to base Application
+ *
+ * @example
+ * ```typescript
+ * // Create a moving platform with obstacles
+ * const platformGroup = physics.createGroup({
+ *   type: 'MovingPlatform',
+ *   position: [100, 300]
+ * });
+ *
+ * // Add platform and spikes
+ * const platform = physics.createSolid({
+ *   type: 'Platform',
+ *   size: [200, 32]
+ * });
+ *
+ * const spikes = physics.createSensor({
+ *   type: 'Spikes',
+ *   position: [0, -32],
+ *   size: [200, 32]
+ * });
+ *
+ * platformGroup.add(platform);
+ * platformGroup.add(spikes);
+ *
+ * // Move the entire group
+ * gsap.to(platformGroup, {
+ *   x: 500,
+ *   duration: 2,
+ *   yoyo: true,
+ *   repeat: -1
+ * });
+ * ```
+ */
+export class Group<D extends EntityData = EntityData> extends Entity<D> {
+  protected _visible: boolean = true;
+
+  public entityType: PhysicsEntityType = 'Group';
+  /** Map of child entities to their relative offsets from the group's position */
+  private childOffsets: Map<Entity, { x: number; y: number }> = new Map();
+  /** Whether this group's position is static (not affected by physics) */
+  public isStatic: boolean = true;
+
+  /**
+   * Gets the relative offset of a child entity from the group's position.
+   * @param entity - The child entity to get the offset for
+   * @returns The relative {x, y} offset of the entity
+   */
+  public getChildOffset(entity: Entity): { x: number; y: number } {
+    return this.childOffsets.get(entity) ?? { x: 0, y: 0 };
+  }
+
+  set visible(value: boolean) {
+    this.system.getEntitiesInGroup(this).forEach((entity) => {
+      entity.view.visible = value;
+    });
+  }
+
+  get visible(): boolean {
+    return this._visible;
+  }
+
+  /**
+   * Sets the group's X position, affecting all child entities.
+   */
+  set x(value: number) {
+    this._x = value;
+  }
+
+  get x(): number {
+    return this._x;
+  }
+
+  /**
+   * Sets the group's Y position, affecting all child entities.
+   */
+  set y(value: number) {
+    this._y = value;
+  }
+
+  get y(): number {
+    return this._y;
+  }
+
+  /**
+   * Add an entity to this container
+   * @param entity The entity to add
+   * @param preserveWorldPosition If true, the entity's world position will be preserved
+   */
+  public add(entity: Entity, offset: { x: number; y: number } = { x: 0, y: 0 }): Group {
+    entity.setGroup(this, offset);
+    return this;
+  }
+
+  /**
+   * Remove an entity from this container
+   */
+  public remove(entity: Entity): Group {
+    entity.setGroup(null);
+    return this;
+  }
+
+  /**
+   * Move the container and all its children
+   */
+  public move(x: number, y: number): void {
+    // Update container position
+    this._x += x;
+    this._y += y;
+
+    this.updateView();
+  }
+
+  /**
+   * Force move the container and all its children to an absolute position
+   */
+  public moveTo(x: number, y: number): void {
+    const dx = x - this.x;
+    const dy = y - this.y;
+    this.move(dx, dy);
+  }
+
+  /**
+   * Get all children of a specific type
+   */
+  public getChildrenByType<E extends Entity>(type: PhysicsEntityType): E[] {
+    return this.system
+      .getEntitiesInGroup(this)
+      .filter((child): child is E => child.entityType === type || child.type === type);
+  }
+
+  /**
+   * Get all actors in this container
+   */
+  public getActors(): Actor[] {
+    return this.getChildrenByType('Actor');
+  }
+
+  /**
+   * Get all solids in this container
+   */
+  public getSolids(): Solid[] {
+    return this.getChildrenByType('Solid');
+  }
+
+  /**
+   * Get all sensors in this container
+   */
+  public getSensors(): Sensor[] {
+    return this.getChildrenByType('Sensor');
+  }
+
+  /**
+   * Get all groups in this container
+   */
+  public getGroups(): Group[] {
+    return this.getChildrenByType('Group');
+  }
+
+  public destroy(): void {
+    this.system.removeGroup(this);
+    super.destroy();
+  }
+}

package/src/Sensor.ts

@@ -0,0 +1,427 @@
+import { Actor } from './Actor';
+import { Entity } from './Entity';
+import { Solid } from './Solid';
+import { EntityData, PhysicsEntityConfig, PhysicsEntityType, SensorOverlap, Vector2 } from './types';
+
+/**
+ * A trigger zone that can detect overlaps with actors.
+ * Sensors are typically used for collectibles, triggers, and detection zones.
+ *
+ * Features:
+ * - Overlap detection with specific actor types
+ * - Optional gravity and movement
+ * - Can be static or dynamic
+ * - Callbacks for enter/exit events
+ *
+ * @typeParam T - Application type, defaults to base Application
+ *
+ * @example
+ * ```typescript
+ * // Create a coin pickup sensor
+ * class Coin extends Sensor {
+ *   constructor() {
+ *     super({
+ *       type: 'Coin',
+ *       position: [100, 100],
+ *       size: [32, 32],
+ *       view: coinSprite
+ *     });
+ *
+ *     // Only detect overlaps with player
+ *     this.collidableTypes = ['Player'];
+ *   }
+ *
+ *   // Called when a player enters the coin
+ *   onActorEnter(actor: Actor) {
+ *     if (actor.type === 'Player') {
+ *       increaseScore(10);
+ *       this.physics.removeSensor(this);
+ *     }
+ *   }
+ * }
+ *
+ * // Create a damage zone
+ * class Spikes extends Sensor {
+ *   constructor() {
+ *     super({
+ *       type: 'Spikes',
+ *       position: [300, 500],
+ *       size: [100, 32],
+ *       view: spikesSprite
+ *     });
+ *
+ *     this.collidableTypes = ['Player', 'Enemy'];
+ *     this.isStatic = true; // Don't move or fall
+ *   }
+ *
+ *   onActorEnter(actor: Actor) {
+ *     if (actor.type === 'Player') {
+ *       actor.damage(10);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class Sensor<D extends EntityData = EntityData> extends Entity<D> {
+  public readonly entityType: PhysicsEntityType = 'Sensor';
+  /** Whether this sensor should be removed when culled */
+  public shouldRemoveOnCull = false;
+
+  /** List of actor types this sensor can detect */
+  public collidableTypes: string[] = [];
+
+  /** Current velocity in pixels per second */
+  public velocity: Vector2 = { x: 0, y: 0 };
+
+  /** Whether this sensor should stay in place */
+  public isStatic: boolean = false;
+
+  /** Set of actors currently overlapping this sensor */
+  private overlappingActors: Set<Actor> = new Set();
+
+  /** Cache for isRidingSolid check */
+  private _isRidingSolidCache: boolean | null = null;
+
+  private _currentSensorOverlaps = new Set<SensorOverlap>();
+  private _currentOverlaps = new Set<Actor>();
+
+  public setPosition(x: number, y: number): void {
+    if (this.isStatic) {
+      this._x = x;
+      this._y = y;
+      this._xRemainder = 0;
+      this._yRemainder = 0;
+      this.updateView();
+      this.checkActorOverlaps();
+    } else {
+      super.setPosition(x, y);
+    }
+  }
+
+  set x(value: number) {
+    super.x = value;
+    if (this.isStatic) {
+      this._xRemainder = 0;
+      this.updateView();
+      this.checkActorOverlaps();
+    }
+  }
+
+  get x(): number {
+    return super.x;
+  }
+
+  set y(value: number) {
+    super.y = value;
+    if (this.isStatic) {
+      this._yRemainder = 0;
+      this.updateView();
+      this.checkActorOverlaps();
+    }
+  }
+
+  get y(): number {
+    return super.y;
+  }
+
+  /**
+   * Initializes or reinitializes the sensor with new configuration.
+   *
+   * @param config - Configuration for the sensor
+   */
+  public init(config: PhysicsEntityConfig<D>): void {
+    super.init(config);
+    if (!this.velocity) {
+      this.velocity = { x: 0, y: 0 };
+    }
+    this.velocity.x = 0;
+    this.velocity.y = 0;
+    if (!this.overlappingActors) {
+      this.overlappingActors = new Set();
+    }
+    this._isRidingSolidCache = null;
+  }
+
+  /**
+   * Checks if this sensor is riding the given solid.
+   * Takes into account gravity direction for proper riding detection.
+   *
+   * @param solid - The solid to check against
+   * @returns True if riding the solid
+   */
+  public isRiding(solid: Solid): boolean {
+    const gravityDirection = Math.sign(this.system.gravity);
+    if (gravityDirection > 0) {
+      // Normal gravity - check if we're on top of the solid
+      const sensorBottom = this.y + this.height;
+      const onTop = Math.abs(sensorBottom - solid.y) <= 1;
+      const overlap = this.x + this.width > solid.x && this.x < solid.x + solid.width;
+      return onTop && overlap;
+    } else {
+      // Reversed gravity - check if we're on bottom of the solid
+      const sensorTop = this.y;
+      const onBottom = Math.abs(sensorTop - (solid.y + solid.height)) <= 1;
+      const overlap = this.x + this.width > solid.x && this.x < solid.x + solid.width;
+      return onBottom && overlap;
+    }
+  }
+
+  /**
+   * Checks if this sensor is riding any solid.
+   * Uses caching to optimize multiple checks per frame.
+   *
+   * @returns True if riding any solid
+   */
+  public isRidingSolid(): boolean {
+    // Return cached value if available
+    if (this._isRidingSolidCache !== null) {
+      return this._isRidingSolidCache;
+    }
+
+    // Calculate and cache the result
+    const solids = this.getSolidsAt(this.x, this.system.gravity > 0 ? this.y + 1 : this.y - 1);
+    this._isRidingSolidCache = solids.some((solid) => this.isRiding(solid));
+    return this._isRidingSolidCache;
+  }
+
+  /**
+   * Force moves the sensor to a new position, ignoring static state and collisions.
+   *
+   * @param x - New X position
+   * @param y - New Y position
+   */
+  public moveStatic(x: number, y: number): void {
+    this._x = x;
+    this._y = y;
+    this._xRemainder = 0;
+    this._yRemainder = 0;
+    this.updateView();
+    this.checkActorOverlaps();
+  }
+
+  /**
+   * Moves the sensor horizontally, passing through solids.
+   *
+   * @param amount - Distance to move in pixels
+   */
+  public moveX(amount: number): void {
+    if (this.isStatic) {
+      return;
+    }
+
+    this._xRemainder += amount;
+    const move = Math.round(this._xRemainder);
+
+    if (move !== 0) {
+      this._xRemainder -= move;
+      const sign = Math.sign(move);
+      let remaining = Math.abs(move);
+      while (remaining > 0) {
+        const step = sign;
+        const nextX = this.x + step;
+
+        // Check for collision with any solid
+        let collided = false;
+        for (const solid of this.getSolidsAt(nextX, this.y)) {
+          if (solid.canCollide) {
+            collided = true;
+            break;
+          }
+        }
+
+        if (!collided) {
+          this._x = nextX;
+          remaining--;
+          this.updateView();
+          this.checkActorOverlaps();
+        } else {
+          // Stop horizontal movement when hitting a solid
+          this.velocity.x = 0;
+          break;
+        }
+      }
+    }
+  }
+
+  /**
+   * Moves the sensor vertically, colliding with solids for riding.
+   *
+   * @param amount - Distance to move in pixels
+   */
+  public moveY(amount: number): void {
+    if (this.isStatic) {
+      return;
+    }
+
+    this._yRemainder += amount;
+    const move = Math.round(this._yRemainder);
+
+    if (move !== 0) {
+      this._yRemainder -= move;
+      const sign = Math.sign(move);
+
+      let remaining = Math.abs(move);
+      while (remaining > 0) {
+        const step = sign;
+        const nextY = this.y + step;
+
+        // Check for collision with any solid
+        let collided = false;
+        // Only check collisions when moving in the direction of gravity
+        if (Math.sign(this.system.gravity) === sign) {
+          for (const solid of this.getSolidsAt(this.x, nextY)) {
+            if (solid.canCollide) {
+              collided = true;
+              break;
+            }
+          }
+        }
+
+        if (!collided) {
+          this._y = nextY;
+          remaining--;
+          this.updateView();
+          this.checkActorOverlaps();
+        } else {
+          // Stop vertical movement when landing on a solid
+          this.velocity.y = 0;
+          break;
+        }
+      }
+    }
+  }
+
+  /**
+   * Updates the sensor's position and checks for overlapping actors.
+   *
+   * @param deltaTime - Delta time in seconds
+   */
+  public update(deltaTime: number): void {
+    // Reset the cache at the start of each update
+    this._isRidingSolidCache = null;
+
+    if (!this.active) {
+      return;
+    }
+
+    // Only apply gravity if not static and not riding a solid
+    if (!this.isStatic && !this.isRidingSolid()) {
+      this.velocity.y += this.system.gravity * deltaTime;
+    }
+
+    // Move
+    if (this.velocity.x !== 0) {
+      this.moveX(this.velocity.x * deltaTime);
+    }
+    if (this.velocity.y !== 0) {
+      this.moveY(this.velocity.y * deltaTime);
+    }
+  }
+
+  /**
+   * Checks for overlapping actors and triggers callbacks.
+   *
+   * @returns Set of current overlaps
+   */
+  public checkActorOverlaps(): Set<SensorOverlap> {
+    // Skip if sensor has no collision mask or is inactive
+    if (this.collisionMask === 0 || !this.active) {
+      return new Set();
+    }
+
+    this._currentSensorOverlaps.clear();
+    this._currentOverlaps.clear();
+
+    // Get all actors at current position - use spatial filtering first
+    // Only get actors that are potentially in the same grid cells
+
+    // Cache collision layer and mask for faster access
+    const sensorLayer = this.collisionLayer;
+    const sensorMask = this.collisionMask;
+
+    // Get actors by type, but only process those that could be nearby
+    const nearbyActors = this.system.getActorsByType(this.collidableTypes);
+
+    for (const actor of nearbyActors) {
+      // Skip inactive actors
+      if (!actor.active) continue;
+
+      // Fast collision layer check
+      if ((sensorLayer & actor.collisionMask) === 0 || (actor.collisionLayer & sensorMask) === 0) {
+        continue;
+      }
+
+      // Fast AABB check before detailed overlap
+      if (this.system.aabbOverlap(this, actor)) {
+        this._currentOverlaps.add(actor);
+        if (!this.overlappingActors.has(actor)) {
+          // New overlap
+          this._currentSensorOverlaps.add({
+            actor,
+            sensor: this,
+            type: `${actor.type}|${this.type}`,
+          });
+
+          this.onActorEnter(actor);
+        }
+      }
+    }
+
+    // Check for actors that are no longer overlapping
+    for (const actor of this.overlappingActors) {
+      if (!this._currentOverlaps.has(actor)) {
+        this.onActorExit(actor);
+      }
+    }
+
+    // Swap the sets to avoid unnecessary clear and forEach operations
+    const temp = this.overlappingActors;
+    this.overlappingActors = this._currentOverlaps;
+    this._currentOverlaps = temp;
+    this._currentOverlaps.clear();
+
+    return this._currentSensorOverlaps;
+  }
+
+  public reset(): void {
+    super.reset();
+    this._currentSensorOverlaps.clear();
+    this._currentOverlaps.clear();
+    this._isRidingSolidCache = null;
+    this.velocity = { x: 0, y: 0 };
+    this.overlappingActors = new Set();
+  }
+
+  /**
+   * Called when an actor starts overlapping with this sensor.
+   * Override this to handle overlap start events.
+   *
+   * @param actor - The actor that entered
+   */
+  public onActorEnter<A extends Actor = Actor>(actor: A): void {
+    // Override in subclass
+    void actor;
+  }
+
+  /**
+   * Called when an actor stops overlapping with this sensor.
+   * Override this to handle overlap end events.
+   *
+   * @param actor - The actor that exited
+   */
+  public onActorExit<A extends Actor = Actor>(actor: A): void {
+    // Override in subclass
+    void actor;
+  }
+
+  /**
+   * Gets all solids at the specified position.
+   *
+   * @param x - X position to check
+   * @param y - Y position to check
+   * @returns Array of solids at the position
+   */
+  protected getSolidsAt(x: number, y: number): Solid[] {
+    return this.system.getSolidsAt(x, y, this);
+  }
+}