ecspresso 0.5.0 → 0.7.0

package/dist/bundles/utils/timers.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Timer Bundle for ECSpresso
+ *
+ * Provides ECS-native timers following the "data, not callbacks" philosophy.
+ * Timers are components processed each frame, automatically cleaned up when entities are removed.
+ */
+import Bundle from '../../bundle';
+/**
+ * Data structure published when a timer completes.
+ * Use this type when defining timer completion events in your EventTypes interface.
+ *
+ * @example
+ * ```typescript
+ * interface Events {
+ *   hideMessage: TimerEventData;
+ *   spawnWave: TimerEventData;
+ * }
+ * ```
+ */
+export interface TimerEventData {
+    /** The entity ID that the timer belongs to */
+    entityId: number;
+    /** The timer's configured duration in seconds */
+    duration: number;
+    /** The actual elapsed time (may exceed duration slightly) */
+    elapsed: number;
+}
+/**
+ * Extracts event names from EventTypes that have TimerEventData as their payload.
+ * This ensures only compatible events can be used with timer.onComplete.
+ */
+export type TimerEventName<EventTypes extends Record<string, any>> = {
+    [K in keyof EventTypes]: EventTypes[K] extends TimerEventData ? K : never;
+}[keyof EventTypes];
+/**
+ * Timer component data structure.
+ * Use `justFinished` to detect timer completion in your systems.
+ *
+ * @template EventTypes The event types from your ECS
+ */
+export interface Timer<EventTypes extends Record<string, any>> {
+    /** Time accumulated so far (seconds) */
+    elapsed: number;
+    /** Target duration (seconds) */
+    duration: number;
+    /** Whether timer repeats after completion */
+    repeat: boolean;
+    /** Whether timer is currently running */
+    active: boolean;
+    /** True for one frame after timer completes */
+    justFinished: boolean;
+    /** Optional event name to publish when timer completes. Must be an event with TimerEventData payload. */
+    onComplete?: TimerEventName<EventTypes>;
+}
+/**
+ * Component types provided by the timer bundle.
+ * Extend your component types with this interface.
+ *
+ * @template EventTypes The event types from your ECS
+ *
+ * @example
+ * ```typescript
+ * interface GameComponents extends TimerComponentTypes<GameEvents> {
+ *   velocity: { x: number; y: number };
+ *   player: true;
+ * }
+ * ```
+ */
+export interface TimerComponentTypes<EventTypes extends Record<string, any>> {
+    timer: Timer<EventTypes>;
+}
+/**
+ * Configuration options for the timer bundle.
+ */
+export interface TimerBundleOptions {
+    /** System group name (default: 'timers') */
+    systemGroup?: string;
+    /** Priority for timer update system (default: 0) */
+    priority?: number;
+}
+/**
+ * Options for timer creation
+ *
+ * @template EventTypes The event types from your ECS
+ */
+export interface TimerOptions<EventTypes extends Record<string, any>> {
+    /** Event name to publish when timer completes. Must be an event with TimerEventData payload. */
+    onComplete?: TimerEventName<EventTypes>;
+}
+/**
+ * Create a one-shot timer that fires once after the specified duration.
+ *
+ * @template EventTypes The event types from your ECS (must be explicitly provided)
+ * @param duration Duration in seconds until the timer completes
+ * @param options Optional configuration including event name
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * // Timer without event
+ * ecs.spawn({
+ *   ...createTimer<GameEvents>(2),
+ *   explosion: true,
+ * });
+ *
+ * // Timer that publishes an event on completion
+ * ecs.spawn({
+ *   ...createTimer<GameEvents>(1.5, { onComplete: 'hideMessage' }),
+ * });
+ * ```
+ */
+export declare function createTimer<EventTypes extends Record<string, any>>(duration: number, options?: TimerOptions<EventTypes>): Pick<TimerComponentTypes<EventTypes>, 'timer'>;
+/**
+ * Create a repeating timer that fires every `duration` seconds.
+ *
+ * @template EventTypes The event types from your ECS (must be explicitly provided)
+ * @param duration Duration in seconds between each timer completion
+ * @param options Optional configuration including event name
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * // Timer without event
+ * ecs.spawn({
+ *   ...createRepeatingTimer<GameEvents>(5),
+ *   spawner: true,
+ * });
+ *
+ * // Repeating timer that publishes an event each cycle
+ * ecs.spawn({
+ *   ...createRepeatingTimer<GameEvents>(3, { onComplete: 'spawnWave' }),
+ * });
+ * ```
+ */
+export declare function createRepeatingTimer<EventTypes extends Record<string, any>>(duration: number, options?: TimerOptions<EventTypes>): Pick<TimerComponentTypes<EventTypes>, 'timer'>;
+/**
+ * Create a timer bundle for ECSpresso.
+ *
+ * This bundle provides:
+ * - Timer update system that processes all timer components each frame
+ * - `justFinished` flag pattern for one-frame completion detection
+ * - Automatic cleanup when entities are removed
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso
+ *   .create<Components, Events, Resources>()
+ *   .withBundle(createTimerBundle())
+ *   .build();
+ *
+ * // Spawn entity with timer
+ * ecs.spawn({
+ *   ...createRepeatingTimer(5),
+ *   spawner: true,
+ * });
+ *
+ * // React to timer completion in a system
+ * ecs.addSystem('spawn-on-timer')
+ *   .addQuery('spawners', { with: ['timer', 'spawner'] })
+ *   .setProcess((queries, _dt, ecs) => {
+ *     for (const { components } of queries.spawners) {
+ *       if (components.timer.justFinished) {
+ *         ecs.spawn({ enemy: true });
+ *       }
+ *     }
+ *   });
+ * ```
+ */
+export declare function createTimerBundle<EventTypes extends Record<string, any>>(options?: TimerBundleOptions): Bundle<TimerComponentTypes<EventTypes>, EventTypes, {}>;

package/dist/bundles/utils/timers.js

@@ -0,0 +1,4 @@
+var $=Object.create;var{getPrototypeOf:G,defineProperty:Z,getOwnPropertyNames:q}=Object;var z=Object.prototype.hasOwnProperty;var P=(j,x,F)=>{F=j!=null?$(G(j)):{};let K=x||!j||!j.__esModule?Z(F,"default",{value:j,enumerable:!0}):F;for(let H of q(j))if(!z.call(K,H))Z(K,H,{get:()=>j[H],enumerable:!0});return K};var W=((j)=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(j,{get:(x,F)=>(typeof require<"u"?require:x)[F]}):j)(function(j){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+j+'" is not supported')});class Y{_label;_ecspresso;_bundle;queries={};processFunction;detachFunction;initializeFunction;eventHandlers;_priority=0;_isRegistered=!1;_groups=[];_inScreens;_excludeScreens;_requiredAssets;constructor(j,x=null,F=null){this._label=j;this._ecspresso=x;this._bundle=F}get label(){return this._label}get bundle(){return this._bundle}get ecspresso(){return this._ecspresso}_autoRegister(){if(this._isRegistered||!this._ecspresso)return;let j=this._buildSystemObject();X(j,this._ecspresso),this._isRegistered=!0}_buildSystemObject(){return this._createSystemObject()}_createSystemObject(){let j={label:this._label,entityQueries:this.queries,priority:this._priority};if(this.processFunction)j.process=this.processFunction;if(this.detachFunction)j.onDetach=this.detachFunction;if(this.initializeFunction)j.onInitialize=this.initializeFunction;if(this.eventHandlers)j.eventHandlers=this.eventHandlers;if(this._groups.length>0)j.groups=[...this._groups];if(this._inScreens)j.inScreens=this._inScreens;if(this._excludeScreens)j.excludeScreens=this._excludeScreens;if(this._requiredAssets)j.requiredAssets=this._requiredAssets;return j}setPriority(j){return this._priority=j,this}inGroup(j){if(!this._groups.includes(j))this._groups.push(j);return this}inScreens(j){return this._inScreens=[...j],this}excludeScreens(j){return this._excludeScreens=[...j],this}requiresAssets(j){return this._requiredAssets=[...j],this}addQuery(j,x){let F=this;return F.queries={...this.queries,[j]:x},F}setProcess(j){return this.processFunction=j,this}registerAndContinue(){if(!this._ecspresso)throw Error(`Cannot register system '${this._label}': SystemBuilder is not attached to an ECSpresso instance. Use Bundle.addSystem() or ECSpresso.addSystem() instead.`);return this._autoRegister(),this._ecspresso}and(){if(this._ecspresso)return this._autoRegister(),this._ecspresso;if(this._bundle)return this._bundle;throw Error(`Cannot use and() on system '${this._label}': not attached to ECSpresso or Bundle.`)}setOnDetach(j){return this.detachFunction=j,this}setOnInitialize(j){return this.initializeFunction=j,this}setEventHandlers(j){return this.eventHandlers=j,this}build(j){let x=this._createSystemObject();if(this._ecspresso)X(x,this._ecspresso);if(j)X(x,j);return this}}function X(j,x){x._registerSystem(j)}function D(j,x){return new Y(j,x)}function _(j,x){return new Y(j,null,x)}function C(){return`bundle_${Date.now().toString(36)}_${Math.random().toString(36).substring(2,9)}`}class U{_systems=[];_resources=new Map;_assets=new Map;_assetGroups=new Map;_screens=new Map;_id;constructor(j){this._id=j||C()}get id(){return this._id}set id(j){this._id=j}addSystem(j){if(typeof j==="string"){let x=_(j,this);return this._systems.push(x),x}else return this._systems.push(j),j}addResource(j,x){return this._resources.set(j,x),this}addAsset(j,x,F){return this._assets.set(j,{loader:x,eager:F?.eager??!0,group:F?.group}),this}addAssetGroup(j,x){let F=new Map;for(let[K,H]of Object.entries(x))F.set(K,H),this._assets.set(K,{loader:H,eager:!1,group:j});return this._assetGroups.set(j,F),this}addScreen(j,x){return this._screens.set(j,x),this}getAssets(){return new Map(this._assets)}getScreens(){return new Map(this._screens)}_setResource(j,x){this._resources.set(j,x)}_setAsset(j,x){this._assets.set(j,x)}_setScreen(j,x){this._screens.set(j,x)}getSystems(){return this._systems.map((j)=>j.build())}registerSystemsWithEcspresso(j){for(let x of this._systems)x.build(j)}getResources(){return new Map(this._resources)}getResource(j){return this._resources.get(j)}getSystemBuilders(){return[...this._systems]}hasResource(j){return this._resources.has(j)}}function O(j,...x){if(x.length===0)return new U(j);let F=new U(j);for(let K of x){for(let H of K.getSystemBuilders())F.addSystem(H);for(let[H,M]of K.getResources().entries())F._setResource(H,M);for(let[H,M]of K.getAssets().entries())F._setAsset(H,M);for(let[H,M]of K.getScreens().entries())F._setScreen(H,M)}return F}function T(j,x){return{timer:{elapsed:0,duration:j,repeat:!1,active:!0,justFinished:!1,onComplete:x?.onComplete}}}function S(j,x){return{timer:{elapsed:0,duration:j,repeat:!0,active:!0,justFinished:!1,onComplete:x?.onComplete}}}function k(j){let{systemGroup:x="timers",priority:F=0}=j??{},K=new U("timers");K.addSystem("timer-update").setPriority(F).inGroup(x).addQuery("timers",{with:["timer"]}).setProcess((M,V,Q)=>{for(let R of M.timers){let{timer:J}=R.components;if(J.justFinished=!1,!J.active)continue;if(J.elapsed+=V,J.elapsed<J.duration)continue;if(J.repeat)while(J.elapsed>=J.duration)J.justFinished=!0,H(Q,R.id,J),J.elapsed-=J.duration;else J.justFinished=!0,H(Q,R.id,J),J.active=!1,Q.commands.removeEntity(R.id)}}).and();function H(M,V,Q){if(!Q.onComplete)return;let R={entityId:V,duration:Q.duration,elapsed:Q.elapsed};M.eventBus.publish(Q.onComplete,R)}return K}export{k as createTimerBundle,T as createTimer,S as createRepeatingTimer};
+
+//# debugId=8A5D1E808447563C64756E2164756E21
+//# sourceMappingURL=timers.js.map

package/dist/bundles/utils/timers.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/system-builder.ts", "../src/bundle.ts", "../src/bundles/utils/timers.ts"],
+  "sourcesContent": [
+    "import Bundle from \"./bundle\";\nimport ECSpresso from \"./ecspresso\";\nimport type { FilteredEntity, System } from \"./types\";\n\n/**\n * Builder class for creating type-safe ECS Systems with proper query inference\n */\nexport class SystemBuilder<\n\tComponentTypes extends Record<string, any> = Record<string, any>,\n\tEventTypes extends Record<string, any> = Record<string, any>,\n\tResourceTypes extends Record<string, any> = Record<string, any>,\n\tQueries extends Record<string, QueryDefinition<ComponentTypes>> = {},\n> {\n\tprivate queries: Queries = {} as Queries;\n\tprivate processFunction?: ProcessFunction<ComponentTypes, EventTypes, ResourceTypes, Queries>;\n\tprivate detachFunction?: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes>;\n\tprivate initializeFunction?: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes>;\n\tprivate eventHandlers?: {\n\t\t[EventName in keyof EventTypes]?: {\n\t\t\thandler(\n\t\t\t\tdata: EventTypes[EventName],\n\t\t\t\tecs: ECSpresso<\n\t\t\t\t\tComponentTypes,\n\t\t\t\t\tEventTypes,\n\t\t\t\t\tResourceTypes\n\t\t\t\t>,\n\t\t\t): void;\n\t\t};\n\t};\n\tprivate _priority = 0; // Default priority is 0\n\tprivate _isRegistered = false; // Track if system has been auto-registered\n\tprivate _groups: string[] = [];\n\tprivate _inScreens?: string[];\n\tprivate _excludeScreens?: string[];\n\tprivate _requiredAssets?: string[];\n\n\tconstructor(\n\t\tprivate _label: string,\n\t\tprivate _ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes> | null = null,\n\t\tprivate _bundle: Bundle<ComponentTypes, EventTypes, ResourceTypes> | null = null,\n\t) {}\n\n\tget label() {\n\t\treturn this._label;\n\t}\n\n\t/**\n\t * Returns the associated bundle if one was provided in the constructor\n\t */\n\tget bundle() {\n\t\treturn this._bundle;\n\t}\n\n\t/**\n\t * Returns the associated ECSpresso instance if one was provided in the constructor\n\t */\n\tget ecspresso() {\n\t\treturn this._ecspresso;\n\t}\n\n\t/**\n\t * Auto-register this system with its ECSpresso instance if not already registered\n\t * @private\n\t */\n\tprivate _autoRegister(): void {\n\t\tif (this._isRegistered || !this._ecspresso) return;\n\t\t\n\t\tconst system = this._buildSystemObject();\n\t\tregisterSystemWithEcspresso(system, this._ecspresso);\n\t\tthis._isRegistered = true;\n\t}\n\n\t/**\n\t * Create the system object without registering it\n\t * @private\n\t */\n\tprivate _buildSystemObject(): System<ComponentTypes, any, any, EventTypes, ResourceTypes> {\n\t\treturn this._createSystemObject();\n\t}\n\n\t/**\n\t * Create a system object with all configured properties\n\t * @private\n\t */\n\tprivate _createSystemObject(): System<ComponentTypes, any, any, EventTypes, ResourceTypes> {\n\t\tconst system: System<ComponentTypes, any, any, EventTypes, ResourceTypes> = {\n\t\t\tlabel: this._label,\n\t\t\tentityQueries: this.queries,\n\t\t\tpriority: this._priority,\n\t\t};\n\n\t\tif (this.processFunction) {\n\t\t\tsystem.process = this.processFunction;\n\t\t}\n\n\t\tif (this.detachFunction) {\n\t\t\tsystem.onDetach = this.detachFunction;\n\t\t}\n\n\t\tif (this.initializeFunction) {\n\t\t\tsystem.onInitialize = this.initializeFunction;\n\t\t}\n\n\t\tif (this.eventHandlers) {\n\t\t\tsystem.eventHandlers = this.eventHandlers;\n\t\t}\n\n\t\tif (this._groups.length > 0) {\n\t\t\tsystem.groups = [...this._groups];\n\t\t}\n\n\t\tif (this._inScreens) {\n\t\t\tsystem.inScreens = this._inScreens;\n\t\t}\n\n\t\tif (this._excludeScreens) {\n\t\t\tsystem.excludeScreens = this._excludeScreens;\n\t\t}\n\n\t\tif (this._requiredAssets) {\n\t\t\tsystem.requiredAssets = this._requiredAssets;\n\t\t}\n\n\t\treturn system;\n\t}\n\n\t// TODO: Should this be a setter?\n\t/**\n\t * Set the priority of this system. Systems with higher priority values\n\t * execute before those with lower values. Systems with the same priority\n\t * execute in the order they were registered.\n\t * @param priority The priority value (default: 0)\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\tsetPriority(priority: number): this {\n\t\tthis._priority = priority;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Add this system to a group. Systems can belong to multiple groups.\n\t * When any group a system belongs to is disabled, the system will be skipped.\n\t * @param groupName The name of the group to add the system to\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\tinGroup(groupName: string): this {\n\t\tif (!this._groups.includes(groupName)) {\n\t\t\tthis._groups.push(groupName);\n\t\t}\n\t\treturn this;\n\t}\n\n\t/**\n\t * Restrict this system to only run in specified screens.\n\t * System will be skipped during update() when the current screen\n\t * is not in this list.\n\t * @param screens Array of screen names where this system should run\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\tinScreens(screens: ReadonlyArray<string>): this {\n\t\tthis._inScreens = [...screens];\n\t\treturn this;\n\t}\n\n\t/**\n\t * Exclude this system from running in specified screens.\n\t * System will be skipped during update() when the current screen\n\t * is in this list.\n\t * @param screens Array of screen names where this system should NOT run\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\texcludeScreens(screens: ReadonlyArray<string>): this {\n\t\tthis._excludeScreens = [...screens];\n\t\treturn this;\n\t}\n\n\t/**\n\t * Require specific assets to be loaded for this system to run.\n\t * System will be skipped during update() if any required asset\n\t * is not loaded.\n\t * @param assets Array of asset keys that must be loaded\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\trequiresAssets(assets: ReadonlyArray<string>): this {\n\t\tthis._requiredAssets = [...assets];\n\t\treturn this;\n\t}\n\n\t/**\n\t * Add a query definition to the system\n\t */\n\taddQuery<\n\t\tQueryName extends string,\n\t\tWithComponents extends keyof ComponentTypes,\n\t\tWithoutComponents extends keyof ComponentTypes = never,\n\t\tNewQueries extends Queries & Record<QueryName, QueryDefinition<ComponentTypes, WithComponents, WithoutComponents>> =\n\t\t\tQueries & Record<QueryName, QueryDefinition<ComponentTypes, WithComponents, WithoutComponents>>\n\t>(\n\t\tname: QueryName,\n\t\tdefinition: {\n\t\t\twith: ReadonlyArray<WithComponents>;\n\t\t\twithout?: ReadonlyArray<WithoutComponents>;\n\t\t}\n\t): this extends SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, Queries>\n\t\t? SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, NewQueries>\n\t\t: this extends SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, Queries>\n\t\t\t? SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, NewQueries>\n\t\t\t: SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, NewQueries> {\n\t\t// Cast is needed because TypeScript can't preserve the type information\n\t\t// when modifying an object property\n\t\tconst newBuilder = this as any;\n\t\tnewBuilder.queries = {\n\t\t\t...this.queries,\n\t\t\t[name]: definition,\n\t\t};\n\t\treturn newBuilder;\n\t}\n\n\t/**\n\t * Set the system's process function that runs each update\n\t * @param process Function to process entities matching the system's queries each update\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\tsetProcess(\n\t\tprocess: ProcessFunction<ComponentTypes, EventTypes, ResourceTypes, Queries>\n\t): this {\n\t\tthis.processFunction = process;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Register this system with its ECSpresso instance and return the ECSpresso for chaining\n\t * This enables seamless method chaining: .registerAndContinue().addSystem(...)\n\t * @returns ECSpresso instance if attached to one, otherwise throws an error\n\t */\n\tregisterAndContinue(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes> {\n\t\tif (!this._ecspresso) {\n\t\t\tthrow new Error(`Cannot register system '${this._label}': SystemBuilder is not attached to an ECSpresso instance. Use Bundle.addSystem() or ECSpresso.addSystem() instead.`);\n\t\t}\n\t\t\n\t\tthis._autoRegister();\n\t\treturn this._ecspresso;\n\t}\n\n\t/**\n\t * Complete this system and return the parent container for seamless chaining\n\t * - For ECSpresso-attached builders: registers the system and returns ECSpresso\n\t * - For Bundle-attached builders: returns the Bundle\n\t * This method is typed via the specialized interfaces (SystemBuilderWithEcspresso, SystemBuilderWithBundle)\n\t */\n\tand(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes> | Bundle<ComponentTypes, EventTypes, ResourceTypes> {\n\t\tif (this._ecspresso) {\n\t\t\tthis._autoRegister();\n\t\t\treturn this._ecspresso;\n\t\t}\n\n\t\tif (this._bundle) {\n\t\t\treturn this._bundle;\n\t\t}\n\n\t\tthrow new Error(`Cannot use and() on system '${this._label}': not attached to ECSpresso or Bundle.`);\n\t}\n\n\t/**\n\t * Set the onDetach lifecycle hook\n\t * Called when the system is removed from the ECS\n\t * @param onDetach Function to run when this system is detached from the ECS\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\tsetOnDetach(\n\t\tonDetach: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes>\n\t): this {\n\t\tthis.detachFunction = onDetach;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Set the onInitialize lifecycle hook\n\t * Called when the system is initialized via ECSpresso.initialize() method\n\t * @param onInitialize Function to run when this system is initialized\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\tsetOnInitialize(\n\t\tonInitialize: LifecycleFunction<ComponentTypes, EventTypes, ResourceTypes>\n\t): this {\n\t\tthis.initializeFunction = onInitialize;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Set event handlers for the system\n\t * These handlers will be automatically subscribed when the system is attached\n\t * @param handlers Object mapping event names to handler functions\n\t * @returns This SystemBuilder instance for method chaining\n\t */\n\tsetEventHandlers(\n\t\thandlers: {\n\t\t\t[EventName in keyof EventTypes]?: {\n\t\t\t\thandler(\n\t\t\t\t\tdata: EventTypes[EventName],\n\t\t\t\t\tecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>\n\t\t\t\t): void;\n\t\t\t};\n\t\t}\n\t): this {\n\t\tthis.eventHandlers = handlers;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Build the final system object\n\t */\n\tbuild(ecspresso?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) {\n\t\tconst system = this._createSystemObject();\n\n\t\tif (this._ecspresso) {\n\t\t\tregisterSystemWithEcspresso(system, this._ecspresso);\n\t\t}\n\n\t\tif(ecspresso) {\n\t\t\tregisterSystemWithEcspresso(system, ecspresso);\n\t\t}\n\n\t\treturn this;\n\t}\n}\n\n/**\n * Helper function to register a system with an ECSpresso instance\n * This handles attaching the system and setting up event handlers\n * @internal Used by SystemBuilder and Bundle\n */\nexport function registerSystemWithEcspresso<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>\n>(\n\tsystem: System<ComponentTypes, any, any, EventTypes, ResourceTypes>,\n\tecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>\n) {\n\t// Use the new internal registration method instead of direct property access\n\tecspresso._registerSystem(system);\n}\n\n// Helper type definitions\ntype QueryDefinition<\n\tComponentTypes,\n\tWithComponents extends keyof ComponentTypes = any,\n\tWithoutComponents extends keyof ComponentTypes = any,\n> = {\n\twith: ReadonlyArray<WithComponents>;\n\twithout?: ReadonlyArray<WithoutComponents>;\n};\n\ntype QueryResults<\n\tComponentTypes,\n\tQueries extends Record<string, QueryDefinition<ComponentTypes>>,\n> = {\n\t[QueryName in keyof Queries]: QueryName extends string\n\t\t? FilteredEntity<\n\t\t\tComponentTypes,\n\t\t\tQueries[QueryName] extends QueryDefinition<ComponentTypes, infer W, any> ? W : never,\n\t\t\tQueries[QueryName] extends QueryDefinition<ComponentTypes, any, infer WO> ? WO : never\n\t\t>[]\n\t\t: never;\n};\n\n/**\n * Function signature for system process methods\n * @param queries Results of entity queries defined by the system\n * @param deltaTime Time elapsed since last update in seconds\n * @param ecs The ECSpresso instance providing access to all ECS functionality\n */\ntype ProcessFunction<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>,\n\tQueries extends Record<string, QueryDefinition<ComponentTypes>>,\n> = (\n\tqueries: QueryResults<ComponentTypes, Queries>,\n\tdeltaTime: number,\n\tecs: ECSpresso<\n\t\tComponentTypes,\n\t\tEventTypes,\n\t\tResourceTypes\n\t>\n) => void;\n\n/**\n * Type for system initialization functions\n * These can be asynchronous\n */\ntype LifecycleFunction<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>,\n> = (\n\tecs: ECSpresso<\n\t\tComponentTypes,\n\t\tEventTypes,\n\t\tResourceTypes\n\t>,\n) => void | Promise<void>;\n\n/**\n * Create a SystemBuilder attached to an ECSpresso instance\n * Helper function used by ECSpresso.addSystem\n */\nexport function createEcspressoSystemBuilder<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>\n>(\n\tlabel: string,\n\tecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>\n): SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes> {\n\treturn new SystemBuilder<ComponentTypes, EventTypes, ResourceTypes>(\n\t\tlabel,\n\t\tecspresso\n\t) as SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes>;\n}\n\n/**\n * Create a SystemBuilder attached to a Bundle\n * Helper function used by Bundle.addSystem\n */\nexport function createBundleSystemBuilder<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>\n>(\n\tlabel: string,\n\tbundle: Bundle<ComponentTypes, EventTypes, ResourceTypes>\n): SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes> {\n\treturn new SystemBuilder<ComponentTypes, EventTypes, ResourceTypes>(\n\t\tlabel,\n\t\tnull,\n\t\tbundle\n\t) as SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes>;\n}\n\n// Type interfaces for specialized SystemBuilders\n\n/**\n * SystemBuilder with a guaranteed non-null reference to an ECSpresso instance\n */\nexport interface SystemBuilderWithEcspresso<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>,\n\tQueries extends Record<string, QueryDefinition<ComponentTypes>> = {}\n> extends SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, Queries> {\n\treadonly ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>;\n\t\n\t/**\n\t * Complete this system and return ECSpresso for seamless chaining\n\t * Automatically registers the system when called\n\t */\n\tand(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes>;\n}\n\n/**\n * SystemBuilder with a guaranteed non-null reference to a Bundle\n */\nexport interface SystemBuilderWithBundle<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>,\n\tQueries extends Record<string, QueryDefinition<ComponentTypes>> = {}\n> extends SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, Queries> {\n\treadonly bundle: Bundle<ComponentTypes, EventTypes, ResourceTypes>;\n\n\t/**\n\t * Complete this system and return the Bundle for chaining\n\t * Enables fluent API: bundle.addSystem(...).and().addSystem(...)\n\t */\n\tand(): Bundle<ComponentTypes, EventTypes, ResourceTypes>;\n}\n",
+    "import { createBundleSystemBuilder, SystemBuilderWithBundle } from './system-builder';\nimport type ECSpresso from './ecspresso';\nimport type { AssetDefinition } from './asset-types';\nimport type { ScreenDefinition } from './screen-types';\n\n/**\n * Generates a unique ID for a bundle\n */\nfunction generateBundleId(): string {\n\treturn `bundle_${Date.now().toString(36)}_${Math.random().toString(36).substring(2, 9)}`;\n}\n\n/**\n * Bundle class that encapsulates a set of components, resources, events, and systems\n * that can be merged into a ECSpresso instance\n */\nexport default class Bundle<\n\tComponentTypes extends Record<string, any> = {},\n\tEventTypes extends Record<string, any> = {},\n\tResourceTypes extends Record<string, any> = {},\n\tAssetTypes extends Record<string, unknown> = {},\n\tScreenStates extends Record<string, ScreenDefinition<any, any>> = {},\n> {\n\tprivate _systems: SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, any>[] = [];\n\tprivate _resources: Map<keyof ResourceTypes, ResourceTypes[keyof ResourceTypes]> = new Map();\n\tprivate _assets: Map<string, AssetDefinition<unknown>> = new Map();\n\tprivate _assetGroups: Map<string, Map<string, () => Promise<unknown>>> = new Map();\n\tprivate _screens: Map<string, ScreenDefinition<any, any>> = new Map();\n\tprivate _id: string;\n\n\tconstructor(id?: string) {\n\t\tthis._id = id || generateBundleId();\n\t}\n\n\t/**\n\t * Get the unique ID of this bundle\n\t */\n\tget id(): string {\n\t\treturn this._id;\n\t}\n\n\t/**\n\t * Set the ID of this bundle\n\t * @internal Used by combineBundles\n\t */\n\tset id(value: string) {\n\t\tthis._id = value;\n\t}\n\n\t/**\n\t * Add a system to this bundle, by label (creating a new builder) or by reusing an existing one\n\t */\n\taddSystem<Q extends Record<string, any>>(builder: SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, Q>): SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, Q>;\n\taddSystem(label: string): SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, {}>;\n\taddSystem(builderOrLabel: string | SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, any>) {\n\t\tif (typeof builderOrLabel === 'string') {\n\t\t\tconst system = createBundleSystemBuilder<ComponentTypes, EventTypes, ResourceTypes>(builderOrLabel, this);\n\t\t\tthis._systems.push(system);\n\t\t\treturn system;\n\t\t} else {\n\t\t\tthis._systems.push(builderOrLabel);\n\t\t\treturn builderOrLabel;\n\t\t}\n\t}\n\n\t/**\n\t * Add a resource to this bundle\n\t * @param label The resource key\n\t * @param resource The resource value, a factory function, or a factory with dependencies\n\t */\n\taddResource<K extends keyof ResourceTypes>(\n\t\tlabel: K,\n\t\tresource:\n\t\t\t| ResourceTypes[K]\n\t\t\t| ((ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>)\n\t\t\t| { dependsOn: readonly string[]; factory: (ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]> }\n\t) {\n\t\t// We need this cast because TypeScript doesn't recognize that a value of type\n\t\t// ResourceTypes[K] | (() => ResourceTypes[K] | Promise<ResourceTypes[K]>) | { dependsOn, factory }\n\t\t// can be properly assigned to Map<keyof ResourceTypes, ResourceTypes[keyof ResourceTypes]>\n\t\tthis._resources.set(label, resource as unknown as ResourceTypes[K]);\n\t\treturn this;\n\t}\n\n\t/**\n\t * Add an asset to this bundle\n\t * @param key The asset key\n\t * @param loader Function that loads and returns the asset\n\t * @param options Optional asset configuration\n\t */\n\taddAsset<K extends string, T>(\n\t\tkey: K,\n\t\tloader: () => Promise<T>,\n\t\toptions?: { eager?: boolean; group?: string }\n\t): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes & Record<K, T>, ScreenStates> {\n\t\tthis._assets.set(key, {\n\t\t\tloader,\n\t\t\teager: options?.eager ?? true,\n\t\t\tgroup: options?.group,\n\t\t});\n\t\treturn this as unknown as Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes & Record<K, T>, ScreenStates>;\n\t}\n\n\t/**\n\t * Add a group of assets to this bundle\n\t * @param groupName The group name\n\t * @param assets Object mapping asset keys to loader functions\n\t */\n\taddAssetGroup<G extends string, T extends Record<string, () => Promise<unknown>>>(\n\t\tgroupName: G,\n\t\tassets: T\n\t): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes & { [K in keyof T]: Awaited<ReturnType<T[K]>> }, ScreenStates> {\n\t\tconst groupAssets = new Map<string, () => Promise<unknown>>();\n\t\tfor (const [key, loader] of Object.entries(assets)) {\n\t\t\tgroupAssets.set(key, loader as () => Promise<unknown>);\n\t\t\tthis._assets.set(key, {\n\t\t\t\tloader: loader as () => Promise<unknown>,\n\t\t\t\teager: false,\n\t\t\t\tgroup: groupName,\n\t\t\t});\n\t\t}\n\t\tthis._assetGroups.set(groupName, groupAssets);\n\t\treturn this as unknown as Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes & { [K in keyof T]: Awaited<ReturnType<T[K]>> }, ScreenStates>;\n\t}\n\n\t/**\n\t * Add a screen to this bundle\n\t * @param name The screen name\n\t * @param definition The screen definition\n\t */\n\taddScreen<K extends string, Config extends Record<string, unknown>, State extends Record<string, unknown>>(\n\t\tname: K,\n\t\tdefinition: ScreenDefinition<Config, State>\n\t): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates & Record<K, ScreenDefinition<Config, State>>> {\n\t\tthis._screens.set(name, definition);\n\t\treturn this as unknown as Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates & Record<K, ScreenDefinition<Config, State>>>;\n\t}\n\n\t/**\n\t * Get all asset definitions in this bundle\n\t */\n\tgetAssets(): Map<string, AssetDefinition<unknown>> {\n\t\treturn new Map(this._assets);\n\t}\n\n\t/**\n\t * Get all screen definitions in this bundle\n\t */\n\tgetScreens(): Map<string, ScreenDefinition<any, any>> {\n\t\treturn new Map(this._screens);\n\t}\n\n\t/**\n\t * Internal method to set a resource\n\t * @internal Used by mergeBundles\n\t */\n\t_setResource(key: string, value: unknown): void {\n\t\tthis._resources.set(key as keyof ResourceTypes, value as ResourceTypes[keyof ResourceTypes]);\n\t}\n\n\t/**\n\t * Internal method to set an asset definition\n\t * @internal Used by mergeBundles\n\t */\n\t_setAsset(key: string, definition: AssetDefinition<unknown>): void {\n\t\tthis._assets.set(key, definition);\n\t}\n\n\t/**\n\t * Internal method to set a screen definition\n\t * @internal Used by mergeBundles\n\t */\n\t_setScreen(name: string, definition: ScreenDefinition<any, any>): void {\n\t\tthis._screens.set(name, definition);\n\t}\n\n\t/**\n\t * Get all systems defined in this bundle\n\t * Returns built System objects instead of SystemBuilders\n\t */\n\tgetSystems() {\n\t\treturn this._systems.map(system => system.build());\n\t}\n\n\t/**\n\t * Register all systems in this bundle with an ECSpresso instance\n\t * @internal Used by ECSpresso when adding a bundle\n\t */\n\tregisterSystemsWithEcspresso(ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) {\n\t\tfor (const systemBuilder of this._systems) {\n\t\t\tsystemBuilder.build(ecspresso);\n\t\t}\n\t}\n\n\t/**\n\t * Get all resources defined in this bundle\n\t */\n\tgetResources(): Map<keyof ResourceTypes, ResourceTypes[keyof ResourceTypes]> {\n\t\treturn new Map(this._resources);\n\t}\n\n\t/**\n\t * Get a specific resource by key\n\t * @param key The resource key\n\t * @returns The resource value or undefined if not found\n\t */\n\tgetResource<K extends keyof ResourceTypes>(key: K): ResourceTypes[K] {\n\t\treturn this._resources.get(key) as ResourceTypes[K];\n\t}\n\n\t/**\n\t * Get all system builders in this bundle\n\t */\n\tgetSystemBuilders(): SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, any>[] {\n\t\treturn [...this._systems];\n\t}\n\n\t/**\n\t * Check if this bundle has a specific resource\n\t * @param key The resource key to check\n\t * @returns True if the resource exists\n\t */\n\thasResource<K extends keyof ResourceTypes>(key: K): boolean {\n\t\treturn this._resources.has(key);\n\t}\n}\n\n/**\n * Utility type to check if two types are exactly the same\n */\ntype Exactly<T, U> = T extends U ? U extends T ? true : false : false;\n\n/**\n * Simplified type constraint for bundle compatibility\n * Ensures that overlapping keys have exactly the same types\n */\ntype CompatibleBundles<\n\tC1 extends Record<string, any>,\n\tC2 extends Record<string, any>,\n\tE1 extends Record<string, any>,\n\tE2 extends Record<string, any>,\n\tR1 extends Record<string, any>,\n\tR2 extends Record<string, any>,\n\tA1 extends Record<string, unknown> = {},\n\tA2 extends Record<string, unknown> = {},\n\tS1 extends Record<string, ScreenDefinition<any, any>> = {},\n\tS2 extends Record<string, ScreenDefinition<any, any>> = {},\n> = {\n\t[K in keyof C1 & keyof C2]: Exactly<C1[K], C2[K]> extends true ? C1[K] : never;\n} & {\n\t[K in keyof E1 & keyof E2]: Exactly<E1[K], E2[K]> extends true ? E1[K] : never;\n} & {\n\t[K in keyof R1 & keyof R2]: Exactly<R1[K], R2[K]> extends true ? R1[K] : never;\n} & {\n\t[K in keyof A1 & keyof A2]: Exactly<A1[K], A2[K]> extends true ? A1[K] : never;\n} & {\n\t[K in keyof S1 & keyof S2]: Exactly<S1[K], S2[K]> extends true ? S1[K] : never;\n};\n\n/**\n * Function that merges multiple bundles into a single bundle\n */\nexport function mergeBundles<\n\tC1 extends Record<string, any>,\n\tE1 extends Record<string, any>,\n\tR1 extends Record<string, any>,\n\tA1 extends Record<string, unknown>,\n\tS1 extends Record<string, ScreenDefinition<any, any>>,\n\tC2 extends Record<string, any>,\n\tE2 extends Record<string, any>,\n\tR2 extends Record<string, any>,\n\tA2 extends Record<string, unknown>,\n\tS2 extends Record<string, ScreenDefinition<any, any>>,\n>(\n\tid: string,\n\tbundle1: Bundle<C1, E1, R1, A1, S1>,\n\tbundle2: Bundle<C2, E2, R2, A2, S2> & CompatibleBundles<C1, C2, E1, E2, R1, R2, A1, A2, S1, S2>\n): Bundle<C1 & C2, E1 & E2, R1 & R2, A1 & A2, S1 & S2>;\n\nexport function mergeBundles<\n\tComponentTypes extends Record<string, any>,\n\tEventTypes extends Record<string, any>,\n\tResourceTypes extends Record<string, any>,\n\tAssetTypes extends Record<string, unknown>,\n\tScreenStates extends Record<string, ScreenDefinition<any, any>>,\n>(\n\tid: string,\n\t...bundles: Array<Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>>\n): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;\n\nexport function mergeBundles(\n\tid: string,\n\t...bundles: Array<Bundle<any, any, any, any, any>>\n): Bundle<any, any, any, any, any> {\n\tif (bundles.length === 0) {\n\t\treturn new Bundle(id);\n\t}\n\n\tconst combined = new Bundle(id);\n\n\tfor (const bundle of bundles) {\n\t\tfor (const system of bundle.getSystemBuilders()) {\n\t\t\t// reuse the full builder so we carry over queries, hooks, and handlers\n\t\t\tcombined.addSystem(system);\n\t\t}\n\n\t\t// Add resources from this bundle\n\t\tfor (const [label, resource] of bundle.getResources().entries()) {\n\t\t\tcombined._setResource(label as string, resource);\n\t\t}\n\n\t\t// Add assets from this bundle\n\t\tfor (const [key, definition] of bundle.getAssets().entries()) {\n\t\t\tcombined._setAsset(key, definition);\n\t\t}\n\n\t\t// Add screens from this bundle\n\t\tfor (const [name, definition] of bundle.getScreens().entries()) {\n\t\t\tcombined._setScreen(name, definition);\n\t\t}\n\t}\n\n\treturn combined;\n}\n",
+    "/**\n * Timer Bundle for ECSpresso\n *\n * Provides ECS-native timers following the \"data, not callbacks\" philosophy.\n * Timers are components processed each frame, automatically cleaned up when entities are removed.\n */\n\nimport Bundle from '../../bundle';\n\n// ==================== Event Types ====================\n\n/**\n * Data structure published when a timer completes.\n * Use this type when defining timer completion events in your EventTypes interface.\n *\n * @example\n * ```typescript\n * interface Events {\n *   hideMessage: TimerEventData;\n *   spawnWave: TimerEventData;\n * }\n * ```\n */\nexport interface TimerEventData {\n\t/** The entity ID that the timer belongs to */\n\tentityId: number;\n\t/** The timer's configured duration in seconds */\n\tduration: number;\n\t/** The actual elapsed time (may exceed duration slightly) */\n\telapsed: number;\n}\n\n// ==================== Component Types ====================\n\n/**\n * Extracts event names from EventTypes that have TimerEventData as their payload.\n * This ensures only compatible events can be used with timer.onComplete.\n */\nexport type TimerEventName<EventTypes extends Record<string, any>> = {\n\t[K in keyof EventTypes]: EventTypes[K] extends TimerEventData ? K : never\n}[keyof EventTypes];\n\n/**\n * Timer component data structure.\n * Use `justFinished` to detect timer completion in your systems.\n *\n * @template EventTypes The event types from your ECS\n */\nexport interface Timer<EventTypes extends Record<string, any>> {\n\t/** Time accumulated so far (seconds) */\n\telapsed: number;\n\t/** Target duration (seconds) */\n\tduration: number;\n\t/** Whether timer repeats after completion */\n\trepeat: boolean;\n\t/** Whether timer is currently running */\n\tactive: boolean;\n\t/** True for one frame after timer completes */\n\tjustFinished: boolean;\n\t/** Optional event name to publish when timer completes. Must be an event with TimerEventData payload. */\n\tonComplete?: TimerEventName<EventTypes>;\n}\n\n/**\n * Component types provided by the timer bundle.\n * Extend your component types with this interface.\n *\n * @template EventTypes The event types from your ECS\n *\n * @example\n * ```typescript\n * interface GameComponents extends TimerComponentTypes<GameEvents> {\n *   velocity: { x: number; y: number };\n *   player: true;\n * }\n * ```\n */\nexport interface TimerComponentTypes<EventTypes extends Record<string, any>> {\n\ttimer: Timer<EventTypes>;\n}\n\n// ==================== Bundle Options ====================\n\n/**\n * Configuration options for the timer bundle.\n */\nexport interface TimerBundleOptions {\n\t/** System group name (default: 'timers') */\n\tsystemGroup?: string;\n\t/** Priority for timer update system (default: 0) */\n\tpriority?: number;\n}\n\n// ==================== Helper Functions ====================\n\n/**\n * Options for timer creation\n *\n * @template EventTypes The event types from your ECS\n */\nexport interface TimerOptions<EventTypes extends Record<string, any>> {\n\t/** Event name to publish when timer completes. Must be an event with TimerEventData payload. */\n\tonComplete?: TimerEventName<EventTypes>;\n}\n\n/**\n * Create a one-shot timer that fires once after the specified duration.\n *\n * @template EventTypes The event types from your ECS (must be explicitly provided)\n * @param duration Duration in seconds until the timer completes\n * @param options Optional configuration including event name\n * @returns Component object suitable for spreading into spawn()\n *\n * @example\n * ```typescript\n * // Timer without event\n * ecs.spawn({\n *   ...createTimer<GameEvents>(2),\n *   explosion: true,\n * });\n *\n * // Timer that publishes an event on completion\n * ecs.spawn({\n *   ...createTimer<GameEvents>(1.5, { onComplete: 'hideMessage' }),\n * });\n * ```\n */\nexport function createTimer<EventTypes extends Record<string, any>>(\n\tduration: number,\n\toptions?: TimerOptions<EventTypes>\n): Pick<TimerComponentTypes<EventTypes>, 'timer'> {\n\treturn {\n\t\ttimer: {\n\t\t\telapsed: 0,\n\t\t\tduration,\n\t\t\trepeat: false,\n\t\t\tactive: true,\n\t\t\tjustFinished: false,\n\t\t\tonComplete: options?.onComplete,\n\t\t},\n\t};\n}\n\n/**\n * Create a repeating timer that fires every `duration` seconds.\n *\n * @template EventTypes The event types from your ECS (must be explicitly provided)\n * @param duration Duration in seconds between each timer completion\n * @param options Optional configuration including event name\n * @returns Component object suitable for spreading into spawn()\n *\n * @example\n * ```typescript\n * // Timer without event\n * ecs.spawn({\n *   ...createRepeatingTimer<GameEvents>(5),\n *   spawner: true,\n * });\n *\n * // Repeating timer that publishes an event each cycle\n * ecs.spawn({\n *   ...createRepeatingTimer<GameEvents>(3, { onComplete: 'spawnWave' }),\n * });\n * ```\n */\nexport function createRepeatingTimer<EventTypes extends Record<string, any>>(\n\tduration: number,\n\toptions?: TimerOptions<EventTypes>\n): Pick<TimerComponentTypes<EventTypes>, 'timer'> {\n\treturn {\n\t\ttimer: {\n\t\t\telapsed: 0,\n\t\t\tduration,\n\t\t\trepeat: true,\n\t\t\tactive: true,\n\t\t\tjustFinished: false,\n\t\t\tonComplete: options?.onComplete,\n\t\t},\n\t};\n}\n\n// ==================== Bundle Factory ====================\n\n/**\n * Create a timer bundle for ECSpresso.\n *\n * This bundle provides:\n * - Timer update system that processes all timer components each frame\n * - `justFinished` flag pattern for one-frame completion detection\n * - Automatic cleanup when entities are removed\n *\n * @example\n * ```typescript\n * const ecs = ECSpresso\n *   .create<Components, Events, Resources>()\n *   .withBundle(createTimerBundle())\n *   .build();\n *\n * // Spawn entity with timer\n * ecs.spawn({\n *   ...createRepeatingTimer(5),\n *   spawner: true,\n * });\n *\n * // React to timer completion in a system\n * ecs.addSystem('spawn-on-timer')\n *   .addQuery('spawners', { with: ['timer', 'spawner'] })\n *   .setProcess((queries, _dt, ecs) => {\n *     for (const { components } of queries.spawners) {\n *       if (components.timer.justFinished) {\n *         ecs.spawn({ enemy: true });\n *       }\n *     }\n *   });\n * ```\n */\nexport function createTimerBundle<EventTypes extends Record<string, any>>(\n\toptions?: TimerBundleOptions\n): Bundle<TimerComponentTypes<EventTypes>, EventTypes, {}> {\n\tconst {\n\t\tsystemGroup = 'timers',\n\t\tpriority = 0,\n\t} = options ?? {};\n\n\tconst bundle = new Bundle<TimerComponentTypes<EventTypes>, EventTypes, {}>('timers');\n\n\tbundle\n\t\t.addSystem('timer-update')\n\t\t.setPriority(priority)\n\t\t.inGroup(systemGroup)\n\t\t.addQuery('timers', {\n\t\t\twith: ['timer'] as const,\n\t\t})\n\t\t.setProcess((queries, deltaTime, ecs) => {\n\t\t\tfor (const entity of queries.timers) {\n\t\t\t\tconst { timer } = entity.components;\n\n\t\t\t\t// Reset justFinished flag from previous frame\n\t\t\t\ttimer.justFinished = false;\n\n\t\t\t\t// Skip inactive timers\n\t\t\t\tif (!timer.active) continue;\n\n\t\t\t\t// Accumulate time\n\t\t\t\ttimer.elapsed += deltaTime;\n\n\t\t\t\t// Check if timer completed\n\t\t\t\tif (timer.elapsed < timer.duration) continue;\n\n\t\t\t\t// Timer completed - handle based on repeat mode\n\t\t\t\tif (timer.repeat) {\n\t\t\t\t\t// Handle multiple cycles in one frame\n\t\t\t\t\twhile (timer.elapsed >= timer.duration) {\n\t\t\t\t\t\ttimer.justFinished = true;\n\t\t\t\t\t\tpublishTimerEvent(ecs, entity.id, timer);\n\t\t\t\t\t\ttimer.elapsed -= timer.duration;\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\t// One-shot timer\n\t\t\t\t\ttimer.justFinished = true;\n\t\t\t\t\tpublishTimerEvent(ecs, entity.id, timer);\n\t\t\t\t\ttimer.active = false;\n\t\t\t\t\t// Auto-remove one-shot timer entities after completion.\n\t\t\t\t\t// If configurability is needed in the future, add an autoRemove option to TimerOptions.\n\t\t\t\t\tecs.commands.removeEntity(entity.id);\n\t\t\t\t}\n\t\t\t}\n\t\t})\n\t\t.and();\n\n\t/**\n\t * Publishes timer completion event if onComplete is specified.\n\t * Type assertion needed: TypeScript can't infer that TimerEventName<EventTypes>\n\t * maps to events with TimerEventData payloads, even though that's what the type enforces.\n\t */\n\tfunction publishTimerEvent(\n\t\tecs: { eventBus: { publish: (event: any, data: any) => void } },\n\t\tentityId: number,\n\t\ttimer: Timer<EventTypes>\n\t): void {\n\t\tif (!timer.onComplete) return;\n\t\tconst eventData: TimerEventData = {\n\t\t\tentityId,\n\t\t\tduration: timer.duration,\n\t\t\telapsed: timer.elapsed,\n\t\t};\n\t\tecs.eventBus.publish(timer.onComplete, eventData);\n\t}\n\n\treturn bundle;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "8A5D1E808447563C64756E2164756E21",
+  "names": []
+}

package/dist/bundles/utils/transform.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Transform Bundle for ECSpresso
+ *
+ * Provides hierarchical transform propagation following Bevy's Transform/GlobalTransform pattern.
+ * LocalTransform is modified by user code; WorldTransform is computed automatically.
+ *
+ * @see https://docs.rs/bevy/latest/bevy/transform/components/struct.GlobalTransform.html
+ */
+import Bundle from '../../bundle';
+/**
+ * Local transform relative to parent (or world if no parent).
+ * This is the transform you modify directly.
+ */
+export interface LocalTransform {
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+}
+/**
+ * Computed world transform (accumulated from parent chain).
+ * Read-only - managed by the transform propagation system.
+ */
+export interface WorldTransform {
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+}
+/**
+ * Component types provided by the transform bundle.
+ * Extend your component types with this interface.
+ *
+ * @example
+ * ```typescript
+ * interface GameComponents extends TransformComponentTypes {
+ *   sprite: Sprite;
+ *   velocity: { x: number; y: number };
+ * }
+ * ```
+ */
+export interface TransformComponentTypes {
+    localTransform: LocalTransform;
+    worldTransform: WorldTransform;
+}
+/**
+ * Configuration options for the transform bundle.
+ */
+export interface TransformBundleOptions {
+    /** System group name (default: 'transform') */
+    systemGroup?: string;
+    /** Priority for transform propagation (default: 500, runs after physics/movement) */
+    priority?: number;
+}
+/**
+ * Default local transform values.
+ */
+export declare const DEFAULT_LOCAL_TRANSFORM: Readonly<LocalTransform>;
+/**
+ * Default world transform values.
+ */
+export declare const DEFAULT_WORLD_TRANSFORM: Readonly<WorldTransform>;
+/**
+ * Create a local transform component with position only.
+ * Uses default rotation (0) and scale (1, 1).
+ *
+ * @param x The x coordinate
+ * @param y The y coordinate
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createLocalTransform(100, 200),
+ *   sprite,
+ * });
+ * ```
+ */
+export declare function createLocalTransform(x: number, y: number): Pick<TransformComponentTypes, 'localTransform'>;
+/**
+ * Create a world transform component with position only.
+ * Typically used alongside createLocalTransform for initial state.
+ *
+ * @param x The x coordinate
+ * @param y The y coordinate
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createWorldTransform(x: number, y: number): Pick<TransformComponentTypes, 'worldTransform'>;
+/**
+ * Options for creating a full transform.
+ */
+export interface TransformOptions {
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    /** Uniform scale (overrides scaleX/scaleY if provided) */
+    scale?: number;
+}
+/**
+ * Create both local and world transform components.
+ * World transform is initialized to match local transform.
+ *
+ * @param x The x coordinate
+ * @param y The y coordinate
+ * @param options Optional rotation and scale
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   sprite,
+ * });
+ *
+ * // With rotation and scale
+ * ecs.spawn({
+ *   ...createTransform(100, 200, { rotation: Math.PI / 4, scale: 2 }),
+ *   sprite,
+ * });
+ * ```
+ */
+export declare function createTransform(x: number, y: number, options?: TransformOptions): TransformComponentTypes;
+/**
+ * Create a transform bundle for ECSpresso.
+ *
+ * This bundle provides:
+ * - Transform propagation system that computes world transforms from local transforms
+ * - Parent-first traversal ensures parents are processed before children
+ * - Supports full transform hierarchy (position, rotation, scale)
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso
+ *   .create<Components, Events, Resources>()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createMovementBundle())
+ *   .build();
+ *
+ * // Spawn entity with transform
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   velocity: { x: 50, y: 0 },
+ * });
+ * ```
+ */
+export declare function createTransformBundle(options?: TransformBundleOptions): Bundle<TransformComponentTypes, {}, {}>;

package/dist/command-buffer.d.ts

@@ -0,0 +1,90 @@
+import type ECSpresso from './ecspresso';
+import type { RemoveEntityOptions } from './types';
+/**
+ * CommandBuffer queues structural changes to be executed later.
+ * This prevents ordering issues when modifying entities during system execution.
+ *
+ * Commands are executed in FIFO order when playback() is called.
+ *
+ * @example
+ * ```typescript
+ * // In a system
+ * ecs.commands.removeEntity(entityId);
+ * ecs.commands.spawn({ position: { x: 0, y: 0 } });
+ *
+ * // Later (automatically at end of update())
+ * ecs.commands.playback(ecs);
+ * ```
+ */
+export default class CommandBuffer<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}> {
+    private commands;
+    /**
+     * Queue an entity removal command
+     * @param entityId The ID of the entity to remove
+     * @param options Optional removal options (cascade, etc.)
+     */
+    removeEntity(entityId: number, options?: RemoveEntityOptions): void;
+    /**
+     * Queue a component addition command
+     * @param entityId The ID of the entity
+     * @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;
+    /**
+     * Queue a component removal command
+     * @param entityId The ID of the entity
+     * @param componentName The name of the component to remove
+     */
+    removeComponent<K extends keyof ComponentTypes>(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;
+    /**
+     * Queue a child entity spawn command
+     * @param parentId The ID of the parent entity
+     * @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;
+    /**
+     * Queue multiple component additions
+     * @param entityId The ID of the entity
+     * @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;
+    /**
+     * Queue a parent assignment command
+     * @param childId The ID of the child entity
+     * @param parentId The ID of the parent entity
+     */
+    setParent(childId: number, parentId: number): void;
+    /**
+     * Queue a parent removal command
+     * @param childId The ID of the child entity
+     */
+    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<AssetTypes extends Record<string, any> = {}, ScreenStates extends Record<string, any> = {}>(ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
+    /**
+     * Clear all queued commands without executing them
+     */
+    clear(): void;
+    /**
+     * Get the number of queued commands
+     * @returns The number of commands waiting to be executed
+     */
+    get length(): number;
+}