===============================================================================
 Pool Table — for the LinuxDoors AppImage Store
===============================================================================

 Name:          Pool Table
 Version:       0.1   —  AN EARLY VERSION
 Price:         $0.00
 Author:        LinuxDoors.com
 Created:       September 19, 2026, 5:17 PM
 Kind:          A LinuxDoors AppImage Software Product
 File:          Pool_Table.AppImage
 Size:          38,631,928 bytes  (37 MB)
 SHA256:        e5df3a2376efd5fd23a03a3db8f0b8411a459b94330d4686d6ec1be654112614

 Bug reports:   bugs-report-pooltable@linuxdoors.com

 CARD DESCRIPTION (the one line the store shows under the name)

     Seven games of pool on a table drawn rather than photographed.


-------------------------------------------------------------------------------
 THIS IS AN EARLY VERSION
-------------------------------------------------------------------------------

 Version 0.1, and the first game LinuxDoors has. It is a whole game and it
 plays properly, but it is early: there will be things in it that are wrong,
 and rough edges that only turn up once somebody other than its author is the
 one holding the cue.

 That is what this address is for:

     bugs-report-pooltable@linuxdoors.com

 If a shot does something a shot should not do, if a rule goes the wrong way,
 if it looks wrong or gets stuck or will not start — please write. Say what
 you did and what happened. Every report is read, and the physics in it has
 already been rebuilt more than once on the strength of somebody saying "that
 is not how a ball behaves."


-------------------------------------------------------------------------------
 DESCRIPTION
-------------------------------------------------------------------------------

 A table, a cue, and seven games to play on it.

 Nothing in it is a photograph or a sprite. The cloth is woven out of noise
 and lit by a lamp overhead, the balls are shaded spheres with a highlight, a
 rim light and a shadow that moves with them, the rails are cut leather with a
 cushion nose, and the pockets are holes with a shadow inside. All of it is
 drawn, so it is sharp at any size and there is no folder of pictures to lose.

 The cue works the way the old online tables did, because it is the way that
 works with a mouse: point to aim, hold the button and pull back to draw the
 power, let go to hit. Pull further for a harder shot. Push forward again and
 the power comes back down, so you can feel for the pace before you commit.

 Everything it needs travels with it. There is no Python to install first and
 no Qt to match — which is the point of shipping it as one file.

 Written for LinuxDoors, though nothing in it is specific to LinuxDoors — it
 runs on Debian and Ubuntu type systems, and on any other Linux distribution
 that can run an AppImage.


-------------------------------------------------------------------------------
 The seven games
-------------------------------------------------------------------------------

     Eight ball        solids and stripes, then the black
     Nine ball         lowest ball first, and the nine wins it
     Ten ball          the called-shot version, on the tournament table
     Straight pool     every ball is a point
     Cutthroat         three players, and you pot other people's
     Snooker           reds and colours, on a twelve foot table
     Practice          a table, a rack and nobody keeping score

 Each racks itself correctly and knows its own rules — which ball is on, what
 counts as a foul, when a scratch gives ball in hand, and who has won.


-------------------------------------------------------------------------------
 The table, from three sides
-------------------------------------------------------------------------------

 STRAIGHT DOWN
     The view you can actually aim in, and where the game opens.

 RAKED
     Tipped back to three quarters, for when you would rather look at the
     table than play on it.

 FREE
     Walk around it. Drag with the right button to swing the eye about, the
     wheel to come closer.

 DOWN ON THE SHOT                                                    (press E)
     Behind the white and along the line of the aim, the way it looks when you
     are actually standing at a table — the eye about a foot and a half above
     the cloth, a stride back from the ball, stick coming toward you. Aiming
     turns the whole view with you. The wheel walks you up and down the line
     rather than zooming.

     Once you strike, it holds absolutely still. Moving the view while the
     balls are moving makes it impossible to see what happened, so it does not.

 All four are painted by the same code from the same scene, so the balls sit
 where the physics says they are whichever one you are looking through.


-------------------------------------------------------------------------------
 How the balls behave
-------------------------------------------------------------------------------

 The part that has had the most work, and the part most likely to still be
 wrong somewhere.

 WHERE YOU STRIKE THE BALL DECIDES WHAT THE WHITE DOES
     Drag the spot on the little cue ball in the Strike panel. Hit it high and
     the white follows through; hit it low and it comes back — around two feet
     from normal potting range, less from further away, which is how a draw
     shot actually grades. Hit it to a side for English, which bends the path
     an inch or three over a full table, not the banana that a first attempt
     at it produced.

     There is a button to put the tip back in the middle, because side left on
     by accident quietly bends every shot after it.

 THE CLOTH IS FAST
     Rolling friction and sliding friction are separate, because a ball that
     is skidding scrubs off speed quickly and a ball that is rolling barely
     fights anything. A struck ball runs on the way a struck ball does.

 AND THE BALLS SETTLE RATHER THAN STOP
     The cloth lets go as a ball slows, so it eases out of its roll and creeps
     the last of it instead of arriving at zero still braking.

 Energy is accounted for. No collision anywhere in the game hands out more
 than the balls brought into it — checked across thirty of them at every pace
 and every strike, and the most any one made was 98%.


-------------------------------------------------------------------------------
 Playing against the computer
-------------------------------------------------------------------------------

 Three strengths, and they are honestly different: on a table with one ball to
 pot it makes roughly one in ten, three in ten, or five and a half in ten. It
 looks for the shot it can see, works out the pace from how far the ball has
 to travel, and misses by an amount that depends on how good it is meant to be.


-------------------------------------------------------------------------------
 The controls
-------------------------------------------------------------------------------

     Point                   aim
     Hold and pull back      draw the power; let go to hit
     Left / right arrows     turn the cue a little
     Shift + arrows          turn it a very little
     Shift while aiming      fine aim, down on the shot
     Space                   hit it
     E                       get down on the shot, or stand back up
     0                       the whole table
     Ctrl + = / Ctrl + -     closer, back
     Right button drag       look around, in the free view
     Wheel                   closer, or up and down the line when down on it
     S                       sound on or off
     Ctrl+N                  rack them again

 Down on the shot the mouse turns the aim at a steady rate rather than
 pointing at a spot on the cloth — from behind the ball the cloth is no guide
 at all, and pointing at it made the stick unusably twitchy.


-------------------------------------------------------------------------------
 On the command line
-------------------------------------------------------------------------------

     Pool_Table.AppImage              open on the eight ball table
     Pool_Table.AppImage nine         rack up nine ball instead
     Pool_Table.AppImage snooker      or snooker, or ten, straight,
                                      cutthroat, practice
     Pool_Table.AppImage --version
     Pool_Table.AppImage --help


-------------------------------------------------------------------------------
 LinuxDoors original
-------------------------------------------------------------------------------

 Built by LinuxDoors — this is our own application, not a mirror and not a
 repackaging of somebody else's build. The SHA-256 above is authoritative.

 The first game for LinuxDoors. It carries its own Python and its own Qt, so
 it runs on a computer with nothing installed on it. The table, the balls, the
 physics, the rules and the opponent are all the program's own code.


-------------------------------------------------------------------------------
 Running it — nothing to install
-------------------------------------------------------------------------------

     chmod +x Pool_Table.AppImage
     ./Pool_Table.AppImage

 On LinuxDoors, which has no FUSE, run it the way LinuxDoors runs any
 AppImage:

     ./Pool_Table.AppImage --appimage-extract-and-run

 or through linuxdoors-run-appimage, which does that for you and unpacks it
 once rather than on every launch.

 Settings live in ~/.config/pool_table/pool_table.save and are written when
 the game closes. Deleting that file puts everything back as it started.


-------------------------------------------------------------------------------
 THE NOISE IT MAKES
-------------------------------------------------------------------------------

 There is not a recording anywhere in the program, for the same reason there
 is not a photograph. Four sounds, worked out rather than sampled.

 Ball on ball is very short, very bright and almost all attack: phenolic
 resin is about the hardest thing anybody plays a game with, and two of them
 meeting is a click rather than a note. Its partials are high and
 deliberately not whole multiples of each other, because a sphere's modes
 are not a string's.

 The tip on the cue ball is softer and lower — leather and chalk are not
 resin, and there is a cue behind it. The engine only ever sees balls
 touching, so the two are told apart by when: the first contact of a shot
 involving the cue ball is the one the cue made, and every later one is two
 balls.

 The cushion is dull and quick with no ring at all, which is the whole
 difference between a cushion and a rail. The pocket is the ball off the
 shelf and then the run down behind it, two layers together.

 How loud each one is comes from how fast the balls were closing, taken
 before the exchange rather than after it — the point of a collision is that
 it changes those velocities, so asking afterwards measures the wrong thing.
 A kiss and a break are the same event and must not be the same noise. On a
 full break: one cue, forty-four clicks, twenty-three cushions and four
 pockets, running from a quarter to half of full gain.

 It does not use Qt for any of it. QtMultimedia is not in the runtime these
 programs are packaged on, and putting it there drags in a media stack
 several times the size of the game in order to play four noises. The mixing
 happens in the game and the result goes down one pipe to whatever the
 desktop already plays sound with — pipewire, pulse or alsa, whichever is
 there. The pipe is set to four kilobytes, one page and the smallest a pipe
 can be: left at the default sixty-four it holds a second and a half of
 audio, and every sound would arrive a second and a half after the thing
 that made it.

 Sound is a toggle — in the Game menu, or the S key. Off closes the pipe
 rather than muting it: a game that is not making a noise should not be
 holding the sound device open either. And it tells the truth — on a machine
 with no sound server it says so in as many words and takes its own tick
 off, leaving the setting asking for sound, so the same copy elsewhere
 starts making a noise again without anybody having to remember why it
 stopped.


-------------------------------------------------------------------------------
 Tell us what is wrong with it
-------------------------------------------------------------------------------

                          bugs-report-pooltable@linuxdoors.com

 It is version 0.1. Your report is the next version.
