@caperjs/plugin-crunch 0.1.0

package/src/collision-layers.d.ts

@@ -0,0 +1,87 @@
+/**
+ * This file provides TypeScript declaration merging for custom collision layers.
+ *
+ * To use this feature, create a declaration file in your project (e.g., collision-layers.d.ts)
+ * and extend the UserCollisionLayers interface with your custom layers:
+ *
+ * ```typescript
+ * // collision-layers.d.ts in your project
+ * declare module '@caperjs/plugin-crunch' {
+ *   interface UserCollisionLayers {
+ *     WATER: number;
+ *     LAVA: number;
+ *     CLOUD: number;
+ *   }
+ * }
+ * ```
+ *
+ * Then you can access your custom layers with intellisense:
+ *
+ * ```typescript
+ * import { physics } from '@caperjs/core';
+ *
+ * // Register your custom layers
+ * physics.registerCollisionLayer('WATER', 0);
+ * physics.registerCollisionLayer('LAVA', 1);
+ * physics.registerCollisionLayer('CLOUD', 2);
+ *
+ * // Access with intellisense
+ * const waterLayer = physics.getCollisionLayer('WATER');
+ * ```
+ */
+
+/**
+ * Interface for user-defined collision layers.
+ * Extend this interface in your own declaration files to add intellisense support
+ * for your custom collision layers.
+ */
+export interface UserCollisionLayers {
+  // This is intentionally empty and should be extended by users
+}
+
+/**
+ * Extended plugin interface with intellisense support for custom collision layers
+ */
+export interface CollisionLayerPluginExtensions {
+  /**
+   * Gets a registered collision layer by name with intellisense support.
+   *
+   * @param name Name of the collision layer
+   * @returns The numeric value of the registered collision layer or undefined if not found
+   */
+  getCollisionLayer<K extends keyof UserCollisionLayers>(name: K): number | undefined;
+
+  /**
+   * Registers a named collision layer with intellisense support.
+   *
+   * @param name Name of the collision layer
+   * @param index Index from 0-15 representing which user bit to use
+   * @param description Optional description of the layer
+   * @returns The numeric value of the registered collision layer
+   */
+  registerCollisionLayer<K extends keyof UserCollisionLayers>(name: K, index: number, description?: string): number;
+
+  /**
+   * Registers a named collision layer with automatic index assignment and intellisense support.
+   *
+   * @param name Name of the collision layer
+   * @param description Optional description of the layer
+   * @returns The numeric value of the registered collision layer
+   */
+  registerCollisionLayer<K extends keyof UserCollisionLayers>(name: K, description?: string): number;
+
+  /**
+   * Removes a registered collision layer with intellisense support.
+   *
+   * @param name Name of the collision layer to remove
+   * @returns True if the layer was removed, false if it didn't exist
+   */
+  removeCollisionLayer<K extends keyof UserCollisionLayers>(name: K): boolean;
+}
+
+// Extend the ICrunchPhysicsPlugin interface to include the CollisionLayerPluginExtensions
+import './CrunchPhysicsPlugin';
+
+declare module './CrunchPhysicsPlugin' {
+  interface ICrunchPhysicsPlugin extends CollisionLayerPluginExtensions {}
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import CrunchPhysicsPlugin from './CrunchPhysicsPlugin';
+
+export * from './Actor';
+// Don't export from collision-layers.d.ts as it's a declaration file
+export * from './Entity';
+export * from './Group';
+export * from './interfaces';
+export * from './Sensor';
+export * from './Solid';
+export * from './System';
+export * from './types';
+
+export type { ICrunchPhysicsPlugin } from './CrunchPhysicsPlugin';
+
+// Export specific types for easier access
+export * from './types';
+
+export default CrunchPhysicsPlugin;

package/src/interfaces.ts

@@ -0,0 +1,33 @@
+import { Container, Rectangle } from 'pixi.js';
+import { ActorCollision, Collision, SensorOverlap } from './types';
+
+export interface CrunchPhysicsOptions {
+  container: Container;
+  /** Grid cell size in pixels */
+  gridSize?: number;
+  /** Gravity strength */
+  gravity?: number;
+  /** Maximum velocity */
+  maxVelocity?: number;
+  /** Whether to enable debug rendering */
+  debug?: boolean;
+  /** Whether to cull out-of-bounds entities */
+  culling?: boolean;
+  /** Whether to remove entities from the system after culling */
+  boundary?: Rectangle;
+  /** Collision resolver */
+  collisionResolver?: (collisions: Collision[]) => void;
+  /** Overlap resolver */
+  overlapResolver?: (overlaps: SensorOverlap[]) => void;
+  /** Actor-to-actor collision resolver */
+  actorCollisionResolver?: (collisions: ActorCollision[]) => void;
+  /** Whether to enable actor-to-actor collisions */
+  enableActorCollisions?: boolean;
+}
+
+export interface AABBLike {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}

package/src/types.ts

@@ -0,0 +1,336 @@
+import { PointLike, SizeLike } from '@caperjs/core';
+import { Container } from 'pixi.js';
+import { Actor } from './Actor';
+import { Entity } from './Entity';
+import { Group } from './Group';
+import { Sensor } from './Sensor';
+import { Solid } from './Solid';
+
+export interface Vector2 {
+  x: number;
+  y: number;
+}
+
+export interface Rectangle {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type CollisionShape = 'rectangle';
+export type EntityData = {
+  [key: string]: any;
+};
+
+export type PhysicsEntityClass = new (config?: PhysicsEntityConfig) => Actor | Solid | Sensor;
+
+/**
+ * Collision layers using bitwise flags
+ * Each entity can belong to multiple layers (using bitwise OR)
+ * and can collide with multiple layers (using bitwise AND)
+ */
+export enum CollisionLayer {
+  NONE = 0,
+  DEFAULT = 1 << 0,
+  PLAYER = 1 << 1,
+  ENEMY = 1 << 2,
+  PROJECTILE = 1 << 3,
+  PLATFORM = 1 << 4,
+  TRIGGER = 1 << 5,
+  ITEM = 1 << 6,
+  WALL = 1 << 7,
+  FX = 1 << 8,
+  // Reserve first 16 bits for built-in layers
+  // Bits 16-31 are available for user-defined layers
+  ALL = 0xffffffff, // All bits set to 1
+}
+
+/**
+ * Interface for a registered collision layer
+ */
+export interface RegisteredCollisionLayer {
+  /** Name of the collision layer */
+  name: string;
+  /** Numeric value of the collision layer (bitwise) */
+  value: number;
+  /** Description of the collision layer (optional) */
+  description?: string;
+}
+
+/**
+ * Registry for tracking custom collision layers
+ */
+export class CollisionLayerRegistry {
+  private static _instance: CollisionLayerRegistry;
+  private _layers: Map<string, RegisteredCollisionLayer> = new Map();
+  private _usedIndices: Set<number> = new Set();
+
+  /**
+   * Get the singleton instance of the registry
+   */
+  public static get instance(): CollisionLayerRegistry {
+    if (!CollisionLayerRegistry._instance) {
+      CollisionLayerRegistry._instance = new CollisionLayerRegistry();
+    }
+    return CollisionLayerRegistry._instance;
+  }
+
+  /**
+   * Register a new collision layer
+   *
+   * @param name Name of the collision layer
+   * @param index Index from 0-15 representing which user bit to use (gets shifted to bits 16-31)
+   * @param description Optional description of the layer
+   * @returns The registered collision layer
+   */
+  public register(name: string, index: number, description?: string): RegisteredCollisionLayer {
+    if (index < 0 || index > 15) {
+      throw new Error('Custom collision layer index must be between 0 and 15');
+    }
+
+    if (this._usedIndices.has(index)) {
+      throw new Error(`Collision layer index ${index} is already in use`);
+    }
+
+    if (this._layers.has(name)) {
+      throw new Error(`Collision layer with name "${name}" already exists`);
+    }
+
+    const value = 1 << (index + 16);
+    const layer: RegisteredCollisionLayer = { name, value, description };
+
+    this._layers.set(name, layer);
+    this._usedIndices.add(index);
+
+    return layer;
+  }
+
+  /**
+   * Get a registered collision layer by name
+   *
+   * @param name Name of the collision layer
+   * @returns The registered collision layer or undefined if not found
+   */
+  public get(name: string): RegisteredCollisionLayer | undefined {
+    return this._layers.get(name);
+  }
+
+  /**
+   * Get all registered collision layers
+   *
+   * @returns Array of all registered collision layers
+   */
+  public getAll(): RegisteredCollisionLayer[] {
+    return Array.from(this._layers.values());
+  }
+
+  /**
+   * Check if a collision layer with the given name exists
+   *
+   * @param name Name of the collision layer
+   * @returns True if the layer exists
+   */
+  public has(name: string): boolean {
+    return this._layers.has(name);
+  }
+
+  /**
+   * Remove a registered collision layer
+   *
+   * @param name Name of the collision layer to remove
+   * @returns True if the layer was removed, false if it didn't exist
+   */
+  public remove(name: string): boolean {
+    const layer = this._layers.get(name);
+    if (!layer) return false;
+
+    // Calculate the index from the value
+    const value = layer.value;
+    const index = Math.log2(value) - 16;
+
+    this._usedIndices.delete(index);
+    return this._layers.delete(name);
+  }
+
+  /**
+   * Clear all registered collision layers
+   */
+  public clear(): void {
+    this._layers.clear();
+    this._usedIndices.clear();
+  }
+
+  /**
+   * Get the next available index for a custom collision layer
+   *
+   * @returns The next available index or -1 if all indices are used
+   */
+  public getNextAvailableIndex(): number {
+    for (let i = 0; i < 16; i++) {
+      if (!this._usedIndices.has(i)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+}
+
+/**
+ * Utility functions for working with collision layers
+ */
+export const CollisionLayers = {
+  /**
+   * Creates a custom collision layer using bits 16-31 (user space)
+   *
+   * @param index Index from 0-15 representing which user bit to use (gets shifted to bits 16-31)
+   * @returns A unique collision layer value
+   *
+   * @example
+   * ```typescript
+   * // Create custom collision layers
+   * const WATER_LAYER = CollisionLayers.createLayer(0);  // 1 << 16
+   * const LAVA_LAYER = CollisionLayers.createLayer(1);   // 1 << 17
+   * const CLOUD_LAYER = CollisionLayers.createLayer(2);  // 1 << 18
+   *
+   * // Use in entity creation
+   * const waterEntity = physics.createActor({
+   *   type: 'Water',
+   *   position: [100, 400],
+   *   size: [800, 100],
+   *   collisionLayer: WATER_LAYER,
+   *   collisionMask: CollisionLayer.PLAYER | CollisionLayer.ENEMY
+   * });
+   * ```
+   */
+  createLayer(index: number): number {
+    if (index < 0 || index > 15) {
+      throw new Error('Custom collision layer index must be between 0 and 15');
+    }
+    return 1 << (index + 16);
+  },
+
+  /**
+   * Creates a collision mask from multiple layers
+   *
+   * @param layers Array of collision layers to combine
+   * @returns A combined collision mask
+   *
+   * @example
+   * ```typescript
+   * // Create a mask that collides with players, enemies and projectiles
+   * const mask = CollisionLayers.createMask([
+   *   CollisionLayer.PLAYER,
+   *   CollisionLayer.ENEMY,
+   *   CollisionLayer.PROJECTILE
+   * ]);
+   * ```
+   */
+  createMask(layers: number[]): number {
+    return layers.reduce((mask, layer) => mask | layer, 0);
+  },
+
+  /**
+   * Checks if a layer is included in a mask
+   *
+   * @param layer The layer to check
+   * @param mask The mask to check against
+   * @returns True if the layer is included in the mask
+   *
+   * @example
+   * ```typescript
+   * // Check if player layer is in the mask
+   * if (CollisionLayers.isLayerInMask(CollisionLayer.PLAYER, entity.collisionMask)) {
+   *   console.log('Entity can collide with players');
+   * }
+   * ```
+   */
+  isLayerInMask(layer: number, mask: number): boolean {
+    return (layer & mask) !== 0;
+  },
+
+  /**
+   * Get the registry for custom collision layers
+   *
+   * @returns The collision layer registry
+   */
+  getRegistry(): CollisionLayerRegistry {
+    return CollisionLayerRegistry.instance;
+  },
+};
+
+export interface PhysicsEntityConfig<D extends EntityData = EntityData> {
+  id?: string;
+  class?: PhysicsEntityClass;
+  type?: PhysicsEntityType;
+  position?: PointLike;
+  size?: SizeLike;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  restitution?: number;
+  view?: PhysicsEntityView;
+  data?: Partial<D>;
+  group?: Group;
+  groupOffset?: PointLike;
+  follows?: Entity;
+  followOffset?: PointLike;
+  /** Collision layer this entity belongs to (bitwise) */
+  collisionLayer?: number;
+  /** Collision mask defining which layers this entity collides with (bitwise) */
+  collisionMask?: number;
+  /** Whether to disable actor-to-actor collisions for this entity */
+  disableActorCollisions?: boolean;
+}
+
+export interface CollisionResult {
+  collided: boolean;
+  normal?: Vector2;
+  penetration?: number;
+  solid: Solid;
+}
+
+export interface SensorOverlap {
+  type: `${PhysicsEntityType}|${PhysicsEntityType}`;
+  actor: Actor;
+  sensor: Sensor;
+}
+
+export interface CollisionResult {
+  collided: boolean;
+  normal?: Vector2;
+  penetration?: number;
+  solid: Solid;
+  pushingSolid?: Solid;
+}
+
+/**
+ * Result of an actor-to-actor collision
+ */
+export interface ActorCollisionResult {
+  collided: boolean;
+  normal?: Vector2;
+  penetration?: number;
+  actor: Actor;
+}
+
+export interface Collision {
+  type: `${PhysicsEntityType}|${PhysicsEntityType}`;
+  entity1: Actor | Sensor;
+  entity2: Actor | Solid;
+  result: CollisionResult;
+}
+
+/**
+ * Represents a collision between two actors
+ */
+export interface ActorCollision {
+  type: `${PhysicsEntityType}|${PhysicsEntityType}`;
+  actor1: Actor;
+  actor2: Actor;
+  result: ActorCollisionResult;
+}
+
+export type PhysicsEntityView = Container;
+export type PhysicsEntityType = 'Actor' | 'Solid' | 'Sensor' | 'Group' | string;

package/src/utils.ts

@@ -0,0 +1,72 @@
+import { resolvePointLike, resolveSizeLike } from '@caperjs/core';
+import { PhysicsEntityConfig } from './types';
+
+/**
+ * Utility functions for resolving entity positions and sizes from various input formats.
+ * These functions handle the conversion of different coordinate and size specifications
+ * into standardized formats used by the physics system.
+ */
+
+/**
+ * Resolves an entity's position from various input formats.
+ * Supports direct x/y values or a position object/array.
+ *
+ * @param config - Entity configuration containing position information
+ * @returns Resolved {x, y} coordinates
+ *
+ * @example
+ * ```typescript
+ * // Using direct x/y values
+ * resolveEntityPosition({ x: 100, y: 200 })
+ * // → { x: 100, y: 200 }
+ *
+ * // Using position array
+ * resolveEntityPosition({ position: [100, 200] })
+ * // → { x: 100, y: 200 }
+ *
+ * // Using position object
+ * resolveEntityPosition({ position: { x: 100, y: 200 } })
+ * // → { x: 100, y: 200 }
+ * ```
+ */
+export function resolveEntityPosition(config: PhysicsEntityConfig): { x: number; y: number } {
+  const { x, y } =
+    config.position !== undefined ? resolvePointLike(config.position) : { x: config?.x ?? 0, y: config?.y ?? 0 };
+
+  return { x, y };
+}
+
+/**
+ * Resolves an entity's size from various input formats.
+ * Supports direct width/height values or a size object/array.
+ *
+ * @param config - Entity configuration containing size information
+ * @returns Resolved {width, height} dimensions
+ *
+ * @example
+ * ```typescript
+ * // Using direct width/height values
+ * resolveEntitySize({ width: 100, height: 200 })
+ * // → { width: 100, height: 200 }
+ *
+ * // Using size array
+ * resolveEntitySize({ size: [100, 200] })
+ * // → { width: 100, height: 200 }
+ *
+ * // Using size object
+ * resolveEntitySize({ size: { width: 100, height: 200 } })
+ * // → { width: 100, height: 200 }
+ *
+ * // Using defaults
+ * resolveEntitySize({})
+ * // → { width: 32, height: 32 }
+ * ```
+ */
+export function resolveEntitySize(config: PhysicsEntityConfig): { width: number; height: number } {
+  const { width, height } =
+    config.size !== undefined
+      ? resolveSizeLike(config.size)
+      : { width: config?.width ?? 32, height: config?.height ?? 32 };
+
+  return { width, height };
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const version = '0.1.0';