made distinctions between paused and un-paused simulation time

Signed-off-by: Ashton Larkin <[email protected]>

include/ignition/gazebo/System.hh

@@ -45,20 +45,31 @@ namespace ignition
     /// Components.
     ///
     /// Systems are executed in three phases, with each phase for a given step
-    /// corresponding to the entities at time "t":
+    /// corresponding to the entities at time UpdateInfo::simTime:
     ///  * PreUpdate
     ///    * Has read-write access to world entities and components.
-    ///    * This is where systems say what they'd like to happen at time "t".
+    ///    * This is where systems say what they'd like to happen at time
+    ///      UpdateInfo::simTime.
     ///    * Can be used to modify state before physics runs, for example for
     ///      applying control signals or performing network syncronization.
     ///  * Update
     ///    * Has read-write access to world entities and components.
-    ///    * Used for physics simulation step (i.e., what happens at time "t").
+    ///    * Used for physics simulation step (i.e., simulates what happens at
+    ///      time UpdateInfo::simTime).
     ///  * PostUpdate
     ///    * Has read-only access to world entities and components.
-    ///    * Captures everything that happened at time "t".
+    ///    * Captures everything that happened at time UpdateInfo::simTime.
     ///    * Used to read out results at the end of a simulation step to be used
     ///      for sensor or controller updates.
+    ///
+    /// It's important to note that UpdateInfo::simTime does not refer to the
+    /// current time, but the time reached after the PreUpdate and Update calls
+    /// have finished. So, if any of the *Update functions are called with
+    /// simulation paused, time does not advance, which means the time reached
+    /// after PreUpdate and Update is the same as the starting time. This
+    /// explains why UpdateInfo::simTime is initially 0 if simulation is started
+    /// paused, while UpdateInfo::simTime is initially UpdateInfo::dt if
+    /// simulation is started un-paused.
     class IGNITION_GAZEBO_VISIBLE System
     {
       /// \brief Constructor

tutorials/create_system_plugins.md

@@ -12,17 +12,20 @@ there are currently three additional available interfaces:
 
 1. ISystemPreUpdate
   1. Has read-write access to world entities and components.
-  2. Executed with simulation time at (t0).
+  2. This is where systems say what they'd like to happen at time `UpdateInfo::simTime`.
   3. Can be used to modify state before physics runs, for example for applying control signals or performing network synchronization.
 2. ISystemUpdate
   1. Has read-write access to world entities and components.
-  2. Responsible for propagating time from (t0) to (t0 + dt).
-  3. Used for physics simulation step.
+  2. Used for physics simulation step (i.e., simulates what happens at time `UpdateInfo::simTime`).
 3. ISystemPostUpdate
   1. Has read-only access to world entities and components.
-  2. Executed with simulation time at (t0 + dt).
+  2. Captures everything that happened at time `UpdateInfo::simTime`.
   3. Used to read out results at the end of a simulation step to be used for sensor or controller updates.
 
+It's important to note that `UpdateInfo::simTime` does not refer to the current time, but the time reached after the `PreUpdate` and `Update` calls have finished.
+So, if any of the `*Update` functions are called with simulation paused, time does not advance, which means the time reached after `PreUpdate` and `Update` is the same as the starting time.
+This explains why `UpdateInfo::simTime` is initially 0 if simulation is started paused, while `UpdateInfo::simTime` is initially `UpdateInfo::dt` if simulation is started un-paused.
+
 Systems that are only used to read the current state of the world (sensors,
 graphics, and rendering) should implement `ISystemPostUpdate`.