refactor: Graphics Component simplification (#2893)

This PR refactors the `GraphicsComponent` to be simpler.

1. Remove confusing Graphics Layering from `ex.GraphicsComponent`, recommend we use the `ex.GraphicsGroup` to manage this behavior

2. Update `ex.GraphicsGroup` to be consistent and use `offset` instead of `pos` for graphics relative positioning

CHANGELOG.md

@@ -8,7 +8,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Breaking Changes
 
--
+- Remove confusing Graphics Layering from `ex.GraphicsComponent`, recommend we use the `ex.GraphicsGroup` to manage this behavior
+  * Update `ex.GraphicsGroup` to be consistent and use `offset` instead of `pos` for graphics relative positioning
 
 ### Deprecated
 

sandbox/src/game.ts

@@ -303,35 +303,35 @@ var group = new ex.GraphicsGroup({
   members: [
     {
       graphic: newSprite,
-      pos: ex.vec(0, 0)
+      offset: ex.vec(0, 0)
     },
     {
       graphic: newSprite,
-      pos: ex.vec(50, 0)
+      offset: ex.vec(50, 0)
     },
     {
       graphic: newSprite,
-      pos: ex.vec(0, 50)
+      offset: ex.vec(0, 50)
     },
     {
       graphic: text,
-      pos: ex.vec(100, 20)
+      offset: ex.vec(100, 20)
     },
     {
       graphic: circle,
-      pos: ex.vec(50, 50)
+      offset: ex.vec(50, 50)
     },
     {
       graphic: anim,
-      pos: ex.vec(200, 200)
+      offset: ex.vec(200, 200)
     },
     {
       graphic: cardAnimation,
-      pos: ex.vec(0, 200)
+      offset: ex.vec(0, 200)
     },
     {
       graphic: spriteText,
-      pos: ex.vec(300, 200)
+      offset: ex.vec(300, 200)
     }
   ]
 });
@@ -618,21 +618,31 @@ var healthbar2 = new ex.Rectangle({
   color: new ex.Color(0, 255, 0)
 });
 
-var backroundLayer = player.graphics.layers.create({
-  name: 'background',
-  order: -1
-});
-
-backroundLayer.show(healthbar2, { offset: ex.vec(0, -70) });
 var playerText = new ex.Text({
   text: 'A long piece of text is long',
   font: new ex.Font({
     size: 20,
     family: 'Times New Roman'
   })
 });
-// playerText.showDebug = true;
-backroundLayer.show(playerText, { offset: ex.vec(0, -70) });
+
+var group = new ex.GraphicsGroup({
+  members: [
+    { graphic: healthbar2, offset: ex.vec(0, -70)},
+    { graphic: playerText, offset: ex.vec(0, -70)}
+  ]
+})
+healthbar.graphics.use(group);
+
+// var backgroundLayer = player.graphics.layers.create({
+//   name: 'background',
+//   order: -1
+// });
+
+// backgroundLayer.show(healthbar2, { offset: ex.vec(0, -70) });
+
+// // playerText.showDebug = true;
+// backgroundLayer.show(playerText, { offset: ex.vec(0, -70) });
 
 // Retrieve animations for player from sprite sheet
 var left = ex.Animation.fromSpriteSheet(spriteSheetRun, ex.range(1, 10), 50);

sandbox/tests/material/index.ts

@@ -266,6 +266,7 @@ void main() {
   
   fragColor.rgb = mix(screen_color.rgb, mixColor, u_color.a)*fragColor.a + (wave_crest_color.rgb * wave_crest);
   fragColor.rgb = texture(u_noise, v_uv).rgb * fragColor.a;
+  fragColor.rgb = vec3(gl_FragCoord.xy/u_resolution, 0.0);
 }`;
 
 const noise = new ex.ImageSource('./noise.avif', false, ex.ImageFiltering.Pixel);

sandbox/tests/sprite-tint/index.ts

@@ -38,8 +38,14 @@ actor.onInitialize = () => {
     })
   );
 
-  actor.graphics.show(shadow, {offset: ex.vec(10, 10)});
-  actor.graphics.show(sprite);
+  const group = new ex.GraphicsGroup({
+    members: [
+      {graphic: shadow, offset: ex.vec(10, 10)},
+      sprite
+    ]
+  })
+
+  actor.graphics.use(group);
 };
 
 

site/docs/04-graphics/04.2-graphics-component.mdx

@@ -84,27 +84,78 @@ actor.graphics.onPostDraw = (ctx: ex.ExcaliburGraphicsContext) => {
 }
 ```
 
-### Layers
+### Multiple Graphics at Once
 
-The layer's component adds a way for multiple [graphics](#graphics) to be on top or behind each other for a certain actor or entity.
+Sometimes you want to draw multiple pieces of graphics at once! There are two recommended ways to accomplish this!
 
-Layers can be ordered numerically, larger negative layers behind, and positive layers in front.
+#### GraphicsGroup
 
-```typescript
-actor.graphics.layers.create({ name: 'background', order: -1 })
-actor.graphics.layers.create({ name: 'foreground', order: 1 })
-
-actor.graphics.layers.get('background').show(myBackground)
-actor.graphics.layers.get('foreground').show(myForeground)
+[[GraphicsGroup|Graphics groups]] allow you to compose multiple graphics together into 1. This can be useful if you have multi layered or complex graphics requirements. One limitation however is you can only influence the relative offset from you Actor.
 
-// no longer display the background
-actor.graphics.layers.get('background').hide()
+```typescript
+const healthBarActor = new ex.Actor({...})
+
+const healthBarRectangle = new ex.Rectangle({
+  width: 140,
+  height: 5,
+  color: new ex.Color(0, 255, 0)
+});
+
+const healthBarText = new ex.Text({
+  text: 'A long piece of text is long',
+  font: new ex.Font({
+    size: 20,
+    family: 'Times New Roman'
+  })
+});
+
+const group = new ex.GraphicsGroup({
+  members: [
+    { graphic: healthbarRectangle, pos: ex.vec(0, -70)},
+    { graphic: healthBarText, pos: ex.vec(0, -70)}
+  ]
+});
+
+healthBarActor.graphics.use(group);
 ```
 
-There is always a layer named `'default'` at `order: 0`
+#### Child Actor or Entity
+
+If you need independent articulation and a lot of control over positioning, rotation, and scale this is this strategy to reach for. One example is you might have a main actor, and a child actor for every limb of a paper doll.
 
 ```typescript
-actor.graphics.show(myAnimation)
-// is equivalent to
-actor.graphics.layers.get('default').show(myAnimation)
+
+import { Resources } from './Resources';
+
+class PaperDoll extends ex.Actor {
+  this.leftArm = new ex.Actor({
+    pos: ex.vec(-10, 10)
+  });
+  this.rightArm = new ex.Actor({
+    pos: ex.vec(10, 10)
+  });
+  this.head = new ex.Actor({
+    pos: ex.vec(0, -10)
+  });
+  this.body = new ex.Actor({
+    pos: ex.vec(0, 20)
+  });
+  this.leftLeg = new ex.Actor({
+    pos: ex.vec(-10, 30)
+  });
+  this.rightLeg = new ex.Actor({
+    pos: ex.vec(10, 30)
+  });
+
+  constructor() {
+    this.leftArm.graphics.use(Resources.LeftArm);
+    this.rightArm.graphics.use(Resources.RightArm);
+
+    this.head.graphics.use(Resources.Head);
+    this.body.graphics.use(Resources.Body);
+
+    this.leftLeg.graphics.use(Resources.LeftLeg);
+    this.rightLeg.graphics.use(Resources.RightLeg);
+  }
+}
 ```

src/engine/Actor.ts

@@ -56,7 +56,7 @@ export function isActor(x: any): x is Actor {
 }
 
 /**
- * Actor contructor options
+ * Actor constructor options
  */
 export interface ActorArgs {
   /**
@@ -137,7 +137,7 @@ export interface ActorArgs {
    */
   collider?: Collider;
   /**
-   * Optionally suppy a [[CollisionGroup]]
+   * Optionally supply a [[CollisionGroup]]
    */
   collisionGroup?: CollisionGroup;
 }
@@ -492,8 +492,7 @@ export class Actor extends Entity implements Eventable, PointerEvents, CanInitia
   }
   public set color(v: Color) {
     this._color = v.clone();
-    const defaultLayer = this.graphics.layers.default;
-    const currentGraphic = defaultLayer.graphics[0]?.graphic;
+    const currentGraphic = this.graphics.current;
     if (currentGraphic instanceof Raster || currentGraphic instanceof Text) {
       currentGraphic.color = this._color;
     }