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

@c TODO(pass 3): Klondike, FreeCell, Spider, Yukon, Canfield, Forty
@c Thieves, Scorpion, Golf, TriPeaks, Pyramid, Gaps/Montana, Hell's
@c Half-Acre, Russian Bank (patience) -- object, rules, strategy, keys.

@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