Toggle · Ember · rbx.lol

The smallest toggle#

Luau

main:Toggle({
    Text = "God mode",
    Callback = function(on)
        godmode = on
    end,
})

on is true or false.

Preview

My Script

v1.0

Search…

Ember v1

Enabled

FireOnStart runs the callback once at build time.

Building it up#

Start it on:

Luau

main:Toggle({
    Text = "God mode",
    Default = true,
    Callback = function(on) godmode = on end,
})

Explain what it does:

Luau

main:Toggle({
    Text = "God mode",
    Description = "Blocks all incoming damage.",
    Icon = "shield",
    Default = true,
    Callback = function(on) godmode = on end,
})

Remember it between sessions. Set Save = true and Ember writes it to disk, deriving the key from where the control sits:

Luau

main:Toggle({
    Text = "God mode",
    Save = true,
    Callback = function(on) godmode = on end,
})

A string key instead of true survives renaming the label — see saving settings.

Running something only when it turns off#

Most toggle callbacks open with if on then … else … end. OnEnabled and OnDisabled let you name the two halves instead:

Luau

main:Toggle({
    Text = "ESP",
    OnEnabled = function()
        espFolder = Instance.new("Folder", workspace)
        espConn = RunService.Heartbeat:Connect(drawBoxes)
    end,
    OnDisabled = function()
        if espFolder then espFolder:Destroy(); espFolder = nil end
        if espConn then espConn:Disconnect(); espConn = nil end
    end,
})

OnDisabled is also what runs on a restored off value, on a respawn re-apply, and on RevertOnClose. See Lifecycle.

Use them with Callback or instead of it. Callback runs first, then whichever half matches. If one handler raises, the others still run and the error is warned to the console.

Every option#

Option	Type	Default	What it does
`Text`req	`string`	`—`	The label.
`Callback`	`function(boolean)`	`—`	Called with the new state whenever it changes.
`OnEnabled`	`function`	`—`	Called when it turns on. Runs after Callback.
`OnDisabled`	`function`	`—`	Called when it turns off, including on revert and on a restored off value.
`Default`	`boolean`	`false`	The starting state.
`Description`	`string`	`—`	A quieter second line.
`Icon`	`string`	`—`	An icon shown before the label.
`FireOnStart`	`boolean`	`false`	Fire the callback once at creation even when nothing was saved.
`Save`	`string \| boolean`	`—`	Persist this toggle. true derives a key from the section and label.
`Reapply`	`boolean`	`—`	Re-fire the callback when the character is replaced.
`RevertOnClose`	`boolean`	`—`	Fire the callback with false when the window closes.
`Tooltip`	`string`	`—`	Shown while the pointer is over the control.
`Disabled`	`boolean`	`false`	Refuses input and dims the control.
`DisabledReason`	`string`	`—`	Shown as a tooltip while it is disabled.

Methods#

Method	Returns	What it does
`Get()`	`boolean`	The current state
`Set(value)`	`true`	Flips the switch and fires `Callback`

Luau

local godmode = main:Toggle({ Text = "God mode" })
 
godmode:Get()        --> false
godmode:Set(true)    -- animates the switch and fires the callback

Firing at startup#

A Saved toggle calls Callback once with the value it restored. See Saving settings.

FireOnStart covers the unsaved case: fire once at creation so a toggle that starts on applies itself.

Luau

main:Toggle({
    Text = "Fullbright",
    Default = true,
    FireOnStart = true,
    Callback = function(on) setFullbright(on) end,
})

Keep the startup callback cheap

Both of these run while the window is being built, so a slow callback delays the window appearing. If yours walks the whole workspace, wrap the body in task.spawn and let the window draw first.

A loop to avoid#

Set fires the callback, so calling it from inside that same toggle's callback loops forever:

Luau

-- Wrong: this recurses
local t
t = main:Toggle({
    Text = "Loop",
    Callback = function(on)
        t:Set(not on)   -- fires Callback again, which calls Set again…
    end,
})

To refuse a change, track the value yourself and call Set only when it differs.