# qb-spawn

`qb-spawn` is the QBCore spawn selector. After character login, it lets players select a configured
public spawn, a supported house or apartment, or their saved position. The actual upstream resource
uses `QB.Spawns` in `config.lua`, **not** a `Config.Spawns` table.

This guide describes [qb-spawn at commit 0cb18b1](https://github.com/qbcore-fivem/qb-spawn/tree/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00).
Check your installed commit before copying a configuration or event into a modified server.

## Quick answer

To add a location, open `qb-spawn/config.lua` and add an entry to `QB.Spawns` with `coords`,
`location`, and `label`. Restart `qb-spawn` after testing the edited Lua, then select an existing
character to confirm the location appears.

- **Configure spawns:** [`config.lua` in the upstream source](https://github.com/qbcore-fivem/qb-spawn/blob/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00/config.lua)
- **Open the selector:** the client event `qb-spawn:client:openUI` receives a Boolean.
- **Populate locations:** the client event `qb-spawn:client:setupSpawns` receives character data,
  whether the character is new, and apartment data.
- **Troubleshoot character handoff:** see [qb-multicharacter](/docs/resources/qb-multicharacter)
  and [multicharacter loading](/docs/troubleshooting/multicharacter-loading).

## Installation & Setup

1. Get the [qb-spawn repository](https://github.com/qbcore-fivem/qb-spawn) and record its commit.
2. Place it at `resources/[qb]/qb-spawn` without renaming the resource.
3. Install and configure the resources used in your login flow. The upstream source references
   `qb-core`, `qb-houses`, `qb-garages`, `qb-apartments`, and `oxmysql`; the client manifest also
   loads `@qb-apartments/config.lua`.
4. Start `qb-core` before `qb-spawn`, and start the housing, apartment, and character resources
   required by your setup. Use the [resource load-order guide](/docs/troubleshooting/resource-load-order)
   if an import or export fails.
5. Join with a test character and verify the spawn selector, a public spawn, and returning to the
   last position before releasing to players.

The official [README](https://github.com/qbcore-fivem/qb-spawn/blob/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00/README.md)
shows the manual `ensure` entries. Follow the [QBCore installation guide](/docs/installation)
for a complete recipe instead of treating this individual resource as a server pack.

## Configuration

### Spawn Locations

The upstream `config.lua` defines `QB = {}` followed by `QB.Spawns`. For example, these two
locations are taken from that file:

```lua
-- qb-spawn/config.lua
QB.Spawns = {
    legion = {
        coords = vector4(195.17, -933.77, 29.7, 144.5),
        location = 'legion',
        label = 'Legion Square',
    },
    motel = {
        coords = vector4(327.56, -205.08, 53.08, 163.5),
        location = 'motel',
        label = 'Motels',
    },
}
```

Use a unique table key and matching `location` value for each new public spawn. `coords` is a
`vector4` with X, Y, Z, and heading; `label` is the text shown in the selector. Confirm that the
position is valid in-game before making it available.

> Do not paste legacy examples using `Config.Spawns`, `Config.CamPositions`, or
> `Config.EnableSpawnSelection` into the current upstream resource. Those settings are not read by
> the verified `qb-spawn` files. An old tutorial may describe a fork with different configuration.

### Houses and apartments

The selector's normal-location list comes from `QB.Spawns`. Owned-house options come from the
`qb-spawn:server:getOwnedHouses` callback, while new-character apartment choices use the apartment
list supplied by the character flow. A configured apartment or house does not need to be duplicated
as a public `QB.Spawns` entry.

If apartment options are absent, verify the apartment resource is running, its config is available,
and the correct character-flow branch is active. See
[qb-apartments](/docs/resources/qb-apartments) and [qb-houses](/docs/resources/qb-houses).

## API Reference

The verified [client.lua](https://github.com/qbcore-fivem/qb-spawn/blob/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00/client.lua)
registers these integration events:

| Event | Arguments | Purpose |
| --- | --- | --- |
| `qb-spawn:client:setupSpawns` | `cData, new, apps` | Send normal/house locations or new-character apartment options to NUI |
| `qb-spawn:client:openUI` | `value` (Boolean) | Open or close the spawn selector |
| `qb-houses:client:setHouseConfig` | `houseConfig` | Receive house information for previews |

For example, the verified
[qb-multicharacter server flow](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/server.lua)
uses this handoff for a returning character when `qb-apartments` is not started:

```lua
-- From qb-multicharacter's existing, authenticated player-loading flow.
TriggerClientEvent('qb-spawn:client:setupSpawns', src, cData, false, nil)
TriggerClientEvent('qb-spawn:client:openUI', src, true)
```

This is an **integration reference**, not a new public event handler to register. Keep character
ownership checks and login on the server. The upstream spawn resource uses NUI callbacks such as
`setCam` and `spawnplayer` internally; they are not public server APIs. It does **not** register
`qb-spawn:client:forceSpawn` or `qb-spawn:client:spawnSelected` in the verified revision.

## Player Experience

For a returning player, the login flow restores character data, populates spawn choices, then opens
the selector. Selecting the saved position uses the player's persisted position and inside-house or
inside-apartment metadata. A public spawn uses the selected `QB.Spawns` entry.

A newly created character may be routed to apartment selection instead, depending on the active
`qb-multicharacter` and `qb-apartments` setup. Do not assume both flows execute for every login.

## Troubleshooting

| Symptom | What to check first |
| --- | --- |
| Spawn selector never opens | Check the first error in F8/server logs, `qb-core` startup, character login and whether `qb-spawn:client:openUI` is triggered |
| Public location missing | Edit `QB.Spawns` in `qb-spawn/config.lua`, not an unrelated `Config` table; check syntax and restart |
| House option missing | Confirm house data and `qb-spawn:server:getOwnedHouses`; check the `player_houses` schema expected by your installed housing revision |
| New character bypasses spawn selection | Check `Config.SkipSelection` in **qb-multicharacter** and the apartment flow; that setting does not belong to qb-spawn |
| Camera or NUI becomes stuck | Inspect the earliest NUI/client error; compare your modified `client.lua` and `html` files with upstream before adding more callbacks |
| Return-to-last-position fails | Verify QBCore saved position and `metadata.inside`, then examine housing/apartment integration |

For broader diagnosis, use [resource debugging](/docs/development/debugging),
[resource load order](/docs/troubleshooting/resource-load-order), and
[character loading issues](/docs/troubleshooting/multicharacter-loading).

## Frequently Asked Questions

### How do I add a qb-spawn location?

Add a keyed entry to `QB.Spawns` in `qb-spawn/config.lua` with `coords`, `location`, and `label`.
Check your coordinates in a test server, restart the resource, and open the selector.

### How do I change the default spawn?

The verified `qb-spawn` source does not define a `Config.DefaultSpawn` option. For the fallback
location used when no starting apartment is enabled, inspect
[qb-multicharacter's `Config.DefaultSpawn`](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/config.lua)
instead. Public selectable points are configured in `QB.Spawns`.

### Why does my player always load into an apartment?

Character creation and apartment selection are coordinated by `qb-multicharacter` and
`qb-apartments`. Verify the installed server's apartment startup and `Apartments.Starting`
configuration before changing the spawn selector.

## Related Resources

- [qb-multicharacter](/docs/resources/qb-multicharacter) — character selection and login
- [qb-apartments](/docs/resources/qb-apartments) — new-character apartments
- [qb-houses](/docs/resources/qb-houses) — owned-house locations
- [qb-core](/docs/resources/qb-core) — player lifecycle and persistence
- [Troubleshooting: character loading](/docs/troubleshooting/multicharacter-loading)

## Sources

- [qb-spawn source (pinned revision)](https://github.com/qbcore-fivem/qb-spawn/tree/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00)
- [qb-spawn config.lua](https://github.com/qbcore-fivem/qb-spawn/blob/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00/config.lua)
- [qb-spawn client.lua](https://github.com/qbcore-fivem/qb-spawn/blob/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00/client.lua)
- [qb-spawn server.lua](https://github.com/qbcore-fivem/qb-spawn/blob/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00/server.lua)
- [qb-spawn fxmanifest.lua](https://github.com/qbcore-fivem/qb-spawn/blob/0cb18b1ea2d6b55bdfec45abd6c3002f88173f00/fxmanifest.lua)

Source reviewed on 2026-10-09. Examples have **not** been tested against a live FiveM server;
compare your deployed commit and dependencies before production use.
