KAZIK/docs/BILLIARDS_CURRENT.md

# Native Billiards

The casino table opens a selection of free Russian pyramid and American
eight-ball pool. All game simulation, rules, input, rendering and prediction
run in x86 MASM. Python only normalizes generated art and verifies captured
frames; no Python or external physics engine ships as the game runtime.

## Eight-Ball Turn Regression

The previous implementation retained a default/previous called ball and pocket
for human shots, while the AI supplied a new call before striking. A normal
human pot could therefore pass the turn despite correct contact and no foul.
Native regression case 12 reproduced that failure through aim, Space, rendering
and actual fixed-step motion before the fix. Scoring also credited every pot
to the shooter instead of the owner of the solid/striped group.

Automatic pre-shot calls now come from the existing physics prediction; manual
ball and pocket overrides remain binding. Group credit is reconstructed from
the actual pocketed balls and assigned groups. No collision, rail, pocket,
friction, force or pyramid-rule formulas were changed for this correction.

## Controls

- Select a discipline with the mouse or 1/2.
- Left-click/drag on the cloth to aim; arrows provide fine aim. Shift makes
  arrow aim slower. Up/down or the force slider changes shot power.
- Space or the shot button strikes. P or the guide button toggles prediction.
- Pyramid: right-click a ball, B or the cue button selects the cue ball.
  The break uses the colored ball; Shift-click places it in the home area.
- Eight-ball: right-click a legal object ball or use the order button/B to
  call it. Right-click a pocket or click the pocket indicator to call a pocket.
  Without an explicit override, the shared physics preview supplies the obvious
  intended ball and pocket before striking, even with the guide hidden. Ball and
  pocket overrides are independent and reset after settlement, not before it.
  An unknown automatic call is shown as a dash rather than a stale previous call.
  After a foul, click a clear place on the cloth to position the cue ball.
- Use the exit button or the casino's Escape flow to leave the table.

## Rules

Free pyramid uses fifteen white numbered balls and one colored ball, with
any active ball eligible as cue after the break. The first player to eight
credited balls wins. Legal cue-ball pots count after contact. Incorrectly
potted balls are respotted; the incoming player may take one penalty ball
and choose who plays next. Invalid breaks offer acceptance or a partial
re-rack. Ordered cushion/crossing histories determine legal non-pot shots.

Eight-ball uses the white cue, seven solids, seven stripes and black eight.
Groups are assigned by a legal called pot after the break. A wrong first
contact, scratch or no post-contact cushion/pot gives ball in hand.
The eight must be called and pocketed in the nominated pocket after clearing
the player's group; an early eight loses. A break eight is respotted, not an
automatic win. Invalid non-scratch breaks offer acceptance or a new break.
Pocketed solids/stripes are credited to their group's player, independently of
who struck or whether a foul occurred. Once groups are assigned, this includes
balls pocketed earlier on the open table. The white and black balls never add
to the group count. A legal called pot keeps the shooter at the table; a miss
passes the turn and a foul gives the opponent ball in hand.

These are playable casino adaptations, not a complete tournament referee.
Shot-clock/lag/protests, airborne balls, jump shots, deliberate push shots,
and all special tournament options for scratch/eight on the break are not
implemented. Backspin, topspin, side spin and curved trajectories are also
not implemented. Do not describe this simulation as ideal real-world physics.

## Physics And Prediction

- Q16.16 positions/velocities; fixed 2 ms steps independent of frame timing.
- Equal-mass normal impulses, separation, restitution and rolling deceleration.
- Distinct narrow pyramid / wider pool pockets and rounded jaw colliders.
- Pocket AABB rejection precedes squared-distance math, preventing long-vector
  overflow from deleting a ball at the opposite end of the table.
- Fine aim uses 4096 interpolated phases and 64-bit projection numerators.
- Preview calls the same `PoolStep3D` as actual play. It restores all ball
  arrays, collision histories and physics event fields before returning.
- Cached preview depends on the layout, discipline, cue, direction and force.
  It samples up to 6000 steps (12 seconds), showing cue/object paths including
  rebounds. This is a bounded guide; a moving ball beyond that horizon is not
  claimed to have reached its final position.

## Verification

`tools/tests/test_casino_actions.ps1 -SkipPreview` runs native MASM assertions,
including disappearance regression, all pockets, 100 breaks, pyramid scoring
and penalties, eight-ball groups/fouls/wins, choice UI, and preview/live parity.
`eightball_regression.inc` adds actual aim/Space/render/physics sequences for
consecutive human pots, both actors, hidden/visible guides, manual calls and
group-based credit. `test_billiards_module.ps1` runs these plus the pre-existing
pyramid/choice tests against fresh MASM code and the native graphics helpers.
`tools/tests/check_billiards.py --parity` checks actual framebuffer captures
and equality of tested versus shipping machine-code procedures.

Generated art and exact built-in prompts are under `assets/sprites/pyramid`.
Packed game assets are under `assets/animations/pyramid`.

## References

- [FBSR pyramid rules, September 2025](https://www.fbsrf.ru/sites/default/files/04-novaya_redakciya_pravil_piramidy_2025-09.pdf)
- [WPA Rules of Play, January 2026](https://www.wpapool.com/wp-content/uploads/2026/01/2026.01.02-WPA-Rules.pdf)
- [Pooltool physics model organization](https://pooltool.readthedocs.io/en/latest/resources/custom_physics.html)

Pooltool is a reference for separating motion and collision models, not a
runtime dependency. No Pooltool source was copied into the MASM game.