Card Games for Emacs
********************

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

Copyright © 2026 Corwin Brust.

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

     The Card Games for Emacs program is free software, licensed under the GNU General Public License, version 3 or later.

Introduction
************

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 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 (see 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 RET acts.  Clicking a card does the same thing.

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

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.  See Solitaire Games.

Trick-taking
     500, Hearts, Spades, Whist, Oh Hell, Euchre, Pitch, Briscola, and Contract Bridge.  See Trick-Taking Games.

Rummy
     Gin Rummy, Rummy, Rummy 500, and the partnership game Hand & Foot. See Rummy Games.

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

Two-player Russian Bank
     The competitive duel, Crapette, against the computer.  See Russian Bank.

To start, type M-x card-game.

Installation
************

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.

From a package archive
======================

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

From source
===========

Clone the repository from https://code.bru.st/corwin/card-game.el, add it to your load-path, and load the umbrella file:

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

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

Building
========

The Makefile provides the usual developer targets:

make compile
     Byte-compile all the sources.

make test
     Run the ERT test suite.

make info
     Build this manual (also make html and make pdf).

make package
     Build the installable .tar.

The Game Menu
*************

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

Two controls sit at the top of the list.

AI opponents
     Sets how hard the computer plays: easy, normal, or hard.  Click it to cycle, or use M-x card-games-set-ai-level. See Opponents.

Cards
     Chooses how the games are drawn: text, svg, or full. Click it to cycle, or use M-x card-games-set-treatment. See Display.

Playing
*******

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

LEFT RIGHT UP DOWN
     Move the highlighted cursor between cards and piles.

RET
     Act on the cursor: pick up or drop a card, play it, or select it.  Many games also accept SPC.

mouse-1
     Click a card or pile to do the same as moving the cursor there and acting.

f
     Where there are foundations, send the chosen card to one.

u
     Undo the last move, in the games that support it.

n
     Deal a new game.

g
     Redraw the board.

?
     Describe the game's controls.

q
     Leave the game and return to the menu (see The Game Menu).

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

Customization
*************

All the options live in the card-games customization group; type M-x customize-group RET card-games RET to browse them. The most useful are collected here.

Display
=======

M-x card-games-set-treatment switches every game between three treatments: text draws UNICODE cards, svg draws SVG cards, and 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 (see The Game Menu).  A change takes effect the next time a game is drawn; press g to redraw an open game.

The card size follows cg-card-scale and the zoom keys (see Playing).

Cards and colours
=================

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

With cg-svg-four-color non-nil, clubs are drawn green and diamonds blue, so all four suits are told apart by colour.

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 ♤ ♧ ♢ ♡, say, instead of the filled ones.

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

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

The Emacs emblem
================

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

Keys
====

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

Opponents
=========

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

Solitaire Games
***************

The one-player games.  Most are 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.

The shared keys for the tableau builders are:

LEFT RIGHT
     Move the cursor between piles.

RET (or SPC)
     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).

f
     Send the card under the cursor to a foundation.

a
     Auto-play the cards that plainly belong on the foundations.

u
     Undo the last move.

n / g / ? / q
     New deal, redraw, describe the keys, and return to the menu.

With cg-keys set to classic the vi keys h j k l move as well (see Keys).

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.

Set cg-sol-klondike-draw to 3 for the harder turn-three variant.

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.

FreeCell
========

Every card is dealt face up into eight columns, and four 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.

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.

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 RET on the stock to deal one card to every column --- but only when no column is empty.

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.

Yukon
=====

Klondike's layout, dealt mostly face up, with one liberating difference: you may move 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.

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

Canfield
========

A thirteen-card 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.

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

Forty Thieves
=============

Two decks, ten columns, eight foundations.  The tableau builds down 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.

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

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.

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

Russian Bank
============

The one-player patience: eight 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, see Russian Bank.)

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

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 or below the waste's top card; the sequence does not wrap, so nothing follows a King. Turn a fresh card from the stock when you are stuck.  Clear the whole layout to win.

Use the arrow keys or the mouse to choose a card, RET to play it (or, on the stock, to deal), u to undo, and n for a new deal.

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

TriPeaks
========

Golf played over three overlapping peaks, with one change: the sequence 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.

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

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.

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

Gaps
====

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, ..., 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 +.

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

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

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, ..., down to the Two.  The controls are identical.

Trick-Taking Games
******************

Rummy Games
***********

Matching Games
**************

Capturing Games
***************

Climbing Games
**************

Russian Bank
************

Networked Play
**************

Credits
*******

License
*******

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