ecspresso 0.11.0 → 0.12.0

package/dist/ecspresso.d.ts

@@ -1,30 +1,33 @@
 import EntityManager from "./entity-manager";
 import EventBus from "./event-bus";
-import { type ResourceFactoryWithDeps } from "./resource-manager";
+import { type ResourceFactoryWithDeps, type ResourceDirectValue } from "./resource-manager";
 import AssetManager from "./asset-manager";
 import ScreenManager from "./screen-manager";
 import { type ReactiveQueryDefinition } from "./reactive-query-manager";
 import CommandBuffer from "./command-buffer";
 import type { System, SystemPhase, FilteredEntity, Entity, RemoveEntityOptions, HierarchyEntry, HierarchyIteratorOptions } from "./types";
-import type Bundle from "./bundle";
-import type { AssetHandle } from "./asset-types";
+import { type Plugin } from "./plugin";
+import { SystemBuilder } from "./system-builder";
+import type { AssetDefinition, AssetHandle } from "./asset-types";
 import type { ScreenDefinition } from "./screen-types";
 import { ECSpressoBuilder } from "./ecspresso-builder";
+import type { WorldConfig, EmptyConfig } from "./type-utils";
 /**
     * 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> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, ScreenDefinition<any, any>> = {}, Labels extends string = string, Groups extends string = string, AssetGroupNames extends string = string, ReactiveQueryNames extends string = string> {
+export default interface ECSpresso<Cfg extends WorldConfig = EmptyConfig, Labels extends string = string, Groups extends string = string, AssetGroupNames extends string = string, ReactiveQueryNames extends string = string> {
     /**
         * Default constructor
     */
-    new (): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
+    new (): ECSpresso<Cfg, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
 }
 /**
     * 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> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, ScreenDefinition<any, any>> = {}, Labels extends string = string, Groups extends string = string, AssetGroupNames extends string = string, ReactiveQueryNames extends string = string> {
+export default class ECSpresso<Cfg extends WorldConfig = EmptyConfig, Labels extends string = string, Groups extends string = string, AssetGroupNames extends string = string, ReactiveQueryNames extends string = string> {
+    readonly _cfg: Cfg;
     /** Library version*/
     static readonly VERSION: string;
     /** Access/modify stored components and entities*/
@@ -39,8 +42,8 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     private _systems;
     /** Systems grouped by execution phase, each sorted by priority */
     private _phaseSystems;
-    /** Track installed bundles to prevent duplicates*/
-    private _installedBundles;
+    /** Track installed plugins to prevent duplicates*/
+    private _installedPlugins;
     /** Disabled system groups */
     private _disabledGroups;
     /** Asset manager for loading and accessing assets */
@@ -67,16 +70,25 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     private _maxFixedSteps;
     /** Registry of required component relationships: trigger -> [{component, factory}] */
     private _requiredComponents;
-    /** Pending bundle assets awaiting manager creation at build time */
-    private _pendingBundleAssets;
-    /** Pending bundle screens awaiting manager creation at build time */
-    private _pendingBundleScreens;
+    /** Pending plugin assets awaiting manager creation at build time */
+    private _pendingPluginAssets;
+    /** Pending plugin screens awaiting manager creation at build time */
+    private _pendingPluginScreens;
     /** Whether diagnostics timing collection is enabled */
     private _diagnosticsEnabled;
     /** Per-system timing in ms, populated when diagnostics enabled */
     private _systemTimings;
     /** Per-phase timing in ms, populated when diagnostics enabled */
     private _phaseTimings;
+    /** Per-system per-query seen entity IDs for onEntityEnter tracking */
+    private _entityEnterTracking;
+    /** Shared reusable set for per-tick entity enter comparison (avoids allocation) */
+    private _entityEnterFrameSet;
+    /** Pre-allocated process context per system (avoids per-frame allocation) */
+    private _systemContexts;
+    /** Pending system builder finalizers to run before next update/initialize */
+    private _pendingFinalizers;
+    private _batchingRegistrations;
     /**
         * Creates a new ECSpresso instance.
     */
@@ -88,9 +100,8 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      */
     private _subscribeLifecycleHooks;
     /**
-        * Creates a new ECSpresso builder for type-safe bundle installation.
-        * This is the preferred way to create an ECSpresso instance with bundles.
-        * Types are inferred from the builder chain — use `.withBundle()`,
+        * Creates a new ECSpresso builder for type-safe plugin installation.
+        * Types are inferred from the builder chain — use `.withPlugin()`,
         * `.withComponentTypes<T>()`, `.withEventTypes<T>()`, and `.withResource()`
         * to accumulate types without manual aggregate interfaces.
      *
@@ -99,8 +110,8 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         * @example
         * ```typescript
         * const ecs = ECSpresso.create()
-     *	 .withBundle(createRenderer2DBundle({ ... }))
-     *	 .withBundle(createPhysics2DBundle())
+     *	 .withPlugin(createRenderer2DPlugin({ ... }))
+     *	 .withPlugin(createPhysics2DPlugin())
      *	 .withComponentTypes<{ player: true; enemy: { type: string } }>()
      *	 .withEventTypes<{ gameStart: true }>()
      *	 .withResource('score', { value: 0 })
@@ -109,13 +120,19 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * type ECS = typeof ecs;
         * ```
     */
-    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, never, never, never, never>;
+    static create<Cfg2 extends WorldConfig = EmptyConfig>(): ECSpressoBuilder<Cfg2, never, never, never, never>;
     /**
-        * Adds a system directly to this ECSpresso instance
+        * Adds a system directly to this ECSpresso instance.
+        * The system is registered when initialize() or update() is next called.
         * @param label Unique name to identify the system
         * @returns A SystemBuilder instance for method chaining
     */
-    addSystem(label: string): import("./system-builder").SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates, {}, string, never>;
+    addSystem(label: string): SystemBuilder<Cfg>;
+    /**
+     * Finalize and register all pending system builders.
+     * @private
+     */
+    private _finalizePendingBuilders;
     /**
      * Update all systems across execution phases.
      * Phases run in order: preUpdate -> fixedUpdate -> update -> postUpdate -> render.
@@ -154,7 +171,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @param keys Optional array of resource keys to initialize. If not provided, all pending resources will be initialized.
      * @returns Promise that resolves when the specified resources are initialized
      */
-    initializeResources<K extends keyof ResourceTypes>(...keys: K[]): Promise<void>;
+    initializeResources<K extends keyof Cfg['resources']>(...keys: K[]): Promise<void>;
     /**
      * Rebuild per-phase system arrays from the flat _systems list.
      * Each phase array is sorted by priority (higher first), with
@@ -220,11 +237,11 @@ 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, AssetTypes, ScreenStates>): void;
+    _registerSystem(system: System<Cfg, any, any>): void;
     /**
         * Check if a resource exists
     */
-    hasResource<K extends keyof ResourceTypes>(key: K): boolean;
+    hasResource<K extends keyof Cfg['resources']>(key: K): boolean;
     /**
      * Get a resource by key. Throws if the resource is not found.
      * @param key The resource key
@@ -232,42 +249,47 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @throws Error if resource not found
      * @see tryGetResource — the non-throwing alternative that returns undefined
      */
-    getResource<K extends keyof ResourceTypes>(key: K): ResourceTypes[K];
+    getResource<K extends keyof Cfg['resources']>(key: K): Cfg['resources'][K];
     /**
      * Try to get a resource by key. Returns undefined if the resource is not found.
      * Inspired by Bevy's `World::get_resource::<T>()` which returns `Option<&T>`.
      *
      * Two overloads:
      * 1. Known key — full type safety from `ResourceTypes`
-     * 2. String key with explicit type param — for cross-bundle optional dependencies
+     * 2. String key with explicit type param — for cross-plugin optional dependencies
      *
      * @example
      * ```typescript
      * // Known key (type inferred from ResourceTypes)
      * const score = ecs.tryGetResource('score'); // ScoreResource | undefined
      *
-     * // Cross-bundle optional dependency (caller specifies expected type)
+     * // Cross-plugin optional dependency (caller specifies expected type)
      * const si = ecs.tryGetResource<SpatialIndex>('spatialIndex') ?? null;
      * ```
      */
-    tryGetResource<K extends keyof ResourceTypes>(key: K): ResourceTypes[K] | undefined;
+    tryGetResource<K extends keyof Cfg['resources']>(key: K): Cfg['resources'][K] | undefined;
     tryGetResource<T>(key: unknown extends T ? never : string): T | undefined;
     /**
-        * Add a resource to the ECS instance
+        * Add a resource to the ECS instance.
+        *
+        * - Plain value → stored directly
+        * - Function → treated as a factory, called with this ECSpresso instance on first access
+        * - `{ factory, dependsOn?, onDispose? }` → factory with dependencies/disposal
+        * - `directValue(val)` → stores the value as-is (use to store functions/classes without invoking them)
     */
-    addResource<K extends keyof ResourceTypes>(key: K, resource: ResourceTypes[K] | ((ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>) => ResourceTypes[K] | Promise<ResourceTypes[K]>) | ResourceFactoryWithDeps<ResourceTypes[K], ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>, keyof ResourceTypes & string>): this;
+    addResource<K extends keyof Cfg['resources']>(key: K, resource: Cfg['resources'][K] | ((ecs: ECSpresso<Cfg>) => Cfg['resources'][K] | Promise<Cfg['resources'][K]>) | ResourceFactoryWithDeps<Cfg['resources'][K], ECSpresso<Cfg>, keyof Cfg['resources'] & string> | ResourceDirectValue<Cfg['resources'][K]>): this;
     /**
         * 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;
+    removeResource<K extends keyof Cfg['resources']>(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>;
+    disposeResource<K extends keyof Cfg['resources']>(key: K): Promise<boolean>;
     /**
      * Dispose all initialized resources in reverse dependency order.
      * Resources that depend on others are disposed first.
@@ -281,34 +303,64 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         * @returns This ECSpresso instance for chaining
         * @throws Error if the resource doesn't exist
     */
-    updateResource<K extends keyof ResourceTypes>(key: K, updater: (current: ResourceTypes[K]) => ResourceTypes[K]): this;
+    updateResource<K extends keyof Cfg['resources']>(key: K, updater: (current: Cfg['resources'][K]) => Cfg['resources'][K]): this;
     /**
         * Get all resource keys that are currently registered
         * @returns Array of resource keys
     */
-    getResourceKeys(): Array<keyof ResourceTypes>;
+    getResourceKeys(): Array<keyof Cfg['resources']>;
     /**
         * Check if a resource needs initialization (was added as a factory function)
         * @param key The resource key to check
         * @returns True if the resource needs initialization
     */
-    resourceNeedsInitialization<K extends keyof ResourceTypes>(key: K): boolean;
+    resourceNeedsInitialization<K extends keyof Cfg['resources']>(key: K): boolean;
+    /**
+        * Get a component value from an entity.
+        * @param entityId The entity ID
+        * @param componentName The component to retrieve
+        * @returns The component value, or undefined if the entity doesn't have it
+    */
+    getComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K): Cfg['components'][K] | undefined;
+    /**
+        * Add or replace a component on an entity.
+        * Triggers component-added callbacks and marks the component as changed.
+        * @param entityId The entity ID
+        * @param componentName The component to add
+        * @param value The component value
+    */
+    addComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K, value: Cfg['components'][K]): void;
+    /**
+        * Add multiple components to an entity at once.
+        * @param entityId The entity ID
+        * @param components Object with component names as keys and component data as values
+    */
+    addComponents<T extends {
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(entityId: number, components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): void;
+    /**
+        * Remove a component from an entity.
+        * Triggers component-removed and dispose callbacks.
+        * @param entityId The entity ID
+        * @param componentName The component to remove
+    */
+    removeComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K): void;
     /**
         * Check if an entity has a component
     */
-    hasComponent<K extends keyof ComponentTypes>(entityId: number, componentName: K): boolean;
+    hasComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K): boolean;
     /**
         * Create an entity and add components to it in one call
         * @param components Object with component names as keys and component data as values
         * @returns The created entity with all components added
         */
     spawn<T extends {
-        [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes>;
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): FilteredEntity<Cfg['components'], keyof T & keyof Cfg['components']>;
     /**
         * Get all entities with specific components
     */
-    getEntitiesWithQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>, changedComponents?: ReadonlyArray<keyof ComponentTypes>, parentHas?: ReadonlyArray<keyof ComponentTypes>): Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>;
+    getEntitiesWithQuery<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>, changedComponents?: ReadonlyArray<keyof Cfg['components']>, parentHas?: ReadonlyArray<keyof Cfg['components']>): Array<FilteredEntity<Cfg['components'], WithComponents, WithoutComponents>>;
     /**
      * Get the single entity matching a query. Throws if zero or more than one match.
      * @param withComponents Components the entity must have
@@ -316,7 +368,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @returns The single matching entity
      * @throws If zero or more than one entity matches
      */
-    getSingleton<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>;
+    getSingleton<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<Cfg['components'], WithComponents, WithoutComponents>;
     /**
      * Get the single entity matching a query, or undefined if none match.
      * Throws if more than one entity matches.
@@ -325,99 +377,99 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @returns The single matching entity, or undefined if none match
      * @throws If more than one entity matches
      */
-    tryGetSingleton<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<ComponentTypes, WithComponents, WithoutComponents> | undefined;
+    tryGetSingleton<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<Cfg['components'], WithComponents, WithoutComponents> | undefined;
     /**
      * Remove an entity (and optionally its descendants)
-     * @param entityOrId Entity or entity ID to remove
+     * @param entityId 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;
+    removeEntity(entityId: number, options?: RemoveEntityOptions): boolean;
     /**
      * Create an entity as a child of another entity with initial components
-     * @param parentOrId The parent entity or entity ID
+     * @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];
-    }>(parentOrId: number | Entity<ComponentTypes>, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes>;
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): FilteredEntity<Cfg['components'], keyof T & keyof Cfg['components']>;
     /**
      * Set the parent of an entity
-     * @param childOrId The entity or entity ID to set as a child
-     * @param parentOrId The entity or entity ID to set as the parent
+     * @param childId The entity ID to set as a child
+     * @param parentId The entity ID to set as the parent
      */
-    setParent(childOrId: number | Entity<ComponentTypes>, parentOrId: number | Entity<ComponentTypes>): this;
+    setParent(childId: number, parentId: number): this;
     /**
      * Remove the parent relationship for an entity (orphan it)
-     * @param childOrId The entity or entity ID to orphan
+     * @param childId The entity ID to orphan
      * @returns true if a parent was removed, false if entity had no parent
      */
-    removeParent(childOrId: number | Entity<ComponentTypes>): boolean;
+    removeParent(childId: number): boolean;
     /**
      * Get the parent of an entity
-     * @param entityOrId The entity or entity ID to get the parent of
+     * @param entityId The entity ID to get the parent of
      * @returns The parent entity ID, or null if no parent
      */
-    getParent(entityOrId: number | Entity<ComponentTypes>): number | null;
+    getParent(entityId: number): number | null;
     /**
      * Get all children of an entity in insertion order
-     * @param parentOrId The parent entity or entity ID
+     * @param parentId The parent entity ID
      * @returns Readonly array of child entity IDs
      */
-    getChildren(parentOrId: number | Entity<ComponentTypes>): readonly number[];
+    getChildren(parentId: number): readonly number[];
     /**
      * Get a child at a specific index
-     * @param parentOrId The parent entity or entity ID
+     * @param parentId The parent entity ID
      * @param index The index of the child
      * @returns The child entity ID, or null if index is out of bounds
      */
-    getChildAt(parentOrId: number | Entity<ComponentTypes>, index: number): number | null;
+    getChildAt(parentId: number, index: number): number | null;
     /**
      * Get the index of a child within its parent's children list
-     * @param parentOrId The parent entity or entity ID
-     * @param childOrId The child entity or entity ID to find
+     * @param parentId The parent entity ID
+     * @param childId The child entity ID to find
      * @returns The index of the child, or -1 if not found
      */
-    getChildIndex(parentOrId: number | Entity<ComponentTypes>, childOrId: number | Entity<ComponentTypes>): number;
+    getChildIndex(parentId: number, childId: number): number;
     /**
      * Get all ancestors of an entity in order [parent, grandparent, ...]
-     * @param entityOrId The entity or entity ID to get ancestors of
+     * @param entityId The entity ID to get ancestors of
      * @returns Readonly array of ancestor entity IDs
      */
-    getAncestors(entityOrId: number | Entity<ComponentTypes>): readonly number[];
+    getAncestors(entityId: number): readonly number[];
     /**
      * Get all descendants of an entity in depth-first order
-     * @param entityOrId The entity or entity ID to get descendants of
+     * @param entityId The entity ID to get descendants of
      * @returns Readonly array of descendant entity IDs
      */
-    getDescendants(entityOrId: number | Entity<ComponentTypes>): readonly number[];
+    getDescendants(entityId: number): readonly number[];
     /**
      * Get the root ancestor of an entity (topmost parent), or self if no parent
-     * @param entityOrId The entity or entity ID to get the root of
+     * @param entityId The entity ID to get the root of
      * @returns The root entity ID
      */
-    getRoot(entityOrId: number | Entity<ComponentTypes>): number;
+    getRoot(entityId: number): number;
     /**
      * Get siblings of an entity (other children of the same parent)
-     * @param entityOrId The entity or entity ID to get siblings of
+     * @param entityId The entity ID to get siblings of
      * @returns Readonly array of sibling entity IDs
      */
-    getSiblings(entityOrId: number | Entity<ComponentTypes>): readonly number[];
+    getSiblings(entityId: number): readonly number[];
     /**
      * Check if an entity is a descendant of another entity
-     * @param entityOrId The potential descendant (entity or ID)
-     * @param ancestorOrId The potential ancestor (entity or ID)
-     * @returns true if entityOrId is a descendant of ancestorOrId
+     * @param entityId The potential descendant ID
+     * @param ancestorId The potential ancestor ID
+     * @returns true if entityId is a descendant of ancestorId
      */
-    isDescendantOf(entityOrId: number | Entity<ComponentTypes>, ancestorOrId: number | Entity<ComponentTypes>): boolean;
+    isDescendantOf(entityId: number, ancestorId: number): boolean;
     /**
      * Check if an entity is an ancestor of another entity
-     * @param entityOrId The potential ancestor (entity or ID)
-     * @param descendantOrId The potential descendant (entity or ID)
-     * @returns true if entityOrId is an ancestor of descendantOrId
+     * @param entityId The potential ancestor ID
+     * @param descendantId The potential descendant ID
+     * @returns true if entityId is an ancestor of descendantId
      */
-    isAncestorOf(entityOrId: number | Entity<ComponentTypes>, descendantOrId: number | Entity<ComponentTypes>): boolean;
+    isAncestorOf(entityId: number, descendantId: number): boolean;
     /**
      * Get all root entities (entities that have children but no parent)
      * @returns Readonly array of root entity IDs
@@ -443,11 +495,11 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      */
     private _emitHierarchyChanged;
     /**
-        * Get all installed bundle IDs
+        * Get all installed plugin IDs
     */
-    get installedBundles(): string[];
-    get entityManager(): EntityManager<ComponentTypes>;
-    get eventBus(): EventBus<EventTypes>;
+    get installedPlugins(): string[];
+    get entityManager(): EntityManager<Cfg["components"]>;
+    get eventBus(): EventBus<Cfg["events"]>;
     /**
      * Command buffer for queuing deferred structural changes.
      * Commands are executed automatically at the end of each update() cycle.
@@ -459,7 +511,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * ecs.commands.spawn({ position: { x: 0, y: 0 } });
      * ```
      */
-    get commands(): CommandBuffer<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
+    get commands(): CommandBuffer<Cfg>;
     /**
      * The current tick number, incremented at the end of each update()
      */
@@ -481,22 +533,34 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     get systemTimings(): ReadonlyMap<string, number>;
     get phaseTimings(): Readonly<Record<SystemPhase, number>>;
     get entityCount(): number;
+    /**
+     * Mutate a component in place and automatically mark it as changed.
+     * Throws if the entity does not exist or does not have the component.
+     * @param entityId The entity ID
+     * @param componentName The component to mutate
+     * @param mutator A function that receives the component value for in-place mutation
+     * @returns The mutated component value
+     */
+    mutateComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K, mutator: (value: Cfg['components'][K]) => void): Cfg['components'][K];
     /**
      * Mark a component as changed on an entity.
      * Each call increments a global monotonic sequence; systems with changed
      * queries will see the mark exactly once (on their next execution).
-     * @param entityOrId The entity or entity ID
+     * @param entityId The entity ID
      * @param componentName The component that was changed
      */
-    markChanged<K extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: K): void;
+    markChanged<K extends keyof Cfg['components']>(entityId: number, componentName: K): void;
     /**
      * Register a dispose callback for a component type.
      * Called when a component is removed (explicit removal, entity destruction, or replacement).
      * Later registrations replace earlier ones for the same component type.
      * @param componentName The component type to register disposal for
-     * @param callback Function receiving the component value being disposed
+     * @param callback Function receiving the component value being disposed and the entity ID
      */
-    registerDispose<K extends keyof ComponentTypes>(componentName: K, callback: (value: ComponentTypes[K]) => void): void;
+    registerDispose<K extends keyof Cfg['components']>(componentName: K, callback: (ctx: {
+        value: Cfg['components'][K];
+        entityId: number;
+    }) => void): void;
     /**
      * Register a required component relationship.
      * When an entity gains `trigger`, the `required` component is auto-added
@@ -506,7 +570,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @param required The component to auto-add
      * @param factory Function that creates the default value for the required component
      */
-    registerRequired<Trigger extends keyof ComponentTypes, Required extends keyof ComponentTypes>(trigger: Trigger, required: Required, factory: (triggerValue: ComponentTypes[Trigger]) => ComponentTypes[Required]): void;
+    registerRequired<Trigger extends keyof Cfg['components'], Required extends keyof Cfg['components']>(trigger: Trigger, required: Required, factory: (triggerValue: Cfg['components'][Trigger]) => Cfg['components'][Required]): void;
     /**
      * Check for circular dependencies in the required components graph.
      * @throws Error if adding trigger→newRequired would create a cycle
@@ -518,20 +582,26 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @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;
+    onComponentAdded<K extends keyof Cfg['components']>(componentName: K, handler: (ctx: {
+        value: Cfg['components'][K];
+        entity: Entity<Cfg['components']>;
+    }) => 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;
+    onComponentRemoved<K extends keyof Cfg['components']>(componentName: K, handler: (ctx: {
+        value: Cfg['components'][K];
+        entity: Entity<Cfg['components']>;
+    }) => 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, OptionalComponents extends keyof ComponentTypes = never>(name: ReactiveQueryNames, definition: ReactiveQueryDefinition<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>): void;
+    addReactiveQuery<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never, OptionalComponents extends keyof Cfg['components'] = never>(name: ReactiveQueryNames, definition: ReactiveQueryDefinition<Cfg['components'], WithComponents, WithoutComponents, OptionalComponents>): void;
     /**
      * Remove a reactive query by name.
      * @param name Name of the query to remove
@@ -544,41 +614,44 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @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;
+    on<E extends keyof Cfg['events']>(eventType: E, callback: (data: Cfg['events'][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;
+    off<E extends keyof Cfg['events']>(eventType: E, callback: (data: Cfg['events'][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, AssetTypes, ScreenStates>, deltaTime: number) => void): () => void;
+    onPostUpdate(callback: (ctx: {
+        ecs: ECSpresso<Cfg>;
+        dt: number;
+    }) => void): () => void;
     private requireAssetManager;
     /**
      * Get a loaded asset by key. Throws if not loaded.
      */
-    getAsset<K extends keyof AssetTypes>(key: K): AssetTypes[K];
+    getAsset<K extends keyof Cfg['assets']>(key: K): Cfg['assets'][K];
     /**
      * Get a loaded asset or undefined if not loaded
      */
-    getAssetOrUndefined<K extends keyof AssetTypes>(key: K): AssetTypes[K] | undefined;
+    tryGetAsset<K extends keyof Cfg['assets']>(key: K): Cfg['assets'][K] | undefined;
     /**
      * Get a handle to an asset with status information
      */
-    getAssetHandle<K extends keyof AssetTypes>(key: K): AssetHandle<AssetTypes[K]>;
+    getAssetHandle<K extends keyof Cfg['assets']>(key: K): AssetHandle<Cfg['assets'][K]>;
     /**
      * Check if an asset is loaded
      */
-    isAssetLoaded<K extends keyof AssetTypes>(key: K): boolean;
+    isAssetLoaded<K extends keyof Cfg['assets']>(key: K): boolean;
     /**
      * Load a single asset
      */
-    loadAsset<K extends keyof AssetTypes>(key: K): Promise<AssetTypes[K]>;
+    loadAsset<K extends keyof Cfg['assets']>(key: K): Promise<Cfg['assets'][K]>;
     /**
      * Load all assets in a group
      */
@@ -595,11 +668,11 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     /**
      * 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>;
+    setScreen<K extends keyof Cfg['screens']>(name: K, config: Cfg['screens'][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>;
+    pushScreen<K extends keyof Cfg['screens']>(name: K, config: Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
     /**
      * Pop the current screen and return to the previous one
      */
@@ -607,62 +680,124 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     /**
      * Get the current screen name
      */
-    getCurrentScreen(): keyof ScreenStates | null;
+    getCurrentScreen(): keyof Cfg['screens'] | null;
+    /**
+     * Get the current screen config (immutable), narrowed to a specific screen.
+     * Throws if the current screen doesn't match.
+     */
+    getScreenConfig<K extends keyof Cfg['screens'] & string>(screen: K): Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    /**
+     * Get the current screen config (immutable).
+     * Returns a union of all possible config types.
+     */
+    getScreenConfig(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    }[keyof Cfg['screens']];
+    /**
+     * Get the current screen config narrowed to a specific screen, or undefined if not on that screen.
+     */
+    tryGetScreenConfig<K extends keyof Cfg['screens'] & string>(screen: K): (Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never) | undefined;
     /**
-     * Get the current screen config (immutable)
+     * Get the current screen config or undefined.
+     * Returns a union of all possible config types, or undefined.
      */
-    getScreenConfig<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    tryGetScreenConfig(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    }[keyof Cfg['screens']] | undefined;
     /**
-     * Get the current screen config or null
+     * Get the current screen state (mutable), narrowed to a specific screen.
+     * Throws if the current screen doesn't match.
      */
-    getScreenConfigOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never) | null;
+    getScreenState<K extends keyof Cfg['screens'] & string>(screen: K): Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never;
     /**
-     * Get the current screen state (mutable)
+     * Get the current screen state (mutable).
+     * Returns a union of all possible state types.
      */
-    getScreenState<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never;
+    getScreenState(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never;
+    }[keyof Cfg['screens']];
     /**
-     * Get the current screen state or null
+     * Get the current screen state narrowed to a specific screen, or undefined if not on that screen.
      */
-    getScreenStateOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never) | null;
+    tryGetScreenState<K extends keyof Cfg['screens'] & string>(screen: K): (Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never) | undefined;
     /**
-     * Update the current screen state
+     * Get the current screen state or undefined.
+     * Returns a union of all possible state types, or undefined.
      */
-    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;
+    tryGetScreenState(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never;
+    }[keyof Cfg['screens']] | undefined;
+    /**
+     * Update the current screen state, narrowed to a specific screen.
+     * Throws if the current screen doesn't match.
+     */
+    updateScreenState<K extends keyof Cfg['screens'] & string>(screen: K, update: Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never> | ((current: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never) => Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never>)): void;
+    /**
+     * Update the current screen state.
+     */
+    updateScreenState<K extends keyof Cfg['screens']>(update: Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never> | ((current: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never) => Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never>)): void;
     /**
      * Check if a screen is the current screen
      */
-    isCurrentScreen(screenName: keyof ScreenStates): boolean;
+    isCurrentScreen(screenName: keyof Cfg['screens']): boolean;
     /**
      * Check if a screen is active (current or in stack)
      */
-    isScreenActive(screenName: keyof ScreenStates): boolean;
+    isScreenActive(screenName: keyof Cfg['screens']): boolean;
     /**
      * Get the screen stack depth
      */
     getScreenStackDepth(): number;
     /**
-     * Internal method to set the asset manager and drain pending bundle assets
+     * Internal method to set the asset manager and drain pending plugin assets
      * @internal Used by ECSpressoBuilder
      */
-    _setAssetManager(manager: AssetManager<AssetTypes>): void;
+    _setAssetManager(manager: AssetManager<Cfg['assets']>): void;
     /**
-     * Internal method to set the screen manager and drain pending bundle screens
+     * Internal method to set the screen manager and drain pending plugin screens
      * @internal Used by ECSpressoBuilder
      */
-    _setScreenManager(manager: ScreenManager<ScreenStates>): void;
+    _setScreenManager(manager: ScreenManager<Cfg['screens']>): void;
     /** @internal */
-    _hasPendingBundleAssets(): boolean;
+    _hasPendingPluginAssets(): boolean;
     /** @internal */
-    _hasPendingBundleScreens(): boolean;
+    _hasPendingPluginScreens(): boolean;
     /**
      * Internal method to set the fixed timestep interval
      * @internal Used by ECSpressoBuilder
      */
     _setFixedDt(dt: number): 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>, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}>(bundle: Bundle<C, E, R, A, S, any, any, any, any>): this;
+     * Register an asset definition for deferred registration.
+     * @internal Used by plugins that need to register assets
+     */
+    _registerAsset(key: string, definition: AssetDefinition<unknown>): void;
+    /**
+     * Register a screen definition for deferred registration.
+     * @internal Used by plugins that need to register screens
+     */
+    _registerScreen(name: string, definition: ScreenDefinition<any, any>): void;
+    /**
+     * Install a plugin into this ECSpresso instance.
+     * Deduplicates by plugin ID. Composite plugins call this in their install function.
+     */
+    installPlugin(plugin: Plugin<any, any, any, any, any, any>): this;
+    /**
+     * Create a plugin factory from the built world's types.
+     * Returns a definePlugin equivalent with no manual type parameters.
+     */
+    pluginFactory(): <PL extends string = never, PG extends string = never, PAG extends string = never, PRQ extends string = never>(config: {
+        id: string;
+        install: (world: ECSpresso<Cfg>) => void;
+    }) => Plugin<Cfg, EmptyConfig, PL, PG, PAG, PRQ>;
+    /**
+     * Call a helper factory with this world instance, inferring the full world type.
+     * Eliminates the need for a separate `type ECS = typeof ecs` ceremony.
+     *
+     * @example
+     * ```typescript
+     * const helpers = ecs.getHelpers(createStateMachineHelpers);
+     * ```
+     */
+    getHelpers<H>(factory: (world: this) => H): H;
 }