BreakthroughGame_Project2

A Python implementation of the board game Breakthrough with AI agents (Minimax, Alpha-Beta, Greedy 1-ply, Iterative Deepening / Transposition option) plus a pygame GUI and PDF reports.

Requirements

• Python 3.8+ (or a compatible Python 3.x)
• pygame -reportlab (for PDFs)

Quick Setup (PowerShell, from project root)

1) Create & activate venv

python -m venv .venv & "..venv\Scripts\Activate.ps1"

2) Upgrade packaging tools

python -m pip install --upgrade pip setuptools wheel

3) Install deps

python -m pip install pygame reportlab

(or) if you keep requirements.txt:

python -m pip install -r requirements.txt

If you prefer, you can install the package system-wide (not recommended):

```powershell
python -m pip install pygame

Windows users who have trouble installing wheels can try pipwin:

python -m pip install pipwin
python -m pipwin install pygame

How to Run (from project root)

A) Experiments → CSVs

six matchups → out\match_details.csv and out\summary.csv

python .\experiments\run_six.py

combine → out\combined_details.csv and out\combined_summary.csv

python .\experiments\combined.py

B) GUI (human vs. agent) + logging

plays a GUI match; logs per-move CSVs under .\Bonus\gui_logs\

python .\gui\pygame_app_menu.py

C) Build Reports (PDFs in out) python .\reports\make_report_final.py python .\reports\make_report_final_plus.py

Outputs expected in out\:

final_report.pdf (core)

final_report_plus.pdf (adds GUI aggregates)

summary.csv, match_details.csv, combined_summary.csv, combined_details.csv

Verify Heuristics (H1 & H2)

Offensive H1 (Given): 2 * (30 - opponent_pieces) + random()

Defensive H1 (Given): 2 * (own_pieces) + random()

H2 (custom) functions are in heuristics\evals.py.

Quick type check:

$env:PYTHONPATH = (Get-Location).Path
python -c "import sys,importlib; sys.path.append('.'); import core; h=importlib.import_module('heuristics.evals'); cfg=core.BTConfig(); g=core.Breakthrough(cfg); s=g.initial; print('H1 types:', type(h.offensive_h1(g,s)).__name__, type(h.defensive_h1(g,s)).__name__); print('H2 types:', type(h.offensive_h2(g,s)).__name__, type(h.defensive_h2(g,s)).__name__)"


Expected:
H1 types: float float
H2 types: float float

Folder Structure (key parts)

agents/ — Minimax, Alpha-Beta, Greedy, IterDeep/TT agents

core/ — game rules, state, search plumbing

heuristics/ — evals.py with H1/H2

experiments/ — run_six.py, combined.py

gui/ — pygame_app_menu.py, gui_logger.py (logs → Bonus\gui_logs\*.csv)

reports/ — make_report_final.py, make_report_final_plus.py

out/ — generated CSVs/PDFs

Bonus/ — bonus assets (e.g., gui_logs\)

scripts/ — optional helpers (e.g., run_all_and_build.py if present)

One-shot “do everything” (optional)
# BreakthroughGame_Project2

A Python implementation of the board game Breakthrough with AI agents (Minimax, Alpha-Beta, Greedy 1-ply, Iterative Deepening / Transposition option), a pygame GUI, and PDF reports.

## Requirements

- Python 3.8+ (or a compatible Python 3.x)
- `pygame` (GUI)
- `reportlab` (PDF reports)

Optional/data packages you may already have: `numpy`, `pandas`.

## Quick Setup (PowerShell, run from project root)

1) Create & activate the virtual environment

```powershell
python -m venv .venv
& ".\.venv\Scripts\Activate.ps1"

2. Upgrade packaging tools

python -m pip install --upgrade pip setuptools wheel

3. Install dependencies

python -m pip install pygame reportlab
# Or, if you maintain a requirements.txt:
python -m pip install -r requirements.txt

If you prefer system-wide installation (not recommended):

python -m pip install pygame

Windows users who have trouble installing wheels can try pipwin:

python -m pip install pipwin
python -m pipwin install pygame

How to Run

Run these commands from the project root (where README.md lives).

• A) Experiments → CSVs

# Run the six-matchup experiment; creates `out\match_details.csv` and `out\summary.csv`
python -m experiments.run_six

# Combine generated CSVs into combined summaries
python -m experiments.combined

• B) GUI (human vs. agent) + logging

# Run the GUI app (module form ensures imports resolve correctly)
python -m gui.pygame_app_menu

# Alternatively, run the script directly
python .\gui\pygame_app_menu.py

• C) Build Reports (PDFs in out/)

python .\reports\make_report_final.py
python .\reports\make_report_final_plus.py

Expected outputs in out/:

• final_report.pdf (core)
• final_report_plus.pdf (adds GUI aggregates)
• summary.csv, match_details.csv, combined_summary.csv, combined_details.csv

Verify Heuristics (H1 & H2)

Example quick type check (PowerShell):

$env:PYTHONPATH = (Get-Location).Path
python -c "import sys, importlib; sys.path.append('.'); import core; h = importlib.import_module('heuristics.evals'); cfg = core.BTConfig(); g = core.Breakthrough(cfg); s = g.initial; print('H1 types:', type(h.offensive_h1(g,s)).__name__, type(h.defensive_h1(g,s)).__name__); print('H2 types:', type(h.offensive_h2(g,s)).__name__, type(h.defensive_h2(g,s)).__name__)"

Expected output:

H1 types: float float
H2 types: float float

H2 (custom) functions live in heuristics/evals.py.

Folder Structure (key parts)

• agents/ — Minimax, Alpha-Beta, Greedy, IterDeep/TT agents
• core/ — game rules, state, search plumbing
• heuristics/ — evals.py with H1/H2
• experiments/ — run_six.py, combined.py
• gui/ — pygame_app_menu.py, gui_logger.py (logs → Bonus/gui_logs/*.csv)
• reports/ — make_report_final.py, make_report_final_plus.py
• out/ — generated CSVs/PDFs (should be ignored by git)
• Bonus/ — bonus assets (e.g., gui_logs/)
• scripts/ — optional helpers (e.g., run_all_and_build.py)

One-shot “do everything” (if present):

python .\scripts\run_all_and_build.py

Common Tips / Troubleshooting

• Module import errors when using -m: prefer the -m module form (e.g., python -m gui.pygame_app_menu) or ensure your current working directory is the project root so relative imports resolve.
• If the PLUS report shows no GUI logs: play a GUI match so CSV logs exist under Bonus/gui_logs/, then rebuild the PLUS report.
• Indentation errors in the report builder: convert tabs to spaces (VS Code → "Convert Indentation to Spaces").
• When running Python code from PowerShell, ensure Python commands are run inside python -c or the Python REPL, not typed at the PowerShell prompt.

Examples

Run a single experiment module (example):

python -m experiments.run_six

Run a single matchup (PowerShell one-liner):

python -c "from experiments.run_six import setup_agents, run_matchup, Breakthrough, BTConfig; mini_off1,mini_def1,ab_off1,ab_def1,ab_off2,ab_def2 = setup_agents(); game = Breakthrough(BTConfig(rows=8, cols=8, start_ranks=2)); rows, summary = run_matchup('Demo', game, mini_off1, ab_off1, trials=1, seed_base=42); print(summary)"

Or save a tiny script run_one_matchup.py and run it:

from experiments.run_six import setup_agents, run_matchup, Breakthrough, BTConfig

mini_off1,mini_def1,ab_off1,ab_def1,ab_off2,ab_def2 = setup_agents()
game = Breakthrough(BTConfig(rows=8, cols=8, start_ranks=2))
rows, summary = run_matchup('Demo', game, mini_off1, ab_off1, trials=1, seed_base=42)
print(summary)

Launch the GUI (manual play)

# preferred: module form
python -m gui.pygame_app_menu

# or run the script directly
python .\gui\pygame_app_menu.py

Notes:

• Use the -m module form to ensure package imports resolve relative to the project root.
• out/ contains generated CSVs and PDFs and should be ignored by git. If you modify code, re-run the experiments to regenerate outputs before building reports.

Project

Breakthrough is an abstract strategy board game invented by Dan Troyka in 2000. This repository contains an implementation of the game plus AI agents. The project was created for CS591 - Advanced Artificial Intelligence at Southeast Missouri State University (Group 1).

Goals

• Implement agents capable of playing Breakthrough
• Experiment with heuristics such as "important pieces", "connected pairs" and configurable aggression/defense parameters

Contributing / Notes for students

When creating new .py files, please add this header near the top:

# author: Mandy Brown

Place files in the appropriate folders (agents/, heuristics/, etc.) and re-run experiments to refresh outputs before building reports.

Thanks!