> For the complete documentation index, see [llms.txt](https://tk-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tk-scripts.gitbook.io/docs/tk_housing/setup.md).

# Setup

Install Housing on an ESX, QBCore or Qbox FiveM server, upgrade from Housing V2 and update without losing your config.

## Requirements

Required:

* ESX (`es_extended`), QBCore (`qb-core`) or Qbox.
* oxmysql or mysql-async.
* `tk_housing_props`, which comes with your purchase on the Cfx.re Portal.
* [K4MB1 Starter Shells](https://k4mb1maps.com/product/5015840), used by the default interiors in `config/interiors.lua`.

Optional:

| Resource                                         | Needed for                                            | Setting                                                                                                |
| ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `ox_inventory`, `qb-inventory` or `qs-inventory` | Items, stashes, house keys and furniture items        | `Config.Inventory`: `'ox'`, `'qb_old'`, `'qb_new'` or `'qs'`                                           |
| `ox_lib`                                         | ox\_lib text UI, notifications and vehicle properties | `Config.UseOxLib = true` or `Config.NotificationType = 'ox'`, plus a line in `fxmanifest.lua` (step 6) |
| `ox_target` or `qb-target`                       | Target zones instead of key prompts                   | `Config.Target = 'ox'` or `'qb'`                                                                       |
| `screenshot-basic` and a Fivemanage token        | Property and picture-frame photos taken in game       | [Set up property photos](#set-up-property-photos)                                                      |
| A clothing script                                | Wardrobes and mirrors                                 | `Config.Clothing`, 12 scripts listed in the config                                                     |
| A weather script                                 | Fixed weather and time inside properties              | `Config.Weather`                                                                                       |
| `tk_dispatch` or `cd_dispatch`                   | Break-in alerts to police                             | `Config.Dispatch = 'tk'` or `'cd'`                                                                     |
| `jg-advancedgarages`                             | Its garage menu in property garages                   | `Config.Garage.menu = 'jg-advancedgarages'`                                                            |

## Install

1. Download `tk_housing` and `tk_housing_props` from the [Cfx.re Portal](https://portal.cfx.re/assets/granted-assets), and the K4MB1 Starter Shells from K4MB1.
2. Put the folders in your `resources` folder. Keep the name `tk_housing`.
3. In `server.cfg`, add the `setr` line and start `tk_housing` after its dependencies. Use `qb-core` or `qbx_core` in place of `es_extended`, and leave out the optional resources you do not run:

   ```
   setr game_enableDynamicDoorCreation "true"

   ensure oxmysql
   ensure es_extended
   ensure ox_lib
   ensure ox_target
   ensure screenshot-basic
   ensure tk_housing_props
   ensure tk_housing
   ```

   Start the K4MB1 shell resource before `tk_housing` too. Without the `setr` line, doors placed in the Shell Creator do not work.
4. Import `tk_housing.sql` into your server database. Coming from Housing V2, follow [Upgrade from Housing V2](#upgrade-from-housing-v2) instead.
5. In `config/config.lua`, set `Config.Framework` to `'esx'` or `'qb'` (also for Qbox), then `Config.Inventory`, `Config.Target`, `Config.Clothing` and `Config.Weather` to the scripts you run.
6. With `Config.UseOxLib = true` or `Config.NotificationType = 'ox'`, uncomment this line in `shared_scripts` of `fxmanifest.lua`:

   ```lua
   '@ox_lib/init.lua',
   ```
7. Put your real-estate job names in `Config.Jobs.realEstate`, your police jobs in `Config.Jobs.police`, and your admin groups in `Config.AdminGroups`.
8. Add the items, and copy their icons from `tk_housing/images/` into your inventory's image folder. `furniture` and `house_key` need item metadata, so they work only with `Config.Inventory` set to something other than `'default'`.

   The config also names `lockpick` (lockpicking), `security_tablet` (door camera) and `wire_tool` (wiring, when `Config.Electricity.wiring.requireItem` is `true`). Add the ones your inventory lacks.

## Set up property photos

Listing and picture-frame photos taken in game upload to Fivemanage. Image links work without a token.

1. Start `screenshot-basic` before `tk_housing` in `server.cfg`.
2. In [Fivemanage](https://docs.fivemanage.com/getting-started), create a team and a token on its **Tokens** page.
3. In `tk_housing/config/server.lua`, paste the token between the quotes:

   ```lua
   ConfigSV.FivemanageToken = 'YOUR_TOKEN'
   ```

## Update without losing your config

Your changes live in `config/*.lua`, `locales/*.lua`, `client/main_editable.lua`, `server/main_editable.lua`, `client/frameworks/*.lua` and `server/frameworks/*.lua`. Shells built in the Shell Creator are saved in `data/shells.json` (or `shells.json` when `data/` cannot be written), and the shell editor writes into `config/interiors.lua`.

1. Copy the whole `tk_housing` folder somewhere outside `resources`, and back up the database.
2. Download the new version from the Cfx.re Portal and replace the `tk_housing` folder. Update `tk_housing_props` too.
3. Copy `data/shells.json` and `shells.json` from the backup into the new folder.
4. Copy your values from the backup into the new `config/*.lua` one option at a time. Keep your own `config/interiors.lua` entries.
5. Move your own code in the editable functions into the new `client/main_editable.lua` and `server/main_editable.lua`.

Database changes between versions run by themselves when `tk_housing` starts.

## Upgrade from Housing V2

V2 kept its settings in `config.lua` and `config_sv.lua` at the resource root; V3 uses `config/config.lua` and `config/server.lua`.

1. Back up the database and the V2 `tk_housing` folder.
2. Replace the folder with V3 and install as in [Install](#install), but do not import `tk_housing.sql`.
3. Copy your V2 values into the V3 config files one option at a time. Do not copy the V2 files over the V3 ones.
4. Start the server. V3 moves every property's furniture and garage vehicles to the new tables and keeps the old columns as `*_legacy` backups.
5. After players confirm their houses, run [housing\_dropbackups](/docs/tk_housing/commands.md#housing_dropbackups) in the server console to list the backup columns, then `housing_dropbackups confirm` to drop them.

If the console prints `verification FAILED` or a `migration WARNING` line, keep the backups and see [Common problems](/docs/tk_housing/common-questions-and-problems.md#common-problems).