The goal of the game is to move all the cards from the bottom part of the screen (eight columns) to the two top right and two top left foundation decks.

1. Installation

Prerequisits

In order to compile xfreecell you need:

  • the gnu C++ compiler g++,

  • gnu make,

  • the X11 development package libx11-dev (or devel),

  • the XPM development package libxpm-dev (or devel),

  • the X11 extensions development package libxext-dev (or devel) for the round corners of cards and for the cursor shape indicating valid destinations of cards. If this package is not available you need to remove the -DSHAPE compilation option from the makefile, and the -r option becomes not supported.

Optionnally you need the tool asciidoc to generate the html documentation.

Documentation

Xfreecell comes with a man page xfreecell.6 and this asciidoc document Xfreecell.txt. The Xfreecell.html document is automatically generated together with the compilation if asciidoc is installed.

Compilation

In xfrecell directory launch: 

make

This has the effect of:

  • in ms-compatible directory compile convert.c and launch convert that generates MSNumbers.h from the binary database MSNumbers of Microsoft seed numbers,

  • compile cpp sources in directory widget and make an archive libwidget.a,

  • compile cpp sources in current xfreecell directory and link xfreecell,

  • generate the html documentation if possible (if asciidoc is installed).

Installation

In xfrecell directory launch: 

make install
Note
 You may need to be root for this (or use sudo).

This installs xfreecell binary in DESTDIR/bin, xfreecell man page in DESTDIR/man/man6 and Xfreecell.html (if any) in DESTDIR/share/xfreecell.

Default DESTDIR is /usr/local but you can change it by launching:

make install DESTDIR=<your_dest_dir>
Clean-up

You can clean the result of compilation and generated documentation with: 

make clean

2. Options

The environment variable HOME is used to define the directory ${HOME}/.xfreecell where are saved the current configuration (options), scores and saved game. Default directory is "./.xfreecell".

The following options can be provided in the command line:

-a | --animation for animation of card movements (default is yes)
-s | --speed to set time in ms for each simple move of a card (default is 100)
-m | --ms-seed for comptibility with microsoft seed generator (default is no)
-q | --query-window for a popup window for single or multiple cards move (default is no).
     See the section on shortcuts for the discution on single/multiple cards movements.
-p | --auto-play for automatic move of cards to the foundations (default is yes)
-r | --round-card for sharp corner of cards, if xfreecell is compiled with -DSHAPE, (default is yes)
-l | --load to load at start-up a game previouly saved (default is no)
-d | --double-click to set the max delay in ms for a double click, from 100 to 900 (default is 500)

Each boolean option can be followed by "Y", "YES", "N" or "NO" in any casing, otherwise "yes" is assumed.

Example:
xfreecell -a no -s 100 -r N -m Y -q yes -p no -l

These preferences (except -r | --round-card and -l | --load) can also be set in the Pref menu.

These preferences (except -l | --load), either set by command line option or by the Pref menu, are saved in the persistent file ${HOME}/.xfreecell/prefs.

For each option, xfreecell defines the value according to the following criteria:

  1. The one modified in the Pref menu,

  2. Otherwise, the option provided in the command line, if any,

  3. Otherwise, the value retrieved from the previous execution of xfreecell, if any,

  4. Otherwise the default value defined above.

3. Playing

3.1. Starting a game

First, you must start a new game by clicking on menu New.

At any time you can:

  • click on the New button to start a random new game (not played yet),

  • click on the Replay button to restart the current game,

  • click on the Seed button and enter a game number to start a given game (you can use the mouse button to paste a X11 selection of the seed number),

  • click on the Lost button start a random game among thoses that have already been lost.

Note
 In all these cases the current game in progress, if any, is considered as lost and counted as such. Same if you close the main window (through the window manager).

3.2. The three areas and what can go where

Playing area

This area is the whole bottom (all but the first row) of the screen. There are 4 columns of 7 cards and 4 columns of 6 cards.

At start-up all the 52 cards are randomly placed in the playing area.

Stacking rule: You can append a card at the bottom of a column providing that the new card is one level below the bottom card (e.g. Jack on Queen) and that the new card is of different color (in term of black and red) from the previous.

In an empty column you can put any card you want then stack several cards as long as they respect the above stacking rule of decrescent levels and alternative colors.

Foundations

Theses are the 4 decks, two at the top left (Hearts and Spades) and two at the top right (Diamonds and Clubs) of the top row.

At start-up they show their target color.

Here you must place the cards, one color per deck, in the order Ace, two, three…, Queen, Kind.

The goal of the game is to move all the cards in the foundation decks.

Free cells

These are the four places in the midlle of the top row.

They are highlighed with a light green border.

Here you can temporary put one card at a time in each free cell.

Areas

3.3. Moving the cards

The cards move one by one, from any area to any area, except that they cannot move back from the foundation (but you can undo any move).

3.3.1. Basics

Select the card to move by left clicking on it. It becomes selected (its background becomes grey). You can toggle the selection by left clicking again on the card.

Once a card is selected, select the destination (foundation, free cell, empty column or a card in the playing area) by left clicking on the location. Valid destinations are indicated by a vertical arrow ⇑ when the mouse cursor moves on it (if xfreecell has been compiled with option -DSHAPE, see section on prerequisits).

3.3.2. Auto-play

The cards are moved automatically to the foundation if all the following conditions are fulfilled:

  • the auto-play mode is activated,

  • the movement is valid,

  • this does not generate more than one level of difference between the colors in the foundations. For example, if the smalest red (Heards or Diamonds) on top of its foundation is the 7, then not more than the 8 of blacks (Clubs and Spades) will be automatically moved in the foundations.
    You can still manually move cards to the foundation in this case.

Note
 At the beginning of the game, or just after activating the auto-play mode, it is necessary to do a first movement in order to trigger the automatic move of cards to the foundations.

3.3.3. Shortcuts

You can right click on a non selected card to move it to its foundation (if possible), otherwise move it to a free cell (if any).

You can double left click, or middle click, on a non selected card to move it in a free cell if any is available.

Once a card of the playing area is selected, you can:

  • on a foundation or empty free cell, left or right click to move the card,

  • on another non-empty column, left or right click to move as many cards as possible (see multiple move hereafter),

  • on an empty column,

    • if the query-window mode is active, left or right click to open a pop-up window that lets you choose to move a single or multiple cards,

    • otherwise, left click to move a single card or right click to move multiple cards.

3.3.4. Practically

Activate the auto-play mode and deactivate the query-window mode.
Right click on a card to move it to 'top' (foundation or free cell),
or select it (left click) and right click on the destination.

3.3.5. Multiple move

The multiple move allows moving several cards from a column to another one (empty column or top card of a column). In this operation, the cards move as if you moved them one by one, so the amount of cards that are moved depends on:

  • how many cards are following the stacking rule,

  • how many empty columns and free cells can be used for temporary storage.

Note
 The automatic move fills the free cells and then the free columns with one card each, then stacks these cards on the last column fed, then does it again until all the columns are full, and then fills each free cell. This strategy is not optimal.
For example, with 2 free columns and one free cell, the automatic move will put 3 cards in the first column, then 2 cards in the second column, then 1 card in the free cell, allowing to move 7 cards altogether.
A better strategy would be to put 2 cards in the first column, 2 cards in the second column, move the 2 first cards in the second column, move 2 cards in the first column, then 1 card in the free cell, allowing to move 8 cards altogether.

3.3.6. Undo and redo

With the Undo and Redo buttons, you can undo as many movements as you want (up to the beginning of the game), and redo any movement undone.

Moving a card clears the list of movements that can be re-done.

4. Other buttons

4.1. Score

You can see you score by clicking on the Score button. This shows the statistics and scores since the game installation:

  • Wins: the total number of games won

  • Defeats: the total number of games lost (see note on starting a game

  • Wins percentage: percentage of games won among all played

  • Defeates percentage: percentage of games lost among all played

  • Continuous wins: number of continuous (successive) games won

  • Continuous defeats: number of continuous (successive) games lost

  • Undos: number of undo performed and not re-done.

  • Total score. This score is:

    • incremented by 10 + NbContinuousWins each time a game is won,

    • decremented by 10 + NbContinuousLost each time a game is lost,

    • decremented by 1 for each undo that is not re-done.

These statistics are saved from one session to another in the file ${HOME}/.xfreecell/score.

4.2. Save

This button saves the current game (in a file named ${HOME}/.xfreecell/saved). This game can be launched with the argument -l or --load of xfreecell. The stacks of movements (for undo and redo) are not saved.
Any previously saved game is overwritten.

4.3. Pref

This button allows modifying your preferences, see section Options.

5. User profile

The directory ${HOME}/.xfreecell is used to save:

  • Your preferences, see sections Options and Pref

  • The game numbers lost (Unix seed and microsoft seed), in order for the Lost button to start a game already lost

  • The game numbers won (Unix seed and microsoft seed), in order for the New button to start a game not yet played (neither won nor lost)

  • Your score and associated statistics, see section Score

  • At most one saved game.