# Installation

This page takes you from the downloaded archive to a running menu.
If you already run illenium-appearance, you replace it — your players keep their skins and outfits.

## Requirements

| Resource | Required | What it is used for |
| --- | --- | --- |
| [ox_lib](https://github.com/overextended/ox_lib) | Yes | Callbacks, commands, notifications, menus |
| [oxmysql](https://github.com/overextended/oxmysql) | Yes | Skins, outfits and the `koja_appearance_*` tables |
| A framework | Yes | ESX (`es_extended`), QBCore (`qb-core`), QBox (`qbx_core`) or ox_core |
| [screenshot-basic](https://github.com/citizenfx/screenshot-basic) | Capture panel only | Taking the thumbnail shots |
| [ox_inventory](https://github.com/overextended/ox_inventory) | No | Clothing as inventory items |
| ox_target or qb-target | No | Talking to shopkeepers through target. Without one, a floor marker is used |
| [Fivemanage](https://fivemanage.com) account | No | Hosting thumbnails instead of the `shots/` folder |

:::hint{type="warning" title="Remove the original first"}
Do not run Koja Appearance next to the original illenium-appearance, `esx_skin` or `skinchanger`.
It registers the same exports and events, and it `provide`s `esx_skin` and `skinchanger` itself.
:::

## Install

:::steps

### Put the resource in `resources`

Unpack the archive and name the folder `illenium-appearance`.

```text
resources/
└── [koja]/
    └── illenium-appearance/
```

The folder name is the resource name, and exports are always registered under it.
Other scripts call `exports['illenium-appearance']`, so a different name (for example `koja-appearance`) breaks them unless you change every call.
Use the same name in the ox_inventory item and the ace lines below.

### Add it to `server.cfg`

Start it after its dependencies and before the scripts that use it:

```cfg title="server.cfg"
ensure ox_lib
ensure oxmysql
ensure screenshot-basic
ensure illenium-appearance
```

### Give admins access

The Capture panel, `/pedmenu`, `/skin` and `/shopped` need admin rights.
A player is an admin when they have the ace in `Config.Koja.Capture.AdminGroup` (default `group.admin`), or their framework group is in `Config.Koja.Capture.FrameworkGroups` (`admin`, `superadmin`, `owner`, `god`, `dev`).

```cfg title="server.cfg"
add_principal identifier.license:YOUR_LICENSE group.admin
add_ace resource.illenium-appearance command.add_ace allow
```

The second line lets the resource grant the ace to the group on start — the same requirement as the upstream `/pedmenu`.

### Pick the language

Open `shared/koja_config.lua` and set `Config.Locale` to a file name from `locales/`:

```lua title="shared/koja_config.lua"
Config.Locale = "en"
```

The old convar `setr illenium-appearance:locale "xx"` still wins when it is set.

### Restart the server

The three `koja_appearance_*` tables are created when the resource starts.
On ESX, old `esx_skin` / `skinchanger` skins in `users.skin` are converted on the same start (see [Database](/new/appearance/database)).

:::

## Coming from illenium-appearance

Nothing in the database has to change.
Copy over the options you changed in the old `shared/config.lua` (stores, clothing rooms, outfits, blacklists) — the file has the same keys.

:::hint{type="info" title="Shopkeepers replace store zones"}
With `Config.Koja.Shops.Enabled = true` (the default), shopkeeper peds from `shared/koja_shops.lua` replace the store zones, target boxes and blips of `Config.Stores`.
Clothing rooms and player outfit rooms keep working as before.
Set `Enabled = false` to keep your `Config.Stores`.
:::

## Changing the UI

The UI is shipped prebuilt in `web/dist`.
You only need Node and pnpm when you change the React source in `web/src`:

```bash
cd web
pnpm install
pnpm build
```

Restart the resource afterwards.

## Check that it works

:::frame{caption="The key prompt in front of a shopkeeper (marker mode)."}
![Clothing store key prompt](https://pub-57d6558d0e204696b4cdeee5d172e561.r2.dev/appearance/hub-prompt.c3944d8343.webp)
:::

1. Join the server and walk to a clothing shop. A clerk stands behind the counter.
2. Talk to the clerk. The wardrobe hub opens; **Change clothes** opens the editor.
3. As an admin, type `/pedmenu`. The editor opens with the **Admin Panel** button in the top toolbar.

## Next steps

- [Configuration](/new/appearance/configuration) — branding, studios, shops, prices and capture.
- [Capture panel](/new/appearance/capture-panel) — make the clothing thumbnails.
- [Troubleshooting](/new/appearance/troubleshooting) — if something above did not happen.