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

  1. Put CueLine.exe anywhere (e.g. C:\Tools\CueLine). It keeps its config in CueLine.ini next to the exe.
  2. Run it — an unsigned build, so SmartScreen may ask once ("More info → Run anyway"). Nothing is installed and nothing is written outside that folder.
  3. 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 Hole positions and the Play_Area box (labels put the six holes at the corners and mid-rails, so pockets are the calibration),
  • White is the cue ball, Guideline is the game's own aim line,
  • Force and Spin are 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, plus OFFSET_CUE_ANGLE and OFFSET_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:

  1. the rectangle is grabbed with BitBlt from the screen,
  2. the felt colour is taken as the most frequent colour in that grab, so any table skin (green, blue, cloth, night mode) works,
  3. every pixel that differs from the felt enough and isn't near-black shadow becomes mask,
  4. connected regions are filtered by area, aspect ratio, fill ratio and radius — only round, ball-sized blobs survive,
  5. 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,
  6. 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.