ecspresso 0.4.3 → 0.5.0

package/README.md

@@ -11,6 +11,9 @@ A type-safe, modular, and extensible Entity Component System (ECS) framework for
 - **Developer-Friendly**: Clean, fluent API with method chaining
 - **Event-Driven**: Integrated event system for decoupled communication
 - **Resource Management**: Global state management with lazy loading
+- **Asset Management**: Eager/lazy asset loading with groups and progress tracking
+- **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
 
 ## Installation
@@ -277,6 +280,19 @@ interface Events {
 
 const world = new ECSpresso<Components, Events>();
 
+// Subscribe to events with on() - returns unsubscribe function
+const unsubscribe = world.on('playerDied', (data) => {
+  console.log(`Player ${data.playerId} died`);
+});
+
+// Unsubscribe when done
+unsubscribe();
+
+// Or unsubscribe by callback reference with off()
+const handler = (data) => console.log(`Level complete! Score: ${data.score}`);
+world.on('levelComplete', handler);
+world.off('levelComplete', handler);
+
 // Handle events in systems
 world.addSystem('gameLogic')
   .setEventHandlers({
@@ -341,6 +357,369 @@ world.addSystem('gameSystem')
 await world.initialize();
 ```
 
+### Post-Update Hooks
+
+Register callbacks that run after all systems have processed during `update()`:
+
+```typescript
+// Register a post-update hook - returns unsubscribe function
+const unsubscribe = world.onPostUpdate((ecs, deltaTime) => {
+  // Runs after all systems in update()
+  // Useful for cleanup, state sync, or debug logging
+  console.log(`Frame completed in ${deltaTime}s`);
+});
+
+// Multiple hooks run in registration order
+world.onPostUpdate((ecs) => {
+  // First hook
+});
+world.onPostUpdate((ecs) => {
+  // Second hook
+});
+
+// Unsubscribe when no longer needed
+unsubscribe();
+```
+
+### Entity Hierarchy
+
+Create parent-child relationships between entities for scene graphs, UI trees, or skeletal hierarchies:
+
+```typescript
+const world = new ECSpresso<Components>();
+
+// Create a parent entity
+const player = world.spawn({
+  position: { x: 0, y: 0 }
+});
+
+// Create a child entity using spawnChild
+const weapon = world.spawnChild(player.id, {
+  position: { x: 10, y: 0 }  // Relative to parent
+});
+
+// Or set parent on existing entity
+const shield = world.spawn({ position: { x: -10, y: 0 } });
+world.setParent(shield.id, player.id);
+
+// Query relationships
+world.getParent(weapon.id);           // player.id
+world.getChildren(player.id);         // [weapon.id, shield.id]
+
+// Orphan an entity (remove from parent)
+world.removeParent(shield.id);
+world.getParent(shield.id);           // null
+```
+
+#### Traversal Methods
+
+Navigate the hierarchy tree with traversal utilities:
+
+```typescript
+// Build a hierarchy: root -> child -> grandchild
+const root = world.spawn({ position: { x: 0, y: 0 } });
+const child = world.spawnChild(root.id, { position: { x: 10, y: 0 } });
+const grandchild = world.spawnChild(child.id, { position: { x: 20, y: 0 } });
+
+// Ancestors (from entity up to root)
+world.getAncestors(grandchild.id);    // [child.id, root.id]
+
+// Descendants (depth-first order)
+world.getDescendants(root.id);        // [child.id, grandchild.id]
+
+// Get root of any entity
+world.getRoot(grandchild.id);         // root.id
+
+// Siblings (other children of same parent)
+const child2 = world.spawnChild(root.id, { position: { x: -10, y: 0 } });
+world.getSiblings(child.id);          // [child2.id]
+
+// Relationship checks
+world.isDescendantOf(grandchild.id, root.id);  // true
+world.isAncestorOf(root.id, grandchild.id);    // true
+
+// All root entities (entities with children but no parent)
+world.getRootEntities();              // [root.id]
+
+// Child ordering
+world.getChildAt(root.id, 0);         // child.id
+world.getChildIndex(root.id, child2.id); // 1
+```
+
+#### Cascade Deletion
+
+When removing entities, descendants are automatically removed by default:
+
+```typescript
+const parent = world.spawn({ position: { x: 0, y: 0 } });
+const child = world.spawnChild(parent.id, { position: { x: 10, y: 0 } });
+const grandchild = world.spawnChild(child.id, { position: { x: 20, y: 0 } });
+
+// Remove parent - cascades to all descendants
+world.removeEntity(parent.id);
+world.entityManager.getEntity(child.id);      // undefined
+world.entityManager.getEntity(grandchild.id); // undefined
+
+// To orphan children instead of deleting them:
+world.removeEntity(parent.id, { cascade: false });
+// Children still exist but have no parent
+```
+
+#### Hierarchy Events
+
+React to hierarchy changes with the `hierarchyChanged` event:
+
+```typescript
+interface Events {
+  hierarchyChanged: {
+    entityId: number;
+    oldParent: number | null;
+    newParent: number | null;
+  };
+}
+
+const world = new ECSpresso<Components, Events>();
+
+world.on('hierarchyChanged', (data) => {
+  if (data.newParent !== null) {
+    console.log(`Entity ${data.entityId} attached to ${data.newParent}`);
+  } else {
+    console.log(`Entity ${data.entityId} detached from ${data.oldParent}`);
+  }
+});
+
+// Events fire on setParent, removeParent, and spawnChild
+world.setParent(child.id, parent.id);  // Emits hierarchyChanged
+```
+
+### Asset Management
+
+Manage game assets with eager/lazy loading, groups, and progress tracking:
+
+```typescript
+// Define asset types
+type Assets = {
+  playerTexture: { data: ImageBitmap };
+  enemyTexture: { data: ImageBitmap };
+  level1Music: { buffer: AudioBuffer };
+  level1Background: { data: ImageBitmap };
+};
+
+// Create world with assets using the builder pattern
+const game = ECSpresso.create<Components, Events, Resources, Assets>()
+  .withAssets(assets => assets
+    // Eager assets - loaded automatically during initialize()
+    .add('playerTexture', async () => {
+      const img = await loadImage('player.png');
+      return { data: img };
+    })
+    .add('enemyTexture', async () => {
+      const img = await loadImage('enemy.png');
+      return { data: img };
+    })
+    // Lazy asset group - loaded on demand
+    .addGroup('level1', {
+      level1Music: async () => {
+        const buffer = await loadAudio('level1.mp3');
+        return { buffer };
+      },
+      level1Background: async () => {
+        const img = await loadImage('level1-bg.png');
+        return { data: img };
+      },
+    })
+  )
+  .build();
+
+// Initialize loads eager assets automatically
+await game.initialize();
+
+// Access loaded assets
+const player = game.getAsset('playerTexture');
+
+// Check if asset is loaded
+if (game.isAssetLoaded('enemyTexture')) {
+  const enemy = game.getAsset('enemyTexture');
+}
+
+// Load asset groups on demand (e.g., when entering a level)
+await game.loadAssetGroup('level1');
+
+// Track loading progress
+const progress = game.getAssetGroupProgress('level1'); // 0-1
+
+// Check if group is fully loaded
+if (game.isAssetGroupLoaded('level1')) {
+  const music = game.getAsset('level1Music');
+}
+```
+
+#### Asset Events
+
+React to asset loading with built-in events:
+
+```typescript
+game.addSystem('loadingUI')
+  .setEventHandlers({
+    assetLoaded: {
+      handler: (data) => console.log(`Loaded: ${data.key}`)
+    },
+    assetFailed: {
+      handler: (data) => console.error(`Failed: ${data.key}`, data.error)
+    },
+    assetGroupProgress: {
+      handler: (data) => {
+        console.log(`${data.group}: ${data.loaded}/${data.total}`);
+      }
+    },
+    assetGroupLoaded: {
+      handler: (data) => console.log(`Group ready: ${data.group}`)
+    }
+  })
+  .build();
+```
+
+#### Systems with Asset Requirements
+
+Systems can declare required assets and will only run when those assets are loaded:
+
+```typescript
+game.addSystem('gameplay')
+  .requiresAssets(['playerTexture', 'enemyTexture'])
+  .setProcess((queries, dt, ecs) => {
+    // This only runs when both assets are loaded
+    const player = ecs.getAsset('playerTexture');
+  })
+  .build();
+```
+
+### Screen Management
+
+Manage game states/screens with transitions and overlay support:
+
+```typescript
+import type { ScreenDefinition } from 'ecspresso';
+
+// Define screen types with config and state
+type Screens = {
+  menu: ScreenDefinition<
+    Record<string, never>,           // Config (passed when entering)
+    { selectedOption: number }       // State (mutable during screen)
+  >;
+  gameplay: ScreenDefinition<
+    { difficulty: string; level: number },  // Config
+    { score: number; isPaused: boolean }    // State
+  >;
+  pause: ScreenDefinition<
+    Record<string, never>,
+    Record<string, never>
+  >;
+};
+
+// Create world with screens
+const game = ECSpresso.create<Components, Events, Resources, {}, Screens>()
+  .withScreens(screens => screens
+    .add('menu', {
+      initialState: () => ({ selectedOption: 0 }),
+      onEnter: () => console.log('Entered menu'),
+      onExit: () => console.log('Left menu'),
+    })
+    .add('gameplay', {
+      initialState: () => ({ score: 0, isPaused: false }),
+      onEnter: (config) => console.log(`Starting level ${config.level}`),
+      onExit: () => console.log('Gameplay ended'),
+      // Require assets before screen can be entered
+      requiredAssetGroups: ['level1'],
+    })
+    .add('pause', {
+      initialState: () => ({}),
+      onEnter: () => console.log('Paused'),
+      onExit: () => console.log('Resumed'),
+    })
+  )
+  .build();
+
+await game.initialize();
+
+// Set initial screen
+await game.setScreen('menu', {});
+
+// Transition to gameplay (clears screen stack)
+await game.setScreen('gameplay', { difficulty: 'hard', level: 1 });
+
+// Push overlay screen (adds to stack, previous screen stays active)
+await game.pushScreen('pause', {});
+
+// Pop overlay (returns to previous screen)
+await game.popScreen();
+
+// Access current screen info
+const current = game.getCurrentScreen();        // 'gameplay'
+const config = game.getScreenConfig();          // { difficulty: 'hard', level: 1 }
+const state = game.getScreenState();            // { score: 0, isPaused: false }
+
+// Update screen state
+game.updateScreenState({ score: 100 });
+```
+
+#### Screen-Scoped Systems
+
+Systems can be restricted to run only in specific screens:
+
+```typescript
+// Only runs when 'menu' is the current screen
+game.addSystem('menuUI')
+  .inScreens(['menu'])
+  .setProcess((queries, dt, ecs) => {
+    const state = ecs.getScreenState();
+    renderMenu(state.selectedOption);
+  })
+  .build();
+
+// Only runs in 'gameplay' screen
+game.addSystem('scoring')
+  .inScreens(['gameplay'])
+  .setProcess((queries, dt, ecs) => {
+    const state = ecs.getScreenState();
+    ecs.updateScreenState({ score: state.score + 1 });
+  })
+  .build();
+
+// Runs in all screens EXCEPT 'pause'
+game.addSystem('animations')
+  .excludeScreens(['pause'])
+  .setProcess(() => {
+    // Animations continue except when paused
+  })
+  .build();
+```
+
+#### Screen Resource
+
+Access screen state through the `$screen` resource:
+
+```typescript
+game.addSystem('ui')
+  .setProcess((queries, dt, ecs) => {
+    const screen = ecs.getResource('$screen');
+
+    console.log(screen.current);     // Current screen name
+    console.log(screen.config);      // Current screen config
+    console.log(screen.state);       // Current screen state (mutable)
+    console.log(screen.isOverlay);   // true if screen was pushed
+    console.log(screen.stackDepth);  // Number of screens in stack
+
+    // Check screen status
+    if (screen.isCurrent('gameplay')) {
+      // ...
+    }
+    if (screen.isActive('menu')) {
+      // true if menu is current OR in the stack
+    }
+  })
+  .build();
+```
+
 ## Type Safety
 
 ECSpresso provides comprehensive TypeScript support:

package/dist/asset-manager.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Asset management for ECSpresso ECS framework
+ */
+import type EventBus from './event-bus';
+import type { AssetStatus, AssetDefinition, AssetHandle, AssetsResource, AssetEvents, AssetConfigurator } from './asset-types';
+/**
+ * Manages asset loading and access for ECSpresso
+ */
+export default class AssetManager<AssetTypes extends Record<string, unknown> = Record<string, never>> {
+    private readonly assets;
+    private readonly groups;
+    private eventBus;
+    /**
+     * Set the event bus for asset events
+     * @internal
+     */
+    setEventBus(eventBus: EventBus<AssetEvents>): void;
+    /**
+     * Register an asset definition
+     */
+    register<K extends string, T>(key: K, definition: AssetDefinition<T>): void;
+    /**
+     * Load all assets marked as eager
+     */
+    loadEagerAssets(): Promise<void>;
+    /**
+     * Load a single asset by key
+     */
+    loadAsset<K extends keyof AssetTypes>(key: K): Promise<AssetTypes[K]>;
+    /**
+     * Load all assets in a group
+     */
+    loadAssetGroup(groupName: string): Promise<void>;
+    /**
+     * Get a loaded asset. Throws if not loaded.
+     */
+    get<K extends keyof AssetTypes>(key: K): AssetTypes[K];
+    /**
+     * Get a loaded asset or undefined
+     */
+    getOrUndefined<K extends keyof AssetTypes>(key: K): AssetTypes[K] | undefined;
+    /**
+     * Get a handle to an asset with status information
+     */
+    getHandle<K extends keyof AssetTypes>(key: K): AssetHandle<AssetTypes[K]>;
+    /**
+     * Get the status of an asset
+     */
+    getStatus<K extends keyof AssetTypes>(key: K): AssetStatus;
+    /**
+     * Check if an asset is loaded
+     */
+    isLoaded<K extends keyof AssetTypes>(key: K): boolean;
+    /**
+     * Check if all assets in a group are loaded
+     */
+    isGroupLoaded(groupName: string): boolean;
+    /**
+     * Get the loading progress of a group (0-1)
+     */
+    getGroupProgress(groupName: string): number;
+    /**
+     * Get detailed group progress
+     */
+    getGroupProgressDetails(groupName: string): {
+        loaded: number;
+        total: number;
+        progress: number;
+    };
+    /**
+     * Check group progress and emit events
+     */
+    private checkGroupProgress;
+    /**
+     * Create the $assets resource object
+     */
+    createResource(): AssetsResource<AssetTypes>;
+    /**
+     * Get all registered asset keys
+     */
+    getKeys(): Array<keyof AssetTypes>;
+    /**
+     * Get all group names
+     */
+    getGroupNames(): string[];
+    /**
+     * Get all asset keys in a group
+     */
+    getGroupKeys(groupName: string): Array<keyof AssetTypes>;
+}
+/**
+ * Implementation of AssetConfigurator for builder pattern
+ */
+export declare class AssetConfiguratorImpl<A extends Record<string, unknown>> implements AssetConfigurator<A> {
+    private readonly manager;
+    constructor(manager: AssetManager<A>);
+    add<K extends string, T>(key: K, loader: () => Promise<T>): AssetConfigurator<A & Record<K, T>>;
+    addWithConfig<K extends string, T>(key: K, definition: AssetDefinition<T>): AssetConfigurator<A & Record<K, T>>;
+    addGroup<G extends string, T extends Record<string, () => Promise<unknown>>>(groupName: G, assets: T): AssetConfigurator<A & {
+        [K in keyof T]: Awaited<ReturnType<T[K]>>;
+    }>;
+    /**
+     * Get the underlying manager
+     * @internal
+     */
+    getManager(): AssetManager<A>;
+}
+/**
+ * Create a new AssetConfigurator for builder pattern usage
+ */
+export declare function createAssetConfigurator<A extends Record<string, unknown> = Record<string, never>>(manager?: AssetManager<A>): AssetConfiguratorImpl<A>;

package/dist/asset-types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Asset management types for ECSpresso ECS framework
+ */
+/**
+ * Status of an asset in the loading lifecycle
+ */
+export type AssetStatus = 'pending' | 'loading' | 'loaded' | 'failed';
+/**
+ * Definition for an asset including its loader and configuration
+ */
+export interface AssetDefinition<T> {
+    readonly loader: () => Promise<T>;
+    readonly eager?: boolean;
+    readonly group?: string;
+}
+/**
+ * Handle to an asset that provides status information and access methods
+ */
+export interface AssetHandle<T> {
+    readonly status: AssetStatus;
+    readonly isLoaded: boolean;
+    /**
+     * Get the asset value. Throws if asset is not loaded.
+     */
+    get(): T;
+    /**
+     * Get the asset value if loaded, undefined otherwise.
+     */
+    getOrUndefined(): T | undefined;
+}
+/**
+ * Resource interface for accessing assets in systems
+ * Exposed as $assets resource
+ */
+export interface AssetsResource<A extends Record<string, unknown>> {
+    /**
+     * Get the loading status of an asset
+     */
+    getStatus<K extends keyof A>(key: K): AssetStatus;
+    /**
+     * Check if an asset is loaded
+     */
+    isLoaded<K extends keyof A>(key: K): boolean;
+    /**
+     * Check if all assets in a group are loaded
+     */
+    isGroupLoaded(groupName: string): boolean;
+    /**
+     * Get the loading progress of a group (0-1)
+     */
+    getGroupProgress(groupName: string): number;
+    /**
+     * Get a loaded asset. Throws if not loaded.
+     */
+    get<K extends keyof A>(key: K): A[K];
+    /**
+     * Get a loaded asset or undefined if not loaded
+     */
+    getOrUndefined<K extends keyof A>(key: K): A[K] | undefined;
+    /**
+     * Get a handle to an asset with status information
+     */
+    getHandle<K extends keyof A>(key: K): AssetHandle<A[K]>;
+}
+/**
+ * Events emitted by the asset system
+ */
+export interface AssetEvents {
+    assetLoaded: {
+        key: string;
+    };
+    assetFailed: {
+        key: string;
+        error: Error;
+    };
+    assetGroupLoaded: {
+        group: string;
+    };
+    assetGroupProgress: {
+        group: string;
+        progress: number;
+        loaded: number;
+        total: number;
+    };
+}
+/**
+ * Configuration for asset definitions during builder setup
+ */
+export interface AssetConfigurator<A extends Record<string, unknown>> {
+    /**
+     * Add a single eager asset
+     */
+    add<K extends string, T>(key: K, loader: () => Promise<T>): AssetConfigurator<A & Record<K, T>>;
+    /**
+     * Add a single asset with full configuration
+     */
+    addWithConfig<K extends string, T>(key: K, definition: AssetDefinition<T>): AssetConfigurator<A & Record<K, T>>;
+    /**
+     * Add a group of assets that can be loaded together
+     */
+    addGroup<G extends string, T extends Record<string, () => Promise<unknown>>>(groupName: G, assets: T): AssetConfigurator<A & {
+        [K in keyof T]: Awaited<ReturnType<T[K]>>;
+    }>;
+}