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.
* 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

@c TODO(pass 4): 500, Hearts, Spades, Whist, Oh Hell, Euchre, Pitch,
@c Briscola, Bridge.

@node Rummy Games
@chapter Rummy Games

@c TODO(pass 5): Gin Rummy, Rummy, Rummy 500, Hand & Foot.

@node Matching Games
@chapter Matching Games

@c TODO(pass 5): Go Fish, Old Maid.

@node Capturing Games
@chapter Capturing Games

@c TODO(pass 5): Scopa, Casino.

@node Climbing Games
@chapter Climbing Games

@c TODO(pass 5): President, Spite & Malice, Cribbage.

@node Russian Bank
@chapter Russian Bank

@c TODO(pass 6): Crapette -- the two-player duel, foundations, houses,
@c loading, the stop rule, sequenced moves, the difficulty dial.

@node Networked Play
@chapter Networked Play

@c TODO(pass 6): live 500 over TCP -- cg-bid-host, cg-bid-join, lobbies.

@node Credits
@chapter Credits

@c TODO(pass 6): rules sources (Wikipedia, Pagat); thanks to testers;
@c a credit for Claude (the AI assistant who helped build much of this).

@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