mcfreecell/README.md

mcfreecell

mcfreecell is a terminal-native FreeCell game with a systems-theme twist.

It has two flavors:

• a modern curses build with Linux-themed suits and richer terminal rendering
• a legacy branch aimed at very old Python and curses environments, including Python 1.5.2-era machines

The project started as a novelty FreeCell prototype and grew into a playable, keyboard-driven curses card game with legal multi-card moves, visual stack selection, and lightweight move hints.

Features

• FreeCell rules with 8 tableau columns, 4 free cells, and 4 foundations
• legal multi-card tableau moves with proper FreeCell move-capacity limits
• keyboard-driven play in a curses interface
• visual stack selection mode
• lightweight ? hint system for suggesting a good next move
• responsive layout for wider terminals
• legacy branch compatible with old machines and older Python/curses behavior

Controls

• Arrow keys / h j k l - move cursor
• v - enter or exit tableau selection mode
• y - pick up selected card or stack
• p - drop held card or stack
• Enter / Space - alternate pick up / drop
• u - undo the last completed move
• ? - show a suggested move
• f - quick move selected card to a free cell
• d - quick move selected card to foundation
• Esc - cancel selection or restore held cards
• q - quit

Branches

Main branch

The main branch targets modern Python 3 and modern terminals.

This version includes:

• Linux distro themed suits
• modern curses layout and highlighting
• Nerd Font-oriented suit glyphs
• richer visual presentation

Current main-branch suits:

• Debian
• Gentoo
• Arch
• Slackware

These are split into two alternating-color groups for FreeCell rules:

• red group: Debian, Gentoo
• black group: Arch, Slackware

The main branch uses special glyphs for suit rendering. If your terminal or font does not display them well, Nerd Fonts can be downloaded for free at https://www.nerdfonts.com/font-downloads.

leg-py1.5.2 branch

The leg-py1.5.2 branch is a backport for very old systems.

This version is written in a Python-1.5.2-friendly style and avoids relying on modern Python features or modern terminal niceties.

This branch includes:

• ASCII-only suit tags
• compatibility fallbacks for weak or incomplete curses implementations
• visible ASCII cursor and hint markers for monochrome terminals

Legacy-branch suits:

• Debian (Deb)
• Red Hat (RHt)
• Solaris (Sol)
• HP-UX (HPx)

These are split into the two FreeCell color groups as:

• red group: Debian, Red Hat
• black-equivalent group: Solaris, HP-UX

On legacy terminals, the non-red group may render as blue, cyan, or plain monochrome depending on curses support.

Running

Modern branch

Run with Python 3:

python3 linux-freecell.py

Legacy branch

On the legacy branch, run with whatever Python interpreter is available on the target machine:

python linux-freecell.py

For very old systems, terminal and curses support may vary. The legacy branch tries to fall back gracefully when color, standout attributes, or newer curses APIs are missing.

Suit Theme Notes

mcfreecell is not trying to be a generic casino card game. The suit sets are themed around operating systems and Unix history.

The modern branch leans into playful terminal-native Linux theming.

The legacy branch uses a more period-appropriate late-1990s / early-2000s mix of Linux and proprietary Unix systems to better fit older hardware and software environments.

License

This project is released under the GNU General Public License, version 2 only.

See LICENSE for the full license text.

Status

This is a small personal curses game project, but it is playable and actively being shaped into both:

• a fun modern terminal FreeCell
• a practical legacy-machine FreeCell

Possible Future Work

• packaged releases for modern and legacy branches