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