Block Blast GridMind AI

A reinforcement-learning experiment for Block Blast-style puzzle gameplay with a playable board and DQN training script.

Chinese · Quickstart · Features · Tech Stack

Overview

Block placement games reward planning, board-space management, and long-horizon tradeoffs. This repo explores how a DQN-style agent can learn placement choices that keep the grid playable longer.

The project includes both a playable Pygame board and a deeper training script. The training script imports PyTorch and psutil, so install those separately if your environment only uses requirements.txt.

Features

• Playable Block Blast-style local game.
• DQN-style training script with convolutional grid features.
• Replay, n-step learning, attention-style scoring, and checkpoint logic in train_ai.py.
• Alternate harder game variant for experimentation.
• MIT-licensed code for study and modification.

How It Works

1. Run game.py to understand the puzzle environment.
2. Encode the grid, preview pieces, and game state as model inputs.
3. Train the DQN-style model with replay and exploration.
4. Watch behavior through the Pygame display and tune hyperparameters.

Quickstart

Run the project locally with the commands below.

git clone https://github.com/Ha22yX/Block-Blast-GridMind-AI.git
cd Block-Blast-GridMind-AI
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python game.py

# Training path: install the extra libraries used by train_ai.py
pip install torch psutil
python train_ai.py

The current requirements.txt covers the playable game path; training needs PyTorch and psutil as shown above.

Configuration

Item	Purpose
Display speed	Use the training script controls to slow down or speed up visual observation.
Training output	Keep checkpoints/logs out of source control for longer runs.
CPU/GPU	The script can run on CPU, but training speed depends heavily on hardware.
Game variant	Use game_hard.py when testing a harder environment.

Tech Stack

Layer	Technology	Role
Game	Pygame	Interactive board and training display.
Learning	PyTorch	DQN/CNN model and optimizer in train_ai.py.
Runtime	NumPy, psutil	State arrays and CPU/resource monitoring.
License	MIT	Permissive reuse with attribution.

Project Layout

game.py                 playable Block Blast-style game
game_hard.py            alternate/harder variant
train_ai.py             reinforcement-learning trainer
requirements.txt        base Python dependencies
LICENSE                 MIT license

Status

RL playground for studying puzzle-game agents. The training code is experimental and should be treated as a research sandbox.

License

MIT License. See LICENSE.