Billiards/Pool Game Template
Documentation
Billiards/Pool Game Template
============================
A billiards/pool game template: a playable pool table for any game. Aim the cue
around the cue ball, pull back for power, put spin on it with the tip, and the balls
roll, spin and bank by their own physics, not Chaos: a 2D simulation in the table's
plane with sliding and rolling, draw, follow and side spin, cushions and pocket
jaws. The same shot always plays the same way. A shot guide shows where the cue ball
goes, where it touches the ball and both balls' paths after, worked out by the same
physics. 8-ball, 9-ball and free play, two players on one screen or against the
computer at three levels. Tables of 7, 8, 9 and 12 feet in five looks, a ball
return, a lamp, a menu and a small bar room to play in.
Quick start
-----------
Open the project and press Play (Maps/L_BL_Demo). The menu opens: choose the game,
the opponent, the computer's difficulty, the guide, the table, the view after the hit
(following the cue ball, or from above), whether the break
decides the groups and what counts as a foul (a checkbox each: a scratch, the wrong
ball first, no ball hit, no rail after the hit), and press New Game. Tab opens the menu again.
Mouse aim (hold Shift for fine aim); A / D too
Left mouse button hold and pull the mouse back for power, let go to shoot
Space hold: a power meter runs; let go to shoot
Right mouse button cancel the shot being drawn (the pull or the meter); Escape too
Arrow keys move the tip on the cue ball: follow, draw, left, right
R the tip back to center
Q / E on the 8: call another pocket (the guide calls one for you)
Mouse wheel zoom; C the view from above
V / Shift+V look from the next ball on the table / the one before; the
mouse turns the view round it, the aim stays. Past the last
ball, or a click, Space or the right button: the cue ball
H hide or show the keys on the screen (also the menu's Show the
controls on screen checkbox, and ShowKeys on BPC_BL_Shooter)
Ball in hand the cue ball follows the cursor; click to place it
Gamepad: the right stick aims, the right trigger is the meter, the left stick moves
the tip, the shoulder buttons call the pocket, the bottom face button places the
cue ball, the top face button is the view from above, the d-pad left and right
look from the other balls, B cancels a shot, the menu button the menu.
In your own project
-------------------
1. Migrate the PoolKit folder into your project (right-click it in the Content
Browser, Asset Actions > Migrate).
2. Drag Blueprints/BP_BL_Table into a level. Set its size and look in the Details
panel, or put a preset in Preset and press Apply Preset.
3. Add BPC_BL_Shooter to the pawn that plays (Add Component). On play it finds the
nearest table, looks through the table's cameras and reads its own input. For a
bar minigame, add the component when the player walks up to the table and
remove it (and set the view back) when they leave; set TakeView and
ShowMenuOnPlay to suit.
4. Choose the game on the table (RulesClass, Opponent, Difficulty) and call
NewGame, or leave StartOnPlay on.
How the balls move
------------------
The table runs its own simulation in its plane: x along the table toward the foot
rail, y across, 0 at the center of the cloth, cm. Each ball has a position, a
velocity and a spin. Each step:
a sliding ball (one whose contact with the cloth slips: just struck, or with
draw or follow) is pulled toward rolling by the cloth (SlideFriction); a
rolling ball slows (RollFriction); side spin wears off (SpinFriction)
a ball touching a cushion or a pocket's jaw bounces off it (CushionRestitution),
its side spin changing the angle (CushionFriction)
a ball whose center crosses a pocket's throat drops
touching balls part along the line of their centers (BallRestitution) with a
little throw from spin (BallFriction)
A step is as short as the fastest ball needs to move at most MaxMove (up to 480
steps a second at full speed, as few as 120 when everything is slow). Nothing in it
is random and nothing depends on the frame rate: the same shot gives the same
result, so it can be played ahead (the guide, the computer player).
Draw and follow come out of the physics: a ball struck low slides with backspin,
and after it hits a ball the backspin pulls it back.
The ball meshes are placed from the simulation every frame and turned by their
spin, so the numbers roll. Pocketed balls drop into the pocket and roll out of the
return into the tray under the foot rail.
The games
---------
The rules are a component the table adds for its game (RulesClass). After every
shot the table asks them to judge it from its record of the shot: the first ball
the cue ball hit, the cushions touched after it, the balls pocketed and where.
8-Ball Player 1 breaks from behind the head string. The first ball legally
pocketed takes its group (solids 1-7 or stripes 9-15), on the break
too; turn BreakDecidesGroup off on the table (or in the menu) for an
open table after the break. Hit one of your group first (any but the 8 on
an open table); after the hit a ball must reach a cushion or drop. A
foul gives the other player ball in hand anywhere (behind the head
string after a scratch on the break). With your group down, call the
8's pocket (the ring marks it) and pocket it to win; the 8 pocketed
early, in another pocket or with a foul loses. The 8 on the break is
respotted.
9-Ball Hit the lowest ball on the table first. Any ball pocketed on a legal
shot keeps the turn; the 9 pocketed on a legal shot wins (on the break
too). A foul gives ball in hand anywhere, and a 9 pocketed on it is
respotted. No push-out.
Free Play No fouls but a scratch (ball in hand anywhere); pocket a ball to shoot
again; a cleared table is racked again.
A game of your own is a child of BP_BL_Rules that overrides its hooks: RackGame,
StartRules, JudgeShot, GroupText, Targets and MustCall.
The computer player
-------------------
With Opponent Computer Opponent (player 2) or Two Computer Opponents the table spawns BP_BL_AI. On its
turn it places ball in hand, breaks, or lists every legal ball into every pocket
by ghost-ball geometry (a cut no wider than 75 degrees, the ball able to enter the
pocket, nothing in the way), plays the most promising few ahead on the table a few
steps a frame, and takes the best: the ball in its pocket, no scratch or foul,
the cue ball left off the cushions. Its aim and speed are off by its difficulty:
Easy 2 shots tried, up to 1.5 degrees off, center ball only
Medium 4 shots tried (and their draw versions), up to 0.7 degrees off
Hard 8 shots tried (center, draw and follow), up to 0.25 degrees off
Settings (BP_BL_Table, in the Details panel)
--------------------------------------------
Table
TableSize 7 ft, 8 ft, 9 ft or 12 ft (playing areas 198 x 99, 224 x 112,
254 x 127, 356 x 178 cm; pool balls and rules on all four).
PocketSize The pockets' mouths times this (1 = 11.7 cm corners, 13.3 cm
sides). Keep within 0.85-1.15 (the holes are cut for 1).
ClothColor, Wood The cloth's color, the rails' and body's material.
Preset A PDA_BL_Preset; Apply Preset puts it on the table.
Game
RulesClass BP_BL_Rules_EightBall, _NineBall, _FreePlay, or your own.
Opponent Two Players, Computer Opponent or Two Computer Opponents.
Difficulty Easy, Medium or Hard.
PlayerNames, AIName The names on the HUD.
StartOnPlay A new game when play starts.
MessageSeconds How long a message (a foul, the winner) stays up.
BreakDecidesGroup 8-ball: a ball pocketed on the break takes its group (on by
default). Off: the table stays open after the break.
Fouls (each on by default; the menu sets them too)
ScratchFoul The cue ball pocketed. Off: no foul, the cue ball comes back
behind the head string.
WrongBallFoul Not your group first, the 8 early or on an open table, not the
lowest ball in 9-ball.
NoHitFoul No ball hit.
NoRailFoul No ball reaching a cushion or a pocket after the hit.
Game The rack shown in the editor (and with StartOnPlay off).
Seed 0: a different rack each time; any other number racks the
same way every time, so the same break plays the same way.
RackJitter How far apart the racked balls may sit (cm).
AIClass The computer player's class.
Physics
SlideFriction 0.2, RollFriction 0.01, SpinFriction 0.044, BallRestitution
0.95, BallFriction 0.06, CushionRestitution 0.75, CushionFriction 0.2
MaxShotSpeed The hardest shot, cm/s (1100).
StepRate, MinStepRate, MaxMove The simulation's steps (see above).
StopSpeed Below this a rolling ball stops (cm/s).
TimeScale Below 1, the balls roll in slow motion.
MaxStepsPerFrame The most steps in one frame.
Guide
GuideBefore The longest line to the first ball (cm).
GuideAfterCue, GuideAfterHit The Full guide's paths after the first hit (cm).
GuideShort The Short guide's paths after the first hit (cm).
GuideBounce How far the guide follows the cue ball off a cushion (cm).
Cue and View
CueElevation, StrokeTime, ViewPitch
Lamp
ShowLamp, LampHeight (cm above the cloth), LampIntensity (candelas, each of 3)
BPC_BL_Shooter
Table The table to play (empty: the nearest).
Guide Full, Short or Off.
AimSensitivity, FineAim, KeyAimSpeed, StickAimSpeed Aiming.
PowerDrag How far the mouse is pulled back for full power.
MeterSpeed The power meter's sweeps a second.
PowerCurve Speed = MaxShotSpeed x power to this (above 1: finer soft shots).
PreviewPower The power the guide shows before you pull back.
SpinSpeed, MaxSpin The tip's movement (ball radii).
MaxPullBack How far the cue draws back at full power (cm).
StartZoom, ZoomMin, ZoomMax, ZoomStep The shot camera's distance (cm).
GuideRate The most guide updates a second.
TopViewAfterShot Off: after the hit the shot camera follows the cue ball. On:
the view from above until the balls stop (the menu sets it too).
TakeView, ShowHUD, ShowMenuOnPlay, ShowKeys, HUDClass, MenuClass
BP_BL_AI
AimErrors, SpeedErrors, Verify, Variants, PositionWeights, BreakPowers
Per difficulty (Easy, Medium, Hard).
ThinkSteps Simulation steps of thinking a frame.
AimTime, Pause Its turn's pace (seconds).
Blueprint API
-------------
BP_BL_Table
NewGame() a new rack and game
Strike(Ball, Direction, Speed, Side, Top) hit a ball; Side and Top are where the
tip hits, in ball radii (0.5 at most)
BeginStroke(Direction, Speed, Side, Top, PullBack) the cue's stroke, then the shot
PredictShot(Ball, Direction, Speed, Side, Top, MaxSeconds, Paths)
-> Hit, PottedBalls, CueEnd, Scratch, RailsAfter
the shot played ahead on a copy
RunToRest(MaxSeconds), SimStep(), Advance(Seconds) the simulation by hand
SetBall(Index, Location, InPlay), GetBall(Index) -> Location, BallState, Velocity
RackBalls(Game), Respot(Ball), StartBallInHand(BehindHeadString), MoveCueBall,
FinishBallInHand, CallPocket(Pocket), UpdateGuide(...), HideGuide(),
PoseCue(...), AimView(Yaw, Zoom, Delta), SetTopView(Top), ApplyPreset(), Refit()
Phase 0 aiming, 1 striking, 2 rolling, 3 ball in hand, 4 game over
CurrentPlayer, Winner, Message, BreakShot, Rules
Events: OnPotted(Ball, Pocket), OnFoul(Player, Reason), OnTurnChanged(Player),
OnGameOver(Winner)
Balls are 0 (the cue ball) to 15; pockets 0-3 are the corners, 4 and 5 the sides.
Presets
-------
A preset is a PDA_BL_Preset data asset: TableSize, PocketSize, ClothColor, Wood.
Put one in the table's Preset and press Apply Preset (the menu's Table row does it
at runtime). Included:
DA_BL_Classic 8 ft, green, walnut
DA_BL_Tournament 9 ft, blue, mahogany, tighter pockets
DA_BL_BarBox 7 ft, red, oak, generous pockets
DA_BL_Snooker 12 ft, green, mahogany, tight pockets
DA_BL_Modern 8 ft, gray, ebony
Contents
--------
Blueprints/BP_BL_Table the table, its physics and the game
Blueprints/BPC_BL_Shooter what a player shoots with (any pawn)
Blueprints/BP_BL_AI the computer player
Blueprints/BP_BL_Rules, BP_BL_Rules_FreePlay, _EightBall, _NineBall the games
Blueprints/BP_BL_Cue the cue
Blueprints/BP_BL_Player, BP_BL_GameMode the demo's pawn and game mode
UI/WBP_BL_HUD, WBP_BL_Menu the power, spin, players and messages; the menu
Presets/PDA_BL_Preset, DA_BL_* the preset asset and 5 presets
Meshes/T<size>/SM_BL_<size>_* bed, rails, sights, pockets and body for each size
Meshes/SM_BL_* cushion pieces, ball, cue, triangle and diamond racks,
chalk, lamp, shade, bulb, guide strip, pocket ring
Meshes/Room/SM_BL_* the demo's bar room: floor, paneling, walls, ceiling,
bar, foot rail, shelf, 3 bottles, stool, seat, cue
rack, sconce
Materials/M_BL_Ball the balls: stripe, number circle and number drawn in
the material (no textures), 16 instances
Materials/M_BL_Cloth, M_BL_Wood, M_BL_Cue, M_BL_Surface, M_BL_Guide, and instances
Enums/E_BL_TableSize, E_BL_Guide, E_BL_Difficulty, E_BL_Opponent, E_BL_Game
Maps/L_BL_Demo the bar room with an 8 ft table
Unreal Engine 5.8. Blueprint only; no plugins required. No textures.