Skip to main content

Input

Input-related APIs.

Events​

KeyDown: (key: number)​

The KeyDown event fires every time a key on the keyboard is pressed. The first argument is the numerical value of the key that was pressed. To get a list of non-numerical key values (such as the delete key), see Key.

Example that teleports the local player to their aim position when they press F:

Event.Add("OnKeyDown", function(key)
    if key == Key.F then
        local localPlayer = Players.LocalPlayer()
        local aimPos = localPlayer:GetAimPosition()
        Local.Teleport(aimPos)
    end
end)

KeyUp: (key: number)​

The KeyUp event fires every time a key on the keyboard is pressed. The first argument is the numerical value of the key that was pressed. To get a list of non-numerical key values (such as the delete key), see Key.

Example that teleports the local player to their aim position when they press F:

Event.Add("OnKeyUp", function(key)
    if key == Key.F then
        local localPlayer = Players.LocalPlayer()
        local aimPos = localPlayer:GetAimPosition()
        Local.Teleport(aimPos)
    end
end)

MouseDown​

The MouseDown event fires every time a button on the mouse is pressed down. Use Key.MouseLeft for left clicks, Key.MouseRight for right clicks, and Key.MouseMid for middle clicks.

Example that teleports the local player to their aim position when they left clicking:

Event.Add("OnMouseDown", function(key)
    if key == Key.MouseLeft then
        local localPlayer = Players.LocalPlayer()
        local aimPos = localPlayer:GetAimPosition()
        Local.Teleport(aimPos)
    end
end)

LocalPlayerInput: (action: Action)​

The LocalPlayerInput event fires every time an input action occurs for the local player. The first argument is the numerical value of the Action. To get a list of actions (such as the jump action), see Action. Actions are not guarantees that something actually happened - for example, pressing spacebar to jump while already jumping will trigger Action.Jump, but it will not jump again.

Example that prints a message to chat when the jump action occurs:

Event.Add("OnLocalPlayerInput", function(action)
    if action == Action.Jump then
        Chat.Print("Local player jumped!")
    end
end)

Global Methods​

Input.SetEnabled(enabled: boolean)​

Enables or disables player input. If disabled, all player input will be disabled - the player will not be able to move their character or camera. This is the same functionality that happens when you press T to open the chat window.

This is ref counted, meaning that for each time you disable input, you must enable input to restore player input. For example:

Input.SetEnabled(false)
Input.SetEnabled(false)
-- Requires 2 enables to fully enable input again
Input.SetEnabled(true)
Input.SetEnabled(true)

Input.IsEnabled(): boolean​

Returns true if input is enabled, false otherwise.

Input.IsKeyPressed(key: number): boolean​

Returns true if the key is currently being pressed, false otherwise. Refer to Key for a list of keys to use.

Input.IsKeyDown(key: number): boolean​

Returns true if the key is currently down, false otherwise. Refer to Key for a list of keys to use.

Input.IsKeyReleased(key: number): boolean​

Returns true if the key is released, false otherwise. Refer to Key for a list of keys to use.

Input.GetValue(action: Action): number​

Returns greater than 0 if the action is currently active, 0 otherwise. Refer to Action for a list of actions to use.

Input.GetClipboard(): string​

Returns the current contents of the system clipboard as a string.

Returns: string - The current clipboard contents

Example:

local clipboardText = Input.GetClipboard()
print("Clipboard contains: " .. clipboardText)

Input.SetClipboard(text: string)​

Sets the system clipboard to the specified text.

Parameters:

  • text: string - The text to set in the clipboard

Example:

Input.SetClipboard("Hello, world!")
print("Set clipboard to: " .. Input.GetClipboard())

Input.GetWheelValue(): vec2​

Returns the current scroll wheel delta since the last frame. X is horizontal, Y is vertical.

Returns: vec2 - The current wheel delta

Example:

local wheel = Input.GetWheelValue()
if wheel.y > 0 then
    print("Scrolled up")
elseif wheel.y < 0 then
    print("Scrolled down")
end

Additional Events​

OnMouseWheel(value: vec2)​

Fires when the mouse wheel is scrolled. value.x is horizontal and value.y is vertical scroll amount.

Parameters:

  • value: vec2 - The wheel delta for this event

Example:

Event.Add("OnMouseWheel", function(value)
    print("Wheel: " .. tostring(value))
end)