ecspresso 0.10.2 → 0.11.0

package/dist/system-builder.d.ts

@@ -1,10 +1,10 @@
 import Bundle from "./bundle";
 import ECSpresso from "./ecspresso";
-import type { FilteredEntity, System, SystemPhase } from "./types";
+import type { FilteredEntity, QueryDefinition, System, SystemPhase } from "./types";
 /**
  * Builder class for creating type-safe ECS Systems with proper query inference
  */
-export declare class SystemBuilder<ComponentTypes extends Record<string, any> = Record<string, any>, EventTypes extends Record<string, any> = Record<string, any>, ResourceTypes extends Record<string, any> = Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>> = {}> {
+export declare class SystemBuilder<ComponentTypes extends Record<string, any> = Record<string, any>, EventTypes extends Record<string, any> = Record<string, any>, ResourceTypes extends Record<string, any> = Record<string, any>, AssetTypes extends Record<string, unknown> = Record<string, unknown>, ScreenStates extends Record<string, any> = Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>> = {}, Label extends string = string, SysGroups extends string = never, BundleLabels extends string = never, BundleGroups extends string = never, BundleAssetGroupNames extends string = never, BundleReactiveQueryNames extends string = never> {
     private _label;
     private _ecspresso;
     private _bundle;
@@ -20,26 +20,22 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
     private _inScreens?;
     private _excludeScreens?;
     private _requiredAssets?;
-    constructor(_label: string, _ecspresso?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes> | null, _bundle?: Bundle<ComponentTypes, EventTypes, ResourceTypes> | null);
+    private _runWhenEmpty;
+    constructor(_label: string, _ecspresso?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates> | null, _bundle?: Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, BundleLabels, BundleGroups, BundleAssetGroupNames, BundleReactiveQueryNames> | null);
     get label(): string;
     /**
      * Returns the associated bundle if one was provided in the constructor
      */
-    get bundle(): Bundle<ComponentTypes, EventTypes, ResourceTypes, {}, {}> | null;
+    get bundle(): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, BundleLabels, BundleGroups, BundleAssetGroupNames, BundleReactiveQueryNames> | null;
     /**
      * Returns the associated ECSpresso instance if one was provided in the constructor
      */
-    get ecspresso(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, {}, {}> | null;
+    get ecspresso(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, string, string, string, string> | null;
     /**
      * Auto-register this system with its ECSpresso instance if not already registered
      * @private
      */
     private _autoRegister;
-    /**
-     * Create the system object without registering it
-     * @private
-     */
-    private _buildSystemObject;
     /**
      * Create a system object with all configured properties
      * @private
@@ -67,7 +63,7 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
      * @param groupName The name of the group to add the system to
      * @returns This SystemBuilder instance for method chaining
      */
-    inGroup(groupName: string): this;
+    inGroup<G extends string>(groupName: G): this extends SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, Label, SysGroups> ? SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, Label, SysGroups | G> : this extends SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, BundleLabels, BundleGroups, Label, SysGroups, BundleAssetGroupNames, BundleReactiveQueryNames> ? SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, BundleLabels, BundleGroups, Label, SysGroups | G, BundleAssetGroupNames, BundleReactiveQueryNames> : SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, Label, SysGroups | G, BundleLabels, BundleGroups, BundleAssetGroupNames, BundleReactiveQueryNames>;
     /**
      * Restrict this system to only run in specified screens.
      * System will be skipped during update() when the current screen
@@ -75,7 +71,7 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
      * @param screens Array of screen names where this system should run
      * @returns This SystemBuilder instance for method chaining
      */
-    inScreens(screens: ReadonlyArray<string>): this;
+    inScreens(screens: ReadonlyArray<keyof ScreenStates & string>): this;
     /**
      * Exclude this system from running in specified screens.
      * System will be skipped during update() when the current screen
@@ -83,7 +79,7 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
      * @param screens Array of screen names where this system should NOT run
      * @returns This SystemBuilder instance for method chaining
      */
-    excludeScreens(screens: ReadonlyArray<string>): this;
+    excludeScreens(screens: ReadonlyArray<keyof ScreenStates & string>): this;
     /**
      * Require specific assets to be loaded for this system to run.
      * System will be skipped during update() if any required asset
@@ -91,7 +87,12 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
      * @param assets Array of asset keys that must be loaded
      * @returns This SystemBuilder instance for method chaining
      */
-    requiresAssets(assets: ReadonlyArray<string>): this;
+    requiresAssets(assets: ReadonlyArray<keyof AssetTypes & string>): this;
+    /**
+     * Allow this system to run even when all queries return zero entities.
+     * By default, systems with queries are skipped when no entities match.
+     */
+    runWhenEmpty(): this;
     /**
      * Add a query definition to the system
      */
@@ -101,40 +102,40 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
         changed?: ReadonlyArray<WithComponents>;
         optional?: ReadonlyArray<OptionalComponents>;
         parentHas?: ReadonlyArray<keyof ComponentTypes>;
-    }): this extends SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, Queries> ? SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, NewQueries> : this extends SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, Queries> ? SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, NewQueries> : SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, NewQueries>;
+    }): this extends SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, Label, SysGroups> ? SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, NewQueries, Label, SysGroups> : this extends SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, BundleLabels, BundleGroups, Label, SysGroups, BundleAssetGroupNames, BundleReactiveQueryNames> ? SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, NewQueries, BundleLabels, BundleGroups, Label, SysGroups, BundleAssetGroupNames, BundleReactiveQueryNames> : SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, NewQueries, Label, SysGroups, BundleLabels, BundleGroups, BundleAssetGroupNames, BundleReactiveQueryNames>;
     /**
      * Set the system's process function that runs each update
      * @param process Function to process entities matching the system's queries each update
      * @returns This SystemBuilder instance for method chaining
      */
-    setProcess(process: ProcessFunction<ComponentTypes, EventTypes, ResourceTypes, Queries>): this;
+    setProcess(process: ProcessFunction<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries>): this;
     /**
      * Register this system with its ECSpresso instance and return the ECSpresso for chaining
      * This enables seamless method chaining: .registerAndContinue().addSystem(...)
      * @returns ECSpresso instance if attached to one, otherwise throws an error
      */
-    registerAndContinue(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes>;
+    registerAndContinue(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
     /**
      * Complete this system and return the parent container for seamless chaining
      * - For ECSpresso-attached builders: registers the system and returns ECSpresso
      * - For Bundle-attached builders: returns the Bundle
      * This method is typed via the specialized interfaces (SystemBuilderWithEcspresso, SystemBuilderWithBundle)
      */
-    and(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes> | Bundle<ComponentTypes, EventTypes, ResourceTypes>;
+    and(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates> | Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, BundleLabels | Label, BundleGroups | SysGroups, BundleAssetGroupNames, BundleReactiveQueryNames>;
     /**
      * Set the onDetach lifecycle hook
      * Called when the system is removed from the ECS
      * @param onDetach Function to run when this system is detached from the ECS
      * @returns This SystemBuilder instance for method chaining
      */
-    setOnDetach(onDetach: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes>): this;
+    setOnDetach(onDetach: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): this;
     /**
      * Set the onInitialize lifecycle hook
      * Called when the system is initialized via ECSpresso.initialize() method
      * @param onInitialize Function to run when this system is initialized
      * @returns This SystemBuilder instance for method chaining
      */
-    setOnInitialize(onInitialize: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes>): this;
+    setOnInitialize(onInitialize: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): this;
     /**
      * Set event handlers for the system
      * These handlers will be automatically subscribed when the system is attached
@@ -143,29 +144,22 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
      */
     setEventHandlers(handlers: {
         [EventName in keyof EventTypes]?: {
-            handler(data: EventTypes[EventName], ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): void;
+            handler(data: EventTypes[EventName], ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
         };
     }): this;
     /**
      * Build the final system object
      */
-    build(ecspresso?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): this;
+    build(ecspresso?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): this;
 }
 /**
  * Helper function to register a system with an ECSpresso instance
  * This handles attaching the system and setting up event handlers
  * @internal Used by SystemBuilder and Bundle
  */
-export declare function registerSystemWithEcspresso<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>>(system: System<ComponentTypes, any, any, EventTypes, ResourceTypes>, ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): void;
-type QueryDefinition<ComponentTypes, WithComponents extends keyof ComponentTypes = any, WithoutComponents extends keyof ComponentTypes = any, OptionalComponents extends keyof ComponentTypes = any> = {
-    with: ReadonlyArray<WithComponents>;
-    without?: ReadonlyArray<WithoutComponents>;
-    changed?: ReadonlyArray<WithComponents>;
-    optional?: ReadonlyArray<OptionalComponents>;
-    parentHas?: ReadonlyArray<keyof ComponentTypes>;
-};
-type QueryResults<ComponentTypes, Queries extends Record<string, QueryDefinition<ComponentTypes>>> = {
-    [QueryName in keyof Queries]: QueryName extends string ? FilteredEntity<ComponentTypes, Queries[QueryName] extends QueryDefinition<ComponentTypes, infer W, any, any> ? W : never, Queries[QueryName] extends QueryDefinition<ComponentTypes, any, infer WO, any> ? WO : never, Queries[QueryName] extends QueryDefinition<ComponentTypes, any, any, infer O> ? O : never>[] : never;
+export declare function registerSystemWithEcspresso<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, AssetTypes extends Record<string, unknown>, ScreenStates extends Record<string, any>>(system: System<ComponentTypes, any, any, EventTypes, ResourceTypes, AssetTypes, ScreenStates>, ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
+type QueryResults<ComponentTypes extends Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>>> = {
+    [QueryName in keyof Queries]: QueryName extends string ? FilteredEntity<ComponentTypes, Queries[QueryName] extends QueryDefinition<ComponentTypes, infer W> ? W : never, Queries[QueryName] extends QueryDefinition<ComponentTypes, any, infer WO> ? WO : never, Queries[QueryName] extends QueryDefinition<ComponentTypes, any, any, infer O> ? O : never>[] : never;
 };
 /**
  * Function signature for system process methods
@@ -173,42 +167,42 @@ type QueryResults<ComponentTypes, Queries extends Record<string, QueryDefinition
  * @param deltaTime Time elapsed since last update in seconds
  * @param ecs The ECSpresso instance providing access to all ECS functionality
  */
-type ProcessFunction<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>>> = (queries: QueryResults<ComponentTypes, Queries>, deltaTime: number, ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => void;
+type ProcessFunction<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, AssetTypes extends Record<string, unknown>, ScreenStates extends Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>>> = (queries: QueryResults<ComponentTypes, Queries>, deltaTime: number, ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>) => void;
 /**
  * Type for system initialization functions
  * These can be asynchronous
  */
-type LifecycleFunction<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>> = (ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => void | Promise<void>;
+type LifecycleFunction<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, AssetTypes extends Record<string, unknown>, ScreenStates extends Record<string, any>> = (ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>) => void | Promise<void>;
 /**
  * Create a SystemBuilder attached to an ECSpresso instance
  * Helper function used by ECSpresso.addSystem
  */
-export declare function createEcspressoSystemBuilder<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>>(label: string, ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes>;
+export declare function createEcspressoSystemBuilder<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, AssetTypes extends Record<string, unknown>, ScreenStates extends Record<string, any>>(label: string, ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
 /**
  * Create a SystemBuilder attached to a Bundle
  * Helper function used by Bundle.addSystem
  */
-export declare function createBundleSystemBuilder<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>>(label: string, bundle: Bundle<ComponentTypes, EventTypes, ResourceTypes>): SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes>;
+export declare function createBundleSystemBuilder<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, AssetTypes extends Record<string, unknown>, ScreenStates extends Record<string, any>, BundleLabels extends string = never, BundleGroups extends string = never, Label extends string = string, BundleAssetGroupNames extends string = never, BundleReactiveQueryNames extends string = never>(label: Label, bundle: Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, BundleLabels, BundleGroups, BundleAssetGroupNames, BundleReactiveQueryNames>): SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, {}, BundleLabels, BundleGroups, Label, never, BundleAssetGroupNames, BundleReactiveQueryNames>;
 /**
  * SystemBuilder with a guaranteed non-null reference to an ECSpresso instance
  */
-export interface SystemBuilderWithEcspresso<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>> = {}> extends SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, Queries> {
-    readonly ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>;
+export interface SystemBuilderWithEcspresso<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, AssetTypes extends Record<string, unknown>, ScreenStates extends Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>> = {}, Label extends string = string, SysGroups extends string = never> extends SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, Label, SysGroups> {
+    readonly ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
     /**
      * Complete this system and return ECSpresso for seamless chaining
      * Automatically registers the system when called
      */
-    and(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes>;
+    and(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
 }
 /**
  * SystemBuilder with a guaranteed non-null reference to a Bundle
  */
-export interface SystemBuilderWithBundle<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>> = {}> extends SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, Queries> {
-    readonly bundle: Bundle<ComponentTypes, EventTypes, ResourceTypes>;
+export interface SystemBuilderWithBundle<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>, AssetTypes extends Record<string, unknown>, ScreenStates extends Record<string, any>, Queries extends Record<string, QueryDefinition<ComponentTypes>> = {}, BundleLabels extends string = never, BundleGroups extends string = never, Label extends string = string, SysGroups extends string = never, BundleAssetGroupNames extends string = never, BundleReactiveQueryNames extends string = never> extends SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Queries, Label, SysGroups, BundleLabels, BundleGroups, BundleAssetGroupNames, BundleReactiveQueryNames> {
+    readonly bundle: Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, BundleLabels, BundleGroups, BundleAssetGroupNames, BundleReactiveQueryNames>;
     /**
      * Complete this system and return the Bundle for chaining
      * Enables fluent API: bundle.addSystem(...).and().addSystem(...)
      */
-    and(): Bundle<ComponentTypes, EventTypes, ResourceTypes>;
+    and(): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, BundleLabels | Label, BundleGroups | SysGroups, BundleAssetGroupNames, BundleReactiveQueryNames>;
 }
 export {};

package/dist/type-utils.d.ts

@@ -29,7 +29,56 @@ export type Merge<T1, T2> = T1 & T2;
  * Utility type for merging an array of types
  */
 export type MergeAll<T extends any[]> = T extends [infer First, ...infer Rest] ? Rest extends [] ? First : Merge<First, MergeAll<Rest>> : {};
-export {};
 /**
- * Basic utility types that can be used independently
- */ 
+ * Extract the ComponentTypes from a Bundle instance
+ */
+export type ComponentsOf<B> = B extends import('./bundle').default<infer C extends Record<string, any>, any, any, any, any, any, any, any, any> ? C : never;
+/**
+ * Extract the EventTypes from a Bundle instance
+ */
+export type EventsOf<B> = B extends import('./bundle').default<any, infer E extends Record<string, any>, any, any, any, any, any, any, any> ? E : never;
+/**
+ * Extract the ResourceTypes from a Bundle instance
+ */
+export type ResourcesOf<B> = B extends import('./bundle').default<any, any, infer R extends Record<string, any>, any, any, any, any, any, any> ? R : never;
+/**
+ * Extract the system Labels from a Bundle instance
+ */
+export type LabelsOf<B> = B extends import('./bundle').default<any, any, any, any, any, infer L extends string, any, any, any> ? L : never;
+/**
+ * Extract the system Groups from a Bundle instance
+ */
+export type GroupsOf<B> = B extends import('./bundle').default<any, any, any, any, any, any, infer G extends string, any, any> ? G : never;
+/**
+ * Extract the AssetGroupNames from a Bundle instance
+ */
+export type AssetGroupNamesOf<B> = B extends import('./bundle').default<any, any, any, any, any, any, any, infer AG extends string, any> ? AG : never;
+/**
+ * Extract the ReactiveQueryNames from a Bundle instance
+ */
+export type ReactiveQueryNamesOf<B> = B extends import('./bundle').default<any, any, any, any, any, any, any, any, infer RQ extends string> ? RQ : never;
+/**
+ * Extract AssetTypes from a Bundle instance
+ */
+export type AssetTypesOf<B> = B extends import('./bundle').default<any, any, any, infer A extends Record<string, unknown>, any, any, any, any, any> ? A : never;
+/**
+ * Extract ScreenStates from a Bundle instance
+ */
+export type ScreenStatesOf<B> = B extends import('./bundle').default<any, any, any, any, infer S extends Record<string, import('./screen-types').ScreenDefinition<any, any>>, any, any, any, any> ? S : never;
+/**
+ * Extract ScreenStates from an ECSpresso world instance type
+ */
+export type ScreenStatesOfWorld<W> = W extends import('./ecspresso').default<any, any, any, any, infer S extends Record<string, import('./screen-types').ScreenDefinition<any, any>>, any, any, any, any> ? S : never;
+/**
+ * Extract ComponentTypes from an ECSpresso world instance type.
+ */
+export type ComponentsOfWorld<W> = W extends import('./ecspresso').default<infer C extends Record<string, any>, any, any, any, any, any, any, any, any> ? C : never;
+/**
+ * Extract EventTypes from an ECSpresso world instance type.
+ */
+export type EventsOfWorld<W> = W extends import('./ecspresso').default<any, infer E extends Record<string, any>, any, any, any, any, any, any, any> ? E : never;
+/**
+ * Extract AssetTypes from an ECSpresso world instance type.
+ */
+export type AssetsOfWorld<W> = W extends import('./ecspresso').default<any, any, any, infer A extends Record<string, unknown>, any, any, any, any, any> ? A : never;
+export {};

package/dist/types.d.ts

@@ -18,17 +18,6 @@ export interface RemoveEntityOptions {
      */
     cascade?: boolean;
 }
-/**
- * Event data emitted when an entity's parent changes
- */
-export interface HierarchyChangedEvent {
-    /** The entity whose parent changed */
-    entityId: number;
-    /** The previous parent, or null if entity had no parent */
-    oldParent: number | null;
-    /** The new parent, or null if entity was orphaned */
-    newParent: number | null;
-}
 /**
  * Options for hierarchy traversal methods
  */
@@ -47,10 +36,6 @@ export interface HierarchyEntry {
     /** Depth in the hierarchy (0 for roots) */
     depth: number;
 }
-export interface EventHandler<T> {
-    callback: (data: T) => void;
-    once: boolean;
-}
 export interface FilteredEntity<ComponentTypes, WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never> {
     id: number;
     components: Omit<Partial<ComponentTypes>, WithoutComponents | OptionalComponents> & {
@@ -159,17 +144,23 @@ export interface System<ComponentTypes extends Record<string, any> = {}, WithCom
      * Screens where this system should run. If specified, system only runs
      * when current screen is in this list.
      */
-    inScreens?: string[];
+    inScreens?: ReadonlyArray<keyof ScreenStates & string>;
     /**
      * Screens where this system should NOT run. If specified, system skips
      * when current screen is in this list.
      */
-    excludeScreens?: string[];
+    excludeScreens?: ReadonlyArray<keyof ScreenStates & string>;
     /**
      * Assets that must be loaded for this system to run.
      * System will be skipped if any required asset is not loaded.
      */
-    requiredAssets?: string[];
+    requiredAssets?: ReadonlyArray<keyof AssetTypes & string>;
+    /**
+     * When true, the system's process function runs even when all queries
+     * return zero entities. Default is false (system is skipped when all
+     * queries are empty).
+     */
+    runWhenEmpty?: boolean;
     entityQueries?: {
         [queryName: string]: QueryConfig<ComponentTypes, WithComponents, WithoutComponents>;
     };
@@ -208,4 +199,4 @@ export interface System<ComponentTypes extends Record<string, any> = {}, WithCom
         };
     };
 }
-export type { Merge, MergeAll } from './type-utils';
+export type { Merge, MergeAll, TypesAreCompatible, ComponentsOf, EventsOf, ResourcesOf, LabelsOf, GroupsOf, AssetGroupNamesOf, ReactiveQueryNamesOf, AssetTypesOf, ScreenStatesOf, ComponentsOfWorld, EventsOfWorld, AssetsOfWorld, ScreenStatesOfWorld } from './type-utils';

package/dist/utils/check-required-cycle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * BFS cycle detection for required component graphs.
+ * Shared by ECSpresso and Bundle.
+ *
+ * @param trigger     The component that triggers the requirement
+ * @param newRequired The component about to be added as required
+ * @param getRequirements Callback returning the existing requirements for a component
+ * @throws Error if adding trigger→newRequired would create a cycle
+ */
+export declare function checkRequiredCycle<K>(trigger: K, newRequired: K, getRequirements: (component: K) => Iterable<{
+    component: K;
+}> | undefined): void;

package/dist/utils/easing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Easing Functions
+ *
+ * 31 standard easing functions for animation. Pure math, no dependencies.
+ */
+export type EasingFn = (t: number) => number;
+export declare function linear(t: number): number;
+export declare function easeInQuad(t: number): number;
+export declare function easeOutQuad(t: number): number;
+export declare function easeInOutQuad(t: number): number;
+export declare function easeInCubic(t: number): number;
+export declare function easeOutCubic(t: number): number;
+export declare function easeInOutCubic(t: number): number;
+export declare function easeInQuart(t: number): number;
+export declare function easeOutQuart(t: number): number;
+export declare function easeInOutQuart(t: number): number;
+export declare function easeInQuint(t: number): number;
+export declare function easeOutQuint(t: number): number;
+export declare function easeInOutQuint(t: number): number;
+export declare function easeInSine(t: number): number;
+export declare function easeOutSine(t: number): number;
+export declare function easeInOutSine(t: number): number;
+export declare function easeInExpo(t: number): number;
+export declare function easeOutExpo(t: number): number;
+export declare function easeInOutExpo(t: number): number;
+export declare function easeInCirc(t: number): number;
+export declare function easeOutCirc(t: number): number;
+export declare function easeInOutCirc(t: number): number;
+export declare function easeInBack(t: number): number;
+export declare function easeOutBack(t: number): number;
+export declare function easeInOutBack(t: number): number;
+export declare function easeInElastic(t: number): number;
+export declare function easeOutElastic(t: number): number;
+export declare function easeInOutElastic(t: number): number;
+export declare function easeOutBounce(t: number): number;
+export declare function easeInBounce(t: number): number;
+export declare function easeInOutBounce(t: number): number;
+/** Runtime lookup of all easing functions by name */
+export declare const easings: {
+    readonly linear: typeof linear;
+    readonly easeInQuad: typeof easeInQuad;
+    readonly easeOutQuad: typeof easeOutQuad;
+    readonly easeInOutQuad: typeof easeInOutQuad;
+    readonly easeInCubic: typeof easeInCubic;
+    readonly easeOutCubic: typeof easeOutCubic;
+    readonly easeInOutCubic: typeof easeInOutCubic;
+    readonly easeInQuart: typeof easeInQuart;
+    readonly easeOutQuart: typeof easeOutQuart;
+    readonly easeInOutQuart: typeof easeInOutQuart;
+    readonly easeInQuint: typeof easeInQuint;
+    readonly easeOutQuint: typeof easeOutQuint;
+    readonly easeInOutQuint: typeof easeInOutQuint;
+    readonly easeInSine: typeof easeInSine;
+    readonly easeOutSine: typeof easeOutSine;
+    readonly easeInOutSine: typeof easeInOutSine;
+    readonly easeInExpo: typeof easeInExpo;
+    readonly easeOutExpo: typeof easeOutExpo;
+    readonly easeInOutExpo: typeof easeInOutExpo;
+    readonly easeInCirc: typeof easeInCirc;
+    readonly easeOutCirc: typeof easeOutCirc;
+    readonly easeInOutCirc: typeof easeInOutCirc;
+    readonly easeInBack: typeof easeInBack;
+    readonly easeOutBack: typeof easeOutBack;
+    readonly easeInOutBack: typeof easeInOutBack;
+    readonly easeInElastic: typeof easeInElastic;
+    readonly easeOutElastic: typeof easeOutElastic;
+    readonly easeInOutElastic: typeof easeInOutElastic;
+    readonly easeInBounce: typeof easeInBounce;
+    readonly easeOutBounce: typeof easeOutBounce;
+    readonly easeInOutBounce: typeof easeInOutBounce;
+};

package/dist/utils/math.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared 2D vector math utilities for ECSpresso bundles.
+ * All functions are pure — they return new vectors, never mutate inputs.
+ */
+/**
+ * A 2D vector with x and y components.
+ */
+export interface Vector2D {
+    x: number;
+    y: number;
+}
+/**
+ * Create a Vector2D from x and y components.
+ */
+export declare function vec2(x: number, y: number): Vector2D;
+/**
+ * Return a zero vector {x: 0, y: 0}.
+ */
+export declare function vec2Zero(): Vector2D;
+/**
+ * Add two vectors component-wise.
+ */
+export declare function vec2Add(a: Vector2D, b: Vector2D): Vector2D;
+/**
+ * Subtract b from a component-wise.
+ */
+export declare function vec2Sub(a: Vector2D, b: Vector2D): Vector2D;
+/**
+ * Scale a vector by a scalar.
+ */
+export declare function vec2Scale(v: Vector2D, scalar: number): Vector2D;
+/**
+ * Negate a vector (flip both components).
+ */
+export declare function vec2Negate(v: Vector2D): Vector2D;
+/**
+ * Compute the dot product of two vectors.
+ */
+export declare function vec2Dot(a: Vector2D, b: Vector2D): number;
+/**
+ * Compute the 2D cross product (scalar z-component of the 3D cross product).
+ */
+export declare function vec2Cross(a: Vector2D, b: Vector2D): number;
+/**
+ * Compute the squared length of a vector. Avoids sqrt when only comparing magnitudes.
+ */
+export declare function vec2LengthSq(v: Vector2D): number;
+/**
+ * Compute the length (magnitude) of a vector.
+ */
+export declare function vec2Length(v: Vector2D): number;
+/**
+ * Return a unit vector in the same direction. Returns zero vector if input is zero-length.
+ */
+export declare function vec2Normalize(v: Vector2D): Vector2D;
+/**
+ * Compute the squared distance between two points. Avoids sqrt when only comparing.
+ */
+export declare function vec2DistanceSq(a: Vector2D, b: Vector2D): number;
+/**
+ * Compute the distance between two points.
+ */
+export declare function vec2Distance(a: Vector2D, b: Vector2D): number;
+/**
+ * Check if two vectors are approximately equal within an epsilon tolerance.
+ */
+export declare function vec2Equals(a: Vector2D, b: Vector2D, epsilon?: number): boolean;

package/dist/utils/narrowphase.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared Narrowphase Module
+ *
+ * Provides contact-computing narrowphase tests and a generic collision
+ * iteration pipeline used by both the collision bundle (event-only) and
+ * the physics2D bundle (impulse response).
+ */
+import type { SpatialIndex } from './spatial-hash';
+/** Contact result from a narrowphase test. Normal points from A toward B. */
+export interface Contact {
+    normalX: number;
+    normalY: number;
+    /** Penetration depth (positive = overlapping) */
+    depth: number;
+}
+/** Minimum collider data shared by collision and physics bundles. */
+export interface BaseColliderInfo<L extends string = string> {
+    entityId: number;
+    x: number;
+    y: number;
+    layer: L;
+    collidesWith: readonly L[];
+    aabb?: {
+        halfWidth: number;
+        halfHeight: number;
+    };
+    circle?: {
+        radius: number;
+    };
+}
+/**
+ * Build a BaseColliderInfo from raw entity/collider component data.
+ * Returns null if the entity has neither an AABB nor circle collider.
+ * Shared by collision bundle (event-only) and physics2D bundle (impulse response).
+ */
+export declare function buildBaseColliderInfo<L extends string>(entityId: number, x: number, y: number, layer: L, collidesWith: readonly L[], aabb: {
+    width: number;
+    height: number;
+    offsetX?: number;
+    offsetY?: number;
+} | undefined, circle: {
+    radius: number;
+    offsetX?: number;
+    offsetY?: number;
+} | undefined): BaseColliderInfo<L> | null;
+/**
+ * Retrieve the optional spatialIndex resource, returning null when absent.
+ * Centralizes the cross-bundle typed lookup so individual bundles don't each
+ * need to import SpatialIndex or repeat the tryGetResource pattern.
+ */
+export declare function tryGetSpatialIndex(tryGetResource: <T>(key: string) => T | undefined): SpatialIndex | null;
+export declare function computeAABBvsAABB(ax: number, ay: number, ahw: number, ahh: number, bx: number, by: number, bhw: number, bhh: number): Contact | null;
+export declare function computeCircleVsCircle(ax: number, ay: number, ar: number, bx: number, by: number, br: number): Contact | null;
+export declare function computeAABBvsCircle(aabbX: number, aabbY: number, ahw: number, ahh: number, circleX: number, circleY: number, radius: number): Contact | null;
+export declare function computeContact(a: BaseColliderInfo, b: BaseColliderInfo): Contact | null;
+/**
+ * Generic collision detection pipeline: brute-force or broadphase,
+ * with layer filtering and contact computation.
+ *
+ * Uses a context parameter forwarded to the callback to avoid
+ * per-frame closure allocation.
+ */
+export declare function detectCollisions<I extends BaseColliderInfo, C>(colliders: I[], spatialIndex: SpatialIndex | null, onContact: (a: I, b: I, contact: Contact, context: C) => void, context: C): void;

package/dist/utils/spatial-hash.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Spatial Hash Grid
+ *
+ * Uniform-grid spatial hash for broadphase collision detection and
+ * proximity queries. Pure data structure, no ECS dependencies.
+ */
+export interface SpatialEntry {
+    entityId: number;
+    x: number;
+    y: number;
+    halfW: number;
+    halfH: number;
+}
+export interface SpatialHashGrid {
+    cellSize: number;
+    invCellSize: number;
+    cells: Map<number, number[]>;
+    entries: Map<number, SpatialEntry>;
+}
+/**
+ * Hash a cell coordinate pair to a single integer key.
+ * Uses large-prime XOR to distribute values.
+ */
+export declare function hashCell(cx: number, cy: number): number;
+/**
+ * Create a new empty spatial hash grid.
+ */
+export declare function createGrid(cellSize: number): SpatialHashGrid;
+/**
+ * Clear all data from the grid without reallocating the Maps.
+ */
+export declare function clearGrid(grid: SpatialHashGrid): void;
+/**
+ * Insert an entity into all overlapping cells of the grid.
+ */
+export declare function insertEntity(grid: SpatialHashGrid, entityId: number, x: number, y: number, halfW: number, halfH: number): void;
+/**
+ * Collect entity IDs from all cells overlapping the given rectangle.
+ */
+export declare function gridQueryRect(grid: SpatialHashGrid, minX: number, minY: number, maxX: number, maxY: number, result: Set<number>): void;
+/**
+ * Collect entity IDs within a circle. Uses rect broadphase then
+ * AABB-to-point distance filter.
+ */
+export declare function gridQueryRadius(grid: SpatialHashGrid, cx: number, cy: number, radius: number, result: Set<number>): void;
+export interface SpatialIndex {
+    readonly grid: SpatialHashGrid;
+    queryRect(minX: number, minY: number, maxX: number, maxY: number): number[];
+    queryRectInto(minX: number, minY: number, maxX: number, maxY: number, result: Set<number>): void;
+    queryRadius(cx: number, cy: number, radius: number): number[];
+    queryRadiusInto(cx: number, cy: number, radius: number, result: Set<number>): void;
+    getEntry(entityId: number): SpatialEntry | undefined;
+}