> 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/it/multichar/configuration.md).

# Configurazione

Due file di testo, modificabili da te (non sono sotto escrow): `config.lua` (replicato ai client, niente segreti) e `config_server.lua` (solo server, mai inviato ai client). Un valore non valido viene segnalato da `gmc selftest`.

## config.lua

| Chiave                       | Default      | Cosa fa                                                                                                                                                                                                     |
| ---------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Locale`              | `'it'`       | `'it'` o `'en'` (altri file in `locales/` si aggiungono da soli).                                                                                                                                           |
| `Config.Framework`           | `'auto'`     | `'auto'`, `'esx'`, `'qbcore'` o `'qbox'`.                                                                                                                                                                   |
| `Config.Debug`               | `false`      | Log aggiuntivi.                                                                                                                                                                                             |
| `Config.Modules`             | tutti `true` | `select`, `identity`, `spawn`, `pause`: ognuno si spegne. Con `select = false` si entra con l'ultimo personaggio. Le combinazioni non valide (per esempio identity senza select) le segnala `gmc selftest`. |
| `Config.Rpc.clientTimeoutMs` | `25000`      | Timeout delle chiamate client-server. Deve essere almeno `Config.ESX.joinTimeoutMs` + 5000 (lo controlla il selftest).                                                                                      |

### Tema

```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',
}
```

### Selezione

```lua
Config.Select = {
    autoPlay = false,        -- true: salta la selezione e gioca l'ultimo PG (se giocabile)
    showDetails = true,
    skipIntro = false,
    alwaysAvailable = true,  -- la selezione resta raggiungibile anche con Modules.select = false (via /relog)
    command = 'personaggi',  -- comando per tornare alla selezione ('' = nessun comando); avvia il relog
    bucketBase = 5000,       -- routing bucket privato durante selezione/identity: bucketBase + id server
}
```

### Scene

`Config.Scenes`:

| Chiave                          | Default    | Cosa fa                                                                                                                                                                                                    |
| ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                       | `true`     | `false`: nessuna scena, il ped del giocatore resta nascosto e la UI sta sopra il mondo.                                                                                                                    |
| `selectScene`                   | `'hangar'` | Scena della selezione (deve avere `ensemble`): tutti i personaggi insieme.                                                                                                                                 |
| `studioScene`                   | `'studio'` | Set fotografico dell'identity.                                                                                                                                                                             |
| `maxPeds`                       | `10`       | Personaggi in scena insieme (1..10); oltre restano selezionabili dalla tastiera.                                                                                                                           |
| `quality`                       | `'high'`   | `'high'` (2 luci con ombra + luce del segnaposto) o `'low'` (1 luce, niente ombre: PC deboli).                                                                                                             |
| `debug`                         | `false`    | Stampa in F8 posti scartati, suolo dei ped, camera, verifica dell'inquadratura (vedi `/gmc camdebug`).                                                                                                     |
| `streamTimeoutMs`               | `7000`     | Tempo massimo per caricare la zona della scena; oltre si usa lo stage semplice.                                                                                                                            |
| `groundTimeoutMs`               | `2500`     | Attesa massima della collision attorno al ped.                                                                                                                                                             |
| `revealTimeoutMs`               | `15000`    | Watchdog: il giocatore non resta mai sullo schermo nero oltre questo tempo.                                                                                                                                |
| `introMs`                       | `1800`     | Dolly d'ingresso dall'inquadratura larga a quella di gruppo.                                                                                                                                               |
| `reaction`                      | `true`     | Il ped guarda in camera quando viene selezionato.                                                                                                                                                          |
| `silenceWorld`                  | `true`     | Smorza l'audio del mondo durante la selezione.                                                                                                                                                             |
| `customPoses` / `disabledPoses` | `{}`       | Aggiungi pose tue (catalogo in `shared/poses.lua`) o nascondi quelle che non vuoi.                                                                                                                         |
| `weatherPause`                  | 3 righe    | Script di weather sync da mettere in pausa mentre la scena controlla ora e meteo (vedi [Integrazioni](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/multichar/integrations.md#weather-sync)). |

Le scene (posizione, ora, meteo, luci, formazione) stanno in `data/scenes.json` (formato in `docs/SCENES_API.md`) e si ricaricano con `/gmc reload`; `/gmc scene` le elenca. C'è una scena di selezione e un set per l'identity.

### Identità

```lua
Config.Identity = {
    fields = { nationality = true, backstory = true, height = true },
    nameMin = 2, nameMax = 20,
    ageMin = 16, ageMax = 90,
    heightMin = 140, heightMax = 220,
    defaultHeight = 175,         -- altezza salvata quando il campo `height` è spento
    dateFormat = 'DD/MM/YYYY',   -- 'DD/MM/YYYY' | 'MM/DD/YYYY' | 'YYYY-MM-DD'
    nationalities = 'free',      -- 'free' (testo libero) oppure lista { 'Italiana', 'Americana', ... }
    uniqueNames = true,          -- nome + cognome unici fra tutti i personaggi (verificato dal 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`: foto della carta d'identità (pedheadshot). Se non arriva entro `timeoutMs` la carta mostra la silhouette. `autoCreate`: con `Modules.identity = false` e nessun PG, il personaggio si crea da solo con questi dati (nome = nome del giocatore).

### Aspetto

```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`: come si vede l'aspetto in selezione. Se lo script non sa vestire un ped diverso dal giocatore (esx\_skin), la risorsa usa il giocatore stesso, nascosto nel suo bucket privato. Il creatore gira nel **routing bucket privato** del giocatore; il bucket 0 torna solo a creatore chiuso o allo spawn. Vedi [Integrazioni](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/multichar/integrations.md#adapter-vestiti).

### Spawn

| Chiave                 | Default           | Cosa fa                                                                                                                                                                                                                               |
| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`                 | `'ghiaccio'`      | `'ghiaccio'` (selettore 3D), `'framework'`, `'last'` o `'none'`. Modulo spento, `'framework'`, `'none'` o nessun punto = ultima posizione.                                                                                            |
| `lastOnlyAfterMinutes` | `0`               | "Ultima posizione" non disponibile se l'ultima sessione del PG è più recente di così (anti teletrasporto gratis).                                                                                                                     |
| `onlyNewCharacter`     | `true`            | Il selettore compare solo al primo spawn di un personaggio appena creato; nei login successivi si entra all'ultima posizione salvata (morti/arrestati: decide medical/polizia). `false` = selettore a ogni ingresso.                  |
| `newCharacter`         | `'spawns'`        | Primo spawn dopo identity/aspetto: `'spawns'` (selettore, punti con `firstTime = true` inclusi), `'coords'` (punto fisso `firstSpawn`, nessuna scelta) o `'apartments'` (ultima posizione / default del framework).                   |
| `firstSpawn`           | LSIA              | Punto usato con `newCharacter = 'coords'`.                                                                                                                                                                                            |
| `camera`               | `height = 'auto'` | Camera aerea: `height` `'auto'` (500 m) o metri sul suolo (clamp 80..1500: oltre il gioco non disegna la mappa); `fov`, `tilt` (0 = a picco), `hover`. La camera vola sul punto scelto.                                               |
| `properties`           | `false`           | `true` aggiunge proprietà/appartamenti del PG da `Bridge.getProperties(src, charKey)` o, se definita in `config_server.lua`, da `Config.Spawn.propertyProvider(src, charKey)` che ritorna `{ { id, label, x, y, z, h, district? } }`. |
| `locations`            | 9 punti           | Legion Square, Pillbox Hill, Motel, Spiaggia, Aeroporto, Sandy Shores, Grapeseed, Paleto Bay, Mission Row PD (job `police`).                                                                                                          |

Un punto: `{ id, label, district, icon, x, y, z, h, job, gang, ace, firstTime }`. `id` è `a-z0-9_-`, massimo 32 caratteri (`last` e `first` sono riservati). `icon` è `'pin'`, `'home'`, `'work'`, `'beach'` o `'peak'`. `job` è un nome o una lista, `gang` uguale (job e gang sono in OR), `ace` è in AND con loro, `firstTime = true|false`.

### Pause menu

```lua
Config.Pause = {
    keyP = 'menu',            -- 'menu' (nostro menu) | 'map' (mappa nativa)
    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,     -- avviso a schermo (al massimo uno ogni 3 s) quando ESC è bloccato
    native = { ... },         -- pagine native aperte dal nostro menu (hash; vedi config.lua)
    changeCharacter = { cooldownSec = 300, blockIfDead = true, blockIfCuffed = true,
                        blockIfDamagedWithinSec = 60, blockInVehicle = true, allowedAce = nil },
}
```

Il menu mostra la scheda del personaggio e le info del server con dati **vivi** (soldi, lavoro, ore, giocatori, ping, ora; polling leggero SOLO a menu aperto) e azioni rapide con scorciatoie (M mappa, I server, S impostazioni, G impostazioni GTA, K tasti, R relog, D disconnetti). Le impostazioni del giocatore (scala, accento, lingua, audio...) si applicano subito e si salvano in KVP.

`interceptMode`: `'auto'` prova il metodo 1 (disabilita controlli), poi 2 (chiude il frontend nativo), poi 3 (lascia il menu nativo e spegne il modulo). Gli hash di `native` sono configurabili perché variano tra build: se una pagina non si apre entro 1 s sparisce dalla UI.

### Relog

```lua
Config.Relog = {
    enabled = true,
    command = 'relog',        -- '' = nessun comando
    key = '',                 -- tasto opzionale, es. 'F10' (RegisterKeyMapping); '' = nessun tasto
    keyMapper = 'keyboard',   -- 'keyboard' | 'PAD_ANALOGBUTTON' | 'MOUSE_BUTTON' ...
    countdownSec = 5,         -- secondi di ped congelato prima del relog (1..60)
    cooldownSec = nil,        -- nil = Config.Pause.changeCharacter.cooldownSec
}
```

`confirm` / `confirmSec` delle versioni precedenti sono **inerti**: si possono lasciare in una vecchia config. `Config.Pause.changeCharacter.enabled` non esiste più (un vecchio valore è ignorato): il relog è l'UNICO modo per tornare alla selezione e si spegne solo con `Config.Relog.enabled`. Vedi [Comandi e permessi](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/multichar/commands-and-permissions.md#relog).

### Transizioni, loadscreen, loading

| Chiave                          | Default | Descrizione                                                                                                                      |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Transition.fadeOutMs`   | `750`   | Dissolvenza in uscita (400..1500, consigliato 600-900).                                                                          |
| `Config.Transition.fadeInMs`    | `700`   | Dissolvenza in entrata (300..1500).                                                                                              |
| `Config.Transition.sceneWaitMs` | `3500`  | Attesa massima della scena a schermo nero (500..10000).                                                                          |
| `Config.Loadscreen.watchdogSec` | `90`    | Dopo tanti secondi dall'avvio della sessione il loadscreen si chiude comunque (10..600). Il resto è in `loadscreen/config.json`. |
| `Config.Loading.music`          | spenta  | `enabled`, `file`, `volume` (0.5), `fadeInMs`, `fadeOutMs`, `duringSelect = true`. Unica sorgente audio del pacchetto.           |
| `Config.Loading.ambient`        | spento  | `enabled`, `file`, `volume` (0.3), `fadeInMs`, `fadeOutMs`.                                                                      |

I file audio stanno in `web/public` (percorso relativo, senza `..`), poi si ricostruisce la UI. Il volume è moltiplicato per il volume musica scelto dal giocatore.

## config\_server.lua

| Chiave                           | Default                                    | Descrizione                                                                                                                                                                                                                                                         |
| -------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Slots.default`           | `1`                                        | Slot base di ogni account nuovo (gli altri arrivano da ACE, `/gmc slots add` o accredito Tebex).                                                                                                                                                                    |
| `Config.Slots.max`               | `8`                                        | Tetto assoluto (massimo 15).                                                                                                                                                                                                                                        |
| `Config.Slots.showLocked`        | `true`                                     | Con `unlockUrl`: UN solo slot col lucchetto (il prossimo da sbloccare), mai una fila di lucchetti.                                                                                                                                                                  |
| `Config.Slots.unlockUrl`         | `''`                                       | Link Tebex del pulsante "Sblocca".                                                                                                                                                                                                                                  |
| `Config.Slots.rules`             | `{}`                                       | Slot per ruolo SOLO via ACE. Per esempio `{ { ace = 'group.vip', add = 1 }, { ace = 'tebex.gold', add = 2 } }`. I ruoli Discord arrivano come ACE da DiscordAcePerms/txAdmin.                                                                                       |
| `Config.Slots.stack`             | `'sum'`                                    | `'sum'` o `'max'`.                                                                                                                                                                                                                                                  |
| `Config.ESX.prefix`              | `'char'`                                   | Identico a `esx_multicharacter`: i personaggi esistenti `char1:<license>` compaiono da soli.                                                                                                                                                                        |
| `Config.ESX.widenColumns`        | `true`                                     | Allarga le colonne identifier/owner (varchar) come faceva `esx_multicharacter`.                                                                                                                                                                                     |
| `Config.ESX.joinTimeoutMs`       | `15000`                                    | Timeout di caricamento del personaggio su ESX.                                                                                                                                                                                                                      |
| `Config.Staff.command`           | `'gmc'`                                    | Nome del comando staff.                                                                                                                                                                                                                                             |
| `Config.Staff.confirmTimeoutSec` | `60`                                       | Tempo per confermare un'azione distruttiva.                                                                                                                                                                                                                         |
| `Config.Staff.acePrefix`         | `'ghiaccio_multichar'`                     | Prefisso ACE.                                                                                                                                                                                                                                                       |
| `Config.Staff.groups`            | `{ admin = {}, mod = {} }`                 | Gruppi del framework per chi non usa ACE. `admin` = tutto, `mod` = `modNodes`.                                                                                                                                                                                      |
| `Config.Staff.modNodes`          | `staff.view`, `staff.slots`, `staff.chars` | Cosa può fare il gruppo `mod`.                                                                                                                                                                                                                                      |
| `Config.Staff.maxBackupBytes`    | `33554432`                                 | 32 MB per backup.                                                                                                                                                                                                                                                   |
| `Config.Backup.retentionDays`    | `14`                                       | Retention dei backup.                                                                                                                                                                                                                                               |
| `Config.Wipe`                    | vedi file                                  | Il wipe lascia il personaggio (nome, data, slot) ma lo fa tornare "nuovo": `resetMoney`, `clearInventory`, `resetJob`, `resetPosition`, `removeVehicles` (tutti `true`), `removeProperties` (`false`), `extraTables`, soldi iniziali, spawn e lavoro per framework. |
| `Config.DeleteExtraTables`       | `{}`                                       | Come `Wipe.extraTables` ma solo per delete. Ogni voce è `{ table = 'nome', column = 'colonna_chiave' }`.                                                                                                                                                            |
| `Config.Logging`                 | console + db, `retentionDays = 180`        | Webhook solo da convar `ghiaccio_mc:webhook` (vedi [Integrazioni](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/multichar/integrations.md#webhook-discord)).                                                                                           |

{% hint style="info" %}
Su un server già avviato nessun personaggio esistente viene bloccato dal default: finché lo staff non fissa la base, gli slot di un account sono almeno i suoi personaggi (anche oltre `max`). Si blocca solo con `/gmc char lock` (o `/gmc slots remove|set`, con conferma).
{% endhint %}

## Build della UI

La UI (`web/dist`) è già compilata. Serve ricostruirla solo se modifichi `web/src` o `web/public` (serve 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/it/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.
