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