Mouse Input

The mouse is also a primary source of input for any desktop game. Though mostly used in FPS (First Person Shooter) games in the form of mouse look, they play an important role in the input stage of a game. This wiki page explains how to use mouse input in SilenceEngine.

Mouse button states

It is important to understand the different states a button can be in, and the Mouse class supports input in three different states — down (pressed), up (released) and tapped (first press). The difference between them is actually very small.

Down refers to when the button is down. It can be that you pressed and held the button down, or you just tapped it for a shorter amount of time.

Up refers to when the button is released, that is, it is not pressed, and you didn't tap it. It is the opposite of the pressed event, that is, the value is true if you didn't press, and is false if you pressed it. By default, the button is in the released state.

Tapped is nothing but the first occurrence of down event. You have to note that this is not dependent on the time, but the events.

Polling the button input

The button input is actually polled from a big list of events that are received asynchronously from the window, when the event frame begins. In order to use that input in your game, the Mouse class provides you three methods — isButtonDown(), isButtonUp() and isButtonTapped() that return the polled input in that frame.

// Left click fire
if (Mouse.isButtonDown(Mouse.BUTTON_LEFT))
    doFire();

// Right click reload
if (Mouse.isButtonDown(Mouse.BUTTON_RIGHT))
    reloadAmmo();

SilenceEngine is not limited to the standard three button mouse, it supports gaming mice which has up to 8 buttons. In case your mouse has no extra buttons, then those buttons are simply reported as released.

Cursor position and delta movement

Apart from these buttons, the Mouse class also supports the current cursor position, using the x and y public fields. They represent the position of the mouse in pixel coordinates, so you might need to project them using the camera to get world positions.

// Follow the mouse!!
position.lerp(temp.set(Mouse.x, Mouse.y), delta * 240);

The above code allows the 2D entities to follow the mouse at the speed of 240 world units in a second. In the same way, the delta movement is also polled in the mouse. To access the delta movement, use the dx and dy public fields.

// Mouse look!
if (Keyboard.isKeyDown(Keyboard.KEY_SPACE))
{
    SilenceEngine.display.setGrabMouse(true);

    camera.rotateX(Mouse.dy * speed);
    camera.rotateY(Mouse.dx * speed);
}
else
    SilenceEngine.display.setGrabMouse(false);

This snippet is used to add mouse look feature while pressing the SPACE key, which allows to look in any direction by simply moving the mouse in that direction. Just beware that these delta movement functions when called in a row just return zero.

Scroll input

A mouse not only offers movement, and buttons, but it also has a scroll wheel which we can use, most probably used to say switch between menu states or in game weapons. For that purpose the Mouse class provides deltaScrollX and deltaScrollY public fields.

float scroll = Mouse.deltaScrollY;

// Increase the menu index if scrolled down
if (scroll < 0)
    menuIndex = (menuIndex + 1) % totalMenus;

// Decrease the menu index if scrolled up
else if (scroll > 0)
    menuIndex = (totalMenus + menuIndex - 1) % totalMenus;

You might wonder why there is deltaScrollX when there is only vertical scroll wheel. It is used for trackpads, where you can send scroll events by swiping with two fingers. This is all what the Mouse input offers in SilenceEngine.

Event based mouse input

Mouse button events will be available via callbacks too, and you need to add a IMouseEventHandler to the input device.

private void onMouseButton(int button, boolean down, float x, float y)
{
    // Do whatever you want when the event happens
}

// Add the event handler to the device
SilenceEngine.input.addMouseEventHandler(this::onMouseButton);

Of course you will have to rely on the fields in the Mouse class for scroll input and delta movement. The event handlers are here due to request, but we recommend to use polled input.