> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Where the appearance config lives and what the Awoken rework adds.

The Awoken build is a **visual & UX rework** of illenium-appearance - the script logic, database schema, shops, outfits and exports are all inherited unchanged. This page is the map: the config files, the common knobs, and links to the dedicated pages for the bigger structures.

## Where the config lives

All settings are plain Lua in the resource root - edit, save, `ensure illenium-appearance`. No build step.

| File                   | What's in it                                                                                    |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| `shared/config.lua`    | Main config - costs, shops, blips, peds, target, toggles, outfits, image previews.              |
| `shared/theme.lua`     | Accent colour and UI themes. See [Theming](/resources/awoken-appearance/configuration/theming). |
| `shared/tattoos.lua`   | The tattoo catalogue (per-zone, per-gender hashes).                                             |
| `shared/peds.lua`      | Selectable ped models for the ped menu / character creator.                                     |
| `shared/blacklist.lua` | Drawables/props to hide, gated behind ace permissions.                                          |
| `locales/*.lua`        | UI text and notification strings.                                                               |

The bigger structures each have their own page:

* [Stores & Locations](/resources/awoken-appearance/configuration/stores) - shop zones, map blips, target interaction, and job clothing rooms.
* [Job & Gang Outfits](/resources/awoken-appearance/configuration/outfits) - preset uniforms per job/gang, locked by grade.
* [Character Creator](/resources/awoken-appearance/configuration/character-creator) - editable sections, selectable peds, and starting clothes.

And the rework's added features:

* [Image Previews](/resources/awoken-appearance/configuration/image-previews) - real thumbnails for every clothing, hair, prop and overlay option, instead of blind number steppers.
* [Theming](/resources/awoken-appearance/configuration/theming) - the accent colour and the cross-resource `awoken:primaryColor` convar.
* [The Recorder](/resources/awoken-appearance/image-recorder) - the companion tool that generates the preview thumbnails.

<Info>
  Everything the rework adds is layered **on top of** stock illenium-appearance - your existing skins, outfits, stores and exports keep working unchanged.
</Info>

## Image previews

When enabled, the UI shows a thumbnail for each option instead of a number stepper. Missing images fall back to the stepper automatically.

```lua shared/config.lua theme={"dark"}
Config.UseImagePreviews = true       -- master toggle (on by default)
Config.ImageBasePath    = "images"   -- resolves to web/dist/images/
```

Folder structure and how to generate the images are on the [Image Previews](/resources/awoken-appearance/configuration/image-previews) page.

## Shop costs

```lua shared/config.lua theme={"dark"}
Config.ClothingCost    = 100
Config.BarberCost      = 100
Config.TattooCost      = 100
Config.SurgeonCost     = 100
Config.ChargePerTattoo = true
```

| Key                                                          | Effect                                                                                                                                   |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `ClothingCost` / `BarberCost` / `TattooCost` / `SurgeonCost` | Cash charged to enter and use each shop type.                                                                                            |
| `ChargePerTattoo`                                            | `true` charges `TattooCost` **per tattoo applied** (per-tattoo `cost` can be set in `shared/tattoos.lua`); `false` charges once on save. |

## Interaction & menus

```lua shared/config.lua theme={"dark"}
Config.UseTarget          = false   -- ox_target / qb-target interaction
Config.UseRadialMenu      = false   -- radial-menu entries
Config.UseOxRadial        = false   -- use ox_lib radial (needs UseRadialMenu = true)
Config.EnablePedsForShops = true    -- spawn a clerk ped at each shop
Config.EnablePedMenu      = true    -- /pedmenu for staff
Config.PedMenuGroup       = "group.admin"
```

| Key                             | Effect                                                                       |
| ------------------------------- | ---------------------------------------------------------------------------- |
| `UseTarget`                     | Open shops via a targeting resource instead of walking into the zone.        |
| `UseRadialMenu` / `UseOxRadial` | Expose shop actions through a radial menu.                                   |
| `EnablePedsForShops`            | Spawn an NPC clerk at each store/barber/tattoo/surgeon.                      |
| `EnablePedMenu`                 | Enables `/pedmenu` - a free, full customisation menu.                        |
| `PedMenuGroup`                  | Ace group allowed to use `/pedmenu` (and `/pedmenu [id]` on another player). |

## Commands

| Command                       | Gated by                         | What it does                                                           |
| ----------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
| `/pedmenu [id]`               | `Config.PedMenuGroup`            | Open full customisation on yourself (or another player by id).         |
| `/reloadskin`                 | anyone                           | Re-applies your saved appearance - the fix for an invisible/stuck ped. |
| `/clearstuckprops`            | anyone                           | Removes props that got physically attached and stuck.                  |
| `/joboutfits`, `/gangoutfits` | `Config.EnableJobOutfitsCommand` | Open the job/gang outfit menu without a clothing room.                 |
| `/migrateskins`               | `group.admin`                    | One-time migration of skins from another appearance script.            |

## Other useful toggles

```lua shared/config.lua theme={"dark"}
Config.HideRadar                     = false -- hide minimap while the menu is open
Config.InvincibleDuringCustomization = true
Config.GenderBasedOnPed              = true  -- pick male/female options from the ped model
Config.PersistUniforms               = false -- keep job/gang outfits across reconnects
Config.AutomaticFade                 = false -- auto hair-fade; hides the Fade section
Config.RCoreTattoosCompatibility     = false -- set true only if you use rcore_tattoos
Config.ReloadSkinCooldown            = 5000  -- ms between /reloadskin uses
```

`Config.DisableComponents` and `Config.DisableProps` hide whole clothing/prop categories (Masks, Bags, Hats, Watches, …) from the UI - set any entry to `true` to remove it.