card-game.el/README.org

#+TITLE: card-games -- Play card games in Emacs
#+AUTHOR: Corwin Brust

Card games for Emacs.

Renders SVG by default when ~display-graphic-p~ is t and rsvg is
available.  The default (UNICODE) symbols maybe customized by
configuring ~card-game-symbols~.

* Games

To open the game menu type ~M-x card-game~, or start a game directly
with its command.

** Trick-taking
- ~cg-bid~ -- 500 (Bid).  Win the auction, name the trump suit, then take
  tricks with your partner to reach 500 points before the opposing pair.
  Also playable live over the network (~M-x cg-bid-host~ / ~cg-bid-join~).
- ~cg-hearts~ -- Hearts.  Avoid taking hearts and the Queen of Spades, or
  take them all to "shoot the moon"; lowest score loses.
- ~cg-spades~ -- Spades.  Partnership bidding to 500; spades are always
  trump.  Make your side's combined bid, mind the bags, dare a nil.
- ~cg-whist~ -- Whist.  Trump is the turned card, there is no bidding;
  score one point for each trick past the book of six.
- ~cg-ohhell~ -- Oh Hell.  The hand shrinks each round; bid the exact
  number of tricks you will take, no more and no fewer.

** Solitaire
- ~cg-montana~ -- Montana (also called Gaps).  Each row is anchored by a
  Two and built upward in one suit, 2 through King; slide cards into the
  gaps until all four rows are sorted.
- ~cg-gaps~ -- an alias for ~cg-montana~.
- ~cg-hells-half-acre~ -- the build-down variant: each row is anchored by
  a King and built downward, King through 2.
- ~cg-klondike~ -- Klondike, the classic "Solitaire": build the four
  foundations up by suit from the Ace.
- ~cg-freecell~ -- FreeCell: every card in view, four free cells, a game
  of nearly pure skill.
- ~cg-spider~ -- Spider (two decks): build down regardless of suit, but
  only same-suit runs move; clear eight King-to-Ace runs.
- ~cg-yukon~ -- Yukon: Klondike's layout dealt mostly face up, with any
  buried group movable and no stock.
- ~cg-canfield~ -- Canfield: a 13-card reserve and a foundation base rank
  set by the deal; foundations wrap King to Ace.
- ~cg-forty-thieves~ -- Forty Thieves: two decks, ten columns, eight
  foundations, build down by suit, and no second pass through the stock.
- ~cg-scorpion~ -- Scorpion: build down by suit and free any buried group
  to assemble four King-to-Ace runs.
- ~cg-golf~ -- Golf: clear the layout by playing exposed cards one rank
  above or below the waste top.
- ~cg-tripeaks~ -- TriPeaks: the same, on three overlapping peaks, with
  Ace-King wrapping for long chains.
- ~cg-pyramid~ -- Pyramid: remove pairs of exposed cards whose ranks sum
  to thirteen; Kings go alone.

** Shedding and climbing
- ~cg-eights~ -- Crazy Eights.  Match the suit or rank of the discard;
  eights are wild and let you name the next suit.
- ~cg-president~ -- President (Scum).  Climb: play one to four of a rank,
  beat it or pass; first out rules, last out scrubs, and the roles trade
  cards on the next deal.

** Rummy
- ~cg-gin~ -- Gin Rummy.  A two-handed duel: draw or take the discard,
  build sets and runs, and knock once your deadwood is ten or less, or go
  gin with none; your opponent then lays off and may undercut you.  First
  to 100 wins.
- ~cg-rummy-basic~ -- Rummy.  Meld sets and runs onto the table and lay
  cards off onto them; empty your hand to go out and score the cards left
  in the other hands.
- ~cg-rum500~ -- Rummy 500.  As above, but you score the cards you lay
  down and lose the cards left in your hand; first past 500 wins.
- ~cg-handfoot~ -- Hand & Foot.  A partnership Canasta cousin: play a hand
  and then a foot, build books of a rank with Twos and Jokers wild, and go
  out once your side has completed two of them.

* TODO
- [X] make the suit symbols customizable (~cg-symbols~) and obey them
- [ ] a Texinfo manual
- [ ] renderer "skins": let games subclass the display components (text,
  SVG, full-window SVG)
- [ ] a manual card-size control for the full-window SVG UI
- [ ] more games

* Install
** From the package tarball
#+begin_src
make package           # builds card-games-1.0.60.tar
#+end_src
Then in Emacs: ~M-x package-install-file RET card-games-1.0.60.tar~.

** From a local ELPA archive
#+begin_src
make elpa              # builds dist/ (archive-contents + tar)
#+end_src
#+begin_src emacs-lisp
(add-to-list 'package-archives '("cg" . "/path/to/dist/"))
(package-refresh-contents)
(package-install 'card-games)
#+end_src

** Manually
Put the ~cg-*.el~ and ~card-games.el~ files on your ~load-path~ and
~(require 'card-games)~.

* Playing
Both games work with the keyboard everywhere and with the mouse on a
graphical display.

- 500: ~b~ bid, ~p~ pass, arrows + ~RET~ to play (or click a card),
  ~n~ next hand / new game, ~?~ help.
- Gaps: arrows to move (or ~hjkl~ when ~cg-keys~ is ~classic~), ~RET~ to
  fill a gap (or click it), ~r~ redeal, ~u~ undo, ~n~ new, ~?~ help.
- Klondike / FreeCell / Spider / Yukon: arrows move between piles, ~RET~
  picks up a movable run and drops it, ~f~ sends a card to a foundation,
  ~a~ auto-plays everything it can, ~u~ undo, ~n~ new, ~?~ help.  On the
  stock pile, ~RET~ deals or recycles.
- Hearts / Spades: arrows choose a card, ~RET~ plays it (in Hearts, ~RET~
  marks a card to pass and ~p~ sends the three), ~n~ new match, ~?~ help.
- Crazy Eights: arrows choose, ~RET~ plays, ~d~ draws, ~x~ passes, ~n~
  new deal, ~?~ help.

On a graphical display, ~v~ toggles the full-window SVG table and
~+~ / ~-~ / ~0~ (Emacs ~text-scale-adjust~) resize the cards.

* Customization
~M-x customize-group RET cg-svg~ and ~RET card-games~:
- ~cg-svg-theme-colors~ -- derive the highlight ring and card backs
  from your theme (on by default).
- ~cg-bid-felt-color~ -- the 500 table felt.
- ~cg-svg-card-width~, ~cg-svg-card-height~, ~cg-svg-card-shadow~,
  ~cg-svg-font-family~ -- card appearance.
- ~cg-svg-card-back~ -- card-back pattern: dots, rings, or solid.
- ~cg-symbols~ -- the Unicode suit glyphs (and the joker) drawn on cards.
- ~cg-svg-four-color~ -- draw a four-colour deck (clubs green, diamonds
  blue-purple).
- ~cg-keys~ -- ~emacs~ (default) or ~classic~ (adds vi-style ~hjkl~ and
  ~SPC~).
- ~cg-bid-animate~, ~cg-bid-ai-delay~, ~cg-bid-trick-pause~ -- pace the
  500 AI so play is watchable and completed tricks linger.
- ~M-x card-games-set-theme~ -- apply a preset (classic, dark, contrast).

* Development
#+begin_src
make compile     # byte-compile (should be warning-free)
make test        # run the ERT suite
make checkdoc    # documentation lint
make release     # clean + test + package + source tarball
#+end_src

* License
GPL-3.0-or-later.  See the file headers; add a COPYING file with the
full GPLv3 text for distribution.