Skip to main content

UIStateManager

This item only works when running on the client. Client

Handles UI state management for AtomicPanes. Designed as a standalone state manager that controls which UI components are visible based on named states.

Functions​

SetState​

</>
UIStateManager:SetState(
state: string,--

The name of the state to transition to

forceState: boolean?,--

If true, bypasses any block rules on the current state

targetGuiObject: Instance?--

The GuiObject to target for gamepad cursor focus

) → (
boolean,--

Whether the state was successfully set

string?--

The reason the state was blocked, if applicable

)

Sets the current UI state. Hides and shows registered components according to the state's StateProperties. Returns false and a reason string if the transition is blocked by the current state.

RegisterState​

</>
UIStateManager:RegisterState(
name: string,--

The name to register the state under

properties: StateProperties--

The configuration for the state

) → ()

Types

​

interface StateProperties {
Hides: {string}?--

Component names to hide when this state is active. Use "*" to hide all.

Shows: {string}?--

Component names to show when this state is active. Use "*" to show all.

CoreGui: {
Shows: {string}?,
Hides: {string}?
}?--

CoreGui elements to show or hide

Blocks: {string}?--

State names that cannot be transitioned to from this state. Use "*" to block all.

GamepadCursorEnabled: boolean?--

Whether the gamepad cursor should be enabled in this state

}

Registers a new UI state with the given name and properties. If a state with the same name already exists, registration is skipped with a warning.

RegisterComponent​

</>
UIStateManager:RegisterComponent(
name: string,--

The name to register the component under

class: {}--

The component object, must have :Show() and :Hide() methods

) → ()

Registers a UI component under the given name so it can be referenced in state configurations. The component must implement :Show() and :Hide() methods. If a component with the same name is already registered, the registration is skipped with a warning.

UnregisterComponent​

</>
UIStateManager:UnregisterComponent(
name: string,--

The name the component was registered under

class: {}--

The original class reference used during registration

) → ()

Unregisters a previously registered UI component by name. Does nothing if the component is not registered or was registered under a different class reference.

GetState​

</>
UIStateManager:GetState() → string

Returns the name of the current UI state.

IsComponentShowing​

</>
UIStateManager:IsComponentShowing(
name: string--

The name of the registered component to check

) → boolean

Returns whether the named component is currently visible.

PreviousState​

</>
UIStateManager:PreviousState() → ()

Reverts to the previous UI state, if one exists.

SetDefault​

</>
UIStateManager:SetDefault() → (
boolean?,--

true on success, nil if no default is registered

string?--

The reason for failure, if applicable

)

Sets the current state to the registered default state. Returns nil and a reason string if no default state has been registered.

RegisterDefaultState​

</>
UIStateManager:RegisterDefaultState(
name: string--

The name of the state to use as the default

) → (
boolean?,--

true on success, nil if the state does not exist

string?--

The reason for failure, if applicable

)

Registers the named state as the default state for :SetDefault(). Returns nil and a reason string if the state has not been registered.

RegisterEventHook​

</>
UIStateManager:RegisterEventHook(
eventName: string,--

The name of the event to hook into

callback: function--

Called with (newState, oldState) when the event fires

) → ()

Registers a callback to be invoked when the specified event occurs.

Valid event names and their callback argument order:

  • StateChange(newState, oldState)
  • BeforeStateChange(oldState, newState)
  • AfterStateChange(newState, oldState)
  • CoreGuiChange(newState, oldState)
UIStateManager:RegisterEventHook("StateChange", function(newState, oldState)
	print("UI State changed to:", newState)
end)
Show raw api
{
    "functions": [
        {
            "name": "SetState",
            "desc": "Sets the current UI state. Hides and shows registered components according\nto the state's `StateProperties`. Returns `false` and a reason string if\nthe transition is blocked by the current state.",
            "params": [
                {
                    "name": "state",
                    "desc": "The name of the state to transition to",
                    "lua_type": "string"
                },
                {
                    "name": "forceState",
                    "desc": "If true, bypasses any block rules on the current state",
                    "lua_type": "boolean?"
                },
                {
                    "name": "targetGuiObject",
                    "desc": "The GuiObject to target for gamepad cursor focus",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "Whether the state was successfully set",
                    "lua_type": "boolean"
                },
                {
                    "desc": "The reason the state was blocked, if applicable",
                    "lua_type": "string?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 217,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "RegisterState",
            "desc": "Registers a new UI state with the given name and properties. If a state\nwith the same name already exists, registration is skipped with a warning.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name to register the state under",
                    "lua_type": "string"
                },
                {
                    "name": "properties",
                    "desc": "The configuration for the state",
                    "lua_type": "StateProperties"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 271,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "RegisterComponent",
            "desc": "Registers a UI component under the given name so it can be referenced in\nstate configurations. The component must implement `:Show()` and `:Hide()`\nmethods. If a component with the same name is already registered, the\nregistration is skipped with a warning.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name to register the component under",
                    "lua_type": "string"
                },
                {
                    "name": "class",
                    "desc": "The component object, must have `:Show()` and `:Hide()` methods",
                    "lua_type": "{}"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 289,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "UnregisterComponent",
            "desc": "Unregisters a previously registered UI component by name. Does nothing if\nthe component is not registered or was registered under a different class\nreference.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name the component was registered under",
                    "lua_type": "string"
                },
                {
                    "name": "class",
                    "desc": "The original class reference used during registration",
                    "lua_type": "{}"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 314,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "GetState",
            "desc": "Returns the name of the current UI state.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 331,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "IsComponentShowing",
            "desc": "Returns whether the named component is currently visible.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name of the registered component to check",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 341,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "PreviousState",
            "desc": "Reverts to the previous UI state, if one exists.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 354,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "SetDefault",
            "desc": "Sets the current state to the registered default state. Returns `nil` and\na reason string if no default state has been registered.",
            "params": [],
            "returns": [
                {
                    "desc": "`true` on success, `nil` if no default is registered",
                    "lua_type": "boolean?"
                },
                {
                    "desc": "The reason for failure, if applicable",
                    "lua_type": "string?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 367,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "RegisterDefaultState",
            "desc": "Registers the named state as the default state for `:SetDefault()`. Returns\n`nil` and a reason string if the state has not been registered.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name of the state to use as the default",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "`true` on success, `nil` if the state does not exist",
                    "lua_type": "boolean?"
                },
                {
                    "desc": "The reason for failure, if applicable",
                    "lua_type": "string?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 384,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        },
        {
            "name": "RegisterEventHook",
            "desc": "Registers a callback to be invoked when the specified event occurs.\n\nValid event names and their callback argument order:\n- `StateChange(newState, oldState)`\n- `BeforeStateChange(oldState, newState)`\n- `AfterStateChange(newState, oldState)`\n- `CoreGuiChange(newState, oldState)`\n\n```lua\nUIStateManager:RegisterEventHook(\"StateChange\", function(newState, oldState)\n\tprint(\"UI State changed to:\", newState)\nend)\n```",
            "params": [
                {
                    "name": "eventName",
                    "desc": "The name of the event to hook into",
                    "lua_type": "string"
                },
                {
                    "name": "callback",
                    "desc": "Called with (newState, oldState) when the event fires",
                    "lua_type": "function"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 411,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "StateProperties",
            "desc": "",
            "fields": [
                {
                    "name": "Hides",
                    "lua_type": "{string}?",
                    "desc": "Component names to hide when this state is active. Use `\"*\"` to hide all."
                },
                {
                    "name": "Shows",
                    "lua_type": "{string}?",
                    "desc": "Component names to show when this state is active. Use `\"*\"` to show all."
                },
                {
                    "name": "CoreGui",
                    "lua_type": "{Shows: {string}?, Hides: {string}?}?",
                    "desc": "CoreGui elements to show or hide"
                },
                {
                    "name": "Blocks",
                    "lua_type": "{string}?",
                    "desc": "State names that cannot be transitioned to from this state. Use `\"*\"` to block all."
                },
                {
                    "name": "GamepadCursorEnabled",
                    "lua_type": "boolean?",
                    "desc": "Whether the gamepad cursor should be enabled in this state"
                }
            ],
            "source": {
                "line": 42,
                "path": "src/client/core/tasks/UI/UIStateManager.luau"
            }
        }
    ],
    "name": "UIStateManager",
    "desc": "Handles UI state management for [AtomicPanes](/api/AtomicPane). Designed as\na standalone state manager that controls which UI components are visible\nbased on named states.",
    "realm": [
        "Client"
    ],
    "source": {
        "line": 19,
        "path": "src/client/core/tasks/UI/UIStateManager.luau"
    }
}