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

# Integrations & adapters

## Frameworks

`Config.Framework = 'auto'` detects the framework; force it with `'esx'`, `'qbcore'` or `'qbox'`. The framework-specific installation steps are in [Installation](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/installation.md).

## Appearance adapters

`Config.Appearance.adapter`:

* `'auto'` (default) tries illenium-appearance, fivem-appearance, rcore\_clothing, qb-clothing, esx\_skin and uses the first one running.
* Or force one: `'illenium'`, `'fivem_appearance'`, `'rcore'`, `'qb_clothing'`, `'esx_skin'`, `'custom'`, `'none'`.

| Option                     | What it does                                                                                                                                                                                                                                                                                              |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `previewMode`              | How appearance is shown during selection: `auto`, `ped` (applied to the local ped), `player` (on the player ped) or `monogram` (no appearance in the 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. |
| `forceCreatorOnNew = true` | The creator opens after identity. It runs in the player's **private routing bucket**; bucket 0 is restored only when the creator closes or on spawn.                                                                                                                                                      |
| `defaultOutfits`           | With no adapter the character joins with these outfits (`m` and `f`).                                                                                                                                                                                                                                     |

With `esx_skin` the look is also applied to local peds (skinchanger format applied with natives), so with ESX every character is shown dressed together in the selection.

**Another appearance script**: set `adapter = 'custom'` and fill in `adapters/appearance/custom.lua` (2 functions, instructions in the file). The adapters are in plain text, not escrowed.

## Importing characters

To bring characters over from another script, run from the **server console**:

```
gmc import esx
gmc import qb
gmc import qbox
```

Without `--apply` it is a dry run. With `--apply` it imports. `import` is console only and needs the `admin` permission.

With ESX, `Config.ESX.prefix = 'char'` is the same as `esx_multicharacter`: existing `char1:<license>` characters show up by themselves. If a character does not show up, check it with `gmc info <target>` and `gmc backup list <target>`.

## Tebex slot grant

No API key is needed. The Tebex package runs a console command; the transaction reference makes it idempotent (one purchase = one grant):

```
gmc slots add fivem:{id} 1 --yes tebex:{transaction}
```

* For a player who never joined, the grant stays pending and applies on first join.
* Timed slots: add `--days 30`.
* Set `Config.Slots.unlockUrl` (`config_server.lua`) to the package link: the "Unlock" button in the selection opens it.
* Roles: slot rules by ACE in `Config.Slots.rules` (Discord roles arrive as ACE from DiscordAcePerms / txAdmin).

## Loadscreen and local editor

The resource ships its own loadscreen (`loadscreen/`): gradient / image / slideshow / local video background, logo and server name, colors and accent (ice blue by default), music with volume and mute, rotating tips, links and a **real** progress bar (FiveM's `loadProgress`, `startInitFunction`... messages).

Customize it from **one file**, `loadscreen/config.json`, or with the **local web editor**: double-click `editor.bat` (Windows) or run `./editor.sh`. It offers a live preview of the real loadscreen, autosave (the previous copy is kept in `config.prev.json`), image / video / music upload into `loadscreen/media/` with content and size checks, and "Restore defaults". The editor listens only on 127.0.0.1 and writes only inside `loadscreen/`. Broken JSON or wrong fields: defaults are used and the warning goes to the console only. The full key reference is in `loadscreen/README.md` (Italian).

{% hint style="warning" %}
The manifest declares `loadscreen` and `loadscreen_manual_shutdown 'yes'`: this resource closes the loadscreen (when the selection is ready; a safety watchdog exists, `Config.Loadscreen.watchdogSec`). FiveM uses **one loadscreen** per server: stop the others. `gmc selftest` reports them. To keep another loadscreen, remove the 3 `loadscreen*` lines from this resource's `fxmanifest.lua`.
{% endhint %}

## Weather sync

While a scene is open the resource pauses weather sync and sets time and weather itself; sync resumes when it closes. Works with `qb-weathersync`, `cd_easytime` and `Renewed-Weathersync` (rows in `Config.Scenes.weatherPause`). For other scripts add a row with a pause and a resume event:

```lua
{ resource = 'qb-weathersync', pause = 'qb-weathersync:client:DisableSync', resume = 'qb-weathersync:client:EnableSync' },
```

Limits: the original `vSync` has no clean pause, so the scene weather is not guaranteed (stop it or switch to Renewed-Weathersync). `cd_easytime` forces `EXTRASUNNY` while paused.

## Discord webhook

The audit log goes to the console and the database (`ghiaccio_mc_audit`), and optionally to a Discord webhook. The webhook URL is read **only** from a server convar, never from a config file (config files are replicated to clients). In `server.cfg`:

```cfg
set ghiaccio_mc:webhook "https://discord.com/api/webhooks/..."
```

Retention of the audit log: `Config.Logging.retentionDays` (180).

## Exports

Two client exports to integrate with the pause menu (`SetPauseBlocked`, `AddPauseItem`): see [Commands & permissions](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/commands-and-permissions.md#client-exports). The resource has **no server exports**.


---

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