From 1944a6aae26aea8a4a397515df8a11a78f638f69 Mon Sep 17 00:00:00 2001
From: Erik Onarheim <erik.onarheim@gmail.com>
Date: Thu, 18 Jan 2024 14:37:25 -0600
Subject: [PATCH] docs: Update pointer documentation

---
 site/docs/02-fundamentals/03-actors.mdx | 10 ++++
 site/docs/11-input/10.3-pointer.mdx     | 65 ++++++++++++++++---------
 2 files changed, 52 insertions(+), 23 deletions(-)

diff --git a/site/docs/02-fundamentals/03-actors.mdx b/site/docs/02-fundamentals/03-actors.mdx
index aa445063b..828074830 100644
--- a/site/docs/02-fundamentals/03-actors.mdx
+++ b/site/docs/02-fundamentals/03-actors.mdx
@@ -18,6 +18,16 @@ If you don't want these built-ins and you want to build only what you want, read
 declare const game: ex.Engine;
 ```
 
+:::warning
+
+Actors use collision geometry for pointer events meaning they need at least a width/height or custom collider, but can be configured to use graphics bounds for pointer testing.
+
+[[Actor.pointer]] and [[PointerComponent]]
+
+Read more [here](/docs/pointers#actor-pointer-events)
+
+::: 
+
 ## Basic actors
 
 For quick and dirty games, you may be able to create an instance of an [[Actor]]
diff --git a/site/docs/11-input/10.3-pointer.mdx b/site/docs/11-input/10.3-pointer.mdx
index a0f6e1297..a9ccf3745 100644
--- a/site/docs/11-input/10.3-pointer.mdx
+++ b/site/docs/11-input/10.3-pointer.mdx
@@ -142,34 +142,53 @@ engine.input.pointers.at(1).on('move', paint('red')); // 2nd finger
 engine.input.pointers.at(2).on('move', paint('green')); // 3rd finger
 ```
 
-### Actor pointer events
-
-By default, [actors](/docs/actors) do not participate in pointer events. In other
-words, when you "click" an Actor, it will not throw an event **for that Actor**,
-only a generic pointer event for the game. This is to keep performance
-high and allow actors to "opt-in" to handling pointer events. Actors will automatically
-opt-in if a pointer related event handler is set on them `actor.on("pointerdown", () => {})` for example.
+### Actor Pointer Events
+
+Actors will participate in pointer events, by default it uses the collision geometry to test whether the pointer is
+in or out of the actor. In the example below the actor has default box geometry of 100x100.
+
+```typescript
+class MyActor extends ex.Actor {
+  constructor() {
+    super({
+      pos: ex.vec(200, 200),
+      width: 100,
+      height: 100});
+    this.on('pointerenter', () => {
+      console.log('enter')
+    });
+    this.on('pointerleave', () => {
+      console.log('leave')
+    });
+  }
+}
 
-To opt-in manually, set [[Actor.enableCapturePointer]] to `true` and the [[Actor]] will
-start publishing `pointerup` and `pointerdown` events. `pointermove` events
-will not be published by default due to performance implications. If you want
-an actor to receive move events, set [[CapturePointerConfig.captureMoveEvents]] to
-`true`.
+```
+:::warning
+If your [[Actor]] has no geometry and only graphics you will need to enable graphics bounds testing.
+:::
 
-Actor pointer events will be prefixed with `pointer`.
+To enable graphics bounds testing for pointer events you can grab the [[Actor]]'s [[PointerComponent]]
+
+```typescript
+class MyGraphicsActor extends ex.Actor {
+  constructor(image: ImageSource) {
+    super({pos: ex.vec(200, 200)});
+    this.pointer.useGraphicsBounds = true;
+    this.graphics.use(image.toSprite());
+
+    this.on('pointerenter', () => {
+      console.log('enter')
+    });
+    this.on('pointerleave', () => {
+      console.log('leave')
+    });
+  }
+}
 
-```js
-const player = new ex.Actor();
-// enable propagating pointer events
-player.enableCapturePointer = true;
-// enable move events, warning: performance intensive!
-player.capturePointer.captureMoveEvents = true;
-// subscribe to input
-player.on('pointerup', function (ev) {
-  player.logger.info('Player selected!', ev);
-});
 ```
 
+
 #### Actor Events
 
 Actors have the following **extra** events you can subscribe to: