GetGuiObjectsAtPosition

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Function of:

Description:

This function takes a screen position and returns a list of all the visible GuiObject|GuiObjects that are occupying that screen position.

The main use case is to get GUI objects under the player’s mouse or touch inputs to do things like allow selection or highlighting. These effects can already be achieved using GuiObject/MouseEnter and GuiObject/MouseLeave but this requires the developer to track these events for their UI objects all the time even if they only need this functionality in specific circumstances.

Since the child classes of BasePlayerGui inherit this function, it can be fired by class objects such as the PlayerGui and StarterGui folders.

Parameters

Name	Type	Default	Description
Name x	Type int	Default	Summary The x position on the screen relative to the top left corner after the `GuiService/GetGuiInset\|GuiInset` is applied
Name y	Type int	Default	Summary The y position on the screen relative to the top left corner after the `GuiService/GetGuiInset\|GuiInset` is applied

Returns

Return Type	Summary
Return Type Objects	Summary A table of the visible `GuiObject`s that occupy the given screen space

Code Samples

Selecting GUIs at a Position

All GUIs returned by GetGuiObjectsAtPosition() at ‘cloned’ by the highlighAsFrame() local function which creates a Frame GUI positioned on top of the specified GUI that is semi-transparent and the same GuiObject/AbsoluteSize and GuiObject/AbsolutePosition.

These highlights are added to the HighlightsContainer ScreenGui in the Highlight folder of the player’s PlayerGui folder. Both are created by the code sample. All highlight GUIs are Instance/Remove|Removed when every time highlightGui() executes.

Note that HighlightContainer’s ScreenGui/DisplayOrder is 99999, a large number, so that it is unlikely any other GUI will render on top of the higlight GUIs.

			
			
				Selecting GUIs at a Position

			
			
			
				Expected Output
			
			
				Expand
				
			
		

			
			local UserInputService = game:GetService("UserInputService")

 -- Get the LocalPlayer’s PlayerGui folder
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local PlayerGui = player:WaitForChild("PlayerGui")

 -- Create a Folder and ScreenGui to contain the highlight Frames
local Highlights = Instance.new("Folder")
Highlights.Name = "Highlights"
Highlights.Parent = PlayerGui
local HighlightsContainer = Instance.new("ScreenGui")
HighlightsContainer.Name = "Container"
HighlightsContainer.Parent = Highlights
HighlightsContainer.DisplayOrder = 99999

  -- Deletes all GUIs in HighlightsContainer
local function deleteHighlights()
	local highlights = HighlightsContainer:GetChildren()

-	for _, highlight in pairs(highlights) do	
+	for _, highlight in ipairs(highlights) do
-		highlight:Remove()
+		highlight:Destroy()
	end
end

 -- Creates a semi-transparent yellow Frame on top of the gui with the same AbsoluteSize and AbsolutePosition
local function highlightAsFrame(gui)
	local highlight = Instance.new("Frame")
	highlight.Name = "Highlight"
	highlight.Parent = HighlightsContainer
	highlight.Size = UDim2.new(0, gui.AbsoluteSize.X, 0, gui.AbsoluteSize.Y)
	highlight.Position = UDim2.new(0, gui.AbsolutePosition.X, 0, gui.AbsolutePosition.Y)
	highlight.BackgroundColor3 = Color3.new(255/255, 255/255, 10/255) -- Yellow
	highlight.BackgroundTransparency = 0.75
	highlight.BorderSizePixel = 0
	highlight.LayoutOrder = gui.LayoutOrder -1
end

 -- Use GetGuiObjectsAtPosition to get and highlight all GuiObjects at the input’s position
local function highlightGui(input, gameProcessed)
	local pos = input.Position
	local guisAtPosition = PlayerGui:GetGuiObjectsAtPosition(pos.X, pos.Y)
	
	deleteHighlights()
	
-	for _, gui in pairs(guisAtPosition) do
+	for _, gui in ipairs(guisAtPosition) do
-		if gui:IsA("GuiButton") then
+		if gui:IsA("GuiObject") then
			local highlight = gui:Clone()
			highlightAsFrame(gui)
		end
	end
end

 -- Fire highlightGui on InputBegan if input is of type MouseButton1 of Touch
local function InputBegan(input, gameProcessed)
	local inputType = input.UserInputType
	local touch = Enum.UserInputType.Touch
	local mouse1 = Enum.UserInputType.MouseButton1
	if inputType == touch or inputType == mouse1 then
		highlightGui(input, gameProcessed)
	end
end

UserInputService.InputBegan:Connect(InputBegan)
		

			
		

			
				
				Copy Code
			
			
				Light Theme
				
					
					
				
			
		