ecspresso 0.10.2 → 0.11.0

package/dist/bundles/collision.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Collision Bundle for ECSpresso
+ *
+ * Provides layer-based collision detection with events.
+ * Uses worldTransform for position (world-space collision).
+ * Supports AABB and circle colliders.
+ */
+import { Bundle } from 'ecspresso';
+import type { SystemPhase } from 'ecspresso';
+import type { TransformComponentTypes } from './transform';
+/**
+ * Axis-Aligned Bounding Box collider.
+ */
+export interface AABBCollider {
+    /** Width of the bounding box */
+    width: number;
+    /** Height of the bounding box */
+    height: number;
+    /** X offset from entity position (default: 0) */
+    offsetX?: number;
+    /** Y offset from entity position (default: 0) */
+    offsetY?: number;
+}
+/**
+ * Circle collider.
+ */
+export interface CircleCollider {
+    /** Radius of the circle */
+    radius: number;
+    /** X offset from entity position (default: 0) */
+    offsetX?: number;
+    /** Y offset from entity position (default: 0) */
+    offsetY?: number;
+}
+/**
+ * Collision layer configuration.
+ */
+export interface CollisionLayer<L extends string = never> {
+    /** The layer this entity belongs to */
+    layer: L;
+    /** Layers this entity can collide with */
+    collidesWith: readonly L[];
+}
+/**
+ * Component types provided by the collision bundle.
+ * Included automatically via `.withBundle(createCollisionBundle())`.
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withBundle(createCollisionBundle())
+ *   .withComponentTypes<{ sprite: Sprite; enemy: boolean }>()
+ *   .build();
+ * ```
+ */
+export interface CollisionComponentTypes<L extends string = never> {
+    aabbCollider: AABBCollider;
+    circleCollider: CircleCollider;
+    collisionLayer: CollisionLayer<L>;
+}
+/**
+ * Event fired when two entities collide.
+ */
+export interface CollisionEvent<L extends string = never> {
+    /** First entity in the collision */
+    entityA: number;
+    /** Second entity in the collision */
+    entityB: number;
+    /** Layer of the first entity */
+    layerA: L;
+    /** Layer of the second entity */
+    layerB: L;
+    /** Contact normal pointing from entityA toward entityB */
+    normal: {
+        x: number;
+        y: number;
+    };
+    /** Penetration depth (positive = overlapping) */
+    depth: number;
+}
+/**
+ * Event types provided by the collision bundle.
+ */
+export interface CollisionEventTypes<L extends string = never> {
+    collision: CollisionEvent<L>;
+}
+/**
+ * Configuration options for the collision bundle.
+ */
+export interface CollisionBundleOptions<G extends string = 'physics'> {
+    /** System group name (default: 'physics') */
+    systemGroup?: G;
+    /** Priority for collision system (default: 0) */
+    priority?: number;
+    /** Name of the collision event (default: 'collision') */
+    collisionEventName?: string;
+    /** Execution phase (default: 'postUpdate') */
+    phase?: SystemPhase;
+}
+/**
+ * Create an AABB collider component.
+ *
+ * @param width Width of the bounding box
+ * @param height Height of the bounding box
+ * @param offsetX X offset from entity position
+ * @param offsetY Y offset from entity position
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ * });
+ * ```
+ */
+export declare function createAABBCollider(width: number, height: number, offsetX?: number, offsetY?: number): {
+    aabbCollider: AABBCollider;
+};
+/**
+ * Create a circle collider component.
+ *
+ * @param radius Radius of the circle
+ * @param offsetX X offset from entity position
+ * @param offsetY Y offset from entity position
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createCircleCollider(25),
+ * });
+ * ```
+ */
+export declare function createCircleCollider(radius: number, offsetX?: number, offsetY?: number): {
+    circleCollider: CircleCollider;
+};
+/**
+ * Create a collision layer component.
+ *
+ * @param layer The layer this entity belongs to
+ * @param collidesWith Layers this entity can collide with
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ *   ...createCollisionLayer('player', ['enemy', 'obstacle']),
+ * });
+ * ```
+ */
+export declare function createCollisionLayer<L extends string>(layer: L, collidesWith: readonly L[]): Pick<CollisionComponentTypes<L>, 'collisionLayer'>;
+/**
+ * Layer factory result from defineCollisionLayers.
+ */
+export type LayerFactories<T extends Record<string, readonly string[]>> = {
+    [K in keyof T]: () => Pick<CollisionComponentTypes<Extract<keyof T, string>>, 'collisionLayer'>;
+};
+/**
+ * Extract layer names from a `defineCollisionLayers` result for use with
+ * `createCollisionPairHandler`'s `L` type parameter.
+ *
+ * @example
+ * ```typescript
+ * const layers = defineCollisionLayers({ player: ['enemy'], enemy: ['player'] });
+ * type Layer = LayersOf<typeof layers>;
+ * const handler = createCollisionPairHandler<ECS, Layer>({
+ *   'player:enemy': (playerId, enemyId, ecs) => { ... },
+ * });
+ * ```
+ */
+export type LayersOf<T> = Extract<keyof T, string>;
+/**
+ * Define collision layer relationships and get factory functions.
+ *
+ * @param rules Object mapping layer names to arrays of layers they collide with
+ * @returns Object with factory functions for each layer
+ *
+ * @example
+ * ```typescript
+ * const layers = defineCollisionLayers({
+ *   player: ['enemy', 'enemyProjectile'],
+ *   playerProjectile: ['enemy'],
+ *   enemy: ['playerProjectile'],
+ *   enemyProjectile: ['player'],
+ * });
+ *
+ * // Usage
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ *   ...layers.player(),
+ * });
+ * ```
+ */
+/**
+ * Validates that all `collidesWith` values reference actual layer keys.
+ * Catches typos at compile time.
+ */
+type ValidateCollidesWith<T> = {
+    [K in keyof T]: T[K] extends readonly (infer V)[] ? [V] extends [Extract<keyof T, string>] ? T[K] : readonly Extract<keyof T, string>[] : never;
+};
+export declare function defineCollisionLayers<const T extends Record<string, readonly string[]>>(rules: T & ValidateCollidesWith<T>): LayerFactories<T>;
+/**
+ * Callback for a collision pair handler.
+ *
+ * @param firstEntityId Entity belonging to the first layer in the pair key
+ * @param secondEntityId Entity belonging to the second layer in the pair key
+ * @param ecs The ECS world instance (passed through from the subscriber)
+ */
+export type CollisionPairCallback<W = unknown> = (firstEntityId: number, secondEntityId: number, ecs: W) => void;
+/**
+ * Create a collision pair handler that routes collision events to
+ * layer-pair-specific callbacks.
+ *
+ * Registering `"a:b"` automatically handles both `(layerA=a, layerB=b)` and
+ * `(layerA=b, layerB=a)`. Entity arguments are swapped to match the declared
+ * key order. If both `"a:b"` and `"b:a"` are explicitly registered, each gets
+ * its own handler with no implicit reverse.
+ *
+ * @typeParam W - The ECS world type (e.g. `ECSpresso<C, E, R>`). Defaults to `unknown`.
+ * @typeParam L - Union of valid layer names. Defaults to `string`.
+ *   Provide specific layer names for compile-time key validation:
+ *   `createCollisionPairHandler<ECS, keyof typeof layers>({...})`
+ *
+ * @param pairs Object mapping `"layerA:layerB"` keys to callbacks
+ * @returns A dispatch function to call with collision event data and ECS instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage:
+ * const handler = createCollisionPairHandler<ECS>({
+ *   'playerProjectile:enemy': (projectileId, enemyId, ecs) => {
+ *     ecs.commands.removeEntity(projectileId);
+ *   },
+ * });
+ *
+ * // With layer name validation:
+ * const layers = defineCollisionLayers({ player: ['enemy'], enemy: ['player'] });
+ * type Layer = LayersOf<typeof layers>;
+ * const handler = createCollisionPairHandler<ECS, Layer>({
+ *   'player:enemy': (playerId, enemyId, ecs) => { ... },
+ * });
+ *
+ * ecs.eventBus.subscribe('collision', (data) => handler(data, ecs));
+ * ```
+ */
+export declare function createCollisionPairHandler<W = unknown, L extends string = string>(pairs: {
+    [K in `${L}:${L}`]?: CollisionPairCallback<W>;
+}): (event: CollisionEvent<L>, ecs: W) => void;
+type CombinedComponentTypes<L extends string> = CollisionComponentTypes<L> & TransformComponentTypes;
+/**
+ * Create a collision bundle for ECSpresso.
+ *
+ * This bundle provides:
+ * - Collision detection between entities with colliders
+ * - AABB-AABB, circle-circle, and AABB-circle collision
+ * - Layer-based filtering for collision pairs
+ * - Deduplication of A-B / B-A collisions
+ * - Automatic broadphase acceleration when spatialIndex resource is present
+ *
+ * Uses worldTransform for position (world-space collision detection).
+ * The `layers` parameter is required for type inference — at runtime the
+ * bundle does not consume it.
+ *
+ * @example
+ * ```typescript
+ * const layers = defineCollisionLayers({ player: ['enemy'], enemy: ['player'] });
+ * const ecs = ECSpresso
+ *   .create()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createCollisionBundle({ layers }))
+ *   .build();
+ *
+ * // Entity with collision
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ *   ...layers.player(),
+ * });
+ * ```
+ */
+export declare function createCollisionBundle<L extends string, G extends string = 'physics'>(options: CollisionBundleOptions<G> & {
+    layers: LayerFactories<Record<L, readonly string[]>>;
+}): Bundle<CombinedComponentTypes<L>, CollisionEventTypes<L>, {}, {}, {}, 'collision-detection', G>;
+export {};

package/dist/bundles/diagnostics.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Diagnostics Bundle for ECSpresso
+ *
+ * Runtime diagnostics: FPS, entity count, per-system timing, per-phase timing,
+ * and an optional DOM overlay for visual debugging.
+ */
+import { Bundle } from 'ecspresso';
+import type { SystemPhase } from 'ecspresso';
+export interface DiagnosticsData {
+    fps: number;
+    entityCount: number;
+    systemTimings: ReadonlyMap<string, number>;
+    phaseTimings: Readonly<Record<SystemPhase, number>>;
+    averageFrameTime: number;
+}
+export interface DiagnosticsResourceTypes {
+    diagnostics: DiagnosticsData;
+}
+export interface DiagnosticsBundleOptions<G extends string = 'diagnostics'> {
+    /** System group name (default: 'diagnostics') */
+    systemGroup?: G;
+    /** Enable timing collection on initialize (default: true) */
+    enableTimingOnInit?: boolean;
+    /** Number of frames to sample for FPS average (default: 60) */
+    fpsSampleCount?: number;
+}
+export interface DiagnosticsOverlayOptions {
+    /** Corner position (default: 'top-left') */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /** Milliseconds between DOM updates (default: 200) */
+    updateInterval?: number;
+    /** Show per-system timings (default: true) */
+    showSystemTimings?: boolean;
+    /** Maximum systems to show in overlay (default: 10) */
+    maxSystemsShown?: number;
+}
+export declare function createDiagnosticsBundle<G extends string = 'diagnostics'>(options?: DiagnosticsBundleOptions<G>): Bundle<{}, {}, DiagnosticsResourceTypes, {}, {}, 'diagnostics-collect', G>;
+/**
+ * Create a DOM overlay that displays diagnostics data.
+ * Returns a cleanup function that removes the element and clears the interval.
+ *
+ * @param ecs An ECSpresso instance with the diagnostics resource
+ * @param options Overlay configuration
+ * @returns Cleanup function
+ */
+export declare function createDiagnosticsOverlay<R extends DiagnosticsResourceTypes>(ecs: {
+    getResource<K extends keyof R>(key: K): R[K];
+}, options?: DiagnosticsOverlayOptions): () => void;

package/dist/bundles/{utils/input.d.ts → input.d.ts}

@@ -48,35 +48,35 @@ export interface PointerState {
     justPressed(button: number): boolean;
     justReleased(button: number): boolean;
 }
-export interface ActionState {
-    isActive(action: string): boolean;
-    justActivated(action: string): boolean;
-    justDeactivated(action: string): boolean;
+export interface ActionState<A extends string = string> {
+    isActive(action: A): boolean;
+    justActivated(action: A): boolean;
+    justDeactivated(action: A): boolean;
 }
-export interface InputState {
+export interface InputState<A extends string = string> {
     readonly keyboard: KeyboardState;
     readonly pointer: PointerState;
-    readonly actions: ActionState;
-    setActionMap(actions: ActionMap): void;
-    getActionMap(): Readonly<ActionMap>;
+    readonly actions: ActionState<A>;
+    setActionMap(actions: ActionMap<A>): void;
+    getActionMap(): Readonly<ActionMap<A>>;
 }
 export interface ActionBinding {
     keys?: KeyCode[];
     buttons?: number[];
 }
-export type ActionMap = Record<string, ActionBinding>;
-export interface InputResourceTypes {
-    inputState: InputState;
+export type ActionMap<A extends string = string> = Record<A, ActionBinding>;
+export interface InputResourceTypes<A extends string = string> {
+    inputState: InputState<A>;
 }
-export interface InputBundleOptions {
+export interface InputBundleOptions<A extends string = string, G extends string = 'input'> {
     /** System group name (default: 'input') */
-    systemGroup?: string;
+    systemGroup?: G;
     /** Priority for input system (default: 100) */
     priority?: number;
     /** Execution phase (default: 'preUpdate') */
     phase?: SystemPhase;
     /** Initial action mappings */
-    actions?: ActionMap;
+    actions?: ActionMap<A>;
     /** EventTarget to attach listeners to (default: globalThis). Pass a custom target for testability. */
     target?: EventTarget;
 }
@@ -98,8 +98,7 @@ export declare function createActionBinding(binding: ActionBinding): ActionBindi
  *
  * @example
  * ```typescript
- * const ecs = ECSpresso
- *   .create<Components, Events, Resources>()
+ * const ecs = ECSpresso.create()
  *   .withBundle(createInputBundle({
  *     actions: {
  *       jump: { keys: [' ', 'ArrowUp'] },
@@ -114,5 +113,5 @@ export declare function createActionBinding(binding: ActionBinding): ActionBindi
  * if (input.keyboard.isDown('ArrowRight')) { ... }
  * ```
  */
-export declare function createInputBundle(options?: InputBundleOptions): Bundle<{}, {}, InputResourceTypes>;
+export declare function createInputBundle<A extends string = string, G extends string = 'input'>(options?: InputBundleOptions<A, G>): Bundle<{}, {}, InputResourceTypes<A>, {}, {}, 'input-state', G>;
 export {};

package/dist/bundles/physics2D.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Physics 2D Bundle for ECSpresso
+ *
+ * Provides ECS-native arcade physics: gravity, forces, drag, semi-implicit Euler
+ * integration, and impulse-based collision response with friction.
+ *
+ * Reuses collider types from the collision bundle for shape definitions.
+ * Has its own collision detection in fixedUpdate for physics response;
+ * the existing collision bundle can still run in postUpdate for game logic events.
+ */
+import { Bundle } from 'ecspresso';
+import type { SystemPhase } from 'ecspresso';
+import type { TransformComponentTypes } from './transform';
+import type { CollisionComponentTypes, LayerFactories } from './collision';
+import type { Vector2D } from 'ecspresso';
+/**
+ * Rigid body types for physics simulation.
+ * - 'dynamic': Fully simulated (gravity, forces, collisions)
+ * - 'kinematic': Moves via velocity only (ignores gravity/forces, immovable in collisions)
+ * - 'static': Immovable (ignores gravity, forces, and velocity)
+ */
+export type BodyType = 'dynamic' | 'kinematic' | 'static';
+/**
+ * Rigid body component controlling physics behavior.
+ */
+export interface RigidBody {
+    type: BodyType;
+    /** Mass in arbitrary units. Affects force→acceleration. Infinity = immovable. */
+    mass: number;
+    /** Linear velocity damping coefficient (units/sec, 0 = none) */
+    drag: number;
+    /** Bounciness 0–1 (0 = no bounce, 1 = perfectly elastic) */
+    restitution: number;
+    /** Surface friction coefficient 0–1 */
+    friction: number;
+    /** Per-entity gravity multiplier (0 = no gravity) */
+    gravityScale: number;
+}
+/**
+ * Component types provided by the physics bundle.
+ */
+export interface Physics2DComponentTypes<L extends string = never> extends TransformComponentTypes, CollisionComponentTypes<L> {
+    rigidBody: RigidBody;
+    velocity: Vector2D;
+    force: Vector2D;
+}
+/**
+ * Physics configuration resource.
+ */
+export interface Physics2DConfig {
+    gravity: Vector2D;
+}
+export interface Physics2DResourceTypes {
+    physicsConfig: Physics2DConfig;
+}
+/**
+ * Event emitted for each physics collision pair.
+ */
+export interface Physics2DCollisionEvent {
+    entityA: number;
+    entityB: number;
+    /** Unit normal pointing from A toward B */
+    normal: Vector2D;
+    /** Penetration depth (positive) */
+    depth: number;
+}
+export interface Physics2DEventTypes {
+    physicsCollision: Physics2DCollisionEvent;
+}
+export interface Physics2DBundleOptions<G extends string = 'physics2D', CG extends string = never> {
+    /** World gravity vector (default: {x: 0, y: 0}) */
+    gravity?: Vector2D;
+    /** System group name (default: 'physics2D') */
+    systemGroup?: G;
+    /** Additional group for the collision system only (default: none).
+     * When set, the collision system belongs to both `systemGroup` and this group,
+     * allowing independent enable/disable of collision detection. */
+    collisionSystemGroup?: CG;
+    /** Priority for integration system (default: 1000) */
+    integrationPriority?: number;
+    /** Priority for collision system (default: 900) */
+    collisionPriority?: number;
+    /** Execution phase (default: 'fixedUpdate') */
+    phase?: SystemPhase;
+}
+export interface RigidBodyOptions {
+    mass?: number;
+    drag?: number;
+    restitution?: number;
+    friction?: number;
+    gravityScale?: number;
+}
+/**
+ * Create a rigid body + force component pair.
+ * Static bodies automatically get mass=Infinity.
+ */
+export declare function createRigidBody(type: BodyType, options?: RigidBodyOptions): {
+    rigidBody: RigidBody;
+    force: Vector2D;
+};
+/**
+ * Create a force component with initial values.
+ */
+export declare function createForce(x: number, y: number): {
+    force: Vector2D;
+};
+/**
+ * Accumulate a force onto an entity's force component.
+ */
+export declare function applyForce(ecs: {
+    entityManager: {
+        getComponent(id: number, name: 'force'): Vector2D | undefined;
+    };
+}, entityId: number, fx: number, fy: number): void;
+/**
+ * Apply an instantaneous impulse: velocity += impulse / mass.
+ */
+export declare function applyImpulse(ecs: {
+    entityManager: {
+        getComponent(id: number, name: 'velocity'): Vector2D | undefined;
+        getComponent(id: number, name: 'rigidBody'): RigidBody | undefined;
+    };
+}, entityId: number, ix: number, iy: number): void;
+/**
+ * Directly set an entity's velocity.
+ */
+export declare function setVelocity(ecs: {
+    entityManager: {
+        getComponent(id: number, name: 'velocity'): Vector2D | undefined;
+    };
+}, entityId: number, vx: number, vy: number): void;
+/**
+ * Create a 2D physics bundle for ECSpresso.
+ *
+ * Provides:
+ * - Semi-implicit Euler integration (gravity, forces, drag → velocity → position)
+ * - Impulse-based collision response with restitution and friction
+ * - physicsCollision events with contact normal and depth
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createPhysics2DBundle({ gravity: { x: 0, y: 980 } }))
+ *   .withFixedTimestep(1/60)
+ *   .build();
+ *
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createRigidBody('dynamic', { mass: 1, restitution: 0.5 }),
+ *   velocity: { x: 0, y: 0 },
+ *   ...createAABBCollider(32, 32),
+ *   ...createCollisionLayer('player', ['ground']),
+ * });
+ * ```
+ */
+export declare function createPhysics2DBundle<L extends string = never, G extends string = 'physics2D', CG extends string = never>(options?: Physics2DBundleOptions<G, CG> & {
+    layers?: LayerFactories<Record<L, readonly string[]>>;
+}): Bundle<Physics2DComponentTypes<L>, Physics2DEventTypes, Physics2DResourceTypes, {}, {}, 'physics2D-integration' | 'physics2D-collision', G | CG>;