cueline
CueLine is a tiny native overlay for pool/billiards: 8 Ball Pool on an Android emulator, on the Microsoft Store PC build, or on streamed/mirrored phone screens. It finds the balls itself from the screen and draws aim line, ghost ball, cut angle and bank paths on top of the game while every click still reaches the game
- Language
- C++
- Stars
- 0
- Last updated
From the README
CueLine — 68 KB click-through aim overlay
CueLine is a tiny native overlay for pool/billiards: 8 Ball Pool on an Android emulator, on the Microsoft Store PC build, or on streamed/mirrored phone screens. It finds the balls itself from the screen and draws aim line, ghost ball, cut angle and bank paths on top of the game while every click still reaches the game — ~80 KB, no installer, no runtime, no model file, no network, no account, no key.
Built from main.cpp in this folder (Win32 + GDI, statically linked).
selftest.ps1 drives it with synthetic input and must print PASS.
Install
- Put
CueLine.exeanywhere (e.g.C:\Tools\CueLine). It keeps its config inCueLine.ininext to the exe. - Run it — an unsigned build, so SmartScreen may ask once ("More info → Run anyway"). Nothing is installed and nothing is written outside that folder.
- Start the game. Windowed or borderless, never exclusive fullscreen.
Calibrate (once)
Ctrl+Alt+T→ screen dims → drag a rectangle tightly around the play surface (cushion to cushion, inside the rails).Ctrl+Alt+M→ click the cue ball, then click the object ball.Ctrl+Alt+S→ saved; positions survive restarts.
Esc or right-click leaves any capture mode. Re-calibrate whenever you change
emulator resolution, window size or DPI.
Reverse-engineering notes (what Cheto actually does)
Pulled from a public rebuild that ships their dataset
(aligujar7800-code/Cheto-8BP, CC-BY dataset): the detector has 7 classes —
Ball, Force, Guideline, Hole, Play_Area, Spin, White.
That tells the whole design:
- the table is not calibrated by hand — it comes from detected
Holepositions and thePlay_Areabox (labels put the six holes at the corners and mid-rails, so pockets are the calibration), Whiteis the cue ball,Guidelineis the game's own aim line,ForceandSpinare the on-screen widgets — Cheto reads your chosen power and english instead of inventing them,- the Android build additionally reads ball positions straight out of game
memory (
MemoryOffsets.kt: ball X/Y/Z + type per 0x20-byte struct, plusOFFSET_CUE_ANGLEandOFFSET_GAME_STATE).
Mirrored in CueLine: pockets derived from the play rectangle, the whitest blob as cue ball, a dedicated white pass because the guideline is glued to the cue ball, and two erosion passes to delete the 1–2 px guideline and shadows before blob analysis. Not mirrored (yet): Force/Spin widget reading, memory offsets.
Accuracy on real frames from that dataset, cue ball located 2 px from the label; it still misses some object balls, so treat auto-targeting as a strong hint, not an oracle.
The prediction readout
Everything is drawn live so nothing has to be solved in your head:
- aim line — dashed, brightening toward the contact point: brightness = speed
- ghost ball — exactly where the cue ball has to be at contact
- object ball path — solid, in that ball's own colour, into the pocket, with the run-out after the pocket in a dimmer dash and an X where it dies
- cue ball path after contact — the tangent line (draw/stun/follow shifts it), reflected off cushions, fading as it loses speed, ending in an X stop point
- power meter bottom-left with the spin state; readout line with cut angle, difficulty, power %, aim length and object run length
Ctrl+Alt+F walks draw → stun → follow and the cue path bends accordingly, which
is what the tangent/deflection actually does on the table.
Legal targets, power and auto-play
Each blob is classified by its own pixels: white = cue ball, very dark = the 8,
a white band through the middle = stripe, flat colour = solid, and the hue maps
to the ball number, which is printed next to the ball. Targets are then filtered
by the group you selected with Ctrl+Alt+Y (auto accepts both groups), and the
8 is only considered on a second pass when nothing legal is reachable.
Power is derived per shot: distance to the pocket + cue distance + cut angle →
drag length, so the stop markers match the shot you are about to take instead of
a constant. Ctrl+Alt+L keeps firing — shoot, wait for the rack to settle,
re-scan, shoot again — until nothing is left or you press L again.
Numbers are a heuristic (colour + stripe band), not OCR: they are right far more often than not, but treat them as guidance rather than gospel.
Controls — complete list
| Keys | Action |
|---|---|
Ctrl+Alt+X |
auto-detect on / off (default on) |
Ctrl+Alt+Z |
take the shot automatically (aim + drag + release) |
Ctrl+Alt+, / . |
shot power − / + (Z drag distance) |
Ctrl+Alt+Y |
group: auto → solids → stripes → 8 only |
Ctrl+Alt+L |
auto-play loop: shoot, re-scan, shoot again |
Ctrl+Alt+F |
spin: draw 2 → draw 1 → stun → follow 1 → follow 2 |
Ctrl+Alt+P |
predictive paths on / off |
Ctrl+Alt+T |
calibrate the table rectangle |
Ctrl+Alt+M |
place cue ball, then object ball (click, click) |
Ctrl+Alt+A |
hide / show all drawing |
Ctrl+Alt+G |
ghost ball + cut line on / off |
Ctrl+Alt+B |
banks: 0 → 1 → 2 |
Ctrl+Alt+H |
shot readout (angle, difficulty, banks, distance) |
Ctrl+Alt+C |
colour theme (4) |
Ctrl+Alt+[ / ] |
ball size − / + |
Ctrl+Alt+←→↑↓ |
nudge the object ball 1 px (Shift = 10 px) |
Ctrl+Alt+S |
save config |
Ctrl+Alt+R |
clear both balls |
Ctrl+Alt+F1 |
help line on / off |
Ctrl+Alt+Q |
quit |
Esc / right-click |
leave the current capture mode |
How it sees the balls
No model file, no OpenCV — about 120 lines of pixel maths, ~8 scans/second inside the calibrated rectangle only:
- the rectangle is grabbed with
BitBltfrom the screen, - the felt colour is taken as the most frequent colour in that grab, so any table skin (green, blue, cloth, night mode) works,
- every pixel that differs from the felt enough and isn't near-black shadow becomes mask,
- connected regions are filtered by area, aspect ratio, fill ratio and radius — only round, ball-sized blobs survive,
- the whitest blob is the cue ball; every other blob is scored for a shot (cue distance + distance to pocket + cut angle) with an occlusion test so blocked balls are skipped, then the best is targeted,
- the ball radius is measured from the blobs, so you never set it by hand.
Detected balls get a thin ring so you can see what it locked onto. If it loses
track, Ctrl+Alt+X turns detection off and Ctrl+Alt+M goes back to manual.
What it draws
- dashed cue → ghost-ball line, ghost ball ring, object → pocket path with the target pocket ringed
- bank paths (1 or 2 rails) with rail impact points, chosen by shortest distance with a cut-angle limit of 80°
- readout: cut angle, difficulty word, bank count, aim distance
Pockets are derived from the calibrated rectangle (portrait tables get side pockets mid-rail), so 8 Ball Pool in a portrait emulator window lines up correctly.
Why it is safe-ish
Pure drawing: no injection, no memory reading, no hooks, no network. The game server cannot see it. Emulator/mapper bans are about the emulator itself, not this overlay.