diff --git a/include/ignition/gazebo/System.hh b/include/ignition/gazebo/System.hh index fc2a3403c1b..f8ef47ed01a 100644 --- a/include/ignition/gazebo/System.hh +++ b/include/ignition/gazebo/System.hh @@ -44,21 +44,32 @@ namespace ignition /// will only operate on an Entity if it has all of the required /// Components. /// - /// Systems are executed in three phases: + /// Systems are executed in three phases, with each phase for a given step + /// corresponding to the entities at time UpdateInfo::simTime: /// * PreUpdate - /// * Has read-write access to world entities and components - /// * Executed with simulation time at (t0) + /// * Has read-write access to world entities and components. + /// * 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 - /// * Responsible for propagating time from (t0) to (t0 + dt) - /// * Used for physics simulation step + /// * Has read-write access to world entities and components. + /// * Used for physics simulation step (i.e., simulates what happens at + /// time UpdateInfo::simTime). /// * PostUpdate - /// * Has read-only access to world entities and components - /// * Executed with simulation time at (t0 + dt) + /// * Has read-only access to world entities and components. + /// * 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 diff --git a/tutorials/create_system_plugins.md b/tutorials/create_system_plugins.md index 283e73a222a..86f5420aabb 100644 --- a/tutorials/create_system_plugins.md +++ b/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 ignition::gazebo::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 ignition::gazebo::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 ignition::gazebo::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 ignition::gazebo::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 ignition::gazebo::UpdateInfo::simTime is initially 0 if simulation is started paused, while ignition::gazebo::UpdateInfo::simTime is initially ignition::gazebo::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`.