.. _stdlib_main_loop:

=========
Main loop
=========

++++++++++++++
Initialization
++++++++++++++

The game initialization happens right after the game launch. It consists of the following steps:

- All global ``on_initialize()`` functions are called.

    - It is possible for every module to have its own single ``on_initialize()``, but the call order will be undefined.

- A default prefab is instantiated.

    - For every node, ``Component.on_initialize()`` is called (like in any prefab instantiation).

        - The calls order is the same as the order of ``Component.on_update()`` calls (see below).

    - This step is skipped if no default prefab is provided.


+++++++++
Game loop
+++++++++

The main loop consists of the following calls to user-provided functions:

- ``on_resolution_changed`` if resolution changed

- All global ``on_update()`` functions.

    - Multiple modules can have their own ``on_update()`` functions (but a single module can have only one ``on_update()``).

        - If multiple modules have ``on_update()``, they are called in random order.

- All ``Component.on_update()`` functions

    - For every alive node, call ``Component.on_update()``

        - Order of nodes: in the order of creation

            - For example, if node ``a`` is created before ``b``, then ``a`` will always be called before ``b``, regardless of the scene tree.

        - Order of components: in the order of addition

            - For example, if component ``Foo`` is added to a node before component ``Bar``, then ``Foo.on_update()`` will be called before ``Bar.on_update()``.

- Physics simulation

    - Simulate physics and invoke collision callbacks for collisions that occurred during this frame. See :ref:`Physics Simulation in a Main Loop <stdlib_physics_core_main_loop>`.

+++++++++
Functions
+++++++++

  *  :ref:`on_initialize () <function-main_loop_on_initialize>` 
  *  :ref:`on_update () <function-main_loop_on_update>` 
  *  :ref:`on_resolution_changed (res: int2) <function-main_loop_on_resolution_changed_int2>` 
  *  :ref:`on_before_reload () <function-main_loop_on_before_reload>` 
  *  :ref:`on_after_reload () <function-main_loop_on_after_reload>` 
  *  :ref:`on_pause (pause: bool) <function-main_loop_on_pause_bool>` 
  *  :ref:`on_exit () <function-main_loop_on_exit>` 
  *  :ref:`on_editor_update (playing: bool) <function-main_loop_on_editor_update_bool>` 

.. _function-main_loop_on_initialize:

.. das:function:: on_initialize()

This function is called once when the scene is first loaded

Usage example::

    [export]
    def on_initialize() {
        print("Hello, world!")
    }

.. _function-main_loop_on_update:

.. das:function:: on_update()

This function is called every frame

Usage example::

    [export]
    def on_update() {
        print("Frame time {get_delta_time()}")
    }

.. _function-main_loop_on_resolution_changed_int2:

.. das:function:: on_resolution_changed(res: int2)

This function is called when the resolution is changed

:Arguments: * **res** : int2 -  The new resolution



Usage example::

    [export]
    def on_resolution_changed(res : int2) {
        print("Resolution changed to {res}")
    }

.. _function-main_loop_on_before_reload:

.. das:function:: on_before_reload()

This function is called before the scene is reloaded
Usually whole global state of game can be automatically hot-reloaded, but sometimes you need to do some manual setups in this function

Usage example::

    [export]
    def on_before_reload() {
        print("Reloading scene...")
    }

.. _function-main_loop_on_after_reload:

.. das:function:: on_after_reload()

This function is called after the scene is reloaded

Usage example::

    [export]
    def on_after_reload() {
        print("Scene reloaded")
    }

.. _function-main_loop_on_pause_bool:

.. das:function:: on_pause(pause: bool)

This function is called when the scene is paused. Can be used to save the game state

:Arguments: * **pause** : bool -  True if the scene is paused, False if it is resumed



Usage example::

    [export]
    def on_pause(pause : bool) {
        if (pause) {
            print("Game paused")
        } else {
            print("Game resumed")
        }
    }

.. _function-main_loop_on_exit:

.. das:function:: on_exit()

This function is called when the scene is exited. Last chance to save the game state

Usage example::

    [export]
    def on_exit() {
        print("Exiting game")
    }

.. _function-main_loop_on_editor_update_bool:

.. das:function:: on_editor_update(playing: bool)

This function is called every frame in the editor.
Can be used to draw debug information in the editor.

:Arguments: * **playing** : bool -  True if the game is running in the editor, False if it is paused



Usage example::

    [export]
    def on_editor_update() {
        print("Inside editor")
    }