.. _stdlib_global_input_state: ================ Raw input module ================ This module provides functionality related to the global input state. You can directly read the raw input events from various input devices, such as keyboard, mouse, and gamepad. It includes enumerations for types of these events, as well as functions to handle them. To add this module to your project, add the following line to your project file:: require engine.input_core // or require engine.core .. warning:: Raw input module 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 ` instead There are two ways to handle input events. Let's consider how to determine whether a button was pressed on different devices using the following methods: 1. By reading raw input events from :ref:`get_input_command_buffer ` Example:: for (cmd in get_input_command_buffer()) { match (cmd) { if (RawKeyboardInputEvent(kind=RawKeyboardInputEventKind KeyDown, buttonIdx=$v(buttonIdx))) { print("kind = KeyDown, buttonIdx = {buttonIdx}") } if (RawKeyboardInputEvent(kind=RawKeyboardInputEventKind KeyUp, buttonIdx=$v(buttonIdx))) { print("kind = KeyUp, buttonIdx = {buttonIdx}") } } } 2. By reading the global input state 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") } ++++++++++++ Enumerations ++++++++++++ .. _enum-input_commands-RawKeyboardInputEventKind: .. das:attribute:: RawKeyboardInputEventKind Represents the kind of raw keyboard input event. :Values: * **KeyDown** = 0x0u8 - The key down event * **KeyUp** = 0x1u8 - The key up event .. _enum-input_commands-RawMouseInputEventKind: .. das:attribute:: RawMouseInputEventKind Represents the kind of raw mouse input event. :Values: * **MouseMove** = 0x0u8 - The mouse move event * **MouseDown** = 0x1u8 - The mouse down event * **MouseUp** = 0x2u8 - The mouse up event * **MouseWheel** = 0x3u8 - The mouse wheel event .. _enum-input_commands-RawMouseInputEventPointerId: .. das:attribute:: RawMouseInputEventPointerId Represents the pointer id of the raw mouse input event. :Values: * **RealMouse** = 0x0u8 - The real mouse pointer id * **VirtualMouse** = 0x1u8 - The virtual mouse pointer id .. _enum-input_commands-RawTouchInputEventKind: .. das:attribute:: RawTouchInputEventKind Represents the kind of raw touch input event. :Values: * **TouchBegan** = 0x0u8 - The touch began event * **TouchMoved** = 0x1u8 - The touch moved event * **TouchEnded** = 0x2u8 - The touch ended event .. _enum-public_input-MouseCursor: .. das:attribute:: MouseCursor Represents the type of the mouse cursor. :Values: * **Default** = 0 - The default cursor (arrow) * **Arrow** = 1 - The arrow cursor * **Button** = 2 - The button cursor * **IBeam** = 3 - The I-beam cursor ++++++++++ Structures ++++++++++ .. _struct-input_commands-RawMouseInputEvent: .. das:attribute:: RawMouseInputEvent Represents a raw mouse input event. :Fields: * **pointerId** : :ref:`RawMouseInputEventPointerId ` - The pointer id of the raw mouse input event * **kind** : :ref:`RawMouseInputEventKind ` - The kind of raw mouse input event * **buttonIdx** : :ref:`MouseButton ` - The index of the button associated with the event * **wheel** : int - The wheel value for mouse wheel events * **deltaPosition** : float2 - The change in position since the last event * **absolutePosition** : float2 - The absolute position of the mouse * **timeUsec** : int64 - The time in microseconds when the event occurred .. _struct-input_commands-RawTouchInputEvent: .. das:attribute:: RawTouchInputEvent Represents a raw touch input event. :Fields: * **kind** : :ref:`RawTouchInputEventKind ` - The kind of raw touch input event * **touchIdx** : int - The index of the touch * **deltaPosition** : float2 - The change in position since the last event * **absolutePosition** : float2 - The absolute position of the touch * **startPosition** : float2 - The start position of the touch * **timeUsec** : int64 - The time in microseconds when the event occurred .. _struct-input_commands-RawKeyboardInputEvent: .. das:attribute:: RawKeyboardInputEvent Represents a raw keyboard input event. :Fields: * **kind** : :ref:`RawKeyboardInputEventKind ` - The kind of raw keyboard input event * **buttonIdx** : :ref:`KeyCode ` - The index of the button associated with the event * **shifts** : :ref:`KeyboardShifts ` - The keyboard shift state * **repeat** : bool - Indicates if the key event is a repeat event * **charCode** : uint - The character code associated with the event * **timeUsec** : int64 - The time in microseconds when the event occurred .. _struct-input_commands-RawGamepadInputEvent: .. das:attribute:: RawGamepadInputEvent Represents a raw gamepad input event. :Fields: * **gamepadIndex** : int - The index of the gamepad * **buttonDownState** : :ref:`GamepadButton ` - The state of the buttons that are currently down. Each bit of the value represent single gamepad button starting from lowest bit. * **buttonPressedState** : :ref:`GamepadButton ` - The state of the buttons that were pressed since the last event. Each bit of the value represent single gamepad button starting from lowest bit. * **buttonReleasedState** : :ref:`GamepadButton ` - The state of the buttons that were released since the last event. Each bit of the value represent single gamepad button starting from lowest bit. * **xyz** : float3 - The XYZ values of the left stick of the gamepad. The Z value is the trigger value. * **rxyz** : float3 - The XYZ values of the right stick of the gamepad. The Z value is the trigger value. * **sensor** : float4 - The sensor values of the gamepad. The first three values are the accelerometer values and the last value is the gyroscope value. * **slider** : float2 - The slider values of the gamepad. The X value is the left slider value and the Y value is the right slider value. * **timeUsec** : int64 - The time in microseconds when the event occurred +++++++++ Functions +++++++++ * :ref:`key_down (charCode: string) : bool ` * :ref:`key_down (buttonIdx: KeyCode) : bool ` * :ref:`key_pressed (charCode: string) : bool ` * :ref:`key_pressed (buttonIdx: KeyCode) : bool ` * :ref:`key_released (charCode: string) : bool ` * :ref:`key_released (buttonIdx: KeyCode) : bool ` * :ref:`mouse_button_down (button: MouseButton) : bool ` * :ref:`mouse_button_pressed (button: MouseButton) : bool ` * :ref:`mouse_button_released (button: MouseButton) : bool ` * :ref:`get_mouse_position () : float2 ` * :ref:`get_mouse_delta () : float2 ` * :ref:`get_mouse_wheel () : float ` * :ref:`has_gamepad (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool ` * :ref:`get_left_stick (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float2 ` * :ref:`get_right_stick (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float2 ` * :ref:`get_left_slider (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float ` * :ref:`get_right_slider (gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : float ` * :ref:`gamepad_key_down (key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool ` * :ref:`gamepad_key_pressed (key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool ` * :ref:`gamepad_key_released (key_code: GamepadButton; gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0) : bool ` * :ref:`get_input_command_buffer () : CommandBuffer const&# ` * :ref:`get_mouse_cursor () : MouseCursor ` * :ref:`set_mouse_cursor (cursor_type: MouseCursor) ` * :ref:`get_gamepads_info (cb: block\<(idx:int;deviceName:string#;deviceVendor:string#;userId:int):void\>) : int ` * :ref:`get_gamepads_generation () : uint64 ` * :ref:`get_gamepads_count () : int ` .. _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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - the key to check * **gamepad_idx** : :ref:`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 ` - the key to check * **gamepad_idx** : :ref:`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 ` - the key to check * **gamepad_idx** : :ref:`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") } .. _function-public_input_get_input_command_buffer: .. das:function:: get_input_command_buffer() : CommandBuffer const&# This command buffer can be used to communicate with the input system. :Returns: * :ref:`CommandBuffer ` &# - a command buffer which contains list of input commands .. _function-public_input_get_mouse_cursor: .. das:function:: get_mouse_cursor() : MouseCursor :Returns: * :ref:`MouseCursor ` - The type of the mouse cursor. .. _function-public_input_set_mouse_cursor_MouseCursor: .. das:function:: set_mouse_cursor(cursor_type: MouseCursor) Change mouse cursor type. :Arguments: * **cursor_type** : :ref:`MouseCursor ` .. _function-gamepad_input_get_gamepads_info_block_ls_idx_c_int;deviceName_c_string_hh_;deviceVendor_c_string_hh_;userId_c_int_c_void_gr_: .. das:function:: get_gamepads_info(cb: block<(idx:int;deviceName:string#;deviceVendor:string#;userId:int):void>) : int Iterates over all connected gamepads and calls the callback for each one :Arguments: * **cb** : block<(idx:int;deviceName:string#;deviceVendor:string#;userId:int):void> - callback to call for each gamepad :Returns: * int - number of connected gamepads Usage example:: get_gamepads_info() $(idx, deviceName, deviceVendor, userId) { // do something with the gamepad info } .. _function-gamepad_input_get_gamepads_generation: .. das:function:: get_gamepads_generation() : uint64 The current generation of the gamepads. This value is incremented each time a gamepad is connected or disconnected. It can be used to detect if the gamepad list has changed. :Returns: * uint64 - the current generation of the gamepads .. _function-gamepad_input_get_gamepads_count: .. das:function:: get_gamepads_count() : int :Returns: * int - number of connected gamepads