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 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 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}")
        }
    }
}

  1. 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

RawKeyboardInputEventKind

Represents the kind of raw keyboard input event.

Values:

  • KeyDown = 0x0u8 - The key down event

  • KeyUp = 0x1u8 - The key up event

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

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

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

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

RawMouseInputEvent

Represents a raw mouse input event.

Fields:

  • pointerId : RawMouseInputEventPointerId - The pointer id of the raw mouse input event

  • kind : RawMouseInputEventKind - The kind of raw mouse input event

  • buttonIdx : 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

RawTouchInputEvent

Represents a raw touch input event.

Fields:

  • kind : 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

RawKeyboardInputEvent

Represents a raw keyboard input event.

Fields:

  • kind : RawKeyboardInputEventKind - The kind of raw keyboard input event

  • buttonIdx : KeyCode - The index of the button associated with the event

  • shifts : 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

RawGamepadInputEvent

Represents a raw gamepad input event.

Fields:

  • gamepadIndex : int - The index of the gamepad

  • buttonDownState : GamepadButton - The state of the buttons that are currently down. Each bit of the value represent single gamepad button starting from lowest bit.

  • buttonPressedState : 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 : 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

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")
}
key_down(buttonIdx: KeyCode): bool

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

Arguments:

  • buttonIdx : 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")
}
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")
}
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 : 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")
}
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")
}
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 : 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")
}
mouse_button_down(button: MouseButton): bool

Checks if the mouse button is currently held down.

Arguments:
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")
}
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:
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")
}
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:
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")
}
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.

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.

get_mouse_wheel(): float
Returns:

  • float - current mouse wheel

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

Checks if the gamepad is attached

Arguments:

  • gamepad_idx : 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")
}
get_left_stick(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0): float2
Arguments:

  • gamepad_idx : 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

get_right_stick(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0): float2
Arguments:

  • gamepad_idx : 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

get_left_slider(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0): float
Arguments:

  • gamepad_idx : ControllerIndex - the index of the gamepad, default is the first gamepad

Returns:

  • float - left slider value if the gamepad is attached, 0 otherwise

get_right_slider(gamepad_idx: ControllerIndex = input_consts::ControllerIndex.Device0): float
Arguments:

  • gamepad_idx : ControllerIndex - the index of the gamepad, default is the first gamepad

Returns:

  • float - right slider value if the gamepad is attached, 0 otherwise

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

Checks if the gamepad key is held down.

Arguments:
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")
}
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:
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")
}
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:
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")
}
get_input_command_buffer(): CommandBuffer const&#

This command buffer can be used to communicate with the input system.

Returns:

  • CommandBuffer &# - a command buffer which contains list of input commands

get_mouse_cursor(): MouseCursor
Returns:
set_mouse_cursor(cursor_type: MouseCursor)

Change mouse cursor type.

Arguments:
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
}
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

get_gamepads_count(): int
Returns:

  • int - number of connected gamepads