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

# Feron Multicharacter

Premium character selection system for FiveM with built-in Tebex integration for selling extra character slots.

* **Frameworks:** QBCore / Qbox (main package) · ESX Legacy 1.10+ (ESX package)
* **MySQL:** oxmysql / mysql-async / ghmattimysql (switch via `Config.Mysql`)

## Features

* 4 character slots by default — scales to \~10 cleanly
* Premium slot expansion via Tebex purchase + redeem code
* Discord webhook logging for character create / delete / play / premium redeem
* Optional audit log table (`feron_multichar_audit_log`)
* Photo / preview mode with rotating idle animations and theme picker (crimson · arctic · toxic)
* Streamer Mode toggle (blurs PII for content creators)
* `/relog` command to switch characters mid-session without disconnect

## Installation

### 1. Drop the resource

Copy `feron_multicharacter/` into your `resources/` folder.

### 2. Run `install.sql`

Execute the file once against your database. It creates:

* `feron_multichar_slots` — premium slot allowance per identifier
* `feron_multichar_keys` — pending Tebex keys (filled when a key is purchased)
* `feron_multichar_audit_log` — optional, soft no-op if the table is absent

### 3. `server.cfg`

```cfg
ensure oxmysql
ensure feron_multicharacter
```

### 4. Edit `config.lua`

See the [Config](/welcome/scripts/feron-multicharacter/config.md) page for the full file with comments.

***

## ESX-specific notes

{% hint style="info" %}
**Set `Config.Multichar = true` in `es_extended/shared/config/main.lua`.**

This tells es\_extended to defer its built-in player-join flow to a multichar resource — feron\_multicharacter takes over from there.

Some ESX Legacy builds auto-detect this via the `provides "esx_multicharacter"` directive in our `fxmanifest.lua` and flip the flag automatically. **Setting it explicitly is the safer choice** — if you skip it on a build that doesn't auto-detect, ESX runs its own auto-login on join and races our flow, leaving the player with a broken character load.
{% endhint %}

If your server previously had `esx_multicharacter` or `esx_identity` installed, disable them:

* Move them out of `resources/`, or rename to `[disabled]/`, or remove their `ensure` lines from `server.cfg`

The ESX edition stores characters in the `users` table with multichar-style identifiers (`char1:<hash>`, `char2:<hash>`, …).

***

## QBCore / Qbox-specific notes

* Disable `qb-multicharacter` if installed — feron\_multicharacter replaces it entirely
* Set `Config.Framework` to `'qb'` (modern export-based), `'oldqb'` (legacy TriggerEvent), or `'qbx'` (qbox)
* Characters are stored in the standard QBCore `players` table

***

## Tebex setup — Premium Slots

In your Tebex package's **Online Command** field, paste:

```
feron_mc_redeem_premium {"transid":"{transaction_id}","slots":1}
```

Change `"slots":1` to the number of slots the package grants.

When a player buys:

1. Tebex runs the command on your server (online instantly, or queued until next login)
2. Server inserts the key into `feron_multichar_keys`
3. Player opens the multichar UI → **Unlock Premium Slot** → enters the transaction ID
4. Server validates + grants the slots + marks the key as used

***

## Spawn flow

After character select, the player goes to wherever `Config.SpawnFlow` resolves:

| Flow              | Behavior                                                                                  |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `'auto'`          | Detects spawn selector / apartments / custom hook and picks the best                      |
| `'spawnSelector'` | Triggers the configured spawn picker (default: `feron_spawnSelector`)                     |
| `'apartments'`    | Triggers `qb-apartments` (QBCore only)                                                    |
| `'custom'`        | Invokes `Config.OnCustomSpawn(src, charKey, position, identity)` — integrate any selector |
| `'lastLocation'`  | Teleports the player to their saved coordinates                                           |

For non-feron spawn selectors, override these three keys to wire your own:

```lua
Config.SpawnSelectorResource  = 'vms_spawnselector'
Config.SpawnSelectorOpenEvent = 'vms_spawnselector:openUI'
Config.SpawnFinishEvent       = 'vms_spawnselector:spawned'
```

***

For the full annotated `config.lua`, see [Config](/welcome/scripts/feron-multicharacter/config.md).