.. 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 responisble 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 the ``Record <>`` function.
Currently only Constraint positions are supported, see :ref:`record-and-playback-limitations-label`.

.. figure:: images/play_record/blueprint_record.jpg
  :alt: Call record function.
  :target: _images/blueprint_record.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 the ``Play Back <>`` function (currently only Constraint positions are supported, see :ref:`record-and-playback-limitations-label`).

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

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

3. Play the Simulation. The Constraints 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.


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

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

Currently only Constraint positions 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.