Building an Abalone Game Using Amazon Q CLI & Pygame

Tahmid Fayaz — Fri, 13 Jun 2025 12:36:01 +0000

🚀 Introduction
I’ve always been fascinated by board games that combine elegant mechanics with deep strategy, and Abalone is the perfect example. In this post, I’ll walk you through how I used the Amazon Q Developer CLI alongside Pygame to create my own digital version of Abalone—from scaffolding the project to polishing the UI.

✨Amazon Q Developer CLI

To install the Amazon Q Developer CLI on my Windows machine, I first set up the Windows Subsystem for Linux (WSL). With a Linux distribution like Ubuntu installed, I open the WSL terminal to run the installer script using the command: curl -o- https://s3.amazonaws.com/amazon-q-cli/install.sh | bash. Once the installation is complete, I just need to restart my WSL terminal. After that, I'm all set to start using the q command.

Prerequisites 🛠️

Before we dive in, make sure you have:
1.Python 3.7+ installed 🐍
2.Pygame library (pip install pygame) 🎨

Folder Structure 📂

Step 1: Initializing Pygame and Defining Constants 💡
In abalone_game.py, I start by importing modules and initializing Pygame:

Next, I define window dimensions, hexagon sizing, and colors for the board, marbles, and UI elements:

and so on

These constants make it easy to tweak the look and feel of the board later. 🎨

Step 2: Representing Hexagonal Positions 🔢
Abalone uses a hex grid, so I created a HexPosition class that stores cube coordinates (q, r, s) and implements equality, hashing, and a string method:

Step 3: Initializing the Board ⚙️
Inside the AbaloneGame class, I set up a dictionary self.board mapping every valid HexPosition (from r = -4 to 4 and appropriate q ranges) to an integer:

0 = empty ➖

1 = black marble ⚫

2 = white marble ⚪

I then fill initial positions for both players

Step 4: Coordinate Conversion 🔄
To render and detect clicks, I convert between hex coordinates and pixel coordinates:

Step 5: Selection and Move Validation ✅
Abalone rules allow selecting 1–3 marbles in a line and either sidestep or push opponent marbles. I implemented:

is_valid_selection() to ensure up to 3 marbles belong to the current player and are in line.get_valid_moves() which loops through six directions and calls either can_sidestep_to_positions() or can_push_in_direction().

This logic checks board bounds, empty target spaces, and the “sumito” push rules (only if you have a larger chain than your opponent’s). 🤜🤛

Step 6: Making a Move ⏩

Once the player clicks a highlighted green circle, make_move():
Clears original marble positions ➖
Shifts marbles (or opponent chain) in the chosen direction 🔄
Increments score if an opponent marble is pushed off 📈
Checks for win (first to push off 6 marbles 🏆)
Switches the current player 🔁

Everything happens smoothly in one method! 👍

Step 7: Drawing the Board and UI 🎨

In draw_board(), I:
Draw a large hexagon border and fill for the wooden board
Loop over all hex positions, draw holes, shadows, and marbles
Highlight selected marbles in yellow
Mark valid destinations with small green circles

In draw_ui(), I render scores, current player, and simple instructions. If the game is over, I display a “Game Over” banner with the winner. 🖥️

Final Step: Game Loop 🔁

The run() method handles Pygame’s event loop:

Play and Extend 🚀
I’m thrilled with how the Abalone game turned out! You can:

Customize colors or board size by tweaking constants 🎨

Add sound effects when marbles move or are pushed off 🔊

Implement AI: a simple minimax over valid moves would be a fun next step 🤖

Save and load game states to disk 💾

Grab the full source on GitHub and let me know how you’d improve it! 🛠️
https://github.com/TahmidFayaz/Abalone

Conclusion 🏁
Implementing Abalone in Pygame was a rewarding dive into hex-grid math, move validation, and UI polish. I hope this walkthrough inspires you to build your own board games—feel free to fork the code, file issues, or submit pull requests. Happy coding! 💻🎉

DEV Community: Tahmid Fayaz

Building an Abalone Game Using Amazon Q CLI & Pygame