# qb-clothing: appearance, outfits and persistence

`qb-clothing` is the QBCore appearance resource for character editing, clothing shops, barber shops and saved outfits. This guide follows [upstream commit 8cca400](https://github.com/qbcore-fivem/qb-clothing/tree/8cca4009dd473ab30c30e443ecad50830b816ed7); custom appearance replacements may expose completely different APIs.

## Installation

1. Start `qb-core` and `oxmysql`; the [manifest](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/fxmanifest.lua) also imports `PolyZone` client modules.
2. Install `qb-clothing` with its bundled `html`, Lua files, config and locales. Do not copy only the UI folder.
3. Import the upstream [`qb-clothing.sql`](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/qb-clothing.sql) into a **backed-up staging database** before replacing another appearance script.
4. Test initial character creation, skin save/reload, job outfit selection, disconnect/reconnect and switching characters.

## Actual database tables

| Table | Relevant columns | Use |
| --- | --- | --- |
| `playerskins` | `citizenid`, `model`, `skin`, `active` | Character appearance data |
| `player_outfits` | `citizenid`, `outfitname`, `model`, `skin`, `outfitId` | Named saved outfits |

Both tables are present in upstream SQL. A generic `clothing_stores`, `clothing_items` or `player_clothing` migration is **not** part of this resource. It is unsafe to paste such a schema on top of existing player appearance data.

The server loads the active row from `playerskins` for the current citizen ID and sends the model/skin to the client. Outfit save/delete flows use `player_outfits`. The [source](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/server.lua) uses parameterized queries.

## Client exports: what actually exists?

From the [client implementation](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/client.lua):

| Export | Usage / important boundary |
| --- | --- |
| `reloadSkin` | Re-applies appearance through the resource's reload flow |
| `IsCreatingCharacter` | Returns whether its character-creation UI is active |
| `getOutfits` | `getOutfits(gradeLevel, data)` opens a job outfit UI; expects a compatible gender/grade outfit data table, **not** a plain return array |

For example, an **in-client** guard can check whether the clothing creator is open:

~~~lua filename="client.lua"
if exports['qb-clothing']:IsCreatingCharacter() then
    print('Clothing creator is already active')
else
    TriggerEvent('qb-clothing:client:openMenu')
end
~~~

The upstream revision does **not** export `OpenClothingMenu`, `SaveOutfit`, `LoadOutfit` or `GetPlayerOutfits`. Do not replace the actual client event/exports with those invented wrappers.

## Events and callbacks

These are implementation-defined handlers, not a promise of an external stable API:

| Side | Name | Role |
| --- | --- | --- |
| Client | `qb-clothing:client:openMenu` | Opens appearance editing |
| Client | `qb-clothes:client:CreateFirstCharacter` | Opens initial character creator |
| Client | `qb-clothes:loadSkin` | Applies server-delivered skin |
| Client | `qb-clothing:client:reloadOutfits` | Refreshes outfit UI |
| Server | `qb-clothing:saveSkin` | Saves character skin |
| Server | `qb-clothes:loadPlayerSkin` | Reads saved skin for a character |
| Server | `qb-clothes:saveOutfit` | Writes an outfit row |
| Server | `qb-clothing:server:removeOutfit` | Deletes an owned outfit row |
| Server callback | `qb-clothing:server:getOutfits` | Loads saved outfits for the caller |

The historical `qb-clothes` prefix is used for some **real** events in this revision. Do not normalize all events to `qb-clothing:...` without checking their registration.

## Configuration and compatibility

`config.lua` contains large `Config.WomanPlayerModels` and `Config.ManPlayerModels` lists plus appearance/shop settings. Compare the **actual keys** in your installed version before copying someone else's menu/store config.

A replacement like `illenium-appearance` or `fivem-appearance` may have a different database schema, creator API and character-login integration. Choose exactly one authoritative appearance implementation and plan a data migration before switching.

## Troubleshooting

| Symptom | Investigate |
| --- | --- |
| Skin resets after rejoin | Character ID, active `playerskins` row, SQL import and `qb-clothes:loadPlayerSkin` flow |
| Outfits vanish | `player_outfits` schema, caller citizen ID, save callback and SQL errors |
| Character editor fails to open | Client event registration, NUI files and first-character flow |
| Error involving PolyZone | Dependency loading and manifest imports |
| No such export `OpenClothingMenu` | Not an export in this upstream; use a verified client event or a wrapper in your own resource |
| Appearance breaks after script replacement | Compare schema, model/skin serialization and login lifecycle in a staging copy |

## Update checklist

1. Pin the server's `qb-clothing` commit and installed appearance/inventory/character dependencies.
2. Diff `config.lua` and the upstream SQL against local customizations.
3. Test initial skin, outfit save/remove, job outfits and reconnect with **two different characters**.
4. Never run an unrelated example `CREATE TABLE` over live player appearance data.

If you need more garments rather than a different clothing menu, compare
[clothing packs on RPScripts](https://rpscripts.net/product-category/assets/clothes/) by the components and
slot ranges they stream. RPScripts and qbcore.net are operated by the same owner.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-clothing/tree/8cca4009dd473ab30c30e443ecad50830b816ed7) · [Manifest](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/fxmanifest.lua) · [Client exports and events](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/client.lua) · [Server handlers](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/server.lua) · [SQL schema](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/qb-clothing.sql)

For the login/spawn sequence see [qb-multicharacter](/docs/resources/qb-multicharacter).
