ecspresso 0.10.2 → 0.12.0

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

@@ -1,15 +1,15 @@
 /**
- * Input Bundle for ECSpresso
+ * Input Plugin for ECSpresso
  *
  * Provides frame-accurate keyboard, pointer (mouse + touch via PointerEvent),
- * and action mapping input. Resource-only bundle — input is polled via the
+ * and action mapping input. Resource-only plugin — input is polled via the
  * `inputState` resource. No ECS components or events.
  *
  * DOM events are accumulated between frames and snapshotted once per frame
  * in the system's process step, so all systems see consistent state.
  */
-import { Bundle } from 'ecspresso';
-import type { SystemPhase } from 'ecspresso';
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
 export interface Vec2 {
     x: number;
     y: number;
@@ -48,35 +48,29 @@ 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 {
-    /** System group name (default: 'input') */
-    systemGroup?: string;
-    /** Priority for input system (default: 100) */
-    priority?: number;
-    /** Execution phase (default: 'preUpdate') */
-    phase?: SystemPhase;
+export interface InputPluginOptions<A extends string = string, G extends string = 'input'> extends BasePluginOptions<G> {
     /** Initial action mappings */
-    actions?: ActionMap;
+    actions?: ActionMap<A>;
     /** EventTarget to attach listeners to (default: globalThis). Pass a custom target for testability. */
     target?: EventTarget;
 }
@@ -88,9 +82,9 @@ export interface InputBundleOptions {
  */
 export declare function createActionBinding(binding: ActionBinding): ActionBinding;
 /**
- * Create an input bundle for ECSpresso.
+ * Create an input plugin for ECSpresso.
  *
- * This bundle provides:
+ * This plugin provides:
  * - Frame-accurate keyboard state (isDown, justPressed, justReleased)
  * - Pointer position/delta and button state (mouse + touch via PointerEvent)
  * - Named action mapping with runtime remapping
@@ -98,9 +92,8 @@ export declare function createActionBinding(binding: ActionBinding): ActionBindi
  *
  * @example
  * ```typescript
- * const ecs = ECSpresso
- *   .create<Components, Events, Resources>()
- *   .withBundle(createInputBundle({
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createInputPlugin({
  *     actions: {
  *       jump: { keys: [' ', 'ArrowUp'] },
  *       shoot: { keys: ['z'], buttons: [0] },
@@ -114,5 +107,5 @@ export declare function createActionBinding(binding: ActionBinding): ActionBindi
  * if (input.keyboard.isDown('ArrowRight')) { ... }
  * ```
  */
-export declare function createInputBundle(options?: InputBundleOptions): Bundle<{}, {}, InputResourceTypes>;
+export declare function createInputPlugin<A extends string = string, G extends string = 'input'>(options?: InputPluginOptions<A, G>): Plugin<WorldConfigFrom<{}, {}, InputResourceTypes<A>>, EmptyConfig, 'input-state', G>;
 export {};

package/dist/plugins/particles.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Particle System Plugin for ECSpresso
+ *
+ * High-performance particle system where particles live outside the ECS in
+ * pre-allocated pools. Renders via PixiJS v8's ParticleContainer + Particle API.
+ * Renderer2D is a required dependency.
+ *
+ * Follows the established plugin pattern: immutable shared config
+ * (ParticleEffectConfig) + mutable per-entity state (ParticleEmitter) component,
+ * side-storage Map for PixiJS objects, kit pattern for typed helpers.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { BaseWorld } from 'ecspresso';
+import type { WorldConfigFrom } from '../type-utils';
+import type { TransformComponentTypes } from 'ecspresso/plugins/transform';
+/** BaseWorld narrowed to particle components for typed access in helpers. */
+type ParticleWorld = BaseWorld<ParticleComponentTypes>;
+/** Fixed value or random range [min, max] */
+export type ParticleValue = number | readonly [number, number];
+/** Emission geometry */
+export type EmissionShape = 'point' | 'circle';
+/** Blend modes for particle rendering */
+export type ParticleBlendMode = 'normal' | 'add' | 'multiply' | 'screen';
+/**
+ * User-facing config input for defining a particle effect.
+ * All properties optional except maxParticles and texture.
+ */
+export interface ParticleEffectInput {
+    /** Pool size — maximum simultaneous particles */
+    maxParticles: number;
+    /** PixiJS Texture for particles */
+    texture: unknown;
+    /** Particles per second (0 = burst-only, default: 10) */
+    spawnRate?: number;
+    /** Particles per burst (default: 0) */
+    burstCount?: number;
+    /** Emitter lifetime in seconds (-1 = infinite, default: -1) */
+    duration?: number;
+    /** Per-particle lifetime in seconds (default: 1) */
+    lifetime?: ParticleValue;
+    /** Initial speed in pixels/second (default: 100) */
+    speed?: ParticleValue;
+    /** Emission direction in radians (default: [0, 2*PI]) */
+    angle?: ParticleValue;
+    /** Spawn geometry (default: 'point') */
+    emissionShape?: EmissionShape;
+    /** Radius for 'circle' shape (default: 0) */
+    emissionRadius?: number;
+    /** Acceleration in pixels/second^2 (default: {x: 0, y: 0}) */
+    gravity?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /** Initial scale (default: 1) */
+    startSize?: ParticleValue;
+    /** Final scale (default: same as startSize) */
+    endSize?: ParticleValue;
+    /** Initial opacity (default: 1) */
+    startAlpha?: ParticleValue;
+    /** Final opacity (default: 0) */
+    endAlpha?: ParticleValue;
+    /** Initial hex color (default: 0xffffff) */
+    startTint?: number;
+    /** Final hex color (default: same as startTint) */
+    endTint?: number;
+    /** Initial rotation in radians (default: 0) */
+    startRotation?: ParticleValue;
+    /** Rotation velocity in rad/s (default: 0) */
+    rotationSpeed?: ParticleValue;
+    /** Blend mode (default: 'normal') */
+    blendMode?: ParticleBlendMode;
+    /** Particles in world coordinates (default: true) */
+    worldSpace?: boolean;
+}
+/**
+ * Frozen, fully-resolved particle effect config.
+ * Output of defineParticleEffect.
+ */
+export interface ParticleEffectConfig {
+    readonly maxParticles: number;
+    readonly texture: unknown;
+    readonly spawnRate: number;
+    readonly burstCount: number;
+    readonly duration: number;
+    readonly lifetime: ParticleValue;
+    readonly speed: ParticleValue;
+    readonly angle: ParticleValue;
+    readonly emissionShape: EmissionShape;
+    readonly emissionRadius: number;
+    readonly gravity: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly startSize: ParticleValue;
+    readonly endSize: ParticleValue;
+    readonly startAlpha: ParticleValue;
+    readonly endAlpha: ParticleValue;
+    readonly startTint: number;
+    readonly endTint: number;
+    readonly startRotation: ParticleValue;
+    readonly rotationSpeed: ParticleValue;
+    readonly blendMode: ParticleBlendMode;
+    readonly worldSpace: boolean;
+}
+/**
+ * Mutable per-particle state. Pre-allocated, never GC'd.
+ */
+export interface ParticleState {
+    active: boolean;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    life: number;
+    maxLife: number;
+    size: number;
+    startSize: number;
+    endSize: number;
+    alpha: number;
+    startAlpha: number;
+    endAlpha: number;
+    tint: number;
+    rotation: number;
+    rotationSpeed: number;
+}
+/**
+ * Per-entity emitter state stored as an ECS component.
+ */
+export interface ParticleEmitter {
+    readonly config: ParticleEffectConfig;
+    activeCount: number;
+    spawnAccumulator: number;
+    elapsed: number;
+    playing: boolean;
+    pendingBurst: number;
+    finished: boolean;
+    onComplete?: (data: ParticleEmitterEventData) => void;
+}
+/**
+ * Component types provided by the particle plugin.
+ */
+export interface ParticleComponentTypes {
+    particleEmitter: ParticleEmitter;
+}
+/**
+ * Data published when an emitter completes.
+ */
+export interface ParticleEmitterEventData {
+    entityId: number;
+}
+export interface ParticlePluginOptions<G extends string = 'particles'> extends BasePluginOptions<G> {
+}
+/**
+ * Sample a ParticleValue: returns fixed value or random within [min, max].
+ */
+export declare function sampleRange(value: ParticleValue): number;
+/**
+ * Linear interpolation between two hex colors (RGB channels).
+ */
+export declare function lerpTint(start: number, end: number, t: number): number;
+/**
+ * Define a particle effect config with defaults applied and frozen.
+ */
+export declare function defineParticleEffect(input: ParticleEffectInput): ParticleEffectConfig;
+/**
+ * Create a particleEmitter component suitable for spreading into spawn().
+ */
+export declare function createParticleEmitter(config: ParticleEffectConfig, options?: {
+    playing?: boolean;
+    onComplete?: (data: ParticleEmitterEventData) => void;
+}): Pick<ParticleComponentTypes, 'particleEmitter'>;
+/**
+ * Queue a burst of particles on an emitter.
+ * Returns false if entity has no particleEmitter component.
+ */
+export declare function burstParticles(ecs: ParticleWorld, entityId: number, count?: number): boolean;
+/**
+ * Stop an emitter from spawning new particles.
+ * Existing particles continue their lifecycle.
+ */
+export declare function stopEmitter(ecs: ParticleWorld, entityId: number): boolean;
+/**
+ * Resume a stopped emitter.
+ */
+export declare function resumeEmitter(ecs: ParticleWorld, entityId: number): boolean;
+/**
+ * Runtime data stored outside the ECS, keyed by entity ID.
+ */
+export interface EmitterRuntimeData {
+    particles: ParticleState[];
+    pixiContainer: unknown;
+    pixiParticles: unknown[];
+}
+export declare const particlePresets: {
+    readonly explosion: (texture: unknown, overrides?: Partial<ParticleEffectInput>) => ParticleEffectConfig;
+    readonly smoke: (texture: unknown, overrides?: Partial<ParticleEffectInput>) => ParticleEffectConfig;
+    readonly fire: (texture: unknown, overrides?: Partial<ParticleEffectInput>) => ParticleEffectConfig;
+    readonly sparkle: (texture: unknown, overrides?: Partial<ParticleEffectInput>) => ParticleEffectConfig;
+    readonly trail: (texture: unknown, overrides?: Partial<ParticleEffectInput>) => ParticleEffectConfig;
+};
+type ParticleLabels = 'particle-update' | 'particle-render-sync';
+type ParticleRequires = WorldConfigFrom<TransformComponentTypes & {
+    renderLayer: string;
+}>;
+/**
+ * Create a particle system plugin for ECSpresso.
+ *
+ * Provides:
+ * - Pre-allocated particle pools outside the entity system
+ * - Continuous and burst emission modes
+ * - Velocity, gravity, lifetime, interpolation (size, alpha, tint, rotation)
+ * - World-space and local-space particle emission
+ * - PixiJS ParticleContainer rendering (via renderer2D dependency)
+ * - Presets for common effects (explosion, smoke, fire, sparkle, trail)
+ *
+ * Renderer2D is a required dependency.
+ */
+export declare function createParticlePlugin<G extends string = 'particles'>(options?: ParticlePluginOptions<G>): Plugin<WorldConfigFrom<ParticleComponentTypes>, ParticleRequires, ParticleLabels, G, never, 'particle-emitters'>;
+/**
+ * Get the runtime data for an emitter entity.
+ * Useful for tests and advanced usage.
+ * @internal Exported for testing only.
+ */
+export declare function getEmitterData(emitterDataMap: Map<number, EmitterRuntimeData>, entityId: number): EmitterRuntimeData | undefined;
+export {};

package/dist/plugins/physics2D.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Physics 2D Plugin 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 plugin for shape definitions.
+ * Has its own collision detection in fixedUpdate for physics response;
+ * the existing collision plugin can still run in postUpdate for game logic events.
+ */
+import { type Plugin } from 'ecspresso';
+import type { SystemPhase } from 'ecspresso';
+import type { WorldConfigFrom } from '../type-utils';
+import type { TransformComponentTypes, TransformWorldConfig } 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 directly provided by the physics plugin.
+ */
+export interface Physics2DOwnComponentTypes {
+    rigidBody: RigidBody;
+    velocity: Vector2D;
+    force: Vector2D;
+}
+/**
+ * Full component types available when using the physics plugin
+ * (own components + transform + collision dependencies).
+ * Convenience alias for consumer code.
+ */
+export interface Physics2DComponentTypes<L extends string = never> extends TransformComponentTypes, CollisionComponentTypes<L>, Physics2DOwnComponentTypes {
+}
+/**
+ * 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 Physics2DPluginOptions<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: {
+    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: {
+    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: {
+    getComponent(id: number, name: 'velocity'): Vector2D | undefined;
+}, entityId: number, vx: number, vy: number): void;
+/**
+ * Create a 2D physics plugin 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()
+ *   .withPlugin(createTransformPlugin())
+ *   .withPlugin(createPhysics2DPlugin({ 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']),
+ * });
+ * ```
+ */
+type Physics2DProvides<L extends string = never> = Physics2DOwnComponentTypes & CollisionComponentTypes<L>;
+export declare function createPhysics2DPlugin<L extends string = never, G extends string = 'physics2D', CG extends string = never>(options?: Physics2DPluginOptions<G, CG> & {
+    layers?: LayerFactories<Record<L, readonly string[]>>;
+}): Plugin<WorldConfigFrom<Physics2DProvides<L>, Physics2DEventTypes, Physics2DResourceTypes>, TransformWorldConfig, 'physics2D-integration' | 'physics2D-collision', G | CG>;
+export {};