Contains a Enum/UserInputState enum that describes the state of the user’s input and indicates how a user’s input is currently interacting with your game.
Enums
Name
Value
Description
Begin
0
When an InputObject starts to interact with the game. For example, a mouse button down, or a key down, or when a touch begins touching the screen.
Change
1
When an InputObjecthas already begun interacting with the game, and part of it’s state is changing. For example, a mouse position move, or a thumbstick moving, or when a touch begins to move across the screen.
End
2
When an InputObject finishes interacting with the game. For example, a mouse button up, or a key up, or when a touch stops touching the screen.
Cancel
3
A special circumstance state that indicates this input is now being used for some other function. For example, binding two actions to the same input will cause a function to fire with Cancel.
None
4
A state that should never be seen in a game, essentially just marks the end of the enum.
See also
InputObject/Delta
InputObject/KeyCode
InputObject/Position
InputObject/UserInputType
Code Samples
Create a Custom CameraScript
By default, Roblox relies on a LocalScript, described [here][1], to control the user’s camera. However, this script can be overridden with a custom CameraScript. The example below demonstrates how to create a custom script to control the user’s camera using many of the UserInputService events.
The script is broken into two parts:
Mobile camera events, which rely on touch events
Non-mobile camera events, which rely on keyboard input and tracking the user’s movement
First, the camera script needs utility functions to setup the camera and set its Camera/CameraType|CameraType to Scriptable so that the script can control the camera. It also needs a function to update the camera when it moves, rotates, and zooms.
Using touch events allows us to track user input as they interact with the touchscreen on their mobile device. These events allow us to handle camera movement, rotation, and zoom.
The second half of the code sample adds camera support for players on desktop devices. When input begans, the function Input() checks that the state of the input is Enum/UserInputState|Enum.UserInputState.Begin to ignore all keypress inputs other than when the user first presses a key down. When the user presses I and O the camera zooms in and out. When the presses down and moves their left mouse button, the script Enum/MouseBehavior|locks the player’s mouse by changing the UserInputService/MouseBehavior property. The camera rotates according to the mouse’s UserInputService/GetMouseDelta|change in screen position. When the player moves their character, the camera moves with them.
All of the parts discussed above are combined and shown in the code sample below.
-- ========================================
-- GLOBAL VARIABLES
-- ========================================
local UserInputService = game:GetService("UserInputService")
local RunService = game:GetService("RunService")
-- The camera used by the LocalPlayer
local camera = game.Workspace.CurrentCamera
local players = game:GetService("Players")
local player = players.LocalPlayer
local character = player.CharacterAdded:Wait()
local torso = character:WaitForChild("Torso")
local playerPosition = torso.Position
local default_CameraPosition = torso.Position
local default_CameraRotation = Vector2.new(0,math.rad(-60))
local default_CameraZoom = 15
local cameraPosition = default_CameraPosition
local cameraRotation = default_CameraRotation
local cameraZoom = default_CameraZoom
local cameraRotationBounds = {math.rad(-81),math.rad(20)}
local cameraZoomBounds = nil --{10,200}
local touchDragSpeed = 0.15
local cameraSpeed = 0.1
local cameraRotateSpeed = 10
local cameraMouseRotateSpeed = 0.25
local cameraTouchRotateSpeed = 10
-- ========================================
-- ========================================
-- ========================================
-- UTILITY FUNCTIONS
-- ========================================
local function SetCameraMode()
camera.CameraType = "Scriptable"
camera.FieldOfView = 80
camera.CameraSubject = nil
end
local function UpdateCamera()
SetCameraMode()
local cameraRotationCFrame = CFrame.Angles(0, cameraRotation.X, 0)*CFrame.Angles(cameraRotation.Y, 0, 0)
camera.CFrame = cameraRotationCFrame + cameraPosition + cameraRotationCFrame*Vector3.new(0, 0, cameraZoom)
camera.Focus = camera.CFrame - Vector3.new(0, camera.CFrame.p.Y, 0)
end
-- ========================================
-- ========================================
-- ========================================
-- MOBILE CAMERA EVENTS
-- ========================================
-- Events used to control the camera for players using a mobile device
-- ====================
-- CAMERA MOVE
-- ====================
-- Fired by UserInputService.TouchPan
local lastTouchTranslation = nil
local function TouchMove(touchPositions, totalTranslation, velocity, state)
if state == Enum.UserInputState.Change or state == Enum.UserInputState.End then
local difference = totalTranslation - lastTouchTranslation
cameraPosition = cameraPosition + Vector3.new(difference.X, 0, difference.Y)
UpdateCamera()
end
lastTouchTranslation = totalTranslation
end
-- ====================
-- CAMERA ROTATE
-- ====================
-- Fired by UserInputService.TouchRotate
local lastTouchRotation = nil
local function TouchRotate(touchPositions, rotation, velocity, state)
if state == Enum.UserInputState.Change or state == Enum.UserInputState.End then
local difference = rotation - lastTouchRotation
cameraRotation = cameraRotation + Vector2.new(-difference,0)*math.rad(cameraTouchRotateSpeed*cameraRotateSpeed)
UpdateCamera()
end
lastTouchRotation = rotation
end
-- ====================
-- CAMERA ZOOM
-- ====================
-- Fired by UserInputService.TouchPinch
local lastTouchScale = nil
local function TouchZoom(touchPositions, scale, velocity, state)
if state == Enum.UserInputState.Change or state == Enum.UserInputState.End then
local difference = scale - lastTouchScale
cameraZoom = cameraZoom * (1 + difference)
if cameraZoomBounds ~= nil then
cameraZoom = math.min(math.max(cameraZoom, cameraZoomBounds[1]), cameraZoomBounds[2])
else
cameraZoom = math.max(cameraZoom, 0)
end
UpdateCamera()
end
lastTouchScale = scale
end
local function Input()
UpdateCamera()
end
-- ========================================
-- ========================================
-- NON-MOBILE CAMERA EVENTS
-- ========================================
local function Input(inputObject)
if inputObject.UserInputType == Enum.UserInputType.Keyboard then
if inputObject.UserInputState == Enum.UserInputState.Begin then
-- ====================
-- CAMERA ZOOM
-- ====================
-- (I) Zoom In
if inputObject.KeyCode == Enum.KeyCode.I then
cameraZoom = cameraZoom - 15
elseif inputObject.KeyCode == Enum.KeyCode.O then
cameraZoom = cameraZoom + 15
end
-- (O) Zoom Out
if cameraZoomBounds ~= nil then
cameraZoom = math.min(math.max(cameraZoom, cameraZoomBounds[1]), cameraZoomBounds[2])
else
cameraZoom = math.max(cameraZoom, 0)
end
UpdateCamera()
end
end
-- ====================
-- CAMERA ROTATE
-- ====================
local pressed = UserInputService:IsMouseButtonPressed(Enum.UserInputType.MouseButton1)
if pressed then
UserInputService.MouseBehavior = Enum.MouseBehavior.LockCurrentPosition
local rotation = userInputService:GetMouseDelta()
cameraRotation = cameraRotation + rotation*math.rad(cameraMouseRotateSpeed)
else
UserInputService.MouseBehavior = Enum.MouseBehavior.Default
end
end
-- ====================
-- CAMERA MOVE
-- ====================
local function PlayerChanged()
local movement = torso.Position - playerPosition
cameraPosition = cameraPosition + movement
playerPosition = torso.Position
UpdateCamera()
end
-- ========================================
-- ========================================
-- ========================================
-- DEVICE CHECK
-- ========================================
-- Determine whether the user is on a mobile device
if UserInputService.TouchEnabled then
-- The user is on a mobile device, use Touch events
UserInputService.TouchPan:Connect(TouchMove)
UserInputService.TouchRotate:Connect(TouchRotate)
UserInputService.TouchPinch:Connect(TouchZoom)
else
-- The user is not on a mobile device use Input events
UserInputService.InputBegan:Connect(Input)
UserInputService.InputChanged:Connect(Input)
UserInputService.InputEnded:Connect(Input)
-- Camera controlled by player movement
wait(2)
RunService:BindToRenderStep("PlayerChanged", Enum.RenderPriority.Camera.Value-1, PlayerChanged)
end
-- ========================================
-- ========================================
This example gets a list of navigation gamepads and a list of their supported Enum/KeyCodes. Then, it iterates through the supported KeyCode list and binds the ButtonX and X keys to functions if they are supported by a gamepad using the ContextActionService/BindAction|ContextActionService.
Check out this article to learn more about adding support for gamepad input into your game.
local UserInputService = game:GetService("UserInputService")
local ContextActionService = game:GetService(“ContextActionService”)
local function actionHandler(actionName, inputState, inputObj)
if inputState == Enum.UserInputState.Begin then
print("Action Handler: " .. actionName)
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
local navGamepads = UserInputService:GetNavigationGamepads()
for _, gamepad in pairs(navGamepads) do
local supportedKeyCodes = UserInputService:GetSupportedGamepadKeyCodes()
for _, keycode in pairs(supportedKeyCodes) do
if (keycode == Enum.KeyCode.ButtonX) then
ContextActionService:BindAction(“SampleAction”, actionHandler, false, Enum.KeyCode.ButtonX)
end
if (keycode == Enum.KeyCode.X) then
ContextActionService:BindAction(“SampleAction”, actionHandler, false, Enum.KeyCode.X)
end
end
end
This Platform uses cookies to offer you a better experience, to personalize content, to provide social media features and to analyse the traffic on our site. For further information, including information on how to prevent or manage the use of cookies on this Platform, please refer to our Privacy and Cookie Policy.
