excalibur 0.32.0-alpha.1591 → 0.32.0-alpha.1593

package/CHANGELOG.md

@@ -17,6 +17,23 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 
+- Added new Timer events! 
+  ```typescript
+  const timer = new ex.Timer({...});
+  timer.events.on('complete', () => {...}); // after the last repeat
+  timer.events.on('action', () => {...}); // every fire of the timer
+  timer.events.on('start', () => {...}); // after the timer is started
+  timer.events.on('stop', () => {...}); // after the timer is stopped 
+  timer.events.on('pause', () => {...}); // after every pause
+  timer.events.on('resume', () => {...}); // after every resume
+  timer.events.on('cancel', () => {...}); // after cancel
+
+  // or specify the onComplete in the constructor
+  const timer2 = new ex.Timer({
+      onComplete: () => {...},
+      ...
+  });
+  ```
 - Added a way to configure general debug settings on text
   ```typescript
   class DebugConfig { 

package/build/dist/Graphics/SpriteSheet.d.ts

@@ -1,4 +1,4 @@
-import type { ImageSource } from './ImageSource';
+import { ImageSource } from './ImageSource';
 import type { SourceView } from './Sprite';
 import { Sprite } from './Sprite';
 import type { GraphicOptions } from './Graphic';
@@ -130,6 +130,19 @@ export declare class SpriteSheet {
      * @param options
      */
     getTiledSprite(x: number, y: number, options?: Partial<Omit<TiledSpriteOptions & GraphicOptions, 'image'>>): TiledSprite;
+    /**
+     * Returns a sprite that has a new backing image the exact size of the sprite that tha is a copy of the original sprite slice.
+     *
+     * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+     *
+     */
+    getSpriteAsStandalone(x: number, y: number): Promise<Sprite>;
+    /**
+     * Returns a new image exact size and copy of the original sprite slice.
+     *
+     * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+     */
+    getSpriteAsImage(x: number, y: number): Promise<HTMLImageElement>;
     /**
      * Create a sprite sheet from a sparse set of {@apilink SourceView} rectangles
      * @param options

package/build/dist/Timer.d.ts

@@ -1,5 +1,26 @@
 import type { Scene } from './Scene';
 import type * as ex from './index';
+/**
+ * Built in events supported by all entities
+ */
+export interface TimerEvents {
+    start: void;
+    stop: void;
+    pause: void;
+    resume: void;
+    cancel: void;
+    action: void;
+    complete: void;
+}
+export declare const TimerEvents: {
+    readonly Start: "start";
+    readonly Stop: "stop";
+    readonly Pause: "pause";
+    readonly Resume: "resume";
+    readonly Cancel: "cancel";
+    readonly Action: "action";
+    readonly Complete: "complete";
+};
 export interface TimerOptions {
     /**
      * If true the timer repeats every interval infinitely
@@ -29,6 +50,10 @@ export interface TimerOptions {
      * Optionally provide a random instance to use for random behavior, otherwise a new random will be created seeded from the current time.
      */
     random?: ex.Random;
+    /**
+     * Optionally provide a callback to fire once when the timer completes its last action callback.
+     */
+    onComplete?: () => void;
 }
 /**
  * The Excalibur timer hooks into the internal timer and fires callbacks,
@@ -38,6 +63,7 @@ export declare class Timer {
     private _logger;
     private static _MAX_ID;
     id: number;
+    events: ex.EventEmitter<ex.TimerEvents>;
     private _elapsedTime;
     private _totalTimeAlive;
     private _running;
@@ -50,6 +76,7 @@ export declare class Timer {
     random: ex.Random;
     private _baseInterval;
     private _generateRandomInterval;
+    private _onComplete;
     private _complete;
     get complete(): boolean;
     scene: Scene;

package/build/dist/excalibur.development.js

@@ -1,4 +1,4 @@
-/*! excalibur - 0.32.0-alpha.1591+851fc99 - 2025-12-6
+/*! excalibur - 0.32.0-alpha.1593+0f899e4 - 2025-12-6
 https://github.com/excaliburjs/Excalibur
 Copyright (c) 2025 Excalibur.js <https://github.com/excaliburjs/Excalibur/graphs/contributors>
 Licensed BSD-2-Clause
@@ -11212,6 +11212,104 @@ Read more here: https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL
       }
       throw Error(`Invalid sprite coordinates (${x}, ${y})`);
     }
+    /**
+     * Returns a sprite that has a new backing image the exact size of the sprite that tha is a copy of the original sprite slice.
+     *
+     * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+     *
+     */
+    async getSpriteAsStandalone(x, y) {
+      if (x >= this.columns || x < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), x: ${x} should be between 0 and ${this.columns - 1} columns`);
+      }
+      if (y >= this.rows || y < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), y: ${y} should be between 0 and ${this.rows - 1} rows`);
+      }
+      const spriteIndex = x + y * this.columns;
+      const sprite = this.sprites[spriteIndex];
+      const cnv = document.createElement("canvas");
+      const ctx = cnv.getContext("2d");
+      cnv.width = sprite.width;
+      cnv.height = sprite.height;
+      if (!sprite) {
+        throw Error(`Invalid sprite coordinates (${x}, ${y})`);
+      }
+      if (!ctx) {
+        throw Error("Unable to create canvas context");
+      }
+      ctx.drawImage(
+        sprite.image.image,
+        sprite.sourceView.x,
+        sprite.sourceView.y,
+        sprite.sourceView.width,
+        sprite.sourceView.height,
+        0,
+        0,
+        sprite.sourceView.width,
+        sprite.sourceView.height
+      );
+      const imgSrc = new ImageSource(cnv.toDataURL());
+      await imgSrc.load();
+      return new Sprite({
+        image: imgSrc,
+        sourceView: {
+          x: 0,
+          y: 0,
+          width: sprite.width,
+          height: sprite.height
+        },
+        destSize: {
+          width: sprite.width,
+          height: sprite.height
+        }
+      });
+    }
+    /**
+     * Returns a new image exact size and copy of the original sprite slice.
+     *
+     * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+     */
+    async getSpriteAsImage(x, y) {
+      if (x >= this.columns || x < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), x: ${x} should be between 0 and ${this.columns - 1} columns`);
+      }
+      if (y >= this.rows || y < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), y: ${y} should be between 0 and ${this.rows - 1} rows`);
+      }
+      const spriteIndex = x + y * this.columns;
+      const sprite = this.sprites[spriteIndex];
+      const cnv = document.createElement("canvas");
+      const ctx = cnv.getContext("2d");
+      cnv.width = sprite.width;
+      cnv.height = sprite.height;
+      if (!sprite) {
+        throw Error(`Invalid sprite coordinates (${x}, ${y})`);
+      }
+      if (!ctx) {
+        throw Error("Unable to create canvas context");
+      }
+      ctx.drawImage(
+        sprite.image.image,
+        sprite.sourceView.x,
+        sprite.sourceView.y,
+        sprite.sourceView.width,
+        sprite.sourceView.height,
+        0,
+        0,
+        sprite.sourceView.width,
+        sprite.sourceView.height
+      );
+      const imgSrc = new Image(sprite.width, sprite.height);
+      imgSrc.src = cnv.toDataURL();
+      return await new Promise((resolve, reject) => {
+        imgSrc.onload = () => {
+          resolve(imgSrc);
+        };
+        imgSrc.onerror = (e) => {
+          reject(e);
+        };
+      });
+    }
     /**
      * Create a sprite sheet from a sparse set of {@apilink SourceView} rectangles
      * @param options
@@ -24706,10 +24804,20 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       return super.contains(coords.x, coords.y);
     }
   }
+  const TimerEvents = {
+    Start: "start",
+    Stop: "stop",
+    Pause: "pause",
+    Resume: "resume",
+    Cancel: "cancel",
+    Action: "action",
+    Complete: "complete"
+  };
   const _Timer = class _Timer2 {
     constructor(options) {
       this._logger = Logger.getInstance();
       this.id = 0;
+      this.events = new EventEmitter();
       this._elapsedTime = 0;
       this._totalTimeAlive = 0;
       this._running = false;
@@ -24722,15 +24830,18 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this._generateRandomInterval = () => {
         return this._baseInterval + this.random.integer(this.randomRange[0], this.randomRange[1]);
       };
+      this._onComplete = () => {
+      };
       this._complete = false;
       this.scene = null;
-      var _a;
+      var _a, _b;
       const fcn = (_a = options.action) != null ? _a : options.fcn;
       const interval = options.interval;
       const repeats = options.repeats;
       const numberOfRepeats = options.numberOfRepeats;
       const randomRange = options.randomRange;
       const random = options.random;
+      this._onComplete = (_b = options.onComplete) != null ? _b : this._onComplete;
       if (!!numberOfRepeats && numberOfRepeats >= 0) {
         this.maxNumberOfRepeats = numberOfRepeats;
         if (!repeats) {
@@ -24786,18 +24897,23 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
           this._complete = true;
           this._running = false;
           this._elapsedTime = 0;
+          this._onComplete();
+          this.events.emit("complete");
         }
         if (!this.complete && this._elapsedTime >= this.interval) {
           this._callbacks.forEach((c) => {
             c.call(this);
           });
           this._numberOfTicks++;
+          this.events.emit("action");
           if (this.repeats) {
             this._elapsedTime = 0;
           } else {
             this._complete = true;
             this._running = false;
             this._elapsedTime = 0;
+            this._onComplete();
+            this.events.emit("complete");
           }
         }
       }
@@ -24852,6 +24968,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
      */
     pause() {
       this._running = false;
+      this.events.emit("pause");
       return this;
     }
     /**
@@ -24859,6 +24976,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
      */
     resume() {
       this._running = true;
+      this.events.emit("resume");
       return this;
     }
     /**
@@ -24873,6 +24991,8 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         this._complete = false;
         this._elapsedTime = 0;
         this._numberOfTicks = 0;
+      } else {
+        this.events.emit("start");
       }
       return this;
     }
@@ -24883,6 +25003,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this._running = false;
       this._elapsedTime = 0;
       this._numberOfTicks = 0;
+      this.events.emit("stop");
       return this;
     }
     /**
@@ -24892,6 +25013,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this.pause();
       if (this.scene) {
         this.scene.cancelTimer(this);
+        this.events.emit("cancel");
       }
     }
   };
@@ -33472,7 +33594,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
       this._count += count;
     }
   }
-  const EX_VERSION = "0.32.0-alpha.1591+851fc99";
+  const EX_VERSION = "0.32.0-alpha.1593+0f899e4";
   polyfill();
   exports2.ActionCompleteEvent = ActionCompleteEvent;
   exports2.ActionContext = ActionContext;
@@ -33771,6 +33893,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
   exports2.TiledAnimation = TiledAnimation;
   exports2.TiledSprite = TiledSprite;
   exports2.Timer = Timer;
+  exports2.TimerEvents = TimerEvents;
   exports2.Toaster = Toaster;
   exports2.Transform = Transform;
   exports2.TransformComponent = TransformComponent;

package/build/dist/excalibur.js

@@ -1,4 +1,4 @@
-/*! excalibur - 0.32.0-alpha.1591+851fc99 - 2025-12-6
+/*! excalibur - 0.32.0-alpha.1593+0f899e4 - 2025-12-6
 https://github.com/excaliburjs/Excalibur
 Copyright (c) 2025 Excalibur.js <https://github.com/excaliburjs/Excalibur/graphs/contributors>
 Licensed BSD-2-Clause
@@ -11212,6 +11212,104 @@ Read more here: https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL
       }
       throw Error(`Invalid sprite coordinates (${x}, ${y})`);
     }
+    /**
+     * Returns a sprite that has a new backing image the exact size of the sprite that tha is a copy of the original sprite slice.
+     *
+     * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+     *
+     */
+    async getSpriteAsStandalone(x, y) {
+      if (x >= this.columns || x < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), x: ${x} should be between 0 and ${this.columns - 1} columns`);
+      }
+      if (y >= this.rows || y < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), y: ${y} should be between 0 and ${this.rows - 1} rows`);
+      }
+      const spriteIndex = x + y * this.columns;
+      const sprite = this.sprites[spriteIndex];
+      const cnv = document.createElement("canvas");
+      const ctx = cnv.getContext("2d");
+      cnv.width = sprite.width;
+      cnv.height = sprite.height;
+      if (!sprite) {
+        throw Error(`Invalid sprite coordinates (${x}, ${y})`);
+      }
+      if (!ctx) {
+        throw Error("Unable to create canvas context");
+      }
+      ctx.drawImage(
+        sprite.image.image,
+        sprite.sourceView.x,
+        sprite.sourceView.y,
+        sprite.sourceView.width,
+        sprite.sourceView.height,
+        0,
+        0,
+        sprite.sourceView.width,
+        sprite.sourceView.height
+      );
+      const imgSrc = new ImageSource(cnv.toDataURL());
+      await imgSrc.load();
+      return new Sprite({
+        image: imgSrc,
+        sourceView: {
+          x: 0,
+          y: 0,
+          width: sprite.width,
+          height: sprite.height
+        },
+        destSize: {
+          width: sprite.width,
+          height: sprite.height
+        }
+      });
+    }
+    /**
+     * Returns a new image exact size and copy of the original sprite slice.
+     *
+     * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+     */
+    async getSpriteAsImage(x, y) {
+      if (x >= this.columns || x < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), x: ${x} should be between 0 and ${this.columns - 1} columns`);
+      }
+      if (y >= this.rows || y < 0) {
+        throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), y: ${y} should be between 0 and ${this.rows - 1} rows`);
+      }
+      const spriteIndex = x + y * this.columns;
+      const sprite = this.sprites[spriteIndex];
+      const cnv = document.createElement("canvas");
+      const ctx = cnv.getContext("2d");
+      cnv.width = sprite.width;
+      cnv.height = sprite.height;
+      if (!sprite) {
+        throw Error(`Invalid sprite coordinates (${x}, ${y})`);
+      }
+      if (!ctx) {
+        throw Error("Unable to create canvas context");
+      }
+      ctx.drawImage(
+        sprite.image.image,
+        sprite.sourceView.x,
+        sprite.sourceView.y,
+        sprite.sourceView.width,
+        sprite.sourceView.height,
+        0,
+        0,
+        sprite.sourceView.width,
+        sprite.sourceView.height
+      );
+      const imgSrc = new Image(sprite.width, sprite.height);
+      imgSrc.src = cnv.toDataURL();
+      return await new Promise((resolve, reject) => {
+        imgSrc.onload = () => {
+          resolve(imgSrc);
+        };
+        imgSrc.onerror = (e) => {
+          reject(e);
+        };
+      });
+    }
     /**
      * Create a sprite sheet from a sparse set of {@apilink SourceView} rectangles
      * @param options
@@ -24706,10 +24804,20 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       return super.contains(coords.x, coords.y);
     }
   }
+  const TimerEvents = {
+    Start: "start",
+    Stop: "stop",
+    Pause: "pause",
+    Resume: "resume",
+    Cancel: "cancel",
+    Action: "action",
+    Complete: "complete"
+  };
   const _Timer = class _Timer2 {
     constructor(options) {
       this._logger = Logger.getInstance();
       this.id = 0;
+      this.events = new EventEmitter();
       this._elapsedTime = 0;
       this._totalTimeAlive = 0;
       this._running = false;
@@ -24722,15 +24830,18 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this._generateRandomInterval = () => {
         return this._baseInterval + this.random.integer(this.randomRange[0], this.randomRange[1]);
       };
+      this._onComplete = () => {
+      };
       this._complete = false;
       this.scene = null;
-      var _a;
+      var _a, _b;
       const fcn = (_a = options.action) != null ? _a : options.fcn;
       const interval = options.interval;
       const repeats = options.repeats;
       const numberOfRepeats = options.numberOfRepeats;
       const randomRange = options.randomRange;
       const random = options.random;
+      this._onComplete = (_b = options.onComplete) != null ? _b : this._onComplete;
       if (!!numberOfRepeats && numberOfRepeats >= 0) {
         this.maxNumberOfRepeats = numberOfRepeats;
         if (!repeats) {
@@ -24786,18 +24897,23 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
           this._complete = true;
           this._running = false;
           this._elapsedTime = 0;
+          this._onComplete();
+          this.events.emit("complete");
         }
         if (!this.complete && this._elapsedTime >= this.interval) {
           this._callbacks.forEach((c) => {
             c.call(this);
           });
           this._numberOfTicks++;
+          this.events.emit("action");
           if (this.repeats) {
             this._elapsedTime = 0;
           } else {
             this._complete = true;
             this._running = false;
             this._elapsedTime = 0;
+            this._onComplete();
+            this.events.emit("complete");
           }
         }
       }
@@ -24852,6 +24968,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
      */
     pause() {
       this._running = false;
+      this.events.emit("pause");
       return this;
     }
     /**
@@ -24859,6 +24976,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
      */
     resume() {
       this._running = true;
+      this.events.emit("resume");
       return this;
     }
     /**
@@ -24873,6 +24991,8 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         this._complete = false;
         this._elapsedTime = 0;
         this._numberOfTicks = 0;
+      } else {
+        this.events.emit("start");
       }
       return this;
     }
@@ -24883,6 +25003,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this._running = false;
       this._elapsedTime = 0;
       this._numberOfTicks = 0;
+      this.events.emit("stop");
       return this;
     }
     /**
@@ -24892,6 +25013,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this.pause();
       if (this.scene) {
         this.scene.cancelTimer(this);
+        this.events.emit("cancel");
       }
     }
   };
@@ -33472,7 +33594,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
       this._count += count;
     }
   }
-  const EX_VERSION = "0.32.0-alpha.1591+851fc99";
+  const EX_VERSION = "0.32.0-alpha.1593+0f899e4";
   polyfill();
   exports2.ActionCompleteEvent = ActionCompleteEvent;
   exports2.ActionContext = ActionContext;
@@ -33771,6 +33893,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
   exports2.TiledAnimation = TiledAnimation;
   exports2.TiledSprite = TiledSprite;
   exports2.Timer = Timer;
+  exports2.TimerEvents = TimerEvents;
   exports2.Toaster = Toaster;
   exports2.Transform = Transform;
   exports2.TransformComponent = TransformComponent;