excalibur 0.32.0-alpha.1563 → 0.32.0-alpha.1565

package/CHANGELOG.md

@@ -15,6 +15,18 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- Added a convenience parameter to set the initial graphics or material in an Actor
+  ```typescript
+  const cloudSprite = cloud.toSprite();
+  const swirlMaterial = game.graphicsContext.createMaterial({
+    name: 'swirl',
+    fragmentSource
+  });
+  const actor = new ex.Actor({
+      graphic: cloudSprite,
+      material: swirlMaterial
+  });
+  ```
 - Simpler easing functions of the form `(currentTime: number) => number` instead of the 4 parameter legacy ones
 - Support for disabling integration for all offscreen entities, or on a per entity basis
 
@@ -38,6 +50,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
+- Fixed issue where overriding built in uniforms and graphics no longer worked as v0.30.x
 - Fixed issue where clearSchedule during a scheduled callback could cause a cb to be skipped
 - Fixed issue where the Loader could run twice even if already loaded when included in the scene loader.
 - Fixed issue where pixel ratio was accidentally doubled during load if the loader was included in the scene loader.
@@ -48,6 +61,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Updates
 
+- When overriding a built-in uniform/graphic there is now a warning in dev excalibur builds 
 - Camera zoom and move now support new easing functions form
 - MoveTo/MoveBy actions now support new easing function form
 - Transitions now support new easing functions form

package/build/dist/Actor.d.ts

@@ -24,6 +24,7 @@ import { ActionsComponent } from './Actions/ActionsComponent';
 import { CoordPlane } from './Math/coord-plane';
 import type { EventKey, Handler, Subscription } from './EventEmitter';
 import { EventEmitter } from './EventEmitter';
+import type { Graphic, Material } from './Graphics';
 /**
  * Type guard for checking if something is an Actor
  * @param x
@@ -82,6 +83,14 @@ export type ActorArgs = ColliderArgs & {
      * If a width/height or a radius was set a default graphic will be added
      */
     color?: Color;
+    /**
+     * Optionally set the default graphic
+     */
+    graphic?: Graphic;
+    /**
+     * Optionally set the default material
+     */
+    material?: Material;
     /**
      * Optionally set the color of an actor, only used if no graphics are present
      * If a width/height or a radius was set a default graphic will be added

package/build/dist/Graphics/Context/material.d.ts

@@ -75,6 +75,7 @@ export interface MaterialImageOptions {
     filtering?: ImageFiltering;
 }
 export declare class Material {
+    static BuiltInUniforms: string[];
     private _logger;
     private _name;
     private _shader;
@@ -92,6 +93,7 @@ export declare class Material {
     set color(c: Color);
     get name(): string;
     get isUsingScreenTexture(): boolean;
+    get isOverridingGraphic(): boolean;
     update(callback: (shader: Shader) => any): void;
     getShader(): Shader | null;
     addImageSource(samplerName: string, image: ImageSource): void;

package/build/dist/excalibur.development.js

@@ -1,4 +1,4 @@
-/*! excalibur - 0.32.0-alpha.1563+eadef91 - 2025-11-24
+/*! excalibur - 0.32.0-alpha.1565+76be137 - 2025-11-24
 https://github.com/excaliburjs/Excalibur
 Copyright (c) 2025 Excalibur.js <https://github.com/excaliburjs/Excalibur/graphs/contributors>
 Licensed BSD-2-Clause
@@ -14358,7 +14358,7 @@ void main() {
   v_screenuv = a_screenuv;
 }
 `;
-  class Material {
+  const _Material = class _Material2 {
     constructor(options) {
       this._logger = Logger.getInstance();
       this._color = Color.Transparent;
@@ -14380,6 +14380,25 @@ void main() {
       } else {
         this._logger.warn(`Material ${name} was created in 2D Canvas mode, currently only WebGL is supported`);
       }
+      {
+        if (this.images.u_graphic) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_graphic, is this on purpose? If so ignore this warning.`
+          );
+        }
+        if (this.images.u_screen_texture) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_screen_texture, is this on purpose? If so ignore this warning.`
+          );
+        }
+        for (const uniform of Object.keys(this._uniforms)) {
+          if (_Material2.BuiltInUniforms.includes(uniform)) {
+            this._logger.warn(
+              `Material named "${this.name}" is overriding built in uniform ${uniform}, is this on purpose? If so ignore this warning.`
+            );
+          }
+        }
+      }
     }
     _initialize(graphicsContextWebGL) {
       if (this._initialized) {
@@ -14416,6 +14435,9 @@ void main() {
     get isUsingScreenTexture() {
       return this._fragmentSource.includes("u_screen_texture");
     }
+    get isOverridingGraphic() {
+      return !!this._images.u_graphic;
+    }
     update(callback) {
       if (this._shader) {
         this._shader.use();
@@ -14427,6 +14449,18 @@ void main() {
     }
     addImageSource(samplerName, image) {
       this._shader.addImageSource(samplerName, image);
+      {
+        if (this.images.u_graphic) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_graphic, is this on purpose? If so ignore this warning.`
+          );
+        }
+        if (this.images.u_screen_texture) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_screen_texture, is this on purpose? If so ignore this warning.`
+          );
+        }
+      }
     }
     removeImageSource(samplerName) {
       this._shader.removeImageSource(samplerName);
@@ -14439,7 +14473,19 @@ void main() {
         throw Error(`Material ${this.name} not yet initialized, use the ExcaliburGraphicsContext.createMaterial() to work around this.`);
       }
     }
-  }
+  };
+  _Material.BuiltInUniforms = [
+    "u_time_ms",
+    "u_opacity",
+    "u_resolution",
+    "u_graphic_resolution",
+    "u_size",
+    "u_matrix",
+    "u_transform",
+    "u_graphic",
+    "u_screen_texture"
+  ];
+  let Material = _Material;
   const _Debug = class _Debug2 {
     static registerGraphicsContext(ctx) {
       _Debug2._ctx = ctx;
@@ -15555,7 +15601,7 @@ void main() {
       this._gl = null;
     }
     draw(image, sx, sy, swidth, sheight, dx, dy, dwidth, dheight) {
-      var _a, _b, _c, _d;
+      var _a, _b, _c, _d, _e;
       const gl = this._gl;
       const material = this._context.material;
       if (!material) {
@@ -15620,7 +15666,7 @@ void main() {
       vertexBuffer[vertexIndex++] = uvy1;
       vertexBuffer[vertexIndex++] = screenUVX1;
       vertexBuffer[vertexIndex++] = screenUVY1;
-      const texture = this._addImageAsTexture(image);
+      let texture = this._addImageAsTexture(image);
       material.use();
       this._layout.shader = shader;
       this._layout.use(true);
@@ -15631,6 +15677,11 @@ void main() {
       shader.trySetUniformFloatVector("u_size", vec(sw, sh));
       shader.trySetUniformMatrix("u_matrix", this._context.ortho);
       shader.trySetUniformMatrix("u_transform", transform.to4x4());
+      if (material.isOverridingGraphic) {
+        if ((_e = material.images.u_graphic) == null ? void 0 : _e.image) {
+          texture = this._addImageAsTexture(material.images.u_graphic.image);
+        }
+      }
       gl.activeTexture(gl.TEXTURE0 + 0);
       gl.bindTexture(gl.TEXTURE_2D, texture);
       shader.trySetUniformInt("u_graphic", 0);
@@ -19416,7 +19467,9 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         anchor,
         offset,
         collisionType,
-        collisionGroup
+        collisionGroup,
+        graphic,
+        material
       } = {
         ...config
       };
@@ -19487,6 +19540,12 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         }
       }
       this.graphics.isVisible = visible != null ? visible : true;
+      if (graphic) {
+        this.graphics.use(graphic);
+      }
+      if (material) {
+        this.graphics.material = material;
+      }
     }
     /**
      * Gets the position vector of the actor in pixels
@@ -33043,7 +33102,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
       this._count += count;
     }
   }
-  const EX_VERSION = "0.32.0-alpha.1563+eadef91";
+  const EX_VERSION = "0.32.0-alpha.1565+76be137";
   polyfill();
   exports2.ActionCompleteEvent = ActionCompleteEvent;
   exports2.ActionContext = ActionContext;

package/build/dist/excalibur.js

@@ -1,4 +1,4 @@
-/*! excalibur - 0.32.0-alpha.1563+eadef91 - 2025-11-24
+/*! excalibur - 0.32.0-alpha.1565+76be137 - 2025-11-24
 https://github.com/excaliburjs/Excalibur
 Copyright (c) 2025 Excalibur.js <https://github.com/excaliburjs/Excalibur/graphs/contributors>
 Licensed BSD-2-Clause
@@ -14358,7 +14358,7 @@ void main() {
   v_screenuv = a_screenuv;
 }
 `;
-  class Material {
+  const _Material = class _Material2 {
     constructor(options) {
       this._logger = Logger.getInstance();
       this._color = Color.Transparent;
@@ -14380,6 +14380,25 @@ void main() {
       } else {
         this._logger.warn(`Material ${name} was created in 2D Canvas mode, currently only WebGL is supported`);
       }
+      {
+        if (this.images.u_graphic) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_graphic, is this on purpose? If so ignore this warning.`
+          );
+        }
+        if (this.images.u_screen_texture) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_screen_texture, is this on purpose? If so ignore this warning.`
+          );
+        }
+        for (const uniform of Object.keys(this._uniforms)) {
+          if (_Material2.BuiltInUniforms.includes(uniform)) {
+            this._logger.warn(
+              `Material named "${this.name}" is overriding built in uniform ${uniform}, is this on purpose? If so ignore this warning.`
+            );
+          }
+        }
+      }
     }
     _initialize(graphicsContextWebGL) {
       if (this._initialized) {
@@ -14416,6 +14435,9 @@ void main() {
     get isUsingScreenTexture() {
       return this._fragmentSource.includes("u_screen_texture");
     }
+    get isOverridingGraphic() {
+      return !!this._images.u_graphic;
+    }
     update(callback) {
       if (this._shader) {
         this._shader.use();
@@ -14427,6 +14449,18 @@ void main() {
     }
     addImageSource(samplerName, image) {
       this._shader.addImageSource(samplerName, image);
+      {
+        if (this.images.u_graphic) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_graphic, is this on purpose? If so ignore this warning.`
+          );
+        }
+        if (this.images.u_screen_texture) {
+          this._logger.warn(
+            `Material named "${this.name}" is overriding built in image u_screen_texture, is this on purpose? If so ignore this warning.`
+          );
+        }
+      }
     }
     removeImageSource(samplerName) {
       this._shader.removeImageSource(samplerName);
@@ -14439,7 +14473,19 @@ void main() {
         throw Error(`Material ${this.name} not yet initialized, use the ExcaliburGraphicsContext.createMaterial() to work around this.`);
       }
     }
-  }
+  };
+  _Material.BuiltInUniforms = [
+    "u_time_ms",
+    "u_opacity",
+    "u_resolution",
+    "u_graphic_resolution",
+    "u_size",
+    "u_matrix",
+    "u_transform",
+    "u_graphic",
+    "u_screen_texture"
+  ];
+  let Material = _Material;
   const _Debug = class _Debug2 {
     static registerGraphicsContext(ctx) {
       _Debug2._ctx = ctx;
@@ -15555,7 +15601,7 @@ void main() {
       this._gl = null;
     }
     draw(image, sx, sy, swidth, sheight, dx, dy, dwidth, dheight) {
-      var _a, _b, _c, _d;
+      var _a, _b, _c, _d, _e;
       const gl = this._gl;
       const material = this._context.material;
       if (!material) {
@@ -15620,7 +15666,7 @@ void main() {
       vertexBuffer[vertexIndex++] = uvy1;
       vertexBuffer[vertexIndex++] = screenUVX1;
       vertexBuffer[vertexIndex++] = screenUVY1;
-      const texture = this._addImageAsTexture(image);
+      let texture = this._addImageAsTexture(image);
       material.use();
       this._layout.shader = shader;
       this._layout.use(true);
@@ -15631,6 +15677,11 @@ void main() {
       shader.trySetUniformFloatVector("u_size", vec(sw, sh));
       shader.trySetUniformMatrix("u_matrix", this._context.ortho);
       shader.trySetUniformMatrix("u_transform", transform.to4x4());
+      if (material.isOverridingGraphic) {
+        if ((_e = material.images.u_graphic) == null ? void 0 : _e.image) {
+          texture = this._addImageAsTexture(material.images.u_graphic.image);
+        }
+      }
       gl.activeTexture(gl.TEXTURE0 + 0);
       gl.bindTexture(gl.TEXTURE_2D, texture);
       shader.trySetUniformInt("u_graphic", 0);
@@ -19416,7 +19467,9 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         anchor,
         offset,
         collisionType,
-        collisionGroup
+        collisionGroup,
+        graphic,
+        material
       } = {
         ...config
       };
@@ -19487,6 +19540,12 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         }
       }
       this.graphics.isVisible = visible != null ? visible : true;
+      if (graphic) {
+        this.graphics.use(graphic);
+      }
+      if (material) {
+        this.graphics.material = material;
+      }
     }
     /**
      * Gets the position vector of the actor in pixels
@@ -33043,7 +33102,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
       this._count += count;
     }
   }
-  const EX_VERSION = "0.32.0-alpha.1563+eadef91";
+  const EX_VERSION = "0.32.0-alpha.1565+76be137";
   polyfill();
   exports2.ActionCompleteEvent = ActionCompleteEvent;
   exports2.ActionContext = ActionContext;