.. _stdlib_collision_listener_component:

=================
CollisionListener
=================

Custom collision handling.

Custom collision handling can be implemented by using the
:ref:`on_collision <function-physics_core_on_collision_NodeId_lambda_ls_collision_c_Collision_c_void_gr_>`
function on a node. Under the hood, this function adds a :ref:`LambdaCollisionListener <struct-collision_listener_component-LambdaCollisionListener>` component to that node.
This component inherits from the :ref:`CollisionListener <struct-collision_listener_component-CollisionListener>` component, which is the base component for all collision listeners.
You can create your own component, inherit from ``CollisionListener``, add it to a node, and this component will receive collision callbacks from that node.

.. note::
    To receive collision callbacks, the body should have an active :ref:`RigidBody <stdlib_rigid_body_component>` or :ref:`CharacterController <stdlib_character_controller_component>` component.

.. note::
    ``MotionType Static`` is the cheapest motionType for a body to receive callbacks, but it has its limitations. See :ref:`MotionType <enum-public_components-MotionType>`.

This component is provided by the ``engine.physics_core`` module, which is included in the ``engine.core`` module.

Example::

    require engine.core

    let node = create_node(NodeData())
    add_component(node, new RigidBody())
    on_collision(node) @(collision) {
        print("Collision detected")
    }

See also :ref:`Physics Simulation in a Main Loop <stdlib_physics_core_main_loop>`

++++++++++
Structures
++++++++++

.. _struct-collision_listener_component-Collision:

.. das:attribute:: Collision

Collision event

:Fields: * **nodeId** :  :ref:`NodeId <handle-public_scene-NodeId>`  - the other body that collides with the receiver body

         * **normal** : float3 - normal of the collision on the other node (world space)

         * **penetration** : float - penetration depth

         * **impulse** : float - collision impulse, use for impact measurement

         * **positions** : array<float3> - positions of the collision (world space, not empty)


+++++++
Classes
+++++++

.. _struct-collision_listener_component-CollisionListener:

.. das:attribute:: CollisionListener : Component

Base component for all collision callback handlers. When added to a node with an active RigidBody component, it starts receiving collision callbacks for it.

You can create a custom component, inherit it from ``CollisionListener``, override methods, and receive callbacks to yourself

However, if you want a quick collision handling, consider using :ref:`on_collision <function-physics_core_on_collision_NodeId_lambda_ls_collision_c_Collision_c_void_gr_>` function.

Usage example::

    class CustomCollisionListener : CollisionListener {
        def override on_initialize() {
            super.on_initialize()
            // ...
        }

        def override on_collision(c: Collision) {
            // Collision started
            ...
        }

        def override on_collision_stay(c: Collision) {
            // Collision stays
            ...
        }

        def override on_collision_exit(otherNode: NodeId) {
            // Collision finished
            ...
        }
    }

    // ...
    add_component(node, new CustomCollisionListener())

.. note::
    CharacterController generates collision events only with rigid bodies. To collide with other CharacterController-s, it must have an active RigidBody component.


.. _function-collision_listener_component_CollisionListener_rq_on_collision_CollisionListener_Collision:

.. das:function:: CollisionListener.on_collision(collision: Collision)

Called when the body collides with another another node with a RigidBody component collides with this node.

The callback is called for every new collision.

:Arguments: * **collision** :  :ref:`Collision <struct-collision_listener_component-Collision>` 

.. _function-collision_listener_component_CollisionListener_rq_on_collision_stay_CollisionListener_Collision:

.. das:function:: CollisionListener.on_collision_stay(collision: Collision)

Registers a callback that is called when another node with a RigidBody component collides with this node.

The callback is called for every collisions that stays between frames.

:Arguments: * **collision** :  :ref:`Collision <struct-collision_listener_component-Collision>` 

.. _function-collision_listener_component_CollisionListener_rq_on_collision_exit_CollisionListener_NodeId:

.. das:function:: CollisionListener.on_collision_exit(otherNode: NodeId)

Registers a callback that is called when another node with a RigidBody component collides with this node.

The callback is called for every finished collisions.

:Arguments: * **otherNode** :  :ref:`NodeId <handle-public_scene-NodeId>` 

.. _struct-collision_listener_component-LambdaCollisionListener:

.. das:attribute:: LambdaCollisionListener : CollisionListener

Collision handler that calls lambdas as custom handlers.

Don't use this component directly, instead use :ref:`on_collision <function-physics_core_on_collision_NodeId_lambda_ls_collision_c_Collision_c_void_gr_>` function and others.

Usage example::

    on_collision(node) @(collision) {
        print("Collision started between {node} and {collision.node}")
    }
    on_collision_stay(node) @(collision) {
        print("Collision stays between {node} and {collision.node}")
    }
    on_collision_exit(node) @(otherNode) {
        print("Collision finished between {node} and {otherNode}")
    }


.. _function-collision_listener_component_LambdaCollisionListener_rq_on_collision_LambdaCollisionListener_Collision:

.. das:function:: LambdaCollisionListener.on_collision(collision: Collision)

Called when you use ``on_collision`` on a node. See :ref:`on_collision <function-physics_core_on_collision_NodeId_lambda_ls_collision_c_Collision_c_void_gr_>`

:Arguments: * **collision** :  :ref:`Collision <struct-collision_listener_component-Collision>` 

.. _function-collision_listener_component_LambdaCollisionListener_rq_on_collision_stay_LambdaCollisionListener_Collision:

.. das:function:: LambdaCollisionListener.on_collision_stay(collision: Collision)

Called when you use ``on_collision_stay`` on a node. See :ref:`on_collision_stay <function-physics_core_on_collision_stay_NodeId_lambda_ls_collision_c_Collision_c_void_gr_>`

:Arguments: * **collision** :  :ref:`Collision <struct-collision_listener_component-Collision>` 

.. _function-collision_listener_component_LambdaCollisionListener_rq_on_collision_exit_LambdaCollisionListener_NodeId:

.. das:function:: LambdaCollisionListener.on_collision_exit(node: NodeId)

Called when you use ``on_collision_exit`` on a node. See :ref:`on_collision_exit <function-physics_core_on_collision_exit_NodeId_lambda_ls_otherNode_c_NodeId_c_void_gr_>`

:Arguments: * **node** :  :ref:`NodeId <handle-public_scene-NodeId>` 

.. _function-collision_listener_component_LambdaCollisionListener_rq_addOnCollisionListener_LambdaCollisionListener_lambda_ls_collision_c_Collision_c_void_gr_:

.. das:function:: LambdaCollisionListener.addOnCollisionListener(callback: lambda<(collision:Collision):void>)

Adds a callback for ``on_collision`` event.

:Arguments: * **callback** : lambda<(collision: :ref:`Collision <struct-collision_listener_component-Collision>` ):void>

.. _function-collision_listener_component_LambdaCollisionListener_rq_addOnCollisionStayListener_LambdaCollisionListener_lambda_ls_collision_c_Collision_c_void_gr_:

.. das:function:: LambdaCollisionListener.addOnCollisionStayListener(callback: lambda<(collision:Collision):void>)

Adds a callback for ``on_collision_stay`` event.

:Arguments: * **callback** : lambda<(collision: :ref:`Collision <struct-collision_listener_component-Collision>` ):void>

.. _function-collision_listener_component_LambdaCollisionListener_rq_addOnCollisionExitListener_LambdaCollisionListener_lambda_ls_otherNode_c_NodeId_c_void_gr_:

.. das:function:: LambdaCollisionListener.addOnCollisionExitListener(callback: lambda<(otherNode:NodeId):void>)

Adds a callback for ``on_collision_exit`` event.

:Arguments: * **callback** : lambda<(otherNode: :ref:`NodeId <handle-public_scene-NodeId>` ):void>