Input

In Pine, input handling is done by input systems.

Keyboard

Keyboard keys are represented as values of the Key enum, which maps keys to GLFW keyboard key tokens.

// Returns true in every frame while the space key is being pressed
boolean spacePressed = input.getKey(Key.SPACE);

// Returns true in the first frame the space key is down
boolean spaceDown = input.getKeyDown(Key.SPACE);

// Returns true in every frame while both the left control and space keys are being pressed
boolean controlSpacePressed = input.getKeys(Key.L_CONTROL, Key.SPACE)

// Returns true in every frame while either the left or right control keys are being pressed
boolean controlPressed = input.getAnyKey(Key.L_CONTROL, Key.R_CONTROL)

Stopping propagation

To prevent later systems from reading the same keyboard input, use the following methods:

boolean spacePressed = input.getKey(Key.SPACE, true);
boolean spaceDown = input.getKeyDown(Key.SPACE, true);

Using GLFW keyboard key tokens

Instead of using the Key enum, you can also use GLFW keyboard key tokens directly.

import static org.lwjgl.glfw.GLFW.*;

boolean spacePressed = input.getKey(GLFW_KEY_SPACE);

This is the equivalent of:

boolean spacePressed = input.getKey(Key.SPACE);

Mouse

Cursor position

The position of the cursor can be retrieved using the following methods. These methods will return null if the cursor was already blocked by an entity.

// Returns the screen coordinates of the cursor
Vector2i cursorPosition = input.getCursor();

// Returns the position of the cursor transformed to a global world position, relative to the camera
Vector2f cursorWorldPosition = input.getWorldCursor();

Blocking

The cursor can be blocked by an entity to prevent later systems from reading the cursor position. This is only possible if the entity is currently active.

// Block the cursor using an entity, if it hasn't been blocked yet
input.blockCursor(entity);

// Block the cursor using an entity, regardless of whether it has already been blocked yet
input.blockCursor(entity, true);

// Returns true if the cursor has been blocked by an entity
boolean isCursorBlocked = input.isCursorBlocked();

// Returns the entity that is blocking the cursor, or null if there isn't one
Entity cursorBlocker = input.getCursorBlocker();

Buttons

Mouse buttons are represented as values of the MouseButton enum, which maps buttons to GLFW mouse buttons.

// Returns true in every frame while the left mouse button is being pressed
boolean leftMouseButtonPressed = input.getMouseButton(MouseButton.LEFT);

// Returns true in the first frame the left mouse button is down
boolean leftMouseButtonDown = input.getMouseButtonDown(MouseButton.LEFT);

Stopping propagation

To prevent later systems from reading the same mouse button input, use the following methods:

boolean leftMouseButtonPressed = input.getMouseButton(MouseButton.LEFT, true);
boolean leftMouseButtonDown = input.getMouseButtonDown(MouseButton.LEFT, true);

Using GLFW mouse buttons

Instead of using the MouseButton enum, you can also use GLFW mouse buttons directly.

import static org.lwjgl.glfw.GLFW.*;

boolean leftMouseButtonPressed = input.getMouseButton(GLFW_MOUSE_BUTTON_1);

Scroll

Horizontal and vertical scroll values can be read using the following methods.

float scrollX = input.getScrollX();
float scrollY = input.getScrollY();

Cursor type and image

The appearance of the cursor can be changed using the following methods. Cursors can either have a standard appearance (cursor type) or a custom appearace (cursor image).

// Show the default hand (or pointer) cursor
input.setCursorType(CursorType.HAND);
// Or
import static org.lwjgl.glfw.GLFW.*;
input.setCursorType(GLFW_ARROW_CURSOR);

// Show a custom cursor image
Image cursorImage = AssetPools.images.load("textures/cursor.png");
input.setCursorImage(cursorImage);

// Show a custom cursor image with an offset of 16x16 pixels
input.setCursorImage(cursorImage, 16, 16);
input.setCursorImage(cursorImage, new Vector2i(16, 16));

Gamepad

Pine supports up to 16 gamepads. Once a gamepad is connected, it is assigned a unique ID. The following method returns true when the gamepad with the given ID is currently connected.

int gamepadId = ...
boolean isConnected = input.isGamepadConnected(gamepadId);

The next methods are used to retrieve gamepads.

// Retrieve the first gamepad, or a fallback gamepad which returns `0f` for all axes and `false` for all buttons if no gamepad is connected.
GamepadInput gamepad = input.getGamepad();

// Retrieve a specific gamepad
int gamepadId = ...
GamepadInput gamepad = input.getGamepad(gamepadId); // Will throw an error if the ID is invalid or the corresponding gamepad is not connected

Buttons

Gamepad buttons are represented as values of the GamepadButton enum, which maps buttons to GLFW gamepad buttons. The buttons CROSS, CIRCLE, SQUARE and TRIANGLE are respectively equal to A, B, X and Y.

// Returns true in every frame while the circle button is being pressed
boolean circleButtonPressed = gamepad.getButton(GamepadButton.CIRCLE);

// Returns true in the first frame the circle button is down
boolean circleButtonDown = gamepad.getButtonDown(GamepadButton.CIRCLE);

Using GLFW gamepad buttons

Instead of using the GamepadButton enum, you can also use GLFW gamepad buttons directly.

import static org.lwjgl.glfw.GLFW.*;

boolean circleButtonPressed = gamepad.getButton(GLFW_GAMEPAD_BUTTON_CIRCLE);

Axes

Gamepad axes are represented as values of the GamepadAxis enum, which maps axes to GLFW gamepad axes.

// Returns the value of the horizontal axis of the left joystick
float leftX = gamepad.getAxis(GamepadAxis.LEFT_X);

// Returns the value of the vertical axis of the right joystick
float rightY = gamepad.getAxis(GamepadAxis.RIGHT_Y);

// Returns the value of the left trigger
float leftTrigger = gamepad.getAxis(GamepadAxis.LEFT_TRIGGER);

Using GLFW gamepad axes

Instead of using the GamepadAxis enum, you can also use GLFW gamepad axes directly.

import static org.lwjgl.glfw.GLFW.*;

float leftX = gamepad.getAxis(GLFW_GAMEPAD_AXIS_LEFT_X);