From 6087c4f052c4e4f927372ad128ff1cffe61c85dd Mon Sep 17 00:00:00 2001
From: Erik Onarheim <erik.onarheim@gmail.com>
Date: Wed, 18 Sep 2024 08:24:56 -0500
Subject: [PATCH] docs: Update GraphicsGroup

---
 sandbox/tests/graphics-group/index.ts         |  7 +-
 site/docs/04-graphics/04.2-graphics-group.mdx | 64 +++++++++++++++++--
 src/engine/Graphics/GraphicsGroup.ts          |  8 ++-
 3 files changed, 66 insertions(+), 13 deletions(-)

diff --git a/sandbox/tests/graphics-group/index.ts b/sandbox/tests/graphics-group/index.ts
index 67517fe90..c9c5d84a3 100644
--- a/sandbox/tests/graphics-group/index.ts
+++ b/sandbox/tests/graphics-group/index.ts
@@ -16,7 +16,7 @@ var loader = new ex.Loader([heartImage]);
 class MyActor2 extends ex.Actor {
   constructor() {
     super({
-      pos: ex.vec(200, 200)
+      pos: ex.vec(0, 0)
     });
   }
   onInitialize() {
@@ -24,6 +24,7 @@ class MyActor2 extends ex.Actor {
       '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;
diff --git a/site/docs/04-graphics/04.2-graphics-group.mdx b/site/docs/04-graphics/04.2-graphics-group.mdx
index 8c467b1a0..6d114c8ff 100644
--- a/site/docs/04-graphics/04.2-graphics-group.mdx
+++ b/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.
+
+:::
\ No newline at end of file
diff --git a/src/engine/Graphics/GraphicsGroup.ts b/src/engine/Graphics/GraphicsGroup.ts
index 7c3bbe0ed..bc44b119e 100644
--- a/src/engine/Graphics/GraphicsGroup.ts
+++ b/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;
 }