> 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).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://feron-scripts.gitbook.io/welcome/scripts/feron-multicharacter.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.