Documentation
Install Shell Creator on your FiveM server: requirements, qs-shellcreator-props, server.cfg load order, the qs_shells SQL table, admin access for ESX, QBCore, Qbox and FiveManage cover photos.
Before installing Shell Creator, make sure your server meets the minimum requirements.
Requirement | Status | Notes |
|---|---|---|
OneSync | Required | Declared as a dependency; the resource will not start without it. |
oxmysql | Required | Stores every saved shell in the |
ox_lib | Required | Callbacks, classes and text UI. |
qs-shellcreator-props | Required | Included in the download. Streams every wall, floor, stair, window, light and furniture model the builder uses. |
screenshot-basic | Required | Every save takes an aerial photo of the build for the shell manager. |
FiveManage token | Recommended | Where that photo is uploaded. Without it shells still save, just with no cover picture. |
Framework | Optional | ESX, QBCore or Qbox — auto-detected and used for admin checks. Standalone uses ACE permissions. |
Housing script | Optional | Where players will actually live in your shells: QS, RTX, PS, VMS Housing, ESX Property or any other. |
The framework is chosen by looking at what is already running, in this order:
Resource found | Bridge used |
|---|---|
|
|
|
|
none of them |
|
After purchasing Shell Creator, 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 Shell Creator. With a different account the asset will not appear.
After extracting the download, you should have these two folders:
qs-shellcreator/
├── config/ -- main.lua and builder.lua (what you may edit)
├── custom/ -- framework bridges, text UI, HUD (editable)
├── client/custom/ -- weather freeze and other client hooks (editable)
├── server/webhooks.lua -- the FiveManage token
├── locales/ -- 25 languages
├── textures/ -- your own wall and floor PNGs
└── web/ -- the interface, already built
qs-shellcreator-props/
└── stream/ -- walls, floors, stairs, windows, lights, furnitureKeep the folder named
qs-shellcreator. The interface loads its images and textures fromnui://qs-shellcreator/web/and the exports are called asexports['qs-shellcreator'], so a renamed copy shows empty pictures.
Move both folders into your server's resources directory. They can live anywhere inside it, including a category folder:
resources/
└── [qs]/
├── qs-shellcreator/
└── qs-shellcreator-props/Then open your server.cfg and start everything in this order:
ensure oxmysql
ensure ox_lib
ensure screenshot-basic
# Framework
ensure es_extended
# ensure qb-core
# ensure qbx_core
ensure qs-shellcreator-props
ensure qs-shellcreator
# Your housing script goes after Shell Creator
# ensure qs-housingThe loading order matters. The framework is detected only if it is already started, so a framework that starts later leaves Shell Creator in standalone mode — and then only players with the command ace can open it.
So that the doors you place inside a shell open and close like real doors instead of standing as static props, add this line to your server.cfg:
setr game_enableDynamicDoorCreation "true"Run this in HeidiSQL, phpMyAdmin or any MariaDB/MySQL client against your server's database. Avoid XAMPP and similar non-optimised local servers, which cause connection errors.
CREATE TABLE IF NOT EXISTS `qs_shells` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`label` VARCHAR(50) NULL DEFAULT NULL,
`creator` VARCHAR(80) NULL DEFAULT '0',
`data` LONGTEXT NULL DEFAULT NULL,
`image` LONGTEXT NULL DEFAULT NULL,
`coords` LONGTEXT NULL DEFAULT NULL,
`created_at` TIMESTAMP NOT NULL DEFAULT current_timestamp(),
`updated_at` TIMESTAMP NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),
`has_void` TINYINT(1) NOT NULL DEFAULT '1',
PRIMARY KEY (`id`) USING BTREE
)
COLLATE='utf8mb3_general_ci'
ENGINE=InnoDB
AUTO_INCREMENT=1;Column | Holds |
|---|---|
| The shell's number. Its model is always |
| The name you gave it, and the identifier of the admin who saved it. |
| The whole build: floors, tiles, walls, doors, windows, stairs, furniture, textures and the spawn point. |
| The URL of the cover photo. |
| Where the shell stands in the world. Picked automatically: every shell gets its own spot at height 800, at least 300 m from any other. |
| Whether a dark void box is spawned around the shell so the sky and the map are not visible through the windows. |
Building and managing shells is for staff only. Who counts as an admin depends on the framework that was detected:
Players in the admin or superadmin group. Set it with your usual ESX tool, for example:
setgroup <server id> adminPlayers with the god or admin permission, or with the command ace (txAdmin's admin group has it).
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.adminPlayers with the command ace.
add_ace identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx command allowThe check lives in custom/<framework>/server.lua as framework:playerIsAdmin. It is checked again by the server on every save, edit and delete, so changing it on the client alone does nothing. Integrations shows how to use your own rule.
When a shell is saved, the camera rises over the build, takes a photo and uploads it, so every shell in the manager has a picture. The upload goes to FiveManage.
Make an account at fivemanage.com and generate an API token for images.
_G['fivemanage'] = {
token = 'your-fivemanage-token'
}The token is read on the server only and never sent to players.
Everything you can tune sits in a handful of unencrypted files:
File | Contents |
|---|---|
| Language, framework, the object limit, the builder grid, the export formats, debug and the editor keybinds. |
| The catalogue of the builder: wall, floor and roof finishes, construction pieces, doors, windows, stairs, lights and furniture. |
| The FiveManage token. |
| Notifications, text UI, progress bar and hiding the HUD. |
| Who is an admin, and which identifier is stored as the creator. |
| Freezes the weather and time while building. |
| Your own finishes — see Custom Textures. |
The values worth reviewing first, in config/main.lua:
Config.Locale = 'en' -- any file in locales/
Config.CustomTextureEnabled = true -- load your PNGs from textures/
Config.MaxObjects = 800 -- lower it if players crash (pool size)
Config.Debug = true -- set to false on a live server
Config.GridSystem = {
gridSize = 25, -- tiles per side of the workspace
gridSpacing = 2.07, -- size of one tile, matched to the props
gridCenter = vector3(-1559.93, -2605.01, 1213.0), -- where the workspace floats
}Set
Config.Debug = falsebefore opening to players. Debug mode prints extra console output and registers the/testshelland/change_offsetdeveloper commands.
Restart your server and look at the console. You should see the framework that was picked:
[INFO] Successfully loaded the framework. esx
You are using the latest version of qs-shellcreator!standalone when you do run ESX or QBCore means the framework started after Shell Creator — move it above ensure qs-shellcreator. An oxmysql error mentioning qs_shells means the table was not imported into the database your server uses.
Then join your server and build your first shell:
Type /shellcreator. The shell manager opens with the list of saved shells — empty on a fresh server.
Press create. You are taken to the builder's workspace in the sky: lay a few foundation tiles, add a door and place the spawn point.
Save, give it a name, and open it in the manager: pick your housing script under Export Code and copy the result. Usage covers every tool in detail.
Nothing needs a restart after this. New shells, edits and deletions reach every connected player as soon as they are saved.