Skip to content

Project 2: Griddle Game

Griddle game screenshot image

Introduction

In this project, you will implement a game similar to Waffle (wafflegame.net), which we will call Griddle. The game presents a 5×5 grid of letters, some of which are fixed and others that can be swapped. The goal is to match the grid to a hidden solution within 15 swaps. Each letter is color-coded to indicate its correctness:

  • Green: Correct letter in the correct position.
  • Yellow: Correct letter in the wrong position (same row or column).
  • Red: Incorrect letter.
  • White: Blank cell (underscore _).

You will use two modules (file_utils.py and word_utils.py) to build the file I/O, game logic, and utilities.

Provided Files

Download and extract PA2.zip into your CS149 folder.

These files require you to install the following two packages:

pip install colorama
pip install pyside6

Grid Format

The game grid is read from a CSV (Comma Separated Values) file. Here is what one of the starter files looks like:

starter.txt
[M],_E_,(V),(A),[E]
_R_,___,(R),___,(S)
(E),_P_,[U],(T),_U_
_S_,___,_A_,___,(A)
[L],[A],(E),_S_,[L]
The corresponding solution file looks like:
solution.txt
[M],[A],[U],[V],[E]
[E],___,[S],___,[A]
[T],[R],[U],[S],[S]
[A],___,[R],___,[E]
[L],[A],[P],[E],[L]

Each cell in the grid is represented with the following symbols:

  • [A] → brackets mean "Green"
  • (B) → parentheses mean "Yellow"
  • _C_ → underscores mean "Red"
  • D or  D  → Invalid (will be marked as *)

Each cell is parsed into a list of two strings: [letter, color]. For example, the text _C_ in the file becomes the list ["C", "RED"] in Python.

Game Rules

The grid must be a "flat" (one-dimensional) list of 25 cells that looks like this: 

[  0 ] [  1 ] [  2 ] [  3 ] [  4 ]

[  5 ] [  6 ] [  7 ] [  8 ] [  9 ]

[ 10 ] [ 11 ] [ 12 ] [ 13 ] [ 14 ]

[ 15 ] [ 16 ] [ 17 ] [ 18 ] [ 19 ]

[ 20 ] [ 21 ] [ 22 ] [ 23 ] [ 24 ]

Note: Cells 6, 8, 16, and 18 are 'hole cells' or blank ones with no letters used here.

When playing the game and swapping letters, cell indexes will be represented using letters:

[ a ] [ b ] [ c ] [ d ] [ e ]

[ f ] [ g ] [ h ] [ i ] [ j ]

[ k ] [ l ] [ m ] [ n ] [ o ]

[ p ] [ q ] [ r ] [ s ] [ t ]

[ u ] [ v ] [ w ] [ x ] [ y ]
  • Only letters a–y and _ are allowed.
  • Valid swaps are between letter indices a to y (excluding the holes at g, i, q, s).
  • A maximum number of swaps is allowed (15 before the game ends).
  • After each swap, the grid is re-evaluated and re-colored.
  • The game ends when the grid matches the solution or the swap limit is reached.

Required Functions

You must implement or use the following:

Part A: file_utils.py

  • parse_cell(line) – Used by read_file().

  • read_file(filename) – Load a grid from a CSV file.

  • write_log(swap) – Log a swap to a file.

  • print_log() – Display all logged swaps.

  • valid_border(raw) – Used by check_grid().

  • check_grid(grid) – Validate grid structure.

Part B: word_utils.py

  • is_solved(current, solution) – Check if the puzzle is solved.

  • check_swap(a, b) – Validate swap indices.

  • cell_to_str(cell) – Used by print_grid().

  • print_grid(grid) – Display the grid with colors and borders.

  • update_grid(current, solution) – Recolor the grid based on correctness.

  • swap_cells(a, b, grid) – Swap two cells in the grid.

Tip

Helper Functions: parse_cell(), valid_border(), and cell_to_str() are "used by" other functions to break down larger problems into smaller problems. During Part B, you will need to define additional helper functions to distribute the work of update_grid(), which is a very complex function.

Unit Testing

Sample tests (test_file_utils.py and test_word_utils.py) are included in the provided files. Only 1–2 examples are provided for each function. We strongly recommend you write additional unit tests. However, you don't need (and wont be able) to submit your test code.

Submission

Submit the following files:

  • file_utils.py (Part A)
  • word_utils.py (Part B)

Ensure that your code:

  • Passes all your tests
  • Follows style guidelines
  • Includes docstrings and comments
  • Passes a ruff check

Part A: file_utils.py (40 pts)

Read the provided docstrings in file_utils.py for details in the implementation of the functions.

We are providing 2 CSV files a starting grid and a solution grid for a daily puzzle of Waffle:

You should use these to test your file_utils.py and also when completed your word_utils.py to run the griddle game in either text or gui mode.

You will be limited to 15 submissions for Part A code.

Part B: word_utils.py (60 pts)

Read the provided docstrings in word_utils.py for details in the implementation of the functions.

You should make use of the colorama library for creating the foreground colors of Green, Yellow, or Red. Make sure to do an import at the top of your word_utils.py file. Something like this: 

from colorama import Fore, Style, init

The only color setting from the colorama module needed for this function is the foreground color. To color a string "ABC" so that A is green, B is red, and C is yellow, you create the string: 

colorstring = Fore.GREEN + "A" + Fore.RED + "B" + Fore.YELLOW + "C"

To test part B you should again create some unit tests of your own locally in a file called test_word_utils.py. We are also providing two game play files:

  • griddle.py a text based implementation of the game where you enter two letters to swap positions a–y, excluding g, i, q, and s.
  • griddle_gui.py a graphic based implementation of the game.

These will require the solution.txt and starter.txt from Part A to run properly.

Before uploading your submission to Gradescope, be sure to complete the following steps:

  • Test your solution carefully.
  • Run ruff locally and resolve all warnings.
  • Review and update docstrings and comments as needed.
  • Play a round of the game using griddle.py or griddle_gui.py

You will be limited to 15 submissions for Part B code.

Your code will be run against many tests written by the faculty. If any of these tests fail, we recommend you add a similar test to your own code. Make sure your test fails in the same way that the Gradescope test fails. Then use the debugger to find and fix the problem until your own test passes. Doing this will help ensure your solution will also pass on Gradescope.

Reflection

Submit the graded survey on Canvas after completing the assignment.

Acknowledgment

The game Waffle was created by James Robinson.