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

# Exports & Events

> The complete client export surface - unchanged from upstream illenium-appearance.

The Awoken rework ships under the `illenium-appearance` name and **preserves the entire upstream export and event surface unchanged**. Every resource written against stock illenium-appearance - inventory clothing panels, multichar, character creators - works without modification. These exports are inherited from the original [illenium-appearance](https://github.com/iLLeniumStudios/illenium-appearance).

All exports are **client-side** and called on the `illenium-appearance` resource name:

```lua theme={"dark"}
local appearance = exports['illenium-appearance']:getPedAppearance(cache.ped)
```

## The appearance table

Most exports read or write pieces of an **appearance table** - the same shape `getPedAppearance` returns and `setPlayerAppearance` accepts:

```lua theme={"dark"}
{
    model        = "mp_m_freemode_01",        -- model name (string)
    headBlend    = { ... },                   -- parents + skin mix
    faceFeatures = { noseWidth = 0.0, ... },  -- per-feature floats (-1.0 … 1.0)
    headOverlays = { beard = { ... }, ... },  -- per-overlay style/opacity/colour
    components   = { { component_id, drawable, texture }, ... },
    props        = { { prop_id, drawable, texture }, ... },
    hair         = { style, color, highlight, texture },
    tattoos      = { ZONE_TORSO = { ... }, ... },
    eyeColor     = 0,                          -- eye-colour index
}
```

Sub-shapes:

| Part                 | Shape                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `component`          | `{ component_id = number, drawable = number, texture = number }`                                         |
| `prop`               | `{ prop_id = number, drawable = number, texture = number }`                                              |
| `headBlend`          | `{ shapeFirst, shapeSecond, shapeThird, skinFirst, skinSecond, skinThird, shapeMix, skinMix, thirdMix }` |
| `headOverlays[name]` | `{ style = number, opacity = number, color = number, secondColor = number }`                             |
| `hair`               | `{ style = number, color = number, highlight = number, texture = number }`                               |

`component_id` and `prop_id` are the standard GTA slots - see the [Image Previews](/resources/awoken-appearance/configuration/image-previews) page for the full slot tables.

## Getters

Read state from a ped entity. Pass `cache.ped` for the local player.

| Export                    | Returns                                                                                                                           |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `getPedAppearance(ped)`   | The full appearance table above.                                                                                                  |
| `getPedModel(ped)`        | The model **name** string. Resolves models listed in `Config.Peds`; freemode peds return `mp_m_freemode_01` / `mp_f_freemode_01`. |
| `getPedComponents(ped)`   | Array of `{ component_id, drawable, texture }`.                                                                                   |
| `getPedProps(ped)`        | Array of `{ prop_id, drawable, texture }`.                                                                                        |
| `getPedHeadBlend(ped)`    | The `headBlend` table.                                                                                                            |
| `getPedFaceFeatures(ped)` | Map of `featureName → float`.                                                                                                     |
| `getPedHeadOverlays(ped)` | Map of `overlayName → { style, opacity, color, secondColor }`.                                                                    |
| `getPedHair(ped)`         | `{ style, color, highlight, texture }`.                                                                                           |

## Setters

Apply state to a ped. The `setPed*` exports take an explicit `ped`; the `setPlayer*` exports always act on the **local player** (`cache.ped`) and can swap the model.

| Export                                  | Effect                                                                                     |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `setPlayerAppearance(appearance)`       | Apply a full appearance table to the local player, **including a model swap**.             |
| `setPedAppearance(ped, appearance)`     | Apply a full appearance table to any ped (no model swap).                                  |
| `setPlayerModel(model)`                 | Swap the local player's model (name string or hash). Resets head blend on freemode models. |
| `setPedComponent(ped, component)`       | Apply one `{ component_id, drawable, texture }`.                                           |
| `setPedComponents(ped, components)`     | Apply an array of components.                                                              |
| `setPedProp(ped, prop)`                 | Apply one `{ prop_id, drawable, texture }`. A `drawable` of `-1` clears the prop.          |
| `setPedProps(ped, props)`               | Apply an array of props.                                                                   |
| `setPedHeadBlend(ped, headBlend)`       | Apply parents/skin mix (freemode peds only).                                               |
| `setPedFaceFeatures(ped, faceFeatures)` | Apply the per-feature float map.                                                           |
| `setPedHeadOverlays(ped, headOverlays)` | Apply the overlay map (beard, makeup, blush, …).                                           |
| `setPedHair(ped, hair, tattoos)`        | Apply hair; re-applies tattoos (and auto-fade) on freemode peds. `tattoos` is optional.    |
| `setPedEyeColor(ped, eyeColor)`         | Apply the eye-colour index.                                                                |
| `setPedTattoos(ped, tattoos)`           | Replace the ped's tattoo set.                                                              |

<Warning>
  On **freemode** peds, `setPedComponent`/`setPedComponents` ignore `component_id` `0` (face) and `2` (hair) - those are driven by `setPedHeadBlend` and `setPedHair`. Apply hair through `setPedHair`, not as a component.
</Warning>

## Opening the editor

`startPlayerCustomization(cb, config)` opens the full appearance UI on the local player. `cb` receives the saved appearance table, or `nil` if the player cancelled.

```lua theme={"dark"}
exports['illenium-appearance']:startPlayerCustomization(function(appearance)
    if appearance then
        -- player saved; appearance is the new look
    else
        -- player cancelled
    end
end, {
    ped          = true,
    headBlend    = true,
    faceFeatures = true,
    headOverlays = true,
    components   = true,
    props        = true,
    tattoos      = true,
})
```

`config` toggles which **sections** the player can edit - the same keys as `Config.NewCharacterSections`. Omit a key (or set it `false`) to hide that section.

| Key            | Section                                                                             |
| -------------- | ----------------------------------------------------------------------------------- |
| `ped`          | Model picker. With `peds = { "model1", … }` you can restrict the selectable models. |
| `headBlend`    | Parents / heritage / skin mix.                                                      |
| `faceFeatures` | Nose, brow, cheek, jaw sliders.                                                     |
| `headOverlays` | Beard, eyebrows, makeup, blemishes, etc.                                            |
| `components`   | Clothing (tops, legs, shoes, bags …).                                               |
| `props`        | Hats, glasses, watches, bracelets.                                                  |
| `tattoos`      | Tattoo picker.                                                                      |

## Commands & events

| Trigger                                 | What it does                                                                                     |
| --------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `/reloadskin`                           | Re-applies the saved appearance from the database - the go-to fix for an invisible or stuck ped. |
| `/pedmenu [id]`                         | Opens full customisation (gated by `Config.PedMenuGroup`).                                       |
| `illenium-appearance:client:reloadSkin` | Net event behind `/reloadskin`, callable from other resources.                                   |

<Info>
  The resource name, exports, and event namespace all use **`illenium-appearance`** - reference it that way in `exports[...]` and event calls. Nothing changes for scripts written against stock illenium-appearance.
</Info>