.. _hello_world:

Hello World
==================

.. highlight:: python

SAPIEN provides APIs to build physical simulation environments.

In this tutorial, you will learn the following:

* Create a simulation engine ``Engine``
* Create a simulation scene ``Scene``
* Setup a renderer to visualize
* Run a simulation loop

.. figure:: assets/hello_world.png
    :width: 640px
    :align: center
    :figclass: align-center

The full script can be downloaded here :download:`hello_world.py <../../../../examples/basic/hello_world.py>`

Simulation engine and scene
-------------------------------------

To simulate with SAPIEN, you need to first create a simulation engine, and then create a simulation scene by the engine.

.. literalinclude:: ../../../../examples/basic/hello_world.py
   :dedent: 0
   :lines: 18-23

``Engine`` is the physical simulation engine connected to the `PhysX <https://gameworksdocs.nvidia.com/PhysX/4.1/documentation/physxguide/Manual/Index.html>`_ backend.
One engine per process is allowed.
``Scene`` is an instance of the simulation world.
Multiple scenes can be created through ``create_scene``, and run independently.
``VulkanRenderer`` is the rendering engine connected to our `vulkan-based <https://www.khronos.org/vulkan/>`_ renderer.
The renderer should be bound with an engine, and then all the scenes created by the engine will be bound with the renderer.

Add rigid bodies
-------------------

So far, our scene is empty.
``Actor`` (rigid body) is simulated in SAPIEN.
Let's add two actors, a ground and a box, to the scene.
How to create actors will be elaborated in :ref:`create_actors`.

.. literalinclude:: ../../../../examples/basic/hello_world.py
   :dedent: 0
   :lines: 26-31

Viewer
-------------------------------------------

``Viewer`` creates a window (GUI) to render the simulation world.
How to use the GUI will be elaborated in :ref:`viewer`.

.. literalinclude:: ../../../../examples/basic/hello_world.py
   :dedent: 0
   :lines: 33-47

.. note::
   The GUI is not necessary when you only need physical simulation, e.g. collecting experiences for policy learning.

Simulation loop
---------------

After setting up the simulation world, the actual simulation happens in a loop.
For each iteration, the scene simulates for one step and updates the world to the renderer.
The viewer calls ``render`` to update the results on the screen.

.. literalinclude:: ../../../../examples/basic/hello_world.py
   :dedent: 0
   :lines: 49-52

Full script
----------------

.. literalinclude:: ../../../../examples/basic/hello_world.py
    :linenos:
    :lines: 12-