Before You Begin#
Before installing Apartments, make sure your server meets the minimum requirements. Four things are mandatory; everything else is optional and detected on its own.
Requirement | Status | Notes |
|---|---|---|
| Required | Database access. The SQL file is imported once by hand. |
| Required | Callbacks, menus, entrance zones and the cleaning progress bar. |
| Required | A declared dependency. The Furniture Creator's photo booth takes its pictures with it. |
Framework | Required |
|
Inventory | Optional | Needed for every stash — the apartment's own and the storage furniture. |
Clothing script | Optional | Opens the player's saved outfits at the wardrobe. |
Target | Optional |
|
| Optional | Styled 3D prompts. Plain drawn text otherwise. |
Spawn selector | Optional | Multicharacter, qb-spawn or Qbox's character menu — lets a new character pick a starter apartment. |
Each third-party resource is reached through a small, unencrypted bridge file, and Apartments picks the right one by looking at what is already running:
Layer | Detected resources |
|---|---|
Framework |
|
Inventory |
|
Clothing |
|
Target | Not detected — set |
Run one resource per layer. If two inventories or two clothing scripts are started, which one Apartments picks is not guaranteed. Integrations explains what each layer does and what happens without it.
github.comReleases · overextended/oxmysqlMySQL resource for FXServer.github.comReleases · overextended/ox_libA FiveM resource and script library for Lua and JS.github.comcitizenfx/screenshot-basicScreenshot resource for FiveM, used by the Furniture Creator's photo booth.Downloading Apartments#
After purchasing Apartments, the resource is automatically linked to your CFX Portal account.
Sign in to the CFX Portal using the same account used during checkout, open Granted Assets, and download Apartments.
After extracting the download, you should have the following folders:
[apartments]/
├── qs-apartments/
│ ├── config/ -- what you may edit
│ ├── client/custom/ -- bridges to other resources (editable)
│ ├── server/custom/ -- bridges to other resources (editable)
│ ├── locales/ -- 41 languages
│ ├── stream/ -- the photo booth used by the Furniture Creator
│ ├── web/ -- the interface, already built
│ └── shell_offsets.json -- the exit door of each interior
├── [maps]/
│ └── K4MB1-StarterShells/ -- the apartment interiors
└── [sql]/
└── database.sql -- the tables, imported onceKeep the folder named
qs-apartments. The interface loads its pictures fromnui://qs-apartments/web/, and Multicharacter and other resources call its exports by that name.
Installing the Resource#
Move the qs-apartments and K4MB1-StarterShells folders into your server's resources directory. They can live anywhere inside it, including a category folder:
resources/
└── [qs]/
└── [apartments]/
├── qs-apartments/
└── K4MB1-StarterShells/Once copied, open your server.cfg and make sure every dependency — and everything it should detect — starts before Apartments:
# Lets placed doors swing open (Config.DynamicDoors)
setr game_enableDynamicDoorCreation "true"
ensure oxmysql
ensure ox_lib
ensure screenshot-basic
# Framework
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Inventory, clothing, target, text UI
ensure ox_inventory
ensure illenium-appearance
ensure ox_target
ensure qs-textui
# The interiors, then Apartments
ensure K4MB1-StarterShells
ensure qs-apartments
# Spawn selectors look for Apartments, so they go after it
ensure qs-multicharacterThe loading order matters. Detection only sees resources that are already started, so an inventory or clothing script that starts after Apartments is not found. The other way round, Multicharacter only offers starter apartments when Apartments is already running.
The Database#
Apartments ships its schema as [sql]/database.sql. On a new server, import it once into your server's database with HeidiSQL or any MySQL/MariaDB client, before the first start.
Table | Holds |
|---|---|
| Who owns which apartment, its ID and label, where the stash, wardrobe and charger are, and the vault codes. |
| Every piece of furniture bought: its model, position and rotation, and whether it is put away. |
| Furniture added in game with the Furniture Creator. |
| Rubbish waiting to be cleaned. Entries older than seven days are removed automatically. |
player_apartmentskeeps the columns qb-apartments used —name,type,label,citizenid— which is what lets scripts written for qb-apartments keep reading it. On ESX,citizenidholds the player's ESX identifier.
Admin Access#
Only one part of Apartments is behind an admin check: the Furniture Creator (/apartmentfurniture), and the FiveManage token it uploads with. Everything else is for players. Who counts as an admin follows your framework:
Players whose ESX group is admin or superadmin. Set it with ESX's own command, from the server console or as an admin:
setgroup <server id> adminPlayers QBCore treats as god or admin, or anyone allowed the command ace — which the default admin group already has:
add_ace group.admin command allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.adminThe check is the PlayerIsAdmin function in server/custom/framework/esx.lua or server/custom/framework/qb.lua. Both files are open: change what it returns to use your own staff list or ace.
Configuring the Resource#
Everything is configured in files and applied when the resource restarts. Each value in the config is tagged [EDIT] (safe to change), [ADV], [CORE] or [AUTO] (leave alone).
File | Contents |
|---|---|
| Language, target, money, the buildings, the shells, stash size, decoration keys and camera, junk and the cleaning robot, debug. |
| The decoration menu: its five rooms, 40 categories and every piece with its price, stash or wardrobe. |
| Your FiveManage token, for the Furniture Creator's thumbnails. |
| Where the exit door is in each shell tier. Written from in game when you place one — see Usage. |
| The bridges: framework, inventory, clothing, target, weather sync, quests. |
| The 41 translations. |
The values worth reviewing first, in config/main.lua:
Config.Locale = 'en' -- any file in locales/
Config.UseTarget = false -- true with ox_target, qb-target or qtarget
Config.MoneyType = 'money' -- 'money' or 'bank': what furniture is paid from
Config.InitialSpawnEnabled = true -- offer a starter apartment to new characters (qb-spawn)
Config.Cleaning = true -- junk appears while somebody is home
Config.FiveGuard = false -- your FiveGuard resource name, or false
Config.Debug = false -- ships as true: turn it off on a live serverAnd your FiveManage token, in config/fivemanage.lua. The server hands it only to admins, but keep the file out of anything you share:
Config.FiveManageToken = 'your-fivemanage-token'
Config.Debugships set totrue. Leave it on while you set things up, then set it tofalse: debug prints a line for almost every action and registers thegizmo:apttest command.
Verifying the Installation#
After completing the installation, restart your server and read the console. A healthy start prints:
APARTMENTS INFO: Furniture Creator initialized: 0 custom items loadedA repeating [ERROR] Framework not found! means your framework starts after Apartments — move its ensure line above. Then join your server and work through the first loop:
Claim an apartment
Type
/Apartmentand pick one of the five buildings. You are told You have received an apartment, and every building appears on the map — yours with its own icon.Go inside
Walk to your building's door, press
Eand choose Enter Apartment. The screen fades and you are standing at the door of your interior.Make it yours
Type
/ApartmentLocation, choose Stash, stand where you want it and pressG. Then pressF9to open the decoration menu. Usage covers the rest.
Nothing players do needs a restart: apartments, points, vault codes and furniture are saved as they happen. A change to a file under
config/needsrestart qs-apartments— do it with nobody inside an apartment.