From 2f2d381696ed6eecf000fd53a2d49fa60c057e58 Mon Sep 17 00:00:00 2001
From: Evan Hemsley <evan@moonside.games>
Date: Mon, 27 Jul 2020 14:04:18 -0700
Subject: [PATCH] adding some language to clarify motion engine process

---
 content/pong/ball/bouncing/motion_engine.md | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/content/pong/ball/bouncing/motion_engine.md b/content/pong/ball/bouncing/motion_engine.md
index 5b115f6..aa35f92 100644
--- a/content/pong/ball/bouncing/motion_engine.md
+++ b/content/pong/ball/bouncing/motion_engine.md
@@ -72,7 +72,9 @@ namespace PongFE.Engines
 }
 ```
 
-Next, let's consolidate our MotionMessages per Entity.
+First, at the very beginning of the processing, we insert all of our entities with a Position and Collision into the SpatialHash. 
+
+Next, in a separate block, let's consolidate our MotionMessages per Entity.
 
 ```cs
     ...
@@ -81,6 +83,11 @@ Next, let's consolidate our MotionMessages per Entity.
 
     ...
 
+    foreach (var entity in TrackedEntities)
+    {
+        ...
+    }
+
     foreach (ref readonly var entity in ReadEntities<PositionComponent>())
     {
         ref readonly var positionComponent = ref GetComponent<PositionComponent>(entity);
@@ -95,7 +102,7 @@ Next, let's consolidate our MotionMessages per Entity.
     ...
 ```
 
-This is where our *IHasEntity* optimization comes in. It allows us to use the **ReadMessagesWithEntity** method.
+This is where our *IHasEntity* optimization comes in. It allows us to use the **ReadMessagesWithEntity** method. This method efficiently queries messages that refer to the given entity.
 
 Finally, let's implement our sweep test.
 
@@ -219,11 +226,16 @@ namespace PongFE.Engines
 }
 ```
 
-Now we can send these messages in **MotionEngine**.
+Now, in the final block of our **MotionEngine**, we can perform our collision tests and send out our messages.
 
 ```cs
     ...
 
+    foreach (ref readonly var entity in ReadEntities<PositionComponent>())
+    {
+        ...
+    }
+
     foreach (var entity in TrackedEntities)
     {
         Vector2 moveAmount = _moveAmounts[entity];
@@ -252,8 +264,6 @@ Now we can send these messages in **MotionEngine**.
 
         SendMessage(new UpdatePositionMessage(entity, projectedPosition));
     }
-
-    ...
 ```
 
 Here, we go over everything with a Position and Collision component, sweep test for collisions, and send appropriate Collision and UpdatePosition messages accordingly.