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


---

# Agent Instructions: 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:

```
GET https://dxs-scripts.gitbook.io/home/documentation/fivem/dxs-multi-character.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.