ecspresso 0.4.3 → 0.6.0

package/dist/ecspresso.d.ts

@@ -1,23 +1,28 @@
 import EntityManager from "./entity-manager";
 import EventBus from "./event-bus";
-import type { System, FilteredEntity, Entity } from "./types";
+import AssetManager from "./asset-manager";
+import ScreenManager from "./screen-manager";
+import { type ReactiveQueryDefinition } from "./reactive-query-manager";
+import type { System, FilteredEntity, Entity, RemoveEntityOptions, HierarchyEntry, HierarchyIteratorOptions } from "./types";
 import type Bundle from "./bundle";
 import type { BundlesAreCompatible } from "./type-utils";
+import type { AssetHandle, AssetConfigurator } from "./asset-types";
+import type { ScreenDefinition, ScreenConfigurator } from "./screen-types";
 /**
     * Interface declaration for ECSpresso constructor to ensure type augmentation works properly.
     * This merges with the class declaration below.
 */
-export default interface ECSpresso<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}> {
+export default interface ECSpresso<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, ScreenDefinition<any, any>> = {}> {
     /**
         * Default constructor
     */
-    new (): ECSpresso<ComponentTypes, EventTypes, ResourceTypes>;
+    new (): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
 }
 /**
     * ECSpresso is the central ECS framework class that connects all features.
     * It handles creation and management of entities, components, and systems, and provides lifecycle hooks.
 */
-export default class ECSpresso<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}> {
+export default class ECSpresso<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, ScreenDefinition<any, any>> = {}> {
     /** Library version*/
     static readonly VERSION: string;
     /** Access/modify stored components and entities*/
@@ -32,10 +37,25 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     private _sortedSystems;
     /** Track installed bundles to prevent duplicates*/
     private _installedBundles;
+    /** Disabled system groups */
+    private _disabledGroups;
+    /** Asset manager for loading and accessing assets */
+    private _assetManager;
+    /** Screen manager for state/screen transitions */
+    private _screenManager;
+    /** Reactive query manager for enter/exit callbacks */
+    private _reactiveQueryManager;
+    /** Post-update hooks to be called after all systems in update() */
+    private _postUpdateHooks;
     /**
         * Creates a new ECSpresso instance.
     */
     constructor();
+    /**
+     * Sets up component lifecycle hooks for reactive query tracking
+     * @private
+     */
+    private _setupReactiveQueryHooks;
     /**
         * Creates a new ECSpresso builder for type-safe bundle installation.
         * This is the preferred way to create an ECSpresso instance with bundles.
@@ -50,7 +70,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      *	 .build();
         * ```
     */
-    static create<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}>(): ECSpressoBuilder<C, E, R>;
+    static create<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}>(): ECSpressoBuilder<C, E, R, A, S>;
     /**
         * Adds a system directly to this ECSpresso instance
         * @param label Unique name to identify the system
@@ -66,7 +86,9 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * Initialize all resources and systems
      * This method:
      * 1. Initializes all resources that were added as factory functions
-     * 2. Calls the onInitialize lifecycle hook on all systems
+     * 2. Sets up asset manager and loads eager assets
+     * 3. Sets up screen manager
+     * 4. Calls the onInitialize lifecycle hook on all systems
      *
      * This is useful for game startup to ensure all resources are ready
      * and systems are properly initialized before the game loop begins.
@@ -95,6 +117,28 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         * @returns true if the system was found and updated, false otherwise
     */
     updateSystemPriority(label: string, priority: number): boolean;
+    /**
+     * Disable a system group. Systems in this group will be skipped during update().
+     * @param groupName The name of the group to disable
+     */
+    disableSystemGroup(groupName: string): void;
+    /**
+     * Enable a system group. Systems in this group will run during update().
+     * @param groupName The name of the group to enable
+     */
+    enableSystemGroup(groupName: string): void;
+    /**
+     * Check if a system group is enabled.
+     * @param groupName The name of the group to check
+     * @returns true if the group is enabled (or doesn't exist), false if disabled
+     */
+    isSystemGroupEnabled(groupName: string): boolean;
+    /**
+     * Get all system labels that belong to a specific group.
+     * @param groupName The name of the group
+     * @returns Array of system labels in the group
+     */
+    getSystemsInGroup(groupName: string): string[];
     /**
         * Remove a system by its label
         * Calls the system's onDetach method with this ECSpresso instance if defined
@@ -106,7 +150,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         * Internal method to register a system with this ECSpresso instance
         * @internal Used by SystemBuilder - replaces direct private property access
     */
-    _registerSystem(system: System<ComponentTypes, any, any, EventTypes, ResourceTypes>): void;
+    _registerSystem(system: System<ComponentTypes, any, any, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
     /**
         * Check if a resource exists
     */
@@ -118,13 +162,29 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     /**
         * Add a resource to the ECS instance
     */
-    addResource<K extends keyof ResourceTypes>(key: K, resource: ResourceTypes[K] | ((ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>)): this;
+    addResource<K extends keyof ResourceTypes>(key: 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]>;
+        onDispose?: (resource: ResourceTypes[K], ecs?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => void | Promise<void>;
+    }): this;
     /**
-        * Remove a resource from the ECS instance
+        * Remove a resource from the ECS instance (without calling onDispose)
         * @param key The resource key to remove
         * @returns True if the resource was removed, false if it didn't exist
     */
     removeResource<K extends keyof ResourceTypes>(key: K): boolean;
+    /**
+     * Dispose a single resource, calling its onDispose callback if defined
+     * @param key The resource key to dispose
+     * @returns True if the resource existed and was disposed, false if it didn't exist
+     */
+    disposeResource<K extends keyof ResourceTypes>(key: K): Promise<boolean>;
+    /**
+     * Dispose all initialized resources in reverse dependency order.
+     * Resources that depend on others are disposed first.
+     * Calls each resource's onDispose callback if defined.
+     */
+    disposeResources(): Promise<void>;
     /**
         * Update an existing resource using an updater function
         * @param key The resource key to update
@@ -155,44 +215,371 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         */
     spawn<T extends {
         [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): Entity<ComponentTypes>;
+    }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes, never>;
     /**
         * Get all entities with specific components
     */
     getEntitiesWithQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>;
+    /**
+     * Remove an entity (and optionally its descendants)
+     * @param entityOrId Entity or entity ID to remove
+     * @param options Options for removal (cascade: true by default)
+     * @returns true if entity was removed
+     */
+    removeEntity(entityOrId: number | Entity<ComponentTypes>, options?: RemoveEntityOptions): boolean;
+    /**
+     * Create an entity as a child of another entity with initial components
+     * @param parentId The parent entity ID
+     * @param components Initial components to add
+     * @returns The created child entity
+     */
+    spawnChild<T extends {
+        [K in keyof ComponentTypes]?: ComponentTypes[K];
+    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes, never>;
+    /**
+     * Set the parent of an entity
+     * @param childId The entity to set as a child
+     * @param parentId The entity to set as the parent
+     */
+    setParent(childId: number, parentId: number): this;
+    /**
+     * Remove the parent relationship for an entity (orphan it)
+     * @param childId The entity to orphan
+     * @returns true if a parent was removed, false if entity had no parent
+     */
+    removeParent(childId: number): boolean;
+    /**
+     * Get the parent of an entity
+     * @param entityId The entity to get the parent of
+     * @returns The parent entity ID, or null if no parent
+     */
+    getParent(entityId: number): number | null;
+    /**
+     * Get all children of an entity in insertion order
+     * @param parentId The parent entity
+     * @returns Readonly array of child entity IDs
+     */
+    getChildren(parentId: number): readonly number[];
+    /**
+     * Get a child at a specific index
+     * @param parentId The parent entity
+     * @param index The index of the child
+     * @returns The child entity ID, or null if index is out of bounds
+     */
+    getChildAt(parentId: number, index: number): number | null;
+    /**
+     * Get the index of a child within its parent's children list
+     * @param parentId The parent entity
+     * @param childId The child entity to find
+     * @returns The index of the child, or -1 if not found
+     */
+    getChildIndex(parentId: number, childId: number): number;
+    /**
+     * Get all ancestors of an entity in order [parent, grandparent, ...]
+     * @param entityId The entity to get ancestors of
+     * @returns Readonly array of ancestor entity IDs
+     */
+    getAncestors(entityId: number): readonly number[];
+    /**
+     * Get all descendants of an entity in depth-first order
+     * @param entityId The entity to get descendants of
+     * @returns Readonly array of descendant entity IDs
+     */
+    getDescendants(entityId: number): readonly number[];
+    /**
+     * Get the root ancestor of an entity (topmost parent), or self if no parent
+     * @param entityId The entity to get the root of
+     * @returns The root entity ID
+     */
+    getRoot(entityId: number): number;
+    /**
+     * Get siblings of an entity (other children of the same parent)
+     * @param entityId The entity to get siblings of
+     * @returns Readonly array of sibling entity IDs
+     */
+    getSiblings(entityId: number): readonly number[];
+    /**
+     * Check if an entity is a descendant of another entity
+     * @param entityId The potential descendant
+     * @param ancestorId The potential ancestor
+     * @returns true if entityId is a descendant of ancestorId
+     */
+    isDescendantOf(entityId: number, ancestorId: number): boolean;
+    /**
+     * Check if an entity is an ancestor of another entity
+     * @param entityId The potential ancestor
+     * @param descendantId The potential descendant
+     * @returns true if entityId is an ancestor of descendantId
+     */
+    isAncestorOf(entityId: number, descendantId: number): boolean;
+    /**
+     * Get all root entities (entities that have children but no parent)
+     * @returns Readonly array of root entity IDs
+     */
+    getRootEntities(): readonly number[];
+    /**
+     * Traverse the hierarchy in parent-first (breadth-first) order.
+     * Parents are guaranteed to be visited before their children.
+     * @param callback Function called for each entity with (entityId, parentId, depth)
+     * @param options Optional traversal options (roots to filter to specific subtrees)
+     */
+    forEachInHierarchy(callback: (entityId: number, parentId: number | null, depth: number) => void, options?: HierarchyIteratorOptions): void;
+    /**
+     * Generator-based hierarchy traversal in parent-first (breadth-first) order.
+     * Supports early termination via break.
+     * @param options Optional traversal options (roots to filter to specific subtrees)
+     * @yields HierarchyEntry for each entity in parent-first order
+     */
+    hierarchyIterator(options?: HierarchyIteratorOptions): Generator<HierarchyEntry, void, unknown>;
+    /**
+     * Emit a hierarchy changed event
+     * @internal
+     */
+    private _emitHierarchyChanged;
     /**
         * Get all installed bundle IDs
     */
     get installedBundles(): string[];
     get entityManager(): EntityManager<ComponentTypes>;
     get eventBus(): EventBus<EventTypes>;
+    /**
+     * Register a callback when a specific component is added to any entity
+     * @param componentName The component key
+     * @param handler Function receiving the new component value and the entity
+     * @returns Unsubscribe function to remove the callback
+     */
+    onComponentAdded<K extends keyof ComponentTypes>(componentName: K, handler: (value: ComponentTypes[K], entity: Entity<ComponentTypes>) => void): () => void;
+    /**
+     * Register a callback when a specific component is removed from any entity
+     * @param componentName The component key
+     * @param handler Function receiving the old component value and the entity
+     * @returns Unsubscribe function to remove the callback
+     */
+    onComponentRemoved<K extends keyof ComponentTypes>(componentName: K, handler: (oldValue: ComponentTypes[K], entity: Entity<ComponentTypes>) => void): () => void;
+    /**
+     * Add a reactive query that triggers callbacks when entities enter/exit the query match.
+     * @param name Unique name for the query
+     * @param definition Query definition with with/without arrays and onEnter/onExit callbacks
+     */
+    addReactiveQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(name: string, definition: ReactiveQueryDefinition<ComponentTypes, WithComponents, WithoutComponents>): void;
+    /**
+     * Remove a reactive query by name.
+     * @param name Name of the query to remove
+     * @returns true if the query existed and was removed, false otherwise
+     */
+    removeReactiveQuery(name: string): boolean;
+    /**
+     * Subscribe to an event (convenience wrapper for eventBus.subscribe)
+     * @param eventType The event type to subscribe to
+     * @param callback The callback to invoke when the event is published
+     * @returns An unsubscribe function
+     */
+    on<E extends keyof EventTypes>(eventType: E, callback: (data: EventTypes[E]) => void): () => void;
+    /**
+     * Unsubscribe from an event by callback reference (convenience wrapper for eventBus.unsubscribe)
+     * @param eventType The event type to unsubscribe from
+     * @param callback The callback to remove
+     * @returns true if the callback was found and removed, false otherwise
+     */
+    off<E extends keyof EventTypes>(eventType: E, callback: (data: EventTypes[E]) => void): boolean;
+    /**
+     * Register a hook that runs after all systems in update()
+     * @param callback The hook to call after all systems have processed
+     * @returns An unsubscribe function to remove the hook
+     */
+    onPostUpdate(callback: (ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>, deltaTime: number) => void): () => void;
+    /**
+     * Get a loaded asset by key. Throws if not loaded.
+     */
+    getAsset<K extends keyof AssetTypes>(key: K): AssetTypes[K];
+    /**
+     * Get a loaded asset or undefined if not loaded
+     */
+    getAssetOrUndefined<K extends keyof AssetTypes>(key: K): AssetTypes[K] | undefined;
+    /**
+     * Get a handle to an asset with status information
+     */
+    getAssetHandle<K extends keyof AssetTypes>(key: K): AssetHandle<AssetTypes[K]>;
+    /**
+     * Check if an asset is loaded
+     */
+    isAssetLoaded<K extends keyof AssetTypes>(key: K): boolean;
+    /**
+     * Load a single asset
+     */
+    loadAsset<K extends keyof AssetTypes>(key: K): Promise<AssetTypes[K]>;
+    /**
+     * Load all assets in a group
+     */
+    loadAssetGroup(groupName: string): Promise<void>;
+    /**
+     * Check if all assets in a group are loaded
+     */
+    isAssetGroupLoaded(groupName: string): boolean;
+    /**
+     * Get the loading progress of a group (0-1)
+     */
+    getAssetGroupProgress(groupName: string): number;
+    /**
+     * Transition to a new screen, clearing the stack
+     */
+    setScreen<K extends keyof ScreenStates>(name: K, config: ScreenStates[K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
+    /**
+     * Push a screen onto the stack (overlay)
+     */
+    pushScreen<K extends keyof ScreenStates>(name: K, config: ScreenStates[K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
+    /**
+     * Pop the current screen and return to the previous one
+     */
+    popScreen(): Promise<void>;
+    /**
+     * Get the current screen name
+     */
+    getCurrentScreen(): keyof ScreenStates | null;
+    /**
+     * Get the current screen config (immutable)
+     */
+    getScreenConfig<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    /**
+     * Get the current screen config or null
+     */
+    getScreenConfigOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never) | null;
+    /**
+     * Get the current screen state (mutable)
+     */
+    getScreenState<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never;
+    /**
+     * Get the current screen state or null
+     */
+    getScreenStateOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never) | null;
+    /**
+     * Update the current screen state
+     */
+    updateScreenState<K extends keyof ScreenStates>(update: Partial<ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never> | ((current: ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never) => Partial<ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never>)): void;
+    /**
+     * Check if a screen is the current screen
+     */
+    isCurrentScreen(screenName: keyof ScreenStates): boolean;
+    /**
+     * Check if a screen is active (current or in stack)
+     */
+    isScreenActive(screenName: keyof ScreenStates): boolean;
+    /**
+     * Get the screen stack depth
+     */
+    getScreenStackDepth(): number;
+    /**
+     * Internal method to set the asset manager
+     * @internal Used by ECSpressoBuilder
+     */
+    _setAssetManager(manager: AssetManager<AssetTypes>): void;
+    /**
+     * Internal method to set the screen manager
+     * @internal Used by ECSpressoBuilder
+     */
+    _setScreenManager(manager: ScreenManager<ScreenStates>): void;
     /**
         * Internal method to install a bundle into this ECSpresso instance.
         * Called by the ECSpressoBuilder during the build process.
         * The type safety is guaranteed by the builder's type system.
     */
-    _installBundle<C extends Record<string, any>, E extends Record<string, any>, R extends Record<string, any>>(bundle: Bundle<C, E, R>): this;
+    _installBundle<C extends Record<string, any>, E extends Record<string, any>, R extends Record<string, any>, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}>(bundle: Bundle<C, E, R, A, S>): this;
 }
+/**
+ * Resource factory with optional dependencies and disposal callback
+ */
+type ResourceFactoryWithDeps<T> = {
+    dependsOn?: readonly string[];
+    factory: (context?: any) => T | Promise<T>;
+    onDispose?: (resource: T, context?: any) => void | Promise<void>;
+};
 /**
     * Builder class for ECSpresso that provides fluent type-safe bundle installation.
     * Handles type checking during build process to ensure type safety.
 */
-export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}> {
+export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}> {
     /** The ECSpresso instance being built*/
     private ecspresso;
+    /** Asset configurator for collecting asset definitions */
+    private assetConfigurator;
+    /** Screen configurator for collecting screen definitions */
+    private screenConfigurator;
+    /** Pending resources to add during build */
+    private pendingResources;
     constructor();
     /**
         * Add the first bundle when starting with empty types.
         * This overload allows any bundle to be added to an empty ECSpresso instance.
     */
-    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>>(this: ECSpressoBuilder<{}, {}, {}>, bundle: Bundle<BC, BE, BR>): ECSpressoBuilder<BC, BE, BR>;
+    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>>(this: ECSpressoBuilder<{}, {}, {}, A, S>, bundle: Bundle<BC, BE, BR>): ECSpressoBuilder<BC, BE, BR, A, S>;
     /**
         * Add a subsequent bundle with type checking.
         * This overload enforces bundle type compatibility.
     */
-    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>>(bundle: BundlesAreCompatible<C, BC, E, BE, R, BR> extends true ? Bundle<BC, BE, BR> : never): ECSpressoBuilder<C & BC, E & BE, R & BR>;
+    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>>(bundle: BundlesAreCompatible<C, BC, E, BE, R, BR> extends true ? Bundle<BC, BE, BR> : never): ECSpressoBuilder<C & BC, E & BE, R & BR, A, S>;
+    /**
+     * Add a resource during ECSpresso construction
+     * @param key The resource key
+     * @param resource The resource value, factory function, or factory with dependencies/disposal
+     * @returns This builder with updated resource types
+     *
+     * @example
+     * ```typescript
+     * ECSpresso.create<Components, Events, Resources>()
+     *   .withResource('config', { debug: true })
+     *   .withResource('counter', () => 42)
+     *   .withResource('derived', {
+     *     dependsOn: ['base'],
+     *     factory: (ecs) => ecs.getResource('base') * 2,
+     *     onDispose: (value) => console.log('Disposed:', value)
+     *   })
+     *   .build();
+     * ```
+     */
+    withResource<K extends string, V>(key: K, resource: V | ((context?: any) => V | Promise<V>) | ResourceFactoryWithDeps<V>): ECSpressoBuilder<C, E, R & Record<K, V>, A, S>;
+    /**
+     * Configure assets for this ECSpresso instance
+     * @param configurator Function that receives an AssetConfigurator and returns it after adding assets
+     * @returns This builder with updated asset types
+     *
+     * @example
+     * ```typescript
+     * ECSpresso.create<Components, Events, Resources>()
+     *   .withAssets(assets => assets
+     *     .add('playerSprite', () => loadTexture('player.png'))
+     *     .addGroup('level1', {
+     *       background: () => loadTexture('level1-bg.png'),
+     *       music: () => loadAudio('level1.mp3'),
+     *     })
+     *   )
+     *   .build();
+     * ```
+     */
+    withAssets<NewA extends Record<string, unknown>>(configurator: (assets: AssetConfigurator<{}>) => AssetConfigurator<NewA>): ECSpressoBuilder<C, E, R, A & NewA, S>;
+    /**
+     * Configure screens for this ECSpresso instance
+     * @param configurator Function that receives a ScreenConfigurator and returns it after adding screens
+     * @returns This builder with updated screen types
+     *
+     * @example
+     * ```typescript
+     * ECSpresso.create<Components, Events, Resources>()
+     *   .withScreens(screens => screens
+     *     .add('loading', {
+     *       initialState: () => ({ progress: 0 }),
+     *     })
+     *     .add('gameplay', {
+     *       initialState: ({ level }) => ({ score: 0, level }),
+     *       requiredAssetGroups: ['level1'],
+     *     })
+     *   )
+     *   .build();
+     * ```
+     */
+    withScreens<NewS extends Record<string, ScreenDefinition<any, any>>>(configurator: (screens: ScreenConfigurator<{}>) => ScreenConfigurator<NewS>): ECSpressoBuilder<C, E, R, A, S & NewS>;
     /**
         * Complete the build process and return the built ECSpresso instance
     */
-    build(): ECSpresso<C, E, R>;
+    build(): ECSpresso<C, E, R, A, S>;
 }
+export {};

package/dist/entity-manager.d.ts

@@ -1,4 +1,4 @@
-import type { Entity, FilteredEntity } from "./types";
+import type { Entity, FilteredEntity, RemoveEntityOptions, HierarchyEntry, HierarchyIteratorOptions } from "./types";
 export default class EntityManager<ComponentTypes> {
     private nextId;
     private entities;
@@ -11,6 +11,10 @@ export default class EntityManager<ComponentTypes> {
      * Callbacks registered for component removals
      */
     private removedCallbacks;
+    /**
+     * Hierarchy manager for parent-child relationships
+     */
+    private hierarchyManager;
     createEntity(): Entity<ComponentTypes>;
     addComponent<ComponentName extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: ComponentName, data: ComponentTypes[ComponentName]): this;
     /**
@@ -24,18 +28,128 @@ export default class EntityManager<ComponentTypes> {
     removeComponent<ComponentName extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: ComponentName): this;
     getComponent<ComponentName extends keyof ComponentTypes>(entityId: number, componentName: ComponentName): ComponentTypes[ComponentName] | null;
     getEntitiesWithQuery<WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never>(required?: ReadonlyArray<WithComponents>, excluded?: ReadonlyArray<WithoutComponents>): Array<FilteredEntity<ComponentTypes, WithComponents extends never ? never : WithComponents, WithoutComponents extends never ? never : WithoutComponents>>;
-    removeEntity(entityOrId: number | Entity<ComponentTypes>): boolean;
+    removeEntity(entityOrId: number | Entity<ComponentTypes>, options?: RemoveEntityOptions): boolean;
+    /**
+     * Internal method to remove a single entity without cascade logic
+     */
+    private removeEntityInternal;
     getEntity(entityId: number): Entity<ComponentTypes> | undefined;
     /**
      * Register a callback when a specific component is added to any entity
      * @param componentName The component key
      * @param handler Function receiving the new component value and the entity
+     * @returns Unsubscribe function to remove the callback
      */
-    onComponentAdded<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (value: ComponentTypes[ComponentName], entity: Entity<ComponentTypes>) => void): this;
+    onComponentAdded<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (value: ComponentTypes[ComponentName], entity: Entity<ComponentTypes>) => void): () => void;
     /**
      * Register a callback when a specific component is removed from any entity
      * @param componentName The component key
      * @param handler Function receiving the old component value and the entity
+     * @returns Unsubscribe function to remove the callback
+     */
+    onComponentRemoved<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (oldValue: ComponentTypes[ComponentName], entity: Entity<ComponentTypes>) => void): () => void;
+    /**
+     * Create an entity as a child of another entity with initial components
+     * @param parentId The parent entity ID
+     * @param components Initial components to add
+     * @returns The created child entity
+     */
+    spawnChild<T extends {
+        [K in keyof ComponentTypes]?: ComponentTypes[K];
+    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes, never>;
+    /**
+     * Set the parent of an entity
+     * @param childId The entity to set as a child
+     * @param parentId The entity to set as the parent
+     */
+    setParent(childId: number, parentId: number): this;
+    /**
+     * Remove the parent relationship for an entity (orphan it)
+     * @param childId The entity to orphan
+     * @returns true if a parent was removed, false if entity had no parent
+     */
+    removeParent(childId: number): boolean;
+    /**
+     * Get the parent of an entity
+     * @param entityId The entity to get the parent of
+     * @returns The parent entity ID, or null if no parent
+     */
+    getParent(entityId: number): number | null;
+    /**
+     * Get all children of an entity in insertion order
+     * @param parentId The parent entity
+     * @returns Readonly array of child entity IDs
+     */
+    getChildren(parentId: number): readonly number[];
+    /**
+     * Get a child at a specific index
+     * @param parentId The parent entity
+     * @param index The index of the child
+     * @returns The child entity ID, or null if index is out of bounds
+     */
+    getChildAt(parentId: number, index: number): number | null;
+    /**
+     * Get the index of a child within its parent's children list
+     * @param parentId The parent entity
+     * @param childId The child entity to find
+     * @returns The index of the child, or -1 if not found
+     */
+    getChildIndex(parentId: number, childId: number): number;
+    /**
+     * Get all ancestors of an entity in order [parent, grandparent, ...]
+     * @param entityId The entity to get ancestors of
+     * @returns Readonly array of ancestor entity IDs
+     */
+    getAncestors(entityId: number): readonly number[];
+    /**
+     * Get all descendants of an entity in depth-first order
+     * @param entityId The entity to get descendants of
+     * @returns Readonly array of descendant entity IDs
+     */
+    getDescendants(entityId: number): readonly number[];
+    /**
+     * Get the root ancestor of an entity (topmost parent), or self if no parent
+     * @param entityId The entity to get the root of
+     * @returns The root entity ID
+     */
+    getRoot(entityId: number): number;
+    /**
+     * Get siblings of an entity (other children of the same parent)
+     * @param entityId The entity to get siblings of
+     * @returns Readonly array of sibling entity IDs
+     */
+    getSiblings(entityId: number): readonly number[];
+    /**
+     * Check if an entity is a descendant of another entity
+     * @param entityId The potential descendant
+     * @param ancestorId The potential ancestor
+     * @returns true if entityId is a descendant of ancestorId
+     */
+    isDescendantOf(entityId: number, ancestorId: number): boolean;
+    /**
+     * Check if an entity is an ancestor of another entity
+     * @param entityId The potential ancestor
+     * @param descendantId The potential descendant
+     * @returns true if entityId is an ancestor of descendantId
+     */
+    isAncestorOf(entityId: number, descendantId: number): boolean;
+    /**
+     * Get all root entities (entities that have children but no parent)
+     * @returns Readonly array of root entity IDs
+     */
+    getRootEntities(): readonly number[];
+    /**
+     * Traverse the hierarchy in parent-first (breadth-first) order.
+     * Parents are guaranteed to be visited before their children.
+     * @param callback Function called for each entity with (entityId, parentId, depth)
+     * @param options Optional traversal options (roots to filter to specific subtrees)
+     */
+    forEachInHierarchy(callback: (entityId: number, parentId: number | null, depth: number) => void, options?: HierarchyIteratorOptions): void;
+    /**
+     * Generator-based hierarchy traversal in parent-first (breadth-first) order.
+     * Supports early termination via break.
+     * @param options Optional traversal options (roots to filter to specific subtrees)
+     * @yields HierarchyEntry for each entity in parent-first order
      */
-    onComponentRemoved<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (oldValue: ComponentTypes[ComponentName], entity: Entity<ComponentTypes>) => void): this;
+    hierarchyIterator(options?: HierarchyIteratorOptions): Generator<HierarchyEntry, void, unknown>;
 }