Input
The input API allows precise filtering of all keyboard and mouse input to the game. Although its main use case is for detecting hotkeys being pressed or making sure the user does not interrupt a scripted action, it can also be used to synthesize user input when the Me namespace does not expose requried functionality.
Detecting input
The basic primitives for detecting user input are GetKey(s) and GetMouse. Since games often lock cursor position to the middle of the screen, the mouse information is in terms of change in position and will be reset to zero after each frame.
-- Returns true if the key 'k' is down.
bool Input.GetKey(VKey k, bool? asGame)
-- Retuns a list of all keys down.
VKey[] Input.GetKeys(bool? asGame)
-- Returns change in cursor(xy, pixels) and mouse wheel(z, steps) positions.
vec3 Input.GetMouse(bool? asGame)
As you might have noticed, both take an optional asGame parameter, this is used to distinguish between the user input and the input observed by the game. When set to true, the result will include any of our changes such as inputs being discarded due to blocking and synthesized inputs.
For press events rather than hold events, instead of using GetKey(s) every frame, you can use the event KeyDown.
-- Invoked each time user presses a key.
Event<VKey> Event.OnKeyDown
In addition to these primitives, there's also TestKeys which takes an array of keys to simplify checking states of key combinations with a varying number of elements, and the convenience function IsActive to check if the game window is active.
-- Returns true if all of the keys specified in the array are down.
bool Input.TestKeys(VKey[] k, bool? asGame)
-- Returns true if the game window is on the foreground.
bool Input.IsActive()
Blocking input
Blocking of keys is achieved by the primitives BlockKey and BlockMouse, similar to GetMouse the block flags will be reset after each frame to make sure an error whilist executing a script does not leave the player paralysed.
-- Blocks the given keyboard key or mouse button, if not given all.
void Input.BlockKey(VKey? k)
-- Blocks all mouse movement.
void Input.BlockMouse()
Synthesizing input
Synthesizing input is achieved by using the SendKey and MoveMouse primitives both of which are relatively self explanatory to use. However one quirk with them is that they can fail, which can be caused by the game window not being active or simply invalid arguments; so make sure to check the return value before assuming it went through.
-- Synthesizes the key state change, returns false on failure.
bool Input.SendKey(VKey k, bool down)
-- Synthesizes the mouse movement, returns false on failure.
bool Input.MoveMouse(vec3 delta)
Additionally there's a helper function for sending the press and release motion together called PulseKey, which takes a simulated hold duration in milliseconds.
-- Synthesizes the key press and schedules its release, returns false on failure.
bool Input.PulseKey(VKey k, int ms)
List of keys
You can find all key enumerations under the namespace VKey and convert their values to string using the helper functions ToString/ToDisplayName.
-- Converts a virtual key enumerator back to it's name.
string VKey.ToString(VKey k)
-- Returns the user-displayed name for the given virtual key enumerator.
string VKey.ToDisplayName(VKey k)
-- Control keys.
--
VKey VKey.BACKSPACE
VKey VKey.CAPS_LOCK
VKey VKey.ENTER
VKey VKey.ESCAPE
VKey VKey.L_ALT
VKey VKey.L_CTRL
VKey VKey.L_SHIFT
VKey VKey.NUM_LOCK
VKey VKey.R_SHIFT
VKey VKey.SCRL_LOCK
VKey VKey.SPACE
VKey VKey.TAB
VKey VKey.R_ALT
VKey VKey.R_CTRL
VKey VKey.DOWN
VKey VKey.LEFT
VKey VKey.RIGHT
VKey VKey.UP
VKey VKey.DEL
VKey VKey.END
VKey VKey.HOME
VKey VKey.INSERT
VKey VKey.PG_DOWN
VKey VKey.PG_UP
-- Alpha numeric keys.
--
VKey VKey.KB_A
VKey VKey.KB_B
VKey VKey.KB_C
VKey VKey.KB_D
VKey VKey.KB_E
VKey VKey.KB_F
VKey VKey.KB_G
VKey VKey.KB_H
VKey VKey.KB_I
VKey VKey.KB_J
VKey VKey.KB_K
VKey VKey.KB_L
VKey VKey.KB_M
VKey VKey.KB_N
VKey VKey.KB_O
VKey VKey.KB_P
VKey VKey.KB_Q
VKey VKey.KB_R
VKey VKey.KB_S
VKey VKey.KB_T
VKey VKey.KB_U
VKey VKey.KB_V
VKey VKey.KB_W
VKey VKey.KB_X
VKey VKey.KB_Y
VKey VKey.KB_Z
VKey VKey.KB_1
VKey VKey.KB_2
VKey VKey.KB_3
VKey VKey.KB_4
VKey VKey.KB_5
VKey VKey.KB_6
VKey VKey.KB_7
VKey VKey.KB_8
VKey VKey.KB_9
VKey VKey.KB_0
-- F keys.
--
VKey VKey.F1
VKey VKey.F2
VKey VKey.F3
VKey VKey.F4
VKey VKey.F5
VKey VKey.F6
VKey VKey.F7
VKey VKey.F8
VKey VKey.F9
VKey VKey.F10
VKey VKey.F11
VKey VKey.F12
-- Numpad.
--
VKey VKey.NP_0
VKey VKey.NP_1
VKey VKey.NP_2
VKey VKey.NP_3
VKey VKey.NP_4
VKey VKey.NP_5
VKey VKey.NP_6
VKey VKey.NP_7
VKey VKey.NP_8
VKey VKey.NP_9
VKey VKey.NP_SEP
VKey VKey.NP_MUL
VKey VKey.NP_SUB
VKey VKey.NP_ADD
-- OEM specific keys, mapped to US QWERTY.
--
VKey VKey.KB_SUB -- '-'
VKey VKey.KB_ADD -- '+'
VKey VKey.KB_OBRKT -- '['
VKey VKey.KB_EBRKT -- ']'
VKey VKey.KB_SCOL -- ';'
VKey VKey.KB_TILDE -- '~'
VKey VKey.KB_QUOTE -- '''
VKey VKey.KB_COMMA -- ','
VKey VKey.KB_PERIOD -- '.'
VKey VKey.KB_BSLASH -- '\'
VKey VKey.KB_SLASH -- '/'
-- Mouse buttons.
--
VKey VKey.LBUTTON
VKey VKey.RBUTTON
VKey VKey.MBUTTON
VKey VKey.XBUTTON
VKey VKey.XBUTTON2