What goes wrong most often, what it actually means, and what to change to fix it. Most of these come down to load order, the ACE permission, or a table model the script has no surface for.
Installation and Access#
"You do not have permission to use /poolcreator."
Your identifier does not have the ACE command.poolcreator — or the one you set in Config.Creator.permission. Add it as shown in Installation → Granting Creator Access and restart the server; reconnecting is not enough.
The creator opens, but tables are not saved
The server checks the ACE itself before it saves, moves or deletes a table. If you rewrote HasPermission to check a framework group, that group still needs the ACE. Also make sure oxmysql is running — without it, nothing is written.
The console never prints "Loaded N table(s) from SQL."
oxmysql is not connected, or starts after qs-billiards. Fix the connection string and the order in server.cfg, then restart.
The resource does not start and asks for OneSync
Billiards needs OneSync. Turn it on in txAdmin, or add set onesync on to server.cfg.
WARNING: Locale "xx" not found, falling back to "en"
Config.Locale is not one of the 41 codes, or locales/xx.json is missing. A line about a missing key means your edited file lacks that text: it shows in English until you add it.
Tables#
A table does not appear
Tables render within 60 m (Config.StreamDistance). A model with no Config.Surfaces entry never appears, even when it is listed in Config.Creator.models — add its entry as in Integrations → Adding a Table Model. With Config.Debug on, /poolcheck tells you whether the models load in your game.
There is no [E] prompt at a table
Stand within 2 m of the centre of the cloth (Config.InteractDistance) — at the ends of the table, that means right at the rail. A table in use shows a panel in the bottom-right corner instead of the prompt. And a pool table that is part of a map is only playable with Config.AutoDetect = true.
Map tables never become playable
Config.AutoDetect is false by default. Turn it on, and make sure the map's table model is in both Config.TableModels and Config.Surfaces.
A cue, triangle or ball from the map lies on the table
Add its model to Config.HideWorldProps.models, or raise its radius if it lies further than 1.6 m from the centre of the table.
The balls are coloured spheres
The ball models could not be loaded, and the F8 console says ball model #N not available — drawing a coloured marker instead. Check with /poolcheck; another resource replacing or removing the prop_poolball_* models is the usual cause.
Every table disappeared at once
Somebody ran /poolclear while Config.Debug was on. Creator tables come back on the next restart, config and map tables when players reconnect. Turn Config.Debug off.
A table I removed from the config is still there
It was saved in the creator at some point, so it has a row in the database. Delete it from the creator.
Playing#
Balls float, sink or sit outside the cloth
Config.Surfaces does not match that table model — usually because the model is new, or a map uses a modified version of it. Fit it with /pooledit and /pooltune, or /poolbz for the height, as in Usage → Calibrating a Custom Table.
Balls bounce out of the pockets or will not drop
The pockets are too small, or their mouths too narrow, for that table. Grow them with /poolpocket r and /poolpocket m and paste the printed values into Config.Physics.
"You left the table area — the game has ended."
You walked further than 8 m from the table during a game, which ends it for everyone at the table. Raise Config.LeaveZone.distance, switch shape to 'square', or set enabled = false.
I cannot put the cue ball where I want
Ball in hand stops at the cushions and at other balls: the cue ball can go anywhere on the cloth, but it cannot overlap another ball or leave the playing area.
Nobody can join my game
Only Play vs Player tables can be joined, and only before the break. Practice and games against the bot are played alone, and a table stops taking players once it is full or the host breaks.
The shooter looks wrong to other players
Floating, sunk into the floor, or hands away from the cue: Config.Ped is tuned for standard peds. Fit it with /poolhands, /poolarms, /poolstick and /poolstickrot, or set Config.Ped.enabled = false to use GTA's standard pool-player animation instead.
A command answers "Activa Config.Debug = true para usar este comando."
That is the debug-only notice, written in Spanish. Set Config.Debug = true and restart the resource — and switch it off again when you are done.
Money and Bets#
No money is taken
Either the table's price is 0 — config and map tables use Config.PlayPrice, 0 by default — or no framework was found and the script runs standalone. A framework that starts after qs-billiards is not found: fix the order in server.cfg. On a server without one, define the three money functions in Integrations.
"Not enough cash! This table costs $X."
The player cannot pay the entry fee with the table's method. The word in the message — cash or bank — tells you which one was checked.
"Not enough money for a $X bet."
The player cannot cover the bet, paid in Config.Bot.betMethod. In a game between players it is checked when they accept and again when the game starts; if anyone falls short then, the game is called off for everybody.
Bets are taken but winners are never paid
Config.RemoveMoney is defined without Config.AddMoney. Define all three money functions together.
A pot disappeared
The resource restarted, or the table was deleted or moved, during the game. Games live in the server's memory and are not settled when they are dropped.
What the Messages Mean#
Every message comes from the notify and creator sections of the locale files, so it reads in each server's language. In English:
Message | Means |
|---|---|
Foul! You pocketed the cue ball — your opponent gets ball in hand. | A scratch. |
Foul! You hit the wrong ball first — your opponent gets ball in hand. | The cue ball hit nothing, or first hit a ball you may not play. |
Foul! No ball was potted and no cushion was hit — your opponent gets ball in hand. | After the first contact, nothing was potted and no ball reached a cushion. |
Shot taken — waiting for the other players to shoot. | Your turn has passed to the next player. |
Your opponent joined — break when you're ready! | The table filled up and the game has started. |
You won the game! Nicely played. / You lost the game. | A game between players is over. |
You beat the bot! You won $X. / The bot won this one. | A game against the bot is over; X is what the win paid. |
You left the table area — the game has ended. | You walked out of |
Not enough cash! This table costs $X. | The entry fee could not be paid — bank instead of cash for a table paid by bank. |
Not enough money for a $X bet. | The bet could not be covered. |
You do not have permission to use /poolcreator. | The player lacks the creator's ACE. |
Model could not be loaded. Check Config.Creator.models. | The model picked in the creator did not load within 3 seconds — usually a typo, or a custom model that is not streamed. |
No surface config for that table model. |
|
Still stuck? Open a ticket and include the server console from the moment
qs-billiardsstarts, yourconfig/config.lua, and — if the problem is at one table — the F8 output of/pooldbg, run withConfig.Debugon.