> 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-v5/f.a.q.md). # F.A.Q izzy-multicharacterv5 — Frequently Asked Questions (FAQ) ### Installation & General #### How do I install the script? 1. Place the `izzy-multicharacterv5` folder in your `resources` directory. 2. Add to `server.cfg`: `ensure izzy-multicharacterv5` 3. Make sure dependencies are running: `oxmysql`, `qb-core` or `es_extended` 4. Configure `shared/cfg.lua` and `server/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`: ```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. ### 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 * No MySQL connection → check oxmysql logs * F8 → NUI devtools — any JS errors? #### 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 | 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` * ESX: Deletes from `users`; related tables (inventory, vehicles, etc.) may not be cleaned up #### "Fill all parts" error when creating a character All fields must be filled: first name, last name, date of birth, gender (nationality is also required on QB). ### Slots & Tebex #### How many character slots are there? * Default: `cfg.defaultFreeSlotAmount = 2` * Maximum: `cfg.maxSlotAmount = 4` * Extra slots: via Tebex purchase code or admin-generated code #### How do I unlock a slot? 1. Click a locked slot in the character slider 2. The Unlock Modal opens 3. Enter the code → if validation succeeds, the slot is unlocked #### Code system doesn't work 1. `server/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. Is your license listed in `cfg.admins`? #### "This code has been used before" error The code was already used and is recorded in `transactions.json`. It cannot be reused. *** #### "This code was not found" error The code is invalid, not found via the Tebex API, or missing from `codes.json`. #### Tebex purchase code doesn't work automatically * Is the Tebex Plugin API secret key correct? * Does `packageId` match the purchased package ID? * If the Tebex API isn't responding, test manually with `/createCode` #### 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. ### Spawn & Location #### Spawn selector doesn't open * `cfg.useOwnSpawnSelector = true` is required * If `false`, an external script is expected: `izzy_spawn`, `izzy-spawn`, or `qb-spawn` * When `useOwnSpawnSelector = false`, Izzy spawn is disabled at the top of `client/spawn.lua` #### How does spawning work? Two-step system: 1. First click: Camera moves to the location, character is previewed 2. Second click: Spawn is confirmed and the player enters the game If spawn doesn't happen on the first click, that's normal — press Select Spawn a second time. #### 3D map markers don't show * Locations are displayed on the map while the spawn page is open * `coords` values in `cfg.locations` must be valid * For `lastLocation`, the player must have a saved position #### 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. #### There's a delay of a few seconds after spawning The script waits for the camera transition animation to finish. Duration can be adjusted via `cfg.cameraDurationSpawn` (default 2500ms). #### Player spawns underground or floating * Check `coords` in `cfg.locations` * With `lastLocation`, the saved position may be invalid ### 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? * After `npm install`, are `react-slick` and `slick-carousel` installed? * F8 → NUI devtools — any JS errors? #### How do I change colors? `shared/cfg.lua` → `colors`: ```lua colors = { primary = '#8FD733', secondary = '#43993E', tertiary = '#83B93A' } ``` No UI rebuild needed; config is sent to NUI at runtime. \ How do I set the minimum character age? ```lua minimumAge = 18 ``` The date of birth picker limits the maximum date based on this age. #### 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'`. The locale structure is nested (e.g. `header.title`, `unlockModal.title`). ### Commands & Admin #### What does the `/logout` command do? Logs the player out of the framework and returns them to the multicharacter screen. #### How do I open the multichar screen from another script? ```lua -- Server TriggerClientEvent('izzy-multicharacterv5:open', playerId) -- Client TriggerEvent('izzy-multicharacterv5:open') ``` #### How do I open the spawn selector externally? ```lua exports['izzy-multicharacterv5']:open() -- or TriggerClientEvent('izzy-multicharacterv5:openSpawn', playerId) ``` (`cfg.useOwnSpawnSelector = true` required) #### Compatibility with scripts expecting qb-spawn ```lua TriggerEvent('qb-spawn:client:setupSpawns', data, isNew, apartments) ``` The script listens for this and opens its own spawn UI. ### ESX Specific #### What is the character prefix for? ESX identifier format: `char1:licensehash`, `char2:licensehash`, etc.\ `cfg.prefixForESX = "char"` — must match your ESX multichar setup. #### Nationality always shows as USA on ESX The code hardcodes `nationality = 'USA'` on the ESX side. Edit the relevant line in `shared/shared.lua` 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` *** #### 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 #### 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. #### 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. *** #### `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 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 `server/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? * [ ] Are cfg.lua + sv\_cfg.lua configured for your server? * [ ] Is an appearance script installed? * [ ] Are housing / apartments settings correct? * [ ] Is it known that spawn requires two confirmations? * [ ] 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 we can walk through a fix step by step. --- # 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-v5/f.a.q.md?ask=&goal= ``` `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.