Skip to main content
Configuration is loaded automatically by Library.new() and saved as controls change. Theme colors are configured through Library.new({ Theme = ... }) or the runtime theme methods, but theme colors are not stored in the JSON configuration file. See Theming for the full theme API.

File location

The path is derived from SaveFolder and SaveId:
The file extension is always .json.
Persistence depends on executor/environment file APIs. If the environment does not provide them, runtime UI behavior still works but saved state cannot be written to disk.

Default structure

A fresh configuration starts with this shape:

Tab positions and state

Dragging a tab saves its position in TabPositions. Collapsing or expanding a tab saves its minimized state in TabStates.
When the same SaveFolder and SaveId are used on the next initialization, those values restore the tab.

Keybinds

Bindable components store their assigned keyboard key by command ID:
The built-in Settings tab stores the two global shortcuts separately:

Rebinding component controls

Enable binding on a component:
Then right-click the component and choose Assign a New Keybind. The selected key is written under Keybinds["noclip"].

Startup flags

Controls with StartupAvailable = true expose a Toggle Startup action in their right-click menu:
The library consumes that startup flag automatically for supported components:
  • Buttons execute their callback with true.
  • Single-select selections execute their main callback with the restored value.
  • Multi-select selections execute their main callback with the restored array of values.
For selections, opt into value persistence with Save = true (or InternalInfo.Save = true). Single-select values are stored under Settings[commandId] as one value; multi-select values are stored as an array. The startup preference remains under Startup[commandId]. If no saved value exists, DefaultValue is used. Picker selections should provide a stable InternalInfo.UniqueCommandId for persistence to work across runs. SingleSelect and MultiSelect cannot both be enabled. A selection defaults to single-select when MultiSelect is not enabled. Inputs and sliders currently expose the startup menu flag without automatically executing their callback from it during initialization.

Saved sliders

A slider opts into persistence with Save = true:
The value is stored as:
The implementation also accepts InternalInfo.Save = true and Settings = { save = true } on the component config.

Saved selection values

Selections persist their current picker value independently of the startup preference. Single-select stores one value, while multi-select stores an array:
The resulting configuration can contain:
With startup enabled, the callback receives a copy of the restored array during initialization. When the user changes the selection, the new value replaces the saved value.

Grid settings

The built-in settings tab stores:
The settings UI limits GridSize to 5–30 pixels in 5-pixel increments.

Resetting layout

The built-in Reset Tab Positions action clears:
It then moves current tabs back to their initial vertical stack order.