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

# Configuration

Two plain-text files, editable by you (they are not escrowed): `config.lua` (replicated to clients, no secrets) and `config_server.lua` (server only, never sent to clients). Invalid values are reported by `gmc selftest`.

## config.lua

| Key                          | Default    | What it does                                                                                                                                                                                                             |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Config.Locale`              | `'it'`     | `'it'` or `'en'` (more files in `locales/` are picked up automatically).                                                                                                                                                 |
| `Config.Framework`           | `'auto'`   | `'auto'`, `'esx'`, `'qbcore'` or `'qbox'`.                                                                                                                                                                               |
| `Config.Debug`               | `false`    | Extra logging.                                                                                                                                                                                                           |
| `Config.Modules`             | all `true` | `select`, `identity`, `spawn`, `pause`: each can be turned off. With `select = false` players join with their last character. Invalid combinations (for example identity without select) are reported by `gmc selftest`. |
| `Config.Rpc.clientTimeoutMs` | `25000`    | Client-to-server call timeout. Must be at least `Config.ESX.joinTimeoutMs` + 5000 (checked by the selftest).                                                                                                             |

### Theme

```lua
Config.Theme = {
    accent = '#5AD1FF',   -- hex #RRGGBB
    radius = 'cut',       -- 'cut' | 'round' | 'square'
    scale = 1.0,          -- 0.85 - 1.25
    contrast = 'normal',  -- 'normal' | 'high'
    font = 'archivo',     -- 'archivo' | 'inter' | 'system'
    logo = '',            -- file in web/public
    serverName = 'Ghiaccio',
}
```

### Selection

```lua
Config.Select = {
    autoPlay = false,        -- true: skip the selection and play the last character (if playable)
    showDetails = true,
    skipIntro = false,
    alwaysAvailable = true,  -- selection stays reachable even with Modules.select = false (via /relog)
    command = 'personaggi',  -- command to return to the selection ('' = none); starts the relog
    bucketBase = 5000,       -- private routing bucket during selection/identity: bucketBase + server id
}
```

### Scenes

`Config.Scenes`:

| Key                             | Default    | What it does                                                                                                                                                                                  |
| ------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                       | `true`     | `false`: no scene, the player ped stays hidden and the UI sits over the world.                                                                                                                |
| `selectScene`                   | `'hangar'` | Selection scene (must have `ensemble`): every character together.                                                                                                                             |
| `studioScene`                   | `'studio'` | Identity photo set.                                                                                                                                                                           |
| `maxPeds`                       | `10`       | Characters in the scene together (1..10); beyond that they stay selectable from the keyboard.                                                                                                 |
| `quality`                       | `'high'`   | `'high'` (2 lights with shadow + placeholder light) or `'low'` (1 light, no shadows: weak PCs).                                                                                               |
| `debug`                         | `false`    | Prints to F8 the discarded spots, ped ground, camera and framing check (see `/gmc camdebug`).                                                                                                 |
| `streamTimeoutMs`               | `7000`     | Longest wait to load the scene area; beyond that a plain stage is used.                                                                                                                       |
| `groundTimeoutMs`               | `2500`     | Longest wait for the collision around the ped.                                                                                                                                                |
| `revealTimeoutMs`               | `15000`    | Watchdog: the player never stays on a black screen longer than this.                                                                                                                          |
| `introMs`                       | `1800`     | Entry dolly from the wide shot to the group shot.                                                                                                                                             |
| `reaction`                      | `true`     | The ped looks at the camera when selected.                                                                                                                                                    |
| `silenceWorld`                  | `true`     | Dampens the world audio during the selection.                                                                                                                                                 |
| `customPoses` / `disabledPoses` | `{}`       | Add your own poses (catalog in `shared/poses.lua`) or hide some.                                                                                                                              |
| `weatherPause`                  | 3 rows     | Weather sync scripts to pause while the scene controls time and weather (see [Integrations](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/integrations.md#weather-sync)). |

The scenes themselves (position, time, weather, lights, formation) live in `data/scenes.json` (format in `docs/SCENES_API.md`) and are reloaded with `/gmc reload`; `/gmc scene` lists them. There is one selection scene and one identity set.

### Identity

```lua
Config.Identity = {
    fields = { nationality = true, backstory = true, height = true },
    nameMin = 2, nameMax = 20,
    ageMin = 16, ageMax = 90,
    heightMin = 140, heightMax = 220,
    defaultHeight = 175,         -- saved height when the `height` field is off
    dateFormat = 'DD/MM/YYYY',   -- 'DD/MM/YYYY' | 'MM/DD/YYYY' | 'YYYY-MM-DD'
    nationalities = 'free',      -- 'free' or a list { 'Italian', 'American', ... }
    uniqueNames = true,          -- name + surname unique across all characters (checked by the server)
    blockedWords = {},
    backstoryMax = 500,
    fallbackNationality = 'N/D',
    photo = { enabled = true, transparent = true, timeoutMs = 4000 },
    autoCreate = { lastname = 'Cittadino', dobIso = '1995-01-01', sex = 'm', height = 175, nationality = 'N/D' },
}
```

`photo`: the ID card photo (pedheadshot). If it does not arrive within `timeoutMs` the card shows a silhouette. `autoCreate`: with `Modules.identity = false` and no character, one is created by itself with these data (name = the player's name).

### Appearance

```lua
Config.Appearance = {
    adapter = 'auto',        -- 'auto' | 'illenium' | 'fivem_appearance' | 'esx_skin' | 'qb_clothing' | 'rcore' | 'custom' | 'none'
    previewMode = 'auto',    -- 'auto' | 'ped' | 'player' | 'monogram'
    forceCreatorOnNew = true,
    defaultOutfits = { m = {}, f = {} },
}
```

`previewMode`: how appearance is shown during selection. If the script cannot dress a ped other than the player (esx\_skin), the resource uses the player itself, hidden in their private bucket. The creator runs in the player's **private routing bucket**; bucket 0 is restored only when the creator closes or on spawn. See [Integrations](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/integrations.md#appearance-adapters).

### Spawn

| Key                    | Default           | What it does                                                                                                                                                                                                                             |
| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`                 | `'ghiaccio'`      | `'ghiaccio'` (3D selector), `'framework'`, `'last'` or `'none'`. Module off, `'framework'`, `'none'` or no point = last position.                                                                                                        |
| `lastOnlyAfterMinutes` | `0`               | "Last position" is not available if the character's last session is more recent than this (anti free teleport).                                                                                                                          |
| `onlyNewCharacter`     | `true`            | The selector only appears on the first spawn of a newly created character; later logins enter at the last saved position (dead / cuffed: medical / police decide). `false` = selector on every join.                                     |
| `newCharacter`         | `'spawns'`        | First spawn after identity / appearance: `'spawns'` (selector, points with `firstTime = true` included), `'coords'` (fixed `firstSpawn` point, no choice) or `'apartments'` (last position / framework default).                         |
| `firstSpawn`           | LSIA              | Point used with `newCharacter = 'coords'`.                                                                                                                                                                                               |
| `camera`               | `height = 'auto'` | Aerial camera: `height` `'auto'` (500 m) or metres above ground (clamped 80..1500, beyond that the game does not draw the map); `fov`, `tilt` (0 = straight down), `hover`. The camera flies to the chosen point.                        |
| `properties`           | `false`           | `true` adds the character's properties / apartments from `Bridge.getProperties(src, charKey)` or, if defined in `config_server.lua`, `Config.Spawn.propertyProvider(src, charKey)` returning `{ { id, label, x, y, z, h, district? } }`. |
| `locations`            | 9 points          | Legion Square, Pillbox Hill, Motel, Beach, Airport, Sandy Shores, Grapeseed, Paleto Bay, Mission Row PD (job `police`).                                                                                                                  |

A point: `{ id, label, district, icon, x, y, z, h, job, gang, ace, firstTime }`. `id` is `a-z0-9_-`, max 32 characters (`last` and `first` are reserved). `icon` is `'pin'`, `'home'`, `'work'`, `'beach'` or `'peak'`. `job` is a name or a list, `gang` the same (job and gang are in OR), `ace` is in AND with them, `firstTime = true|false`.

### Pause menu

```lua
Config.Pause = {
    keyP = 'menu',            -- 'menu' (our menu) | 'map' (native map)
    portrait = true,
    links = {},               -- { { label = 'Discord', url = 'https://...' } }
    rules = '',
    disconnectMessage = 'Disconnesso dal menu di pausa.',
    interceptMode = 'auto',   -- 'auto' | 'controls' | 'frontend' | 'native'
    block = { dead = true, cuffed = true, inVehicle = false, ragdoll = false, cutscene = true,
              falling = false, swimming = false, parachute = false, climbing = false },
    blockedAction = 'ignore', -- 'ignore' | 'native'
    blockedNotify = true,     -- on-screen notice (at most one every 3 s) when ESC is blocked
    native = { ... },         -- native pages opened by our menu (hashes; see config.lua)
    changeCharacter = { cooldownSec = 300, blockIfDead = true, blockIfCuffed = true,
                        blockIfDamagedWithinSec = 60, blockInVehicle = true, allowedAce = nil },
}
```

The menu shows the character card and the server info with **live** data (money, job, hours, players, ping, time; light polling **only while open**) and quick actions with shortcuts (M map, I server, S settings, G GTA settings, K keys, R relog, D disconnect). Player settings (scale, accent, language, audio...) apply instantly and are saved in KVP.

`interceptMode`: `'auto'` tries method 1 (disable controls), then 2 (close the native frontend), then 3 (leave the native menu and turn the module off). `native` hashes are configurable because they vary between builds: if a page does not open within 1 s it disappears from the UI.

### Relog

```lua
Config.Relog = {
    enabled = true,
    command = 'relog',        -- '' = no command
    key = '',                 -- optional key, e.g. 'F10' (RegisterKeyMapping); '' = none
    keyMapper = 'keyboard',   -- 'keyboard' | 'PAD_ANALOGBUTTON' | 'MOUSE_BUTTON' ...
    countdownSec = 5,         -- seconds the ped stays frozen before the relog (1..60)
    cooldownSec = nil,        -- nil = Config.Pause.changeCharacter.cooldownSec
}
```

The old `confirm` / `confirmSec` are **inert**: you can leave them in an old config. `Config.Pause.changeCharacter.enabled` no longer exists (an old value is ignored): the relog is the only way back to the selection and is turned off only by `Config.Relog.enabled`. See [Commands & permissions](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/commands-and-permissions.md#relog).

### Transition, loadscreen, loading

| Key                             | Default  | Description                                                                                                                 |
| ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Config.Transition.fadeOutMs`   | `750`    | Fade out (400..1500, recommended 600-900).                                                                                  |
| `Config.Transition.fadeInMs`    | `700`    | Fade in (300..1500).                                                                                                        |
| `Config.Transition.sceneWaitMs` | `3500`   | Longest wait for the scene on a black screen (500..10000).                                                                  |
| `Config.Loadscreen.watchdogSec` | `90`     | The loadscreen closes anyway this many seconds after the session starts (10..600). The rest is in `loadscreen/config.json`. |
| `Config.Loading.music`          | disabled | `enabled`, `file`, `volume` (0.5), `fadeInMs`, `fadeOutMs`, `duringSelect = true`. The only audio source of the package.    |
| `Config.Loading.ambient`        | disabled | `enabled`, `file`, `volume` (0.3), `fadeInMs`, `fadeOutMs`.                                                                 |

Audio files go in `web/public` (relative path, no `..`), then rebuild the UI. The volume is multiplied by the player's music volume setting.

## config\_server.lua

| Key                              | Default                                    | Description                                                                                                                                                                                                                                                         |
| -------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Slots.default`           | `1`                                        | Base slots of every new account (the others come from ACE, `/gmc slots add` or a Tebex grant).                                                                                                                                                                      |
| `Config.Slots.max`               | `8`                                        | Absolute cap (max 15).                                                                                                                                                                                                                                              |
| `Config.Slots.showLocked`        | `true`                                     | With `unlockUrl`: show at most ONE locked slot (the next to unlock), never a row of locks.                                                                                                                                                                          |
| `Config.Slots.unlockUrl`         | `''`                                       | Tebex link of the "Unlock" button.                                                                                                                                                                                                                                  |
| `Config.Slots.rules`             | `{}`                                       | Slots per role, by ACE only. For example `{ { ace = 'group.vip', add = 1 }, { ace = 'tebex.gold', add = 2 } }`. Discord roles arrive as ACE from DiscordAcePerms / txAdmin.                                                                                         |
| `Config.Slots.stack`             | `'sum'`                                    | `'sum'` or `'max'`.                                                                                                                                                                                                                                                 |
| `Config.ESX.prefix`              | `'char'`                                   | Same as `esx_multicharacter`: existing `char1:<license>` characters show up by themselves.                                                                                                                                                                          |
| `Config.ESX.widenColumns`        | `true`                                     | Widen the identifier / owner varchar columns like `esx_multicharacter` did.                                                                                                                                                                                         |
| `Config.ESX.joinTimeoutMs`       | `15000`                                    | ESX character load timeout.                                                                                                                                                                                                                                         |
| `Config.Staff.command`           | `'gmc'`                                    | Staff command name.                                                                                                                                                                                                                                                 |
| `Config.Staff.confirmTimeoutSec` | `60`                                       | Time to confirm a destructive action.                                                                                                                                                                                                                               |
| `Config.Staff.acePrefix`         | `'ghiaccio_multichar'`                     | ACE prefix.                                                                                                                                                                                                                                                         |
| `Config.Staff.groups`            | `{ admin = {}, mod = {} }`                 | Framework groups for people without ACE. `admin` = everything, `mod` = `modNodes`.                                                                                                                                                                                  |
| `Config.Staff.modNodes`          | `staff.view`, `staff.slots`, `staff.chars` | What the `mod` group can do.                                                                                                                                                                                                                                        |
| `Config.Staff.maxBackupBytes`    | `33554432`                                 | 32 MB per backup.                                                                                                                                                                                                                                                   |
| `Config.Backup.retentionDays`    | `14`                                       | Backup retention.                                                                                                                                                                                                                                                   |
| `Config.Wipe`                    | see file                                   | A wipe keeps the character (name, birth date, slot) but makes it "new" again: `resetMoney`, `clearInventory`, `resetJob`, `resetPosition`, `removeVehicles` (all `true`), `removeProperties` (`false`), `extraTables`, starting money, spawn and job per framework. |
| `Config.DeleteExtraTables`       | `{}`                                       | Like `Wipe.extraTables` but only for delete. Each entry is `{ table = 'name', column = 'key_column' }`.                                                                                                                                                             |
| `Config.Logging`                 | console + db, `retentionDays = 180`        | Webhook only via the convar `ghiaccio_mc:webhook` (see [Integrations](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/integrations.md#discord-webhook)).                                                                                          |

{% hint style="info" %}
On a server that is already running, no existing character is ever locked by the default: until staff sets the base, an account's slots are at least its characters (even above `max`). Characters are locked only with `/gmc char lock` (or `/gmc slots remove|set`, with confirmation).
{% endhint %}

## UI build

The UI (`web/dist`) is prebuilt. Rebuild it only if you change `web/src` or `web/public` (needs Node): `cd web && npm install && npm run build`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
