docs: Update GraphicsGroup

sandbox/tests/graphics-group/index.ts

@@ -16,14 +16,15 @@ var loader = new ex.Loader([heartImage]);
 class MyActor2 extends ex.Actor {
   constructor() {
     super({
-      pos: ex.vec(200, 200)
+      pos: ex.vec(0, 0)
     });
   }
   onInitialize() {
     this.graphics.add(
       'interactive',
       new ex.GraphicsGroup({
         useAnchor: false,
+        scale: ex.vec(4, 4),
         members: [
           {
             graphic: heartImage.toSprite(),
@@ -54,5 +55,5 @@ class MyActor2 extends ex.Actor {
 game.add(new MyActor2());
 
 game.start(loader);
-game.currentScene.camera.pos = ex.vec(200, 200);
-game.currentScene.camera.zoom = 3;
+// game.currentScene.camera.pos = ex.vec(200, 200);
+// game.currentScene.camera.zoom = 3;

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

@@ -8,35 +8,85 @@ A graphics group is an new graphic that draws a graphics in some relation to one
 
 ```typescript
 const group = new ex.GraphicsGroup({
+  useAnchor: false, // position group from the top left
   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: triangle,
-      pos: ex.vec(0, 200),
+      offset: ex.vec(0, 200),
     },
   ],
 })
 ```
+
+### Positioning GraphicsGroup and its Members
+
+There are a few options available to you when defining a grouping.
+
+Setting `useAnchor: false` will tell the `GraphicsGroup` to completely ignore anchoring of any parent component and position from the top left.
+
+
+```typescript
+
+const group = new ex.GraphicsGroup({
+
+  useAnchor: false, // position group from the top left
+  members: [
+    {
+      graphic: newSprite,
+      offset: ex.vec(0, 0)
+    },
+    {
+      graphic: newSprite,
+      offset: ex.vec(50, 0)
+    }
+  ],
+})
+```
+
+Group members are added to the collection of graphics and their bounds are included as a default. You can disable the bounds inclusion into the `GraphicsGroup` on a per member basis, this is useful if you have large unpredictably sized graphics or dynamic text that can change the bounds. Excalibur default anchor centers graphics, these new bounds can cause `GraphicsGroup`s to shift when new members are added because bounds change.
+
+
+```typescript
+export interface GraphicsGrouping {
+  offset: Vector;
+  graphic: Graphic;
+  /**
+   * Optionally disable this graphics bounds as part of group calculation, default true
+   * if unspecified
+   *
+   * You may want to do this if you're using text because their bounds will affect
+   * the centering of the whole group
+   */
+  useBounds?: boolean;
+}
+```
+
+:::note
+
+`useAnchor: false` is the preferred option, turning off bounds can have some unexpected onscreen/offscreen effects like popping in or out unexpectedly.
+
+:::

src/engine/Graphics/GraphicsGroup.ts

@@ -10,7 +10,7 @@ export interface GraphicsGroupingOptions {
   /**
    * Default true, GraphicsGroup will use the anchor to position all the graphics based on their combined bounds
    *
-   * Setting to false will ignore anchoring and position the top left of all graphics at the actor's position,
+   * Setting to false will ignore anchoring from parent components and position the top left of all graphics at the actor's position,
    * positioning graphics in the group is done with the `offset` property.
    */
   useAnchor?: boolean;
@@ -23,8 +23,10 @@ export interface GraphicsGrouping {
    * Optionally disable this graphics bounds as part of group calculation, default true
    * if unspecified
    *
-   * You may want to do this if you're using text because their bounds will affect
-   * the centering of the whole group
+   * You may want disable this if you're using text because their bounds will affect
+   * the centering of the whole group.
+   *
+   * **WARNING** having inaccurate bounds can cause offscreen culling issues.
    */
   useBounds?: boolean;
 }