GSmGpE6CwX2y9JjB25B8
We use cookies on this site to enhance your user experience

Creating Mobile Buttons

Creating Mobile Buttons

Sep 03 2019, 1:29 PM PST 10 min

When designing an optimal cross-platform experience on Roblox, ContextActionService is a convenient service which lets you bind a function to traditional PC input and simultaneously create an on-screen button visible only on mobile devices. It also allows for quick manipulation of what input is tied to which functions, as well as when mobile action buttons are shown or not.

Adding Mobile Buttons

After ContextActionService has been declared in a LocalScript, the ContextActionService/BindAction|BindAction() method can be used to associate specific input with a function. This method takes the following parameters:

Parameter Type Description
actionName string A "key" used by other functions in ContextActionService to manipulate the binding.
functionToBind function The function to call when the specified input is triggered. This function will receive three arguments:
  • A string equal to the action name.
  • A enum/UserInputState|UserInputState which defines the input state when it called the function.
  • The InputObject that caused the function call.
createTouchButton boolean Whether or not you want an on-screen button to be created when the game is running on a mobile device.
inputTypes tuple The inputs you want to bind to the function, for instance enum values from enum/KeyCode|KeyCode.
local ContextActionService = game:GetService("ContextActionService")

local function interactNPC(actionName, inputState, inputObject)
	if inputState == Enum.UserInputState.Begin then
		print(actionName, inputObject)
	end
end

-- Bind action to function
ContextActionService:BindAction("InteractNPC", interactNPC, true, Enum.KeyCode.T, Enum.KeyCode.ButtonR1)
Reserved Keybindings »

When choosing enum/KeyCode values for ContextActionService/UserInputService or detecting Mouse events, note that some bindings are reserved by Roblox and should generally not be assigned to a game’s custom control bindings.

Character Movement
Key Codes and Events Action
W / Up Forward
S / Down Back
A / Left Left
D / Right Right
Space Jump
Camera
Key Codes and Events Action
Mouse/Button2Down Turn camera
Mouse/WheelForward / Mouse/WheelBackward Zoom in/out
I Zoom in
O Zoom out
LeftShift/RightShift Toggle mouselock (player setting if StarterPlayer/EnableMouseLockOption|EnableMouseLockOption is enabled)
Accessories
Key Codes and Events Action
Zero / One / Two / Three / Four / Five / Six / Seven / Eight / Nine Equip or unequip tools
Mouse/Button1Down Use tool
Backspace Drop tool
Menu and UI
Key Codes and Events Action
Escape Main menu
Tab Player list
Slash Chat
Backquote Backpack
F11 Fullscreen mode
LeftControl/RightControl + LeftShift/RightShift + G Toggle core UI
Miscellaneous
Key Codes / Events Action
Print (Windows)
LeftControl/RightControl + LeftShift/RightShift + 3 (Mac)
Take screenshot
F12 Record video (Windows only)
F10 Increase graphics level
LeftShift/RightShift + F10 Decrease graphics level
F9 Developer Console
LeftControl/RightControl + LeftShift/RightShift + F7 (Windows)
LeftControl/RightControl + LeftAlt/RightAlt + F7 (Mac)
Performance Stats
LeftControl/RightControl + F6 Show Microprofiler
LeftControl/RightControl + P Pause Microprofiler, if showing

Removing Mobile Buttons

If you want to remove a mobile button from the screen, call ContextActionService/UnbindAction|UnbindAction() with the sole argument of the actionName string you passed to ContextActionService/BindAction|BindAction().

-- Unbind action by name
ContextActionService:UnbindAction("InteractNPC")

Customizing Buttons

ContextActionService provides several functions to customize the buttons that are generated by ContextActionService/BindAction|BindAction().

Button Text

To change the text label for a mobile button, call ContextActionService/SetTitle|SetTitle() with the actionName string and a title:

-- Set button label to "Talk"
ContextActionService:SetTitle("InteractNPC", "Talk")

Button Image

Mobile buttons can use custom images just like other GUI buttons via the ContextActionService/SetImage|SetImage() method:

-- Set button image
ContextActionService:SetImage("InteractNPC", "rbxassetid://0123456789")

Button Position

To position a mobile button, use ContextActionService/SetPosition|SetPosition() and specify the desired datatype/UDim2:

-- Set button position
ContextActionService:SetPosition("InteractNPC", UDim2.new(1, -80, 1, -150))

Overriding Inputs

Because screen space on mobile devices is very limited, it’s best practice to use contextual buttons that perform different actions based on what the player can or can’t do. For instance, you may want to display an active “Collect” button when the player is standing near a chest of gold:

local ContextActionService = game:GetService("ContextActionService")

-- Collect treasure function
local function collectTreasure(actionName, inputState, inputObject)
	if inputState == Enum.UserInputState.Begin then
		print("Collect treasure")
	end
end

ContextActionService:BindAction("RightButton1", collectTreasure, true, Enum.KeyCode.T, Enum.KeyCode.ButtonR1)
ContextActionService:SetPosition("RightButton1", UDim2.new(1, -80, 1, -150))
-- Set image to blue "Collect" button
ContextActionService:SetImage("RightButton1", "rbxassetid://0123456789")

At another point in the game, you may wish to change the button to “Talk” when the player is standing near an NPC. Instead of adding a new button in the same place (and removing the old button), you can simply re-bind its action to a new function and change its image:

ContextActionService:BindAction("RightButton1", talkToNPC, true, Enum.KeyCode.T, Enum.KeyCode.ButtonR1)
-- Set image to yellow "Talk" button
ContextActionService:SetImage("RightButton1", "rbxassetid://0011223344")
Tags:
  • mobile
  • controls
  • button