# Installation

## Requirements

| Resource | Notes |
| --- | --- |
| [koja-lib](/koja-lib/getting-started) | Required |
| oxmysql | Required |
| es_extended (Legacy), qb-core or qbx_core | Detected automatically |
| Koja Appearance or illenium-appearance | Recommended. fivem-appearance, qb-clothing and esx_skin also work |
| koja-spawnselector | Optional. Its map replaces the built-in spawn screen |

:::::steps

### Add the resource

Put `koja-multicharacter` in your `resources` folder.

### Set up your framework

::::tabs
:::tab{title="ESX"}
Remove `ensure esx_multicharacter` and `ensure esx_identity` from `server.cfg`.

ESX only loads characters in multicharacter mode when `Config.Multichar` is true. es_extended sets it to true when the `esx_multicharacter` folder exists, so either keep that folder in `resources` without ensuring it, or set it yourself in `es_extended/shared/config/main.lua`:

```lua title="es_extended/shared/config/main.lua"
Config.Multichar = true
```

The resource prints a red warning on start when `Config.Multichar` is false.
:::
:::tab{title="QBCore"}
Remove `ensure qb-multicharacter` and `ensure qb-spawn` from `server.cfg`.
:::
:::tab{title="QBX"}
Disable the built-in character menu in `qbx_core/config/client.lua`:

```lua title="qbx_core/config/client.lua"
characters = {
    useExternalCharacters = true,
}
```

Stop `qbx_spawn` if you use it.
:::
::::

### Start it after its dependencies

```cfg title="server.cfg"
ensure oxmysql
ensure es_extended        # or qb-core / qbx_core
ensure koja-lib
ensure illenium-appearance
ensure koja-spawnselector # optional
ensure koja-multicharacter
```

### Start the server

The tables are created on the first start. `sql/koja_multicharacter.sql` is only there for reference.

On ESX the resource also widens the `identifier` and `owner` columns so the character prefix (`char1:`) fits. Turn this off with `Config.Esx.AutoResizeColumns = false`.

:::::

:::hint{type="warning" title="Old multicharacter resources"}
If `esx_multicharacter`, `esx_identity` or `qb-multicharacter` start while Koja Multicharacter runs, it stops them and prints a warning. Two character menus at once block each other, so remove them from `server.cfg` anyway.
:::

## Discord logs (optional)

```cfg title="server.cfg"
set kmc_webhook_created "https://discord.com/api/webhooks/..."
set kmc_webhook_deleted "https://discord.com/api/webhooks/..."
set kmc_webhook_selected "https://discord.com/api/webhooks/..."
set kmc_webhook_admin "https://discord.com/api/webhooks/..."
```

Character selection is only logged when `ServerConfig.LogSelected = true` in `server/config.lua`.

## Slot tiers and admin access (optional)

```cfg title="server.cfg"
add_ace group.vip koja.multicharacter.slots.vip allow
add_ace group.admin koja.multicharacter.slots.staff allow
add_ace group.admin koja.multicharacter.admin allow
```

The tier ACEs and slot counts are set in [`Config.Slots.Tiers`](/new/multicharacter/configuration). Framework groups listed in `Config.Admin.Groups` can use the admin commands without the ACE.

## Building the UI (only if you change it)

```bash
cd web
pnpm install
pnpm build   # outputs web/build
pnpm dev     # browser preview with mock data on http://localhost:5201
```