#+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
- *500 (Bid)* -- the four-handed partnership trick-taking game, against
  three computer opponents (~M-x cg-bid~).
- *Gaps / Hell's Half-Acre* -- solitaire; sort each row into one suit
  running 2..K (~M-x cg-gaps~).

To open the game menu type ~M-x card-game~, or start a game directly
with its command:
- ~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-bid~ -- 500 (Bid).  Win the auction, name the trump suit, then take
  tricks with your partner to reach 500 points before the opposing pair.

* 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.50.tar
#+end_src
Then in Emacs: ~M-x package-install-file RET card-games-1.0.50.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.

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.