.. include:: definitions.rstinc

.. _record-and-playback-label:

===================
Record and Playback
===================

.. note::
  This is an experimental feature meaning it may be changed in the future with no guaranteed backwards compatibility.


|AGXUnreal| offers some functionality that enables recording and playback of some aspects of a Simulation.
This can be useful when for example recording the movements of a machine controlled by user inputs for later playback.

The ``Play Record Component`` is responsible for handling the record and playback functionality.
During recording it writes data to a ``Play Record`` Asset which is stored permanently for later playback.


.. _record-and-playback-record-label:

******
Record
******

1. Create a ``Play Record`` Asset. This is where the recorded data will be stored.

.. figure:: images/play_record/create_play_record_asset.jpg
  :alt: Create a Play Record Asset.
  :target: _images/create_play_record_asset.jpg

2. Add a ``Play Record Component`` (AGX Play Record) to your Blueprint and assign the ``Play Record`` Asset created from step 1 to it, in the Details Panel.

.. figure:: images/play_record/details_panel_asset.jpg
  :alt: Assign Play Record Asset.
  :target: _images/details_panel_asset.jpg

3. Call one of the ``Record <>`` functions.
Currently only either Constraint positions or Rigid Body positions are supported, see :ref:`record-and-playback-limitations-label`.

.. figure:: images/play_record/blueprint_record.jpg
  :alt: Call record function recording Constraints.
  :target: _images/blueprint_record.jpg


.. figure:: images/play_record/play_record_record_bodies.jpg
  :alt: Call record function recording Rigid Bodies.
  :target: _images/play_record_record_bodies.jpg



Notice that we use a AGX Simulation Step Forward event for triggering the recording instead of Unreal Engines Tick event.
This is important for determinism. See :ref:`events-and-delegates-label` for more information.

4. Play the Simulation and stop it once done. The recorded data is now present in the ``Play Record`` Asset and can be used for future playback.
Remember to disconnect the ``Record <>`` function route node in your Blueprint to avoid overwriting the data in subsequent Simulations.


********
Playback
********

Here it is assumed that the steps in :ref:`record-and-playback-record-label` has been followed.

1. Assign a ``Play Record`` Asset containing recorded data to the ``Play Record Component`` in the Details Panel.

.. figure:: images/play_record/details_panel_asset.jpg
  :alt: Assign Play Record Asset.
  :target: _images/details_panel_asset.jpg

2. Call one of the ``Play Back <>`` functions, either Constraint Positions or Rigid Body Positions. See :ref:`record-and-playback-limitations-label`.

.. figure:: images/play_record/blueprint_playback.jpg
  :alt: Call playback function for Constraints.
  :target: _images/blueprint_playback.jpg


.. figure:: images/play_record/play_record_play_back_bodies.jpg
  :alt: Call playback function for Rigid Bodies.
  :target: _images/play_record_play_back_bodies.jpg


It is important that the array of Constraints or Rigid Bodies match those used during recording to get a correct result.

3. Play the Simulation. The Constraints or Rigid Bodies will now move according to the recorded data.
Note that the ``Play Record Component`` does position control internally and does not guarantee equal Constraint forces/torques during playback as during recording.
While playing back Rigid Body trajectories the bodies temporarily have their Motion Control set to Kinematics.


.. _record-and-playback-limitations-label:

***********
Limitations
***********

Currently only one of Constraint positions or Rigid Body trajectories can be recorded and played back when using the ``Play Record Component``.
The ``Play Record Component`` strictly uses position control of Constraints during playback meaning forces, torques and trajectories are not guaranteed to be the same as during recording.