1. Getting Started

• Game modes (mode list at the top, or ☰ menu on phones):
  • ⚔️ 2 Players (1v1 Offline) — two players take turns on the same device. White starts.
  • 🤖 Play vs AI — you play White, the AI plays Yellow. Choose Easy / Medium / Hard in the AI level list or in ⚙️ Setup.
  • 🎯 Free Practice — no opponent; drag any ball to set up a position, load drills, use the AI hint and the full path preview.
  • 🌐 Play Online — 1 vs 1 or 2 vs 2 against other players (see section 9).
• ⚙️ Setup: target score for each side (different targets = handicap), points for a bank shot (1 or 2) and AI level, then Start Match.
• A basic shot: aim with the mouse / finger, pick the tip position (english), set the power, press SHOOT (or Enter).
• 🔊 turns sound on/off. ❓ opens this guide.

2. Rules & Scoring (UMB 3-cushion)

• Your cue ball (White or Yellow) must hit both object balls, and it must touch the cushions at least 3 times before it hits the second ball.
• Valid patterns:
  • Ball 1 → 3 cushions → ball 2.
  • 1 cushion → ball 1 → 2 more cushions → ball 2.
  • 3 cushions first → ball 1 → ball 2 (bank shot).
• A cushion counts each time the cue ball comes off it (the same cushion can count twice). Cushions touched after the second ball do not matter.
• Each valid carom scores 1 point and you shoot again. A bank shot (cushion before the first ball) scores 1 or 2 points depending on ⚙️ Setup.
• A miss ends your inning and the turn passes to the opponent.
• The first side to reach its target score wins immediately.
• Break: on the opening shot the first ball you hit should be the red (UMB rule; the AI always does this). Drill 1 shows the standard UMB break position and shot.
• Double hit (foul): after the stroke the cue tip keeps travelling forward for a split second (stopping within about 0.04 s, a few cm — further when you hit harder) and is then withdrawn. If the cue ball comes back into the cue in that moment — typically when it is touching or very close to a cushion and you shoot into that same cushion — it is a foul: no point and the turn passes. The cue ball bounces off the cue. With Trajectory ON the path turns red when this will happen.

3. Aiming & Shooting

• Drag on the table (left mouse button / one finger) to turn the cue. When the aim line is on a ball the drag becomes finer automatically; hold Shift for even finer aiming.
• Click / tap a spot on the table (at least 15 cm from the cue ball) to aim straight at it.
• Hit thickness: how much of the object ball the cue ball covers at contact — 100% = full ball, 50% = half ball, small % = thin cut. The badge shows e.g. "Half ball 1/2 (49%) – Cut Right".
  • ◀ / ▶ (buttons or arrow keys): move the aim by exactly 1% thickness.
  • 1/1, 3/4, 1/2, 1/3, 1/4, 1/8: jump straight to that thickness on the ball you are aiming at. ⇋ Side: same thickness on the other side of the ball.
  • The thickness is measured along the real path of the cue ball, so it already allows for squirt (section 4).
• Power: drag the POWER bar (0.8 – 8 m/s), or ▲ / ▼ keys (5% per press, Shift = 1%), or Space (+10%). The power of the previous shot is kept.
• SHOOT or Enter strikes the ball.
• ⏪ Replay (R key): puts the balls, aim, english, elevation and power back to the previous shot so you can adjust and shoot again (not available online).
• 💡 AI hint (Practice and vs AI): the AI finds a scoring shot and sets aim, thickness, english and power for you; you just press SHOOT. It uses the elevation you have chosen.

4. Cue Tip (English) & Elevation

• Tip Position / English: click or drag on the ball to choose where the cue tip strikes — left/right = side english, up = follow (top spin), down = draw (back spin). The tip buttons use the coaching scale most players agree on: 1 tip ≈ 1 diamond — a ball shot straight across from one long rail to the other comes back about one diamond farther per tip of english at medium speed (1 tip ≈ 4.3 mm of tip offset; the faint rings mark 1 – 4 tips, the red ring is the miscue limit at 5 tips). R/L and F/D switch right / left and follow / draw. The ◀ ▶ and ▼ ▲ arrows add or remove 0.1 tip of side english or draw / follow at a time (hold to repeat). The hit thickness you picked is kept. Center resets it. The 3D cue points exactly at that spot in every view. The ball is drawn to scale and the dashed red ring marks the limit: the tip can be placed up to 0.7 of the ball radius (about 21 mm) from the centre in any direction — further out a real cue would miscue, so the game stops there (miscues are not simulated). As in real play, the spot is the offset of the cue axis from the ball's centre, measured square to the cue: Center means the cue points straight through the centre, so it gives no spin at any elevation (a raised cue at center just drives the ball forward). Spin per unit of speed is the same at every power: hitting harder gives proportionally more spin.
• Elevation / Massé: the slider or the 0° / 35° / 65° / 75° buttons raise the back of the cue (0° – 80°). 16°+ = piqué, 46°+ = massé, 71°+ = super massé. Raising the cue lowers the forward speed (the table absorbs the downward part of the stroke) but not the spin, so the spin becomes relatively stronger: draw + elevation = piqué (the ball stops or comes back), side english + elevation = the ball curves toward the side you hit. Like a real massé, the ball finally heads along the line from the ball to the spot where the extended cue would meet the cloth.
• The cue is never exactly level: it must clear the cushion (37 mm), the wooden rail (47 mm) and any ball behind the cue ball, so the game automatically raises it to the minimum needed:
  • about 1° when the cue ball is far from the rail behind it, 3–4° at 40 cm, 15° or more right next to the rail;
  • follow needs less elevation, draw needs more.
  • The card shows the real angle and "↑ Min X° here"; it turns orange (also the angle under the mobile cue button) when the cue was raised above the angle you set. The AI always plays with the lowest possible elevation.
• Squirt: side english pushes the cue ball slightly away from the side you strike — right english sends it a little to the left of the cue line — up to about 2.1° at maximum english, whatever the speed.
• Swerve: because the cue is always a little raised, side english also makes the cue ball curve slightly back the other way as it travels; with high elevation this becomes a full massé curve.

5. Aim Lines & Path Preview

• White dashed line: the path the cue ball will really take (with squirt and swerve) up to the ghost ball — the ring that shows where the cue ball will be when it touches the first ball or cushion.
• Orange dashed line (only with side english): the straight line of the cue itself, up to the first ball or cushion in that direction. Without side english it is the same as the white line, so it is hidden.
• 👁️ Trajectory (T key; Practice and vs AI only): shows the full predicted path of the cue ball for the next 10 s:
  • line colour: green = this shot scores, cyan = no score, red = double-hit foul;
  • rings mark each cushion contact (green from the 3rd cushion on); a second ghost ball marks where the cue ball reaches the second ball (green = score, orange = too few cushions);
  • the red line from the object ball shows where it will go.
• 📐 Angles (off by default): with Trajectory ON, shows the angle in (white) and angle out (yellow) at each cushion, measured from the rail.
• With Trajectory OFF (and always in 2-player and online matches) only the two dashed lines and the ghost ball are drawn.

6. Camera Views

• 🎯 Aim View: from behind the cue. Use the ▲ / ▼ buttons (left edge on desktop, beside the power bar on phones), PageUp / PageDown, or the mouse wheel over those buttons to raise or lower the view (about 5° – 63°). Hold a button to change it continuously; double-click the angle to reset. The camera follows the cue sideways so you see which side of the ball the tip will strike.
• 📐 Top View: straight down on the whole table with the diamonds — best for planning 3-cushion paths.
• 🌐 3D Orbit: with a mouse, left-drag aims the cue (click a spot on the table to aim at it) and right-drag (or middle-drag) rotates around the table; mouse wheel zooms. On a touch screen, drag to rotate and pinch to zoom.

7. Practice & Drills

• In Free Practice, drag any ball to place it. The Practice panel has 🔄 Reset balls, ⏪ Replay this position and 👁️ Trajectory. ✕ hides the panel; 🎯 Practice (right after 💡 AI Hint on the aim bar) shows it again.
• 📐 Diamond systems (Practice panel): while you aim, the panel reads your shot with three common systems and marks each predicted 3rd-cushion point on the table: Five & Half (long rail first: Start − Aim = Arrival), Plus (short rail first: Start + Aim = Arrival) and No English (long rail first, no side spin: 1.5 × (Start′ − Aim) = Arrival, numbers measured in this game; it is used only when side english is set to 0). 10 = 1 diamond. "Real path" is where the cue ball really lands with the game physics (cue ball alone). Ball-first shots: when the cue ball hits an object ball before any cushion, Five & Half and Plus use the cue ball's path after the first ball — that line, extended back and forward, crosses the diamonds at the Start and Aim numbers (shown on the table with a dashed line). Each system has standard english and power; Apply sets them without moving your aim.
• 📚 Drills load 11 positions with a recommended shot (aim, power, english, elevation) and a description: UMB break, Around the Table, 3-rail bank, draw, follow rail-hug, thick-hit follow, curved massé, Kobayashi, and three diamond system drills (Corner-5: cue number − aim number = arrival number, e.g. 50 − 20 = 30) that teach reading the diamonds.

8. Playing vs AI

• Easy / Medium / Hard differ mainly in how precise the AI's aim and power are — Hard rarely misses a shot it has found.
• The AI turns the cue to its shot, then strikes; its english, power and elevation are shown on your controls.

9. Playing Online

• Press 🌐 Play Online, choose a server, then:
  • Create Room: your name, Public (listed for everyone) or Private (join by code), 1 vs 1 or 2 vs 2, target score for each side and bank-shot points. Share the 4-letter code with 📋 Copy room code.
  • Join Room: pick a public room from the list (🔄 Refresh) or type the room code.
• 2 vs 2: order A1 → B1 → A2 → B2. Rotation By inning = each player shoots a whole inning; By shot = teammates alternate every shot.
• Send quick emotes 👏 🔥 😎 😭 🎯 during the match. Replay, AI hint and the full path preview are disabled online.
• All players should use the same game version (web and app), otherwise the same shot can end differently on each device.

10. On a Phone

• Play in landscape (⛶ Fullscreen hides the browser bars).
• Left column: target score, then White and Yellow scores. Right column: ☰ menu (modes, drills, camera, setup, sound, rules, online), the cue controls button (mini ball = tip position, number = real elevation), POWER bar, SHOOT, ⏪.
• Bottom bar: ◀ % ▶, 1/1 … 1/8, ⇋, 👁️ trajectory, 💡 hint.
• The cue controls panel holds Tip Position, Elevation and Hit Thickness; while it is open the bottom bar is hidden. The panel becomes see-through while you drag inside it.

11. How the Balls Behave

• Natural rebound: without english the rebound angle is wider than the incoming angle (a rolling ball coming in at 45° leaves at about 55°).
• Cushions create english: friction at the cushion nose drags the side of the ball along the rail, so a ball without english leaves the cushion with natural running english, which widens the angle at the next cushion. Reverse english is reduced by each cushion.
• Running english widens the rebound and speeds the ball off the cushion; reverse english shortens it and at steep angles can bring the ball back.
• Speed: medium speed (2 – 3 m/s) runs long and true to the Diamond System; hard shots sink into the cushion and shorten the path by about 0.5 – 1 diamond. At very shallow angles english does not grip.
• Follow makes the cue ball keep going / hug the rail after contact; draw pulls it back. Spin takes time to take effect, so the path bends after the contact.
• Spin off a rail: the cushion uses Stronge's compliant impact model (W. J. Stronge, Impact Mechanics, 2018), the default cushion model of the open-source simulator pooltool. The 37 mm cushion nose touches the ball above its centre, so the impact pushes along a line that points slightly down through the ball's centre. The rubber acts as a spring both into the rail and along it, and friction can make the contact slide, stick and slide back during the bounce. Rebound speed, side english and follow / draw all come from that model. The ball – cushion friction is μ = 0.2 (pooltool default): enough grip for english to change the rebound clearly, without the rail swallowing all the english on a near head-on hit, so spin still carries to the next rails. A rolling ball without english comes off a little wider than the mirror angle — a real effect of the roll it keeps. As on a real table, the path bends a little just after the rail (within the first 10 – 35 cm) while the spin left over from the bounce takes hold on the cloth. Cue elevation only matters at the moment of the stroke.
• Throw: friction between the balls pushes the object ball slightly off the line of centres — most on slow, half-ball cuts (1 – 3°), and side english throws it the opposite way.

12. Keyboard & Mouse

• Left-drag on the table: aim (Shift = finer). Click a spot: aim at it. In Practice, drag a ball to move it.
• ◀ / ▶ arrows: aim ±1% thickness (when not aiming at a ball: turn the cue slightly, Shift = finer).
• ▲ / ▼ arrows: power ±5% (Shift = 1%). Space: power +10%. Enter: shoot.
• Mouse wheel: thickness ±1% (or a tiny turn when not aiming at a ball); zoom in 3D Orbit; Aim View tilt over the ▲ / ▼ buttons.
• M: elevation 0° → 35° → 65° → 75°. [ / ]: elevation −5° / +5°. The shot never uses less than the minimum shown.
• PageUp / PageDown: raise / lower the Aim View camera.
• T: Trajectory on/off. R: Replay the previous shot.

Start Match

Congratulations on a great 3-cushion match!

New Match