Input¶

Description¶

Input is a static polling class that provides the current keyboard, mouse, touch, and gamepad state at any point during a frame. Use it inside onUpdate or onFixedUpdate to check whether a key or button is held down. For event-based input (press/release and controller connect/disconnect notifications), subscribe to the Engine callback events instead.

#include "Doriax.h"
using namespace doriax;

// Inside an update callback:
if (Input::isKeyPressed(D_KEY_SPACE)) {
    player.jump();
}

-- Inside update:
if Input.isKeyPressed(Input.KEY_SPACE) then
    player:jump()
end

Methods¶

Keys¶

Key constants are preprocessor #define values in C++ (prefix D_KEY_) and static properties on Input in Lua (prefix Input.KEY_). The table below lists the C++ form; for Lua, replace D_KEY_ with Input.KEY_.

Mouse buttons¶

In Lua, replace the D_MOUSE_BUTTON_ prefix with Input.MOUSE_BUTTON_.

Modifiers¶

Modifier bits returned by getModifiers and passed to key/mouse callbacks. In Lua, replace the D_MODIFIER_ prefix with Input.MODIFIER_.

Gamepad buttons¶

Button indices follow the standard Xbox-style layout. In Lua, replace the D_GAMEPAD_BUTTON_ prefix with Input.GAMEPAD_BUTTON_. The PlayStation-style aliases are the same underlying values.

The aliases D_GAMEPAD_BUTTON_CROSS, CIRCLE, SQUARE, and TRIANGLE (Lua Input.GAMEPAD_BUTTON_CROSS, …) resolve to A, B, X, and Y respectively.

Gamepad axes¶

Axis values range from -1.0 to 1.0. Sticks are down-positive on the Y axis (up is -1), and triggers rest at -1, reaching +1 when fully pressed. In Lua, replace the D_GAMEPAD_AXIS_ prefix with Input.GAMEPAD_AXIS_.

Method details¶

isKeyPressed¶

• static bool isKeyPressed(int key)

Returns true while the given key is held down. Use D_KEY_* constants in C++ and Input.KEY_* in Lua for the key code.

if (Input::isKeyPressed(D_KEY_W)) {
    player.moveForward(Engine::getDeltatime() * speed);
}

if Input.isKeyPressed(Input.KEY_W) then
    player:moveForward(Engine.deltatime * speed)
end

isMousePressed¶

• static bool isMousePressed(int button)

Returns true while the given mouse button is held down. Use D_MOUSE_BUTTON_* constants in C++ and Input.MOUSE_BUTTON_* in Lua.

if (Input::isMousePressed(D_MOUSE_BUTTON_LEFT)) {
    // drag logic
}

if Input.isMousePressed(Input.MOUSE_BUTTON_LEFT) then
    -- drag logic
end

isTouch¶

• static bool isTouch()

Returns true if there is at least one active touch contact.

isMouseEntered¶

• static bool isMouseEntered()

Returns true while the mouse cursor is inside the canvas boundary.

getMousePosition¶

• static Vector2 getMousePosition()

Current cursor position in canvas coordinates. Updated every frame; use for hover detection in onUpdate.

This value can also be set manually with Engine.setMousePosition. When Engine.mouseMode is CAPTURED, the position is a virtual canvas-space position accumulated from relative mouse movement and may move outside the normal canvas range.

Vector2 pos = Input::getMousePosition();

local pos = Input.getMousePosition()

getMouseScroll¶

• static Vector2 getMouseScroll()

Accumulated scroll wheel delta since the last frame, in (xoffset, yoffset). Reset each frame.

getTouchPosition¶

• static Vector2 getTouchPosition(int pointer)

Returns the current position of the touch contact identified by pointer. Use findTouchIndex to convert a pointer ID to an array index if needed.

getTouches¶

• static std::vector<Touch> getTouches()

Returns all active touch contacts. Each Touch has int pointer and Vector2 position.

for (const auto& touch : Input::getTouches()) {
    drawCircle(touch.position.x, touch.position.y, 10.0f);
}

local touches = Input.getTouches()
for i = 1, #touches do
    drawCircle(touches[i].position.x, touches[i].position.y, 10)
end

numTouches¶

• static size_t numTouches()

Returns the count of currently active touch contacts.

isGamepadConnected¶

• static bool isGamepadConnected(int id)

Returns true while a controller with the given id is connected. Ids are assigned per platform and are sparse — enumerate connected controllers with getGamepadId, not by assuming ids 0..numGamepads()-1.

if (Input::isGamepadConnected(0)) {
    // controller 0 is present
}

if Input.isGamepadConnected(0) then
    -- controller 0 is present
end

getGamepadName¶

• static std::string getGamepadName(int id)

Returns the human-readable name of the controller with the given id, or an empty string if it is not connected.

isGamepadButtonPressed¶

• static bool isGamepadButtonPressed(int id, int button)

Returns true while the given button is held down on controller id. Use D_GAMEPAD_BUTTON_* constants in C++ and Input.GAMEPAD_BUTTON_* in Lua. Returns false for an unknown controller.

if (Input::isGamepadButtonPressed(0, D_GAMEPAD_BUTTON_A)) {
    player.jump();
}

if Input.isGamepadButtonPressed(0, Input.GAMEPAD_BUTTON_A) then
    player:jump()
end

getGamepadAxis¶

• static float getGamepadAxis(int id, int axis)

Returns the current value of an analog axis on controller id, in the range -1.0…1.0. Use D_GAMEPAD_AXIS_* constants in C++ and Input.GAMEPAD_AXIS_* in Lua. Returns 0.0 for an unknown controller.

Sticks are down-positive on the Y axis (up is -1). Triggers rest at -1 and reach +1 when fully pressed — a released trigger reads -1 from the moment the controller connects, not 0.

float x = Input::getGamepadAxis(0, D_GAMEPAD_AXIS_LEFT_X);
if (fabsf(x) > 0.15f) {  // dead zone
    player.strafe(x);
}

local x = Input.getGamepadAxis(0, Input.GAMEPAD_AXIS_LEFT_X)
if math.abs(x) > 0.15 then  -- dead zone
    player:strafe(x)
end

getGamepads¶

• static std::vector<Gamepad> getGamepads()
• C++ only

Returns all connected controllers. Each Gamepad holds an int id, a std::string name, and the current button and axis state. In Lua, iterate with numGamepads and getGamepadId instead.

numGamepads¶

• static size_t numGamepads()

Returns the count of currently connected controllers. This is a count, not the highest id — combine it with getGamepadId to iterate.

getGamepadId¶

• static int getGamepadId(size_t index)

Returns the real id of the index-th connected controller, or -1 if index is out of range. Because gamepad ids are sparse (they can have gaps after a disconnect), this is the correct way to enumerate connected controllers:

for (size_t i = 0; i < Input::numGamepads(); i++) {
    int id = Input::getGamepadId(i);
    // poll controller `id`
}

for i = 0, Input.numGamepads() - 1 do
    local id = Input.getGamepadId(i)
    -- poll controller `id`
end

getModifiers¶

• static int getModifiers()

Returns the current modifier key bitmask. Check individual modifiers with bitwise AND.

int mods = Input::getModifiers();
if (mods & D_MODIFIER_SHIFT) {
    // Shift is held
}

local mods = Input.getModifiers()
if (mods & Input.MODIFIER_SHIFT) ~= 0 then
    -- Shift is held
end

findTouchIndex¶

• static size_t findTouchIndex(int pointer)

Returns the index into the getTouches array for the given pointer ID. Returns SIZE_MAX if not found.

findGamepadIndex¶

• static size_t findGamepadIndex(int id)
• C++ only

Returns the internal index of the controller with the given id, or SIZE_MAX if it is not connected. Most code should use isGamepadConnected and getGamepadId instead.