Engine Class
ContextActionService
Summary
Methods
BindAction(actionName: string,functionToBind: function,createTouchButton: boolean,inputTypes: Tuple):() |
BindActionToInputTypes(actionName: string,functionToBind: function,createTouchButton: boolean,inputTypes: Tuple):() |
BindActivate(userInputTypeForActivation: Enum.UserInputType,keyCodesForActivation: Tuple):() |
GetBoundActionInfo(actionName: string):Dictionary |
SetDescription(actionName: string,description: string):() |
SetPosition(actionName: string,position: UDim2):() |
UnbindAction(actionName: string):() |
UnbindActivate(userInputTypeForActivation: Enum.UserInputType,keyCodeForActivation: Enum.KeyCode):() |
UnbindAllActions():() |
Events
LocalToolEquipped(toolEquipped: Instance):RBXScriptSignal |
LocalToolUnequipped(toolUnequipped: Instance):RBXScriptSignal |
Code Samples
ContextActionService Tool Reload
local ContextActionService = game:GetService("ContextActionService")
local ACTION_RELOAD = "Reload"
local tool = script.Parent
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
print("Reloading!")
end
end
tool.Equipped:Connect(function()
ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)
tool.Unequipped:Connect(function()
ContextActionService:UnbindAction(ACTION_RELOAD)
end)API Reference
Methods
BindAction
Returns
()
Code Samples
ContextActionService Tool Reload
local ContextActionService = game:GetService("ContextActionService")
local ACTION_RELOAD = "Reload"
local tool = script.Parent
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
print("Reloading!")
end
end
tool.Equipped:Connect(function()
ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)
tool.Unequipped:Connect(function()
ContextActionService:UnbindAction(ACTION_RELOAD)
end)General Action Handler
local ContextActionService = game:GetService("ContextActionService")
local function handleAction(actionName, inputState, inputObj)
if inputState == Enum.UserInputState.Begin then
print("Handling action: " .. actionName)
print(inputObj.UserInputType)
end
-- Since this function does not return anything, this handler will
-- "sink" the input and no other action handlers will be called after
-- this one.
end
ContextActionService:BindAction("BoundAction", handleAction, false, Enum.KeyCode.F)Stacked Action Handlers
local ContextActionService = game:GetService("ContextActionService")
-- Define an action handler for FirstAction
local function actionHandlerOne(actionName, inputState, _inputObj)
if inputState == Enum.UserInputState.Begin then
print("Action Handler One: " .. actionName)
end
-- This action handler returns nil, so it is assumed that
-- it properly handles the action.
end
-- Binding the action FirstAction (it's on the bottom of the stack)
ContextActionService:BindAction("FirstAction", actionHandlerOne, false, Enum.KeyCode.Z, Enum.KeyCode.X, Enum.KeyCode.C)
-- Define an action handler for SecondAction
local function actionHandlerTwo(actionName, inputState, inputObj)
if inputState == Enum.UserInputState.Begin then
print("Action Handler Two: " .. actionName)
end
if inputObj.KeyCode == Enum.KeyCode.X then
return Enum.ContextActionResult.Pass
else
-- Returning nil implicitly Sinks inputs
return Enum.ContextActionResult.Sink
end
end
-- Binding SecondAction over the first action (since it bound more recently, it is on the top of the stack)
-- Note that SecondAction uses the same keys as
ContextActionService:BindAction("SecondAction", actionHandlerTwo, false, Enum.KeyCode.Z, Enum.KeyCode.X)BindActionAtPriority
Returns
()
Code Samples
ContextActionService BindAction Priorities
local ContextActionService = game:GetService("ContextActionService")
local INPUT_KEY1 = Enum.KeyCode.Q
local INPUT_KEY2 = Enum.KeyCode.E
local function handleThrow(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
if inputState ~= Enum.UserInputState.Begin then
return Enum.ContextActionResult.Pass
end
print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)
return Enum.ContextActionResult.Sink
end
local function handlePunch(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
if inputState ~= Enum.UserInputState.Begin then
return Enum.ContextActionResult.Pass
end
print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)
return Enum.ContextActionResult.Sink
end
-- Without specifying priority, the most recently bound action is called first,
-- so pressing INPUT_KEY1 prints "Punch" and then sinks the input.
ContextActionService:BindAction("DefaultThrow", handleThrow, false, INPUT_KEY1)
ContextActionService:BindAction("DefaultPunch", handlePunch, false, INPUT_KEY1)
-- Here we bind both functions in the same order as above, but with explicitly swapped priorities.
-- That is, we give "Throw" a higher priority of 2 so it will be called first,
-- despite "Punch" still being bound more recently.
-- Pressing INPUT_KEY2 prints "Throw" and then sinks the input.
ContextActionService:BindActionAtPriority("PriorityThrow", handleThrow, false, 2, INPUT_KEY2)
ContextActionService:BindActionAtPriority("PriorityPunch", handlePunch, false, 1, INPUT_KEY2)BindActionToInputTypes
BindActivate
ContextActionService:BindActivate(
):()
Parameters
Returns
()
GetBoundActionInfo
Parameters
Returns
GetButton
SetDescription
Returns
()
Code Samples
ContextActionService Touch Button
local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
endSetImage
Returns
()
Code Samples
ContextActionService Touch Button
local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
endSetPosition
Returns
()
Code Samples
ContextActionService Touch Button
local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
endSetTitle
Returns
()
Code Samples
ContextActionService Touch Button
local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
endUnbindAction
Parameters
Returns
()
Code Samples
ContextActionService Tool Reload
local ContextActionService = game:GetService("ContextActionService")
local ACTION_RELOAD = "Reload"
local tool = script.Parent
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
print("Reloading!")
end
end
tool.Equipped:Connect(function()
ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)
tool.Unequipped:Connect(function()
ContextActionService:UnbindAction(ACTION_RELOAD)
end)UnbindActivate
ContextActionService:UnbindActivate(
):()
Parameters
| Default Value: "Unknown" |
Returns
()
UnbindAllActions
ContextActionService:UnbindAllActions():()
Returns
()
Events
LocalToolEquipped
Parameters
LocalToolUnequipped
Parameters