Freecell Game - Verilog Implementation

A hardware implementation of the classic Freecell card game using Verilog HDL.

Overview

This project implements a Freecell solitaire game in Verilog, designed for ECSE 318 Lab 2. The game follows standard Freecell rules where the objective is to move all 52 cards to four home cell stacks (one per suit) in ascending order from Ace to King.

Project Structure

• freecellPlayer.v - Main game module implementing Freecell logic
• tb_freecell.v - Testbench with a complete winning game sequence
• Freecell.mpf - ModelSim project file
• work/ - Compiled simulation library

Module Interface

freecellPlayer Module

module freecellPlayer(clock, source, dest, win);

Inputs:

• clock - Clock signal for synchronous operation
• source[3:0] - Source location encoded as 4-bit value
• dest[3:0] - Destination location encoded as 4-bit value

Outputs:

• win - High when all cards successfully placed in home cells

Location Encoding

Source/Destination Format (4-bit)

• Tableau Columns (0-7): 0xxx where xxx is the column index (0-7)
• Free Cells (0-3): 10xx where xx is the free cell index (0-3)
• Home Cells: 11xx for home cell destinations

Examples

• 4'b0000 - Tableau column 0
• 4'b0101 - Tableau column 5
• 4'b1000 - Free cell 0
• 4'b1111 - Home cell destination

Game Layout

Initial Setup

• 8 Tableau Columns: Cards dealt in 7 cards per column (first 4 columns get 7 cards, last 4 get 6)
• 4 Free Cells: Empty temporary storage for single cards
• 4 Home Cells: Foundation piles (one per suit) built from Ace to King

Card Encoding (6-bit)

Each card is represented by 6 bits:

• Bits [5:4]: Suit
  • 2'b00 - Hearts (H)
  • 2'b01 - Diamonds (D)
  • 2'b10 - Spades (S)
  • 2'b11 - Clubs (C)
• Bits [3:0]: Value
  • 4'b0001 - Ace
  • 4'b0010 - 2
  • ...
  • 4'b1010 - 10
  • 4'b1011 - Jack
  • 4'b1100 - Queen
  • 4'b1101 - King

Game Rules Implementation

Valid Moves

1. Tableau to Tableau: Cards can be placed on a card of opposite color and one rank higher
2. Tableau/Free Cell to Home Cell: Cards must be placed in ascending order by suit (Ace first)
3. Tableau/Free Cell to Free Cell: Only if the free cell is empty
4. Free Cell to Tableau: Same rules as tableau-to-tableau

Win Condition

The game is won when all 52 cards are successfully placed in the four home cell stacks, with each stack containing all 13 cards of one suit in order (Ace through King).

Simulation

Prerequisites

• ModelSim or Questa Sim
• Windows environment (or compatible simulator)

Running the Simulation

1. Open the ModelSim project:

   Open Freecell.mpf in ModelSim
   

2. Compile the design:

   vlog freecellPlayer.v tb_freecell.v

3. Run the simulation:

   vsim tb_freecell
   add wave -r /*
   run -all

Testbench

The testbench (tb_freecell.v) includes:

• Automatic clock generation (10ns period)
• A sequence of 92 moves that solves the dealt hand
• Real-time display of game state after each move
• Monitoring of free cells, home cells, and tableau piles

Expected Output

The simulation displays after each clock cycle:

• Current state of all free cells
• Current state of all home cells
• Current state of all tableau piles
• Card being moved
• Card placement status
• Win status

The game should complete successfully with win = 1 after 92 moves.

Design Features

• Synchronous Operation: All moves occur on the positive clock edge
• Automatic Rule Validation: Invalid moves are ignored
• Win Detection: Automatic detection when all cards are in home cells
• Flexible Initial Setup: Card layout can be modified in the initial block

Implementation Details

Data Structures

• piles[0:7][0:18] - 8 tableau columns, up to 19 cards each
• freecells[0:3] - 4 free cell slots for single cards
• homecells[0:3][0:12] - 4 home cell stacks, 13 cards each

State Variables

• cardFound - Indicates valid card found at source
• cardPlaced - Indicates successful card placement
• gameWon - Internal win condition flag

Course Information

Course: ECSE 318 - Digital Logic Design
Assignment: Lab 2
Institution: Case Western Reserve University

Notes

• The game uses a fixed initial card layout for reproducibility
• All card movements follow standard Freecell rules
• The testbench demonstrates a complete winning strategy
• Empty slots are represented by 6'b000000

Future Enhancements

• Add user input interface for interactive play
• Implement move validation feedback
• Add move history tracking
• Create visual display module for cards
• Support for random initial deals