# Koja Multicharacter

Koja Multicharacter replaces the character selection, identity form and spawn screen of your framework with one resource.
It runs on **ESX**, **QBCore** and **QBX**, is built on [koja-lib](/koja-lib/getting-started) and shares its design with [Koja Appearance](/new/appearance).

This section covers version **2.0.0** of the resource.

## What you get

| Area | What is in it |
| --- | --- |
| Selection scene | Configurable locations, time and weather, idle scenarios, a single preview or a line-up of all characters, drag to rotate and scroll to zoom |
| Scene per character | Workplace or home locations, auto framing, the character's own car behind them |
| Cutscenes | An opening shot, walk-out / walk-in on every switch, and an arrival cutscene for new characters |
| Seasons and sound | Winter and Halloween scenes, UI sounds, cinematic sounds and music with per-player mute toggles |
| Character cards | Headshot, job and grade, gang, cash and bank, playtime, last played, created date, nationality, height, backstory and fields from other resources |
| Statuses | CK memorial cards, trash with restore, optional staff approval, name change requests |
| Slots | Default count, ACE tiers, Discord role tiers, per-player overrides, a Tebex command, locked slots with a store link, import of old `esx_multicharacter` slots |
| Creator | Identity form checked on the server (name rules, blacklist, unique names, age, height, nationality, backstory), then the appearance editor |
| Presets | Save a look and start new characters from it, or copy another character's look |
| Spawn selector | Last location, public, job and gang spots with minimum grade, cooldowns, spawns from other resources, party spawns and a sky camera. Uses the koja-spawnselector map when it is on the server |
| Spawn protection | Ghosting, invincibility, no shooting and transparency for a few seconds |
| Relog | `/relog` without reconnecting, with cooldown, dead, vehicle and combat checks and blockers from other resources |
| Admin | In-game panel (`/charadmin`) with search, notes, history and a queue, plus commands and Discord logs |
| Developer API | Exports, hooks that can cancel actions, events, state bags, card fields, scene hooks and custom arrivals |
| Languages | English and Polish, add your own in `locales/` |

## Quick facts

- **Frameworks:** ESX Legacy, QBCore and QBX, detected automatically.
- **Requires:** `koja-lib` and `oxmysql`.
- **Appearance:** Koja Appearance or illenium-appearance recommended. fivem-appearance, qb-clothing and esx_skin also work.
- **Replaces:** `esx_multicharacter` and `esx_identity` on ESX, `qb-multicharacter` on QBCore. It stops them if they start next to it.
- **Database:** seven `koja_multicharacter_*` tables, created and updated on start.
- **UI:** shipped prebuilt, sounds included. You only need Node and pnpm to change it.

## Start here

:::steps

### Install it

[Installation](/new/multicharacter/installation): dependencies, framework settings, `server.cfg` order and admin access.

### Configure it

[Configuration](/new/multicharacter/configuration): every option in `shared/config.lua`.

### Learn what it does

[Features](/new/multicharacter/features) and [2.0 Features](/new/multicharacter/features-2).

### Use it from your own code

[Developer API](/new/multicharacter/developer-api) and [Developer API 2.0](/new/multicharacter/developer-api-2).

:::

## In this section

::::cards{cols="2"}
:::card{title="Installation" href="/new/multicharacter/installation" icon="download"}
Dependencies, framework settings and start order.
:::
:::card{title="Configuration" href="/new/multicharacter/configuration" icon="settings"}
Every Config option, explained.
:::
:::card{title="Features" href="/new/multicharacter/features" icon="sparkles"}
Selection, cutscenes, creator, spawns and relog.
:::
:::card{title="2.0 Features" href="/new/multicharacter/features-2" icon="sparkles"}
Arrival, scene per character, seasons, statuses, admin panel and party.
:::
:::card{title="Developer API" href="/new/multicharacter/developer-api" icon="code"}
Exports, hooks, events and state bags.
:::
:::card{title="Developer API 2.0" href="/new/multicharacter/developer-api-2" icon="code"}
Statuses, card fields, scene hooks and arrivals.
:::
:::card{title="Commands" href="/new/multicharacter/commands" icon="terminal"}
Admin and player commands.
:::
:::card{title="Troubleshooting" href="/new/multicharacter/troubleshooting" icon="bug"}
Fixes for common setup problems.
:::
::::