Skip to main content

FocusUI

This item only works when running on the client. Client

Dims the whole screen except one GuiObject, and optionally waits for it to be clicked.

This is the workhorse of most tutorials: show the player exactly one thing they can press, and move on when they press it. 

Step.new(2, {
	FocusUI.to(shopButton, { Advance = true }),
})

The dim panels live in a CanvasGroup, which is what keeps the four of them from stacking their alpha and drawing a seam along the edge of the hole.

Functions​

to​

constructor
</>
FocusUI.to(
target: GuiObject,--

What stays lit

options: FocusUIOptions?--

Padding and click behaviour

) → Action

Types

​

interface FocusUIOptions {
Padding: Vector2?--

Extra room around the target, in pixels

Clicked: ((context: ActionContext) → ())?--

Runs when the target is clicked

Advance: boolean?--

Move to the next step on click

}

Highlights a GuiObject.

Just showing something

With no options it dims and waits. Some other action in the step has to end it.

FocusUI.to(inventoryPanel, { Padding = Vector2.new(12, 12) })

Advancing on click

FocusUI.to(shopButton, { Advance = true })

Deciding for yourself

Clicked receives the ActionContext, so the step can end on a condition:

FocusUI.to(buyButton, {
	Clicked = function(context)
		if playerHasEnoughCoins() then
			context:Advance()
		end
	end,
})

How the click is detected

Three fallbacks, in order: the target itself if it is a GuiButton, otherwise the first descendant button, otherwise raw InputBegan on the frame. That last one is what makes this work on plain Frame targets, and it covers mouse and touch.

Show raw api
{
    "functions": [
        {
            "name": "to",
            "desc": "Highlights a GuiObject.\n\n### Just showing something\n\nWith no options it dims and waits. Some other action in the step has to end it.\n\n```lua\nFocusUI.to(inventoryPanel, { Padding = Vector2.new(12, 12) })\n```\n\n### Advancing on click\n\n```lua\nFocusUI.to(shopButton, { Advance = true })\n```\n\n### Deciding for yourself\n\n`Clicked` receives the [ActionContext], so the step can end on a condition:\n\n```lua\nFocusUI.to(buyButton, {\n\tClicked = function(context)\n\t\tif playerHasEnoughCoins() then\n\t\t\tcontext:Advance()\n\t\tend\n\tend,\n})\n```\n\n### How the click is detected\n\nThree fallbacks, in order: the target itself if it is a `GuiButton`, otherwise the first\ndescendant button, otherwise raw `InputBegan` on the frame. That last one is what makes this\nwork on plain `Frame` targets, and it covers mouse and touch.",
            "params": [
                {
                    "name": "target",
                    "desc": "What stays lit",
                    "lua_type": "GuiObject"
                },
                {
                    "name": "options",
                    "desc": "Padding and click behaviour",
                    "lua_type": "FocusUIOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Action"
                }
            ],
            "function_type": "static",
            "tags": [
                "constructor"
            ],
            "source": {
                "line": 115,
                "path": "src/Actions/FocusUI.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "FocusUIOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Padding",
                    "lua_type": "Vector2?",
                    "desc": "Extra room around the target, in pixels"
                },
                {
                    "name": "Clicked",
                    "lua_type": "((context: ActionContext) -> ())?",
                    "desc": "Runs when the target is clicked"
                },
                {
                    "name": "Advance",
                    "lua_type": "boolean?",
                    "desc": "Move to the next step on click"
                }
            ],
            "source": {
                "line": 33,
                "path": "src/Actions/FocusUI.luau"
            }
        }
    ],
    "name": "FocusUI",
    "desc": "Dims the whole screen except one GuiObject, and optionally waits for it to be clicked.\n\nThis is the workhorse of most tutorials: show the player exactly one thing they can press, and\nmove on when they press it.\n\n```lua\nStep.new(2, {\n\tFocusUI.to(shopButton, { Advance = true }),\n})\n```\n\nThe dim panels live in a `CanvasGroup`, which is what keeps the four of them from stacking their\nalpha and drawing a seam along the edge of the hole.",
    "realm": [
        "Client"
    ],
    "source": {
        "line": 20,
        "path": "src/Actions/FocusUI.luau"
    }
}