===============================================================================
 Skee Ball — for the LinuxDoors AppImage Store
===============================================================================

 Name:          Skee Ball
 Version:       0.1   —  AN EARLY VERSION
 Price:         $0.00
 Maker:         LinuxDoors.com Games
 Created:       September 19, 2026, 4:58 PM
 Kind:          A LinuxDoors AppImage Software Product
 File:          Skee_Ball.AppImage
 Size:          38,627,832 bytes  (37 MB)
 SHA256:        4691eb54dc59025468289c78a591f78409cb4e47a8ebe32f140e1f71881a706d

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

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

     The alley game, on a lane drawn rather than photographed.


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

 Version 0.1, and the second 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 rolling the ball.

 That is what this address is for:

     bugs-report-skee_ball@linuxdoors.com

 If a ball does something a ball should not do, if the aim and the landing
 disagree, if it looks wrong or gets stuck or will not start — please write.
 Say what you did and what happened.


-------------------------------------------------------------------------------
 THE TARGETER
-------------------------------------------------------------------------------

 This is the whole game, so it is worth being plain about.

 Two lines at right angles to each other, in a box in the top corner of the
 window. One runs side to side and says where across the plate the ball will
 land; the other runs up and down and says how far up the slope it. Where
 they cross is where the ball goes, and the plate in miniature under the two
 tracks shows which hole that is.

 In the corner, and not drawn across the plate itself. On the plate the
 lines crossed the holes they were about to go into, which meant the one
 thing you most needed to see was the one thing with a line through it.
 While they sweep the machine is left clear; a quiet pip appears on the
 plate once the aim is settled, so there is something to look at while you
 wind up the throw.

 And it goes there. The throw is solved backwards from that crossing — the
 speed the ball must leave the lip at is worked out from where you asked it
 to come down — so the crosshair is a promise rather than a suggestion.
 Every one of a hundred and forty-three test aims spread over the whole
 plate landed in exactly the hole it was aimed at. All of the difficulty is
 in stopping the lines where you meant to, which is where it should be.

 Two lines rather than one, because one is not enough to describe the
 target. The fifty is straight ahead and the two hundreds are not: going up
 the plate gets you to the fifty, and only going up AND across gets you to a
 corner. A single sweeping line could never ask that question.


-------------------------------------------------------------------------------
 SEVEN WAYS TO USE IT
-------------------------------------------------------------------------------

 One of them has no sweeping at all, and the other four are two questions
 with two answers each: do the lines stop one at a time or together, and is
 the ball thrown for you or by you.

     Pool        point at the plate and pull back, the way a cue works on
                 a pool table. Aim and power in one movement instead of
                 two, and the one it starts on.
     Flick       flick up with the mouse and click to let go.
     Arcade      both lines at once, one press, then you throw it.
     Arcade #2   no lines and no stopping: the aim wanders about the plate
                 on its own. Hold and drag *upwards* to wind the throw up,
                 and let go when it is over the hole you want — the aim is
                 read at the instant you release.
     Classic     across first, then up, and it throws itself. Two timed
                 presses, the way the video cabinets did it.
     Snap        both lines, one press, thrown for you. The quickest and
                 the least forgiving.
     Pitch       one line at a time, then throw it yourself. The slowest
                 to aim and the hardest to finish.

 When both lines run at once they run at deliberately unrelated speeds. Two
 sweeps at the same rate fall into step and the crossing walks a straight
 diagonal, which anybody learns in about four throws and is then not a game.

 They also start at opposite ends of their tracks. Started together at the
 near end, every quick press gave the same short throw — so the fastest
 thing a player could do was also the worst throw on the plate, which is the
 wrong lesson for a machine to teach.

 How fast they sweep is yours: gentle, normal, quick or unkind. That is the
 difficulty, and it is the honest place to put it — the machine is not
 secretly deciding whether you deserve the fifty.


-------------------------------------------------------------------------------
 THE THROW, AND WHY THE POWER IS THE HEIGHT
-------------------------------------------------------------------------------

 Pull back with the mouse and let go. Hold Space and release, if you would
 rather not use the mouse.

 How hard you throw is not a second difficulty bolted on beside the aim. It
 *is* the up-and-down half of the aim. On a real machine the ramp never
 moves, and the only thing deciding whether a ball drops into the ten or
 sails into the fifty is how fast it is going when it leaves the lip.

 So the power bar stands up beside the lane rather than lying along the
 bottom, and it has a green band marked on it. That band is exactly the
 speed the crosshair asked for. Pull to the band and the ball lands on the
 crossing. Pull past it and it lands high; fall short and it lands low —
 measurably so: the same aim thrown at eighty per cent power comes down
 fourteen inches lower on the plate.

 The bar is the z axis of the throw, stood on end where you can see it.
 Pulling to the band and landing on the crossing are then the same action
 rather than two separate things to learn.


-------------------------------------------------------------------------------
 LEANING ON IT
-------------------------------------------------------------------------------

 Once the ball is on its way, move the mouse left or right and it leans that
 way. Arrow keys do the same.

 This is not a second go at the aim, and it deliberately does not happen
 during the wind-up. The lines were stopped, the ball was thrown, and this
 is what a person's body does afterwards. It is worth six inches by the time
 the ball reaches the plate — the ball spends the best part of a second on
 the boards before it leaves the lip, and a lean that cannot be felt in that
 time may as well not be there. Six inches moves a ball between neighbouring
 holes, which is a real save; it does not reach from the middle of the plate
 to a hundred eleven inches out, so the lines still have to be stopped
 somewhere sensible.

 Nothing about it is painted over the machine. The lane is the thing to be
 watching while a ball is rolling, and a banner across the foot of it is in
 the way of the one moment the game is actually happening. What the lean is
 doing shows in the targeter box instead.

 And when a ball drops, the whole plate lights up — gold for a hundred,
 green for the rest. A machine that scores is supposed to be pleased about
 it, and a glow round one hole is a notification where this wants to be a
 reaction.


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

 There is not a recording anywhere in the program, for the same reason there
 is not a photograph. The ball on the boards is filtered noise, low and
 rough, because a maple lane under a three pound ball is the loudest thing
 in an arcade and the least like a tone. The drop is the lip of the hole and
 the net behind it, layered. The plate is wood struck and left to stop
 almost at once, which is what a dished face does.

 Five sounds. How loud each one is comes from how hard the ball arrived, so
 a ball that just reaches the fifty and one that slams into it are not the
 same noise.

 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 five noises. Instead
 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.

 And the pipe is deliberately tiny — four kilobytes, which is one page and
 the smallest a pipe can be. Left at the default sixty-four it holds a
 second and a half of audio, so the mixer fills it once and from then on
 every sound arrives a second and a half after the thing that made it.

 Even a tenth of a second is visible, though, so the sound is not triggered
 by the event: it is worked out *before* it. A ball in the air is in free
 flight and free flight has a closed form — the plate is a plane, the moment
 the ball crosses it is the root of a quadratic, and where on the plate it
 will be when it gets there is two multiplications. Measured at every hole
 on the plate, the noise is called 99 ms ahead of the contact, which is
 exactly what the pipe swallows.

     Sound                  the lot, on or off (S)
     Chime when it scores   the bright one after the drop, on its own
     Nothing but the drop   the ball going in, and silence everywhere else


-------------------------------------------------------------------------------
 THE GAMES
-------------------------------------------------------------------------------

     Nine balls    the standard frame, and whatever nine of them add up to
     Rush          ninety seconds, and as many as you can get away
     Hundreds      nine balls, and only the two corner holes count at all
     Knockout      it goes on until a ball scores nothing, and then it stops

 A machine opponent will take alternate rolls in the frames that have a
 fixed number of them. It plays the same game you do: it picks a hole, and
 then it has to stop the lines, and its skill is entirely how close it gets.
 At easy it averages a bit over a hundred across nine balls, at fair about
 three hundred and fifty, and at hard a little over five hundred — and it
 visibly nearly-misses in the same way a person does, because it is missing
 in the same way.


-------------------------------------------------------------------------------
 THREE VIEWS
-------------------------------------------------------------------------------

     1   From above    the plan, and the easiest to read the plate in
     2   Raked         standing at the machine, which is the one to play in
     3   Free 3D       the same again from wherever you drag it to

 Hold the right button in Free 3D and drag, and the machine turns under
 you. Dragging takes hold of the machine rather than of the camera — pull
 the near edge downwards and the lane tips towards you, so you end up
 looking from higher up; pull it up and you drop towards the floor.
 Sideways turns it. The wheel goes closer and further away.

 Doing it in either of the other two quietly switches to Free 3D rather
 than doing nothing, because somebody dragging with the right button is
 asking to look around and the honest answer is to let them. The plan is
 the one view that never turns: it is the plan, and it stops being the plan
 the moment it can be nudged off square.

 The eye can be dragged from eight degrees below the horizontal to
 eighty-four above. Not to the floor, because from there the plate is
 edge-on and the holes close to nothing, which is a view of a plank; and
 not to straight down, where the arithmetic for which way is up stops
 having an answer.

 All three are one camera and one lot of drawing code, so the ball is where
 the physics says it is in every one of them rather than in three places
 that have to be kept agreeing.

 The plate leans back rather than standing up. That is how the machines are
 built, and it is also the only way the view from straight above is any use:
 a plate standing upright is edge-on from up there and collapses to a line,
 which is a picture of nothing.


-------------------------------------------------------------------------------
 DRAWN, NOT PHOTOGRAPHED
-------------------------------------------------------------------------------

 There is not a photograph or a sprite anywhere in the program. The maple is
 grain made out of smoothed noise and drawn board by board; the ramp is
 painted as strips across the lane so each one can be shaded for the angle
 the boards are at just there, which is why it looks round instead of
 looking like a wedge with a picture of wood on it; the holes are a mouth, a
 rim lit on the side the lamp is on, a net and a dark inside; and the
 cabinet is cut and lit in code.

 One lamp hangs over the lane, and everything is shaded against that one
 light. One light consistently applied is most of what makes a drawn thing
 look like a photographed one — far more than detail is.

 The ball has six things going on and every one of them is something a real
 ball does: the lit body, the soft band where the light gives out (never a
 hard line on something round), warm light bouncing back up off the pale
 boards into its underside, a thin bright rim from the room behind it, a
 small hard highlight that is the actual reflection of the lamp and is
 offset towards it rather than centred, and fine speckle, because a
 composite ball is not poured plastic. Its shadow spreads and fades as the
 ball rises, because the same darkness is being shared over more floor.

 Drawn rather than fetched means it is sharp at any size and there is no
 folder of pictures to lose.


-------------------------------------------------------------------------------
 THE PHYSICS
-------------------------------------------------------------------------------

 The ball rolls the length of the lane losing a little to friction, climbs
 the ramp losing a little more to the climb — five sevenths of what a
 sliding thing would lose, which is a solid sphere's share, because a
 rolling ball carries energy in its spin as well as its motion — leaves the
 lip at the angle the ramp is built at, and flies.

 The flight is ordinary ballistics. The plate it comes down on leans, so
 "has it arrived" is which side of a sloping plane the ball is on rather
 than how far up the lane it has got, checked either side of every step so
 that a fast ball cannot be past the plate before anything has looked.

 Reading the equation the other way — speed in, place on the plate out — is
 done by halving rather than by algebra. With the ramp and the plate both at
 forty-five degrees the two happen to cancel and the answer is a straight
 line, but that is a coincidence of two numbers that are meant to be
 adjustable, and an equation that is only right while nobody touches them is
 a trap rather than a saving.

 The holes are a shade larger than an alley machine's. A hole takes a ball
 only if the whole ball fits, so what you are aiming at is the hole less one
 ball — and at true dimensions that leaves about three quarters of an inch
 of room in the fifty, which is unplayable when the aiming is a sweeping
 line rather than your own arm.


-------------------------------------------------------------------------------
 THE REST OF IT
-------------------------------------------------------------------------------

 Tickets. Every frame pays out the way an alley does — one for every ten
 points and five more for each hundred, because the corners are the ones
 people remember. They add up across sessions and the prize wall says what
 the tin is worth, from a paper fortune fish at forty to the enormous bear
 nobody has ever won at twenty-five thousand.

 Best frames, kept with the date.

 Maple, oak or walnut, if you would rather the lane were darker.

 The arc the ball will take, shown or not, as you like.

 Settings, tickets and best frames live in ~/.config/skee_ball/skee_ball.save.
 Deleting that file puts everything back as it started.


-------------------------------------------------------------------------------
 KEYS
-------------------------------------------------------------------------------

     Space      press, and hold-then-release to throw
     S          sound on or off
     1 2 3      from above, raked, free 3D
     right drag turn the machine round, in Free 3D
     wheel      closer and further away
     Ctrl+N     another frame
     F1         how to play
     Esc        out


-------------------------------------------------------------------------------
 RUNNING IT — NOTHING TO INSTALL
-------------------------------------------------------------------------------

     chmod +x Skee_Ball.AppImage
     ./Skee_Ball.AppImage

 Python, Qt and PySide6 all travel inside it. Nothing on the machine is used
 and nothing on the machine can conflict with it.

 On the command line:

     ./Skee_Ball.AppImage --game rush --aim classic
     ./Skee_Ball.AppImage --version

 On a machine without FUSE, add --appimage-extract-and-run.
