Before You Begin#
Appearance replaces every clothing, barber, tattoo and character menu on your server. Before installing, check that your server meets the requirements below.
Requirement | Status | Notes |
|---|---|---|
| Required | Database access. The catalogue schema installs itself. |
| Required | Callbacks, commands, notifications and shared helpers. |
Framework | Required |
|
Target | Optional |
|
| Optional | Only to photograph your own add-on clothing. The shipped catalogue is already photographed. |
| Optional | The green-screen studio the photo run teleports to. Ships with the script. Needed whenever you take photos. |
| Optional | Locks the inventory while a player is in the clothing menu. |
| Optional | Notifications, progress bars and the zone prompt. Falls back to ox_lib. |
| Optional | Adds its own runtime tattoos on top of Appearance's. Appearance fires a hook after every tattoo change so the two never fight over the ped. See Tattoo Creator. |
| Optional | Clothing you design and publish with it is detected as an add-on pack, so it photographs into the catalogue like any other. See Clothing Creator. |
Everything framework- or third-party-specific sits behind a small bridge file, and the right one is chosen by looking at what is already started:
Layer | Detection |
|---|---|
Framework |
|
Target |
|
Inventory |
|
Tattoos |
|
Every optional integration degrades silently. If a resource is missing, that feature falls back to the built-in behaviour and nothing errors.
github.comReleases · overextended/oxmysqlMySQL resource for FXServer.github.comReleases · overextended/ox_libA FiveM resource and script library for Lua and JS.Downloading Appearance#
After purchasing Appearance, the resource is automatically linked to your CFX Portal account — there is no key to enter and nothing to activate.
Sign in to the CFX Portal with the same account used during checkout, open Granted Assets and download the latest build.
After extracting the download you should have:
qs-appearance/
├── config/ -- what you may edit
├── custom/ -- the bridges to your framework
├── locales/ -- 41 translations
├── sql/ -- the catalogue schema and its seeds, applied for you
└── web/ -- the compiled interface
greenscreen-map/ -- the photo studio, only needed while taking photos
[sql]/main.sql -- the player outfit and skin tablesThe folder must be named
qs-appearance. Its exports, its events and thenui://paths the interface loads its images from all use that name, and the resource refuses to start under any other.
Installing the Resource#
Move the qs-appearance folder into your server's resources directory. It can live anywhere inside it:
resources/
└── [qs]/
└── qs-appearance/Then open your server.cfg and make sure every dependency starts before it:
ensure oxmysql
ensure ox_lib
# Framework — only one of these
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Optional
ensure ox_target
ensure screenshot-basic
ensure greenscreen-map
ensure qs-appearanceThe loading order matters. Detection only sees resources that are already started, so a framework or target started after Appearance is invisible to it. Clothing packs are the exception — they are scanned on demand, not at boot — but an add-on pack that depends on an asset pack still needs /assetpacks started.
The Database#
There are two layers. One installs itself; the other you import once.
The catalogue — installed for you#
There is no catalogue SQL to import. On the first start Appearance creates its own tables and fills them from the shipped seed: about 29,000 clothing rows, 1,009 ped models, 2,575 glove variants, 89 face presets, 7,568 top-to-hands mappings and 29 ready-made stores.
Tables | Hold |
|---|---|
| The clothing catalogue: one row per garment with its label, price, photo, collection, colours, tags and addon/replaced flags. |
| The shops you draw in game, and what each one has in stock per ped model. |
| The peds a player may choose, their photos and which of them are hidden. |
| Hands grouped into glove categories, and the variants inside each one. |
| Which hands each top wears, so sleeves and arms match. |
| The mother and father faces offered during character creation. |
| Bookkeeping: which schema and which catalogue version are applied. |
It only does work when something changed. On a normal start the console prints Schema up-to-date and Catalog seed up-to-date and nothing is written.
The seed is an upsert over every shipped row, so when a new catalogue version ships it resets the price, label and photo of shipped items and of the 29 shipped stores. Peds you hid and photos you captured yourself are detected and put back. Player data — saved appearances and outfits — is never touched.
Player outfits and skins — import once#
The tables that hold what your players save are not created automatically. Import [sql]/main.sql by hand, once, before the first start. It creates player_outfits, playerskins, clothing_player_outfits and clothing_job_outfits.
Claiming Admin Access#
The creator draws shops, edits the catalogue, deletes rows and photographs clothing, so it is behind an admin check. There is no separate ace for it — it reuses your framework's own idea of staff, and every creator action is re-checked on the server, not just hidden in the interface.
The player's group must be admin or superadmin.
UPDATE users SET `group` = 'superadmin' WHERE identifier = 'char1:xxxxxxxx';The god or admin permission, or the command ace — whichever you already use for staff.
add_principal identifier.license:xxxxxxxx group.adminThe clothing menu for another player is gated separately: /appearance <id> exists only when Config.EnablePedMenu is on, and is restricted to Config.PedMenuGroup — group.admin out of the box.
add_ace group.admin command.appearance allowConfiguring the Resource#
Most of what used to live in files is now edited in game. Shops, stock, ped models, glove categories, catalogue rows, labels, prices and photos are all database rows managed from the creator and applied without a restart. The files hold the rest.
File | Contents |
|---|---|
| Detection overrides, the language, the menu's behaviour, zones and blips, the target settings, body scale, the photo pipeline and the debug switch. |
| Which jobs may build shops, where the clothing rooms are, the fallback outfit that stops a naked ped glitching, and what a brand-new character spawns wearing. |
| Whether clothing costs money at all, and the entry price of the clothing store, barber, surgeon and tattooist. |
| Clothing restricted per gender, optionally allowed only to named jobs — police uniforms and faction gear. |
| The tattoo list, grouped by body zone, with a price per tattoo. |
| Legacy. Peds are managed in the creator now. Anything left here is imported once on start and can then only be hidden, never deleted. Leave it empty on a new install. |
| Your FiveManage token, used only when photographing your own add-on clothing. A placeholder ships in the file — replace it with your own. |
| Development only. Points the photo pipeline at a local image server instead of FiveManage. |
The values worth reviewing before you open the server:
Config.Locale = 'en' -- any of the 41 files in locales/
Config.Debug = false -- ships TRUE; turn it off in production
Config.UseTarget = false -- true to enter shops with ox_target / qb-target
Config.UsePricing = true -- false makes every garment free
Config.ShowNearestShopOnly = false -- true thins 29 blips down to the closest of each type
Config.EnableScale = false -- player height; experimental, affects hitboxes
Config.ShareOutfitCost = 5000 -- what sharing an outfit with a nearby player costs
Config.ImageSaver.enable = false -- ships TRUE; see the warning belowVerifying the Installation#
Restart the server and read the console. A healthy first start looks like this:
[INFO] Successfully loaded the framework. esx
[qs-appearance] Schema applied (version=1)
[qs-appearance] Catalog seed not found, applying initial seed...
[qs-appearance] Catalog seed applied: 40296 rows across 86 chunks in 14820ms
You are using the latest version of qs-appearance!Every start after that is quiet: Schema up-to-date and Catalog seed up-to-date, with no writes. If the framework line is missing, the resource could not find a core and nothing else will work.
Then join your server and work through the first loop:
Walk into a clothing store
Twenty-nine shops are already on the map with blips. Step into the zone, press
Eon the prompt and pay the entry fee. The catalogue should open full of photographs, not empty squares.Buy something and save an outfit
Click a few garments into the basket, check out with Cash or Bank, then use Save Current Outfit. Reconnect — you should come back wearing it. If you do not, the player tables were never imported.
Open the creator
/appearance-creatoropens on Shop Creator with all 29 shops listed. If you are told you have no permission, your admin group is not one of the two the bridge recognises.
Nothing needs a restart from here on. New shops, hidden peds, edited prices, stock and catalogue photos all take effect live. Read Usage next.