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.  Take a
  buried discard card with ~T~: you take it and every card above it, and
  meld the chosen card at once.
- ~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.  Each round opens with a
  rising go-down minimum (50, 90, 120, 150); red threes are bonus cards;
  and you can pick up the discard pile (~p~) by melding its top card with
  two matching naturals.

** Matching
- ~cg-go-fish~ -- Go Fish.  Ask another player for a rank you hold;
  collect all four to lay down a book, and make the most books.
- ~cg-old-maid~ -- Old Maid.  One Queen is set aside; discard pairs and
  draw blind from your neighbour, and do not be left with the odd Queen.

** Pegging
- ~cg-cribbage~ -- Cribbage.  Lay two cards to the crib, cut a starter,
  peg toward 31, then count fifteens, pairs, runs, flushes, and his nobs.
  Two-handed to 121.

** Capturing
- ~cg-scopa~ -- Scopa.  A 40-card deck; capture table cards by value and
  sweep the board for a scopa.  Score cards, coins, the sette bello, and
  primiera to 11.
- ~cg-casino~ -- Casino.  The full deck; capture by pairs and sums and
  score cards, spades, the casinos, and aces to 21.

** More trick-taking
- ~cg-euchre~ -- Euchre.  A 24-card deck with the two bowers; order up or
  call trump and take three of five tricks.  Partnership to 10.
- ~cg-pitch~ -- Auction Pitch.  Bid for the pitch; your first lead sets
  trump.  Score High, Low, Jack, and Game; first to 7.
- ~cg-briscola~ -- Briscola.  A fixed trump turned from the deal and no
  obligation to follow suit; capture the Aces and Threes.  Partnership to
  61 of the 120 points.

** Climbing patience
- ~cg-spite~ -- Spite & Malice.  Race the computer to empty your goal
  pile onto shared centre piles that build Ace to Queen; Kings are wild.

** Bridge
- ~cg-bridge~ -- Contract Bridge.  A full auction (bids, pass, double,
  redouble), play with the dummy exposed, and classic rubber scoring with
  vulnerability.  You are South; when you declare you play the dummy too.
  The bidding AI is a small natural system, sensible but no expert.

* TODO
- [X] make the suit symbols customizable (~cg-symbols~) and obey them
- [ ] a Texinfo manual
- [ ] finish ~checkdoc~ docstrings across the per-game files
  (the shared engine files are clean; ~make compile~ is warning-free)
- [ ] renderer "skins": let games subclass the display components (text,
  SVG, full-window SVG)
- [X] 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.90.tar
#+end_src
Then in Emacs: ~M-x package-install-file RET card-games-1.0.90.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.  A
*Card size* slider (and the ~+~ / ~-~ / ~0~ keys) resizes the cards, and
in 500 the ~? Help / Rules~ button explains play.  Every game accepts the
mouse: click cards, board slots, buttons, and the slider.

* Testing
This is a 1.0.90 pre-test snapshot.  To try it:
1. ~make compile && make test~ -- should be warning-free and all green.
2. ~M-x card-game~ opens the menu, or jump straight in, e.g.
   ~M-x cg-klondike~, ~M-x cg-bid~ (500), ~M-x cg-gin~, ~M-x cg-handfoot~.
3. On a graphical display, press ~v~ in 500 for the full-window SVG
   table and play entirely with the mouse: click a bid, click five kitty
   cards and the *Discard* button, click cards to play, move the *Card
   size* slider, and open ~? Help / Rules~.

Feedback most wanted: anything a mouse-only player who is new to Emacs
finds confusing or unreachable, rules bugs, and rendering glitches.

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