# Native Billiards

This is the historical first-implementation plan. Current disciplines,
controls, physics coefficients and verification are documented in
[BILLIARDS_CURRENT.md](BILLIARDS_CURRENT.md); use that document for the game
now shipping rather than the older controls and coefficients below.

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](https://www.wpapool.com/wp-content/uploads/2026/01/2026.01.02-WPA-Rules.pdf).
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.