# qb-apartments: starting housing and character spawn

`qb-apartments` provides starter apartments for character onboarding and a player-accessible apartment interior, stash, wardrobe and doorbell. This reference follows [upstream commit d9d40ba](https://github.com/qbcore-fivem/qb-apartments/tree/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb), not a furniture/rent/real-estate addon with a different database.

## Installation and dependency order

The [manifest](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/fxmanifest.lua) explicitly depends on `qb-core`, `qb-interior`, `qb-clothing` and `qb-weathersync`. It also loads `oxmysql` on the server and `PolyZone` on the client. Start those before `qb-apartments` and verify the related `qb-multicharacter`/`qb-spawn` flow.

1. Back up the database and import the official [`qb-apartments.sql`](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/qb-apartments.sql) only after checking your existing schema.
2. Start dependencies, then `qb-apartments`.
3. Test initial character creation, apartment selection, saving a character, opening a stash and logging out/in with the same character.
4. Verify another character cannot access the original character's stored inventory.

## Configuration uses `Apartments`, not `Config`

The current [`config.lua`](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/config.lua) defines:

| Setting | Default/role |
| --- | --- |
| `Apartments.Starting` | `true` — starting-apartment selection |
| `Apartments.SpawnOffset` | `30` — interior spawn offset |
| `Apartments.Locations` | Indexed apartment definitions; keys like `apartment1` |
| `Apartments.Locations.apartment1.label` | Example label `South Rockford Drive` |
| `coords.enter` | Door position and heading |
| `polyzoneBoxData` | Door interaction geometry, distance and debug options |

~~~lua filename="config.lua"
-- Edit the existing file, not a new Config.Apartments table:
Apartments.Starting = true
Apartments.SpawnOffset = 30
-- Apartments.Locations.apartment1.label = 'South Rockford Drive'
~~~

The upstream resource does **not** define built-in `Config.RentPayment`, `Config.UtilityBills`, `Config.Furniture` or `Config.EnableGarages`. These refer to a different housing system, not this source.

## Database tables and player ownership

The bundled SQL creates **one** resource-owned table, `apartments`, with `name`, `type`, `label` and `citizenid` fields (plus the numeric primary key). Outfit data is read from `player_outfits`, which is owned by `qb-clothing`. The server's apartment-stash integration belongs to the installed `qb-inventory`, not a newly invented `CreateStorage` export.

An apartment is associated with a QBCore `citizenid`. Check that identifier, the apartment name/type and its interior routing bucket before changing any save/entry flow.

## Current client/server events

[`server/main.lua`](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/server/main.lua) registers internal events under two historical prefixes: `apartments:server:CreateApartment`, `UpdateApartment`, `openStash`, `RingDoor`, `OpenDoor`, `setCurrentApartment` and `qb-apartments:server:SetInsideMeta`. Its QBCore callbacks include `apartments:GetOwnedApartment`, `GetAvailableApartments`, `GetApartmentOffset`, `IsOwner` and `GetOutfits`.

The [client](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/client/main.lua) registers `apartments:client:setupSpawnUI`, `SpawnInApartment`, `EnterApartment`, `LeaveApartment`, `OpenStash` and `ChangeOutfit`.

**These are internal events/callbacks, not externally supported server exports.** Client-chosen apartment IDs, contents or routing buckets should never be treated as sufficient proof of ownership or entry permission.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Spawn selector doesn't appear | `Apartments.Starting`, `qb-multicharacter` and `qb-spawn` event sequence |
| Entering an apartment shows the wrong interior | `qb-interior` shell, `SpawnOffset` and player routing bucket |
| Stash inaccessible | `qb-inventory` version, `apartments:server:openStash` and citizen ID |
| Wardrobe empty | `player_outfits` table and the currently loaded citizen ID |
| Apartment disappears after reconnect | `apartments` SQL row and server callback |
| No such export `CreateApartment` | This is a registered internal event, not an export |

## Update checklist

1. Pin `qb-apartments`, `qb-core`, `qb-interior`, `qb-clothing` and character selection versions.
2. Preserve apartment SQL and custom `Apartments.Locations` before an upgrade.
3. Test two characters, apartment spawn, outfits, stash, logout/reconnect and visitor access.
4. Audit ownership and routing-bucket updates on the **server**.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-apartments/tree/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb) · [Manifest](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/fxmanifest.lua) · [Configuration](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/config.lua) · [SQL](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/qb-apartments.sql) · [Server callbacks](https://github.com/qbcore-fivem/qb-apartments/blob/d9d40baaa69ecf556e270f6fcc3accaffbee6ebb/server/main.lua)

Related: [character loading issues](/docs/troubleshooting/multicharacter-loading), [qb-clothing](/docs/resources/qb-clothing).
