# Kivo Spawn Selector

Cinematic spawn location selector for FiveM. Presents a god-view hub camera that pans to each location on hover, with last location memory for returning characters. Framework-agnostic — no `ox_lib` or `oxmysql` required.

***

## Installation Steps

{% stepper %}
{% step %}

## Remove conflicting scripts

Remove or comment out any of the following from `server.cfg` before installing:

* `qb-spawn` — replaced by kivo-spawn (QBCore)
* `spawnmanager` — **remove for QBCore and QBX only**; keep it for ESX
* Any other spawn selector resource currently running on your server
  {% endstep %}

{% step %}

## Place the resource

```
resources/
  [kivo]/
    kivo-spawn/
```

{% endstep %}

{% step %}

## Configure

Open `config.lua` and set your hub camera and spawn locations:

```lua
-- Hub camera shown on open
Config.spawnbehavior.hub = {
    coords = vector3(-269.0, -955.0, 750.0),
    rot    = vector3(-90.0, 0.0, 0.0),
}

-- New character behaviour
Config.newCharSkipSelector = false   -- true = skip UI and spawn at defaultSpawn
Config.defaultSpawn        = vector4(-269.4, -955.3, 31.2, 205.0)

-- Spawn locations
Config.spawnlocations = {
    {
        id            = '1',
        coords        = vector4(-1411.59, -1241.65, 4.40, 12.28),
        img           = '',   -- path relative to html/images/, leave '' for default image
        name          = 'Vespucci Beach',
        description   = 'Relax by the shore.',
        temperature   = '32C',
        wind          = 'Light',
        weather       = 'sunny',
        spawnfunction = 'default',
    },
    -- add more locations here
}
```

{% hint style="info" %}
Use `/freecam` in-game and press `ENTER` to print current camera coords and rotation to console.
{% endhint %}
{% endstep %}

{% step %}

## Add to server.cfg

{% tabs %}
{% tab title="QBX" %}

```
ensure qbx_core
ensure kivo-multi-char    # if using Kivo Suite
ensure kivo-spawn
```

{% endtab %}

{% tab title="QBCore" %}

```
ensure qb-core
ensure kivo-multi-char    # if using Kivo Suite
ensure kivo-spawn
```

Do **not** add `spawnmanager` for QBCore.
{% endtab %}

{% tab title="ESX" %}

```
ensure mapmanager
ensure spawnmanager       # keep for ESX
ensure es_extended
ensure kivo-multi-char    # if using Kivo Suite
ensure kivo-spawn
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

***

## Features

* Cinematic hub camera + per-location flyover cameras
* Last location memory for returning characters
* New character skip option (bypass UI, teleport to default spawn)
* Custom spawn functions via `SpawnFunctions` in `shared/spawnfunctions/`
* Exports: `openSpawnUI`, `isMenuOpen`
* No `ox_lib` or `oxmysql` dependency

***

## Config Reference

| Key                                           | Default                      | Description                                      |
| --------------------------------------------- | ---------------------------- | ------------------------------------------------ |
| `Config.ui.title`                             | `'Spawn Selector'`           | NUI heading                                      |
| `Config.ui.subtitle`                          | `'Choose where to begin...'` | NUI subheading                                   |
| `Config.ui.defaultImg`                        | `'images/default.png'`       | Fallback image for locations with no `img` set   |
| `Config.ui.openDelay`                         | `1000`                       | ms delay before NUI opens after trigger          |
| `Config.spawnbehavior.allowLastSpawnLocation` | `true`                       | Show Last Location card for returning characters |
| `Config.spawnbehavior.cameraHoverDelay`       | `150`                        | ms before camera focuses on hovered location     |
| `Config.spawnbehavior.hub.coords`             | —                            | Hub camera world position                        |
| `Config.spawnbehavior.hub.rot`                | —                            | Hub camera rotation                              |
| `Config.newCharSkipSelector`                  | `false`                      | Skip selector for new characters                 |
| `Config.defaultSpawn`                         | Legion Square                | Spawn used when selector is skipped              |

***

## Exports

```lua
exports['kivo-spawn']:openSpawnUI()  -- open the spawn selector from another resource
exports['kivo-spawn']:isMenuOpen()   -- returns true if selector is currently open
```

***

## Kivo Suite Integration

When kivo-multi-char has `Config.spawnSelector = 'kivo-spawn'`, it fires the following event after a character is selected:

```lua
TriggerEvent('kivo:client:readyForSpawn', spawnCoords, false, isDemoServer)
```

kivo-spawn listens for this and opens its UI. No manual wiring needed — install both, set the config option, and they connect automatically.

***

## Troubleshooting

1. **Player stuck on loading screen**
   * `ShutdownLoadingScreen()` must be called before `kivo:client:readyForSpawn` fires
   * Add `setr loadscreen:externalShutdown "false"` to `server.cfg` as a quick workaround
2. **Player spawns at wrong location or default coords**
   * Check that `coords.w` (heading) is set in every `spawnlocations` entry
3. **Camera stuck after a location is selected**
   * A custom `spawnfunction` returned `nil` — use `SpawnFunctions.default` as a reference
4. **Selector never opens after `readyForSpawn`**
   * kivo-spawn is not started, or it loads before kivo-multi-char in `server.cfg`

***

## Checklist

* [ ] Removed `qb-spawn` or other conflicting spawn scripts from `server.cfg`
* [ ] `spawnmanager` removed for QBCore / QBX, kept for ESX
* [ ] Spawn locations configured in `Config.spawnlocations`
* [ ] Hub camera positioned correctly in `Config.spawnbehavior.hub`
* [ ] kivo-spawn loads after kivo-multi-char (if using Kivo Suite)
* [ ] Tested with a fresh character and a returning character


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kivostudios.net/scripts/kivo-spawn-selector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.