.. _stdlib_global_input_state:

==================
Global input state
==================

This module provides functionality related to the global input state.

.. note::
   This module is not included in engine.core by default. You need to explicitly require it in your project file.

To add this module to your project, add the following line to your project file::

    require engine.input.global_input_state

.. warning::
   Global input state is not recommended for use due to its lack of built-in cross-platform support. It is recommended to use the :ref:`Action set module <stdlib_action_set_input_state>` instead


Example::

    if (mouse_button_pressed(MouseButton Left)) {
        print("left mouse button was just pressed")
    }

    if (key_pressed(KeyCode.Up)) {
        print("up key was just pressed")
    }

    if (gamepad_key_down(0, GamepadButton.Up)) {
        print("up key is pressed")
    }

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

  *  :ref:`key_down (charCode: string) : bool <function-global_input_state_key_down_string>` 
  *  :ref:`key_down (buttonIdx: KeyCode) : bool <function-global_input_state_key_down_KeyCode>` 
  *  :ref:`key_pressed (charCode: string) : bool <function-global_input_state_key_pressed_string>` 
  *  :ref:`key_pressed (buttonIdx: KeyCode) : bool <function-global_input_state_key_pressed_KeyCode>` 
  *  :ref:`key_released (charCode: string) : bool <function-global_input_state_key_released_string>` 
  *  :ref:`key_released (buttonIdx: KeyCode) : bool <function-global_input_state_key_released_KeyCode>` 
  *  :ref:`mouse_button_down (button: MouseButton) : bool <function-global_input_state_mouse_button_down_MouseButton>` 
  *  :ref:`mouse_button_pressed (button: MouseButton) : bool <function-global_input_state_mouse_button_pressed_MouseButton>` 
  *  :ref:`mouse_button_released (button: MouseButton) : bool <function-global_input_state_mouse_button_released_MouseButton>` 
  *  :ref:`get_mouse_position () : float2 <function-global_input_state_get_mouse_position>` 
  *  :ref:`get_mouse_delta () : float2 <function-global_input_state_get_mouse_delta>` 
  *  :ref:`get_mouse_wheel () : float <function-global_input_state_get_mouse_wheel>` 
  *  :ref:`has_gamepad (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool <function-global_input_state_has_gamepad_ControllerIndex>` 
  *  :ref:`get_left_stick (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float2 <function-global_input_state_get_left_stick_ControllerIndex>` 
  *  :ref:`get_right_stick (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float2 <function-global_input_state_get_right_stick_ControllerIndex>` 
  *  :ref:`get_left_slider (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float <function-global_input_state_get_left_slider_ControllerIndex>` 
  *  :ref:`get_right_slider (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float <function-global_input_state_get_right_slider_ControllerIndex>` 
  *  :ref:`gamepad_key_down (key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool <function-global_input_state_gamepad_key_down_GamepadButton_ControllerIndex>` 
  *  :ref:`gamepad_key_pressed (key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool <function-global_input_state_gamepad_key_pressed_GamepadButton_ControllerIndex>` 
  *  :ref:`gamepad_key_released (key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool <function-global_input_state_gamepad_key_released_GamepadButton_ControllerIndex>` 

.. _function-global_input_state_key_down_string:

.. das:function:: key_down(charCode: string) : bool

Checks if the key with the given charCode is currently held down.

:Arguments: * **charCode** : string -  the key to check, as a string



:Returns: * bool -  true if the key is held down, false otherwise

Usage example::

    if (key_down("a")) {
        print("a is held down")
    }

.. _function-global_input_state_key_down_KeyCode:

.. das:function:: key_down(buttonIdx: KeyCode) : bool

Checks if the key with the given buttonIdx is currently held down.

:Arguments: * **buttonIdx** :  :ref:`KeyCode <enum-input_consts-KeyCode>`  -  the key to check



:Returns: * bool -  true if the key is held down, false otherwise

Usage example::

    if (key_down(KeyCode.A)) {
        print("a is held down")
    }

.. _function-global_input_state_key_pressed_string:

.. das:function:: key_pressed(charCode: string) : bool

Checks if the key was pressed during the current frame. Note that this function will return false in subsequent frames if the key is still pressed.

:Arguments: * **charCode** : string -  the key to check, as a string



:Returns: * bool -  true if the key was pressed during the current frame, false otherwise

Usage example::

    if (key_pressed("a")) {
        print("a was just pressed")
    }

.. _function-global_input_state_key_pressed_KeyCode:

.. das:function:: key_pressed(buttonIdx: KeyCode) : bool

Checks if the key was pressed during the current frame. Note that this function will return false in subsequent frames if the key is still pressed.

:Arguments: * **buttonIdx** :  :ref:`KeyCode <enum-input_consts-KeyCode>`  -  the key to check



:Returns: * bool -  true if the key was pressed during the current frame, false otherwise

Usage example::

    if (key_pressed(KeyCode.A)) {
        print("a was just pressed")
    }

.. _function-global_input_state_key_released_string:

.. das:function:: key_released(charCode: string) : bool

Checks if the key was released during the current frame. Note that this function will return false in subsequent frames if the key is still released.

:Arguments: * **charCode** : string -  the key to check, as a string



:Returns: * bool -  true if the key was released during the current frame, false otherwise

Usage example::

    if (key_released("a")) {
        print("a was just released")
    }

.. _function-global_input_state_key_released_KeyCode:

.. das:function:: key_released(buttonIdx: KeyCode) : bool

Checks if the key was released during the current frame. Note that this function will return false in subsequent frames if the key is still released.

:Arguments: * **buttonIdx** :  :ref:`KeyCode <enum-input_consts-KeyCode>`  -  the key to check



:Returns: * bool -  true if the key was released during the current frame, false otherwise

Usage example::

    if (key_released(KeyCode.A)) {
        print("a was just released")
    }

.. _function-global_input_state_mouse_button_down_MouseButton:

.. das:function:: mouse_button_down(button: MouseButton) : bool

Checks if the mouse button is currently held down.

:Arguments: * **button** :  :ref:`MouseButton <enum-input_consts-MouseButton>`  -  the mouse button to check



:Returns: * bool -  true if the mouse button is held down, false otherwise

Usage example::

    if (mouse_button_down(MouseButton Left)) {
        print("left mouse button is held down")
    }

.. _function-global_input_state_mouse_button_pressed_MouseButton:

.. das:function:: mouse_button_pressed(button: MouseButton) : bool

Checks if the mouse button was pressed during the current frame. Note that this function will return false in subsequent frames if the mouse button is still pressed.

:Arguments: * **button** :  :ref:`MouseButton <enum-input_consts-MouseButton>`  -  the mouse button to check



:Returns: * bool -  true if the mouse button was pressed during the current frame, false otherwise

Usage example::

    if (mouse_button_pressed(MouseButton Left)) {
        print("left mouse button was just pressed")
    }

.. _function-global_input_state_mouse_button_released_MouseButton:

.. das:function:: mouse_button_released(button: MouseButton) : bool

Checks if the mouse button was released during the current frame. Note that this function will return false in subsequent frames if the mouse button is still released.

:Arguments: * **button** :  :ref:`MouseButton <enum-input_consts-MouseButton>`  -  the mouse button to check



:Returns: * bool -  true if the mouse button was released during the current frame, false otherwise

Usage example::

    if (mouse_button_released(MouseButton Left)) {
        print("left mouse button was just released")
    }

.. _function-global_input_state_get_mouse_position:

.. das:function:: get_mouse_position() : float2

:Returns: * float2 -  current mouse position (x, y), in pixels. The origin is the top-left corner of the screen, the x-axis points to the right, and the y-axis points down.

.. _function-global_input_state_get_mouse_delta:

.. das:function:: get_mouse_delta() : float2

:Returns: * float2 -  current mouse delta (x, y), in pixels. The x-axis points to the right, and the y-axis points down.

.. _function-global_input_state_get_mouse_wheel:

.. das:function:: get_mouse_wheel() : float

:Returns: * float -  current mouse wheel

.. _function-global_input_state_has_gamepad_ControllerIndex:

.. das:function:: has_gamepad(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool

Checks if the gamepad is attached

:Arguments: * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad to check, default is the first gamepad



:Returns: * bool -  true if the gamepad is attached, false otherwise

Usage example::

    if (has_gamepad(ControllerIndex Device1)) {
        print("the second gamepad is attached")
    }

.. _function-global_input_state_get_left_stick_ControllerIndex:

.. das:function:: get_left_stick(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float2

:Arguments: * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad, default is the first gamepad



:Returns: * float2 -  left stick value (x, y) if the gamepad is attached, (0, 0) otherwise

.. _function-global_input_state_get_right_stick_ControllerIndex:

.. das:function:: get_right_stick(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float2

:Arguments: * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad, default is the first gamepad



:Returns: * float2 -  right stick value (x, y) if the gamepad is attached, (0, 0) otherwise

.. _function-global_input_state_get_left_slider_ControllerIndex:

.. das:function:: get_left_slider(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float

:Arguments: * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad, default is the first gamepad



:Returns: * float -  left slider value if the gamepad is attached, 0 otherwise

.. _function-global_input_state_get_right_slider_ControllerIndex:

.. das:function:: get_right_slider(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float

:Arguments: * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad, default is the first gamepad



:Returns: * float -  right slider value if the gamepad is attached, 0 otherwise

.. _function-global_input_state_gamepad_key_down_GamepadButton_ControllerIndex:

.. das:function:: gamepad_key_down(key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool

Checks if the gamepad key is held down.

:Arguments: * **key_code** :  :ref:`GamepadButton <enum-input_consts-GamepadButton>`  -  the key to check

            * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad, default is the first gamepad



:Returns: * bool -  true if the gamepad key is held down and the gamepad is attached, false otherwise

Usage example::

    if (gamepad_key_down(GamepadButton.Up, ControllerIndex Device1)) {
        print("up key is held down on the second gamepad")
    }

.. _function-global_input_state_gamepad_key_pressed_GamepadButton_ControllerIndex:

.. das:function:: gamepad_key_pressed(key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool

Checks if the gamepad key has been pressed during the current frame. Note that this function will return false in subsequent frames if the key is still pressed.

:Arguments: * **key_code** :  :ref:`GamepadButton <enum-input_consts-GamepadButton>`  -  the key to check

            * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad, default is the first gamepad



:Returns: * bool -  true if the gamepad key was pressed during the current frame and the gamepad is attached, false otherwise

Usage example::

    if (gamepad_key_pressed(GamepadButton.Up, ControllerIndex Device1)) {
        print("up key was just pressed on the second gamepad")
    }

.. _function-global_input_state_gamepad_key_released_GamepadButton_ControllerIndex:

.. das:function:: gamepad_key_released(key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool

Checks if the gamepad key has been released during the current frame. Note that this function will return false in subsequent frames if the key is still released.

:Arguments: * **key_code** :  :ref:`GamepadButton <enum-input_consts-GamepadButton>`  -  the key to check

            * **gamepad_idx** :  :ref:`ControllerIndex <enum-input_consts-ControllerIndex>`  -  the index of the gamepad, default is the first gamepad



:Returns: * bool -  true if the gamepad key was released during the current frame and the gamepad is attached, false otherwise

Usage example::

    if (gamepad_key_released(GamepadButton.Up, ControllerIndex Device1)) {
        print("up key was just released on the second gamepad")
    }