Make CueAI reviewable: correct the physics, make the ML result real, and put the simulator in front of the reader as a playable game

[BruceMoseti]

Why

The repository claimed to be a physics-informed AI simulation, but three things would not survive a technical reviewer opening it: the physics was wrong, the published ML result was negative, and there was nothing to look at. This PR fixes all three, and the third one is what makes the first two legible.

What a reviewer sees first

A playable eight-ball game against a search bot, in the browser, with no install and no build step.

The browser is not running a lookalike physics engine. web/js/physics.js is a hand port of src/cueai/physics/, and the port is measured rather than asserted: 35 reference shots — draw, follow, english off two rails, thin cuts, clusters, full sixteen-ball breaks — are exported from the Python simulator and replayed in Node. Worst disagreement across 156 s of table time: 1.2 × 10⁻³ mm. CI runs that check on every push and refuses to deploy the page if the two drift apart.

The port also runs 65× faster than the Python reference, which is what makes the opponent possible: the bot solves every pot line in closed form, then spends its whole budget simulating the survivors, and reports what that cost every turn in rollouts and table time. The strength setting is a rollout budget rather than an adjective.

Four panels exist so the mechanics can be read while they run:

Panel	What it shows
Cue ball, live	speed against contact-point slip, with the predicted 5/7·v₀ rolling speed drawn as a line the measured curve has to land on
Opponent	candidates enumerated, rollouts simulated, table time consumed, and the shot chosen
Shot log	which ball was struck first, rails after contact, and which of those facts made a shot a foul
Explainer	the cloth model, the parity harness, the bot's search, and where the learned model does and does not help

The prediction line is drawn only across the stretch of the shot it applies to. Hit a rail after the handover and it stops there; hit something before the slide finishes and the panel withdraws it and says why, rather than showing the simulation missing a target it was never aiming at.

Physics correctness

Sign errors. The contact-point slip velocity and the cloth friction torque used opposite handedness, so friction drove a struck ball away from rolling: measured rolling speed was 0 instead of 5/7 v₀, and stopping distance was 4× short. Sidespin was applied about the rolling axis, so "english" behaved like topspin.

The bug the single-ball tests could not see. The collision solver counted two balls as touching below 1e-4 m, and rack.py built the triangle with a 1e-4 m clearance, so all thirty contacts in the rack sat exactly on the threshold and which side each fell on came down to hypot rounding. Sixteen registered; fourteen did not. Breaks propagated through a contact graph with holes in it, and the table opened up less the harder it was struck. No test failed — it was found by measuring break spread against cue speed and getting the sign wrong. The fix names the tolerance (CONTACT_BAND = 1e-5), uses it everywhere, and racks the balls actually touching. Four regression tests now hold it, including the property that caught it: a harder break opens the table further. Mean pair separation after an 8.2 m/s break went from 0.478 m to 0.637 m.

Validation against theory, not against itself. tests/test_validation.py pins the integrator to independently derived results: the 5/7 rolling speed, the 12v₀²/(49 μ_s g) sliding distance, spin decay, cushion restitution, draw/stun/follow ordering, exact momentum conservation, strictly decreasing energy. Twenty headless bot-against-bot games check on each of ~800,000 physics steps that no two balls share space and nothing is inside a cushion; worst overlap seen is 0.47 mm on a 57 mm ball.

A real learning problem

The old training target was residual = (y + gaussian_noise) − y, which is pure noise, and metrics.json duly reported improvement_pct: -9.86.

cueai.physics.analytic is a closed-form free-ball solver: while a ball slides its slip decays along a fixed direction, so the friction force is constant and the path is exactly parabolic; a cushion damps the normal velocity while carrying the spin term through. It costs 0.27 ms against 4.6 s for a rack simulation. The learned model predicts the residual against that, so its value is measured as error reduction over real physics.

Method	Cost per shot	Mean error	Direct shots	R²
Numerical simulator, 16 balls	4.6 s	ground truth	—	—
Closed-form solver, no fitting	0.27 ms	494 mm	114 mm	0.01
Gradient boosting, same features	2.6 ms	382 mm	162 mm	0.52
Closed form + learned residual	0.60 ms	376 mm	98 mm	0.43

Selective prediction is what makes it deployable. The closed-form solver reports its expected cushion count while computing its answer, so the gating signal is free. Answering only shots it expects to keep off the cushions covers 9.8% of the space at 100 mm; at most one cushion, 27.5% at 189 mm; ungated, 376 mm. The fast path is not a 376 mm model, it is a model that can be asked to decline.

Two findings reported against interest, both measured every run: two thirds of sampled shots never reach the object ball, so the closed-form baseline collects that half of the error metric for free — and split out, the residual model loses to plain gradient boosting once a collision has to be modelled (696 mm against 610 mm). That names the highest-value next change as a physics change, not an ML one. A feature ablation on identical architecture, epochs, seed and split scores 179 mm on direct shots from raw parameters against 98 mm with the solver's conclusions.

Testing the parts that usually go untested

• The input layer, with a real cursor. web/test/input.mjs moves an actual mouse and presses actual keys rather than calling the page's functions, and asserts fifteen promises the interface makes to a player: a quick click lines a shot up instead of playing it, drawing the cue back sets the power without disturbing the aim, shift eases the aim to a hundredth of a degree, the spin widget clamps at the miscue limit, and a focused dropdown keeps its own spacebar.
• The break, because a bad one is invisible. Self-play now asserts that a break moves at least ten of the fifteen balls. This came out of reviewing the demo clip: the recording script aimed the break 33 mm off the apex, so it clipped the rack and moved five balls instead of twelve — and the result looked exactly like the documented under-spread limitation rather than like a badly aimed cue.
• The documentation, from the running page. The README stills and clip are recorded by driving the real page in Chrome, and the inspector still is only taken once the panel's legend confirms the shot stayed clean enough for the 5/7·v₀ prediction to apply. scripts/site_facts.py writes every figure the page quotes from the artefacts of an actual run, and CI fails if the page and the measurements disagree.

CI: ruff, mypy and the test suite on 3.10–3.12; parity export and replay; headless self-play; the real page loaded in Chrome and played end to end; the real-cursor interaction checks; and the full data → train → benchmark → figures pipeline. Pages deploys only after parity and self-play pass.

Verification

• make check — ruff, mypy, 54 tests, green.
• make web — 35/35 parity shots (worst 1.15 × 10⁻³ mm, 65× faster), 20 self-play games all reaching legal conclusions, worst overlap 0.469 mm, every break moving 12/15 balls.
• make browser — two full games in Chrome with no console errors, then 15/15 real-cursor interaction checks.
• make all — regenerates every table and figure; retraining reproduced the committed metrics.
• Layout checked at 1366×768, 1100×900, 820×1180 and 390×844: no overflow, no console errors.

web_demo.mp4

_{To show artifacts inline, enable in settings.}