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

# Installation

> Drop-in replacement for illenium-appearance - same folder name, schema, and exports.

Awoken Appearance is a drop-in replacement for `illenium-appearance`. It keeps the same folder name, database schema, and exports, so dependent resources (inventory, multichar, spawn, etc.) keep working without changes.

<Warning>
  Upgrading from `illenium-appearance`? **Back up your existing folder first** - replacing it without a backup loses any custom stores, outfits, tattoos, peds, blips, and preview images. Coming from a fresh install is also supported; the steps below cover both.
</Warning>

Once purchased on our website, the asset appears in your [Cfx.re portal](https://portal.cfx.re/) - download it there. Purchases are tied to the keymaster account that bought them; use the transfer system to move it to another account.

## Install

<Steps>
  <Step title="Download the asset">
    Grab the resource from your [Cfx.re portal](https://portal.cfx.re/).
  </Step>

  <Step title="Stop the server">
    Take the server fully offline before swapping the resource.
  </Step>

  <Step title="Back up and replace the folder">
    **Upgrading?** Copy your current `illenium-appearance` folder somewhere safe outside `resources/`, delete the original, then extract the Awoken build into the same path.

    **Fresh install?** Just extract the `illenium-appearance` folder into your `resources/`.

    Either way, **keep the folder named `illenium-appearance`** - inventory, multichar, spawn and other resources reference it by that name.
  </Step>

  <Step title="Port your customisations">
    Copy your edits from the backup into the matching files in the new build - see the [table below](#porting-your-customisations).
  </Step>

  <Step title="Ensure it in server.cfg">
    Make sure `ensure illenium-appearance` is in your `server.cfg`. If you're upgrading, you already have this line - leave it as-is.
  </Step>

  <Step title="Start the server" />
</Steps>

<Info>
  **Fresh database?** Import the SQL from the `sql/` folder once (or let your framework auto-import it). Upgrading over an existing install? The tables already exist and are left untouched.
</Info>

<Note>
  Coming from a **different** clothing script (e.g. qb-clothing)? Run `/migrateskins` once as an admin after boot to pull existing skins across. This is **not** needed when upgrading from illenium-appearance.
</Note>

## Porting your customisations

Player data lives in the database and carries over untouched. The only things to bring across from your backup are the files **you** edited:

| What you customised                        | File                                   |
| ------------------------------------------ | -------------------------------------- |
| Stores, blips, target peds, costs, toggles | `shared/config.lua`                    |
| Job / gang outfits                         | `shared/config.lua` (`Config.Outfits`) |
| Tattoo list                                | `shared/tattoos.lua`                   |
| Custom / addon peds                        | `shared/peds.lua`                      |
| Blacklisted drawables                      | `shared/blacklist.lua`                 |
| Accent colour / theme                      | `shared/theme.lua`                     |
| Preview images                             | `web/dist/images/**`                   |
| Locale overrides                           | `locales/*.lua`                        |

<Tip>
  Image previews are on by default (`Config.UseImagePreviews = true`) - drop clothing/hair/prop thumbnails into `web/dist/images/` and they'll show, generated with [awoken-recorder](/resources/awoken-appearance/image-recorder). For a server-wide accent colour, set `setr awoken:primaryColor "#00E5FF"`; see [Theming](/resources/awoken-appearance/configuration/theming).
</Tip>

## Updating

Re-download from your Cfx.re portal, then repeat **Stop → Replace → Ensure → Start**. Your customisation files in the table above are the only things to re-apply.