> 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/installation.md).

# Installazione

## Requisiti

* Server FiveM recente (artifact con `lua54`) e **`oxmysql`**.
* Uno tra **ESX Legacy** (`es_extended`), **QBCore** (`qb-core`) o **Qbox** (`qbx_core`).
* Facoltativo: uno script di aspetto (illenium-appearance, fivem-appearance, rcore\_clothing, qb-clothing, esx\_skin + skinchanger).
* Nessun'altra dipendenza. Le tabelle `ghiaccio_mc_*` si creano da sole all'avvio.

## 1. Download

Lo script viene consegnato tramite **Cfx.re Asset Escrow**. Dopo l'acquisto accedi a [portal.cfx.re](https://portal.cfx.re) con l'account Cfx.re usato per l'acquisto e apri **Granted Assets**. Scarica da lì `ghiaccio_multichar`.

{% hint style="info" %}
Le risorse con escrow funzionano solo su server la cui license key appartiene all'account Cfx.re che ha acquistato.
{% endhint %}

## 2. Copia e ensure

Copia `ghiaccio_multichar` in `resources/` e aggiungilo al `server.cfg` **dopo** oxmysql e il framework:

```cfg
ensure oxmysql
ensure es_extended        # oppure qb-core / qbx_core
ensure ghiaccio_multichar
```

Poi segui la sezione del tuo framework qui sotto, riavvia il server e lancia `gmc selftest` dalla console: dice cosa correggere. I personaggi esistenti compaiono senza migrare nulla.

## ESX Legacy

* Rimuovi `esx_multicharacter` e ferma `esx_identity`. Se nel `server.cfg` avvii una cartella-categoria (`ensure [core]`) non basta togliere la riga: **sposta le due cartelle fuori da `resources/`** (tienine una copia), altrimenti partono comunque.
* Tieni `skinchanger` + `esx_skin` (o un altro script di aspetto) per il creatore.
* Il `fxmanifest.lua` dichiara `provide 'esx_multicharacter'`: `es_extended` lo usa per entrare in modalità multicharacter.
* Metti `ensure ghiaccio_multichar` dopo `ensure [core]` (o dopo `es_extended`, `esx_skin` e `skinchanger`): il creatore usa lo script di aspetto già avviato.
* Il tempo massimo di caricamento del personaggio è `Config.ESX.joinTimeoutMs` (`config_server.lua`).

{% hint style="info" %}
Se `gmc selftest` dice **"ESX does NOT see esx\_multicharacter"**, copia `install/esx_multicharacter/` dentro `resources/` (cartella vuota, solo un fxmanifest; non serve avviarla), riavvia `es_extended` e rilancia il selftest. Finché non è risolto la risorsa resta passiva e non tocca i giocatori.
{% endhint %}

## QBCore

* Ferma e rimuovi `qb-multicharacter` dal `server.cfg` (e dalle dipendenze di altri script). Se avvii la categoria (`ensure [qb]`) togliere la riga non basta: sposta la cartella fuori da `resources/` (tienine una copia).
* Ferma anche `qb-spawn`: il selettore di spawn è di questa risorsa (`Config.Spawn`).
* `qb-apartments` e `qb-houses` possono restare: richiamano eventi di `qb-spawn` / `qb-multicharacter` che ora nessuno ascolta, quindi la scelta dell'appartamento non compare (con `Config.Spawn.newCharacter = 'spawns'`, il default, non serve).
* Metti `ensure ghiaccio_multichar` dopo `qb-core` e `qb-clothing` (in fondo, dopo `ensure [qb]`).

## Qbox

1. `qbx_core/config/client.lua`: `characters.useExternalCharacters = true`.
2. `qbx_core/config/server.lua`: `defaultNumberOfCharacters = 0` e `playersNumberOfCharacters = {}` (gli slot li gestisce questa risorsa).
3. **Chiudi le due porte di cancellazione.** I giocatori non possono eliminare i personaggi; senza questi due passi un client modificato potrebbe farlo, senza backup:
   * `qbx_core/server/character.lua`: rimuovi o commenta il blocco `RegisterNetEvent('qbx_core:server:deleteCharacter', ...)`.
   * `qbx_core/server/player.lua`: rimuovi o commenta la riga `lib.callback.register('qbx_core:server:deleteCharacter', DeleteCharacter)`.
4. `qbx_spawn` può restare avviato: con `useExternalCharacters = true` il core non lo chiama più. Metti `ensure ghiaccio_multichar` dopo `qbx_core` e `illenium-appearance`.

`gmc selftest` segnala se una delle due porte è ancora aperta. Chi le usa comunque viene registrato nel log e disconnesso.

## Altri loadscreen

La risorsa include il suo loadscreen. FiveM usa **un solo loadscreen** per server: **ferma gli altri** (es. `esx_loadingscreen` in `[core]`, `qb-loading` in `[qb]`: `stop` o togli dal `server.cfg` la risorsa o la cartella che la contiene, oppure togli la riga `loadscreen` dal loro manifest). `gmc selftest` li segnala.

Se vuoi tenere il tuo loadscreen, togli le 3 righe `loadscreen*` dal `fxmanifest.lua` di questa risorsa. Vedi [Integrazioni](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/multichar/integrations.md#loadscreen-ed-editor-locale).

## Permessi staff

```cfg
add_ace group.admin ghiaccio_multichar.admin allow            # tutto
add_ace group.mod ghiaccio_multichar.staff.view allow
add_ace group.mod ghiaccio_multichar.staff.slots allow
add_ace group.mod ghiaccio_multichar.staff.chars allow
add_ace group.scenografo ghiaccio_multichar.scene allow       # solo /gmc scene
add_principal identifier.license:XXXXXXXX group.admin
```

I gruppi `group.mod` e `group.scenografo` vanno assegnati alle persone, per esempio `add_principal identifier.license:YYYYYYYY group.mod`; chi è in `group.admin` ha già tutto. Verifica con `gmc selftest` da console o in gioco. La tabella completa è in [Comandi e permessi](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/multichar/commands-and-permissions.md).

## 3. Verifica

Riavvia il server e lancia `gmc selftest` dalla console. Controlla framework, oxmysql, migrazioni, config non valida, risorse in conflitto, ESX provide, Qbox (le 2 righe di config e le 2 porte di delete), adapter vestiti e scene. Livelli: errore, avviso, info, ok.

Prossimo passo: [Configurazione](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/multichar/configuration.md).


---

# 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/installation.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.
