> For the complete documentation index, see [llms.txt](https://izzyshop-1.gitbook.io/izzyshop-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://izzyshop-1.gitbook.io/izzyshop-docs/multicharacter-resources/multicharacter-v4/f.a.q.md).

# F.A.Q

izzy-multicharacterv4 — Frequently Asked Questions (FAQ)

#### How do I install the script?

1. Place the `izzy-multicharacterv4` folder in your `resources` directory.
2. Add to `server.cfg`: `ensure izzy-multicharacterv4`
3. Make sure dependencies are running: `oxmysql`, `qb-core` or `es_extended`
4. Configure `shared/cfg.lua` and `shared/sv_cfg.lua` for your server.
5. If you changed the UI: `cd web` → `npm install` → `npm run build`

#### Which frameworks are supported?

\
QB-Core and ESX are supported. The framework is auto-detected (whichever of `es_extended` or `qb-core` is running). You can also force it manually via `cfg.framework`.

#### I don't use qb-apartments — what should I do?

Remove or comment out this line in `fxmanifest.lua`:

`'@qb-apartments/config.lua',`

Also set `cfg.useQBApartments = false`.

#### I'm getting a `dependency '/assetpacks'` error

This is required for the Tebex escrow package. If you purchased the script from Tebex, you need to install the asset pack on your server. Unofficial/cracked copies often hit this error — use the original package.

### Characters & Login

#### Player gets stuck on a black screen after joining

Possible causes:

* NUI not built (`web/dist` is empty or outdated)
* Loading screen not closing with `manualShutdown = true` → try `cfg.manualShutdown = false`
* Script starts before framework (QB/ESX) loads → check `ensure` order (framework should start first)
* No MySQL connection → check oxmysql logs

#### Characters don't show up / list is empty

* QB: Check `license` match in the `players` table (both `license` and `license2` are supported)
* ESX: Is `cfg.prefixForESX` correct? (usually `"char"`)
* Is oxmysql running?
* Any SQL errors in F8 or server console?

#### Appearance menu doesn't open when creating a new character

Install the appearance script that matches your setup:

| Script              | Status    |
| ------------------- | --------- |
| izzy-appearance     | Supported |
| illenium-appearance | Supported |
| fivem-appearance    | Supported |
| qb-clothing         | Supported |
| rcore\_clothing     | Supported |
| esx\_skin           | Supported |

Make sure the appearance resource starts before multicharacter.

\
Character deletion doesn't work

* `cfg.canDeleteCharacter = true` must be set
* QB: Uses `QBCore.Player.DeleteCharacter` — verify your QB version supports it
* ESX: Deletes directly from `users`; related tables (inventory, vehicles, etc.) may not be cleaned up

<br>

### Spawn & Location

#### Spawn selector doesn't open

* `cfg.useOwnSpawnSelector = true` is required (for Izzy's built-in spawn UI)
* If `false`, an external script is expected: `izzy_spawn`, `izzy-spawn`, or `qb-spawn`
* `client/spawn.lua` has `if not cfg.useOwnSpawnSelector then return end` at the top — when false, Izzy spawn is fully disabled

#### Player spawns underground or floating

* Check `coords` in `cfg.locations`
* With `lastLocation`, the player's saved position may be invalid
* If collision hasn't loaded yet, a short wait before unfreezing can help

#### Houses don't appear in the spawn list

Set `cfg.housing` correctly:

```lua
housing = 'none'           -- no houses
housing = 'qb-houses'      -- qb-houses
housing = 'ps-housing'     -- ps-housing
housing = 'qbx_properties' -- qbx_properties
```

The matching housing script must also be installed and running.

<br>

### Slots & Tebex

#### How many character slots are there?

* Default: `cfg.defaultFreeSlotAmount = 1`
* Maximum: `cfg.maxSlotAmount = 5`
* Extra slots: via Tebex purchase code or admin-generated code

#### Redeem / code system doesn't work

Checklist:

1. `shared/sv_cfg.lua` → are `tebexSecret` and `packageId` correct?
2. Do `codes.json`, `slots.json`, and `transactions.json` exist and are they writable?
3. Admin code: `/createCode CODE123` (requires authorized license)
4. Known bug: `client/client.lua` redeem callback incorrectly calls `deleteCharacter` instead of `isKeyValid` — code validation may be broken until this is fixed

#### Tebex purchase code doesn't work automatically

* Is the Tebex Plugin API secret key correct?
* Does `packageId` match the purchased package ID?
* If the code was already used, it's recorded in `transactions.json` — it can't be reused

#### How do I create an admin code?

```lua
/createCode YOURCODE
```

Permission: server console or a license listed in `cfg.admins`.

Get your license: F8 → `status`, or from the server console identifier list.

### UI & Appearance

#### UI doesn't show at all

* Do `web/dist/index.html` and asset files exist?
* Did you run `npm run build` after changing source code?
* Is `ui_page 'web/dist/index.html'` correct in fxmanifest?
* F8 → NUI devtools — any JS errors?

#### Background keeps flickering black

Set `cfg.disableBackgroundBlur = true`. The blur effect can cause flickering on some systems.

#### How do I change colors?

`shared/cfg.lua` → `lScreenColors`:

```lua
lScreenColors = {
    primary = '#ABEF1B',
    secondary = '#219510',
    background = '#0a0a0f',
    overlay = 'rgba(0,0,0,0.4)'
}
```

No UI rebuild needed; config is sent to NUI at runtime.

\
Is there Turkish / other language support?

Default is `cfg.locale = 'en'`. Add a `'tr'` (or other) block under `cfg.locales` and set `cfg.locale = 'tr'`.

### Commands & Admin

#### What does the `/logout` command do?

Logs the player out of the framework and returns them to the multicharacter screen. Useful for admin panels or testing.

#### How do I open the multichar screen from another script?

```lua
-- Server
TriggerClientEvent('izzy-multicharacterv4:open', playerId)

-- Client
TriggerEvent('izzy-multicharacterv4:open')
```

#### How do I open the spawn selector externally?

```lua
exports['izzy-multicharacterv4']:open()
-- or
TriggerClientEvent('izzy-multicharacterv4:openSpawn', playerId)
```

### ESX Specific

#### What is the character prefix for?

ESX identifier format: `char1:licensehash`, `char2:licensehash`, etc.\
`cfg.prefixForESX = "char"` — don't change this unless it matches your ESX multichar setup.

#### Nationality always shows as USA on ESX

The code hardcodes `data.nationality = 'USA'` on the ESX side (`shared/shared.lua`). Edit that line to customize it.

### QB Specific

#### Starter items aren't given

* `cfg.giveStarterItems = true` must be set
* Item names in `cfg.starterItems` must match `qb-core/shared/items.lua`
* If items are given before the character is fully created, it may be a timing issue

#### Conflict with qb-spawn

* Either `cfg.useOwnSpawnSelector = true` (Izzy spawn)
* Or `false` + external qb-spawn
* Don't run both — you'll get duplicate spawn UIs

### Performance & Technical

#### Script uses high CPU

* Spawn camera animation (`doCamera`) uses an intensive loop — expected but worth noting
* `cfg.camScenarioDuration` is lowered (800ms) — good for performance
* Some `Wait(0)` loops exist (DoF effect, etc.)

#### What are routing buckets for?

While on the multicharacter screen, the player is placed in a random bucket so other players can't see them. After selecting a character, they return to bucket 0 (the real world).

#### What happens if JSON files are deleted?

| File                | Effect                                            |
| ------------------- | ------------------------------------------------- |
| `slots.json`        | All extra slots reset                             |
| `codes.json`        | Admin codes removed                               |
| `transactions.json` | Used-code records gone (same code can be reused!) |

Back these up regularly.

### Error Messages

\
`Model(...) is not valid!`

Character skin model is invalid or failed to load. Check the `model` value in the `playerskins` table.

#### `unknown framework`

Neither ESX nor QB was detected. Make sure the framework resource is started and named correctly.

#### `Error: Missing translation for "..."`

The selected language (`cfg.locale`) is missing that key in `cfg.locales`. Add the missing translation.

\
`Event not Found!` (callback timeout)

Server callback didn't respond within 5 seconds. MySQL slow, framework not ready, or server event not registered.

### Security

#### Someone else's license is in the admin list — what should I do?

Remove unknown licenses from `cfg.admins` and add your own:

```lua
admins = {
    ['license:YOUR_LICENSE_HASH'] = true,
}
```

#### Should I share my Tebex secret key?

No. Keep `tebexSecret` in `sv_cfg.lua` private; don't commit it to a public repo.

### Quick troubleshooting checklist

* [ ] Is oxmysql running?
* [ ] Does qb-core / es\_extended start before this resource?
* [ ] Is web/dist built?
* [ ] Is cfg.lua configured for your server?
* [ ] Is an appearance script installed?
* [ ] Are housing / apartments settings correct?
* [ ] Checked F8 + server console for errors?
* [ ] Are JSON files writable?

If you're hitting a specific error, send the console log or a screenshot and I can walk through a fix. I can also patch the redeem bug if you want that done.


---

# 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://izzyshop-1.gitbook.io/izzyshop-docs/multicharacter-resources/multicharacter-v4/f.a.q.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.