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

# Installation

## Requirements

* A recent FiveM server (artifact with `lua54`) and **`oxmysql`**.
* One of **ESX Legacy** (`es_extended`), **QBCore** (`qb-core`) or **Qbox** (`qbx_core`).
* Optional: an appearance script (illenium-appearance, fivem-appearance, rcore\_clothing, qb-clothing, esx\_skin + skinchanger).
* No other dependency. The `ghiaccio_mc_*` tables are created on start.

## 1. Download

The script is delivered through **Cfx.re Asset Escrow**. After the purchase, log in to [portal.cfx.re](https://portal.cfx.re) with the Cfx.re account used for the purchase and open **Granted Assets**. Download `ghiaccio_multichar` from there.

{% hint style="info" %}
Escrowed resources only run on servers whose license key belongs to the purchasing Cfx.re account.
{% endhint %}

## 2. Copy and ensure

Copy `ghiaccio_multichar` into `resources/` and add it to `server.cfg` **after** oxmysql and the framework:

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

Then follow the section for your framework below, restart the server and run `gmc selftest` in the console: it tells you what to fix. Existing characters show up with no migration.

## ESX Legacy

* Remove `esx_multicharacter` and stop `esx_identity`. If `server.cfg` starts a category folder (`ensure [core]`), dropping a line is not enough: **move both folders out of `resources/`** (keep a copy), otherwise they start anyway.
* Keep `skinchanger` + `esx_skin` (or another appearance script) for the creator.
* `fxmanifest.lua` declares `provide 'esx_multicharacter'`: `es_extended` reads it to enter multicharacter mode.
* Put `ensure ghiaccio_multichar` after `ensure [core]` (or after `es_extended`, `esx_skin` and `skinchanger`): the creator uses the appearance script that is already running.
* The maximum character load time is `Config.ESX.joinTimeoutMs` (`config_server.lua`).

{% hint style="info" %}
If `gmc selftest` says **"ESX does NOT see esx\_multicharacter"**, copy `install/esx_multicharacter/` into `resources/` (an empty folder with just an fxmanifest, no need to start it), restart `es_extended` and run the selftest again. Until fixed, the resource stays passive and does not touch players.
{% endhint %}

## QBCore

* Stop and remove `qb-multicharacter` from `server.cfg` (and from the dependencies of other scripts). If you start the category (`ensure [qb]`), dropping a line is not enough: move the folder out of `resources/` (keep a copy).
* Also stop `qb-spawn`: the spawn selector is part of this resource (`Config.Spawn`).
* `qb-apartments` and `qb-houses` may stay: they trigger `qb-spawn` / `qb-multicharacter` events that nobody listens to now, so the apartment choice does not appear (with `Config.Spawn.newCharacter = 'spawns'`, the default, it is not needed).
* Put `ensure ghiaccio_multichar` after `qb-core` and `qb-clothing` (at the bottom, after `ensure [qb]`).

## Qbox

1. `qbx_core/config/client.lua`: `characters.useExternalCharacters = true`.
2. `qbx_core/config/server.lua`: `defaultNumberOfCharacters = 0` and `playersNumberOfCharacters = {}` (this resource manages slots).
3. **Close the two delete doors.** Players cannot delete characters; without these two steps a modified client could, with no backup:
   * `qbx_core/server/character.lua`: remove or comment out the `RegisterNetEvent('qbx_core:server:deleteCharacter', ...)` block.
   * `qbx_core/server/player.lua`: remove or comment out the `lib.callback.register('qbx_core:server:deleteCharacter', DeleteCharacter)` line.
4. `qbx_spawn` may stay started: with `useExternalCharacters = true` the core no longer calls it. Put `ensure ghiaccio_multichar` after `qbx_core` and `illenium-appearance`.

`gmc selftest` reports if either delete door is still open. Anyone who uses them anyway is logged and disconnected.

## Other loadscreens

The resource ships its own loadscreen. FiveM uses **one loadscreen** per server: **stop the others** (for example `esx_loadingscreen` in `[core]`, `qb-loading` in `[qb]`: stop or remove the resource or the folder that contains it from `server.cfg`, or drop the `loadscreen` line from their manifest). `gmc selftest` reports them.

To keep your own loadscreen instead, remove the 3 `loadscreen*` lines from this resource's `fxmanifest.lua`. See [Integrations](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/integrations.md#loadscreen-and-local-editor).

## Staff permissions

```cfg
add_ace group.admin ghiaccio_multichar.admin allow            # everything
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.sceneeditor ghiaccio_multichar.scene allow      # /gmc scene only
add_principal identifier.license:XXXXXXXX group.admin
```

Assign `group.mod` and `group.sceneeditor` to people, for example `add_principal identifier.license:YYYYYYYY group.mod`; members of `group.admin` already have everything. Check with `gmc selftest` from the console or in game. The full table is in [Commands & permissions](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/commands-and-permissions.md).

## 3. Check

Restart the server and run `gmc selftest` from the console. It checks the framework, oxmysql, migrations, invalid config, conflicting resources, the ESX `provide`, Qbox (the 2 config lines and the 2 delete doors), the appearance adapter and the scenes. Levels: error, warning, info, ok.

Next step: [Configuration](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/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/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.
