@caperjs/plugin-crunch 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Relish Interactive
+Copyright (c) 2026 Anthony Sapp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# Crunch Physics Plugin
+
+#### @caperjs/physics-crunch
+
+A lightweight, grid-based AABB physics plugin for Caper games. Optimized for 2D platformers and games requiring precise, pixel-perfect collisions.
+
+## Features
+
+- 🎯 Pixel-perfect AABB collision detection
+- 📦 Grid-based spatial partitioning for efficient collision checks
+- 🎮 Optimized for 2D platformers and action games
+- 🧩 System supports Actors (Dynamic), Solids (Static), and Sensors (Trigger - Dynamic or Static)
+- 🎨 Debug visualization tools
+- 🔄 Object pooling support
+- 🎬 Scene-based integration
+
+## Installation
+
+```bash
+npm install @caperjs/physics-crunch
+```
+
+## Quick Start
+
+```typescript
+// in caper.config.ts
+defineConfig({
+  //... other config
+  plugins: ['crunch', { autoLoad: false }],
+});
+
+// in your scene file
+import { Scene } from '@caperjs/core';
+
+// exports
+export const plugins = ['crunch']; // loads the plugin for your scene
+
+// in your scene class
+export default class MyCrunchScene extends Scene {
+  get physics() {
+    return this.app.getPlugin('crunch') as ICrunchPhysicsPlugin;
+  }
+
+  async initialize() {
+    await this.physics.initialize({
+      gridSize: 32,
+      gravity: 980,
+      maxVelocity: 1000,
+      debug: true,
+    });
+
+    // Create a player
+    const player = physics.createActor({
+      type: 'Player',
+      position: [100, 100],
+      size: [32, 64],
+    });
+
+    // Create a platform
+    const platform = physics.createSolid({
+      type: 'Platform',
+      position: [0, 500],
+      size: [800, 32],
+    });
+
+    // Create a coin pickup
+    const coin = physics.createSensor({
+      type: 'Coin',
+      position: [200, 400],
+      size: [32, 32],
+    });
+  }
+}
+```
+
+## Core Components
+
+### Actors
+
+Dynamic entities that can move and collide (players, enemies, projectiles).
+
+```typescript
+class Player extends Actor {
+  update(dt: number) {
+    // Custom movement logic
+    if (this.app.input.isKeyDown('ArrowRight')) {
+      this.velocity.x = 200;
+    }
+  }
+
+  onCollide(result: CollisionResult) {
+    // Handle collisions
+    if (result.solid.type === 'Spikes') {
+      this.die();
+    }
+  }
+}
+```
+
+### Solids
+
+Static or moving collision objects (platforms, walls, obstacles).
+
+```typescript
+// Create a moving platform
+const platform = physics.createSolid({
+  type: 'Platform',
+  position: [100, 300],
+  size: [200, 32],
+});
+
+// Animate platform movement
+gsap.to(platform, {
+  x: 500,
+  duration: 2,
+  yoyo: true,
+  repeat: -1,
+});
+```
+
+### Sensors
+
+Trigger zones for detecting overlaps (collectibles, checkpoints, damage zones).
+
+```typescript
+class Coin extends Sensor {
+  onActorEnter(actor: Actor) {
+    if (actor.type === 'Player') {
+      increaseScore(10);
+      this.physics.removeSensor(this);
+    }
+  }
+}
+```
+
+### Groups
+
+Containers for managing collections of entities that move together.
+
+```typescript
+// Create a moving platform with hazards
+const group = physics.createGroup({
+  type: 'MovingPlatform',
+  position: [100, 300],
+});
+
+const platform = physics.createSolid({
+  type: 'Platform',
+  size: [200, 32],
+});
+
+const spikes = physics.createSensor({
+  type: 'Spikes',
+  position: [0, -32],
+  size: [200, 32],
+});
+
+group.add(platform);
+group.add(spikes);
+```
+
+## Advanced Features
+
+### Spatial Partitioning
+
+The plugin uses a grid-based spatial partitioning system to efficiently handle collision detection:
+
+```typescript
+// Configure grid size for your game's scale
+physics.system.gridSize = 32;
+```
+
+### Debug Visualization
+
+Enable debug rendering to visualize collision boxes and the spatial grid:
+
+```typescript
+physics.system.debug = true;
+```
+
+### Collision Resolution
+
+Custom collision handling with type-based filtering:
+
+```typescript
+physics.system.setCollisionResolver((collisions) => {
+  for (const collision of collisions) {
+    // Handle specific collision types
+    if (collision.type === 'Player|Enemy') {
+      handlePlayerEnemyCollision(collision);
+    }
+  }
+});
+```
+
+## Performance Tips
+
+- Use appropriate grid sizes for your game's scale
+- Enable culling for large levels
+- Utilize object pooling for frequently created/destroyed entities
+- Use sensor overlaps instead of continuous collision checks where possible
+
+## License
+
+MIT © Caper

package/lib/Actor.d.ts

@@ -0,0 +1,227 @@
+import { Entity } from './Entity';
+import { Solid } from './Solid';
+import { ActorCollisionResult, CollisionResult, EntityData, PhysicsEntityConfig, PhysicsEntityType, Vector2 } from './types';
+/**
+ * Dynamic physics entity that can move and collide with other entities.
+ * Actors are typically used for players, enemies, projectiles, and other moving game objects.
+ *
+ * Features:
+ * - Velocity-based movement with gravity
+ * - Collision detection and response
+ * - Solid surface detection (riding)
+ * - Automatic culling when out of bounds
+ * - Actor-to-actor collision detection
+ *
+ * @typeParam T - Application type, defaults to base Application
+ *
+ * @example
+ * ```typescript
+ * // Create a player actor
+ * class Player extends Actor {
+ *   constructor() {
+ *     super({
+ *       type: 'Player',
+ *       position: [100, 100],
+ *       size: [32, 64],
+ *       view: playerSprite
+ *     });
+ *   }
+ *
+ *   // Handle collisions
+ *   onCollide(result: CollisionResult) {
+ *     if (result.solid.type === 'Spike') {
+ *       this.die();
+ *     }
+ *   }
+ *
+ *   // Handle actor-to-actor collisions
+ *   onActorCollide(result: ActorCollisionResult) {
+ *     if (result.actor.type === 'Enemy') {
+ *       this.takeDamage(10);
+ *     }
+ *   }
+ *
+ *   // Custom movement
+ *   update(dt: number) {
+ *     super.update(dt);
+ *
+ *     // Move left/right
+ *     if (this.app.input.isKeyDown('ArrowLeft')) {
+ *       this.velocity.x = -200;
+ *     } else if (this.app.input.isKeyDown('ArrowRight')) {
+ *       this.velocity.x = 200;
+ *     }
+ *
+ *     // Jump when on ground
+ *     if (this.app.input.isKeyPressed('Space') && this.isRidingSolid()) {
+ *       this.velocity.y = -400;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class Actor<D extends EntityData = EntityData> extends Entity<D> {
+    readonly entityType: PhysicsEntityType;
+    /** Current velocity in pixels per second */
+    velocity: Vector2;
+    /** Whether actor-to-actor collisions are disabled for this actor */
+    disableActorCollisions: boolean;
+    /** Whether the actor should be removed when culled (out of bounds) */
+    shouldRemoveOnCull: boolean;
+    /** List of current frame collisions */
+    collisions: CollisionResult[];
+    /** List of current frame actor-to-actor collisions */
+    actorCollisions: ActorCollisionResult[];
+    /** Cache for isRidingSolid check */
+    private _isRidingSolidCache;
+    /** Tracks which solid is currently carrying this actor in the current frame */
+    private _carriedBy;
+    private _carriedByOverlap;
+    /** Tracks the grid cells this actor currently occupies */
+    private _currentGridCells;
+    /**
+     * Initialize or reinitialize the actor with new configuration.
+     *
+     * @param config - Configuration for the actor
+     */
+    init(config: PhysicsEntityConfig<D>): void;
+    /**
+     * Called at the start of each update to prepare for collision checks.
+     */
+    preUpdate(): void;
+    /**
+     * Updates the actor's position based on velocity and handles collisions.
+     *
+     * @param dt - Delta time in seconds
+     */
+    update(dt: number): void;
+    /**
+     * Called after update to handle post-movement effects.
+     */
+    postUpdate(): void;
+    /**
+     * Resets the actor to its initial state.
+     */
+    reset(): void;
+    /**
+     * Called when the actor is culled (goes out of bounds).
+     * Override this to handle culling differently.
+     */
+    onCull(): void;
+    /**
+     * Called when this actor collides with a solid.
+     * Override this method to implement custom collision response.
+     *
+     * @param result - Information about the collision
+     */
+    onCollide(result: CollisionResult): void;
+    /**
+     * Called when this actor collides with another actor.
+     * Override this method to implement custom actor-to-actor collision response.
+     *
+     * @param result - Information about the actor collision
+     */
+    onActorCollide(result: ActorCollisionResult): void;
+    /**
+     * Checks if this actor is riding the given solid.
+     * An actor is riding if it's directly above the solid.
+     *
+     * @param solid - The solid to check against
+     * @returns True if riding the solid
+     */
+    isRiding(solid: Solid): boolean;
+    /**
+     * Checks if this actor is riding any solid in the physics system.
+     * Uses caching to optimize multiple checks per frame.
+     *
+     * @returns True if riding any solid
+     */
+    isRidingSolid(): boolean;
+    /**
+     * Called when the actor is squeezed between solids.
+     * Override this to handle squishing differently.
+     */
+    squish(result: CollisionResult): void;
+    /**
+     * Updates the actor's grid cells in the spatial partitioning system.
+     * This is called when the actor moves or when its size changes.
+     */
+    updateGridCells(): void;
+    /**
+     * Gets the current grid cells this actor occupies
+     */
+    get currentGridCells(): string[];
+    /**
+     * Sets the current grid cells this actor occupies
+     */
+    set currentGridCells(cells: string[]);
+    /**
+     * Moves the actor horizontally, checking for collisions with solids.
+     *
+     * @param amount - Distance to move in pixels
+     * @param collisionHandler - Optional callback for handling collisions
+     * @returns Array of collision results
+     */
+    moveX(amount: number, collisionHandler?: (result: CollisionResult) => void, pushingSolid?: Solid): CollisionResult[];
+    /**
+     * Moves the actor vertically, checking for collisions with solids.
+     *
+     * @param amount - Distance to move in pixels
+     * @param collisionHandler - Optional callback for handling collisions
+     * @returns Array of collision results
+     */
+    moveY(amount: number, collisionHandler?: (result: CollisionResult) => void, pushingSolid?: Solid): CollisionResult[];
+    /**
+     * Updates the actor's view position.
+     */
+    updateView(): void;
+    /**
+     * Gets all solids at the specified position that could collide with this actor.
+     *
+     * @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[];
+    /**
+     * Checks if this actor is colliding with another actor.
+     * The collision will only occur if:
+     * 1. Both actors are active
+     * 2. Neither actor has disabled actor collisions
+     * 3. The collision layers and masks match:
+     *    - (this.collisionLayer & other.collisionMask) !== 0
+     *    - (other.collisionLayer & this.collisionMask) !== 0
+     *
+     * @param actor - The actor to check collision with
+     * @returns Collision result with information about the collision
+     */
+    checkActorCollision(actor: Actor): ActorCollisionResult;
+    /**
+     * Resolves a collision with another actor.
+     *
+     * @param result - The collision result to resolve
+     * @param shouldMove - Whether this actor should move to resolve the collision
+     * @returns The updated collision result
+     */
+    resolveActorCollision(result: ActorCollisionResult): ActorCollisionResult;
+    /**
+     * Sets the actor's size and updates grid cells if needed.
+     *
+     * @param width - New width in pixels
+     * @param height - New height in pixels
+     */
+    setSize(width: number, height: number): void;
+    /**
+     * Sets the actor's width and updates grid cells if needed.
+     *
+     * @param value - New width in pixels
+     */
+    setWidth(value: number): void;
+    /**
+     * Sets the actor's height and updates grid cells if needed.
+     *
+     * @param value - New height in pixels
+     */
+    setHeight(value: number): void;
+}
+//# sourceMappingURL=Actor.d.ts.map

package/lib/Actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Actor.d.ts","sourceRoot":"","sources":["../src/Actor.ts"],"names":[],"mappings":"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"}