Documentation
Place pool tables in game, play 8-Ball, 9-Ball, Straight Pool or practice, take on players or the AI, set entry fees and bets, and calibrate custom tables.
Billiards has a side for players and a side for admins, and it helps to know which is which from the start:
Who | Opened with | What it is for |
|---|---|---|
Players | E at a free table | Choosing Play vs Bot, Play vs Player or Practice, a game mode and a bet — then playing. |
Admins |
| Placing, naming, pricing, moving and deleting tables, and choosing which modes each one offers. |
A table is playable the moment the server knows about it, and there are three ways to tell it:
Way | Kept in | Entry fee and modes | Best for |
|---|---|---|---|
The creator | The database | Per table: a price in cash or from the bank, and its own list of modes. | Most servers — no files to edit. |
|
|
| Tables you want written down with the rest of your config. |
Auto-detect | Your maps |
| Maps and MLOs that already have pool tables. |
Creator and config tables spawn their own table prop for every player within 60 m. Auto-detected tables use the prop that is already part of the map — see Integrations → Map Tables.
-- config/config.lua
Config.Tables = {
{ coords = vec3(-229.13, -935.51, 30.22), heading = 0.0, model = `prop_pooltable_02` },
}You never have to measure one by hand: with Config.Debug on, /poolplace lets you aim a see-through table and prints that line in the F8 console, and /poolhere prints one for the spot you stand on.
Config and map tables show up in the creator's list too, as Table followed by their id. Editing one and saving it gives it a row in the database, with its own name, price and modes.
/poolcreator opens the creator. The left panel lists every table the server knows, sorted by name, with a search box above it; + starts a new one. A new table's form has five sections:
Section | What you set there |
|---|---|
Table Info | The table's name. Required — it is how you find the table in the list. |
Table Model | The prop to spawn: Classic Green Pool Table or Classic Purple Pool Table by default, from |
Pricing | The price to start a game, and whether it is paid in Cash Money or by Bank Transfer. 0 reads Free to play. |
Game Modes | Which modes players can choose at this table: 8-Ball, 9-Ball, Straight Pool and Practice. All of them are on for a new table. |
Placement | Select closes the creator and puts you in placement mode. |
A see-through table follows whatever you look at, up to 50 m away, with a red line from you to the spot. Its heading and height offset are shown at the top of the screen.
Key | Does |
|---|---|
Mouse | Aim. The table stands on the surface you look at. |
Z / X — hold | Rotate the table. |
Mouse wheel | Raise or lower it 5 cm at a time. |
Left click | Confirm the spot and return to the creator. |
Backspace | Cancel and return to the creator. |
Back in the creator, Save Table lights up once the table has a name, a model and a position. Saving spawns it for every player at once and writes it to the database.
Click a table in the list to edit it: rename it, swap its model, change its price, how it is paid or which modes it offers, or press Reposition to place it again. Save Changes applies everything for every player straight away.
The teleport button beside each table asks once, then closes the creator and puts you next to it. Delete asks once, then removes the table from the world and the database.
Walk up to a free table and [E] - Set up a game of pool appears above the cloth — with the price when the table has one, for example ($500 cash). Press E to open the Pool menu:
Option | What happens next |
|---|---|
Play vs Bot | Match Settings with the game mode, the bot's difficulty and the bet. Ready starts the game at once. |
Play vs Player | Match Settings with the game mode and the bet. Ready opens the table for other players to join. |
Practice | Starts straight away: a full rack, no rules, no turns, just you. |
Match Settings only offers the modes that are enabled in Config.Modes and allowed on that table. A table that is busy shows a panel in the bottom-right corner instead of the prompt: Open table · 1/2 players · join in, This table is full, or Game in progress — wait for it to finish.
The first allowed mode and Normal are picked for you. With betting on, each difficulty shows its multiplier — ×0.5, ×1 and ×2 — and once you move the bet slider, Potential Win shows what a win pays: your bet back plus bet × multiplier. Ready takes the bet, racks the balls, and a ped picked at random from Config.Bot.pedModels takes its place at the end of the table. You always break.
Choose Play vs Player, pick a mode and a bet, and press Ready. You pay the table's price, the balls are racked, and a panel shows how many players have joined — 1 / 2 players connected.
Anybody who walks up sees Open table · join in and presses E. An invitation shows who opened the table, the mode and the bet, with Accept and Decline. Accepting is refused if they cannot cover the bet.
The game starts on its own as soon as every seat is taken: 2 players in 8-Ball, 4 in 9-Ball and Straight Pool. Or press E — Break now — to start with whoever has joined, even alone. Backspace closes the table instead.
When the game starts, every player pays the bet. If one of them can no longer cover it, the game is called off for everybody and no bet is taken. The player who opened the table breaks, and turns go round in the order players joined.
On your turn the panel in the bottom-right corner reads Your turn, followed by what you need to do next, and E puts you at the table. The camera drops behind the cue ball and the cue lines up behind it, while everyone else sees your character lean over the rail on the side of the shot.
Step | How |
|---|---|
Aim | A and D turn the cue around the cue ball; hold Left Shift to turn it slowly for a fine cut. A white line runs from the cue ball to the first ball or cushion in its way, and a faint ghost ball marks where the cue ball will meet an object ball. |
Power | Hold the right mouse button. The Shot Power bar at the bottom of the screen fills in about a second — the longer you hold, the harder the shot, from a soft touch up to 6 m/s. |
Shoot | Let go of the right mouse button. The cue strikes, and the camera rises above the table until every ball has stopped. |
Step back | Backspace leaves the aim camera without shooting. It stays your turn: press E to come back. |
When the balls stop, the shot is judged. If it keeps your turn you go straight back to aiming; otherwise a message tells you the turn has passed and the next player is shown as Waiting for <name>...
On the break and after a foul, the shooter starts with ball in hand. The camera looks straight down on the table, and the cue ball can go anywhere on the cloth — not only behind the head string — as long as it does not touch another ball.
Key | Does |
|---|---|
W A S D | Slide the cue ball over the cloth. |
Left Shift — hold | Slide it slowly. |
E | Place it and start aiming. |
The second line of the panel changes with the game, so a player always knows what to aim for:
Mode | What it can say |
|---|---|
8-Ball | Open table · pot a solid or stripe to claim your group · Pot your solids (1-7) · Pot your stripes (9-15) · Pot the 8-ball to win! |
9-Ball | Hit the 3-ball first · sink the 9 to win · Pot the 9-ball to win! |
Straight Pool | Pot any ball · 12/25 points |
Practice | Free play · pot anything |
Mode | Players | Balls | To win |
|---|---|---|---|
8-Ball | 2 | 15 — solids and stripes | Pot your group, then the 8. |
9-Ball | Up to 4 | 1 to 9 | Pot the 9 on a legal shot. |
Straight Pool | Up to 4 | 15 — racked again when cleared | Reach 25 points first. |
Practice | 1 | 15 — racked again when cleared | Nothing to win: free play. |
The player counts are the seats in Config.Modes, and the Straight Pool target is its target value.
The table is open after the break. The first player to pot only solids (1–7) or only stripes (9–15) on a legal shot takes that group, and the opponent gets the other.
While the table is open, hitting the 8 first is a foul. Once the groups are set, the cue ball must hit one of your own balls first — and once your group is cleared, the 8.
Potting one of your own balls keeps your turn.
Potting the 8 after clearing your group, without a foul, wins the game. Potting it any earlier, or on a foul, loses it.
Balls 1 to 9 are racked in a diamond, with the 1 at the front and the 9 in the middle.
The cue ball must hit the lowest-numbered ball on the table first.
Potting any ball on a legal shot keeps your turn.
Potting the 9 on a legal shot wins — even early, or off another ball. Potted on a foul, the 9 goes back on the foot spot and the next player has ball in hand.
Any ball can be potted, and every ball potted on a legal shot scores a point. A foul costs a point.
Potting keeps your turn. When the last ball drops, all fifteen are racked again and play carries on.
The first player to reach Config.Modes.straight.target — 25 by default — wins.
Only a scratch gives the next player ball in hand; after any other foul the cue ball stays where it stopped.
One player, no rules, no turns and no fouls. Pot the cue ball and you get it back in hand; clear the table and it is racked again.
In 8-Ball, 9-Ball and Straight Pool, every shot is checked for three fouls:
Foul | When |
|---|---|
Scratch | The cue ball drops into a pocket. |
Wrong ball first | The cue ball hits nothing, or the first ball it hits is not one you may hit first. |
No rail | Nothing is potted, and no ball reaches a cushion after the cue ball's first contact. |
A foul ends your turn and gives the next player ball in hand — in Straight Pool, only a scratch does — and the message tells everyone which foul it was.
How it ends | Result |
|---|---|
A win | Winner and loser each get a message, and a pot goes to the winner. The prompt over the table becomes [E] - Start a new game. |
Walking away | Going further than 8 m from the table ( |
Disconnecting | With a bet on, the game ends and the pot is shared equally among the players still there. Without one, the player is simply removed and the others carry on. |
Closing the table | Backspace while waiting for players, before the game starts. No bet has been taken yet. |
Two different amounts can change hands at a table, and they work differently:
Entry fee | Bet | |
|---|---|---|
Set by | An admin, per table, in the creator — or | The player who sets up the game, on the Match Settings slider. |
Paid by | The player who sets up a Practice or Player vs Player game. | Every player in the game — against the bot, the player alone. |
Paid in | The table's method: cash or bank. |
|
Taken | When the table is set up. | Against the bot, on Ready. Against players, when the game starts. |
Goes to | Nobody. It leaves the economy. | Against players, the winner takes everything that was staked. Against the bot, a win pays the bet back plus bet × the difficulty's multiplier; a loss keeps it. |
Set Config.Betting.enabled = false to turn betting off: the slider disappears and games are played for nothing but the entry fee.
On each turn the bot looks at every ball it may play and every pocket, keeps the shots where the path to the pocket is clear and the cut is not too thin, and plays the best of them. When no pot is on, it plays safe by hitting the nearest legal ball. With ball in hand it tries spots all over the table and puts the cue ball where its best shot is.
Its ped walks round the table to the shot, leans over the rail, takes its time and strikes, then walks back to the end of the table while you play. How well it plays is set per difficulty:
Config.BotAI = {
easy = { aimError = 0.090, powerJitter = 0.18, thinkMs = 1400, cutMin = 0.55 },
normal = { aimError = 0.035, powerJitter = 0.08, thinkMs = 1000, cutMin = 0.40 },
hard = { aimError = 0.008, powerJitter = 0.02, thinkMs = 750, cutMin = 0.30 },
}Field | Means |
|---|---|
| The largest random error added to its aim, in radians. 0.09 is about 5°; 0.008 is under half a degree. |
| The largest random error on its power: 0.18 is up to 18% too soft or too hard. |
| How long it stands over the shot, in milliseconds, before it strikes. |
| The thinnest cut it will try, as the cosine of the cut angle. Lower means it attempts harder cuts. |
Config.BotDifficulty sets which difficulties appear and in what order, and Config.BotRewards.difficulty what each one pays. The ped is picked at random from Config.Bot.pedModels for each game.
Everyone within 60 m of a table (Config.StreamDistance) watches the game. Players seated at a game hold a cue while they wait; the shooter is shown bent over the rail on the side of the shot, with the cue lined up on the cue ball and thrust forward on the strike. While the balls roll, their positions are sent about twenty times a second and smoothed, so every ball moves in time on every screen. A player who arrives halfway through a game gets the table as it is.
Config.Ped.enabled = false skips the posed stance: shooters play GTA's standard pool-player animation instead.
The two shipped tables are already calibrated. This is only needed when you add a table model, or when the shooter's stance or cue looks off with your peds. All of it happens in game, on the table nearest to you, with Config.Debug = true.
Command | Calibrates | Writes |
|---|---|---|
| Where the cloth is on the prop, how big it is and how high. |
|
| Pocket size and the width of the pocket mouths. |
|
| How the shooter stands and leans, and where both hands go. |
|
| Where the cue sits against the ball and how it is turned. |
|
Set Config.Debug = true and restart the resource. The commands only work while it is on. Stand next to the table you want to fit.
/pooledit draws the playable area in cyan, the cushions in green and the pockets in red, with the current values on screen. /pooltune ox and oy move the area, hx and hy size it, and oz — or /poolup, /pooldown and /poolbz — set its height, until the outline sits on the cushions and the balls rest on the cloth.
/poolpocket r 0.005 grows the pockets and /poolpocket m 0.005 widens their mouths; negative values shrink them. These two values apply to every table.
/poolhands, /poolarms, /poolstick and /poolstickrot put a copy of your ped at the table. The arrow keys change the values, G prints them to the F8 console and Backspace exits — the keys for each tool are in Commands and Controls.
Copy the printed values into config/config.lua, set Config.Debug = false and restart.
Every change is live while you make it, but the tools only print values — they never write files, so nothing is kept until it is in the config.