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
• WPA Rules of Play, January 2026
• Pooltool physics model organization

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