ecspresso 0.5.0 → 0.7.0

package/README.md

@@ -15,6 +15,11 @@ A type-safe, modular, and extensible Entity Component System (ECS) framework for
 - **Screen Management**: Game state/screen transitions with overlay support
 - **Entity Hierarchy**: Parent-child relationships with traversal and cascade deletion
 - **Query System**: Powerful entity filtering with helper type utilities
+- **Reactive Queries**: Enter/exit callbacks when entities match or unmatch queries
+- **System Groups**: Enable/disable groups of systems at runtime
+- **Component Lifecycle**: Callbacks for component add/remove with unsubscribe support
+- **Command Buffer**: Deferred structural changes for safe entity/component operations during systems
+- **Timer Bundle**: ECS-native timers with event-based completion notifications
 
 ## Installation
 
@@ -212,6 +217,35 @@ world.addSystem('physics')
   .build();
 ```
 
+### System Groups
+
+Organize systems into groups that can be enabled/disabled at runtime:
+
+```typescript
+// Assign systems to groups
+world.addSystem('renderSprites')
+  .inGroup('rendering')
+  .addQuery('sprites', { with: ['position', 'sprite'] })
+  .setProcess((queries) => { /* ... */ })
+  .and()
+  .addSystem('renderParticles')
+  .inGroup('rendering')
+  .inGroup('effects')  // Systems can belong to multiple groups
+  .setProcess(() => { /* ... */ })
+  .build();
+
+// Disable/enable groups at runtime
+world.disableSystemGroup('rendering');  // All rendering systems skip
+world.enableSystemGroup('rendering');   // Resume rendering
+
+// Query group state
+world.isSystemGroupEnabled('rendering');  // true/false
+world.getSystemsInGroup('rendering');     // ['renderSprites', 'renderParticles']
+
+// If a system belongs to multiple groups, disabling ANY group skips the system
+world.disableSystemGroup('effects');  // renderParticles won't run
+```
+
 ## Advanced Features
 
 ### Bundles
@@ -316,7 +350,8 @@ Create resources lazily with factory functions:
 ```typescript
 interface Resources {
   config: { difficulty: string; soundEnabled: boolean };
-  assets: { textures: any[] };
+  database: Database;
+  cache: { db: Database };
 }
 
 const world = new ECSpresso<Components, {}, Resources>();
@@ -328,15 +363,87 @@ world.addResource('config', () => ({
 }));
 
 // Async factory
-world.addResource('assets', async () => {
-  const textures = await loadTextures();
-  return { textures };
+world.addResource('database', async () => {
+  return await connectToDatabase();
+});
+
+// Factory with dependencies - initialized after dependencies are ready
+world.addResource('cache', {
+  dependsOn: ['database'],
+  factory: (ecs) => ({
+    db: ecs.getResource('database')
+  })
 });
 
-// Initialize all resources
+// Initialize all resources (respects dependency order)
 await world.initializeResources();
 ```
 
+**Dependency Features:**
+- Resources are initialized in topological order (dependencies first)
+- Circular dependencies throw a descriptive error at initialization time
+- Existing patterns (direct values, simple factories) work unchanged
+
+### Resource Builder
+
+Add resources fluently during ECSpresso construction using `withResource()`:
+
+```typescript
+const world = ECSpresso
+  .create<Components, Events, Resources>()
+  .withBundle(physicsBundle)
+  .withResource('config', { debug: true, maxEntities: 1000 })
+  .withResource('score', () => ({ value: 0 }))
+  .withResource('cache', {
+    dependsOn: ['database'],
+    factory: (ecs) => createCache(ecs.getResource('database'))
+  })
+  .build();
+```
+
+This chains naturally with `withBundle()`, `withAssets()`, and `withScreens()`.
+
+### Resource Disposal
+
+Resources can define cleanup logic with `onDispose` callbacks, useful for removing event listeners, closing connections, or releasing resources:
+
+```typescript
+// Factory with disposal callback
+world.addResource('keyboard', {
+  factory: () => {
+    const handler = (e: KeyboardEvent) => { /* ... */ };
+    window.addEventListener('keydown', handler);
+    return { handler };
+  },
+  onDispose: (resource) => {
+    window.removeEventListener('keydown', resource.handler);
+  }
+});
+
+// Or with the builder pattern
+const world = ECSpresso
+  .create<Components, Events, Resources>()
+  .withResource('database', {
+    factory: async () => await connectToDatabase(),
+    onDispose: async (db) => await db.close()
+  })
+  .build();
+
+// Dispose a single resource
+await world.disposeResource('keyboard');
+
+// Dispose all resources in reverse dependency order
+// (dependents are disposed before their dependencies)
+await world.disposeResources();
+```
+
+**Disposal Features:**
+- `onDispose` receives the resource value and the ECSpresso instance as context
+- `disposeResources()` disposes in reverse topological order (dependents first)
+- Only initialized resources have their `onDispose` called
+- Supports both sync and async disposal callbacks
+- `removeResource()` still exists for removal without disposal
+
 ### System Lifecycle
 
 Systems can have initialization and cleanup hooks:
@@ -446,6 +553,32 @@ world.getChildAt(root.id, 0);         // child.id
 world.getChildIndex(root.id, child2.id); // 1
 ```
 
+#### Parent-First Traversal
+
+Iterate the hierarchy with guaranteed parent-first order (useful for transform propagation):
+
+```typescript
+// Callback-based traversal
+world.forEachInHierarchy((entityId, parentId, depth) => {
+  // Parents are always visited before their children
+  console.log(`Entity ${entityId} at depth ${depth}, parent: ${parentId}`);
+});
+
+// Filter to specific subtrees
+world.forEachInHierarchy(
+  (entityId, parentId, depth) => {
+    // Only visits entities under root.id
+  },
+  { roots: [root.id] }
+);
+
+// Generator-based traversal (supports early termination)
+for (const { entityId, parentId, depth } of world.hierarchyIterator()) {
+  if (depth > 2) break; // Stop at depth 2
+  console.log(entityId);
+}
+```
+
 #### Cascade Deletion
 
 When removing entities, descendants are automatically removed by default:
@@ -771,17 +904,254 @@ world.withBundle(conflictingBundle); // TypeScript prevents this
 
 ## Component Callbacks
 
-React to component changes with callbacks:
+React to component changes with callbacks. Both methods return an unsubscribe function:
 
 ```typescript
-// Listen for component additions/removals
-world.entityManager.onComponentAdded('health', (value, entity) => {
+// Listen for component additions - returns unsubscribe function
+const unsubAdd = world.onComponentAdded('health', (value, entity) => {
   console.log(`Health added to entity ${entity.id}:`, value);
 });
 
-world.entityManager.onComponentRemoved('health', (oldValue, entity) => {
+// Listen for component removals
+const unsubRemove = world.onComponentRemoved('health', (oldValue, entity) => {
   console.log(`Health removed from entity ${entity.id}:`, oldValue);
 });
+
+// Unsubscribe when done
+unsubAdd();
+unsubRemove();
+
+// Also available on entityManager directly
+world.entityManager.onComponentAdded('position', (value, entity) => {
+  // ...
+});
+```
+
+## Reactive Queries
+
+Get callbacks when entities enter or exit a query match. Unlike regular queries that you poll during `update()`, reactive queries push notifications when the entity's components change:
+
+```typescript
+// Add a reactive query with enter/exit callbacks
+world.addReactiveQuery('enemies', {
+  with: ['position', 'enemy'],
+  without: ['dead'],
+  onEnter: (entity) => {
+    // Called when entity starts matching the query
+    console.log(`Enemy ${entity.id} appeared at`, entity.components.position);
+    spawnHealthBar(entity.id);
+  },
+  onExit: (entityId) => {
+    // Called when entity stops matching (receives ID since entity may be removed)
+    console.log(`Enemy ${entityId} gone`);
+    removeHealthBar(entityId);
+  },
+});
+
+// Triggers: spawning matching entity, adding required component,
+//           removing excluded component
+const enemy = world.spawn({ position: { x: 0, y: 0 }, enemy: true }); // onEnter fires
+
+// Triggers: removing required component, adding excluded component,
+//           removing entity
+world.entityManager.addComponent(enemy.id, 'dead', true); // onExit fires
+
+// Existing matching entities trigger onEnter when query is added
+world.spawn({ position: { x: 10, y: 10 }, enemy: true });
+world.addReactiveQuery('positioned', {
+  with: ['position'],
+  onEnter: (entity) => { /* Called for all existing entities with position */ },
+});
+
+// Remove reactive query when no longer needed
+const removed = world.removeReactiveQuery('enemies'); // returns true if existed
+```
+
+**Note:** Component replacement (calling `addComponent` with a component that already exists) does NOT trigger enter/exit callbacks since the entity's query match status doesn't change.
+
+## Command Buffer
+
+The command buffer allows you to queue structural changes (entity creation, removal, component changes) that execute at the end of the update cycle. This prevents issues when modifying entities during system iteration.
+
+```typescript
+// Queue commands during system execution
+world.addSystem('combat')
+  .addQuery('enemies', { with: ['enemy', 'health'] })
+  .setProcess((queries, dt, ecs) => {
+    for (const entity of queries.enemies) {
+      if (entity.components.health.value <= 0) {
+        // Queue removal - doesn't execute immediately
+        ecs.commands.removeEntity(entity.id);
+
+        // Queue spawning an explosion
+        ecs.commands.spawn({
+          position: entity.components.position,
+          explosion: true,
+        });
+      }
+    }
+    // Commands execute automatically at end of update()
+  })
+  .build();
+```
+
+### Available Commands
+
+```typescript
+// Entity operations
+ecs.commands.spawn({ position: { x: 0, y: 0 } });
+ecs.commands.spawnChild(parentId, { position: { x: 10, y: 0 } });
+ecs.commands.removeEntity(entityId);
+ecs.commands.removeEntity(entityId, { cascade: false }); // Orphan children
+
+// Component operations
+ecs.commands.addComponent(entityId, 'velocity', { x: 5, y: 0 });
+ecs.commands.addComponents(entityId, { velocity: { x: 5, y: 0 }, health: { value: 100 } });
+ecs.commands.removeComponent(entityId, 'velocity');
+
+// Hierarchy operations
+ecs.commands.setParent(childId, parentId);
+ecs.commands.removeParent(childId);
+
+// Utility
+ecs.commands.length;  // Number of queued commands
+ecs.commands.clear(); // Discard all queued commands
+```
+
+Commands execute in FIFO order. If a command fails (e.g., entity doesn't exist), it logs a warning and continues with remaining commands.
+
+## Built-in Bundles
+
+ECSpresso provides optional utility bundles for common game development needs:
+
+| Bundle | Import | Description |
+|--------|--------|-------------|
+| **Transform** | `ecspresso/bundles/utils/transform` | Hierarchical transform propagation (local/world transforms) |
+| **Movement** | `ecspresso/bundles/utils/movement` | Velocity-based movement integration |
+| **Bounds** | `ecspresso/bundles/utils/bounds` | Screen bounds enforcement (destroy, clamp, wrap) |
+| **Collision** | `ecspresso/bundles/utils/collision` | Layer-based AABB/circle collision detection with events |
+| **Timers** | `ecspresso/bundles/utils/timers` | ECS-native timers with event-based completion |
+| **PixiJS Renderer** | `ecspresso/bundles/renderers/pixi` | Automated PixiJS scene graph wiring |
+
+## Timer Bundle
+
+The timer bundle provides ECS-native timers that follow the "data, not callbacks" philosophy. Timers are components processed each frame, with optional event-based completion notifications.
+
+```typescript
+import {
+  createTimerBundle,
+  createTimer,
+  createRepeatingTimer,
+  type TimerComponentTypes,
+  type TimerEventData
+} from 'ecspresso/bundles/utils/timers';
+
+// Define events that use TimerEventData payload
+interface Events {
+  hideMessage: TimerEventData;
+  spawnWave: TimerEventData;
+}
+
+// Extend components with timer support
+interface Components extends TimerComponentTypes<Events> {
+  position: { x: number; y: number };
+  messageDisplay: true;
+  spawner: true;
+}
+
+// Create world with timer bundle
+const world = ECSpresso
+  .create<Components, Events, Resources>()
+  .withBundle(createTimerBundle<Events>())
+  .build();
+
+// One-shot timer without event (poll justFinished)
+world.spawn({
+  ...createTimer<Events>(2.0),
+  messageDisplay: true,
+});
+
+// One-shot timer with completion event
+world.spawn({
+  ...createTimer<Events>(1.5, { onComplete: 'hideMessage' }),
+  messageDisplay: true,
+});
+
+// Repeating timer with event
+world.spawn({
+  ...createRepeatingTimer<Events>(5.0, { onComplete: 'spawnWave' }),
+  spawner: true,
+});
+
+// Subscribe to timer events
+world.on('hideMessage', (data) => {
+  console.log(`Timer on entity ${data.entityId} completed after ${data.elapsed}s`);
+});
+```
+
+### Timer Event Data
+
+Events used with timer `onComplete` must have `TimerEventData` as their payload type:
+
+```typescript
+interface TimerEventData {
+  entityId: number;  // Entity the timer belongs to
+  duration: number;  // Timer's configured duration
+  elapsed: number;   // Actual elapsed time (may exceed duration slightly)
+}
+```
+
+### Polling vs Events
+
+You can use timers in two ways:
+
+```typescript
+// 1. Polling with justFinished flag
+world.addSystem('timerPolling')
+  .addQuery('timers', { with: ['timer', 'messageDisplay'] })
+  .setProcess((queries) => {
+    for (const entity of queries.timers) {
+      if (entity.components.timer.justFinished) {
+        // Timer just completed this frame
+        hideMessage(entity.id);
+      }
+    }
+  })
+  .build();
+
+// 2. Event-based (decoupled)
+world.addSystem('timerEvents')
+  .setEventHandlers({
+    hideMessage: {
+      handler: (data, ecs) => {
+        // React to timer completion
+        ecs.commands.removeEntity(data.entityId);
+      }
+    }
+  })
+  .build();
+```
+
+### Timer Properties
+
+```typescript
+interface Timer {
+  elapsed: number;      // Time accumulated (seconds)
+  duration: number;     // Target duration (seconds)
+  repeat: boolean;      // Whether timer repeats
+  active: boolean;      // Whether timer is running
+  justFinished: boolean; // True for one frame after completion
+  onComplete?: string;  // Event name to publish (optional)
+}
+
+// Control timer at runtime
+const entity = world.spawn({ ...createTimer<Events>(5.0), myTimer: true });
+const timer = entity.components.timer;
+
+timer.active = false;  // Pause
+timer.active = true;   // Resume
+timer.elapsed = 0;     // Reset
+timer.duration = 10;   // Change duration
 ```
 
 ## Error Handling

package/dist/bundle.d.ts

@@ -31,9 +31,12 @@ export default class Bundle<ComponentTypes extends Record<string, any> = {}, Eve
     /**
      * Add a resource to this bundle
      * @param label The resource key
-     * @param resource The resource value or a factory function that returns the resource
+     * @param resource The resource value, a factory function, or a factory with dependencies
      */
-    addResource<K extends keyof ResourceTypes>(label: K, resource: ResourceTypes[K] | ((ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>)): this;
+    addResource<K extends keyof ResourceTypes>(label: K, resource: ResourceTypes[K] | ((ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>) | {
+        dependsOn: readonly string[];
+        factory: (ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>;
+    }): this;
     /**
      * Add an asset to this bundle
      * @param key The asset key

package/dist/bundles/renderers/pixi.d.ts

@@ -0,0 +1,235 @@
+/**
+ * PixiJS Renderer Bundle for ECSpresso
+ *
+ * An opt-in PixiJS rendering bundle that automates scene graph wiring.
+ * Import from 'ecspresso/bundles/renderers/pixi'
+ *
+ * Note: This bundle requires the transform bundle for transform propagation.
+ * Add createTransformBundle() before this bundle.
+ */
+import type { Application, ApplicationOptions, Container, Sprite, Graphics } from 'pixi.js';
+import Bundle from '../../bundle';
+import type { LocalTransform, WorldTransform, TransformComponentTypes } from '../utils/transform';
+export type { LocalTransform, WorldTransform, TransformComponentTypes };
+export { createTransform, createLocalTransform, createWorldTransform } from '../utils/transform';
+/**
+ * PixiJS Sprite component
+ */
+export interface PixiSprite {
+    sprite: Sprite;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * PixiJS Graphics component
+ */
+export interface PixiGraphics {
+    graphics: Graphics;
+}
+/**
+ * PixiJS Container component
+ */
+export interface PixiContainer {
+    container: Container;
+}
+/**
+ * Visibility and alpha component
+ */
+export interface PixiVisible {
+    visible: boolean;
+    alpha?: number;
+}
+/**
+ * Aggregate component types for PixiJS bundle.
+ * Users should extend this interface with their own component types.
+ *
+ * @example
+ * ```typescript
+ * interface GameComponents extends PixiComponentTypes {
+ *   velocity: { x: number; y: number };
+ *   player: true;
+ * }
+ * ```
+ */
+export interface PixiComponentTypes extends TransformComponentTypes {
+    pixiSprite: PixiSprite;
+    pixiGraphics: PixiGraphics;
+    pixiContainer: PixiContainer;
+    pixiVisible: PixiVisible;
+}
+/**
+ * Events emitted by the PixiJS bundle
+ */
+export interface PixiEventTypes {
+    hierarchyChanged: {
+        entityId: number;
+        oldParent: number | null;
+        newParent: number | null;
+    };
+}
+/**
+ * Resources provided by the PixiJS bundle
+ */
+export interface PixiResourceTypes {
+    pixiApp: Application;
+    pixiRootContainer: Container;
+}
+/**
+ * Common options shared between both initialization modes
+ */
+interface PixiBundleCommonOptions {
+    /** Optional custom root container (defaults to app.stage) */
+    rootContainer?: Container;
+    /** System group name (default: 'pixi-renderer') */
+    systemGroup?: string;
+    /** Priority for render sync system (default: 500) */
+    renderSyncPriority?: number;
+}
+/**
+ * Options when providing a pre-initialized PixiJS Application
+ */
+export interface PixiBundleAppOptions extends PixiBundleCommonOptions {
+    /** The PixiJS Application instance (already initialized) */
+    app: Application;
+    init?: never;
+    container?: never;
+}
+/**
+ * Options when letting the bundle create and manage the PixiJS Application
+ */
+export interface PixiBundleManagedOptions extends PixiBundleCommonOptions {
+    app?: never;
+    /** PixiJS ApplicationOptions - bundle will create and initialize the Application */
+    init: Partial<ApplicationOptions>;
+    /** Container element to append the canvas to, or CSS selector string */
+    container?: HTMLElement | string;
+}
+/**
+ * Configuration options for the PixiJS bundle.
+ *
+ * Supports two modes:
+ * 1. **Pre-initialized**: Pass an already-initialized Application via `app`
+ * 2. **Managed**: Pass `init` options and the bundle creates the Application during `ecs.initialize()`
+ *
+ * @example Pre-initialized mode (full control)
+ * ```typescript
+ * const app = new Application();
+ * await app.init({ resizeTo: window });
+ * const ecs = ECSpresso.create<...>()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createPixiBundle({ app }))
+ *   .build();
+ * ```
+ *
+ * @example Managed mode (convenience)
+ * ```typescript
+ * const ecs = ECSpresso.create<...>()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createPixiBundle({
+ *     init: { background: '#1099bb', resizeTo: window },
+ *     container: document.body,
+ *   }))
+ *   .build();
+ * await ecs.initialize(); // Application created here
+ * ```
+ */
+export type PixiBundleOptions = PixiBundleAppOptions | PixiBundleManagedOptions;
+/**
+ * Default local transform values
+ */
+export declare const DEFAULT_LOCAL_TRANSFORM: Readonly<LocalTransform>;
+/**
+ * Default world transform values
+ */
+export declare const DEFAULT_WORLD_TRANSFORM: Readonly<WorldTransform>;
+interface PositionOption {
+    x?: number;
+    y?: number;
+}
+interface TransformOptions {
+    rotation?: number;
+    scale?: number | {
+        x: number;
+        y: number;
+    };
+    visible?: boolean;
+    alpha?: number;
+}
+/**
+ * Create components for a sprite entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const player = ecs.spawn({
+ *   ...createSpriteComponents(new Sprite(texture), { x: 100, y: 100 }),
+ *   velocity: { x: 0, y: 0 },
+ * });
+ * ```
+ */
+export declare function createSpriteComponents(sprite: Sprite, position?: PositionOption, options?: TransformOptions & {
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}): Pick<PixiComponentTypes, 'pixiSprite' | 'localTransform' | 'worldTransform' | 'pixiVisible'>;
+/**
+ * Create components for a graphics entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const rect = ecs.spawn({
+ *   ...createGraphicsComponents(graphics, { x: 50, y: 50 }),
+ * });
+ * ```
+ */
+export declare function createGraphicsComponents(graphics: Graphics, position?: PositionOption, options?: TransformOptions): Pick<PixiComponentTypes, 'pixiGraphics' | 'localTransform' | 'worldTransform' | 'pixiVisible'>;
+/**
+ * Create components for a container entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const group = ecs.spawn({
+ *   ...createContainerComponents(new Container(), { x: 0, y: 0 }),
+ * });
+ * ```
+ */
+export declare function createContainerComponents(container: Container, position?: PositionOption, options?: TransformOptions): Pick<PixiComponentTypes, 'pixiContainer' | 'localTransform' | 'worldTransform' | 'pixiVisible'>;
+/**
+ * Create a PixiJS rendering bundle for ECSpresso.
+ *
+ * This bundle provides:
+ * - Render sync system (updates PixiJS objects from ECS components)
+ * - Scene graph management (mirrors ECS hierarchy in PixiJS scene graph)
+ *
+ * **Important**: This bundle requires the transform bundle for transform propagation.
+ * Add `createTransformBundle()` before this bundle.
+ *
+ * @example Pre-initialized mode
+ * ```typescript
+ * const app = new Application();
+ * await app.init({ resizeTo: window });
+ *
+ * const ecs = ECSpresso.create<GameComponents, {}, {}>()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createPixiBundle({ app }))
+ *   .build();
+ * ```
+ *
+ * @example Managed mode
+ * ```typescript
+ * const ecs = ECSpresso.create<GameComponents, {}, {}>()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createPixiBundle({
+ *     init: { background: '#1099bb', resizeTo: window },
+ *     container: document.body,
+ *   }))
+ *   .build();
+ * await ecs.initialize();
+ * ```
+ */
+export declare function createPixiBundle(options: PixiBundleOptions): Bundle<PixiComponentTypes, PixiEventTypes, PixiResourceTypes>;