doc: generate README.md from README.org (Emacs batch ox-md)
Add build.el + pre-commit hook so README.org stays the source and README.md is regenerated for GitHub/MELPA. Refresh README (screenshots, Crapette, use-package, new customs). Makefile: readme/hooks/info-emacs targets; ship README.md.
This commit is contained in:
parent
556485cb6b
commit
69a4de7538
9 changed files with 541 additions and 19 deletions
306
README.md
Normal file
306
README.md
Normal file
|
|
@ -0,0 +1,306 @@
|
|||
Card games for Emacs: about thirty of them, from Klondike and FreeCell
|
||||
to Hearts, 500, Gin, Cribbage, and two-player Russian Bank against the
|
||||
computer. Every game plays with the keyboard everywhere and with the
|
||||
mouse on a graphical display.
|
||||
|
||||
|
||||
|
||||
On a graphical display the cards are drawn as SVG; in a terminal they
|
||||
fall back to UNICODE glyphs (customize `card-game-symbols`). You can
|
||||
switch how every game is drawn from the menu – `text` (UNICODE),
|
||||
`svg` (drawn cards), or `full` (a full-window SVG table) – and dial the
|
||||
computer opponents between `easy`, `normal`, and `hard`.
|
||||
|
||||
A full Info manual ships with the package: after installing, `C-h i` and
|
||||
choose **Card Games**, or `M-x info RET (card-games) RET`.
|
||||
|
||||
|
||||
# Games
|
||||
|
||||
To open the game menu type `M-x card-game`, or start a game directly
|
||||
with its command. From the menu you can also switch the card treatment
|
||||
(text / SVG / full-window) and the AI difficulty.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
## Two-player patience
|
||||
|
||||
- `cg-russian-bank` / `cg-crapette` – Russian Bank (Crapette). A race
|
||||
against the computer: build the eight shared foundations up by suit,
|
||||
build the shared houses down in alternating colour, and empty your
|
||||
reserve to win. Load your cards onto your opponent's piles when the
|
||||
rank and suit line up, mind the "stop" rule that ends your turn if you
|
||||
skip a foundation play, and sequence house-to-house moves within the
|
||||
free houses (`[` / `]` choose how many cards of a run to drop on an
|
||||
empty house). The opponent plays all three difficulty levels.
|
||||
|
||||
|
||||
# TODO
|
||||
|
||||
- [X] make the suit symbols customizable (`cg-symbols`) and obey them
|
||||
- [X] 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
|
||||
|
||||
make package # builds card-games-1.0.90.tar
|
||||
|
||||
Then in Emacs: `M-x package-install-file RET card-games-1.0.90.tar`.
|
||||
|
||||
|
||||
## With `use-package`
|
||||
|
||||
Once the package is on your `load-path` (installed from the tarball or an
|
||||
ELPA archive), the whole collection loads from the single `card-games`
|
||||
feature:
|
||||
|
||||
(use-package card-games
|
||||
:commands (card-game cg-klondike cg-bid cg-hearts cg-gin cg-crapette))
|
||||
|
||||
Then `M-x card-game` for the menu.
|
||||
|
||||
|
||||
## From a local ELPA archive
|
||||
|
||||
make elpa # builds dist/ (archive-contents + tar)
|
||||
|
||||
(add-to-list 'package-archives '("cg" . "/path/to/dist/"))
|
||||
(package-refresh-contents)
|
||||
(package-install 'card-games)
|
||||
|
||||
|
||||
## Manually
|
||||
|
||||
Put the `cg-*.el` and `card-games.el` files on your `load-path` and
|
||||
`(require 'card-games)`.
|
||||
|
||||
|
||||
# Manual
|
||||
|
||||
A complete Info manual is included. After installing, `C-h i` and pick
|
||||
**Card Games**, or `M-x info RET (card-games) RET`. To build it from a
|
||||
source checkout:
|
||||
|
||||
make info # builds doc/card-games.info with makeinfo
|
||||
|
||||
The manual text is licensed CC-BY-4.0; the code is GPL-3.0-or-later.
|
||||
|
||||
|
||||
# Playing
|
||||
|
||||
Every game works 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-ai-level` – how hard the computer plays: `easy`, `normal`, or
|
||||
`hard` (also on the `M-x card-game` menu, or `M-x
|
||||
card-games-set-ai-level`).
|
||||
- `card-games-treatment` – how the games are drawn: `text`, `svg`, or
|
||||
`full` (also on the menu, or `M-x card-games-set-treatment`).
|
||||
- `cg-svg-theme-colors` – derive the highlight ring and card backs
|
||||
from your theme (on by default).
|
||||
- `cg-svg-highlight-color` – the cursor/selection ring (gold 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` – the card-back design: `dots`, `rings`, `solid`,
|
||||
`lattice`, `waves`, `diamond`, an Emacs-logo back (`emacs`,
|
||||
`emacs-classic`, `gnu`, `splash`), or `random` (the default – picks
|
||||
one for the session; `M-x cg-svg-shuffle-card-back` rolls a new one).
|
||||
- `cg-svg-emacs-logo` – the emblem on the full-window table:
|
||||
`modern` (default), `classic`, `gnu`, `splash`, `drawn`, or `none`.
|
||||
- `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
|
||||
|
||||
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
|
||||
|
||||
|
||||
# License
|
||||
|
||||
GPL-3.0-or-later. See the file headers; add a COPYING file with the
|
||||
full GPLv3 text for distribution.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue