Find the Gopher

A Minesweeper-inspired puzzle game built with Java Swing, where players navigate a golf course grid to locate hidden gophers before they can tee off.

Overview

Find the Gopher reimagines the classic Minesweeper formula with a golf course theme. Players are presented with an 8×8 grid of hidden tiles, each concealing either a gopher or a numeric hint indicating how many gophers occupy adjacent cells. The objective is to identify and flag all gopher locations without accidentally digging one up. Successfully marking every gopher clears the course for a round of golf — but reveal a gopher, and you fall into the hole.

Key Features

• Interactive 8×8 Grid Board — A dynamically generated game board with randomized gopher placement on every new game.
• Three-State Tile Cycling — Each tile cycles through hidden, flagged (question mark), and reveal-ready states, giving players full control over their decisions.
• Adjacency Number Hints — Tiles adjacent to gophers display numeric indicators (1–8) calculated across all eight neighboring cells, including diagonals.
• Recursive Auto-Reveal — Revealing an empty tile (zero adjacent gophers) automatically cascades and uncovers all connected safe tiles, accelerating gameplay.
• Confirmation Prompt on Reveal — A dialog box asks players to confirm before committing to a tile reveal, preventing accidental losses.
• Win/Loss Validation — A submit button evaluates the board state, checking that all gophers are correctly flagged and no safe tiles are incorrectly marked.
• Post-Game Board Reveal — After submission or a loss, the full board is uncovered so players can review gopher positions and learn from their strategy.

Tech Stack

Component	Technology
Language	Java
GUI Framework	Java Swing (AWT)
Layout	GridLayout, FlowLayout
Architecture	Event-driven MVC

System Architecture

project3Main (Entry Point)
    └── JFrame
         └── GUISetup (JPanel — View + Controller)
              ├── JButton[8][8] grid — User interaction layer
              ├── TileListener — Event handler for clicks and submission
              └── board (Model)
                   ├── tile[8][8] — Individual cell state management
                   ├── setGophers() — Random gopher placement
                   ├── setNumbers() — Adjacency calculation engine
                   ├── reveal() — Recursive flood-fill for empty regions
                   └── isWon() — Win condition evaluator

Data Flow:

1. project3Main initializes the JFrame window and mounts the GUISetup panel.
2. GUISetup constructs the 8×8 button grid and delegates game logic to the board model.
3. board randomly places 8 gophers, then computes adjacency numbers for all non-gopher tiles (handling corners, edges, and interior cells).
4. Player clicks trigger TileListener, which cycles tile states and, on confirmed reveal, invokes the recursive reveal() method on the model.
5. If the revealed tile is a gopher, the game ends with a full board reveal. If empty (0 neighbors), flood-fill exposes all connected safe tiles.
6. The submit button calls isWon() to verify that all flagged tiles are gophers and no non-gopher tiles are incorrectly flagged.

Setup & Installation

Prerequisites

• Java Development Kit (JDK) 8 or higher
• A terminal or IDE that supports Java compilation

Build & Run

# Clone the repository
git clone https://github.com/samie-mirghani/find-the-gopher.git
cd find-the-gopher

# Compile all source files
javac *.java

# Launch the game
java project3Main

Image Assets

The game expects the following image files in the project root directory:

File	Purpose
back.png	Default hidden tile face
Question_mark.png	Flagged tile indicator
caddyshack-gopher.jpg	Gopher reveal image
num1.jpg – num8.jpg	Adjacency number tile images

Note: Image assets are not included in the repository. You will need to provide your own images matching the filenames above.

How to Play

1. Click a tile once to flag it with a question mark (marking it as a suspected gopher).
2. Click again to enter reveal mode — a confirmation dialog will appear.
3. Confirm the reveal to uncover the tile:
   • If it's a number, it shows how many gophers are in the 8 surrounding cells.
   • If it's empty (0 neighbors), all connected safe tiles auto-reveal.
   • If it's a gopher, you fall in the hole and the game ends.
4. Click "Submit" when you believe all gophers are flagged to check your answer.

Suggested Topics / Tags

java · swing · minesweeper · puzzle-game · desktop-game · gui-application · grid-game

Repository Description

A Minesweeper-style puzzle game built in Java Swing where players locate hidden gophers on a golf course grid using adjacency hints and recursive tile reveals.

License

This project was developed as part of a CPSC 220 course assignment.