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

> Get Awoken MultiCharacter running on your server.

<Warning>
  Only one character selector can run at a time. Disable your framework's
  default multichar before starting this resource.
</Warning>

<Warning>
  The resource folder must be named exactly **`awoken_multicharacter`** (underscore) for both
  QBX/QBCore and ESX. It will refuse to start if the name doesn't match.
</Warning>

## Prerequisites

<Tabs>
  <Tab title="QBX / QBCore">
    * `qbx_core` or `qb-core`
    * `ox_lib`
    * `oxmysql`
    * An appearance resource: `illenium-appearance`, `fivem-appearance`, or `ox_appearance`
    * A spawn selector: `qbx_spawn`, `qb-spawn`, or `um-spawn` (optional - `none` spawns at last position)
  </Tab>

  <Tab title="ESX">
    * `es_extended` (ESX Legacy)
    * `ox_lib`
    * `oxmysql`
    * An appearance resource: `illenium-appearance`, `fivem-appearance`, `ox_appearance`, or the traditional `esx_skin` + `skinchanger` stack
  </Tab>
</Tabs>

***

## Steps

<Tabs>
  <Tab title="QBX / QBCore">
    <Steps>
      <Step title="Disable the default selector">
        Comment out your framework's built-in multichar in `server.cfg` and add the new resource:

        ```cfg server.cfg theme={"dark"}
        ensure awoken_multicharacter
        ```

        For QBX, open `qbx_core/config/client.lua` and set:

        ```lua theme={"dark"}
        useExternalCharacters = true,
        ```
      </Step>

      <Step title="Set the framework">
        Open `config.lua`. The default is `'auto'`, which detects `qbx_core` first then falls back to `qb-core`. You can set it explicitly if needed:

        ```lua config.lua theme={"dark"}
        Config.Framework = 'auto'   -- or 'qbx' / 'qb'
        ```
      </Step>

      <Step title="Set your appearance resource">
        ```lua config.lua theme={"dark"}
        Config.AppearanceResource  = 'illenium-appearance'
        Config.FirstCharacterEvent = 'qb-clothes:client:CreateFirstCharacter'
        ```

        See the [Configuration](/configuration) page for supported values and the full option list.
      </Step>

      <Step title="Start the server">
        Boot up. On start the resource prints a banner and the detected framework:

        ```
        ╔══════════════════════════════════════════════════════╗
        ║               awoken_multicharacter                  ║
        ║  Version  : 1.0.0                                     ║
        ║  Framework: QBX Core                                 ║
        ║  by Awoken Labs                                      ║
        ╚══════════════════════════════════════════════════════╝
        [awoken-mc] Framework: qbx
        ```

        `Framework: qb` means it fell back to `qb-core`. If it shows `Unknown` or defaults to `qbx`
        unexpectedly, make sure your framework resource starts before `awoken_multicharacter`.
        Set `Config.Debug = true` for verbose startup logging (DB setup, slot lookups, etc.).
      </Step>
    </Steps>
  </Tab>

  <Tab title="ESX">
    <Steps>
      <Step title="Disable esx_multicharacter">
        Comment it out in `server.cfg` and add the new resource:

        ```cfg server.cfg theme={"dark"}
        # ensure esx_multicharacter
        ensure awoken_multicharacter
        ```

        `awoken_multicharacter` must start after `es_extended` and `oxmysql`.
      </Step>

      <Step title="Enable multichar in ESX">
        Open `es_extended/config.lua` and set:

        ```lua theme={"dark"}
        Config.Multichar = true
        ```

        Without this ESX spawns the player straight into the world and skips the selector.
      </Step>

      <Step title="Set the framework">
        Open `config.lua` and set the framework to `'esx'`, or leave it as `'auto'` (auto detects `qbx_core` first, then `qb-core`, then `es_extended`):

        ```lua config.lua theme={"dark"}
        Config.Framework = 'esx'
        ```
      </Step>

      <Step title="Set your appearance resource">
        ```lua config.lua theme={"dark"}
        Config.AppearanceResource = 'illenium-appearance'
        ```

        Supported values: `'illenium-appearance'`, `'fivem-appearance'`, `'ox_appearance'`, `'sn_appearance'`. Leave it as any other value (or empty) to use the traditional `skinchanger` + `esx_skin` stack.

        See [Configuration](/configuration) for the clothing editor behaviour per resource.
      </Step>

      <Step title="Start the server">
        Boot up and confirm the console shows the framework was detected as ESX:

        ```
        [awoken-mc] Framework: esx
        ```

        On first start the resource sets up its schema - it adds a `multichar_scenario` column to
        `users` and creates a `multichar_players` table. Both operations are safe and only run if
        the column or table doesn't already exist. Set `Config.Debug = true` to log these steps.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Verify it's working

Connect to your server. You should hit the character selector rather than spawning directly into
the world. The console logs character slot counts and Discord role cache status on each connection.

If you're still spawning into the world, the two most common causes are:

<Tabs>
  <Tab title="QBX / QBCore">
    * The old multichar resource is still running. Check every `.cfg` file, not just `server.cfg` - a resource ensured in a category file will still load even if you commented it out in the main config.
    * `qbx_core`'s built-in multichar flag wasn't set to `false`.
  </Tab>

  <Tab title="ESX">
    * `Config.Multichar = true` is not set in `es_extended/config.lua`.
    * `esx_multicharacter` is commented out in one cfg file but still ensured in another (category files, etc.).
  </Tab>
</Tabs>