> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/core/cuxial-appearance/configuration.md). # Configuration Every option of Cuxial Appearance explained: config, shops, menus, models, restrictions and photo studio. Behaviour lives in `shared/config.lua`; shops, menus, models and restrictions live in the `data` folder. Restart the resource after changing a file. {% hint style="warning" %} Some blocks are also editable from the staff panel: `prices`, `secondHand`, `ui.menuAlpha`, and part of `wardrobe` and `trimmer`. Their values are stored in the database on first start, and from then on the database wins over `shared/config.lua`. Change them in the panel. The reset button of the panel brings back the values of the file. {% endhint %} ## General | Option | Type | Default | What it does | | ------- | ------- | ------- | -------------------------------------------------------------------------------------------------- | | `debug` | boolean | `false` | Prints traces to the console. Also enabled by setting the convar `cuxial_appearance_debug` to `1`. | ## Interface · `ui` | Option | Type | Default | What it does | | ----------- | ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------- | | `accent` | string (hex) | configurable | Accent colour of the interface. | | `menuAlpha` | number | `0.85` | Default background opacity of the menu, from `0.4` to `1`. Each player can adjust their own. Editable from the panel. | ## Staff and logs · `admin`, `logs` | Option | Type | Default | What it does | | ------------------ | ------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `admin.permission` | string | `'admin'` | Permission of your framework that makes a player staff for this script. See [Commands & permissions](/scripts/core/cuxial-appearance/commands.md). | | `logs.enabled` | boolean | `true` | `false` turns the Discord logs off. | | `logs.convar` | string | `'cuxial_appearance_webhook'` | Name of the convar that holds the webhook. | ## Commands · `commands` Each entry has a `name` and, for staff commands, `restricted`. | Option | Type | Default | What it does | | ---------------------- | ----------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `.name` | string | see [Commands & permissions](/scripts/core/cuxial-appearance/commands.md) | Name of the command. An empty name disables the command. | | `.restricted` | boolean \| string | `false` | ACE restriction passed to `ox_lib`, for example `'group.admin'`. `false` adds none: staff commands still check `admin.permission`. | ## Shop menu · `menu` | Option | Type | Default | What it does | | ----------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------- | | `openControl` | string | `'E'` | Default key that opens the shop you are standing in. Each player can rebind it in the GTA key settings. | | `textUi` | boolean | `true` | `true` shows the on-screen prompt when entering a shop. `false` shows nothing; the key still works. | | `alwaysKeepProps` | boolean | `true` | `true` keeps hats and glasses on when the player takes damage. | | `automaticFade` | boolean | `false` | `true` adds the matching hair fade decoration when the hairstyle changes. Only with the built-in tattoos. | ## Prices · `prices` Editable from the panel. | Option | Type | Default | What it does | | ------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | `outfitPrice` | number | `100` | Price of saving an outfit or a look outside a shop. Inside a shop, saving an outfit costs the price of that shop. | | `outfitBagPrice` | number | `50` | Price of turning a saved outfit into an outfit item. | | `outfitSetConsume` | boolean | `false` | `true` removes the outfit item when it is used. `false` keeps it. | | `maxOutfits` | number | `30` | Saved outfits per character. From 1 to 200. | ## Outfits and outfit bag · `outfits` | Option | Type | Default | What it does | | ------------------ | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `outfitCodeLength` | number | `10` | Length of the share codes. From 4 to 32. | | `setItem` | string | `'cuxial_outfit'` | Item created when an outfit is packed. | | `bagItem` | string | `'cuxial_outfitbag'` | Item of the outfit bag. | | `bagSlots` | number | `5` | Outfits a bag holds. | | `bagStorage` | string | `'citizenid'` | `'citizenid'` = the outfits belong to the character, whatever bag they use. `'item'` = the outfits travel inside the item and change hands with it. | | `bagProp` | string | `'prop_big_bag_01'` | Model of the bag on the ground. | | `bagPlaceAnim` | table | see file | Animation played when placing the bag: `dict`, `anim` and `ms`. | | `bagOpenAnim` | table | see file | Animation played while the bag is open: `dict` and `anim`. | ## Wardrobe · `wardrobe` | Option | Type | Default | What it does | | ---------------------- | --------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `item` | string | `'cuxial_clothing'` | Item a garment turns into when it is taken off. | | `legacyItem` | string | `'clothing'` | Older garment item that is still accepted: it can be worn and sold, never created. | | `inventory` | boolean | convar | Inventory mode. Read from the convar `cuxial_appearance:inventory` (`1` = on). Do not edit it here. | | `panel.exclude` | string\[] | `{ 'bags' }` | Pieces left out of the clothing panel and of purchase returns. | | `panel.anim` | boolean | `true` | `true` plays the dressing animation when using the panel. | | `purchaseReturns` | boolean | `true` | `true` hands back, as items, the garments replaced by a purchase. Inventory mode only. Editable from the panel. | | `purchase.destination` | string | `'bag_first'` | Where returned garments go: `'bag_first'` = a garment bag with room, then the inventory; `'inventory_first'` = the other way round. Editable from the panel. | | `bag.item` | string | `'cuxial_garmentbag'` | Item of the garment bag. | | `bag.price` | number | `50` | Price of a new garment bag bought with a purchase. Editable from the panel. | | `bag.slots` | number | `12` | Slots of a garment bag. | | `search.pieces` | string\[] | see file | Pieces that can be taken from another player in a body search. Editable from the panel. | | `search.duration` | number | `2000` | Milliseconds each piece takes to remove in a search. From 500 to 10000. Editable from the panel. | Piece names used across the config: `hat`, `glasses`, `ears`, `mask`, `chain`, `tshirt`, `kevlar`, `jackets`, `gloves`, `watch`, `bracelet`, `decals`, `bags`, `legs`, `shoes`. ## Second hand · `secondHand` Editable from the panel. | Option | Type | Default | What it does | | ------------------ | ------ | -------- | ------------------------------------------------------------------------------- | | `payout` | number | `0.35` | Share of the base price the shop pays. From `0.05` to `1`. | | `collectionFactor` | number | `1.3` | Multiplier for garments that belong to an add-on collection. From `0.5` to `5`. | | `account` | string | `'cash'` | Where the money goes: `'cash'` or `'bank'`. | | `maxPerSale` | number | `20` | Garments sold in one go. From 1 to 100. | | `basePrice` | table | see file | Base price of each piece. A piece at `0` is not bought. | The amount paid for a garment is `basePrice × payout`, times `collectionFactor` for collection garments. ## Trimmer · `trimmer` | Option | Type | Default | What it does | | ----------------- | ------ | ------------------ | -------------------------------------------------------------------------------------- | | `item` | string | `'cuxial_trimmer'` | Item of the trimmer. | | `range` | number | `2.5` | Metres within which the nearest player is picked. Editable from the panel. | | `duration` | number | `10000` | Milliseconds the shave takes. Editable from the panel. | | `hairLockMinutes` | number | `20` | Minutes the shaved player cannot change hair. `0` = no lock. Editable from the panel. | | `emote` | string | see file | Command of the paired emote of `cuxial_emotes` played during the shave. | | `models` | table | freemode models | Ped models that can be shaved, each mapped to `'male'` or `'female'`. | | `bald` | table | `0` / `0` | Hair `drawable` and `texture` applied by a trimmer without a custom style, per gender. | ## Photo studio · `photos` | Option | Type | Default | What it does | | -------------------------------------- | ------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `resource` | string | `'cuxial_appearance_photos'` | Resource where the photos are saved and served from. | | `captureResource` | string | `'screencapture'` | Capture resource tried first. `screencapture` and `screenshot-basic` are tried after it. | | `size` | number | `256` | Side of each photo, in pixels. | | `quality` | number | `0.86` | Image quality, from `0` to `1`. | | `chroma` | string | `'magenta'` | Background colour removed from the photo: `'magenta'` or `'green'`. | | `textures` | boolean | `false` | `true` also photographs every texture of each garment. Much slower and heavier. | | `bucket` | number | `998` | Routing bucket the staff member is moved to while the studio is open. | | `studio` | table | see file | `coords` and `heading` of the spot where the photos are taken. | | `waitApply`, `waitCapture`, `waitProp` | number | `350`, `120`, `400` | Milliseconds waited after applying a garment, before the capture and after a prop. Raise them if photos come out with the previous garment. | | `uploadRate` | number | `1000000` | Transfer rate, in bytes per second, used to send each photo to the server. | ## Compatibility and NPC pool · `compat`, `npcPool` | Option | Type | Default | What it does | | -------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `compat.legacySkins` | boolean | `true` | `true` imports a character's old skin the first time it is needed, when it has no saved appearance yet. See the migration command in [Commands & permissions](/scripts/core/cuxial-appearance/commands.md). | | `npcPool.activeDays` | number | `30` | Only appearances saved in the last days feed the pool of random looks. If none qualifies, all are used. | | `npcPool.size` | number | `60` | Appearances kept in the pool. | The pool is only used through the `GetRandomAppearances` export. ## ACE restrictions · `aces` Hides models or garments from everyone who lacks an ACE permission. Empty by default. {% code title="shared/config.lua" %} ```lua aces = { -- ped model -> ACE models = { ['a_m_y_hipster_01'] = 'appearance.vip', }, -- drawable category -> { [drawable] = ACE } drawables = { masks = { [120] = 'appearance.vip' }, }, -- prop category -> { [prop] = ACE } props = { hats = { [45] = 'appearance.vip' }, }, }, ``` {% endcode %} Drawable categories: `face`, `masks`, `hair`, `torsos`, `legs`, `bags`, `shoes`, `neck`, `shirts`, `vest`, `decals`, `jackets`. Prop categories: `hats`, `glasses`, `earrings`, `mouth`, `lhand`, `rhand`, `watches`, `bracelets`. A model listed in `aces.models` can only be chosen and saved by players who hold the permission. Garments in `aces` are also checked on the server: see [Restrictions](/scripts/core/cuxial-appearance/features.md#restrictions). ## Data files ### `data/shops.lua` The default shops. Each entry has `label`, `type` (`clothing`, `barber`, `surgeon`, `appearance` or `resale`), `price`, `blip` (`1` or `0`), `thickness` (height of the zone), `jobs` (empty = public) and `points` (the corners of the polygon, at least three). {% hint style="warning" %} This file is only read when the shop table is empty, on first start. After that, shops are managed from the staff panel. The panel can import the default shops that are missing; it never touches the existing ones. {% endhint %} ### `data/menus.lua` The tabs of each menu type and whether it can be closed without saving (`allowExit`). Available tabs: `heritage`, `hair`, `clothes`, `accessories`, `face`, `makeup`, `outfits`. The tattoo tab is added to the `appearance` menu on its own when the built-in tattoos are active. ### `data/models.lua` The ped models offered in the heritage tab. They are also the models a player is allowed to save. The file lists the two freemode models: add your own add-on peds after them. ### `data/blacklist.lua` Garments and models hidden from the menu. | Block | What it does | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `base` | Hidden from everyone. For each category, `values` lists whole drawables and `textures` lists textures of a drawable: `textures = { [194] = { 0, 1 } }`. | | `jobs`, `gangs` | Named groups of entries. The `jobs` groups are hidden from everyone and lifted inside a shop limited to jobs, for players who have one of those jobs. The `gangs` groups apply to everyone who does not belong to that gang: its members can wear those garments. A group can also carry `male` and `female` sub-blocks. | | `whitelist` | Models, drawables or props reserved to the character identifiers listed. Everyone else does not see them. | The `jobs` and `gangs` entries shipped in the file are examples. The `whitelist` block ships empty, with commented examples; garments reserved to specific characters are easier to manage from the whitelist tab of the staff panel. The blacklist is enforced on the server as well as in the menu. See [Restrictions](/scripts/core/cuxial-appearance/features.md#restrictions). ### `data/wardrobe.lua` The pieces of the wardrobe, the garment each gender wears when a piece is taken off (`defaults`) and the animation of each piece (`anims`). Change `defaults` if your server uses different "naked" drawables. ### `data/photos.lua` Camera presets, lights and backdrop of the photo studio. Cameras can also be adjusted and saved live from the studio itself. ### `data/tattoos.lua`, `data/hairdecorations.lua` The built-in tattoo list and the hair fade decorations. Edit them only to add your own tattoo packs. ## Common changes **Free dressing room for the police.** Create or edit the shop in the staff panel: type `appearance`, price `0`, and add the job. No file to edit. **Pay second-hand sales into the bank.** In the staff panel, settings, second hand: account `bank`. **Rename the wardrobe command.** {% code title="shared/config.lua" %} ```lua commands = { wardrobe = { name = 'wardrobe' }, }, ``` {% endcode %} Keep the other entries of `commands` as they are: an entry that is removed disables its command. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cuxial.com/scripts/core/cuxial-appearance/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.