Documentation
Install Billiards (qs-billiards) on FiveM: requirements, server.cfg load order, OneSync, the self-creating qs_pool_tables table and the poolcreator ACE.
Before installing Billiards (Pool), make sure your server meets the minimum requirements. Two resources and OneSync are mandatory; everything else is optional and detected on its own.
Requirement | Status | Notes |
|---|---|---|
| Required | Database access. The table installs itself. |
| Required |
Callbacks, the Pool menu and the default notifications. |
OneSync | Required | The resource will not start without it. txAdmin turns it on by default. |
Framework | Optional | ESX, QBCore or Qbox — auto-detected. Without one it runs standalone: every table is free and bets are neither taken nor paid. |
| Optional | Quasar Interface notifications instead of ox_lib's. |
| Optional | Quasar Text UI for the [E] prompt above the table, instead of the built-in floating text. |
Everything framework- or third-party-specific sits behind a small, unencrypted bridge file, and the resource picks the right one by looking at what is already running:
Layer | What is looked for |
|---|---|
Framework |
|
Notifications |
|
Table prompt |
|
Every optional integration degrades silently. If a resource is missing, that part falls back to the built-in version — nothing errors. Integrations has the details and how to plug in your own.
After purchasing Billiards (Pool), 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 Billiards.
After extracting the download, you should have the following folder:
qs-billiards/
├── config/ -- config.lua, what you may edit
├── client/custom/ -- notifications, the table prompt and the menu (editable)
├── server/custom/ -- money, permission and names per framework (editable)
├── locales/ -- 41 languages (editable)
├── database/ -- sql.sql, optional
└── web/ -- the in-game interfaceKeep the folder named
qs-billiards. Updates are delivered under that name, the version check looks it up by that name, and every path and command in this manual refers to it. Onlyconfig/,client/custom/,server/custom/andlocales/are open for editing; the rest is protected by the Cfx escrow.
Move the qs-billiards folder into your server's resources directory. It can live anywhere inside it, including a category folder:
resources/
└── [qs]/
└── qs-billiards/Once copied, open your server.cfg and make sure every dependency — and everything it should detect — starts before Billiards:
# OneSync must be on. txAdmin does this for you; on a plain server.cfg:
set onesync on
ensure oxmysql
ensure ox_lib
# Framework
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Optional
ensure qs-interface
ensure qs-textui
ensure qs-billiardsThe loading order matters. The framework is detected the moment Billiards starts, and qs-textui the moment a player loads it, so a framework that starts later is not found and the script runs as standalone — free tables, no money taken.
There is no SQL file to import. Every time it starts, Billiards makes sure its one table, qs_pool_tables, exists and creates it if it does not. database/sql.sql holds the same statement for anyone who prefers to create it by hand.
Column | Holds |
|---|---|
| The table's id, worked out from its position — for example |
| Position and heading, stored as JSON. |
| The table prop's model hash. |
| The name shown in the creator. |
| The entry fee. |
|
|
| The modes offered at this table, as a JSON list of |
Only tables placed with the creator — or edited in it — get a row. Tables written in
Config.Tablesand tables that come from a map are registered again each time a player loads in, so they need none. Games are never written to the database: they live in the server's memory while they are played.
The creator is where tables are placed, priced and deleted, so /poolcreator needs the ACE permission command.poolcreator. The server checks it again before it saves, moves or deletes a table, so nobody without it can change a table, whatever their client sends. Any of these routes grants it:
The usual route. Give the permission to your admin group, and put your staff in that group:
add_ace group.admin command.poolcreator allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.adminIf your server.cfg already has add_ace group.admin command allow — as most txAdmin recipes do — your admins have it already.
For a single map builder who should not be an admin:
add_ace identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx command.poolcreator allowPrefer a permission name of your own? Change it in the config and grant that one instead:
-- config/config.lua
Config.Creator = {
permission = 'qs.poolcreator',
-- models = { ... },
}add_ace group.admin qs.poolcreator allowRestart the server after changing ACEs. The permission only covers the creator: the calibration commands are switched on by Config.Debug instead — see Commands and Controls.
Everything lives in one file, config/config.lua. It is read when the resource starts, so restart qs-billiards after changing it.
Setting | Controls |
|---|---|
| The language of the notifications and the interface. One of 41 codes. |
| Detected on its own. Set |
| How close the [E] prompt appears (2 m from the centre of the cloth) and how far tables, balls and other players' shots render (60 m). |
| The entry fee for tables with no price of their own: config tables and map tables. |
| The area a player must stay in while playing: a circle of 8 m around the table, drawn on the floor. Walking out of it ends the game. |
| Which modes appear in Match Settings, how many players each one seats, and the score Straight Pool is played to. |
| The bet slider (0 to 5,000 in steps of 100) and what a win against the bot pays at each difficulty. |
| The bot's ped models, whether bets are paid in cash or from the bank, the difficulties offered and how well each one plays. |
| Tables written in the config, and whether pool tables already in your maps are picked up on their own. |
| The ACE permission and the table models offered in the creator. |
| The keys used at the table, as FiveM control indices. |
| Ball physics, where the cloth is on each table model, the shooter's stance and the cue. Tuned for the shipped tables. |
| Hides loose map cues, triangles and cue balls within 1.6 m of every table. |
| Debug drawing and the calibration commands. Keep it |
The values worth reviewing first:
Config.Locale = 'en' -- en · es · fr · de · pt · and 36 more
Config.InteractDistance = 2.0 -- how close the [E] prompt appears
Config.PlayPrice = 0 -- fee for config and map tables, 0 = free
Config.LeaveZone = {
enabled = true,
shape = 'circle', -- 'circle' or 'square'
distance = 8.0, -- walk further than this and the game ends
draw = true, -- draw the boundary on the floor
}
Config.Modes = {
eightball = { enabled = true, players = 2, turnBased = true },
nineball = { enabled = true, players = 4, turnBased = true },
straight = { enabled = true, players = 4, turnBased = true, target = 25 },
practice = { enabled = true, players = 1, turnBased = false },
}
Config.Betting = { enabled = true, min = 0, max = 5000, step = 100 }
Config.BotRewards = { difficulty = { easy = 0.5, normal = 1.0, hard = 2.0 } }
Config.Bot = {
pedModels = { `a_m_y_stbla_01`, `a_m_m_business_01`, `a_m_y_hipster_01`, `s_m_y_dealer_01` },
betMethod = 'money', -- bets in 'money' (cash) or 'bank'
}
Config.Debug = false
Config.Physics,Config.Surfaces,Config.PedandConfig.Cueare tuned for the two tables that ship with the script. Leave them alone unless you add a table model or the shooter's pose looks wrong on your peds — the calibration commands in Usage print the new values for you.
After completing the installation, restart your server and look for these lines in the console:
[qs-billiards] Loaded 0 table(s) from SQL.
You are using the latest version of qs-billiards!0 is right on a new server: no table has been placed yet. If the first line never appears, oxmysql is not connected or starts after Billiards. The second one tells you whether an update is available.
Then join your server and work through the first loop:
Type /poolcreator, press +, give the table a name, pick a model and press Select under Placement. Aim at the floor, turn it with Z and X, and left-click. Back in the creator, press Save Table. The table appears where you aimed.
Walk up to the table until [E] - Set up a game of pool appears, press E and choose Play vs Bot. Pick 8-Ball and Normal, leave the bet at No Bet and press Ready. A ped takes its place at the end of the table.
You start with ball in hand: move the cue ball with W A S D and press E to place it. Turn the cue with A and D, hold the right mouse button to build power and let go to shoot.
From here, Usage covers the creator in full, the other ways to add tables, games between players, bets and the rules of each mode.