card-game.el/doc/card-games.texi

\input texinfo   @c -*- texinfo -*-
@c %**start of header
@setfilename card-games.info
@settitle Card Games for Emacs
@documentencoding UTF-8
@documentlanguage en
@syncodeindex vr cp
@syncodeindex fn cp
@c %**end of header

@set VERSION 1.0.90
@set YEAR 2026

@copying
This manual is for Card Games for Emacs (version @value{VERSION}), an
Emacs package that plays card games as UNICODE text in a terminal and as
SVG cards on a graphical display.

Copyright @copyright{} @value{YEAR} Corwin Brust.

@quotation
This manual is licensed under the Creative Commons Attribution 4.0
International License.  To view a copy of this license, visit
@url{https://creativecommons.org/licenses/by/4.0/}.

The Card Games for Emacs @emph{program} is free software, licensed under
the GNU General Public License, version 3 or later.
@end quotation
@end copying

@dircategory Emacs
@direntry
* Card Games: (card-games).     Play card games in Emacs (text and SVG).
@end direntry

@titlepage
@title Card Games for Emacs
@subtitle A collection of solitaire, two-player, and partnership games
@subtitle for GNU Emacs, version @value{VERSION}
@author Corwin Brust
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Card Games for Emacs

@insertcopying
@end ifnottex

@menu
* Introduction::                What this package is.
* Installation::                Getting it, and starting to play.
* The Game Menu::               The chooser, and its controls.
* Playing::                     Controls shared by every game.
* Customization::               Colours, cards, keys, and opponents.
* Solitaire Games::             One-player patiences.
* Trick-Taking Games::          Hearts, Spades, Bridge, and friends.
* Rummy Games::                 Melds, knocks, and books.
* Matching Games::              Go Fish and Old Maid.
* Capturing Games::             Scopa and Casino.
* Climbing Games::              President and Spite & Malice.
* Cribbage::                    The pegging game, to 121.
* Russian Bank::                The two-player duel.
* Networked Play::              Live 500 over the network.
* Credits::                     Sources and thanks.
* License::                     Terms for this manual.
* Index::                       Commands, variables, and concepts.
@end menu

@node Introduction
@chapter Introduction

@cindex introduction
@cindex about
Card Games for Emacs is a collection of more than thirty card games ---
solitaires, two-player games, and four-handed partnership games ---
played entirely inside GNU Emacs.

Every game draws itself two ways.  In a terminal it uses plain UNICODE
text, so it works anywhere Emacs runs, including over @command{ssh} and
on a phone.  On a graphical display it draws proper SVG cards, with a
felt table for the four-handed games.  You can switch between these
treatments at any time (@pxref{Customization}).

You play with the keyboard, the mouse, or both.  A highlighted cursor
marks the card or pile you are about to act on; the arrow keys move it
and @key{RET} acts.  Clicking a card does the same thing.

@cindex families of games
The games are grouped into families that share an engine and a feel:

@table @asis
@item Solitaire
Klondike, FreeCell, Spider, Yukon, Canfield, Forty Thieves, Scorpion,
Golf, TriPeaks, Pyramid, Gaps (Montana), and Hell's Half-Acre, plus a
one-player Russian Bank.  @xref{Solitaire Games}.

@item Trick-taking
500, Hearts, Spades, Whist, Oh Hell, Euchre, Pitch, Briscola, and
Contract Bridge.  @xref{Trick-Taking Games}.

@item Rummy
Gin Rummy, Rummy, Rummy 500, and the partnership game Hand & Foot.
@xref{Rummy Games}.

@item Matching, capturing, and climbing
Go Fish and Old Maid; Scopa and Casino; President, Spite & Malice, and
Cribbage.

@item Two-player Russian Bank
The competitive duel, Crapette, against the computer.  @xref{Russian
Bank}.
@end table

To start, type @kbd{M-x card-game}.

@node Installation
@chapter Installation

@cindex installation
@cindex requirements
Card Games for Emacs needs GNU Emacs 26.1 or newer.  SVG display
additionally needs an Emacs built with image support (any modern
graphical Emacs has it); in a terminal the games fall back to text.

@menu
* From a package archive::      The easy way.
* From source::                 Cloning the repository.
* Building::                    Compiling, testing, and the manual.
@end menu

@node From a package archive
@section From a package archive

@cindex ELPA
When the package is available from a package archive, install it the
usual way with @kbd{M-x package-install @key{RET} card-games @key{RET}}.
The autoloads let you run @kbd{M-x card-game} straight away.

@node From source
@section From source

@cindex source, installing from
Clone the repository from @url{https://code.bru.st/corwin/card-game.el},
add it to your @code{load-path}, and load the umbrella file:

@example
(add-to-list 'load-path "/path/to/card-game.el")
(require 'card-games)
@end example

@noindent
Then @kbd{M-x card-game}.  You can also build an installable tarball with
@kbd{make package} and install it with @kbd{M-x package-install-file}.

@node Building
@section Building

@cindex Makefile
@cindex tests
The @file{Makefile} provides the usual developer targets:

@table @code
@item make compile
Byte-compile all the sources.
@item make test
Run the ERT test suite.
@item make info
Build this manual (also @code{make html} and @code{make pdf}).
@item make package
Build the installable @file{.tar}.
@end table

@node The Game Menu
@chapter The Game Menu

@findex card-game
@findex card-games
@cindex chooser
@cindex menu
@kbd{M-x card-game} (also available as @code{card-games}) opens the
chooser: a buffer listing every game with a one-line description.  Move
between games with @key{TAB} and @kbd{S-@key{TAB}}, or @kbd{n} and
@kbd{p}, and press @key{RET} --- or click a game's name --- to start it.
@kbd{q} buries the menu.

Two controls sit at the top of the list.

@table @asis
@item AI opponents
@vindex cg-ai-level
Sets how hard the computer plays: @code{easy}, @code{normal}, or
@code{hard}.  Click it to cycle, or use @kbd{M-x card-games-set-ai-level}.
@xref{Opponents}.

@item Cards
@vindex card-games-treatment
Chooses how the games are drawn: @code{text}, @code{svg}, or @code{full}.
Click it to cycle, or use @kbd{M-x card-games-set-treatment}.
@xref{Display}.
@end table

@node Playing
@chapter Playing

@cindex controls, shared
@cindex keys
Each game has its own rules and a few keys of its own, but the basic
controls are the same everywhere.  Press @kbd{?} in any game to see that
game's keys in the echo area.

@table @kbd
@item @key{LEFT} @key{RIGHT} @key{UP} @key{DOWN}
Move the highlighted cursor between cards and piles.
@item @key{RET}
Act on the cursor: pick up or drop a card, play it, or select it.  Many
games also accept @key{SPC}.
@item mouse-1
Click a card or pile to do the same as moving the cursor there and
acting.
@item f
Where there are foundations, send the chosen card to one.
@item u
Undo the last move, in the games that support it.
@item n
Deal a new game.
@item g
Redraw the board.
@item ?
Describe the game's controls.
@item q
Leave the game and return to the menu (@pxref{The Game Menu}).
@end table

@cindex zoom
@vindex cg-card-scale
On a graphical display, @kbd{+} and @kbd{-} (and @kbd{=}) make the cards
larger and smaller, and @kbd{0} resets the size.  Emacs's own
@code{text-scale-adjust} works too.  Many boards show a one-line legend
of the current game's keys along the bottom.

@node Customization
@chapter Customization

@cindex customization
All the options live in the @code{card-games} customization group; type
@kbd{M-x customize-group @key{RET} card-games @key{RET}} to browse them.
The most useful are collected here.

@menu
* Display::                     Text, SVG cards, or a full table.
* Cards and colours::           Backs, decks, glyphs, and themes.
* The Emacs emblem::            Which logo the full table shows.
* Keys::                        Emacs or classic movement.
* Opponents::                   How hard the computer plays.
@end menu

@node Display
@section Display

@vindex card-games-treatment
@findex card-games-set-treatment
@kbd{M-x card-games-set-treatment} switches every game between three
treatments: @code{text} draws UNICODE cards, @code{svg} draws SVG cards,
and @code{full} additionally uses the full-window SVG table for the games
that have one (Gaps and 500).  You can also cycle it from the menu
(@pxref{The Game Menu}).  A change takes effect the next time a game is
drawn; press @kbd{g} to redraw an open game.

@vindex cg-card-scale
The card size follows @code{cg-card-scale} and the zoom keys
(@pxref{Playing}).

@node Cards and colours
@section Cards and colours

@vindex cg-svg-card-back
@findex cg-svg-shuffle-card-back
@cindex card backs
The pattern on a face-down card is @code{cg-svg-card-back}.  Besides
@code{dots}, @code{rings}, and @code{solid} there are the drawn patterns
@code{lattice}, @code{waves}, and @code{diamond}, and four backs stamped
with an Emacs logo: @code{emacs}, @code{emacs-classic}, @code{gnu}, and
@code{splash}.  The default, @code{random}, chooses a back for the
session; @kbd{M-x cg-svg-shuffle-card-back} rolls a new one, and
reopening the menu also re-rolls.

@vindex cg-svg-four-color
@cindex four-colour deck
With @code{cg-svg-four-color} non-@code{nil}, clubs are drawn green and
diamonds blue, so all four suits are told apart by colour.

@vindex cg-symbols
@cindex suit glyphs
@code{cg-symbols} maps each suit to the glyph used for it, in both the
text and the SVG cards; customize it to use the outlined suits
@samp{♤ ♧ ♢ ♡}, say, instead of the filled ones.

@findex card-games-set-theme
@vindex card-games-themes
@cindex themes
@kbd{M-x card-games-set-theme} applies a colour preset ---
@code{classic}, @code{dark}, or @code{contrast} --- setting the felt
colour, the card back, and the highlight together.  The individual
colours (@code{cg-svg-highlight-color}, @code{cg-bid-felt-color}, and the
rest) can also be set on their own.

@vindex cg-cursor-type
@cindex cursor
Card buffers hide the text cursor by default, since you act on the
highlighted card rather than on point; @code{cg-cursor-type} can bring it
back.

@node The Emacs emblem
@section The Emacs emblem

@vindex cg-svg-emacs-logo
@cindex logo
The full-window tables (500 and Gaps) show an Emacs emblem in a corner.
@code{cg-svg-emacs-logo} chooses it: @code{modern} (the current Emacs
icon, the default), @code{classic} (the older icon), @code{gnu} (a GNU
head), @code{splash} (the startup image), @code{drawn} (a small built-in
emblem), or @code{none}.  The image choices embed a logo that ships with
your Emacs, falling back to the drawn emblem when it cannot be found.

@node Keys
@section Keys

@vindex cg-keys
@cindex key scheme
@code{cg-keys} selects a movement scheme.  @code{emacs} (the default)
follows Emacs conventions --- the arrow keys move and @key{RET} acts.
@code{classic} additionally enables @kbd{h} @kbd{j} @kbd{k} @kbd{l} and
@key{SPC}.  A change takes effect the next time a game starts.

@node Opponents
@section Opponents

@vindex cg-ai-level
@findex card-games-set-ai-level
@cindex difficulty
@code{cg-ai-level} sets how hard the computer plays: @code{easy},
@code{normal}, or @code{hard}.  Russian Bank plays all three levels; the
trick-taking games play a random legal card on @code{easy} and their
usual game otherwise.  Other games do not yet consult it.  Set it with
@kbd{M-x card-games-set-ai-level} or from the menu.

@node Solitaire Games
@chapter Solitaire Games

@cindex solitaire
@cindex patience
The one-player games.  Most are @dfn{tableau builders} that share the
same controls; the pile games (Golf, TriPeaks, Pyramid) and the gaps
games (Gaps, Hell's Half-Acre) play a little differently and say so in
their own sections.

@cindex solitaire, controls
The shared keys for the tableau builders are:

@table @kbd
@item @key{LEFT} @key{RIGHT}
Move the cursor between piles.
@item @key{RET} @r{(or} @key{SPC}@r{)}
Pick up the card, or the movable run, under the cursor; press again on a
destination to drop it.  On the stock, deal cards to the waste (or, when
the stock is empty, recycle the waste where the game allows).
@item f
Send the card under the cursor to a foundation.
@item a
Auto-play the cards that plainly belong on the foundations.
@item u
Undo the last move.
@item n @r{/} g @r{/} ? @r{/} q
New deal, redraw, describe the keys, and return to the menu.
@end table

@noindent
With @code{cg-keys} set to @code{classic} the vi keys @kbd{h} @kbd{j}
@kbd{k} @kbd{l} move as well (@pxref{Keys}).

@menu
* Klondike::                    The classic.
* FreeCell::                    A game of pure skill.
* Spider::                      Two decks; clear eight suited runs.
* Yukon::                       Klondike, but move any group.
* Canfield::                    A reserve and a wrapping base rank.
* Forty Thieves::               Two decks, no redeal, and hard.
* Scorpion::                    Free four buried runs.
* Russian Bank Solitaire::      Houses and a feeding reserve.
* Golf::                        One rank up or down.
* TriPeaks::                    Golf with wrapping chains.
* Pyramid::                     Remove pairs that sum to thirteen.
* Gaps::                        Order the rows through the gaps.
* Hell's Half-Acre::            Gaps, built the other way.
@end menu

@node Klondike
@section Klondike

@findex cg-klondike
@cindex Klondike
The classic.  Build the four foundations up in suit, Ace to King.  Seven
columns hold a descending, alternating-colour tableau; move a card or an
ordered run onto the next-higher card of the other colour, and fill an
empty column with a King (or a King-headed run).  Turn cards from the
stock to the waste --- one at a time by default --- and recycle the
waste when the stock runs out.

@vindex cg-sol-klondike-draw
Set @code{cg-sol-klondike-draw} to @code{3} for the harder
turn-three variant.

@cindex strategy, Klondike
@strong{Strategy.}  Uncover face-down cards before anything else, and
keep a column open for a King.  Do not rush low cards to the foundations
if you may still need them to receive tableau cards.

@node FreeCell
@section FreeCell

@findex cg-freecell
@cindex FreeCell
Every card is dealt face up into eight columns, and four @dfn{free cells}
each hold a single card.  Build the tableau down in alternating colour
and the foundations up in suit.  How large a run you can shift at once
depends on how many cells and empty columns are free.  Almost every deal
can be won --- this is a game of skill, not luck.

@strong{Strategy.}  Plan several moves ahead, free the aces early, and
resist filling all four cells; an empty column is worth more than a full
cell.

@node Spider
@section Spider

@findex cg-spider
@cindex Spider
Two decks, ten columns, no separate foundations.  Build down regardless
of suit, but only a same-suit run moves as a block.  Complete a
King-to-Ace run in one suit and it is lifted off the table; clear all
eight to win.  Press @key{RET} on the stock to deal one card to every
column --- but only when no column is empty.

@strong{Strategy.}  Build in suit whenever you have the choice, and empty
a column as soon as you can: it is the key to untangling the rest.

@node Yukon
@section Yukon

@findex cg-yukon
@cindex Yukon
Klondike's layout, dealt mostly face up, with one liberating difference:
you may move @emph{any} face-up card, together with everything piled on
top of it, onto a card one higher of the other colour --- the group need
not be in order.  There is no stock.

@strong{Strategy.}  Expose the face-down cards; the freedom to lift
buried groups wins many deals that Klondike would lose.

@node Canfield
@section Canfield

@findex cg-canfield
@cindex Canfield
A thirteen-card @dfn{reserve}, four tableau columns, and a stock dealt
three at a time.  The first card sets the base rank for the foundations,
which build up in suit and wrap from King round to Ace.  The tableau
builds down in alternating colour, and an empty column refills from the
reserve.

@strong{Strategy.}  Clear the reserve --- it is the bottleneck --- and
keep the wrapping base rank in mind when you choose what to bank.

@node Forty Thieves
@section Forty Thieves

@findex cg-forty-thieves
@cindex Forty Thieves
Two decks, ten columns, eight foundations.  The tableau builds down
@emph{in suit} and moves one card at a time; the foundations build up in
suit; the stock deals to the waste with no redeal.  A hard, skilful game.

@strong{Strategy.}  Be patient, keep the waste short, and avoid burying
the low cards you will need.

@node Scorpion
@section Scorpion

@findex cg-scorpion
@cindex Scorpion
Seven columns, built down in suit.  As in Yukon you may move any card
with everything on top of it, ordered or not.  Free four King-to-Ace runs
to win.  A small stock deals onto the first columns when you are stuck.

@strong{Strategy.}  Dig the buried low cards out early, and think about
which King you can afford to complete first.

@node Russian Bank Solitaire
@section Russian Bank

@findex cg-russian-bank
@cindex Russian Bank, solitaire
The one-player patience: eight @dfn{houses} built down in alternating
colour, four foundations built up in suit from the Ace, and a
thirteen-card reserve that feeds an empty house.  (For the competitive
two-player game, @pxref{Russian Bank}.)

@strong{Strategy.}  Play to the foundations first and empty the reserve;
the houses are just working space.

@node Golf
@section Golf

@findex cg-golf
@cindex Golf
A layout of thirty-five cards over a single waste pile.  Play any exposed
card onto the waste when it is one rank above @emph{or} below the waste's
top card; the sequence does @emph{not} wrap, so nothing follows a King.
Turn a fresh card from the stock when you are stuck.  Clear the whole
layout to win.

@cindex controls, pile games
Use the arrow keys or the mouse to choose a card, @key{RET} to play it
(or, on the stock, to deal), @kbd{u} to undo, and @kbd{n} for a new deal.

@strong{Strategy.}  Look for long up-and-down chains before you spend a
card from the stock.

@node TriPeaks
@section TriPeaks

@findex cg-tripeaks
@cindex TriPeaks
Golf played over three overlapping peaks, with one change: the sequence
@emph{wraps}, so an Ace follows a King and a King follows an Ace.  That
lets you run long chains across the peaks.  Clear all three to win.  The
keys are the same as Golf.

@strong{Strategy.}  Plan the chain that uncovers the most cards, and hold
the stock in reserve for when the board truly stalls.

@node Pyramid
@section Pyramid

@findex cg-pyramid
@cindex Pyramid
A twenty-eight-card pyramid.  Remove pairs of exposed cards whose ranks
sum to thirteen --- Ace counts 1, Jack 11, Queen 12, and a King is 13, so
a King leaves on its own.  Mark one card and then its partner to remove
them, and deal from the stock for more matches.  Clear the pyramid to
win.

@strong{Strategy.}  Free the cards that block two others at once, and do
not strand a card whose only partner is already gone.

@node Gaps
@section Gaps

@findex cg-montana
@findex cg-gaps
@cindex Gaps
@cindex Montana
Also called Montana.  The pack is dealt into four rows with gaps between
the cards.  Each row is built as one suit, with a Two at the head, rising
Two, Three, @dots{}, up to the King.  Move a card into a gap when it
continues the row --- the card one higher, in the same suit, than the
card to the gap's left.  Fillable gaps are ringed and marked with a green
@samp{+}.

When no move remains, @kbd{r} reshuffles the misplaced cards for another
try; you get a limited number of these redeals.  @kbd{v} toggles the
full-window layout.  Order every row to win.

@strong{Strategy.}  Open the gaps that let a Two, then a Three, begin
each row, and spend redeals only when you are truly stuck.

@node Hell's Half-Acre
@section Hell's Half-Acre

@findex cg-hells-half-acre
@cindex Hell's Half-Acre
The same game as Gaps, built the other way: a King anchors the head of
each row and the rows descend King, Queen, @dots{}, down to the Two.  The
controls are identical.

@node Trick-Taking Games
@chapter Trick-Taking Games

@cindex trick-taking
@cindex tricks
In these games the four players each play a card to the @dfn{trick}, and
the highest card (or the highest trump) wins it.  You sit South; the
other three seats are computer players, and for the partnership games
North is your partner.

@cindex trick games, controls
Most of them share these controls:

@table @kbd
@item @key{LEFT} @key{RIGHT}
Choose a card in your hand.
@item @key{RET} @r{(or} @key{SPC}@r{)}
Play the chosen card.  During the Hearts pass it instead marks a card.
@item p
Confirm the Hearts pass, once three cards are marked.
@item n @r{/} g @r{/} ? @r{/} q
New match, redraw, describe the keys, and return to the menu.
@end table

@noindent
When a game calls for a bid, you are prompted for it in the minibuffer.
@xref{Opponents}, to set how hard the computer plays.  500 and Bridge
have richer boards and a few keys of their own, noted below.

@menu
* Five Hundred: 500.            Partnership bidding to 500.
* Hearts::                      Avoid the hearts and the black lady.
* Spades::                      Bid your tricks; spades are trump.
* Whist::                       Fixed trump, no bidding.
* Oh Hell::                     Bid exactly, on shrinking hands.
* Euchre::                      Bowers, and going alone.
* Pitch::                       Set the trump with your lead.
* Briscola::                    No follow; capture the points.
* Bridge: Contract Bridge.      The auction, the dummy, the rubber.
@end menu

@node 500
@section 500

@findex cg-bid
@cindex 500
Australia's national card game, and the flagship of this collection.  You
and North play against East and West.  After the deal there is an
auction: each side bids a number of tricks (six to ten) and a trump ---
or Misère, to take no tricks at all.  The high bidder takes the five-card
@dfn{kitty}, then discards five cards, and play begins.

The trump order runs Joker (highest), then the Jack of trump (right
bower) and the other Jack of the same colour (left bower), then Ace down
to Four.  Score the Avondale table for making or breaking the contract.
A side wins by reaching 500 on a contract it made (the ``front door''),
and loses by falling to @minus{}500 (the ``back door'').

@table @kbd
@item b
Make a bid; @kbd{p} passes.
@item @key{RET}
Select the card, or the kitty card, under the pointer.
@item x
Discard the five cards you have marked for the kitty.
@item v
Toggle the full-window table.
@item M-@key{UP} M-@key{DOWN}
Scroll the message log (the mouse wheel works too).
@item n @r{/} ? @r{/} q
New game, help, and the menu.
@end table

@noindent
500 can also be played live against other people over the network.
@xref{Networked Play}.

@strong{Strategy.}  Bid what your trumps and side-suit aces can actually
make; take the kitty only when it can complete a contract; and keep
Misère for a hand too weak to win a single trick.

@node Hearts
@section Hearts

@findex cg-hearts
@cindex Hearts
An avoidance game with no trump.  Every heart costs one point and the
Queen of Spades costs thirteen, and you want as few as possible.  Before
each hand you pass three cards to another player --- left, right, across,
then a hand with no passing, and around again.  The Two of Clubs leads
the first trick, on which no points may be played.

Take @emph{all} the points in a hand and you ``shoot the moon'': the
twenty-six are charged to everyone else instead.  When a player reaches
100 the game ends and the lowest score wins.

@strong{Strategy.}  Void a suit so you can throw the Queen or a heart into
it; keep track of who might hold the Queen; and only chase the moon with a
hand that cannot be stopped.

@node Spades
@section Spades

@findex cg-spades
@cindex Spades
Spades are always trump.  Each player bids the number of tricks they
expect to win, and the two partners' bids are added: your side must make
that combined total.  Extra tricks (``bags'') score a point each, but
every tenth bag costs you 100.  A bid and made @dfn{Nil} --- no tricks at
all --- scores 100, or loses 100 if broken.  Play to 500.

@strong{Strategy.}  Count your sure winners before you bid; go Nil only
with low spades and short, duckable side suits; and protect your
partner's Nil when you can.

@node Whist
@section Whist

@findex cg-whist
@cindex Whist
The old English ancestor of Bridge, with no bidding.  The dealer's last
card is turned for trump.  Follow the suit led if you can; trumps beat the
plain suits.  Each side counts one point for every trick it wins beyond
the @dfn{book} of six, and the first side to five wins.

@strong{Strategy.}  Lead from your longest suit, draw the opponents'
trumps, and remember the cards that have gone.

@node Oh Hell
@section Oh Hell

@findex cg-ohhell
@cindex Oh Hell
The hand shrinks every deal, from seven cards down to one, and a card is
turned for trump.  Each player bids the @emph{exact} number of tricks
they will take and scores a bonus only for hitting it precisely --- one
over or under and the bonus is lost.  Play the fixed run of rounds; it is
every player for themselves.

@strong{Strategy.}  On the small hands a high card is a sure trick and a
low one a sure miss; do not be afraid to bid zero and duck everything.

@node Euchre
@section Euchre

@findex cg-euchre
@cindex Euchre
A brisk 24-card game (Nine to Ace).  The Jack of the trump suit (the
@dfn{right bower}) and the other Jack of the same colour (the @dfn{left
bower}) are the two highest trumps.  A card is turned up, and you may
@dfn{order it up} as trump or, later, name a different suit.  The side
that names trump must take three of the five tricks.  Partnership to 10.

You are asked whether to order up the turned card (@kbd{y} or @kbd{n})
and, if bidding comes round again, to name a trump.

@strong{Strategy.}  Order up with three trumps, or two trumps and an
off-suit Ace; a very strong hand can be played ``alone'' for a bigger
score.

@node Pitch
@section Pitch

@findex cg-pitch
@cindex Pitch
Auction Pitch.  Players bid for the right to @dfn{pitch}, and the
pitcher's first lead sets the trump suit.  Thereafter follow the led suit
if you can, but you may always trump instead.  Four points are at stake
each hand --- High, Low, Jack, and Game --- and the first to seven wins.

@strong{Strategy.}  Bid only on a solid trump holding, ideally with the
Jack or with both the highest and lowest trumps.

@node Briscola
@section Briscola

@findex cg-briscola
@cindex Briscola
A 40-card Italian game.  One card is turned to fix the trump, the
@dfn{briscola}, and --- unusually --- there is no need to follow suit: you
may play any card to any trick.  Winning a trick captures its cards, and
the Aces and Threes carry the most points.  Capture the points; the first
to 61 of the 120 wins.

@strong{Strategy.}  Save your briscole to capture the opponents' Aces, and
lead worthless cards to coax points out of them.

@node Contract Bridge
@section Bridge

@findex cg-bridge
@cindex Bridge
@cindex Contract Bridge
The full game: the auction, then the play with the dummy exposed, and
rubber scoring.  You sit South and partner North against East and West.

In the auction you compose a call and make it: @key{UP} and @key{DOWN}
change the level, @key{LEFT} and @key{RIGHT} change the strain, @key{RET}
bids it, @kbd{p} passes, and @kbd{d} doubles.  When the auction ends, the
declaring side's first player is declarer and their partner is the dummy,
whose hand is turned face up; the declarer plays both hands, so you play
the dummy from your seat when it is the dummy's turn.  Making your
contract scores below the line toward game and the rubber.

@table @kbd
@item arrows @r{and} @key{RET}
Compose and make a call (auction), or choose and play a card (play).
@item p @r{/} d
Pass and double, during the auction.
@item n @r{/} g @r{/} q
Next deal, redraw, and the menu.
@end table

@strong{Strategy.}  Count your high-card points, look for an eight-card
trump fit with your partner, and plan the whole hand --- drawing trumps,
setting up a long suit --- before you play to the first trick.

@node Rummy Games
@chapter Rummy Games

@cindex rummy
@cindex melds
Draw a card --- from the stock or the discard pile --- then throw one
away, and work your hand into @dfn{melds}: @dfn{sets} of three or four of
a kind, and @dfn{runs} of three or more cards in one suit.

@menu
* Gin Rummy::                   Knock with little deadwood.
* Rummy::                       Meld your whole hand to go out.
* Rummy 500::                   Score the cards you lay down.
* Hand & Foot::                 The partnership Canasta cousin.
@end menu

@node Gin Rummy
@section Gin Rummy

@findex cg-gin
@cindex Gin Rummy
@cindex deadwood
@cindex knock
Two-handed, with ten-card hands.  Draw from the stock (@kbd{s}) or take
the up-card (@kbd{t}), then discard with @key{RET}.  When your unmatched
cards --- your @dfn{deadwood} --- add up to ten points or fewer you may
@dfn{knock} (@kbd{k}) and end the hand; with no deadwood at all you go
@dfn{gin} for a bonus.  Your opponent then lays their own deadwood off
onto your melds.  First to 100 points wins.

@strong{Strategy.}  Keep cards that could join more than one meld, knock
early against a slow hand, and note which cards your opponent takes.

@node Rummy
@section Rummy

@findex cg-rummy-basic
@cindex Rummy
Draw and discard, and lay your melds down on the table.  Mark the cards
of a meld with @key{SPC} and lay it down with @kbd{m}; add a single card
to a meld already on the table (yours or anyone's) with @kbd{l}.  Get rid
of your whole hand to go out.

@table @kbd
@item @key{SPC} @r{/} m @r{/} l
Mark cards, meld them, lay one off.
@item s @r{/} t @r{/} @key{RET}
Draw from the stock, take the up-card, discard.
@end table

@strong{Strategy.}  Do not meld too soon --- cards on the table cannot be
rearranged, and they tell your opponents what you hold.

@node Rummy 500
@section Rummy 500

@findex cg-rum500
@cindex Rummy 500
Rummy played for points over many hands, first past 500.  You score the
cards you lay down and lose the ones left in your hand.  Besides the top
of the discard pile you may take a card from deeper in it with @kbd{T},
picking up that card and everything above it --- as long as you meld the
chosen card at once.  Aces count 15.

@strong{Strategy.}  Chase the high-scoring cards, and raid the discard
pile when the reward outweighs the cards it puts in your hand.

@node Hand & Foot
@section Hand & Foot

@findex cg-handfoot
@cindex Hand and Foot
A partnership cousin of Canasta.  You are dealt a @dfn{hand} and a
@dfn{foot}; play out the hand, then take up the foot.  Build @dfn{books}
of seven cards of a rank --- @dfn{clean} with no wild cards, or
@dfn{dirty} with some.  Twos and Jokers are wild; threes never meld.
Draw two cards with @kbd{s}, or pick up the whole discard pile with
@kbd{p} by melding its top card; meld (@kbd{m}), lay off (@kbd{l}), and
discard (@key{RET}).  Your side goes out once it has two complete books
and you have emptied your foot.

@strong{Strategy.}  Hoard wild cards for clean books, and do not go out
before your partner has played their foot.

@node Matching Games
@chapter Matching Games

@cindex matching games
Two light games of collecting and shedding, good for a quick sit-down.

@menu
* Go Fish::                     Ask for ranks; collect books of four.
* Old Maid::                    Shed pairs; dodge the odd Queen.
@end menu

@node Go Fish
@section Go Fish

@findex cg-go-fish
@cindex Go Fish
@cindex books
Collect @dfn{books} of four of a kind.  On your turn pick a rank you hold
--- click one of the rank buttons, or move the cursor to a card and it
selects that rank --- then press @kbd{1}, @kbd{2}, @kbd{3}, or @kbd{4} to
ask that player for it.  If they have any they must hand them over and you
ask again; if not, you ``go fish'' and draw from the stock.  Complete the
most books to win.

@strong{Strategy.}  Remember what everyone has asked for; it tells you
who holds what.

@node Old Maid
@section Old Maid

@findex cg-old-maid
@cindex Old Maid
One Queen is set aside, so a single Queen is left without a partner.
Throw out every pair in your hand, then draw a card, unseen, from the next
player: move over their face-down cards with the arrows (or click one) and
press @key{RET}.  Whoever is left holding the odd Queen at the end loses.

@strong{Strategy.}  Mostly luck --- but do not let your reactions reveal
where the odd Queen is hiding.

@node Capturing Games
@chapter Capturing Games

@cindex capturing games
@cindex fishing games
Play a card from your hand to the table; if it matches, it @dfn{captures}
table cards and takes them for scoring.  Press @key{RET} to play the card
under the cursor.

@menu
* Scopa::                       Sweep the table for a scopa.
* Casino::                      Big and little casino, and the sweeps.
@end menu

@node Scopa
@section Scopa

@findex cg-scopa
@cindex Scopa
A 40-card Italian game.  The card you play captures a single table card of
the same value, or a set of table cards that add up to its value.
Clearing the whole table at a stroke is a @dfn{scopa} and scores a bonus.
At the end of each round you score for taking the most cards, the most
coins, the Seven of Coins (the @dfn{sette bello}), and the @dfn{primiera};
play to 11.

@strong{Strategy.}  Watch the running total on the table, and try to leave
your opponent unable to make the capture that would sweep it.

@node Casino
@section Casino

@findex cg-casino
@cindex Casino
The 52-card cousin of Scopa.  Number cards capture by value as in Scopa;
face cards capture only by matching rank.  Score the @dfn{big casino}
(the Ten of Diamonds), the @dfn{little casino} (the Two of Spades), the
Aces, and the most cards and most spades; play to 21.

@strong{Strategy.}  Guard the two casinos and grab spades when you can ---
the little points decide close games.

@node Climbing Games
@chapter Climbing Games

@cindex climbing games
@cindex shedding games
Be the first to get rid of your cards by playing something that beats
what is already on the table.

@menu
* President::                   First out rules; last out scrubs.
* Spite & Malice::              Race to empty your goal pile.
@end menu

@node President
@section President

@findex cg-president
@cindex President
@cindex Scum
Also called Scum.  The leader plays one to four cards of a rank; the next
player must answer with the same number of a @emph{higher} rank, or pass
--- and here the Two is the highest card of all.  Whoever empties their
hand first is President; the last one out is the Scum, and before the next
deal the Scum must hand the President their best cards.

To lead more than one card of a rank, give a numeric prefix first ---
@kbd{C-u 2 @key{RET}} leads a pair.  @kbd{p} passes.

@strong{Strategy.}  Shed your low cards while the lead is cheap, and save
your Twos and your pairs to grab the lead back when it matters.

@node Spite & Malice
@section Spite & Malice

@findex cg-spite
@cindex Spite and Malice
@cindex Cat and Mouse
Race to empty your @dfn{goal} pile.  Four shared centre piles are built up
from Ace to Queen, and Kings are wild.  On your turn play a card from your
hand with @key{RET}, the top of your goal pile with @kbd{G}, or the top of
one of your four discard piles with @kbd{1}--@kbd{4}; then end your turn by
discarding a hand card with @kbd{d}.  The first to clear their goal pile
wins.

@strong{Strategy.}  Spend a wild King to reach the next goal card, and
keep your discard piles in order so you can unload them in turn.

@node Cribbage
@chapter Cribbage

@findex cg-cribbage
@cindex Cribbage
@cindex pegging
@cindex the crib
The classic two-player game, pegged to 121.  Each deal has three parts.

First, both players lay two cards face down to the dealer's @dfn{crib}:
mark them with @key{SPC} and confirm with @kbd{m}.  A @dfn{starter} card is
then cut.  Next comes @dfn{the play}: take turns laying cards (@key{RET}),
scoring as the running total reaches fifteen and thirty-one and for pairs
and runs made along the way.  Finally, @dfn{the show} scores each hand and
then the crib for its fifteens, pairs, runs, flushes, and @dfn{his nobs}
(the Jack of the starter's suit).  First to 121 wins.

@strong{Strategy.}  Weigh a strong hand against what you give away to the
crib, and always be counting toward the next fifteen and thirty-one.

@node Russian Bank
@chapter Russian Bank

@findex cg-crapette
@findex cg-russian-bank-duel
@cindex Russian Bank
@cindex Crapette
Russian Bank, also called Crapette, is the competitive two-player
ancestor of the solitaire (@pxref{Russian Bank Solitaire}).  You (South)
play against the computer (North), each with your own 52-card pack.

In the centre sit eight @dfn{foundations}, built up by suit from the Ace,
and eight @dfn{houses}, built down in alternating colour; both are common
ground either player may build on.  Each of you also has a thirteen-card
@dfn{reserve} (its top card face up), a @dfn{waste}, and a face-down
@dfn{hand}.  You win by getting rid of every card in your reserve, hand,
and waste.

On your turn you make as many legal moves as you like:

@itemize @bullet
@item
move the top of your reserve, your waste, or any house onto a foundation
or a house;
@item
move a whole @dfn{sequence} (a run built down in alternating colours) from
one house to another --- but only when there are enough empty houses to
have shifted it a card at a time; and
@item
@dfn{load} a card from your reserve or waste onto the opponent's reserve
or waste, when it is the same suit and one rank higher or lower.
@end itemize

@cindex stop rule
@vindex cg-crapette-stops
@strong{Foundation priority and ``Stop''.}  A card that can go to a
foundation must be played there before anything else.  If you build a
house, load your opponent, turn a card, or end your turn while a
foundation play is waiting, your opponent calls ``Stop!'' and your turn
ends at once --- the piles that owe a foundation play are ringed to warn
you.  Set @code{cg-crapette-stops} to @code{nil} for a gentler mode that
simply blocks the slip instead of ending your turn.

When you can do no more, turn the top of your hand: if it fits somewhere
you keep going, otherwise it goes to your waste and your turn ends.

@table @kbd
@item arrows
Move the cursor between piles.
@item @key{RET} @r{(or click)}
Pick up the card or run under the cursor; press again on a destination to
drop it.
@item f
Send the chosen card to a foundation.
@item [ @r{and} ]
Choose how many cards of a picked-up run to move onto an empty house.
@item @key{SPC} @r{(or} d@r{)}
Turn the top card of your hand.
@item e
End your turn.
@item u @r{/} n @r{/} q
Undo, new game, and the menu.
@end table

@noindent
@code{cg-ai-level} sets how hard North plays (@pxref{Opponents}): on
@code{hard} it even looks a move ahead to rearrange the houses.

@strong{Strategy.}  Play to the foundations first, and empty your reserve
--- it is the pile you must clear to win.  Load your spare cards onto your
opponent to slow them down, and keep an empty house free as room to shift
a sequence.

@node Networked Play
@chapter Networked Play

@findex cg-bid-host
@findex cg-bid-join
@cindex networked play
@cindex multiplayer
500 can be played live against other people over a TCP connection.  One
player hosts the game and the others join it.

@table @kbd
@item M-x cg-bid-host @key{RET} @var{port} @key{RET}
Start a game as the host.  You take the South seat and wait for others to
connect.
@item M-x cg-bid-join @key{RET} @var{host} @key{RET} @var{port} @key{RET} @var{name} @key{RET}
Connect to a host at @var{host} and @var{port} under a display
@var{name}.
@end table

@cindex lobby
The game starts automatically once four people have joined.  The host may
also press @kbd{s} to start early, with the computer filling any empty
seats.

@vindex cg-bid-shuffle-partners
With @code{cg-bid-shuffle-partners} non-@code{nil}, the joining players
are dealt randomly among the seats.  Each player's view is rotated so
they sit South, so the ordinary controls (@pxref{500}) work unchanged.
Play is turn-based and the host is authoritative; a client can join from
anywhere Emacs can open a network connection.

@node Credits
@chapter Credits

@cindex credits
@cindex acknowledgements
Card Games for Emacs was written by Corwin Brust.

The rules of the trickier games were checked against public references,
chiefly Wikipedia and John McLeod's card-game site, Pagat
(@url{https://www.pagat.com/}).  Thanks are due to the playtesters whose
feedback shaped the controls and the display.

@cindex Claude
Much of the code, and this manual, were written by Corwin Brust in
collaboration with Claude, an AI assistant made by Anthropic, over a
series of pair-programming sessions.

@node License
@appendix License

This manual is licensed under the Creative Commons Attribution 4.0
International License.  To view a copy of this license, visit
@url{https://creativecommons.org/licenses/by/4.0/}.

@node Index
@unnumbered Index

@printindex cp

@bye