> For the complete documentation index, see [llms.txt](https://dirkscripts.gitbook.io/dirkscripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dirkscripts.gitbook.io/dirkscripts-documentation/resources/dirk-multichar/configuration.md).

# Live Script Configurator

Every basic setting, backstory, spawn location, lifestyle, character state and VIP role in `dirk_multichar` is editable from the in-game **Live Script Configurator**. Changes save to the `dirk_scriptConfig` database table and apply **live** — no SQL imports, no Lua edits, no resource restart.

{% hint style="success" %}
**Opening the configurator**

You have two options, both registered by `dirk_lib`:

* **`/dirk_multichar`** — opens the configurator straight to the multichar config.
* **`/dirk_config`** — opens the chooser listing every dirk script on the server and lets you pick which one to configure.

The cog icon on the character-list title bar inside the multichar UI also opens the configurator (gated by `dirk_lib`'s scriptConfig edit permission). Back / Esc / close drop you straight back into the character list — no bouncing through the chooser.

Only players with the configured admin permission (set up via `dirk_lib`) can access either command.
{% endhint %}

***

## Sidebar Controls

* **Undo / Redo** — full edit history.
* **Save** — persist pending changes (a badge shows the number of unsaved edits).
* **History** — timestamped audit log of every change, who made it, and the old vs new values.
* **Discard** — drop unsaved edits.
* **Manual Edit (JSON)** — open a raw JSON editor for the entire config.
* **Reset Defaults** — wipe everything and reload shipped defaults (with confirmation).

***

## Sections

The configurator has six top-level sections, listed in the sidebar:

**Basic** · **Scene** · **Backstories** · **Spawn Locations** · **States** · **VIP Roles**

***

### Basic

General script settings: logout flow, debug toggles, UI tweaks. Anything that doesn't belong inside a more specific tab lives here.

***

### Scene

Controls the character-selection scene itself:

* **Drag-reorder** character display positions (where each slot stands during selection).
* **Scenario / Dict / Anim / Flag** rows per position to drive what each character is doing on screen.
* **Walk-and-set position picker** — E to confirm, ⌫ to cancel. Places positions in-world while you're standing where you want them.
* **Customisation position** — where the player stands during clothing handoff.
* **Atmosphere** — weather + time for the selection scene. Applies during selection, restores cleanly on hand-off to the spawn selector / first spawn.

***

### Backstories

Modal editor per backstory with four tabs:

| Tab         | What lives here                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| **General** | Name, label, description.                                                                                  |
| **Access**  | Locked toggle + Discord role gating (only when Locked is on).                                              |
| **Items**   | Compact `SelectItem` list with inline expand — pick items + quantity to grant on spawn.                    |
| **Scenes**  | The scripted intro sequences. Each scene has its own walk-set position, scenario/anim row, and atmosphere. |

Modal height is fixed so switching tabs doesn't reshape the panel.

***

### Spawn Locations

Modal editor with:

* Name + label
* **FontAwesome icon picker** for the map / list display
* In-game group / rank picker backed by `lib.framework` — gate spawns by job, gang or any framework grouping
* Randomised internal IDs (no more hand-typed `spawn_1` slugs)
* **Use Spawn Selector** toggle (was previously elsewhere — moved here to keep all spawn-related settings together)

***

### States

Two parts:

* **Edit visual states** — icon + colour + message + Disabled toggle per state. Disabled states block character usage entirely (good for "Coma", "In Hospital"-style flags).
* **Online Players panel** — search any online character and apply a state to them from the same tab.

***

### VIP Roles

* Add roles via Discord role ID — extra character slots are granted automatically when the player has any of these roles.
* **Use ESX Character Slots Table** toggle — when on, slot counts come from ESX's native `users.character_slots` column instead of the role-based mapping. ESX-only servers use this for parity with the rest of their slot tracking.

***

## scriptConfig + Lua API

dirk\_multichar v1.5 reads everything from `dirk_lib`'s scriptConfig at runtime. Lua-side consumers can subscribe to live changes:

```lua
lib.scriptConfig.on('backstories', function()
  -- runs every time an admin saves the Backstories tab
end)
```

Each section (`basic`, `lifestyles`, `spawnLocations`, `vipRoles`, `characterPositions`, `cameraViews`, `defaultItems`, `characterStates`) has its own watcher. Edits in the configurator apply live, no resource restart required.

The only Lua-side holdout is `characterMetadata` — its entries carry `get(charId)` callback functions that query the database, which can't be JSON-serialised. That lives in `extras/characterMetadata.lua` and remains a regular Lua file.

External resources can still register lifestyles at runtime via:

```lua
exports.dirk_multichar:registerLifestyle('mylifestyle', {
  label = 'My Lifestyle',
  description = '...',
  items = { ... },
})
```