infernojs 0.0.1

package/README.md

@@ -0,0 +1,320 @@
+# pepperjs
+
+A spicy, high-performance library for building 2D games in JavaScript.
+
+![Pepper - The Black Cat Mascot](./assets/pepper-logo.svg)
+
+## Features
+
+- **Efficient Collision Detection**
+
+  - Multiple collision detection strategies for different use cases
+  - Support for circles, rectangles, polygons, and line segments
+  - Spatial partitioning for optimal performance with large numbers of entities
+  - Precise contact point and collision normal information
+
+- **Future Additions** (Coming Soon)
+
+  - Efficient shape rendering
+  - Input handling
+  - Animation system
+  - Simple physics
+  - Game loop management
+
+- **Developer-Friendly**
+  - Written in TypeScript with full type safety
+  - Zero dependencies
+  - Optimized for performance
+
+## Installation
+
+```bash
+npm install pepperjs
+```
+
+## Usage: Collision Detection
+
+### Using Collision Detectors
+
+```typescript
+import { BruteForceCollisionDetector, SpatialGridCollisionDetector } from "pepperjs";
+
+// Create some entities
+const entities = [
+  {
+    id: "circle1",
+    type: "circle",
+    shape: {
+      center: { x: 100, y: 100 },
+      radius: 50,
+    },
+  },
+  {
+    id: "rect1",
+    type: "rectangle",
+    shape: {
+      position: { x: 300, y: 300 },
+      width: 100,
+      height: 100,
+    },
+  },
+];
+
+// Choose the appropriate detector for your use case
+// BruteForce: Best for small number of entities or infrequent checks
+const bruteForce = BruteForceCollisionDetector({ entities });
+
+// SpatialGrid: Best for large number of entities and frequent checks
+const spatialGrid = SpatialGridCollisionDetector({ 
+  entities,
+  cellSize: 64  // Optional: Size of grid cells (default: 64)
+});
+
+// Check collisions with a shape
+const testCircle = {
+  center: { x: 150, y: 150 },
+  radius: 75,
+};
+
+// Get IDs of all entities that collide with the test shape
+const collisions = spatialGrid.getCollisions(testCircle);
+console.log(collisions); // ["circle1"]
+```
+
+### Using the Legacy CollisionSystem
+
+```typescript
+import { CollisionSystem, vec2 } from "pepperjs";
+
+// Create a collision system
+const physics = new CollisionSystem({
+  cellSize: 64, // Size of spatial partitioning cells
+  useBroadPhase: true, // Enable spatial partitioning for better performance
+});
+
+// Add a circle entity
+const circleId = physics.addEntity({
+  type: "circle",
+  shape: {
+    center: vec2(100, 100),
+    radius: 50,
+  },
+});
+
+// Add a rectangle entity
+const rectId = physics.addEntity({
+  type: "rectangle",
+  shape: {
+    position: vec2(120, 90),
+    width: 80,
+    height: 60,
+  },
+});
+
+// Check for collisions
+const collisions = physics.checkAllCollisions();
+
+// Process collisions
+for (const [pairKey, result] of collisions.entries()) {
+  console.log(`Collision detected: ${pairKey}`);
+  console.log(
+    `Contact point: ${result.contacts[0].point.x}, ${result.contacts[0].point.y}`
+  );
+  console.log(
+    `Normal: ${result.contacts[0].normal.x}, ${result.contacts[0].normal.y}`
+  );
+  console.log(`Penetration depth: ${result.contacts[0].depth}`);
+}
+```
+
+## Performance Optimization
+
+The library uses several techniques to ensure high performance:
+
+1. **Multiple collision detection strategies** - Choose the right algorithm for your specific needs
+2. **Spatial partitioning** - Divides the world into grid cells to reduce the number of collision checks
+3. **Broad-phase collision detection** - Uses AABBs (Axis-Aligned Bounding Boxes) to quickly filter out non-colliding objects
+4. **Optimized math operations** - Uses squared distance calculations when possible to avoid costly square roots
+5. **Efficient data structures** - Uses Maps and Sets for fast lookups
+
+## Choosing the Right Collision Detector
+
+PepperJS provides different collision detection strategies optimized for different scenarios:
+
+- **BruteForceCollisionDetector**: Checks every entity against the given shape
+  - Best for small number of entities (< 100)
+  - Best when you only need to check collisions occasionally
+  - Simplest implementation with minimal overhead
+
+- **SpatialGridCollisionDetector**: Uses spatial partitioning to efficiently find potential collisions
+  - Best for large number of entities (100+)
+  - Best when entities are distributed across the space
+  - Best when you need to check collisions frequently
+  - Allows tuning the cell size for optimal performance
+
+## Roadmap
+
+We're actively working on expanding pepperjs into a comprehensive 2D game development library. Here's what's coming:
+
+### Version 0.1.0 (Current)
+
+- ✅ High-performance collision detection
+- ✅ Spatial partitioning for efficient collision handling
+- ✅ Support for multiple shape types (circles, rectangles, polygons, line segments)
+
+### Version 0.2.0 (Planned)
+
+- 🔲 Canvas-based rendering system
+- 🔲 Shape drawing utilities
+- 🔲 Basic sprite support
+- 🔲 Performance optimizations for rendering
+
+### Version 0.3.0 (Planned)
+
+- 🔲 Input handling (keyboard, mouse, touch)
+- 🔲 Game loop management
+- 🔲 Time-based animation system
+
+### Version 0.4.0 (Planned)
+
+- 🔲 Simple physics engine (forces, gravity, etc.)
+- 🔲 Constraints and joints
+- 🔲 Integration with collision system
+
+### Version 0.5.0 (Planned)
+
+- 🔲 Entity-component system
+- 🔲 Particle systems
+- 🔲 Camera and viewport management
+
+### Future Additions
+
+- 🔲 WebGL renderer option
+- 🔲 Sound system
+- 🔲 Tile maps and level loading
+- 🔲 UI components
+
+## Examples
+
+You can run the included examples to see the library in action:
+
+```bash
+# Basic collision detection example
+npm run example
+
+# Collision detectors comparison example
+npm run example:detectors
+```
+
+## Benchmarks
+
+You can run performance benchmarks to test the library's collision detection performance:
+
+```bash
+npm run bench
+```
+
+This will run a series of benchmarks with different configurations, allowing you to see how the library performs with different numbers of entities and different collision detection strategies.
+
+## API Reference
+
+### CollisionSystem
+
+The main class for handling collision detection.
+
+```typescript
+// Create a new collision system
+const system = new CollisionSystem({
+  cellSize: 64, // Size of grid cells for spatial partitioning
+  maxEntities: 1000, // Maximum number of entities (optional)
+  useBroadPhase: true, // Whether to use spatial partitioning
+});
+
+// Add an entity and get its ID
+const entityId = system.addEntity({
+  type: "circle", // or 'rectangle', 'polygon', 'lineSegment'
+  shape: {
+    // Shape data here
+  },
+});
+
+// Remove an entity
+system.removeEntity(entityId);
+
+// Update spatial partitioning (call after entities move)
+system.updateSpatialPartitioning();
+
+// Check for collisions and get results
+const collisionResults = system.checkAllCollisions();
+
+// Check collision between two specific entities
+const result = system.checkCollision(entityA, entityB);
+
+// Clear all entities
+system.clear();
+```
+
+### Shapes
+
+The library supports several shape types:
+
+#### Circle
+
+```typescript
+const circle = {
+  type: "circle",
+  shape: {
+    center: { x: 100, y: 100 },
+    radius: 50,
+  },
+};
+```
+
+#### Rectangle
+
+```typescript
+const rectangle = {
+  type: "rectangle",
+  shape: {
+    position: { x: 100, y: 100 },
+    width: 200,
+    height: 150,
+  },
+};
+```
+
+#### Polygon
+
+```typescript
+const polygon = {
+  type: "polygon",
+  shape: {
+    points: [
+      { x: 0, y: 0 },
+      { x: 100, y: 0 },
+      { x: 100, y: 100 },
+      { x: 0, y: 100 },
+    ],
+  },
+};
+```
+
+#### Line Segment
+
+```typescript
+const lineSegment = {
+  type: "lineSegment",
+  shape: {
+    start: { x: 0, y: 0 },
+    end: { x: 100, y: 100 },
+  },
+};
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,211 @@
+import { Entity, Shape, Circle, Point, Rectangle } from './types.mjs';
+export { AABB, CollisionConfig, CollisionResult, ContactPoint, ShapeType, Vector2D } from './types.mjs';
+export { aabbIntersect, add, cellToId, circleToAABB, cross, distance, distanceSquared, dot, length, lengthSquared, normalize, positionToCell, rectToAABB, scale, subtract, vec2 } from './utils.mjs';
+
+/**
+ * Base class for collision detectors that implements common functionality
+ */
+declare abstract class BaseCollisionDetector {
+    /**
+     * The entities to check collisions against
+     */
+    protected entities: Entity[];
+    /**
+     * Create a new collision detector
+     * @param entities The entities to check collisions against
+     */
+    constructor(entities: Entity[]);
+    /**
+     * Get all entities that collide with the given shape
+     * @param shape The shape to check collisions against
+     * @returns Array of entity IDs that collide with the shape
+     */
+    abstract getCollisions(shape: Shape): (string | number)[];
+}
+
+/**
+ * Collision detector that uses a brute force approach
+ * Checks every entity against the given shape
+ *
+ * Best used when:
+ * - You have a small number of entities
+ * - You only need to check collisions occasionally
+ * - You want the simplest implementation
+ */
+declare function BruteForceCollisionDetector({ entities, }: {
+    entities: Entity[];
+}): BruteForceCollisionDetectorImpl;
+declare class BruteForceCollisionDetectorImpl extends BaseCollisionDetector {
+    /**
+     * Get all entities that collide with the given shape
+     * @param shape The shape to check collisions against
+     * @returns Array of entity IDs that collide with the shape
+     */
+    getCollisions(shape: Shape): (string | number)[];
+}
+
+/**
+ * Configuration options for the spatial grid collision detector
+ */
+interface SpatialGridConfig {
+    /** Size of each grid cell */
+    cellSize: number;
+}
+/**
+ * Collision detector that uses spatial partitioning for efficient collision detection
+ *
+ * Best used when:
+ * - You have a large number of entities
+ * - Entities are distributed across the space
+ * - You need to check collisions frequently
+ */
+declare function SpatialGridCollisionDetector({ entities, cellSize, }: {
+    entities: Entity[];
+    cellSize?: number;
+}): SpatialGridCollisionDetectorImpl;
+declare class SpatialGridCollisionDetectorImpl extends BaseCollisionDetector {
+    /** The spatial hash grid for quick lookups */
+    private grid;
+    /** Configuration for the spatial grid */
+    private config;
+    /**
+     * Create a new spatial grid collision detector
+     */
+    constructor(entities: Entity[], config: SpatialGridConfig);
+    /**
+     * Get all entities that collide with the given shape
+     */
+    getCollisions(shape: Shape): (string | number)[];
+    /**
+     * Rebuild the spatial grid with the current entities
+     */
+    rebuildGrid(): void;
+    /**
+     * Insert an entity into the spatial grid
+     */
+    private insertEntityIntoGrid;
+    /**
+     * Get all cells that an AABB overlaps
+     */
+    private getCellsForAABB;
+    /**
+     * Get the AABB for an entity
+     */
+    private getAABB;
+    /**
+     * Get the AABB for a shape
+     */
+    private getAABBForShape;
+}
+
+/**
+ * Check if two entities are colliding
+ * @param shapeA First shape
+ * @param shapeB Second shape
+ * @returns True if the shapes are colliding
+ */
+declare function checkShapeCollision(shapeA: Shape, shapeB: Shape): boolean;
+
+/**
+ * Style options for rendering shapes
+ */
+type ShapeStyle = {
+    /** Fill color (CSS color string) */
+    fillColor?: string;
+    /** Stroke color (CSS color string) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+    /** Alpha/opacity (0-1) */
+    alpha?: number;
+    /** Shadow blur radius */
+    shadowBlur?: number;
+    /** Shadow color */
+    shadowColor?: string;
+    /** Shadow offset X */
+    shadowOffsetX?: number;
+    /** Shadow offset Y */
+    shadowOffsetY?: number;
+};
+/**
+ * A renderable entity with shape and style
+ */
+type RenderableShape = {
+    shape: Shape;
+    style: ShapeStyle;
+};
+/**
+ * Configuration options for the renderer
+ */
+type RendererOptions = {
+    /** Background color of the canvas */
+    backgroundColor?: string;
+    /** Default style to apply to shapes without specific styling */
+    defaultStyle?: ShapeStyle;
+    /** Whether to clear the canvas before each render */
+    clearBeforeRender?: boolean;
+};
+
+/**
+ * Apply style settings to the canvas context
+ */
+declare function applyStyle(ctx: CanvasRenderingContext2D, style: ShapeStyle): void;
+/**
+ * Restore the canvas context to its previous state
+ */
+declare function restoreContext(ctx: CanvasRenderingContext2D): void;
+/**
+ * Render a circle shape
+ */
+declare function renderCircle(ctx: CanvasRenderingContext2D, circle: Circle, style: ShapeStyle): void;
+/**
+ * Render a point shape
+ */
+declare function renderPoint(ctx: CanvasRenderingContext2D, point: Point, style: ShapeStyle): void;
+/**
+ * Render a rectangle shape
+ */
+declare function renderRectangle(ctx: CanvasRenderingContext2D, rectangle: Rectangle, style: ShapeStyle): void;
+/**
+ * Render any shape based on its type
+ */
+declare function renderShape(ctx: CanvasRenderingContext2D, shape: Shape, style: ShapeStyle): void;
+/**
+ * Main renderer function to render multiple shapes
+ */
+declare function renderShapes(ctx: CanvasRenderingContext2D, shapes: RenderableShape[], options: RendererOptions): void;
+
+/**
+ * pepperjs
+ * A spicy, high-performance library for building 2D games in JavaScript
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "0.0.1";
+/**
+ * @internal
+ * Rendering capabilities
+ */
+declare const Renderer: {
+    notImplemented: boolean;
+    info: string;
+};
+/**
+ * @internal
+ * Future game loop management API
+ */
+declare const GameLoop: {
+    notImplemented: boolean;
+    info: string;
+};
+/**
+ * @internal
+ * Future input handling API
+ */
+declare const Input: {
+    notImplemented: boolean;
+    info: string;
+};
+
+export { BaseCollisionDetector, BruteForceCollisionDetector, Circle, Entity, GameLoop, Input, Point, Rectangle, Renderer, Shape, SpatialGridCollisionDetector, type SpatialGridConfig, VERSION, applyStyle, checkShapeCollision, renderCircle, renderPoint, renderRectangle, renderShape, renderShapes, restoreContext };