UPDATE TO GITHUB.COM USERS

This repository is no longer being updated on github.com, and will
soon be closed. Please visit the project home page to find a link to
its latest home:

  <http://www.muppetlabs.com/~breadbox/software/brainjam.html>




  * ABOUT THIS PROGRAM

Brain Jam is a solitaire card game. It is similar to soltaire games
like Freecell in that the entire deck is dealt out face up at the
start, so the player has full information. However, unlike many
solitaire programs, Brain Jam comes with a large but finite number of
pre-shuffled decks, all of which are guaranteed to be solvable. Thus
there is no luck factor in playing Brain Jam.

When you have solved a given configuration, you can also go back and
try to find a new answer with fewer moves.


  * NOTE FOR WINDOWS USERS

The Brain Jam installer should set up everything for you. If you
didn't create a menu item or shortcut (or if you installed Brain Jam
manually via a zip file), then you can run brainjam.exe directly
from this folder to play the game.


  * HOW TO PLAY

Within the program, you can use the question-mark button (or on the
keybaord, use "?" or "F1") at any time to see the rules of the game,
the interface commands, etc. The rules of the game are very simple.


  * USER DATA

Brain Jam comes with no external data files, but it will create its
own files when it runs, in order to store your progress. Typically,
these files will be located in the following folder:

  Linux:   $HOME/.config/brainjam/
  Mac:     $HOME/Library/Application Support/brainjam/
  Windows: $HOME\Application Data\brainjam\

The file "brainjam.ini" in this folder holds your settings. You should
not normally need to access this file directly. However, if you choose
you can edit this file to change the font used by the program. To do
this, add a line that reads (e.g.):

  font=times

to use the installed Times font. Alternately, you can provide a
explicit path to a font file.

The folder can also contains a file named "brainjam.sol", which holds
your best answer for each game. If you played Brain Jam using the
original 16-bit Windows program, you can copy your old "brainjam.sol"
file into this folder, and this program will then have a record of all
of your previosly solved games.


  * BUILDING FROM SOURCE

If you are building from source, you will need to have installed the
following libraries, including their header files:

  ncursesw
  fontconfig
  SDL2
  SDL2_ttf
  libpng

For users on a debian-based distribution, the following command should
be sufficient to ensure all these dependencies are satisfied:

  sudo apt install libsdl2-dev libsdl2-ttf-dev libpng-dev libncursesw5-dev libfontconfig-dev

Note that you can use the ./configure script to remove some of these
dependencies in exchange for decreased functionality. The option
"--without-ncurses" will drop the ncurses dependency, at the cost of
removing the text-terminal interface. Similarly, the option
"--without-sdl" will remove the dependency on SDL2, SDL2_ttf, and
libpng, at the cost of only providing a text-terminal interface.
Finally, the option "--without-fontconfig" will remove the dependency
on libfontconfig, at the cost of requiring you to explicitly set the
path to the program's font in "brainjam.ini".

Running "make install" will install the binary and a man page.


  * BUILDING VIA HOMEBREW

If you are a homebrew user, you should be able to automatically build
Brain Jam with the command:

  brew install http://www.muppetlabs.com/~breadbox/pub/software/brainjam/brainjam.rb


  * WEBSITES

The home page for this program is at:

  http://www.muppetlabs.com/~breadbox/software/brainjam.html

From here you can download the latest source tree, as well as
pre-built Windows binaries.

The website for the original Brain Jam program is at:

  http://brainjam.ca/brainjam/

From there you can obtain the original 16-bit Windows binary, as well
as play a version that runs in the browser.


  * LICENSE

Copyright (C) 2017-2021 Brian Raiter.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version. This program is distributed in the
hope that it will be useful, but WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. For more details see the GNU General Public License, included
in the source distribution in the file COPYING, or you can view it
online at <http://gnu.org/licenses/gpl.html>.


  * CREDITS

This program is written by Brian Raiter.

This program is a re-implementation of a Windows program of the same
name, which was written by Peter Liepa.

The rules of Brain Jam are based on "Baker's Game", as described by
Martin Gardner in the June 1968 issue of Scientific American.

The deck configurations were created by Peter Liepa with assistance
from Bert van Oortmarssen, and are used here with their permission.

The graphics that appear in Brain Jam are taken from public domain
sources, and/or have been explicitly placed in the public domain by
their creators. The program's icon was drawn by Kay Lousberg.


  * CONTACT

Bug reports and other feedback are appreciated, and can be sent to the
author at <breadbox@muppetlabs.com>.