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

# DXS Multi Character

<figure><img src="/files/EK8vUqhpEB08DMSJ3xEH" alt=""><figcaption></figcaption></figure>

### Dependencies

* `oxmysql` (required)
* Framework (choose one):
* `es_extended` when `Config.Framework = "esx"`
* `qb-core` when `Config.Framework = "qbcore"`
* Appearance resource (optional but recommended):
* `illenium-appearance` (recommended if available)
* or `esx_skin` + `skinchanger`
* `screenshot-basic` if `Config.Mugshot.enabled = true`

### Installation (Step by Step)

1. Put the resource folder in your server resources:

* Example: `resources/[DXS]/DXS_Multichars`

2. Open `server.cfg` and ensure start order is correct:

```cfg
ensure oxmysql

# Framework (choose one)
ensure es_extended
# ensure qb-core

# Appearance (choose one path)
ensure skinchanger
ensure esx_skin
# ensure illenium-appearance

# Needed only when mugshots are enabled
ensure screenshot-basic

ensure DXS_Multichars
```

3. Add admin ACE permission (optional but recommended for commands):

```cfg
add_ace group.admin dxs_multichars.admin allow
```

4. Configure the script in `config.lua`:

* Set `Config.Framework` to `"esx"`, `"qbcore"`, or `"standalone"`
* Set `Config.Locale` (`en`, `es`, `fr`, `ar`, `ur`)
* Set `Config.CharacterCount`
* Configure spawn points in `Config.Spawn.locations`
* Set appearance provider in `Config.Appearance.provider`
* Confirm mugshot settings in `Config.Mugshot`

5. Start or restart your server.
6. Verify in console:

* No `Config validation failed` errors
* No `oxmysql must be started before dxs_multichars` error
* Character UI opens on player join

### Replacing Old Character Scripts (Very Important)

If you are moving from another multicharacter script, do this to avoid double UI, broken spawn, or duplicate identity flow.

#### Quick Disable/Delete List

Disable these in `server.cfg` first:

* `esx_multicharacter` (or similar ESX multichar script)
* `qb-multicharacter`
* Any custom multichar selector
* Any custom spawn selector that opens its own menu (example: `qb-spawn`)

Disable only if it conflicts:

* `esx_identity` (disable if it opens duplicate identity/registration UI)

Do not disable:

* `oxmysql`
* `es_extended` or `qb-core` (your active framework)
* Your selected appearance scripts (`illenium-appearance` or `esx_skin` + `skinchanger`)

#### Example server.cfg Cleanup

Before (old setup example):

```cfg
ensure esx_multicharacter
ensure qb-spawn
ensure esx_identity
```

After (DXS setup):

```cfg
# ensure esx_multicharacter
# ensure qb-spawn
# ensure esx_identity   # keep disabled only if conflicting
ensure DXS_Multichars
```

1. Disable old character selector resources in `server.cfg`:

* `esx_multicharacter` (or any ESX multichar variant)
* `qb-multicharacter`
* Any custom multichar selector resource

2. Disable old spawn selector resources that open their own spawn UI:

* `qb-spawn`
* custom spawn selector scripts
* any resource that forces spawn UI before this script

3. For ESX servers:

* If `esx_identity` is forcing its own registration UI and conflicts with this character creator, disable `esx_identity`.
* Keep it only if your server specifically depends on it and you have no conflict.

4. Do not remove core dependencies:

* Keep `oxmysql`
* Keep your chosen framework (`es_extended` or `qb-core`)
* Keep your chosen appearance resources

5. Test first, then delete folders:

* First comment out old `ensure` lines and test.
* After successful test, you can permanently delete old resource folders.

### Migration and Existing Data

This script supports two migration paths:

1. Users table migration (`Config.Storage.migrateUsers = true`)

* Reads existing rows from `users` table using:
* `identifier = primaryId`
* or `identifier LIKE 'char%:primaryId'`
* Builds DXS character rows automatically when player opens menu.

2. Legacy JSON migration (`Config.Storage.migrateJson = true`)

* Imports from `data/characters.json`
* Migration runs only when DXS character table is empty
* Optional legacy backup file can be created

Notes:

* Schema is auto-created by the resource at startup.
* Manual SQL file is available at `sql/dxs_multichars.sql` if you want to pre-create tables.

### Database Tables

* `dxs_multichars_characters` (main character data)
* `dxs_multichars_audit` (admin/player action logs)
* `dxs_multichars_portraits` (saved mugshot images)

### Commands

Admin commands:

* `/mc_view [playerId]`
* `/mc_lock [playerId] [slot] [true/false]`
* `/mc_reset [playerId] [slot|all]`
* `/mc_diag`
* `/mc_fixmodels`
* `/mc_rebuildindex`

Player command:

* `/charskin` (name depends on `Config.Appearance.command`)

### Important Config Keys

* `Config.Framework`
* `Config.Locale`
* `Config.CharacterCount`
* `Config.AllowPlayerDelete`
* `Config.Storage.*`
* `Config.Validation.*`
* `Config.Appearance.*`
* `Config.Mugshot.*`
* `Config.Spawn.*`
* `Config.AdminAce`

### Troubleshooting

1. Character menu does not open:

* Check that old multichar/spawn selector scripts are disabled.
* Check console for startup errors.

2. Server says `oxmysql must be started before dxs_multichars`:

* Move `ensure oxmysql` above this resource.

3. Appearance menu does not open:

* For `esx_skin` mode, ensure both `esx_skin` and `skinchanger` are started.
* For `illenium` mode, ensure `illenium-appearance` is started.

4. Mugshots do not save:

* Ensure `screenshot-basic` is started.
* Keep `Config.Mugshot.enabled = true`.

5. ESX identity conflicts:

* Disable `esx_identity` if it opens duplicate registration flow.

### Testing Checklist

Use `TEST_CHECKLIST.md` after installation to confirm create/edit/delete/spawn/appearance/admin flows.