KAZIK/docs/BILLIARDS_PLAN.md

Native Billiards

The first playable implementation is in src_graphics/billiards.inc, entirely MASM32. The simulation uses positions and velocities, not predetermined shots.

The pool corner opens an eight-ball table against a basic dealer AI. Mouse aims; left/right fine-tune aim, holding/releasing Space controls power. BALL and POCKET buttons (B/P) call the shot. Click the cloth to place the cue ball after a foul. AI chooses a legal target and a ghost-ball contact towards a nearby pocket; it does not teleport balls or prescribe the outcome. It does not yet search blocked paths or optimize combinations. No account wager is charged for this first mode.

Implemented: fixed 2 ms steps, 16 balls, equal-mass normal impulses, overlap separation, rail restitution, friction, six pockets, group ownership, called pockets, first-contact/no-rail/scratch fouls, ball in hand, early/wrong-pocket eight losses, and re-spotting a break eight. Rule reference: WPA Rules of Play. This is a casino adaptation, not a claim of complete WPA rules enforcement: illegal-break choices, randomized racks, formal safety declarations and rare open-table exceptions are still pending.

Coefficients: cloth ball radius 3 pixels, maximum initial speed 90000/65536 pixels per step, ball restitution 0.98 (impulse coefficient 0.99), rail restitution 0.87, linear rolling slowdown 128/65536 pixels per step. Velocities sleep below 512/65536. These are game-tuned coefficients, not measured SI values. The test executable checks impulse momentum transfer, pocket capture, frame-time partition invariance, stopping friction and early/legal eight outcomes.

Remaining Physics Acceptance

• Use a fixed simulation step independent of rendering and time accumulation; rapid shots need substeps or swept contacts so balls cannot pass through one another or a cushion between frames.
• Test ball/ball impulses, separation of overlapping contacts, cushion rebounds, pocket entry and jaw contacts on explicit table geometry.
• Include sliding-to-rolling transition, frictional stopping, cue-ball spin and follow/draw. Cue power changes initial velocity, not the predetermined outcome.
• Balls may sleep only below documented motion thresholds. A turn finishes only when all active balls settle; rendering cannot change physics or consume RNG.
• Check momentum in ideal equal-mass ball collisions, decreasing energy with friction/restitution, symmetric mirror shots, break-shot contact chains and near-pocket shots at low/high speed. Compare different render frame rates.

Physical coefficients and rules must be specified before implementation and validated against references and measured shot behavior. "Perfect physics" is not a release claim: numerical accuracy, stability and gameplay fidelity need separate tests. Multiway/online billiards comes after the local simulation.