Input
The Input namespace contains functions and hooks for responding to player input. Lean more about how to use the Input system in our Binding Sets reference.
Class Functions
Class Function Name | Return Type | Description | Tags |
---|---|---|---|
Input.GetActionValue(Player, string actionName) | value | Returns the current input value associated with the specified action. This will return a Vector2 for direction bindings, a number for basic and axis bindings, or nil for invalid bindings. nil may also be returned when called on the server with a non-networked action name or a networked action which simply hasn't been pressed yet. | None |
Input.IsActionHeld(Player, string actionName) | boolean | Returns true if the specified action is currently being held by the player, otherwise returns false . | None |
Input.GetCurrentInputType() | InputType | Returns the current active input type. | Client-Only |
Input.IsYAxisInverted(InputType) | boolean | Returns true if the player has inverted the Y axis in their settings for the given input type, otherwise returns false . | Client-Only |
Input.GetActionDescription(string actionName) | string | Returns the description set in the Bindings Manager for the specified action. Returns nil if given an invalid action name. | Client-Only |
Input.GetActions() | Array <string > | Returns a list of the names of each action from currently active binding sets. Actions are included in this list regardless of whether the action is currently held or not. | Client-Only |
Input.GetActionInputLabel(string actionName, [table parameters]) | string | Returns a string label indicating the key or button assigned to the specified action. Returns nil if actionName is not a valid action or if an invalid direction parameter is specified for axis and direction bindings. Returns "None" for valid actions with no control bound. Supported parameters include: direction (string) : Required for axis and direction bindings, specifying "positive" or "negative" for axis bindings, or "up", "down", "left", or "right" for direction bindings. inputType (InputType) : Specifies whether to return a label for keyboard and mouse or controller. Defaults to the current active input type. secondary (boolean) : When true and returning a label for keyboard and mouse, returns a label for the secondary input. | Client-Only |
Input.IsInputTypeEnabled(InputType) | boolean | Returns true when the current device supports the given input type. For example, Input.IsInputEnabled(InputType.CONTROLLER) will return true if a gamepad is connected. | Client-Only |
Input.IsActionEnabled(string actionName) | boolean | Returns true if the specified action is enabled. Returns false if the action is disabled or does not exist. | Client-Only |
Input.EnableAction(string actionName) | None | Enables the specified action, if the action exists. | Client-Only |
Input.DisableAction(string actionName) | None | Disables the specified action, if the action exists. If the action is currently held, this will also release the action. | Client-Only |
Input.GetCursorPosition() | Vector2 | Returns a Vector2 with the x , y coordinates of the mouse cursor on the screen. May return nil if the cursor position cannot be determined. | Client-Only |
Input.GetTouchPosition([integer touchIndex]) | Vector2 | Returns a Vector2 with the x , y coordinates of a touch input on the screen. An optional touch index may be provided to specify which touch to return on multitouch devices. If not specified, index 1 is used. Returns nil if the requested touch index is not currently active. | Client-Only |
Input.GetPointerPosition([integer touchIndex]) | Vector2 | When the current input type is InputType.TOUCH , returns a Vector2 with the x , y coordinates of a touch input on the screen. When the current input type is not InputType.TOUCH , returns the cursor position. An optional touch index may be provided to specify which touch to return on multitouch devices. If not specified, index 1 is used. Returns nil if the requested touch index is not currently active. The touch index is ignored for other input types. | Client-Only |
Input.GetPinchValue() | number | During a pinch gesture with touch input, returns a value indicating the relative progress of the pinch gesture. Pinch gestures start with a pinch value of 1 and approach 0 when pinching together, or increase past 1 when touches move apart from each other. Returns 0 if no pinch is in progress. | Client-Only |
Input.GetRotateValue() | number | During a rotate gesture with touch input, returns a value indicating the angle of rotation from the start of the gesture. Returns 0 if no rotate is in progress. | Client-Only |
Input.EnableVirtualControls() | None | Enables display of virtual controls on devices with touch input, or in preview mode if device emulation is enabled. Virtual controls default to enabled when using touch input. | Client-Only |
Input.DisableVirtualControls() | None | Disables display of virtual controls on devices with touch input, or in preview mode with device emulation enabled. | Client-Only |
Events
Event Name | Return Type | Description | Tags |
---|---|---|---|
Input.actionPressedEvent | Event <Player player, string actionName, value value> | Fired when a player starts an input action by pressing a key, button, or other input control. The third parameter, value , will be a Vector2 for direction bindings, or a number for axis and basic bindings. | None |
Input.actionReleasedEvent | Event <Player player, string actionName> | Fired when a player stops an input action by releasing a key, button, or other input control. | None |
Input.inputTypeChangedEvent | Event <Player player, InputType inputType> | Fired when the active input device has changed to a new type of input. | None |
Input.touchStartedEvent | Event <Vector2 location, integer touchIndex> | Fired when the player starts touching the screen on a touch input device. Parameters are the screen location of the touch and a touch index used to distinguish between separate touches on a multitouch device. | Client-Only |
Input.touchStoppedEvent | Event <Vector2 location, integer touchIndex> | Fired when the player stops touching the screen on a touch input device. Parameters are the screen location from which the touch was released and a touch index used to distinguish between separate touches on a multitouch device. | Client-Only |
Input.tappedEvent | Event <Vector2 location, integer touchIndex> | Fired when the player taps on a touch input device. Parameters are the screen location of the tap and the touch index with which the tap was performed. | Client-Only |
Input.flickedEvent | Event <number angle> | Fired when the player performs a quick flicking gesture on a touch input device. The angle parameter indicates the direction of the flick. 0 indicates a flick to the right. Values increase in degrees counter-clockwise, so 90 indicates a flick straight up, 180 indicates a flick to the left, etc. | Client-Only |
Input.pinchStartedEvent | Event | Fired when the player begins a pinching gesture on a touch input device. Input.GetPinchValue() may be polled during the pinch gesture to determine how far the player has pinched. | Client-Only |
Input.pinchStoppedEvent | Event | Fired when the player ends a pinching gesture on a touch input device. | Client-Only |
Input.rotateStartedEvent | Event | Fired when the player begins a rotating gesture on a touch input device. Input.GetRotateValue() may be polled during the rotate gesture to determine how far the player has rotated. | Client-Only |
Input.rotateStoppedEvent | Event | Fired when the player ends a rotating gesture on a touch input device. | Client-Only |
Input.pointerMovedEvent | Event <Vector2 delta, integer touchIndex> | Fired when the pointer (either the mouse or a touch input) has moved. Parameters include the change in position since the last time pointerMovedEvent was fired for the given pointer, and an optional touch index indicating which touch input moved. touchIndex will be nil when the mouse has moved. | Client-Only |
Input.mouseButtonPressedEvent | Event <Vector2 position, MouseButton > | Fired when the user has pressed a mouse button. Parameters indicate the screen position of the cursor when the button was pressed, and an enum value indicating which mouse button was pressed. | Client-Only |
Input.mouseButtonReleasedEvent | Event <Vector2 position, MouseButton > | Fired when the user has released a mouse button. Parameters indicate the screen position of the cursor when the button was released, and an enum value indicating which mouse button was released. | Client-Only |
Hooks
Hook Name | Return Type | Description | Tags |
---|---|---|---|
escapeHook | Hook <Player player, table parameters> | Hook called when the local player presses the Escape key. The parameters table contains a boolean named "openPauseMenu", which may be set to false to prevent the pause menu from being opened. Players may press Shift-Esc to force the pause menu to open without calling this hook. | Client-Only |
actionHook | Hook <Player player, table actionList> | Hook called each frame with a list of changes in action values since the previous frame. The actionList table is an array of tables with the structure {action = "actionName", value = number or Vector2 } for each action whose value has changed since the last frame. If no values have changed, actionList will be empty, even if there are actions currently being held. Entries in the table can be added, removed, or changed and will affect whether pressed and released events fire. If a non-zero value is changed to zero then Input.actionReleasedEvent will fire for that action. If a zero value changes to non-zero then Input.actionPressedEvent will fire. | Client-Only |
Examples
Example using:
DisableVirtualControls
EnableVirtualControls
In this example, a trigger is setup to display a UI dialog to any player who walks over it. When this happens, virtual touch controls are disabled. Simultaneously, we tell Core to enable cursor controls. This dual approach broadens the game's support for different types of devices. If the device doesn't support touch or a cursor the corresponding command has no effect. We also setup a UI button that can be used for closing the dialog. When the dialog is closed the touch/cursor controls are set back to normal.
local TRIGGER = script:GetCustomProperty("Trigger"):WaitForObject()
local UIPANEL = script:GetCustomProperty("UIPanel"):WaitForObject()
local CLOSE_BUTTON = script:GetCustomProperty("CloseButton"):WaitForObject()
UIPANEL.visibility = Visibility.FORCE_OFF
local function OnBeginOverlap()
Input.DisableVirtualControls()
UI.SetCursorVisible(true)
UI.SetCanCursorInteractWithUI(true)
UIPANEL.visibility = Visibility.FORCE_ON
end
local function OnButtonClicked()
Input.EnableVirtualControls()
UI.SetCursorVisible(false)
UI.SetCanCursorInteractWithUI(false)
UIPANEL.visibility = Visibility.FORCE_OFF
end
TRIGGER.beginOverlapEvent:Connect(OnBeginOverlap)
CLOSE_BUTTON.clickedEvent:Connect(OnButtonClicked)
See also: Trigger.beginOverlapEvent | UIButton.clickedEvent | UI.SetCursorVisible | CoreObject.visibility | CoreObjectReference.WaitForObject
Example using:
GetCursorPosition
In this client script we listen for the player's shoot action (left mouse click) then print the position of their cursor to the event log.
local function OnActionPressed(player, action)
if action == "Shoot" then
local cursorPos = Input.GetCursorPosition()
if cursorPos then
print("Clicked at: " .. cursorPos.x .. ", " .. cursorPos.y)
else
print("Clicked at an undefined position.")
end
end
end
Input.actionPressedEvent:Connect(OnActionPressed)
See also: Game.GetLocalPlayer | Input.actionPressedEvent | Vector2.x
Example using:
GetTouchPosition
GetPinchValue
GetRotateValue
pinchStartedEvent
pinchStoppedEvent
rotateStartedEvent
rotateStoppedEvent
In this example we manipulate an image with a multi-touch pinching gesture. The pinch gesture is used to move, scale and rotate a 2D image on screen.
local UIIMAGE = script:GetCustomProperty("UIImage"):WaitForObject()
UIIMAGE.anchor = UIPivot.MIDDLE_CENTER
local isPinching = false
local isRotating = false
local startingWidth
local startingHeight
local startingAngle
function Tick()
-- Position
local touch1 = Input.GetTouchPosition(1)
local touch2 = Input.GetTouchPosition(2)
if touch1 ~= nil and touch2 ~= nil then
local position = (touch1 + touch2) / 2
UIIMAGE:SetAbsolutePosition(position)
end
-- Scale
if isPinching then
local pinchPercent = Input.GetPinchValue()
UIIMAGE.width = CoreMath.Round(startingWidth * pinchPercent)
UIIMAGE.height = CoreMath.Round(startingHeight * pinchPercent)
end
-- Rotate
if isRotating then
local angle = Input.GetRotateValue()
UIIMAGE.rotationAngle = startingAngle + angle
end
end
local function PinchStarted()
isPinching = true
startingWidth = UIIMAGE.width
startingHeight = UIIMAGE.height
end
local function PinchStopped()
isPinching = false
end
-- Detect pinch gesture start/end
Input.pinchStartedEvent:Connect(PinchStarted)
Input.pinchStoppedEvent:Connect(PinchStopped)
local function RotateStarted()
isRotating = true
startingAngle = UIIMAGE.rotationAngle
end
local function RotateStopped()
isRotating = false
end
-- Detect rotation gesture start/end
Input.rotateStartedEvent:Connect(RotateStarted)
Input.rotateStoppedEvent:Connect(RotateStopped)
See also: UIControl.SetAbsolutePosition | CoreObject.GetCustomProperty | CoreObjectReference.WaitForObject
Example using:
mouseButtonPressedEvent
mouseButtonReleasedEvent
A power meter is a common mechanic in games, especially sports. For this example, detecting when the mouse buttons are pressed and released will control the progress of a UIProgressBar.
local POWER_METER = script:GetCustomProperty("PowerMeter"):WaitForObject()
local POWER_SPEED = script:GetCustomProperty("PowerSpeed")
local mouseDown = false
function Tick(deltaTime)
if mouseDown then
POWER_METER.progress = POWER_METER.progress + deltaTime / POWER_SPEED
end
end
local function OnMousePressed()
POWER_METER.progress = 0
mouseDown = true
end
local function OnMouseReleased()
mouseDown = false
end
Input.mouseButtonPressedEvent:Connect(OnMousePressed)
Input.mouseButtonReleasedEvent:Connect(OnMouseReleased)
See also: CoreObject.GetCustomProperty | CoreObjectReference.WaitForObject | UIProgressBar.progress | CoreLua.Tick
Example using:
pointerMovedEvent
In this example, the script will print to the Event Log the distance the mouse cursor or touch index traveled.
local function OnPointerMoved(offsetVector, touchIndex)
local distance = offsetVector.size
if touchIndex == nil then
print("Mouse traveled " .. distance)
else
print("Touch index " .. touchIndex .. " traveled " .. distance)
end
end
Input.pointerMovedEvent:Connect(OnPointerMoved)
See also: Vector2 | Event.Connect
Example using:
tappedEvent
flickedEvent
In this example we listen for the tapped and flicked touch gestures. When one of those events is triggered, the pertinent information is printed to the screen.
function OnTappedEvent(location, touchIndex)
UI.PrintToScreen("Tap ".. touchIndex ..": ".. tostring(location))
end
function OnFlickedEvent(angle)
UI.PrintToScreen("Flick: " .. angle)
end
Input.tappedEvent:Connect(OnTappedEvent)
Input.flickedEvent:Connect(OnFlickedEvent)
See also: UI.PrintToScreen | Event.Connect
Example using:
touchStartedEvent
touchStoppedEvent
In this example, touch inputs are tracked in two different ways, with a counter and with a table. Each time the amount of touches change a summary of the touch information is printed to screen.
local touchCount = 0
local activeTouches = {}
function OnTouchStarted(screenPosition, touchId)
touchCount = touchCount + 1
activeTouches[touchId] = true
PrintTouchInfo()
end
function OnTouchStopped(screenPosition, touchId)
touchCount = touchCount - 1
activeTouches[touchId] = nil
PrintTouchInfo()
end
Input.touchStartedEvent:Connect(OnTouchStarted)
Input.touchStoppedEvent:Connect(OnTouchStopped)
function PrintTouchInfo()
local str = touchCount .. ": ["
local addComma = false
for id,_ in pairs(activeTouches) do
if addComma then
str = str .. ", "
end
addComma = true
str = str .. id
end
str = str .. "]"
UI.PrintToScreen(str)
end
See also: UI.PrintToScreen | Event.Connect
Example using:
actionHook
In this example we override the jump action to make all players automatically jump every second.
local JUMP_PERIOD = 1
local nextJumpTime = 0
function OnAction(player, actionList)
-- Verbose output of all actions to the Event Log
for k,v in ipairs(actionList) do
print(tostring(k), tostring(v.action), tostring(v.value))
end
-- Everyone periodically jumps automatically
if time() > nextJumpTime then
-- Jump
nextJumpTime = time() + JUMP_PERIOD
actionList[1] = {
action = "Jump",
value = 1.0
}
else
-- No jump
actionList[1] = {
action = "Jump",
value = 0.0
}
end
end
Input.actionHook:Connect(OnAction)
See also: Hook.Connect
Example using:
IsActionEnabled
EnableAction
DisableAction
In this example players are prevented from jumping while moving. Also, a UI element is toggled on/off to indicate when jump is available.
local JUMP_ICON = script:GetCustomProperty("JumpIcon"):WaitForObject()
function Tick()
if Input.IsActionEnabled("Jump") then
JUMP_ICON.visibility = Visibility.INHERIT
else
JUMP_ICON.visibility = Visibility.FORCE_OFF
end
end
function OnAction(player, actionList)
for k,v in ipairs(actionList) do
-- Verbose output of all actions to the Event Log
print(tostring(k), tostring(v.action), tostring(v.value))
-- Toggle jump on/off, depending on movement
if v.action == "Move" then
if v.value == Vector2.ZERO then
Input.EnableAction("Jump")
else
Input.DisableAction("Jump")
end
end
end
end
Input.actionHook:Connect(OnAction)
See also: CoreObject.visibility | CoreObjectReference.WaitForObject | Hook.Connect
Example using:
GetActionInputLabel
This client script shows how to get the "display name" for the jump action. It may usually say "Space Bar". However, the user could bind different keys to their inputs, or the value may differ due to localization. If you were to hardcode the words "Space Bar" into the user interface, it would be misleading for some users. Instead, call Input.GetActionInputLabel()
and use the returned value to populate the UI.
local UI_TEXT = script:GetCustomProperty("UIText"):WaitForObject()
local label = Input.GetActionInputLabel("jump", {inputType = InputType.KEYBOARD_AND_MOUSE})
print(tostring(label))
UI_TEXT.text = label
Example using:
actionPressedEvent
Hotbars in games are a useful way for players to access things such as abilities, weapons, or tools quickly. This example shows how the mouse wheel can be used to scroll through all the slots in a hotbar. It supports wrapping around when scrolling past the start or end of the hotbar.
-- Client script.
-- The container that holds the slots.
local SLOTS_CONTAINER = script:GetCustomProperty("SlotsContainer"):WaitForObject()
-- The color of the slot frame when it is active.
local ACTIVE_COLOR = script:GetCustomProperty("ActiveColor")
-- The color of the slot frame when it is inactive.
local INACTIVE_COLOR = script:GetCustomProperty("InactiveColor")
-- The current active slot index.
local currentSlotIndex = 1
-- All the slots in the container.
local slots = SLOTS_CONTAINER:GetChildren()
-- Total slots, just caching it here for use later.
local totalSlots = #slots
-- Sets a slot to become active based on the index passed in.
local function SetActiveSlot(index)
slots[index]:FindChildByName("Frame"):SetColor(ACTIVE_COLOR)
end
-- Clears the last active slot based on the index passed in.
local function ClearActiveSlot(index)
slots[index]:FindChildByName("Frame"):SetColor(INACTIVE_COLOR)
end
local function OnActionPressed(player, action, value)
-- Checks to see if the action is the Zoom action.
-- This could be a custom action, doesn't need to be named "Zoom".
if action == "Zoom" then
-- Need to store the old slot to compare later on.
local oldSlotIndex = currentSlotIndex
-- Scroll wheel will either be -1 or 1.
if value > 0 then
currentSlotIndex = currentSlotIndex == totalSlots and 1 or (currentSlotIndex + 1)
elseif value < 0 then
currentSlotIndex = currentSlotIndex == 1 and totalSlots or (currentSlotIndex - 1)
end
-- If the slot has changed, clear the old one and set the new one.
if oldSlotIndex ~= currentSlotIndex then
ClearActiveSlot(oldSlotIndex)
SetActiveSlot(currentSlotIndex)
end
end
end
-- Listens for when an action is pressed.
Input.actionPressedEvent:Connect(OnActionPressed)
-- Set the active slot from the start (1 in this case).
SetActiveSlot(currentSlotIndex)
See also: CoreObject.GetCustomProperty | CoreObjectReference.WaitForObject | UIImage.SetColor
Example using:
actionPressedEvent
actionReleasedEvent
This client script demonstrates how to listen for all input actions being pressed/released. Results appear in the Event Log.
function OnActionPressed(player, action, value)
print("Action: " .. action .. ", value: " .. tostring(value))
end
function OnActionReleased(player, action)
print("Action: " .. action)
end
Input.actionPressedEvent:Connect(OnActionPressed)
Input.actionReleasedEvent:Connect(OnActionReleased)
Example using:
escapeHook
Core has a default pause menu that appears when a player presses the ESC key. This client script demonstrates how to prevent Core's default pause from occurring and replace it with a custom menu. As a fallback in case your UI gets stuck, Shift + ESC allows you to access Core's default pause, even with the escape hook in place.
-- "MenuPanel" is a UI Panel assigned as a custom property to the script.
local CUSTOM_MENU = script:GetCustomProperty("MenuPanel"):WaitForObject()
-- "ExitButton" is a UI Button within that panel. Also assigned as a custom property.
local EXIT_BUTTON = script:GetCustomProperty("ExitButton"):WaitForObject()
CUSTOM_MENU.visibility = Visibility.FORCE_OFF
local isShowingMenu = false
function ShowMenu()
-- Show our custom menu and enable mouse control
isShowingMenu = true
CUSTOM_MENU.visibility = Visibility.INHERIT
UI.SetCanCursorInteractWithUI(true)
UI.SetCursorVisible(true)
end
function HideMenu()
-- Hide our custom menu and disable mouse control
isShowingMenu = false
CUSTOM_MENU.visibility = Visibility.FORCE_OFF
UI.SetCanCursorInteractWithUI(false)
UI.SetCursorVisible(false)
end
function OnEscape(localPlayer, params)
-- Prevents Core's default pause from appearing
params.openPauseMenu = false
-- Toggle the custom menu on/off
if isShowingMenu then
HideMenu()
else
ShowMenu()
end
end
-- Intercept the ESC key being pressed
Input.escapeHook:Connect(OnEscape)
local function DoTransfer()
Game.GetLocalPlayer():TransferToGame("e39f3e/core-world")
end
-- Send players to Core World when they press the custom "Exit" button
EXIT_BUTTON.clickedEvent:Connect(DoTransfer)
See also: Player.TransferToGame | UIButton.clickedEvent | UI.SetCanCursorInteractWithUI | Game.GetLocalPlayer
Example using:
inputTypeChangedEvent
In this example, the UI will update to show what input type the player is currently using, and will update the UI when the player changes the input type.
-- Client script.
-- UI image for mouse input.
local MOUSE_IMAGE = script:GetCustomProperty("MouseImage"):WaitForObject()
-- UI image for controller input.
local CONTROLLER_IMAGE = script:GetCustomProperty("ControllerImage"):WaitForObject()
-- Fired when the input has changed.
local function UpdateInputImage(player, changedInputType)
-- Check the changed input type by comparing with the
-- InputType enum.
if changedInputType == InputType.KEYBOARD_AND_MOUSE then
MOUSE_IMAGE.visibility = Visibility.FORCE_ON
CONTROLLER_IMAGE.visibility = Visibility.FORCE_OFF
elseif changedInputType == InputType.CONTROLLER then
MOUSE_IMAGE.visibility = Visibility.FORCE_OFF
CONTROLLER_IMAGE.visibility = Visibility.FORCE_ON
end
end
Input.inputTypeChangedEvent:Connect(UpdateInputImage)
-- Update the input type image first time
UpdateInputImage(Game.GetLocalPlayer(), Input.GetCurrentInputType())
See also: CoreObject.GetCustomProperty | Game.GetLocalPlayer | CoreObjectReference.WaitForObject | Input.GetCurrentInputType | KEYBOARD_AND_MOUSE