ecspresso 0.15.0 → 0.16.0

package/dist/plugins/scripting/timers.d.ts

@@ -1,146 +1,148 @@
 /**
  * Timer Plugin 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.
+ * ECS-native timers as pure data. An entity may carry multiple named timer
+ * slots; the plugin's update system ticks every slot each frame and exposes
+ * `justFinished` for the frame a slot crosses its duration. The plugin never
+ * touches entity lifecycle — callers despawn (or do anything else) themselves
+ * by reacting to `justFinished` or in the slot's `onComplete` callback.
  */
 import { type BasePluginOptions } from 'ecspresso';
 /**
- * Data structure passed to onComplete callbacks when a timer completes.
+ * Data passed to a slot's `onComplete` callback when its timer completes.
  *
  * @example
  * ```typescript
- * createTimer(1.5, {
- *   onComplete: (data) => {
- *     console.log(`Timer on entity ${data.entityId} finished after ${data.elapsed}s`);
- *   }
- * });
+ * timers: {
+ *   launch: createTimer(1.5, {
+ *     onComplete: ({ entityId, slot, elapsed }) => {
+ *       console.log(`Slot ${slot} on entity ${entityId} finished after ${elapsed}s`);
+ *     },
+ *   }),
+ * }
  * ```
  */
 export interface TimerEventData {
-    /** The entity ID that the timer belongs to */
+    /** The entity ID that owns the timer slot */
     entityId: number;
-    /** The timer's configured duration in seconds */
+    /** The slot name within the entity's `timers` map */
+    slot: string;
+    /** The slot's configured duration in seconds */
     duration: number;
     /** The actual elapsed time (may exceed duration slightly) */
     elapsed: number;
 }
 /**
- * Timer component data structure.
- * Use `justFinished` to detect timer completion in your systems.
+ * A single timer's data. Multiple of these can live on one entity, keyed by slot name.
+ * Use `justFinished` to detect completion in your systems.
  */
 export interface Timer {
     /** Time accumulated so far (seconds) */
     elapsed: number;
     /** Target duration (seconds) */
     duration: number;
-    /** Whether timer repeats after completion */
+    /** Whether the timer repeats after completion */
     repeat: boolean;
-    /** Whether timer is currently running */
+    /** Whether the timer is currently running */
     active: boolean;
-    /** True for one frame after timer completes */
+    /** True for one frame after the timer completes */
     justFinished: boolean;
-    /** Optional callback invoked when timer completes */
+    /** Optional callback invoked when the timer completes */
     onComplete?: (data: TimerEventData) => void;
 }
 /**
  * Component types provided by the timer plugin.
- * Included automatically via `.withPlugin(createTimerPlugin())`.
+ *
+ * Each entity carries a single `timers` component whose value is a map of
+ * named slots. This lets one entity host independent phase clocks
+ * (e.g. `{ launch: ..., shieldDepletion: ..., hangarCycle: ... }`) without
+ * one timer's lifecycle constraining another.
  *
  * @example
  * ```typescript
  * const ecs = ECSpresso.create()
  *   .withPlugin(createTimerPlugin())
- *   .withComponentTypes<{ velocity: { x: number; y: number }; player: true }>()
+ *   .withComponentTypes<{ fighter: true }>()
  *   .build();
+ *
+ * ecs.spawn({
+ *   fighter: true,
+ *   timers: { launch: createTimer(2.0) },
+ * });
  * ```
  */
 export interface TimerComponentTypes {
-    timer: Timer;
+    timers: Record<string, Timer>;
 }
-/**
- * Configuration options for the timer plugin.
- */
 export interface TimerPluginOptions<G extends string = 'timers'> extends BasePluginOptions<G> {
 }
-/**
- * Options for timer creation
- */
 export interface TimerOptions {
-    /** Callback invoked when timer completes */
+    /** Callback invoked when the timer completes */
     onComplete?: (data: TimerEventData) => void;
 }
 /**
- * Create a one-shot timer that fires once after the specified duration.
+ * Create a one-shot `Timer` to drop into a `timers` slot.
  *
- * @param duration Duration in seconds until the timer completes
- * @param options Optional configuration including onComplete callback
- * @returns Component object suitable for spreading into spawn()
+ * The timer fires `justFinished` for one frame on completion and then idles
+ * (`active = false`). The entity is left alone — if the slot's lifetime
+ * coincides with the entity's lifetime (vfx, blasts, summon-anim), despawn
+ * the host yourself in `onComplete` or in a system that watches `justFinished`.
  *
  * @example
  * ```typescript
- * // Timer without callback
  * ecs.spawn({
- *   ...createTimer(2),
- *   explosion: true,
+ *   fighter: true,
+ *   timers: { launch: createTimer(2.0) },
  * });
  *
- * // Timer with onComplete callback
+ * // Self-destructing vfx — caller owns the despawn:
  * ecs.spawn({
- *   ...createTimer(1.5, { onComplete: (data) => console.log('done', data.entityId) }),
+ *   timers: {
+ *     fade: createTimer(1.0, {
+ *       onComplete: ({ entityId }) => ecs.commands.removeEntity(entityId),
+ *     }),
+ *   },
  * });
  * ```
  */
-export declare function createTimer(duration: number, options?: TimerOptions): Pick<TimerComponentTypes, 'timer'>;
+export declare function createTimer(duration: number, options?: TimerOptions): Timer;
 /**
- * Create a repeating timer that fires every `duration` seconds.
- *
- * @param duration Duration in seconds between each timer completion
- * @param options Optional configuration including onComplete callback
- * @returns Component object suitable for spreading into spawn()
+ * Create a repeating `Timer` to drop into a `timers` slot. Fires
+ * `justFinished` once per cycle and continues running.
  *
  * @example
  * ```typescript
- * // Timer without callback
  * ecs.spawn({
- *   ...createRepeatingTimer(5),
- *   spawner: true,
- * });
- *
- * // Repeating timer with onComplete callback
- * ecs.spawn({
- *   ...createRepeatingTimer(3, { onComplete: (data) => console.log('cycle', data.elapsed) }),
+ *   carrier: true,
+ *   timers: { hangarCycle: createRepeatingTimer(5.0) },
  * });
  * ```
  */
-export declare function createRepeatingTimer(duration: number, options?: TimerOptions): Pick<TimerComponentTypes, 'timer'>;
+export declare function createRepeatingTimer(duration: number, options?: TimerOptions): Timer;
 /**
  * Create a timer plugin for ECSpresso.
  *
- * This plugin 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
+ * The plugin installs one update system that ticks every slot of every
+ * `timers` component each frame. It does not touch entity lifecycle —
+ * react to `justFinished` (or use `onComplete`) and despawn yourself if needed.
  *
  * @example
  * ```typescript
- * const ecs = ECSpresso
- *   .create<Components, Events, Resources>()
+ * const ecs = ECSpresso.create()
  *   .withPlugin(createTimerPlugin())
+ *   .withComponentTypes<{ spawner: true }>()
  *   .build();
  *
- * // Spawn entity with timer
  * ecs.spawn({
- *   ...createRepeatingTimer(5),
  *   spawner: true,
+ *   timers: { wave: createRepeatingTimer(5.0) },
  * });
  *
- * // React to timer completion in a system
  * ecs.addSystem('spawn-on-timer')
- *   .addQuery('spawners', { with: ['timer', 'spawner'] })
- *   .setProcess((queries, _dt, ecs) => {
+ *   .addQuery('spawners', { with: ['timers', 'spawner'] })
+ *   .setProcess(({ queries, ecs }) => {
  *     for (const { components } of queries.spawners) {
- *       if (components.timer.justFinished) {
+ *       if (components.timers.wave?.justFinished) {
  *         ecs.spawn({ enemy: true });
  *       }
  *     }

package/dist/plugins/scripting/timers.js

@@ -1,4 +1,4 @@
-var J=((k)=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(k,{get:(x,A)=>(typeof require<"u"?require:x)[A]}):k)(function(k){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+k+'" is not supported')});import{definePlugin as H}from"ecspresso";function M(k,x){return{timer:{elapsed:0,duration:k,repeat:!1,active:!0,justFinished:!1,onComplete:x?.onComplete}}}function N(k,x){return{timer:{elapsed:0,duration:k,repeat:!0,active:!0,justFinished:!1,onComplete:x?.onComplete}}}function Q(k){let{systemGroup:x="timers",priority:A=0,phase:B="preUpdate"}=k??{};return H("timers").withComponentTypes().withLabels().withGroups().install((C)=>{C.addSystem("timer-update").setPriority(A).inPhase(B).inGroup(x).addQuery("timers",{with:["timer"]}).setProcess(({queries:D,dt:E,ecs:F})=>{for(let z of D.timers){let{timer:j}=z.components;if(j.justFinished=!1,!j.active)continue;if(j.elapsed+=E,j.elapsed<j.duration)continue;if(j.repeat)while(j.elapsed>=j.duration)j.justFinished=!0,j.onComplete?.({entityId:z.id,duration:j.duration,elapsed:j.elapsed}),j.elapsed-=j.duration;else j.justFinished=!0,j.onComplete?.({entityId:z.id,duration:j.duration,elapsed:j.elapsed}),j.active=!1,F.commands.removeEntity(z.id)}})})}export{Q as createTimerPlugin,M as createTimer,N as createRepeatingTimer};
+var V=((A)=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(A,{get:(B,D)=>(typeof require<"u"?require:B)[D]}):A)(function(A){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+A+'" is not supported')});import{definePlugin as U}from"ecspresso";function Y(A,B){return{elapsed:0,duration:A,repeat:!1,active:!0,justFinished:!1,onComplete:B?.onComplete}}function Z(A,B){return{elapsed:0,duration:A,repeat:!0,active:!0,justFinished:!1,onComplete:B?.onComplete}}function _(A){let{systemGroup:B="timers",priority:D=0,phase:L="preUpdate"}=A??{};return U("timers").withComponentTypes().withLabels().withGroups().install((M)=>{M.addSystem("timer-update").setPriority(D).inPhase(L).inGroup(B).addQuery("timers",{with:["timers"]}).setProcess(({queries:N,dt:O})=>{for(let H of N.timers){let K=H.components.timers;for(let J in K){let z=K[J];if(!z)continue;if(z.justFinished=!1,!z.active)continue;if(z.elapsed+=O,z.elapsed<z.duration)continue;if(z.repeat)while(z.elapsed>=z.duration)z.justFinished=!0,z.onComplete?.({entityId:H.id,slot:J,duration:z.duration,elapsed:z.elapsed}),z.elapsed-=z.duration;else z.justFinished=!0,z.onComplete?.({entityId:H.id,slot:J,duration:z.duration,elapsed:z.elapsed}),z.active=!1}}})})}export{_ as createTimerPlugin,Y as createTimer,Z as createRepeatingTimer};
 
-//# debugId=7B8408B3E517C6C664756E2164756E21
+//# debugId=03F5D4A1CC15EDC764756E2164756E21
 //# sourceMappingURL=timers.js.map

package/dist/plugins/scripting/timers.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/plugins/scripting/timers.ts"],
   "sourcesContent": [
-    "/**\n * Timer Plugin 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 { definePlugin, type BasePluginOptions } from 'ecspresso';\n\n// ==================== Event Types ====================\n\n/**\n * Data structure passed to onComplete callbacks when a timer completes.\n *\n * @example\n * ```typescript\n * createTimer(1.5, {\n *   onComplete: (data) => {\n *     console.log(`Timer on entity ${data.entityId} finished after ${data.elapsed}s`);\n *   }\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/**\n * Timer component data structure.\n * Use `justFinished` to detect timer completion in your systems.\n */\nexport interface Timer {\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 callback invoked when timer completes */\n\tonComplete?: (data: TimerEventData) => void;\n}\n\n/**\n * Component types provided by the timer plugin.\n * Included automatically via `.withPlugin(createTimerPlugin())`.\n *\n * @example\n * ```typescript\n * const ecs = ECSpresso.create()\n *   .withPlugin(createTimerPlugin())\n *   .withComponentTypes<{ velocity: { x: number; y: number }; player: true }>()\n *   .build();\n * ```\n */\nexport interface TimerComponentTypes {\n\ttimer: Timer;\n}\n\n// ==================== Plugin Options ====================\n\n/**\n * Configuration options for the timer plugin.\n */\nexport interface TimerPluginOptions<G extends string = 'timers'> extends BasePluginOptions<G> {}\n\n// ==================== Helper Functions ====================\n\n/**\n * Options for timer creation\n */\nexport interface TimerOptions {\n\t/** Callback invoked when timer completes */\n\tonComplete?: (data: TimerEventData) => void;\n}\n\n/**\n * Create a one-shot timer that fires once after the specified duration.\n *\n * @param duration Duration in seconds until the timer completes\n * @param options Optional configuration including onComplete callback\n * @returns Component object suitable for spreading into spawn()\n *\n * @example\n * ```typescript\n * // Timer without callback\n * ecs.spawn({\n *   ...createTimer(2),\n *   explosion: true,\n * });\n *\n * // Timer with onComplete callback\n * ecs.spawn({\n *   ...createTimer(1.5, { onComplete: (data) => console.log('done', data.entityId) }),\n * });\n * ```\n */\nexport function createTimer(\n\tduration: number,\n\toptions?: TimerOptions\n): Pick<TimerComponentTypes, '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 * @param duration Duration in seconds between each timer completion\n * @param options Optional configuration including onComplete callback\n * @returns Component object suitable for spreading into spawn()\n *\n * @example\n * ```typescript\n * // Timer without callback\n * ecs.spawn({\n *   ...createRepeatingTimer(5),\n *   spawner: true,\n * });\n *\n * // Repeating timer with onComplete callback\n * ecs.spawn({\n *   ...createRepeatingTimer(3, { onComplete: (data) => console.log('cycle', data.elapsed) }),\n * });\n * ```\n */\nexport function createRepeatingTimer(\n\tduration: number,\n\toptions?: TimerOptions\n): Pick<TimerComponentTypes, '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// ==================== Plugin Factory ====================\n\n/**\n * Create a timer plugin for ECSpresso.\n *\n * This plugin 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 *   .withPlugin(createTimerPlugin())\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 createTimerPlugin<G extends string = 'timers'>(\n\toptions?: TimerPluginOptions<G>\n) {\n\tconst {\n\t\tsystemGroup = 'timers',\n\t\tpriority = 0,\n\t\tphase = 'preUpdate',\n\t} = options ?? {};\n\n\treturn definePlugin('timers')\n\t\t.withComponentTypes<TimerComponentTypes>()\n\t\t.withLabels<'timer-update'>()\n\t\t.withGroups<G>()\n\t\t.install((world) => {\n\t\t\tworld\n\t\t\t\t.addSystem('timer-update')\n\t\t\t\t.setPriority(priority)\n\t\t\t\t.inPhase(phase)\n\t\t\t\t.inGroup(systemGroup)\n\t\t\t\t.addQuery('timers', {\n\t\t\t\t\twith: ['timer'],\n\t\t\t\t})\n\t\t\t\t.setProcess(({ queries, dt, ecs }) => {\n\t\t\t\t\tfor (const entity of queries.timers) {\n\t\t\t\t\t\tconst { timer } = entity.components;\n\n\t\t\t\t\t\t// Reset justFinished flag from previous frame\n\t\t\t\t\t\ttimer.justFinished = false;\n\n\t\t\t\t\t\t// Skip inactive timers\n\t\t\t\t\t\tif (!timer.active) continue;\n\n\t\t\t\t\t\t// Accumulate time\n\t\t\t\t\t\ttimer.elapsed += dt;\n\n\t\t\t\t\t\t// Check if timer completed\n\t\t\t\t\t\tif (timer.elapsed < timer.duration) continue;\n\n\t\t\t\t\t\t// Timer completed - handle based on repeat mode\n\t\t\t\t\t\tif (timer.repeat) {\n\t\t\t\t\t\t\t// Handle multiple cycles in one frame\n\t\t\t\t\t\t\twhile (timer.elapsed >= timer.duration) {\n\t\t\t\t\t\t\t\ttimer.justFinished = true;\n\t\t\t\t\t\t\t\ttimer.onComplete?.({ entityId: entity.id, duration: timer.duration, elapsed: timer.elapsed });\n\t\t\t\t\t\t\t\ttimer.elapsed -= timer.duration;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t// One-shot timer\n\t\t\t\t\t\t\ttimer.justFinished = true;\n\t\t\t\t\t\t\ttimer.onComplete?.({ entityId: entity.id, duration: timer.duration, elapsed: timer.elapsed });\n\t\t\t\t\t\t\ttimer.active = false;\n\t\t\t\t\t\t\t// Auto-remove one-shot timer entities after completion.\n\t\t\t\t\t\t\t// If configurability is needed in the future, add an autoRemove option to TimerOptions.\n\t\t\t\t\t\t\tecs.commands.removeEntity(entity.id);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t});\n}\n"
+    "/**\n * Timer Plugin for ECSpresso\n *\n * ECS-native timers as pure data. An entity may carry multiple named timer\n * slots; the plugin's update system ticks every slot each frame and exposes\n * `justFinished` for the frame a slot crosses its duration. The plugin never\n * touches entity lifecycle — callers despawn (or do anything else) themselves\n * by reacting to `justFinished` or in the slot's `onComplete` callback.\n */\n\nimport { definePlugin, type BasePluginOptions } from 'ecspresso';\n\n// ==================== Event Types ====================\n\n/**\n * Data passed to a slot's `onComplete` callback when its timer completes.\n *\n * @example\n * ```typescript\n * timers: {\n *   launch: createTimer(1.5, {\n *     onComplete: ({ entityId, slot, elapsed }) => {\n *       console.log(`Slot ${slot} on entity ${entityId} finished after ${elapsed}s`);\n *     },\n *   }),\n * }\n * ```\n */\nexport interface TimerEventData {\n\t/** The entity ID that owns the timer slot */\n\tentityId: number;\n\t/** The slot name within the entity's `timers` map */\n\tslot: string;\n\t/** The slot'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 * A single timer's data. Multiple of these can live on one entity, keyed by slot name.\n * Use `justFinished` to detect completion in your systems.\n */\nexport interface Timer {\n\t/** Time accumulated so far (seconds) */\n\telapsed: number;\n\t/** Target duration (seconds) */\n\tduration: number;\n\t/** Whether the timer repeats after completion */\n\trepeat: boolean;\n\t/** Whether the timer is currently running */\n\tactive: boolean;\n\t/** True for one frame after the timer completes */\n\tjustFinished: boolean;\n\t/** Optional callback invoked when the timer completes */\n\tonComplete?: (data: TimerEventData) => void;\n}\n\n/**\n * Component types provided by the timer plugin.\n *\n * Each entity carries a single `timers` component whose value is a map of\n * named slots. This lets one entity host independent phase clocks\n * (e.g. `{ launch: ..., shieldDepletion: ..., hangarCycle: ... }`) without\n * one timer's lifecycle constraining another.\n *\n * @example\n * ```typescript\n * const ecs = ECSpresso.create()\n *   .withPlugin(createTimerPlugin())\n *   .withComponentTypes<{ fighter: true }>()\n *   .build();\n *\n * ecs.spawn({\n *   fighter: true,\n *   timers: { launch: createTimer(2.0) },\n * });\n * ```\n */\nexport interface TimerComponentTypes {\n\ttimers: Record<string, Timer>;\n}\n\n// ==================== Plugin Options ====================\n\nexport interface TimerPluginOptions<G extends string = 'timers'> extends BasePluginOptions<G> {}\n\n// ==================== Helper Functions ====================\n\nexport interface TimerOptions {\n\t/** Callback invoked when the timer completes */\n\tonComplete?: (data: TimerEventData) => void;\n}\n\n/**\n * Create a one-shot `Timer` to drop into a `timers` slot.\n *\n * The timer fires `justFinished` for one frame on completion and then idles\n * (`active = false`). The entity is left alone — if the slot's lifetime\n * coincides with the entity's lifetime (vfx, blasts, summon-anim), despawn\n * the host yourself in `onComplete` or in a system that watches `justFinished`.\n *\n * @example\n * ```typescript\n * ecs.spawn({\n *   fighter: true,\n *   timers: { launch: createTimer(2.0) },\n * });\n *\n * // Self-destructing vfx — caller owns the despawn:\n * ecs.spawn({\n *   timers: {\n *     fade: createTimer(1.0, {\n *       onComplete: ({ entityId }) => ecs.commands.removeEntity(entityId),\n *     }),\n *   },\n * });\n * ```\n */\nexport function createTimer(duration: number, options?: TimerOptions): Timer {\n\treturn {\n\t\telapsed: 0,\n\t\tduration,\n\t\trepeat: false,\n\t\tactive: true,\n\t\tjustFinished: false,\n\t\tonComplete: options?.onComplete,\n\t};\n}\n\n/**\n * Create a repeating `Timer` to drop into a `timers` slot. Fires\n * `justFinished` once per cycle and continues running.\n *\n * @example\n * ```typescript\n * ecs.spawn({\n *   carrier: true,\n *   timers: { hangarCycle: createRepeatingTimer(5.0) },\n * });\n * ```\n */\nexport function createRepeatingTimer(duration: number, options?: TimerOptions): Timer {\n\treturn {\n\t\telapsed: 0,\n\t\tduration,\n\t\trepeat: true,\n\t\tactive: true,\n\t\tjustFinished: false,\n\t\tonComplete: options?.onComplete,\n\t};\n}\n\n// ==================== Plugin Factory ====================\n\n/**\n * Create a timer plugin for ECSpresso.\n *\n * The plugin installs one update system that ticks every slot of every\n * `timers` component each frame. It does not touch entity lifecycle —\n * react to `justFinished` (or use `onComplete`) and despawn yourself if needed.\n *\n * @example\n * ```typescript\n * const ecs = ECSpresso.create()\n *   .withPlugin(createTimerPlugin())\n *   .withComponentTypes<{ spawner: true }>()\n *   .build();\n *\n * ecs.spawn({\n *   spawner: true,\n *   timers: { wave: createRepeatingTimer(5.0) },\n * });\n *\n * ecs.addSystem('spawn-on-timer')\n *   .addQuery('spawners', { with: ['timers', 'spawner'] })\n *   .setProcess(({ queries, ecs }) => {\n *     for (const { components } of queries.spawners) {\n *       if (components.timers.wave?.justFinished) {\n *         ecs.spawn({ enemy: true });\n *       }\n *     }\n *   });\n * ```\n */\nexport function createTimerPlugin<G extends string = 'timers'>(\n\toptions?: TimerPluginOptions<G>\n) {\n\tconst {\n\t\tsystemGroup = 'timers',\n\t\tpriority = 0,\n\t\tphase = 'preUpdate',\n\t} = options ?? {};\n\n\treturn definePlugin('timers')\n\t\t.withComponentTypes<TimerComponentTypes>()\n\t\t.withLabels<'timer-update'>()\n\t\t.withGroups<G>()\n\t\t.install((world) => {\n\t\t\tworld\n\t\t\t\t.addSystem('timer-update')\n\t\t\t\t.setPriority(priority)\n\t\t\t\t.inPhase(phase)\n\t\t\t\t.inGroup(systemGroup)\n\t\t\t\t.addQuery('timers', { with: ['timers'] })\n\t\t\t\t.setProcess(({ queries, dt }) => {\n\t\t\t\t\tfor (const entity of queries.timers) {\n\t\t\t\t\t\tconst slots = entity.components.timers;\n\t\t\t\t\t\tfor (const slot in slots) {\n\t\t\t\t\t\t\tconst timer = slots[slot];\n\t\t\t\t\t\t\tif (!timer) continue;\n\n\t\t\t\t\t\t\ttimer.justFinished = false;\n\t\t\t\t\t\t\tif (!timer.active) continue;\n\n\t\t\t\t\t\t\ttimer.elapsed += dt;\n\t\t\t\t\t\t\tif (timer.elapsed < timer.duration) continue;\n\n\t\t\t\t\t\t\tif (timer.repeat) {\n\t\t\t\t\t\t\t\twhile (timer.elapsed >= timer.duration) {\n\t\t\t\t\t\t\t\t\ttimer.justFinished = true;\n\t\t\t\t\t\t\t\t\ttimer.onComplete?.({\n\t\t\t\t\t\t\t\t\t\tentityId: entity.id,\n\t\t\t\t\t\t\t\t\t\tslot,\n\t\t\t\t\t\t\t\t\t\tduration: timer.duration,\n\t\t\t\t\t\t\t\t\t\telapsed: timer.elapsed,\n\t\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t\t\ttimer.elapsed -= timer.duration;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\ttimer.justFinished = true;\n\t\t\t\t\t\t\t\ttimer.onComplete?.({\n\t\t\t\t\t\t\t\t\tentityId: entity.id,\n\t\t\t\t\t\t\t\t\tslot,\n\t\t\t\t\t\t\t\t\tduration: timer.duration,\n\t\t\t\t\t\t\t\t\telapsed: timer.elapsed,\n\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t\ttimer.active = false;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t});\n}\n"
   ],
-  "mappings": "2PAOA,uBAAS,kBAqGF,SAAS,CAAW,CAC1B,EACA,EACqC,CACrC,MAAO,CACN,MAAO,CACN,QAAS,EACT,WACA,OAAQ,GACR,OAAQ,GACR,aAAc,GACd,WAAY,GAAS,UACtB,CACD,EAwBM,SAAS,CAAoB,CACnC,EACA,EACqC,CACrC,MAAO,CACN,MAAO,CACN,QAAS,EACT,WACA,OAAQ,GACR,OAAQ,GACR,aAAc,GACd,WAAY,GAAS,UACtB,CACD,EAsCM,SAAS,CAA8C,CAC7D,EACC,CACD,IACC,cAAc,SACd,WAAW,EACX,QAAQ,aACL,GAAW,CAAC,EAEhB,OAAO,EAAa,QAAQ,EAC1B,mBAAwC,EACxC,WAA2B,EAC3B,WAAc,EACd,QAAQ,CAAC,IAAU,CACnB,EACE,UAAU,cAAc,EACxB,YAAY,CAAQ,EACpB,QAAQ,CAAK,EACb,QAAQ,CAAW,EACnB,SAAS,SAAU,CACnB,KAAM,CAAC,OAAO,CACf,CAAC,EACA,WAAW,EAAG,UAAS,KAAI,SAAU,CACrC,QAAW,KAAU,EAAQ,OAAQ,CACpC,IAAQ,SAAU,EAAO,WAMzB,GAHA,EAAM,aAAe,GAGjB,CAAC,EAAM,OAAQ,SAMnB,GAHA,EAAM,SAAW,EAGb,EAAM,QAAU,EAAM,SAAU,SAGpC,GAAI,EAAM,OAET,MAAO,EAAM,SAAW,EAAM,SAC7B,EAAM,aAAe,GACrB,EAAM,aAAa,CAAE,SAAU,EAAO,GAAI,SAAU,EAAM,SAAU,QAAS,EAAM,OAAQ,CAAC,EAC5F,EAAM,SAAW,EAAM,SAIxB,OAAM,aAAe,GACrB,EAAM,aAAa,CAAE,SAAU,EAAO,GAAI,SAAU,EAAM,SAAU,QAAS,EAAM,OAAQ,CAAC,EAC5F,EAAM,OAAS,GAGf,EAAI,SAAS,aAAa,EAAO,EAAE,GAGrC,EACF",
-  "debugId": "7B8408B3E517C6C664756E2164756E21",
+  "mappings": "2PAUA,uBAAS,kBA+GF,SAAS,CAAW,CAAC,EAAkB,EAA+B,CAC5E,MAAO,CACN,QAAS,EACT,WACA,OAAQ,GACR,OAAQ,GACR,aAAc,GACd,WAAY,GAAS,UACtB,EAeM,SAAS,CAAoB,CAAC,EAAkB,EAA+B,CACrF,MAAO,CACN,QAAS,EACT,WACA,OAAQ,GACR,OAAQ,GACR,aAAc,GACd,WAAY,GAAS,UACtB,EAmCM,SAAS,CAA8C,CAC7D,EACC,CACD,IACC,cAAc,SACd,WAAW,EACX,QAAQ,aACL,GAAW,CAAC,EAEhB,OAAO,EAAa,QAAQ,EAC1B,mBAAwC,EACxC,WAA2B,EAC3B,WAAc,EACd,QAAQ,CAAC,IAAU,CACnB,EACE,UAAU,cAAc,EACxB,YAAY,CAAQ,EACpB,QAAQ,CAAK,EACb,QAAQ,CAAW,EACnB,SAAS,SAAU,CAAE,KAAM,CAAC,QAAQ,CAAE,CAAC,EACvC,WAAW,EAAG,UAAS,QAAS,CAChC,QAAW,KAAU,EAAQ,OAAQ,CACpC,IAAM,EAAQ,EAAO,WAAW,OAChC,QAAW,KAAQ,EAAO,CACzB,IAAM,EAAQ,EAAM,GACpB,GAAI,CAAC,EAAO,SAGZ,GADA,EAAM,aAAe,GACjB,CAAC,EAAM,OAAQ,SAGnB,GADA,EAAM,SAAW,EACb,EAAM,QAAU,EAAM,SAAU,SAEpC,GAAI,EAAM,OACT,MAAO,EAAM,SAAW,EAAM,SAC7B,EAAM,aAAe,GACrB,EAAM,aAAa,CAClB,SAAU,EAAO,GACjB,OACA,SAAU,EAAM,SAChB,QAAS,EAAM,OAChB,CAAC,EACD,EAAM,SAAW,EAAM,SAGxB,OAAM,aAAe,GACrB,EAAM,aAAa,CAClB,SAAU,EAAO,GACjB,OACA,SAAU,EAAM,SAChB,QAAS,EAAM,OAChB,CAAC,EACD,EAAM,OAAS,KAIlB,EACF",
+  "debugId": "03F5D4A1CC15EDC764756E2164756E21",
   "names": []
 }

package/dist/system-builder.d.ts

@@ -195,8 +195,14 @@ export declare class SystemBuilder<Cfg extends WorldConfig = EmptyConfig, Querie
      */
     setOnDetach(onDetach: LifecycleFunction<Cfg>): this;
     /**
-     * Set the onInitialize lifecycle hook
-     * Called when the system is initialized via ECSpresso.initialize() method
+     * Set the onInitialize lifecycle hook.
+     *
+     * Fires exactly once per system. For systems added before `initialize()`,
+     * the hook is awaited inside `initialize()` itself. For systems added
+     * after `initialize()` has returned, the hook fires on registration (at
+     * the next `update()`'s finalize step) — async hooks run fire-and-forget,
+     * so don't rely on completion ordering against the first `process` call.
+     *
      * @param onInitialize Function to run when this system is initialized
      * @returns This SystemBuilder instance for method chaining
      */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ecspresso",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"main": "dist/index.js",
 	"module": "dist/index.js",
 	"types": "dist/index.d.ts",