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

# Installation

## Requirements

* FiveM server with `lua54 'yes'`
* `oxmysql`
* One of: `qbx_core`, `qb-core`, `es_extended`, or standalone

## Steps

1. Drop the `awoken_spawn` folder into `resources/`. **The folder must be named exactly `awoken_spawn`.**

2. Add to `server.cfg`:

   ```cfg theme={"dark"}
   ensure oxmysql
   ensure qbx_core        # or qb-core / es_extended
   ensure awoken_spawn
   ```

   If you use a multichar resource, `ensure` it **before** `awoken_spawn`.

3. Open `config.lua`, set your brand, and customise `Config.locations`.

4. Start the server. The DB table (`awoken_spawn_lastchoice` by default) is created automatically on first run.

## How the selector opens

`Config.open.autoOpenOnFrameworkLoad = true` (default) auto-opens the selector when the framework fires its player-loaded event:

| Framework         | Event hooked automatically                                             |
| ----------------- | ---------------------------------------------------------------------- |
| QBox (`qbx_core`) | `QBCore:Server:OnPlayerLoaded` **and** `qbx_core:server:playerLoaded`  |
| QBCore            | `QBCore:Server:OnPlayerLoaded`                                         |
| ESX               | `esx:playerLoaded`                                                     |
| Standalone        | none — trigger the open yourself (see [Exports & Events](exports.mdx)) |

A short de-dupe guard keeps repeated events from opening it twice.

### Third-party multichar

If a standalone multichar doesn't emit the framework's normal player-loaded event, list its "character chosen" event in `config.lua`:

```lua theme={"dark"}
Config.open.multichar = {
    'okokMulticharacter',                              -- bare name -> okokMulticharacter:CharacterChosen
    'nc-multichar:server:characterSelected',           -- full resource:event, used verbatim
}
```

If the selector opens too early, also flip `Config.open.autoOpenOnFrameworkLoad = false` so only the multichar drives it.

### awoken\_multicharacter

Built-in integration — leave `Config.open.awokenMultichar.enabled = true` (default). New characters get the selector after their clothing menu closes and, if `awaitIntroCinematic = true`, only after any intro cutscene finishes.

## Verify

Set `Config.debug = true`, restart, join. Server console should log:

```
[awoken_spawn] open src=1 isNew=false -> N cards
```

Flip back to `Config.debug = false` for production.