> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infilsense.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration & Persistence

> Understand JSON storage for tabs, keybinds, startup flags, selection values, grid settings, and sliders.

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](https://docs.infilsense.com/features/theming.md) for the full theme API.

## File location

The path is derived from `SaveFolder` and `SaveId`:

| Configuration | File |
| :- | :- |
| `SaveFolder = ""`, `SaveId = "config"` | `config.json` |
| `SaveFolder = "MyConfigs"`, `SaveId = "default"` | `MyConfigs/default.json` |

```lua theme={null}
local app = Library.new({
	Name = "Persistent Demo",
	SaveFolder = "MyConfigs",
	SaveId = "player_settings",
})
```

The file extension is always `.json`.

> [!WARNING]
>
> 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:

```lua theme={null}
{
	Startup = {},
	Keybinds = {},
	Settings = {
		GridSnap = true,
		GridSize = 15,
	},
	TabPositions = {},
	TabStates = {},
	MenuToggle = "RightShift",
	QuickCommandsToggle = "F2",
}
```

## Tab positions and state

Dragging a tab saves its position in `TabPositions`. Collapsing or expanding a tab saves its minimized state in `TabStates`.

```text theme={null}
TabPositions["Main"] = {
	X = { 0, 15 },
	Y = { 0, 80 },
}

TabStates["Main"] = true
```

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:

```text theme={null}
Keybinds["noclip"] = "F6"
```

The built-in `Settings` tab stores the two global shortcuts separately:

```text theme={null}
MenuToggle = "RightShift"
QuickCommandsToggle = "F2"
```

### Rebinding component controls

Enable binding on a component:

```lua theme={null}
local button = tab:AddButton({
	Info = { Title = "Noclip" },
	InternalInfo = {
		Toggle = true,
		UniqueCommandId = "noclip",
		Bindable = true,
	},
	Callback = function(enabled)
		print(enabled)
	end,
})
```

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:

```text theme={null}
Startup["noclip"] = true
```

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`:

```lua theme={null}
tab:AddSlider({
	Info = { Title = "Field of View" },
	InternalInfo = { UniqueCommandId = "camera_fov" },
	Min = 70,
	Max = 120,
	Default = 90,
	Save = true,
})
```

The value is stored as:

```text theme={null}
Settings["camera_fov"] = 95
```

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:

```lua theme={null}
local features = tab:AddSelection({
	Info = { Title = "Features" },
	MultiSelect = true,
	DefaultValue = { "ESP" },
	Save = true,
	InternalInfo = {
		UniqueCommandId = "features",
		StartupAvailable = true,
	},
	Callback = function(values)
		print(table.concat(values, ", "))
	end,
})

features:AddOption({ Info = { Title = "ESP" }, Value = "ESP" })
features:AddOption({ Info = { Title = "Tracers" }, Value = "Tracers" })
```

The resulting configuration can contain:

```text theme={null}
Startup["features"] = true
Settings["features"] = { "ESP", "Tracers" }
```

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:

```text theme={null}
Settings.GridSnap = true
Settings.GridSize = 15
```

The settings UI limits `GridSize` to **5–30** pixels in **5-pixel** increments.

## Resetting layout

The built-in **Reset Tab Positions** action clears:

```text theme={null}
TabPositions = {}
TabStates = {}
```

It then moves current tabs back to their initial vertical stack order.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.