PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience
Collapse Sidebar

TouchStarted

The TouchStarted event fires when a user places their finger on a UserInputService/TouchEnabled|TouchEnabled device, beginning touch input with the device.

This event can be used to determine when a user starts touching the screen of their device. It can be paired with UserInputService/TouchEnded to determine when a user starts and stops touching the screen.

The touch input object is the same input object throughout the lifetime of the touch. So comparing InputObject|InputObjects when they are touch objects is valid to determine if it is the same finger.

To check if a user’s device is TouchEnabled, and that touch events will fire, see UserInputService/TouchEnabled.

This event only fires when the Roblox client window is in focus. For example, inputs will not be captured when the window is minimized.

As this event only fires locally, it can only be used in a LocalScript.

See also

  • UserInputService/TouchTap
  • UserInputService/TouchTapInWorld
  • UserInputService/TouchLongPress
  • UserInputService/TouchMoved
  • UserInputService/TouchPan
  • UserInputService/TouchPinch
  • UserInputService/TouchRotate
  • UserInputService/TouchSwipe
  • UserInputService/TouchEnded

Parameters

Name Type Default Description

An InputObject instance, which contains information about the user’s input

Indicates whether the game engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, gameProcessedEvent would be true. This is also true for input events connected via ContextActionService


Code Samples


Tracking Touches

The touch Enum/InputObject is the same input object throughout the lifetime of the touch. So comparing input objects when they are touch objects is valid to determine if it is the same finger.

This example demonstrates how to track touch InputObject|InputObjects to distinguish different fingers when - particularly when multiple fingers are touching the screen at the same time.

The example starts tracking a finger once the touch is registered by the UserInputService/TouchStarted|TouchStarted event. It continues to update the finger, tracking it’s position until its Enum/UserInputState|State is End or Cancel. The example also releases all fingers when the user UserInputService/WindowFocusReleased|minimizes the Roblox client or GuiService/MenuOpened|opens the menu screen.

local touch = {}

local UserInputService = game:GetService("UserInputService")
local UuiService = game:GetService("GuiService")

local fingerTracker = {}
touch.fingers = fingerTracker

local pressed = {}
local moved = {}
local lifted = {}

local function Connect(tab, func)
	tab[func] = true
	return function()
		tab[func] = nil
	end
end

local function Fire(tab, ...)
	for func in next, tab do
		func(...)
	end
end

function touch.Pressed(func)
	return Connect(pressed, func)
end

function touch.Moved(func)
	return Connect(moved, func)
end

function touch.Lifted(func)
	return Connect(lifted, func)
end

local function DoTouchEnded(io)
	local pos = io.Position
	local posx = pos.x
	local posy = pos.y
	
	local storedFingerData = fingerTracker[io]
	if storedFingerData ~= nil then
		local deltax = posx - storedFingerData.initx
		local deltay = posy - storedFingerData.initx
		Fire(lifted, io, posx, posy, deltax, deltay)
		fingerTracker[io] = nil
	end
end

local function DoTouchMoved(io)
	local pos = io.Position
	local posx = pos.x
	local posy = pos.y
	
	local storedFingerData = fingerTracker[io]
	if storedFingerData ~= nil then
		local deltax = posx - storedFingerData.initx
		local deltay = posy - storedFingerData.initx
		Fire(moved, io, posx, posy, deltax, deltay)
	end
end

local function TouchStarted(input)
	local pos = input.Position
	local posx = pos.x
	local posy = pos.y
	
	fingerTracker[input] = {initx = posx, inity = posy}
	Fire(pressed, input, posx, posy)
	
	input.Changed:Connect(function(property)
		if property == "Position" then
			DoTouchMoved(input)
		elseif property == "UserInputState" then
			if input.UserInputState == Enum.UserInputState.End or input.UserInputState == Enum.UserInputState.Cancel then
				DoTouchEnded(input)
			end
		end
	end)
end

local function ReleaseAll()
	for finger,_ in next, fingerTracker do
		DoTouchEnded(finger)
	end
	fingerTracker = {}
end

UserInputService.TouchStarted:Connect(TouchStarted)
UserInputService.WindowFocusReleased:Connect(ReleaseAll)
GuiService.MenuOpened:Connect(ReleaseAll)

return touch