> ## 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.

# Image Previews

> Show real thumbnails for every clothing, hair, prop and overlay option.

By default, customisation menus make players scrub through numbered drawables blind. The Awoken rework lets every option show a **real thumbnail** instead - so players see the jacket, hairstyle or hat before they apply it.

When a thumbnail for an option is missing, that option silently falls back to the standard number stepper - so you can roll previews out gradually, category by category.

## Enabling

```lua shared/config.lua theme={"dark"}
Config.UseImagePreviews = true
Config.ImageBasePath    = "images"
```

| Key                | Effect                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `UseImagePreviews` | Master toggle. `false` = number steppers everywhere (stock behaviour).                                        |
| `ImageBasePath`    | Where thumbnails load from. Leave it as `"images"` - it resolves to the resource's `web/dist/images/` folder. |

## Folder structure

Local images live in `web/dist/images/`, organised by category. Every path is **lowercase**, and `{gender}` is always `male` or `female`.

```text web/dist/images/ theme={"dark"}
components/{gender}/{component_id}/{drawable}.png
props/{gender}/{prop_id}/{drawable}.png
hair/{gender}/{style}.png
headOverlays/{overlay_type}/{style}.png
tattoos/{zone}/{name}.png
```

Examples:

```text theme={"dark"}
components/male/11/0.png      → male jacket, drawable 0
components/female/4/12.png    → female pants, drawable 12
props/male/0/3.png            → male hat, drawable 3
hair/female/7.png             → female hairstyle 7
headOverlays/beard/2.png      → beard style 2
```

### Component & prop IDs

`{component_id}` and `{prop_id}` are the standard GTA clothing slots:

| `component_id` | Slot              |   | `prop_id` | Slot     |
| -------------- | ----------------- | - | --------- | -------- |
| `1`            | Mask              |   | `0`       | Hat      |
| `2`            | Hair              |   | `1`       | Glasses  |
| `3`            | Arms / upper body |   | `2`       | Ear      |
| `4`            | Pants             |   | `6`       | Watch    |
| `5`            | Bag               |   | `7`       | Bracelet |
| `6`            | Shoes             |   |           |          |
| `7`            | Scarf & chains    |   |           |          |
| `8`            | Undershirt        |   |           |          |
| `9`            | Body armour       |   |           |          |
| `10`           | Decals            |   |           |          |
| `11`           | Jacket / top      |   |           |          |

### Head overlay types

`{overlay_type}` is one of: `blemishes`, `beard`, `eyebrows`, `ageing`, `makeUp`, `blush`, `complexion`, `sunDamage`, `lipstick`, `moleAndFreckles`, `chestHair`, `bodyBlemishes`, `eyeColor`.

## Generating the images

You don't make these by hand. The companion resource **`awoken-recorder`** captures every drawable against a green screen, removes the background, and writes the files in exactly this structure.

<Card title="Generate previews with the Recorder" icon="camera" href="/resources/awoken-appearance/image-recorder">
  Run `/recorder`, pick the categories to capture, and let it batch-screenshot every option. Then copy the output into `web/dist/images/`. Full guide on the Recorder page.
</Card>

<Info>
  The Recorder generates `components`, `props`, `hair` and `headOverlays`. **Tattoo** thumbnails (`tattoos/{zone}/{name}.png`) aren't auto-captured - add those manually if you want tattoo previews, otherwise the tattoo list uses its dropdown.
</Info>

## Fallback behaviour

* Missing image for an option → that option shows the **number stepper** (no broken-image icon).
* `UseImagePreviews = false` → every option uses the number stepper, images are ignored.
* Gender is resolved from the ped model, so male/female folders are loaded independently.