ecspresso 0.11.0 → 0.12.0

package/dist/command-buffer.d.ts

@@ -1,5 +1,6 @@
 import type ECSpresso from './ecspresso';
-import type { Entity, RemoveEntityOptions } from './types';
+import type { RemoveEntityOptions } from './types';
+import type { WorldConfig, EmptyConfig } from './type-utils';
 /**
  * CommandBuffer queues structural changes to be executed later.
  * This prevents ordering issues when modifying entities during system execution.
@@ -16,74 +17,83 @@ import type { Entity, RemoveEntityOptions } from './types';
  * ecs.commands.playback(ecs);
  * ```
  */
-export default class CommandBuffer<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> = {}> {
+export default class CommandBuffer<Cfg extends WorldConfig = EmptyConfig> {
     private commands;
     /**
      * Queue an entity removal command
-     * @param entityOrId The entity or entity ID to remove
+     * @param entityId The entity ID to remove
      * @param options Optional removal options (cascade, etc.)
      */
-    removeEntity(entityOrId: number | Entity<ComponentTypes>, options?: RemoveEntityOptions): void;
+    removeEntity(entityId: number, options?: RemoveEntityOptions): void;
     /**
      * Queue a component addition command
-     * @param entityOrId The entity or entity ID
+     * @param entityId The entity ID
      * @param componentName The name of the component to add
      * @param componentValue The component data
      */
-    addComponent<K extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: K, componentValue: ComponentTypes[K]): void;
+    addComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K, componentValue: Cfg['components'][K]): void;
     /**
      * Queue a component removal command
-     * @param entityOrId The entity or entity ID
+     * @param entityId The entity ID
      * @param componentName The name of the component to remove
      */
-    removeComponent<K extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: K): void;
+    removeComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K): void;
     /**
      * Queue an entity spawn command
      * @param components The initial components for the new entity
      * @returns void (entity ID not available until playback)
      */
     spawn<T extends {
-        [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): void;
     /**
      * Queue a child entity spawn command
-     * @param parentOrId The parent entity or entity ID
+     * @param parentId The parent entity ID
      * @param components The initial components for the new child entity
      */
     spawnChild<T extends {
-        [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(parentOrId: number | Entity<ComponentTypes>, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): void;
     /**
      * Queue multiple component additions
-     * @param entityOrId The entity or entity ID
+     * @param entityId The entity ID
      * @param components Object with component names as keys and component data as values
      */
     addComponents<T extends {
-        [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(entityOrId: number | Entity<ComponentTypes>, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(entityId: number, components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): void;
     /**
      * Queue a parent assignment command
-     * @param childOrId The child entity or entity ID
-     * @param parentOrId The parent entity or entity ID
+     * @param childId The child entity ID
+     * @param parentId The parent entity ID
      */
-    setParent(childOrId: number | Entity<ComponentTypes>, parentOrId: number | Entity<ComponentTypes>): void;
+    setParent(childId: number, parentId: number): void;
+    /**
+     * Queue a component mutation command.
+     * The mutator runs during playback, receiving the component for in-place mutation.
+     * Automatically marks the component as changed.
+     * @param entityId The entity ID
+     * @param componentName The component to mutate
+     * @param mutator A function that receives the component value for in-place mutation
+     */
+    mutateComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K, mutator: (value: Cfg['components'][K]) => void): void;
     /**
      * Queue a markChanged command
-     * @param entityOrId The entity or entity ID
+     * @param entityId The entity ID
      * @param componentName The component to mark as changed
      */
-    markChanged<K extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: K): void;
+    markChanged<K extends keyof Cfg['components']>(entityId: number, componentName: K): void;
     /**
      * Queue a parent removal command
-     * @param childOrId The child entity or entity ID
+     * @param childId The child entity ID
      */
-    removeParent(childOrId: number | Entity<ComponentTypes>): void;
+    removeParent(childId: number): void;
     /**
      * Execute all queued commands in FIFO order.
      * Errors from individual commands are caught and logged, but do not stop playback.
      * @param ecs The ECSpresso instance to execute commands on
      */
-    playback(ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
+    playback(ecs: ECSpresso<Cfg>): void;
     /**
      * Clear all queued commands without executing them
      */

package/dist/ecspresso-builder.d.ts

@@ -1,24 +1,30 @@
 import type ECSpresso from "./ecspresso";
-import type { ResourceFactoryWithDeps } from "./resource-manager";
-import type Bundle from "./bundle";
-import type { BundlesAreCompatible, TypesAreCompatible } from "./type-utils";
+import type { ResourceFactoryWithDeps, ResourceDirectValue } from "./resource-manager";
+import { type Plugin } from "./plugin";
+import type { WorldConfig, EmptyConfig, ConfigsAreCompatible, MergeConfigs, TypesAreCompatible, RequirementsSatisfied, WithComponents, WithEvents, WithResources } from "./type-utils";
 import type { AssetConfigurator, AssetsResource } from "./asset-types";
 import type { ScreenDefinition, ScreenConfigurator, ScreenResource } from "./screen-types";
 /**
  * Helper type: finalize built-in resources ($assets, $screen) in the resource map.
- * Auto-injects $assets/$screen when bundles contribute asset/screen types even without
+ * Auto-injects $assets/$screen when plugins contribute asset/screen types even without
  * explicit withAssets()/withScreens(). Also narrows the AssetGroupNames on $assets.
  */
-type FinalizeBuiltinResources<R, A extends Record<string, unknown>, S extends Record<string, ScreenDefinition<any, any>>, AG extends string> = Omit<R, '$assets' | '$screen'> & ([keyof A] extends [never] ? {} : {
-    $assets: AssetsResource<A, AG>;
-}) & ([keyof S] extends [never] ? {} : {
-    $screen: ScreenResource<S>;
-});
+type FinalizeBuiltinResources<Cfg extends WorldConfig, AG extends string> = {
+    readonly components: Cfg['components'];
+    readonly events: Cfg['events'];
+    readonly resources: Omit<Cfg['resources'], '$assets' | '$screen'> & ([keyof Cfg['assets']] extends [never] ? {} : {
+        $assets: AssetsResource<Cfg['assets'], AG>;
+    }) & ([keyof Cfg['screens']] extends [never] ? {} : {
+        $screen: ScreenResource<Cfg['screens']>;
+    });
+    readonly assets: Cfg['assets'];
+    readonly screens: Cfg['screens'];
+};
 /**
-    * Builder class for ECSpresso that provides fluent type-safe bundle installation.
+    * Builder class for ECSpresso that provides fluent type-safe plugin 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> = {}, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}, Labels extends string = never, Groups extends string = never, AssetGroupNames extends string = never, ReactiveQueryNames extends string = never> {
+export declare class ECSpressoBuilder<Cfg extends WorldConfig = EmptyConfig, Labels extends string = never, Groups extends string = never, AssetGroupNames extends string = never, ReactiveQueryNames extends string = never> {
     /** The ECSpresso instance being built*/
     private ecspresso;
     /** Asset configurator for collecting asset definitions */
@@ -31,51 +37,66 @@ export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E exte
     private pendingDisposeCallbacks;
     /** Pending required component registrations to apply during build */
     private pendingRequiredComponents;
+    /** Pending plugins to install during build */
+    private pendingPlugins;
     /** Fixed timestep interval (null means use default 1/60) */
     private _fixedDt;
     constructor();
     /**
-        * Add the first bundle when starting with empty types.
-        * This overload allows any bundle to be added to an empty ECSpresso instance.
+        * Add the first plugin when starting with empty types.
+        * This overload allows any plugin to be added to an empty ECSpresso instance.
+        * Only merges the plugin's Provides (PCfg) into accumulated config, not its Requires (PReq).
     */
-    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>, BA extends Record<string, unknown> = {}, BS extends Record<string, ScreenDefinition<any, any>> = {}, BL extends string = never, BG extends string = never, BAG extends string = never, BRQ extends string = never>(this: ECSpressoBuilder<{}, {}, {}, A, S, Labels, Groups, AssetGroupNames, ReactiveQueryNames>, bundle: Bundle<BC, BE, BR, BA, BS, BL, BG, BAG, BRQ>): ECSpressoBuilder<BC, BE, BR, A & BA, S & BS, Labels | BL, Groups | BG, AssetGroupNames | BAG, ReactiveQueryNames | BRQ>;
+    withPlugin<PCfg extends WorldConfig, PReq extends WorldConfig = EmptyConfig, BL extends string = never, BG extends string = never, BAG extends string = never, BRQ extends string = never>(this: ECSpressoBuilder<{
+        readonly components: {};
+        readonly events: {};
+        readonly resources: {};
+        readonly assets: Cfg['assets'];
+        readonly screens: Cfg['screens'];
+    }, Labels, Groups, AssetGroupNames, ReactiveQueryNames>, plugin: Plugin<PCfg, PReq, BL, BG, BAG, BRQ>): ECSpressoBuilder<{
+        readonly components: PCfg['components'];
+        readonly events: PCfg['events'];
+        readonly resources: PCfg['resources'];
+        readonly assets: Cfg['assets'] & PCfg['assets'];
+        readonly screens: Cfg['screens'] & PCfg['screens'];
+    }, Labels | BL, Groups | BG, AssetGroupNames | BAG, ReactiveQueryNames | BRQ>;
     /**
-        * Add a subsequent bundle with type checking.
-        * This overload enforces bundle type compatibility.
+        * Add a subsequent plugin with type checking.
+        * This overload enforces plugin type compatibility and requirement satisfaction.
+        * Only merges the plugin's Provides (PCfg) into accumulated config, not its Requires (PReq).
     */
-    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>, BA extends Record<string, unknown> = {}, BS extends Record<string, ScreenDefinition<any, any>> = {}, BL extends string = never, BG extends string = never, BAG extends string = never, BRQ extends string = never>(bundle: BundlesAreCompatible<C, BC, E, BE, R, BR, A, BA, S, BS> extends true ? Bundle<BC, BE, BR, BA, BS, BL, BG, BAG, BRQ> : never): ECSpressoBuilder<C & BC, E & BE, R & BR, A & BA, S & BS, Labels | BL, Groups | BG, AssetGroupNames | BAG, ReactiveQueryNames | BRQ>;
+    withPlugin<PCfg extends WorldConfig, PReq extends WorldConfig = EmptyConfig, BL extends string = never, BG extends string = never, BAG extends string = never, BRQ extends string = never>(plugin: ConfigsAreCompatible<Cfg, PCfg> extends true ? RequirementsSatisfied<Cfg, PReq> extends true ? Plugin<PCfg, PReq, BL, BG, BAG, BRQ> : never : never): ECSpressoBuilder<MergeConfigs<Cfg, PCfg>, Labels | BL, Groups | BG, AssetGroupNames | BAG, ReactiveQueryNames | BRQ>;
     /**
      * Add application-specific component types to the builder chain.
      * This is a pure type-level operation with no runtime cost.
      * Conflicts with existing component types (same key, different type) produce a `never` return.
      */
-    withComponentTypes<T extends Record<string, any>>(): TypesAreCompatible<C, T> extends true ? ECSpressoBuilder<C & T, E, R, A, S, Labels, Groups, AssetGroupNames, ReactiveQueryNames> : never;
+    withComponentTypes<T extends Record<string, any>>(): TypesAreCompatible<Cfg['components'], T> extends true ? ECSpressoBuilder<WithComponents<Cfg, T>, Labels, Groups, AssetGroupNames, ReactiveQueryNames> : never;
     /**
      * Add application-specific event types to the builder chain.
      * This is a pure type-level operation with no runtime cost.
      * Conflicts with existing event types (same key, different type) produce a `never` return.
      */
-    withEventTypes<T extends Record<string, any>>(): TypesAreCompatible<E, T> extends true ? ECSpressoBuilder<C, E & T, R, A, S, Labels, Groups, AssetGroupNames, ReactiveQueryNames> : never;
+    withEventTypes<T extends Record<string, any>>(): TypesAreCompatible<Cfg['events'], T> extends true ? ECSpressoBuilder<WithEvents<Cfg, T>, Labels, Groups, AssetGroupNames, ReactiveQueryNames> : never;
     /**
-     * Add a resource during ECSpresso construction
+     * Add application-specific resource types to the builder chain.
+     * This is a pure type-level operation with no runtime cost.
+     * Conflicts with existing resource types (same key, different type) produce a `never` return.
+     */
+    withResourceTypes<T extends Record<string, any>>(): TypesAreCompatible<Cfg['resources'], T> extends true ? ECSpressoBuilder<WithResources<Cfg, T>, Labels, Groups, AssetGroupNames, ReactiveQueryNames> : never;
+    /**
+     * Add a resource during ECSpresso construction.
+     *
+     * When the key matches a pre-declared resource type (via `withResourceTypes`, `create<C,E,R>()`,
+     * or plugin resources), the value is validated against that type.
+     * For new keys, the value type is inferred as before.
+     *
      * @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: ECSpresso<C, E, R & Record<K, V>, A, S>) => V | Promise<V>) | ResourceFactoryWithDeps<V, ECSpresso<C, E, R & Record<K, V>, A, S>, keyof (R & Record<K, V>) & string>): ECSpressoBuilder<C, E, R & Record<K, V>, A, S, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
+    withResource<K extends keyof Cfg['resources'] & string>(key: K, resource: Cfg['resources'][K] | ((context: ECSpresso<Cfg>) => Cfg['resources'][K] | Promise<Cfg['resources'][K]>) | ResourceFactoryWithDeps<Cfg['resources'][K], ECSpresso<Cfg>, keyof Cfg['resources'] & string> | ResourceDirectValue<Cfg['resources'][K]>): ECSpressoBuilder<Cfg, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
+    withResource<K extends string, V>(key: K & ([K] extends [keyof Cfg['resources']] ? [V] extends [Cfg['resources'][K & keyof Cfg['resources']]] ? string : never : string), resource: V | ((context: ECSpresso<WithResources<Cfg, Record<K, V>>>) => V | Promise<V>) | ResourceFactoryWithDeps<V, ECSpresso<WithResources<Cfg, Record<K, V>>>, keyof (Cfg['resources'] & Record<K, V>) & string> | ResourceDirectValue<V>): ECSpressoBuilder<WithResources<Cfg, Record<K, V>>, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
     /**
      * Register a dispose callback for a component type during build.
      * Called when a component is removed (explicit removal, entity destruction, or replacement).
@@ -83,7 +104,10 @@ export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E exte
      * @param callback Function receiving the component value being disposed
      * @returns This builder for method chaining
      */
-    withDispose<K extends keyof C & string>(componentName: K, callback: (value: C[K]) => void): this;
+    withDispose<K extends keyof Cfg['components'] & string>(componentName: K, callback: (ctx: {
+        value: Cfg['components'][K];
+        entityId: number;
+    }) => void): this;
     /**
      * Register a required component relationship during build.
      * When an entity gains `trigger`, the `required` component is auto-added
@@ -93,51 +117,47 @@ export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E exte
      * @param factory Function that creates the default value for the required component
      * @returns This builder for method chaining
      */
-    withRequired<Trigger extends keyof C & string, Required extends keyof C & string>(trigger: Trigger, required: Required, factory: (triggerValue: C[Trigger]) => C[Required]): this;
+    withRequired<Trigger extends keyof Cfg['components'] & string, Required extends keyof Cfg['components'] & string>(trigger: Trigger, required: Required, factory: (triggerValue: Cfg['components'][Trigger]) => Cfg['components'][Required]): this;
     /**
      * 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>, NewG extends string = never>(configurator: (assets: AssetConfigurator<{}, never>) => AssetConfigurator<NewA, NewG>): ECSpressoBuilder<C, E, R & {
-        $assets: AssetsResource<A & NewA, string>;
-    }, A & NewA, S, Labels, Groups, AssetGroupNames | NewG, ReactiveQueryNames>;
+    withAssets<NewA extends Record<string, unknown>, NewG extends string = never>(configurator: (assets: AssetConfigurator<{}, never>) => AssetConfigurator<NewA, NewG>): ECSpressoBuilder<{
+        readonly components: Cfg['components'];
+        readonly events: Cfg['events'];
+        readonly resources: Cfg['resources'] & {
+            $assets: AssetsResource<Cfg['assets'] & NewA, string>;
+        };
+        readonly assets: Cfg['assets'] & NewA;
+        readonly screens: Cfg['screens'];
+    }, Labels, Groups, AssetGroupNames | NewG, ReactiveQueryNames>;
     /**
      * 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<{}, ECSpresso<C, E, R, A, Record<string, ScreenDefinition>>>) => ScreenConfigurator<NewS, ECSpresso<C, E, R, A, Record<string, ScreenDefinition>>>): ECSpressoBuilder<C, E, R & {
-        $screen: ScreenResource<S & NewS>;
-    }, A, S & NewS, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
+    withScreens<NewS extends Record<string, ScreenDefinition<any, any>>>(configurator: (screens: ScreenConfigurator<{}, ECSpresso<{
+        readonly components: Cfg['components'];
+        readonly events: Cfg['events'];
+        readonly resources: Cfg['resources'];
+        readonly assets: Cfg['assets'];
+        readonly screens: Record<string, ScreenDefinition>;
+    }>>) => ScreenConfigurator<NewS, ECSpresso<{
+        readonly components: Cfg['components'];
+        readonly events: Cfg['events'];
+        readonly resources: Cfg['resources'];
+        readonly assets: Cfg['assets'];
+        readonly screens: Record<string, ScreenDefinition>;
+    }>>): ECSpressoBuilder<{
+        readonly components: Cfg['components'];
+        readonly events: Cfg['events'];
+        readonly resources: Cfg['resources'] & {
+            $screen: ScreenResource<Cfg['screens'] & NewS>;
+        };
+        readonly assets: Cfg['assets'];
+        readonly screens: Cfg['screens'] & NewS;
+    }, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
     /**
      * Configure the fixed timestep interval for the fixedUpdate phase.
      * @param dt The fixed timestep in seconds (e.g., 1/60 for 60Hz physics)
@@ -148,11 +168,19 @@ export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E exte
      * Declare reactive query names that will be registered at runtime.
      * This is a pure type-level operation with no runtime cost.
      */
-    withReactiveQueryNames<N extends string>(): ECSpressoBuilder<C, E, R, A, S, Labels, Groups, AssetGroupNames, ReactiveQueryNames | N>;
+    withReactiveQueryNames<N extends string>(): ECSpressoBuilder<Cfg, Labels, Groups, AssetGroupNames, ReactiveQueryNames | N>;
+    /**
+     * Create a plugin factory from the builder's accumulated 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>;
     /**
         * Complete the build process and return the built ECSpresso instance
     */
-    build(): ECSpresso<C, E, FinalizeBuiltinResources<R, A, S, [AssetGroupNames] extends [never] ? string : AssetGroupNames>, A, S, [
+    build(): ECSpresso<FinalizeBuiltinResources<Cfg, [AssetGroupNames] extends [never] ? string : AssetGroupNames>, [
         Labels
     ] extends [never] ? string : Labels, [
         Groups