Skip to main content

AtomicButton

UI

The foundational model for all UI button components in the game. On top of the AtomicPane base, it adds interaction states such as hover, press, selected, and enabled. It also provides events for these interactions. Anything can be a button with this class, it will automatically create a TextButton if one does not already exist (must be named "Sensor" and a direct child of the Gui instance).

Inherits from AtomicPane

A VS Code snippet for creating AtomicButtons quickly is included with the Git repository.

NOTE

The source GUI objects should be located in ReplicatedStorage.GuiTemplates, or Assets.GuiTemplates if using an Enclave package. They can be of any GuiObject type.

Basic usage

local AtomicButton = shared("AtomicButton") ---@module AtomicButton

local ExampleButton = setmetatable({}, AtomicButton)
ExampleButton.__index = ExampleButton
ExampleButton.ClassName = "ExampleButton"

function ExampleButton:_draw()
	local alpha = self._springs.Alpha.Position

	self.Gui.Visible = alpha < 0.999
end

function ExampleButton.new(parent: Instance)
	local self = setmetatable(AtomicButton.new("ExampleButtonTemplate", {}), ExampleButton)

	self:SetVisible(false, true)

	self.Gui.Parent = parent

	return self
end

return ExampleButton

Properties​

Activated​

</>
AtomicButton.Activated: RBXScriptSignal<boolean>

Fires when the button is activated or deactivated.

Hovered​

</>
AtomicButton.Hovered: RBXScriptSignal<boolean>

Fires when the button is hovered or unhovered.

Enabled​

</>
AtomicButton.Enabled: RBXScriptSignal<boolean>

Fires when the button is enabled or disabled.

Pressed​

</>
AtomicButton.Pressed: RBXScriptSignal<boolean>

Fires when the button is pressed or unpressed.

Selected​

</>
AtomicButton.Selected: RBXScriptSignal<boolean>

Fires when the button is selected or unselected.

Functions​

new​

Constructor
</>
AtomicButton.new(
template: string | Instance,--

The name of a GuiObject in ReplicatedStorage.GuiTemplates or an existing instance to use as the button's Gui.

instanceKeys: table--

A mapping of instance names to keys for quick access

) → ()

Creates a new AtomicButton based on the template key or existing frame. Instances are mapped based on a simple descendants search, so unique names are required for consistency.

Activate​

</>
AtomicButton:Activate() → ()

Manually activates the button without requiring the user to click it.

SetPressed​

</>
AtomicButton:SetPressed(
pressed: boolean--

The new pressed state

) → ()

Manually sets the pressed state of the button without requiring the user to click it.

SetHovered​

</>
AtomicButton:SetHovered(hovered: boolean) → ()

Sets the hovered state of the button

SetSelected​

</>
AtomicButton:SetSelected(selected: boolean) → ()

Sets the selected state of the button

SetEnabled​

</>
AtomicButton:SetEnabled(enabled: boolean) → ()

Sets the enabled state of the button

IsEnabled​

</>
AtomicButton:IsEnabled() → boolean--

Whether the button is enabled

IsHovered​

</>
AtomicButton:IsHovered() → boolean--

Whether the button is hovered

IsPressed​

</>
AtomicButton:IsPressed() → boolean--

Whether the button is pressed

IsSelected​

</>
AtomicButton:IsSelected() → boolean--

Whether the button is selected

Show raw api
{
    "functions": [
        {
            "name": "_addSensor",
            "desc": "Adds a sensor to the button or connects to the existing sensor",
            "params": [],
            "returns": [],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 129,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "Activate",
            "desc": "Manually activates the button without requiring the user to click it.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 162,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "SetPressed",
            "desc": "Manually sets the pressed state of the button without requiring the user to\nclick it.",
            "params": [
                {
                    "name": "pressed",
                    "desc": "The new pressed state",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 173,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "SetHovered",
            "desc": "Sets the hovered state of the button",
            "params": [
                {
                    "name": "hovered",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 191,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "SetSelected",
            "desc": "Sets the selected state of the button",
            "params": [
                {
                    "name": "selected",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 213,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "SetEnabled",
            "desc": "Sets the enabled state of the button",
            "params": [
                {
                    "name": "enabled",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 231,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "IsEnabled",
            "desc": "",
            "params": [],
            "returns": [
                {
                    "desc": "Whether the button is enabled",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 248,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "IsHovered",
            "desc": "",
            "params": [],
            "returns": [
                {
                    "desc": "Whether the button is hovered",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 255,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "IsPressed",
            "desc": "",
            "params": [],
            "returns": [
                {
                    "desc": "Whether the button is pressed",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 262,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "IsSelected",
            "desc": "",
            "params": [],
            "returns": [
                {
                    "desc": "Whether the button is selected",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 269,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "new",
            "desc": "Creates a new AtomicButton based on the template key or existing frame.\nInstances are mapped based on a simple descendants search, so unique names\nare required for consistency.",
            "params": [
                {
                    "name": "template",
                    "desc": "The name of a GuiObject in ReplicatedStorage.GuiTemplates or an existing instance to use as the button's Gui.",
                    "lua_type": "string | Instance"
                },
                {
                    "name": "instanceKeys",
                    "desc": "A mapping of instance names to keys for quick access",
                    "lua_type": "table"
                }
            ],
            "returns": [],
            "function_type": "static",
            "tags": [
                "Constructor"
            ],
            "source": {
                "line": 282,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Activated",
            "desc": "Fires when the button is activated or deactivated.",
            "lua_type": "RBXScriptSignal<boolean>",
            "source": {
                "line": 287,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "Hovered",
            "desc": "Fires when the button is hovered or unhovered.",
            "lua_type": "RBXScriptSignal<boolean>",
            "source": {
                "line": 292,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "Enabled",
            "desc": "Fires when the button is enabled or disabled.",
            "lua_type": "RBXScriptSignal<boolean>",
            "source": {
                "line": 297,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "Pressed",
            "desc": "Fires when the button is pressed or unpressed.",
            "lua_type": "RBXScriptSignal<boolean>",
            "source": {
                "line": 302,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "Selected",
            "desc": "Fires when the button is selected or unselected.",
            "lua_type": "RBXScriptSignal<boolean>",
            "source": {
                "line": 307,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        },
        {
            "name": "_springs",
            "desc": "A table of all of the pane's springs. Includes the Alpha, Hovered, Pressed,\nSelected and Enabled springs by default.",
            "lua_type": "{[string]: Spring}",
            "private": true,
            "source": {
                "line": 314,
                "path": "src/client/core/lib/UI/AtomicButton.luau"
            }
        }
    ],
    "types": [],
    "name": "AtomicButton",
    "desc": "The foundational model for all UI button components in the game. On top of\nthe AtomicPane base, it adds interaction states such as hover, press,\nselected, and enabled. It also provides events for these interactions.\nAnything can be a button with this class, it will automatically create a\nTextButton if one does not already exist (must be named \"Sensor\" and a\ndirect child of the Gui instance).\n\n**Inherits from AtomicPane**\n\nA VS Code snippet for creating AtomicButtons quickly is included with the\nGit repository.\n\n:::note\nThe source GUI objects should be located in\n`ReplicatedStorage.GuiTemplates`, or `Assets.GuiTemplates` if using an\nEnclave package. They can be of any GuiObject type.\n:::\n\n### Basic usage\n```lua\nlocal AtomicButton = shared(\"AtomicButton\") ---@module AtomicButton\n\nlocal ExampleButton = setmetatable({}, AtomicButton)\nExampleButton.__index = ExampleButton\nExampleButton.ClassName = \"ExampleButton\"\n\nfunction ExampleButton:_draw()\n\tlocal alpha = self._springs.Alpha.Position\n\n\tself.Gui.Visible = alpha < 0.999\nend\n\nfunction ExampleButton.new(parent: Instance)\n\tlocal self = setmetatable(AtomicButton.new(\"ExampleButtonTemplate\", {}), ExampleButton)\n\n\tself:SetVisible(false, true)\n\n\tself.Gui.Parent = parent\n\n\treturn self\nend\n\nreturn ExampleButton\n```",
    "tags": [
        "UI"
    ],
    "source": {
        "line": 119,
        "path": "src/client/core/lib/UI/AtomicButton.luau"
    }
}