README.md

   1 # solVItaire
   2
   3 Play klondike and spider solitaire in your unicode terminal.
   4
   5 Supports `vi` style keybindings (hjkl), cursor keys and the mouse. Press `J` to
   6 'join' a well-suited pile to the cursor. `Space` locks in a selection, and
   7 `Return` pulls cards from the stack in spider solitaire. Piles can also be
   8 *directly addressed* by the number below them (or 8, 9, 0 for stack, waste and
   9 foundation in klondike).
  10 See `$PROGNAME -h` for details.
  11
  12 Keybindings are documented at the project homepage and in `./$PROGNAME -h`.
  13
  14 ## Details
  15
  16 For details and screenshots see the project homepage at
  17 **https://gir.st/sol.htm**
  18
  19 ## License
  20
  21 You can use, study, share and improve this software under the terms of the GNU
  22 General Public License, version 3. Copyright 2019 Tobias Girstmair. For
  23 licensing details, see `LICENSE`.
  24
  25 <!--
  26 ## TODO
  27
  28 ### P1
  29  * none! \o/
  30 ### P2
  31  * TODO: suggest moves (`h` => hint)
  32  * TODO: cleanup: in `x2y()` functions there is a lot of replication and noise
  33          when calculating legal moves, top cards, etc.
  34 ### P3
  35  * TODO: differential drawing mode (at least for highlighting cards)
  36  * TODO: `.` command (repeat last action)
  37 ### P4
  38  * TODO: mouse mode improvements:
  39           - spider: detect how many cards to move to empty pile
  40             (must find exact position despite `extreme_overlap`)
  41  * TODO: scores, variants: draw 3, max. n overturns
  42  * TODO: vt220 mode (problems: charset, slow baudrate and no differential drawing mode)
  43  * TODO: ed(1) mode (solEDaire): playable on a line printer; ascii/ibm only?
  44
  45 ### DONE
  46  * DONE: use `#ifdef`s to differentiate games (sol, spider, ed-sol, ed-spider)
  47  * DONE: keyboard alias: twice same key == waste/pile -> foundation
  48  * DONE: spider keyboard: `<from><to>` stacks; 1-9,0=tableu, return=draw
  49  * DONE: spider: easy/medium difficulty: only deal 1/2 suits instead of 4 -> deal()
  50  * DONE: patience: allow taking from 0(foundation)
  51  * DONE: highlight `from` pile, so users can see at what input stage they are
  52  * DONE: make piles 0-indexed in klondike as well
  53  * DONE: duplicate card ♠A found in tableu: added check at start to monitor this
  54          Cannot reproduce, removed check
  55  * DONE: bugs in spider's t2t()
  56          * once segfaulted on large column
  57          * sometimes doesn't work (ERR when it should be OK)
  58          Cannot reproduce
  59  * DONE: some input functions are in `x2y()` - - move them to `get_cmd()` (req.
  60          for mouse, hjkl modes)
  61  * DONE: sigint, sigcont handler! atexit() to avoid inconsistent term state
  62  * DONE: hjkl keyboard mode
  63  * DONE: more vim mode keys (first/last tableu)
  64  * DONE: online (key-)help `?`, `-h`, `-v` (NOTE: implemented -h, rest deemed
  65          not usedul)
  66  * DONE: extreme overlapping: if we are printing a sequence or multiple face down
  67          cards, only print `.overlap` lines of the ends, and `1` line for the
  68          middle cards
  69  * DONE: in direct addressing 'up to' dialog: make return/space select the lowest/highest option
  70  * DONE: undo:
  71          - insert append_undo() in x2y() functions
  72          - to encode stack position we need to overload `f.u.n` as index.
  73            (similar for foundation: overload `f.u.n` as foundation id)
  74          - w2f(): have to encode both stock index and foundation id
  75                   don't want to add a struct field for this one case;
  76                   for the time being (i.e. forever) I'm ORing waste index and
  77                   (foundation id<<16). ugly but works :/
  78          - turning over cards: this needs to be encoded, because the card might
  79            be consecutive and there's no way to tell what its previous state was.
  80             * indicate that a card was turned (can be at most 1) by negating u.n
  81               pros: no wasted space (it's just a boolean value), negation pattern
  82                     already used for closed cards
  83               cons: dirty C hack, less obvious than in other places, no need to
  84                     conserve memory this tightly
  85  * DONE: screen size > stack height => rendering issues!
  86          as good as it's going to get, since we can't just not draw cards at all
  87  * DONE: 'join to here' command (should take longest chain available)
  88  * DONE: expose deal() seed for restarting the game
  89  * DONE: make portable (clang on FreeBSD)
  90          makefile's `$<` refuses to work if prequisite name != target name
  91          Fix:
  92              ln -s sol.c. spider.c
  93              sed -i 's/^spider: sol.c/spider: spider.c/' Makefile
  94  * DONE: escape sequences (for real cursor keys)
  95  * DONE: inverted moves (if A->B doesn't work, try B->A)
  96  * DONE:  - allow dragging the mouse
  97 -->
  98
  99 ## Notes
 100
 101  - terminology:
 102 ```
 103     {stock}[waste]    [4*foundation]
 104
 105     []   {}   {}   {}   {}   {}   {}
 106          []  (tableu piles)  {}   {}
 107               []   {}   {}   {}   {}
 108                    []   {}   {}   {}
 109                         []   {}   {}
 110                              []   {}
 111                                   []
 112 ```
 113  - data structures:
 114     - enum for each card (e.g. `SPADES_ACE`, `HEARTS_10`)
 115     - each pile is an array holding (13 open cards + up to 6 closed)
 116       [0] is the "northmost"/bottom-most card; unoccupied are NULL/NO_CARD
 117     - a single card is represented in the 'cards' enum; if it is closed, it is negated.
 118     - the foundation are 4 arrays of size 13
 119     - the stock pile is an array holding n cards and an index to the one to display
 120       when removing, decrement stack size and move all cards above index 1 over
 121     - previous states array: where to move which cards to get back to the state before
 122     - undo:
 123       double-linked list (follow `.prev` to undo, `.next` to redo)
 124       "N cards were moved from X to Y" (do Y->X to undo)
 125       allows jumping forwards in time as well (by repeating X->Y)
 126       warn: when appending state, must check if `.next` was non-NULL and free rest of chain if so.
 127  - multiple card sizes: schemes.h will store cards like below. if we want to draw a card
 128    that has one or more other cards below it, we only draw the first `.overlap` lines,
 129    otherwise if it is the last one, we draw the whole one.
 130    this will give a look like in `~/solitaire-tests`
 131 ```
 132     .grid=7, /*vertical alignment*/
 133     .overlap=2,
 134     .cards = [
 135        ["╭───╮",
 136         "│♠ X│",
 137         "│ ♠ │",
 138         "╰───╯",
 139           NULL],
 140     ]
 141     /*or:*/
 142     .grid=2,
 143     .overlap=1,
 144     .cards = [
 145       [ "🃖 ", NULL ],
 146     ]
 147 ```
 148 "open": face up card
 149 "closed": face down card