Skip to main content

AtomicPane

UI

The foundational model for all UI components in the game. Provides visibility controls, spring management, automatic alpha mapping, and more.

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

NOTE

The source GUI objects should be located in ReplicatedStorage.GuiTemplates. They can be of any GuiObject type.

Basic usage

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

local ExamplePane = setmetatable({}, AtomicPane)
ExamplePane.__index = ExamplePane
ExamplePane.ClassName = "ExamplePane"

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

	self.Gui.Visible = alpha < 0.999
end

function ExamplePane.new(parent: Instance)
	local self = setmetatable(AtomicPane.new("ExamplePaneTemplate", {}), ExamplePane)

	self:SetVisible(false, true)

	self.Gui.Parent = parent

	return self
end

return ExamplePane

Properties​

Gui​

</>
AtomicPane.Gui: Frame

The root GuiObject of a constructed AtomicPane

Maid​

</>
AtomicPane.Maid: Maid

The AtomicPane's dedicated Maid, which cleans up when the pane is destroyed, or a linked (see AtomicPane:Link()) parent pane is destroyed.

VisibleChanged​

</>
AtomicPane.VisibleChanged: RBXScriptSignal<boolean>

Fired when the visibility of the pane changes. Provides the new visibility state and whether the change was animated or instant.

Destroying​

</>
AtomicPane.Destroying: RBXScriptSignal

Fired when the pane is being destroyed.

Functions​

Destroy​

</>
AtomicPane.Destroy(self: AtomicPane) → ()

Destroys the AtomicPane and cleans up all maid tasks.

new​

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

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

instanceKeys: table--

A mapping of instance names to keys for quick access

) → ()

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

_draw​

Override
</>
AtomicPane:_draw() → ()

An overridable function used to update the properties of various UI elements using values from the _springs table.

</>
AtomicPane:Link(
parentPane: AtomicPane,--

The AtomicPane to link to

linkVisibility: boolean?--

Whether to link the visibility of this pane to the parent pane

) → ()

Allows you to link this AtomicPane to another AtomicPane. This is useful to make sure that proper cleanup occurs when a parent pane is destroyed, for example.

MapAlpha​

</>
AtomicPane:MapAlpha(
element: Instance--

The top-level instance to map transparencies for

) → ()

Caches the current transparency values of the specified instance and all its descendants in an internal table for automatic interpolation based on the Alpha spring.

SetSpring​

</>
AtomicPane:SetSpring(
name: string,--

The name of the spring to modify

value: number,--

The target value to set the spring to

instant: boolean?--

Whether to instantly set the spring to the target value

) → ()

Sets the target value of a spring by name. Alpha is available by default. AtomicButtons add Hovered, Pressed, Selected, and Enabled springs.

AddSpring​

</>
AtomicPane:AddSpring(
name: string,--

The name of the spring to add

info: table--

The spring parameters to define the initial spring values, defaults to { s = 30, d = 1, i = 0 }

) → AnimNation.Spring

Adds a custom spring to the AtomicPane, which will automatically bind to the _draw function and be available in the _springs table.

AddSprings​

</>
AtomicPane:AddSprings(
springs: table,--

The list of spring names to add

info: table--

The spring parameters to define the initial spring values

) → ()

Adds multiple custom springs to the AtomicPane, which will automatically bind to the _draw function and be available in the _springs table.

SetVisible​

</>
AtomicPane:SetVisible(
isVisible: boolean,--

Whether to make it visible

doNotAnimate: boolean?--

Whether the transition is animated or instant

) → ()

Sets the visibility of the AtomicPane.

Show​

</>
AtomicPane:Show(
doNotAnimate: boolean?--

Whether the transition is animated or instant

) → ()

Sets the visibility of the AtomicPane to true.

Hide​

</>
AtomicPane:Hide(
doNotAnimate: boolean?--

Whether the transition is animated or instant

) → ()

Sets the visibility of the AtomicPane to false.

Toggle​

</>
AtomicPane:Toggle(
doNotAnimate: boolean?--

Whether the transition is animated or instant

) → ()

Toggles the visibility of the AtomicPane.

IsVisible​

</>
AtomicPane:IsVisible() → boolean--

Whether the AtomicPane is currently visible

SetAlphaAnimationEnabled​

</>
AtomicPane:SetAlphaAnimationEnabled(enabled: boolean) → ()

When enabled, forces a global override so that all Visible transitions are instant. It essentially makes doNotAnimate always true.

Show raw api
{
    "functions": [
        {
            "name": "_draw",
            "desc": "An overridable function used to update the properties of various UI elements\nusing values from the `_springs` table.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Override"
            ],
            "source": {
                "line": 136,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "_drawMappedAlphas",
            "desc": "An internal function used to automatically update the alpha values of mapped\nUI elements.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 143,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "_update",
            "desc": "Runs the specific ordering of draw functions for the AtomicPane.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 155,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "_useStoryControls",
            "desc": "Gives the AtomicPane some default controls for working with Hoarcekat or UI\nLabs",
            "params": [],
            "returns": [],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 169,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "Link",
            "desc": "Allows you to link this AtomicPane to another AtomicPane. This is useful to\nmake sure that proper cleanup occurs when a parent pane is destroyed, for\nexample.",
            "params": [
                {
                    "name": "parentPane",
                    "desc": "The AtomicPane to link to",
                    "lua_type": "AtomicPane"
                },
                {
                    "name": "linkVisibility",
                    "desc": "Whether to link the visibility of this pane to the parent pane",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 188,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "MapAlpha",
            "desc": "Caches the current transparency values of the specified instance and all its\ndescendants in an internal table for automatic interpolation based on the\n`Alpha` spring.",
            "params": [
                {
                    "name": "element",
                    "desc": "The top-level instance to map transparencies for",
                    "lua_type": "Instance"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 204,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "SetSpring",
            "desc": "Sets the target value of a spring by name. `Alpha` is available by default.\nAtomicButtons add `Hovered`, `Pressed`, `Selected`, and `Enabled` springs.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name of the spring to modify",
                    "lua_type": "string"
                },
                {
                    "name": "value",
                    "desc": "The target value to set the spring to",
                    "lua_type": "number"
                },
                {
                    "name": "instant",
                    "desc": "Whether to instantly set the spring to the target value",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 254,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "AddSpring",
            "desc": "Adds a custom spring to the AtomicPane, which will automatically bind to the\n`_draw` function and be available in the `_springs` table.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name of the spring to add",
                    "lua_type": "string"
                },
                {
                    "name": "info",
                    "desc": "The spring parameters to define the initial spring\tvalues, defaults to { s = 30, d = 1, i = 0 }",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AnimNation.Spring\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 273,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "AddSprings",
            "desc": "Adds multiple custom springs to the AtomicPane, which will automatically bind\nto the `_draw` function and be available in the `_springs` table.",
            "params": [
                {
                    "name": "springs",
                    "desc": "The list of spring names to add",
                    "lua_type": "table"
                },
                {
                    "name": "info",
                    "desc": "The spring parameters to define the initial spring values",
                    "lua_type": "table"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 304,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "SetVisible",
            "desc": "Sets the visibility of the AtomicPane.",
            "params": [
                {
                    "name": "isVisible",
                    "desc": "Whether to make it visible",
                    "lua_type": "boolean"
                },
                {
                    "name": "doNotAnimate",
                    "desc": "Whether the transition is animated or instant",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 316,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "Show",
            "desc": "Sets the visibility of the AtomicPane to true.",
            "params": [
                {
                    "name": "doNotAnimate",
                    "desc": "Whether the transition is animated or instant",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 339,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "Hide",
            "desc": "Sets the visibility of the AtomicPane to false.",
            "params": [
                {
                    "name": "doNotAnimate",
                    "desc": "Whether the transition is animated or instant",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 348,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "Toggle",
            "desc": "Toggles the visibility of the AtomicPane.",
            "params": [
                {
                    "name": "doNotAnimate",
                    "desc": "Whether the transition is animated or instant",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 362,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "IsVisible",
            "desc": "",
            "params": [],
            "returns": [
                {
                    "desc": "Whether the AtomicPane is currently visible",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 369,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "SetAlphaAnimationEnabled",
            "desc": "When enabled, forces a global override so that all Visible transitions are\ninstant. It essentially makes doNotAnimate always true.",
            "params": [
                {
                    "name": "enabled",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 379,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the AtomicPane and cleans up all maid tasks.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "AtomicPane"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 388,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "new",
            "desc": "Creates a new AtomicPane 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 pane'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": 419,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Gui",
            "desc": "The root GuiObject of a constructed AtomicPane",
            "lua_type": "Frame",
            "source": {
                "line": 424,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "Maid",
            "desc": "The AtomicPane's dedicated Maid, which cleans up when the pane is destroyed,\nor a linked (see AtomicPane:Link()) parent pane is destroyed.",
            "lua_type": "Maid",
            "source": {
                "line": 430,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "VisibleChanged",
            "desc": "Fired when the visibility of the pane changes. Provides the new visibility\nstate and whether the change was animated or instant.",
            "lua_type": "RBXScriptSignal<boolean>",
            "source": {
                "line": 436,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "Destroying",
            "desc": "Fired when the pane is being destroyed.",
            "lua_type": "RBXScriptSignal",
            "source": {
                "line": 441,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        },
        {
            "name": "_springs",
            "desc": "A table of all of the pane's springs. Includes the Alpha spring by default.",
            "lua_type": "{[string]: Spring}",
            "private": true,
            "source": {
                "line": 447,
                "path": "src/client/core/lib/UI/AtomicPane.luau"
            }
        }
    ],
    "types": [],
    "name": "AtomicPane",
    "desc": "The foundational model for all UI components in the game. Provides\nvisibility controls, spring management, automatic alpha mapping, and more.\n\nA VS Code snippet for creating AtomicPanes quickly is included with the Git\nrepository.\n\n:::note\nThe source GUI objects should be located in\n`ReplicatedStorage.GuiTemplates`. They can be of any GuiObject type.\n:::\n\n### Basic usage\n```lua\nlocal AtomicPane = shared(\"AtomicPane\") ---@module AtomicPane\n\nlocal ExamplePane = setmetatable({}, AtomicPane)\nExamplePane.__index = ExamplePane\nExamplePane.ClassName = \"ExamplePane\"\n\nfunction ExamplePane:_draw()\n\tlocal alpha = self._springs.Alpha.Position\n\n\tself.Gui.Visible = alpha < 0.999\nend\n\nfunction ExamplePane.new(parent: Instance)\n\tlocal self = setmetatable(AtomicPane.new(\"ExamplePaneTemplate\", {}), ExamplePane)\n\n\tself:SetVisible(false, true)\n\n\tself.Gui.Parent = parent\n\n\treturn self\nend\n\nreturn ExamplePane\n```",
    "tags": [
        "UI"
    ],
    "source": {
        "line": 125,
        "path": "src/client/core/lib/UI/AtomicPane.luau"
    }
}