Hinger Strategy Game

A Python AI grid-based board game project modeling game states, applying search algorithms (BFS/DFS/IDDFS/A*) to find safe paths, and developing competitive agents using game algorithms such as Minimax, Alpha-Beta pruning, and Monte Carlo Tree Search.

Overview

Hinger is a two-player, turn-based game played on a grid of counters. Each move removes one counter from a chosen cell. The project focuses on search efficiency, strategy design, and gameplay logic, and includes a GUI for interactive play.

Screenshots

Hinger main menu to choose game type.

Selecting a competitive agent to play against.

Example gameplay playing against an agent.

Highlights

• State module with region and hinger detection, plus move generation and validation.
• Safe-path search with BFS, DFS, IDDFS, and A* algorithms.
• Weighted minimum-cost safe path for non-binary states.
• Agents with MiniMax, Alpha-Beta pruning, and MCTS strategies.
• Pygame UI with difficulty settings, timers, and move counters.
• Built-in tests and performance benchmarking with Matplotlib plots.

Game Rules

• The board is an m x n grid. Each cell contains zero or more counters.
• An active cell has at least one counter. Adjacency includes horizontal, vertical, and diagonal neighbors.
• An active region is a maximal connected set of active cells.
• A move removes exactly one counter from an active cell.
• A hinger is an active cell with exactly one counter whose removal increases the number of active regions.
• The first player to remove a hinger wins. If all counters are removed without triggering a hinger, the game is a draw.
• A safe state has no hingers. A safe path is a sequence of moves that never passes through a hinger state.
• For weighted paths, the cost of a move is 1 plus the number of adjacent active cells.

Project Structure

• hinger/state.py - State representation, region/hinger logic, move generation, and tests.
• hinger/path.py - Safe-path search (BFS, DFS, IDDFS, A*), weighted min-cost search, benchmarks.
• hinger/agent.py - Agent strategies (MiniMax, Alpha-Beta, MCTS), win analysis, and tests.
• hinger/game.py - Pygame GUI, gameplay loop, difficulty settings, and play/test modes.

Requirements

• Python 3.12
• pygame (GUI)
• matplotlib (benchmark plots)

Install dependencies:

python -m pip install -e .

Running

Run module tests:

python -m hinger.state
python -m hinger.path
python -m hinger.agent

Run the game UI:

python -m hinger.game

Usage Notes

• hinger/path.py includes an interactive runner for tests, performance comparison, and a weighted min-cost path function with tests.
• hinger/game.py supports Human vs AI and AI vs AI, with selectable difficulty and strategy.
• The GUI uses random starting boards sized by difficulty level.