ecspresso 0.10.2 → 0.11.0

package/dist/bundles/tween.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Tween Bundle for ECSpresso
+ *
+ * Declarative property animation within the ECS. Tween any numeric component
+ * field over time with standard easing functions, sequences, and completion events.
+ */
+import { Bundle } from 'ecspresso';
+import type { SystemPhase, ComponentsOfWorld, EventsOfWorld } from 'ecspresso';
+import { type EasingFn } from '../utils/easing';
+/**
+ * Data structure published when a tween completes.
+ * Use this type when defining tween completion events in your EventTypes interface.
+ */
+export interface TweenEventData {
+    /** The entity ID the tween belongs to */
+    entityId: number;
+    /** Number of steps in the tween */
+    stepCount: number;
+}
+/**
+ * Extracts event names from EventTypes that have TweenEventData as their payload.
+ * This ensures only compatible events can be used with tween.onComplete.
+ * Uses `keyof EventTypes & string` to exclude number/symbol keys, ensuring the
+ * result is always a string subtype and Tween<E> is assignable to Tween<Record<string, any>>.
+ */
+export type TweenEventName<EventTypes extends Record<string, any>> = {
+    [K in keyof EventTypes & string]: EventTypes[K] extends TweenEventData ? K : never;
+}[keyof EventTypes & string];
+export interface TweenTarget {
+    /** Component name on the entity */
+    component: string;
+    /** Pre-split field path (e.g., ['position', 'x']) */
+    path: readonly string[];
+    /** Starting value. null = resolve from current value on first tick */
+    from: number | null;
+    /** Target value */
+    to: number;
+}
+export interface TweenStep {
+    targets: TweenTarget[];
+    duration: number;
+    easing: EasingFn;
+}
+export interface Tween<EventTypes extends Record<string, any> = Record<string, any>> {
+    steps: TweenStep[];
+    currentStep: number;
+    elapsed: number;
+    loop: LoopMode;
+    totalLoops: number;
+    completedLoops: number;
+    direction: 1 | -1;
+    state: 'pending' | 'active' | 'complete';
+    onComplete?: TweenEventName<EventTypes>;
+    justFinished: boolean;
+}
+export type LoopMode = 'once' | 'loop' | 'yoyo';
+/**
+ * Component types provided by the tween bundle.
+ */
+export interface TweenComponentTypes<EventTypes extends Record<string, any> = Record<string, any>> {
+    tween: Tween<EventTypes>;
+}
+export interface TweenBundleOptions<G extends string = 'tweens'> {
+    /** System group name (default: 'tweens') */
+    systemGroup?: G;
+    /** Priority for tween update system (default: 0) */
+    priority?: number;
+    /** Execution phase (default: 'update') */
+    phase?: SystemPhase;
+}
+export interface TweenOptions<EventTypes extends Record<string, any> = Record<string, any>> {
+    /** Explicit starting value (default: captures current value on first tick) */
+    from?: number;
+    /** Easing function (default: linear) */
+    easing?: EasingFn;
+    /** Loop mode (default: 'once') */
+    loop?: LoopMode;
+    /** Number of loops. -1 = infinite (default: 1) */
+    loops?: number;
+    /** Event name to publish when tween completes */
+    onComplete?: TweenEventName<EventTypes>;
+}
+/**
+ * Create a single-target tween component.
+ *
+ * @param component Component name on the entity
+ * @param field Field path (dot-separated for nested, e.g. 'position.x')
+ * @param to Target value
+ * @param duration Duration in seconds
+ * @param options Optional configuration
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createTween<EventTypes extends Record<string, any> = Record<string, any>>(component: string, field: string, to: number, duration: number, options?: TweenOptions<EventTypes>): Pick<TweenComponentTypes<EventTypes>, 'tween'>;
+export interface TweenSequenceStepInput {
+    targets: ReadonlyArray<{
+        component: string;
+        field: string;
+        to: number;
+        from?: number;
+    }>;
+    duration: number;
+    easing?: EasingFn;
+}
+export interface TweenSequenceOptions<EventTypes extends Record<string, any> = Record<string, any>> {
+    /** Loop mode (default: 'once') */
+    loop?: LoopMode;
+    /** Number of loops. -1 = infinite (default: 1) */
+    loops?: number;
+    /** Event name to publish when tween completes */
+    onComplete?: TweenEventName<EventTypes>;
+}
+/**
+ * Create a multi-step tween sequence. Each step can have parallel targets.
+ *
+ * @param steps Array of step definitions
+ * @param options Optional configuration
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createTweenSequence<EventTypes extends Record<string, any> = Record<string, any>>(steps: ReadonlyArray<TweenSequenceStepInput>, options?: TweenSequenceOptions<EventTypes>): Pick<TweenComponentTypes<EventTypes>, 'tween'>;
+type AnyECSpresso = import('ecspresso').default<any, any, any, any, any, any, any>;
+/**
+ * Recursively produce a union of dot-separated paths that resolve to `number`
+ * within type T. Depth-limited to 4 levels to prevent TS recursion errors.
+ *
+ * @example
+ * NumericPaths<{ x: number; y: number }> // 'x' | 'y'
+ * NumericPaths<{ position: { x: number }; rotation: number }> // 'position.x' | 'rotation'
+ */
+export type NumericPaths<T, Depth extends readonly unknown[] = []> = Depth['length'] extends 4 ? never : T extends readonly unknown[] ? never : T extends Record<string, unknown> ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends number ? K : NonNullable<T[K]> extends readonly unknown[] ? never : NonNullable<T[K]> extends Record<string, unknown> ? `${K}.${NumericPaths<NonNullable<T[K]>, [...Depth, unknown]>}` : never;
+}[keyof T & string] : never;
+/**
+ * Discriminated union over component names: each variant constrains `field`
+ * to the numeric paths of that component. TS narrows inline object literals
+ * by `component` discriminant — zero runtime overhead.
+ */
+export type TypedTweenTargetInput<C extends Record<string, any>> = {
+    [K in keyof C & string]: {
+        component: K;
+        field: NumericPaths<C[K]>;
+        to: number;
+        from?: number;
+    };
+}[keyof C & string];
+export interface TypedTweenSequenceStepInput<C extends Record<string, any>> {
+    targets: ReadonlyArray<TypedTweenTargetInput<C>>;
+    duration: number;
+    easing?: EasingFn;
+}
+export interface TweenKit<W extends AnyECSpresso, G extends string = 'tweens'> {
+    bundle: Bundle<TweenComponentTypes<EventsOfWorld<W>>, EventsOfWorld<W>, {}, {}, {}, 'tween-update', G>;
+    createTween: <K extends keyof ComponentsOfWorld<W> & string>(component: K, field: NumericPaths<ComponentsOfWorld<W>[K]>, to: number, duration: number, options?: TweenOptions<EventsOfWorld<W>>) => Pick<TweenComponentTypes<EventsOfWorld<W>>, 'tween'>;
+    createTweenSequence: (steps: ReadonlyArray<TypedTweenSequenceStepInput<ComponentsOfWorld<W>>>, options?: TweenSequenceOptions<EventsOfWorld<W>>) => Pick<TweenComponentTypes<EventsOfWorld<W>>, 'tween'>;
+}
+/**
+ * Create a typed tween kit that captures the world type W.
+ *
+ * The returned `createTween` and `createTweenSequence` validate component names
+ * and field paths at compile time. Runtime behavior is identical to the standalone
+ * functions — all validation is type-level only.
+ *
+ * @template W - Concrete ECS world type (e.g. `typeof ecs`)
+ * @template G - System group name (default: 'tweens')
+ * @param options - Optional bundle configuration (same as createTweenBundle)
+ * @returns A kit object with bundle, createTween, createTweenSequence
+ *
+ * @example
+ * ```typescript
+ * const kit = createTweenKit<typeof ecs>();
+ * // or: const kit = createTweenKit<ECS>();
+ *
+ * const ecs = ECSpresso.create()
+ *   .withBundle(kit.bundle)
+ *   .build();
+ *
+ * // Type-safe: 'position' must be a component, 'x' must be a numeric field
+ * kit.createTween('position', 'x', 100, 1);
+ *
+ * // Type error: 'z' is not a field of position
+ * kit.createTween('position', 'z', 100, 1);
+ * ```
+ */
+export declare function createTweenKit<W extends AnyECSpresso, G extends string = 'tweens'>(options?: TweenBundleOptions<G>): TweenKit<W, G>;
+/**
+ * Create a tween bundle for ECSpresso.
+ *
+ * This bundle provides:
+ * - Tween system that processes all tween components each frame
+ * - Support for single-field, multi-target, and multi-step sequences
+ * - 31 standard easing functions
+ * - Loop modes: once, loop, yoyo
+ * - `justFinished` flag for one-frame completion detection
+ * - `onComplete` event publishing
+ * - Change detection via markChanged
+ */
+export declare function createTweenBundle<EventTypes extends Record<string, any> = Record<string, any>, G extends string = 'tweens'>(options?: TweenBundleOptions<G>): Bundle<TweenComponentTypes<EventTypes>, EventTypes, {}, {}, {}, 'tween-update', G>;
+export {};

package/dist/command-buffer.d.ts

@@ -1,5 +1,5 @@
 import type ECSpresso from './ecspresso';
-import type { RemoveEntityOptions } from './types';
+import type { Entity, RemoveEntityOptions } from './types';
 /**
  * CommandBuffer queues structural changes to be executed later.
  * This prevents ordering issues when modifying entities during system execution.
@@ -16,27 +16,27 @@ import type { 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> = {}> {
+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> = {}> {
     private commands;
     /**
      * Queue an entity removal command
-     * @param entityId The ID of the entity to remove
+     * @param entityOrId The entity or entity ID to remove
      * @param options Optional removal options (cascade, etc.)
      */
-    removeEntity(entityId: number, options?: RemoveEntityOptions): void;
+    removeEntity(entityOrId: number | Entity<ComponentTypes>, options?: RemoveEntityOptions): void;
     /**
      * Queue a component addition command
-     * @param entityId The ID of the entity
+     * @param entityOrId The entity or entity ID
      * @param componentName The name of the component to add
      * @param componentValue The component data
      */
-    addComponent<K extends keyof ComponentTypes>(entityId: number, componentName: K, componentValue: ComponentTypes[K]): void;
+    addComponent<K extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: K, componentValue: ComponentTypes[K]): void;
     /**
      * Queue a component removal command
-     * @param entityId The ID of the entity
+     * @param entityOrId The entity or entity ID
      * @param componentName The name of the component to remove
      */
-    removeComponent<K extends keyof ComponentTypes>(entityId: number, componentName: K): void;
+    removeComponent<K extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: K): void;
     /**
      * Queue an entity spawn command
      * @param components The initial components for the new entity
@@ -47,43 +47,43 @@ export default class CommandBuffer<ComponentTypes extends Record<string, any> =
     }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
     /**
      * Queue a child entity spawn command
-     * @param parentId The ID of the parent entity
+     * @param parentOrId The parent entity or entity ID
      * @param components The initial components for the new child entity
      */
     spawnChild<T extends {
         [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
+    }>(parentOrId: number | Entity<ComponentTypes>, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
     /**
      * Queue multiple component additions
-     * @param entityId The ID of the entity
+     * @param entityOrId The entity or entity ID
      * @param components Object with component names as keys and component data as values
      */
     addComponents<T extends {
         [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(entityId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
+    }>(entityOrId: number | Entity<ComponentTypes>, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): void;
     /**
      * Queue a parent assignment command
-     * @param childId The ID of the child entity
-     * @param parentId The ID of the parent entity
+     * @param childOrId The child entity or entity ID
+     * @param parentOrId The parent entity or entity ID
      */
-    setParent(childId: number, parentId: number): void;
+    setParent(childOrId: number | Entity<ComponentTypes>, parentOrId: number | Entity<ComponentTypes>): void;
     /**
      * Queue a markChanged command
-     * @param entityId The ID of the entity
+     * @param entityOrId The entity or entity ID
      * @param componentName The component to mark as changed
      */
-    markChanged<K extends keyof ComponentTypes>(entityId: number, componentName: K): void;
+    markChanged<K extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: K): void;
     /**
      * Queue a parent removal command
-     * @param childId The ID of the child entity
+     * @param childOrId The child entity or entity ID
      */
-    removeParent(childId: number): void;
+    removeParent(childOrId: number | Entity<ComponentTypes>): 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<AssetTypes extends Record<string, any> = {}, ScreenStates extends Record<string, any> = {}>(ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
+    playback(ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
     /**
      * Clear all queued commands without executing them
      */

package/dist/ecspresso-builder.d.ts

@@ -0,0 +1,165 @@
+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 { 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
+ * 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>;
+});
+/**
+    * Builder class for ECSpresso that provides fluent type-safe bundle installation.
+    * Handles type checking during build process to ensure type safety.
+*/
+export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}, 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> {
+    /** The ECSpresso instance being built*/
+    private ecspresso;
+    /** Asset configurator for collecting asset definitions */
+    private assetConfigurator;
+    /** Screen configurator for collecting screen definitions */
+    private screenConfigurator;
+    /** Pending resources to add during build */
+    private pendingResources;
+    /** Pending dispose callbacks to register during build */
+    private pendingDisposeCallbacks;
+    /** Pending required component registrations to apply during build */
+    private pendingRequiredComponents;
+    /** 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.
+    */
+    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>;
+    /**
+        * Add a subsequent bundle with type checking.
+        * This overload enforces bundle type compatibility.
+    */
+    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>, 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>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Add a resource during ECSpresso construction
+     * @param key The resource key
+     * @param resource The resource value, factory function, or factory with dependencies/disposal
+     * @returns This builder with updated resource types
+     *
+     * @example
+     * ```typescript
+     * ECSpresso.create<Components, Events, Resources>()
+     *   .withResource('config', { debug: true })
+     *   .withResource('counter', () => 42)
+     *   .withResource('derived', {
+     *     dependsOn: ['base'],
+     *     factory: (ecs) => ecs.getResource('base') * 2,
+     *     onDispose: (value) => console.log('Disposed:', value)
+     *   })
+     *   .build();
+     * ```
+     */
+    withResource<K extends string, V>(key: K, resource: V | ((context: 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>;
+    /**
+     * Register a dispose callback for a component type during build.
+     * Called when a component is removed (explicit removal, entity destruction, or replacement).
+     * @param componentName The component type to register disposal for
+     * @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;
+    /**
+     * Register a required component relationship during build.
+     * When an entity gains `trigger`, the `required` component is auto-added
+     * (using `factory` for the default value) if not already present.
+     * @param trigger The component whose presence triggers auto-addition
+     * @param required The component to auto-add
+     * @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;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Configure the fixed timestep interval for the fixedUpdate phase.
+     * @param dt The fixed timestep in seconds (e.g., 1/60 for 60Hz physics)
+     * @returns This builder for method chaining
+     */
+    withFixedTimestep(dt: number): this;
+    /**
+     * 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>;
+    /**
+        * 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, [
+        Labels
+    ] extends [never] ? string : Labels, [
+        Groups
+    ] extends [never] ? string : Groups, [
+        AssetGroupNames
+    ] extends [never] ? string : AssetGroupNames, [
+        ReactiveQueryNames
+    ] extends [never] ? string : ReactiveQueryNames>;
+}
+export {};