Before You Begin#
Before installing City Builder, make sure your server meets the minimum requirements below. The resource will not start if a required dependency is missing.
Requirement | Status | Notes |
|---|---|---|
| Required | Declared in the manifest. The resource refuses to start without it. |
| Required | Saves placed objects and custom furniture. |
| Required | Callbacks, text UI and shared helpers. |
| Required | Declared in the manifest; used by the Furniture Creator's photo studio. |
Framework | Required | ESX, QBCore or Qbox — auto-detected. Used for admin checks, jobs and money. |
Inventory | Optional | Needed for props that work as stashes. |
Clothing script | Optional | Needed for props that work as wardrobes. |
FiveManage account | Optional | Only to upload the photos the Furniture Creator takes. You can always paste an image URL by hand instead. |
Everything framework- or third-party-specific sits behind a small bridge file, and the right one is picked when the resource starts:
Layer | Detected resources |
|---|---|
Framework | es_extended · qb-core · qbx_core |
Inventory | qs-inventory · qb-inventory · ps-inventory · ox_inventory · core_inventory · codem-inventory · inventory (Chezza) · origen_inventory · tgiann-inventory |
Clothing | qs-appearance · qb-clothing · codem-appearance · ak47_clothing · fivem-appearance · illenium-appearance · raid_clothes · rcore_clothes · rcore_clothing · sleek-clothestore · tgiann-clothing · p_appearance |
The full list, and how to add your own, is on the Integrations page.
github.comReleases · overextended/oxmysqlMySQL resource for FXServer.github.comReleases · overextended/ox_libA FiveM resource and script library for Lua and JS.github.comcitizenfx/screenshot-basicFiveM client screenshot resource.Downloading City Builder#
After purchasing City Builder, 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 City Builder.
After extracting the download, you should have the following folders:
[citybuilder]/
├── [sql]/
│ └── database.sql -- the two tables to import
└── qs-citybuilder/
├── config/ -- what you may edit
├── client/custom/ -- inventory and clothing bridges
├── custom/ -- framework bridges, notifications, text UI
├── locales/ -- 27 languages
├── stream/ -- the photo studio models
└── web/ -- the interface, images and soundsThe folder must be named
qs-citybuilder. The interface loads its images fromnui://qs-citybuilder/web/, so a renamed folder shows a catalogue with no pictures.
Installing the Resource#
Move the qs-citybuilder folder into your server's resources directory. It can live anywhere inside it — a category folder such as [qs] is fine.
resources/
└── [qs]/
└── qs-citybuilder/Once copied, open your server.cfg and make sure every dependency — and every resource it should detect — starts before City Builder:
ensure oxmysql
ensure ox_lib
ensure screenshot-basic
# Framework
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Inventory and clothing
ensure ox_inventory
ensure illenium-appearance
ensure qs-citybuilderThe loading order matters. Detection only sees resources that are already started, so an inventory that starts after City Builder is never picked and stashes will not open.
The Database#
Import [sql]/database.sql into your server's database once, before the first start. It creates two tables:
Table | Holds |
|---|---|
| Every object placed in the world: model, position, rotation, whether it is put away, who placed it and when. |
| The props added with the Furniture Creator: category, model, label, price, image, colour variants, stash and wardrobe settings. |
database.sql (ESX and QBCore)
DROP TABLE IF EXISTS `qs_city_objects`;
CREATE TABLE `qs_city_objects` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`creator` VARCHAR(80) NULL DEFAULT NULL,
`category_key` VARCHAR(100) NOT NULL,
`object` VARCHAR(200) NOT NULL,
`label` VARCHAR(255) NOT NULL,
`description` TEXT NULL DEFAULT NULL,
`price` INT(11) NOT NULL DEFAULT '0',
`img` TEXT NULL DEFAULT NULL,
`colorlabel` VARCHAR(255) NULL DEFAULT NULL,
`type` VARCHAR(50) NULL DEFAULT NULL,
`stash` LONGTEXT NULL DEFAULT NULL,
`offset` LONGTEXT NULL DEFAULT NULL,
`colors` LONGTEXT NULL DEFAULT NULL,
PRIMARY KEY (`id`) USING BTREE,
INDEX `creator` (`creator`) USING BTREE,
INDEX `category_key` (`category_key`) USING BTREE
) COLLATE='utf8mb4_unicode_ci' ENGINE=InnoDB;
DROP TABLE IF EXISTS `qs_citybuilder_decorations`;
CREATE TABLE `qs_citybuilder_decorations` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`creator` VARCHAR(80) NULL DEFAULT NULL,
`modelName` VARCHAR(200) NOT NULL,
`coords` LONGTEXT NOT NULL,
`rotation` LONGTEXT NOT NULL,
`inStash` TINYINT(1) NOT NULL DEFAULT 0,
`inside` TINYINT(1) NOT NULL DEFAULT 0,
`created` DATETIME NULL DEFAULT NULL,
`uniq` VARCHAR(120) NULL DEFAULT NULL,
`lightData` LONGTEXT NULL DEFAULT NULL,
PRIMARY KEY (`id`) USING BTREE,
INDEX `creator` (`creator`) USING BTREE
) COLLATE='utf8mb4_unicode_ci' ENGINE=InnoDB;The file starts with
DROP TABLE IF EXISTS. Importing it again on a live server deletes every placed object and every custom prop. When you update the script, do not re-import it unless the changelog tells you to.
Who Can Build#
Decoration mode and the Furniture Creator are both behind the same check. A player gets in if either of these is true:
Automatic, nothing to configure.
ESX — players in the
adminorsuperadmingroup.QBCore / Qbox — players with the
godoradminpermission, or thecommandace.
Give a job — a city planner, an interior designer, an events team — access without making them admins. grade is a list of allowed grades, or false for every grade.
-- config/config.lua
Config.CreatorJobs = {
{ job = 'realestate', grade = { 3, 4 } }, -- only grades 3 and 4
{ job = 'designer', grade = false }, -- every grade
}Configuring the Resource#
All settings live in four files under config/. Each line is tagged [EDIT] (safe to change), [ADV] (change only if you know why), or [CORE] / [AUTO] (leave alone).
File | Contents |
|---|---|
| Language, detection, money, builder jobs, sounds and music, price formatting, the default stash size, editor keys and camera speeds, debug. |
| How far objects stream in, how far the camera may fly, and dynamic doors. |
| The furniture catalogue: the five rooms, every category, every prop, its price and its behaviour; custom prop events. |
| Your FiveManage token, for photo uploads. Server-side only. |
The values worth reviewing first:
-- config/config.lua
Config.Locale = 'en' -- ar, bg, cs, da, de, el, en, es, fa, fr, he, hi, hu, it, jp,
-- ko, nl, no, pl, pt, ro, ru, sl, sv, tk, tr, zh-CN
Config.EnableMoney = false -- true = props cost money and selling pays a commission
Config.MoneyType = 'money' -- 'money' (cash) or 'bank'
Config.SellObjectCommision = 0.3 -- selling returns 30 % of the price
Config.EnableF3Shop = true -- false = staff can only manage placed objects, not add new ones
Config.FurniCreatorCommand = 'citybuilderfurniture'
Config.DefaultStashData = { maxweight = 1000000, slots = 30 } -- for stash props with no size of their own
-- config/decorate.lua
Config.SpawnDistance = 30.0 -- placed objects appear within 30 m of a player
Config.MaximumDistanceForDecorate = 350.0 -- the camera may fly 350 m from where you opened the builder
Config.DynamicDoors = trueEvery file under
config/is read when the resource starts. After editing one, restartqs-citybuilder— placed objects and custom props are in the database and are not lost.
Photo System Setup (FiveManage)#
The Furniture Creator can photograph a prop and upload the picture for you. Uploads go to FiveManage. Skip this section if you prefer to paste image URLs by hand.
Update the CFX server resources
Download the latest default resources from cfx-server-data and replace the old ones on your server, so
screenshot-basicis up to date.Clear the server cache
Stop the server, open the folder that holds
server.cfgand delete thecachefolder.Add your FiveManage token
Create an account at FiveManage, generate an API token, and paste it in
config/fivemanage.lua:lua Config.FiveManageToken = 'your-fivemanage-token'The file is loaded on the server only, and the token is handed to the interface only for players allowed to use the Furniture Creator.
This video walks through creating the account and the token:
youtube.comFIVEMANAGE | Token creation at fivemanage.comA short tutorial for creating a token in fivemanage.com.
Dynamic Doors#
Door props placed with City Builder can swing open like real doors instead of staying frozen. It takes two switches:
Server configuration
Add this line to
server.cfg:bash setr game_enableDynamicDoorCreation "true"Script configuration
Keep it enabled in
config/decorate.lua, and mark the door props in the catalogue withisDoor = true(see Usage → The Furniture Catalogue).lua Config.DynamicDoors = true
Verifying the Installation#
Restart your server and read the console. A healthy start prints:
[INFO] Successfully loaded the framework. esx
GARAGES INFO: Furniture Creator initialized: 0 custom items loaded
You are using the latest version of qs-citybuilder!The framework line names esx or qb (Qbox also reports qb). The second line counts the props added with the Furniture Creator. If either line is missing, read the console from the top — the first red line is the cause.
Then join your server as an admin and work through the first loop:
Open the builder
Type
/citybuilder. The camera detaches from your character and the decoration panel opens at the bottom of the screen.Place a prop
Pick a room, a category and a prop. It appears in front of the camera — hold the left mouse button to drag it, press G to drop it on the ground, then Enter to buy and place it.
Check it is shared
Ask a second player to walk over: the prop is already there for them. Restart the resource and it is still there.
Placing, moving, selling and adding props never needs a restart. Only edits to the files under
config/do.