Raw input module

This module provides functionality related to the raw input events. 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

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

Enumerations

RawKeyboardInputEventKind

Represents the kind of raw keyboard input event.

Values:

  • KeyDown = 0x0 - The key down event

  • KeyUp = 0x1 - The key up event

RawMouseInputEventKind

Represents the kind of raw mouse input event.

Values:

  • MouseMove = 0x0 - The mouse move event

  • MouseDown = 0x1 - The mouse down event

  • MouseUp = 0x2 - The mouse up event

  • MouseWheel = 0x3 - The mouse wheel event

RawMouseInputEventPointerId

Represents the pointer id of the raw mouse input event.

Values:

  • RealMouse = 0x0 - The real mouse pointer id

  • VirtualMouse = 0x1 - The virtual mouse pointer id

RawTouchInputEventKind

Represents the kind of raw touch input event.

Values:

  • TouchBegan = 0x0 - The touch began event

  • TouchMoved = 0x1 - The touch moved event

  • TouchEnded = 0x2 - 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 : GamepadButtons - The state of the buttons that are currently down. Each bit of the value represent single gamepad button starting from lowest bit.

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

get_gamepads_count(): int
Returns:

  • int - number of connected gamepads

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_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_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:
is_any_button_just_pressed(): bool

Returns true if any button of any input device was just pressed during the current frame. Use it to detect the start of any button press

is_any_button_just_released(): bool

Returns true if any button of any input device was just released during the current frame. Use it to detect the end of any button press

is_any_button_pressed(): bool

Returns true if any button of any input device is pressed. Returns true every frame as long as any button is held down

is_any_gamepad_button_just_pressed(): bool

Returns true if any gamepad button was just pressed during the current frame. Use it to detect the start of a gamepad button press

is_any_gamepad_button_just_released(): bool

Returns true if any gamepad button was just released during the current frame. Use it to detect the end of a gamepad button press

is_any_gamepad_button_pressed(): bool

Returns true if any gamepad button is pressed. Returns true every frame as long as the gamepad button is held down

is_any_gamepad_slider_touched(): bool

Returns true if any gamepad slider is touched (has non-zero value)

is_any_gamepad_stick_touched(): bool

Returns true if any gamepad stick is touched (has non-zero value)

is_any_gamepad_touched(): bool

Returns true if any gamepad button, stick or slider is touched

is_any_keyboard_button_just_pressed(): bool

Returns true if any keyboard button was just pressed during the current frame. Use it to detect the start of a key press

is_any_keyboard_button_just_released(): bool

Returns true if any keyboard button was just released during the current frame. Use it to detect the end of a key press

is_any_keyboard_button_pressed(): bool

Returns true if any keyboard button is pressed. Returns true every frame as long as the keyboard button is held down

is_any_mouse_button_just_pressed(): bool

Returns true if any mouse button was just pressed during the current frame. Use it to detect the start of a mouse button press

is_any_mouse_button_just_released(): bool

Returns true if any mouse button was just released during the current frame. Use it to detect the end of a mouse button press

is_any_mouse_button_pressed(): bool

Returns true if any mouse button is pressed. Returns true every frame as long as the mouse button is held down

is_any_mouse_touched(): bool

Returns true if the mouse has moved or any mouse button is pressed

is_mouse_moved(): bool

Returns true if the mouse has moved since the last frame

set_mouse_cursor(cursor_type: MouseCursor)

Change mouse cursor type.

Arguments:
start_rumble(gamepadIdx: int; lowFreq: float; highFreq: float; durationSec: float = 0f)

Starts vibration on the specified gamepad controller. It can be stopped with stop_rumble. This function controls the low-frequency and high-frequency rumble motors independently. Use it to provide haptic feedback for hits, explosions, weapon fire, or other impactful game events.

Arguments:

  • gamepadIdx : int - the controller index to vibrate

  • lowFreq : float - intensity of the low-frequency motor in the range 0.0 to 1.0, usually felt as a deep rumble.

  • highFreq : float - intensity of the high-frequency motor in the range 0.0 to 1.0, usually felt as a sharper vibration.

  • durationSec : float - optional parameter that sets how long the rumble should last in seconds. A value of 0.0 means keep the rumble active until manually stopped. If a non-zero duration is specified, the rumble will automatically stop after that time.

The exact rumble behavior may vary depending on the connected gamepad hardware and platform support. On controllers without dual-motor support, the two intensity values may be combined or mapped to the available vibration capability.

Usage example:

// Heavy rumble for a hit or explosion
start_rumble(0, 0.9, 0.5, 0.15)

// Light feedback for a button press or UI event
start_rumble(0, 0.2, 0.2, 0.05)

// Continuous rumble until explicitly stopped with stop_rumble(0)
start_rumble(0, 0.4, 0.2)
stop_rumble(gamepadIdx: int)

Stops vibration on the specified gamepad controller.

Use this function to cancel any active rumble effect previously started with start_rumble (both for infinitely long or a specific duration). It is useful for ending a long or continuous vibration immediately.

Arguments:

  • gamepadIdx : int - the controller index to stop vibrating

Usage example:

// Stop rumble on the first connected gamepad
stop_rumble(0)

// Start a continuous rumble and stop it later
start_rumble(0, 0.4, 0.3)
// ... some game logic ...
stop_rumble(0)