# Installation

This page takes you from the downloaded archive to a working spawn screen.

## Requirements

| Resource | Required | What it is used for |
| --- | --- | --- |
| [koja-lib](/koja-lib/getting-started) | Yes | Framework bridge (jobs, identifiers, admin check, notifications, vehicle keys and fuel) |
| [oxmysql](https://github.com/overextended/oxmysql) | Yes | Last location, locks, editor locations, photos and stats |
| A framework | Yes | ESX (`es_extended`), QBCore (`qb-core`) or QBox (`qbx_core`) |
| [screenshot-basic](https://github.com/citizenfx/screenshot-basic) | No | Location photos in the [editor](/new/spawn-selector/admin-tools) |
| [Koja Multicharacter](/new/multicharacter) | No | Opens this map after character selection |
| `qb-apartments` | No | Starter apartments on QBCore |
| A housing script | No | qb-houses, qs-housing, ps-housing, esx_property, nolag_properties or bcs_housing — owned properties become spawns |

## Install

:::steps

### Put the resource in `resources`

Unpack the archive and keep the folder name `koja-spawnselector`.
Other scripts call `exports['koja-spawnselector']` and include `@koja-spawnselector/import.lua`, so the name matters.

### Remove the old spawn screen

- **QBCore / QBox with qb-multicharacter:** remove `qb-spawn`. Koja Spawn Selector `provide`s it and handles the same `qb-spawn:client:setupSpawns` / `qb-spawn:client:openUI` events, including the `qb-apartments` starter apartments.
- **ESX:** nothing to remove. The selector opens on `esx:playerLoaded` after your multicharacter loaded the character.
- **Koja Multicharacter:** nothing to remove. When it runs, it opens the selector itself and the automatic openers above stay off.

### Add it to `server.cfg`

```cfg title="server.cfg"
ensure oxmysql
ensure koja-lib
ensure screenshot-basic
ensure koja-spawnselector
# scripts that use it (multicharacter, housing...) after this line
```

### Pick the language

```lua title="shared/config.lua"
Config.Locale = 'en'
```

Any file name from `shared/locales/` works. See [Translations](/new/spawn-selector/translations).

### Restart the server

The tables are created on start (see [Database](/new/spawn-selector/database)).

:::

## Admin commands

| Command | What it does |
| --- | --- |
| `/spawnselector [id]` | Opens the selector for you or for player `id`, with ESC enabled. From the server console: `spawnselector <id>` |
| `/spawneditor` | Opens the selector with the [Editor and Stats tabs](/new/spawn-selector/admin-tools) |
| `/spawnevent <minutes> <name>` | Creates a temporary event where you stand |

They need the ACE in `Config.Admin.Ace` (default `command`) or a framework group from `Config.Admin.Groups`.

## Check that it works

1. Join and load a character. The map opens over the world with your last location selected, showing the game time and weather.
2. Click another location in the list — the camera flies there, the card shows it live and the route from your last location appears.
3. Press **Enter** or **Spawn here**. The camera drops from the sky to your character.
4. As an admin, type `/spawneditor`, add a location with **Use my position** and take a photo.

## Changing the UI

The UI is shipped prebuilt in `web/dist`. You only need Node and pnpm when you change `web/src`:

```bash
cd web
pnpm install
pnpm build
```

## Next steps

- [Configuration](/new/spawn-selector/configuration) — your own locations, locks and theme.
- [Anti combat log & restrictions](/new/spawn-selector/anti-combat-log) — death, jail and combat logging.
- [Developer API](/new/spawn-selector/developer-api) — houses and other per-player locations.