LittleJS 1.31.0

Input

LittleJS Input System

  • Keyboard input with key down, pressed, and released states
  • Mouse input with position (world and screen space), buttons, and wheel
  • Gamepad support for multiple controllers with analog sticks and buttons
  • Touch input mapped to mouse position and buttons
  • Virtual on-screen gamepad for mobile devices
  • Automatic gamepad vs keyboard/mouse detection
  • Input event prevention for canvas focus

Functions

Members

Constants

Typedefs

Functions

gamepadConnected(gamepad) → booleanengineInput.js:369

Returns true if passed in gamepad is connected

gamepad number optional
gamepadDpad(gamepad) → Vector2engineInput.js:359

Returns gamepad dpad value

gamepad number optional
gamepadIsDown(button, gamepad) → booleanengineInput.js:312

Returns true if gamepad button is down

button number
gamepad number optional
gamepadStick(stick, gamepad) → Vector2engineInput.js:348

Returns gamepad stick value

stick number
gamepad number optional
Returns
  • Where the stick points, y up, length 0 to 1 past the dead zone, zero when there is no such stick
gamepadStickCount(gamepad) → numberengineInput.js:379

Returns how many control sticks the passed in gamepad has

gamepad number optional
gamepadVibrate(gamepad, duration, strongMagnitude, weakMagnitude, startDelay)engineInput.js:393

Pulse a gamepad's vibration hardware using the dual-rumble effect if it exists Strong magnitude is usually the left side motor, weak magnitude is usually the right side motor

gamepad number optional

gamepad index

duration number optional, default 200

effect duration in ms, browsers limit it and the delay to 5 seconds together

strongMagnitude number optional, default 1

strong (left) motor intensity, 0 to 1

weakMagnitude number optional, default 1

weak (right) motor intensity, 0 to 1

startDelay number optional, default 0

delay in ms before the effect starts

gamepadVibrateStop(gamepad)engineInput.js:410

Stop vibration on a gamepad

gamepad number optional

gamepad index

gamepadWasPressed(button, gamepad) → booleanengineInput.js:324

Returns true if gamepad button was pressed

button number
gamepad number optional
gamepadWasReleased(button, gamepad) → booleanengineInput.js:336

Returns true if gamepad button was released

button number
gamepad number optional
inputClear()engineInput.js:189

Clears all input

inputClearKey(key, device, clearDown, clearPressed, clearReleased)engineInput.js:133

Clear a key's state, so it stops reading as down, pressed or released this frame; a key still held is not pressed again until it is let go

key string|number

A key code like 'Space', or a mouse or gamepad button number

device number optional, default 0

0 for the keyboard and mouse, gamepad n is device n + 1

clearDown boolean optional, default true

Clear the held state

clearPressed boolean optional, default true

Clear the pressed this frame state

clearReleased boolean optional, default true

Clear the released this frame state

keyDirection(up, down, left, right) → Vector2engineInput.js:267

Returns input vector from arrow keys or WASD if enabled

up string optional, default ArrowUp
down string optional, default ArrowDown
left string optional, default ArrowLeft
right string optional, default ArrowRight
keyIsDown(key, device) → booleanengineInput.js:220

Returns true if device key is down

key string|number
device number optional, default 0

0 for the keyboard and mouse, gamepad n is device n + 1

keyWasPressed(key, device) → booleanengineInput.js:235

Returns true if device key was pressed this frame

key string|number
device number optional, default 0

0 for the keyboard and mouse, gamepad n is device n + 1

keyWasReleased(key, device) → booleanengineInput.js:250

Returns true if device key was released this frame

key string|number
device number optional, default 0

0 for the keyboard and mouse, gamepad n is device n + 1

mouseIsDown(button) → booleanengineInput.js:281

Returns true if mouse button is down

button number
mouseWasPressed(button) → booleanengineInput.js:291

Returns true if mouse button was pressed

button number
mouseWasReleased(button) → booleanengineInput.js:301

Returns true if mouse button was released

button number
pointerLockExit()engineInput.js:461

Request to unlock the pointer

pointerLockIsActive() → booleanengineInput.js:470

Check if pointer is locked (true if locked)

pointerLockRequest()engineInput.js:447

Request to lock the pointer, for a mouse; a device with only touch refuses it, and a press that came from a touch does not ask, since a locked pointer stops the touch gamepad taking its fingers

setInputMouseMoveThreshold(threshold)engineInput.js:110

Set the screen-pixel mouse movement per frame that counts as using the mouse

threshold number
setInputPreventDefault(preventDefault)engineInput.js:105

Prevents input continuing to the default browser handling This is useful to disable for html menus so the browser can handle input normally, the right click menu included; over an html text field that menu always shows

  • While on, the mouse's back and forward buttons don't leave the page, a game can read them as mouse 3 and 4
preventDefault boolean optional, default true
touchGamepadButtonPos(button) → TouchGamepadButtonPos|undefinedengineInput.js:1586

Returns where a button of the touch gamepad is on screen, to draw an icon of the game's own over it

  • Undefined when the touch gamepad is not showing that button: off, not a touch device, or no such button, or when its center is off the canvas, as in a letterbox bar with canvasFixedSize; one partly off it has its size
  • Buttons 0 to 3 are the right side's, 4 to 7 the left side's when it has buttons instead of a stick
  • Follows the layout, touchGamepadSize, the screen's safe area and setMouseScreenTransform
button number
// in gameRenderPost, an icon centered in the action button that fades with it
const b = touchGamepadButtonPos(0);
if (b && b.alpha)
{
    const color = hsl(0, 0, 1, b.alpha / touchGamepadAlpha); // fades with the buttons
    drawTile(b.pos, vec2(b.size * .6), actionIcon, color, 0, false, undefined, glEnable, true);
}
usingGamepadInput() → booleanengineInput.js:123

Is a gamepad the most recently used input device?

usingKeyboardInput() → booleanengineInput.js:119

Is the keyboard the most recently used input device?

usingMouseInput() → booleanengineInput.js:115

Is the mouse the most recently used input device?

vibrate(pattern)engineInput.js:431

Pulse the vibration hardware if it exists

pattern number|Array<number> optional, default 100

single value in ms or vibration interval array

vibrateStop()engineInput.js:439

Cancel any ongoing vibration

Members

gamepadPrimary : numberengineInput.js:93

Primary gamepad index, automatically set to first gamepad with input

inputMouseMoveThreshold : number default 6engineInput.js:83

Screen-pixel mouse movement per frame that counts as "using the mouse" (so sub-pixel hand jitter doesn't steal focus from the keyboard/gamepad).

inputPreventDefault : booleanengineInput.js:88

Prevents input continuing to the default browser handling (true by default)

isUsingGamepad : booleanengineInput.js:65

True if a gamepad is the most recently used input device. Equivalent to usingGamepadInput(); derived from lastInputDevice each frame.

lastInputDevice : 'mouse'|'keyboard'|'gamepad'engineInput.js:76

The most recently used input device: 'mouse' | 'keyboard' | 'gamepad'. Sticky: it holds its value while every device is idle, so a mouse-follow control (e.g. paddle = mousePos) won't snap back the instant the stick/keys are released. With several devices in play at once (e.g. keyboard to move + mouse to aim) it tracks whichever was touched last each frame, so it may alternate — that's intended; use it to pick which control drives a shared action. Updated every frame by inputUpdate().

Mouse movement delta in world space

mouseDeltaScreen : Vector2engineInput.js:34

Mouse movement delta in screen space

mouseInWindow : booleanengineInput.js:59

True if mouse was inside the document window, set to false when mouse leaves

Mouse pos in world space

mousePosScreen : Vector2engineInput.js:24

Mouse pos in screen space, in canvas pixels counted as the draws count them: pixel n is n - .5 to n + .5, so it runs from -.5 to the canvas size less .5, and is a pixel's number when the pointer is over that pixel's middle

mouseWheel : numberengineInput.js:39

Mouse wheel delta this frame

touchPinch : numberengineInput.js:46

Touch pinch delta this frame, in the mouse wheel's units: two fingers moving apart are negative, as the wheel turned up is, and moving together positive, 1 for every 50 pixels; a trackpad pinch too while touchPinchWheel is on; added to mouseWheel while touchPinchWheel is on, so a game that zooms with the wheel zooms with a pinch

Constants

isTouchDeviceengineInput.js:97

True if a touch device has been detected

Typedefs

TouchGamepadButtonPos : ObjectengineInput.js:1562

Where a touch gamepad button is on screen, its size and how visible it is

pos Vector2

Its center in screen space, as mousePosScreen

size number

Its diameter in screen pixels

alpha number

How visible the gamepad is now, 0 when it has faded out, up to touchGamepadAlpha, 1 in the debug gamepad view