Forem: Kamyarmg

🎮 Building a Terminal-Based 2048 Game in Python

Kamyarmg — Fri, 18 Apr 2025 12:29:58 +0000

In this post, we’ll walk through the implementation of a lightweight terminal-based tile game inspired by 2048. We'll explore the logic, algorithms, color display in the terminal, and movement mechanics—all crafted in pure Python.

🧩 Overview of What We're Building

A grid-based game where tiles with the same number can be merged.
Navigation using WASD keys.
Auto-generated new tiles after each move.
A colorful terminal UI for better visibility.
Game-ending logic upon reaching 2048 or running out of moves.

🚀 Features at a Glance

Pure Python, no external libraries required.
Uses ANSI color codes for terminal coloring.
Compatible with both Windows and Unix-based systems.
Modular code design using classes, enums, and functions.
Supports extensibility and customizations.

🧠 2048 Summary

Each round, the player can move tiles in one of four directions.
If two adjacent tiles with the same value meet, they merge.
A new tile is randomly generated in an empty space after each move.
The game ends when there are no valid moves or a tile reaches 2048.

Code Structure and Explanations

📦 1. Imports

import enum
import random

We use enum for cleaner state and action management, and random to add new tiles.

🔡 2. Cross-platform Character Input

def getch() -> str:
    """Gets a single character"""
    try:
        import msvcrt

        return str(msvcrt.getch().decode("utf-8"))  # type: ignore
    except ImportError:
        import sys
        import termios
        import tty

        fd = sys.stdin.fileno()
        oldsettings = termios.tcgetattr(fd)
        try:
            tty.setraw(fd)
            ch = sys.stdin.read(1)
        finally:
            termios.tcsetattr(fd, termios.TCSADRAIN, oldsettings)
        return ch

On Windows, it uses msvcrt.
On Unix-based systems, it uses termios and tty.

This allows us to read single-character inputs like w, a, etc., in real-time.

🚦 3. Game State and Actions

class State(enum.Enum):
    BLOCK = enum.auto()
    WALL = enum.auto()
    CONTINUE = enum.auto()
    END = enum.auto()


class Action(enum.Enum):
    MOVE_DOWN = "down"
    MOVE_LEFT = "left"
    MOVE_RIGHT = "right"
    MOVE_UP = "up"
    EXIT = "exit"
    NOTHING = "nothing"

We define possible cell states (like wall or end) and player actions (directional movement).

🎨 4. Terminal Coloring

def rgb_bg(r: int, g: int, b: int) -> str:
    return f"\033[48;2;{r};{g};{b}m"


def rgb(r: int, g: int, b: int) -> str:
    return f"\033[38;2;{r};{g};{b}m"


def reset() -> str:
    return "\033[0m"

These helper functions generate ANSI escape codes for colored text and backgrounds.

🌈 5. Tile Colors by Value

value_color = {
    2: f"{rgb(0, 0, 0)}{rgb_bg(255, 255, 255)}",
    4: f"{rgb(0, 0, 0)}{rgb_bg(150, 150, 255)}",
    8: f"{rgb(0, 0, 0)}{rgb_bg(100, 255, 100)}",
    16: f"{rgb(0, 0, 0)}{rgb_bg(255, 100, 100)}",
    32: f"{rgb(0, 0, 0)}{rgb_bg(150, 150, 150)}",
    64: f"{rgb(0, 0, 0)}{rgb_bg(200, 150, 100)}",
    128: f"{rgb(0, 0, 0)}{rgb_bg(255,182,193)}",
    256: f"{rgb(0, 0, 0)}{rgb_bg(255, 255, 0)}",
    512: f"{rgb(0, 0, 0)}{rgb_bg(100, 250, 250)}",
    1024: f"{rgb(0, 0, 0)}{rgb_bg(255, 0, 255)}",
    2048: f"{rgb(0, 0, 0)}{rgb_bg(255, 99, 71)}",
}

Each tile value has a color combo, improving visual feedback in the terminal. This maps values (like 2, 4, 8...) to specific foreground/background color combinations using ANSI escape sequences.

🧱 6. The Cell Class

class Cell:
    def __init__(self, state: State = State.BLOCK, value: int = 0) -> None:
        self.state: State = state
        self.value: int = value
        self.down: "Cell"
        self.up: "Cell"
        self.right: "Cell"
        self.left: "Cell"

    def __str__(self) -> str:
        match self:
            case self if self.state == State.WALL:
                return "🔹"
            case self if self.value:
                value = str(self.value).center(6)[2:4]
                return f"{value_color[self.value]}{value}{reset()}"
            case self if self.right.value:
                value = str(self.right.value).center(6)[:2]
                return f"{value_color[self.right.value]}{value}{reset()}"
            case self if self.left.value:
                value = str(self.left.value).center(6)[4:]
                return f"{value_color[self.left.value]}{value}{reset()}"
        margin_value = (
            self.down.value
            or self.up.value
            or (getattr(self.down.left, "value") if hasattr(self.down, "left") else 0)
            or (getattr(self.down.right, "value") if hasattr(self.down, "right") else 0)
            or (getattr(self.up.right, "value") if hasattr(self.up, "right") else 0)
            or int(getattr(self.up.left, "value") if hasattr(self.up, "left") else 0)
        )
        if margin_value:
            return f"{value_color[int(margin_value)]}  {reset()}"
        return f"{rgb_bg(0, 0, 0)}  {reset()}"

Each cell knows:

Its state (block, wall, etc.)
Its numeric value (used in merging)
References to its four neighbors (left, right, up, down)
__str__ is overridden to print the cell with colors and context-aware visuals.

🗺️ 7. The Board Class

class Board:
    def __init__(self, size: int) -> None:
        self.size = size * 3 + 2
        self.player_state: State = State.CONTINUE
        self.cells: list[list[Cell]]
        self.valuable_cells: list[Cell]
        self.set_initial()

    def set_initial(self) -> None:
        self.set_cells()
        self.set_walls()
        self.set_cells_neighboring()
        self.set_valuable_cells()
        self.set_init_value_cell()

    def set_cells(self) -> None:
        self.cells = [[Cell() for _ in range(self.size)] for _ in range(self.size)]

    def set_walls(self) -> None:
        for i in range(self.size):
            for j in [0, self.size - 1]:
                self.cells[i][j].state = State.WALL
                self.cells[j][i].state = State.WALL

    def set_cells_neighboring(self) -> None:
        for i in range(1, self.size - 1):
            for j in range(1, self.size - 1):
                self.cells[i][j].left = self.cells[i][j - 1]
                self.cells[i][j].right = self.cells[i][j + 1]
                self.cells[i][j].up = self.cells[i - 1][j]
                self.cells[i][j].down = self.cells[i + 1][j]

    def set_valuable_cells(self) -> None:
        self.valuable_cells = [
            self.cells[i][j]
            for i in range(2, self.size, 3)
            for j in range(2, self.size, 3)
        ]

    def set_init_value_cell(self) -> None:
        self.valuable_cells[0].value = 2
        self.valuable_cells[-3].value = 2

    def take(self, ch: str) -> None:
        for _ in range(int(pow(len(self.valuable_cells), 0.5))):
            match ch:
                case " ":
                    self.player_state = State.END
                case "w":
                    self.move(Action.MOVE_UP.value)
                case "s":
                    self.move(Action.MOVE_DOWN.value)
                case "a":
                    self.move(Action.MOVE_LEFT.value)
                case "d":
                    self.move(Action.MOVE_RIGHT.value)
        new_valuable_cell = list(filter(lambda c: not c.value, self.valuable_cells))
        if new_valuable_cell:
            random.choice(new_valuable_cell).value = 2
        else:
            self.player_state = State.END

    def move(self, direction: str) -> None:
        for c in self.valuable_cells:
            if getattr(getattr(c, direction), direction).state == State.BLOCK:
                d_cell = getattr(getattr(getattr(c, direction), direction), direction)
                if d_cell.value == c.value:
                    d_cell.value += c.value
                    c.value = 0
                elif c.value and not d_cell.value:
                    d_cell.value = c.value
                    c.value = 0
                if d_cell.value == 2048:
                    self.player_state = State.END
                    break

    def __str__(self) -> str:
        return "\n".join(["".join(map(str, rows)) for rows in self.cells])

This handles the entire game board logic. The board is constructed as a 2D grid with padded walls.

Methods:

set_initial: Sets up the board by calling the other setup methods.
set_cells: Creates all cells.
set_walls: Adds walls to edges.
set_cells_neighboring: Links each cell to its 4 neighbors.
set_valuable_cells: Marks specific cells on the grid as "valuable" cells — meaning the player can place or merge tile values (like 2, 4, 8, etc.) only in these cells.
set_init_value_cell: Adds the first two cells with value 2.
take(ch):
1. Takes user input (w, a, s, d, or space).
2. Applies movement based on input.
3. Spawns a new random 2 tile if there's space.
4. Ends the game if no space.
move:
1. Moves all cells in the given direction by checking and merging cells. Merging is allowed only if the destination cell is the same value.
2. If 2048 is achieved, the game ends.

🎮 8. The Game Loop

def run() -> None:
    board = Board(4)
    print(f"\033[H\033[J{board}")
    while board.player_state != State.END:
        board.take(getch())
        print(f"\033[H\033[J{board}")

The run() function drives the game:

Initializes the board.
Clears and redraws the screen on each move.
Takes input using getch().

🧪 Try it Yourself!
This program is built for the Python terminal environment using only Python’s standard libraries. It does not depend on any external libraries and is compatible with Python 3.10 and above.

For the complete code, please visit the “oyna” project and then go to the “twenty_forty_eight_2048” section to view the code.

You can run the script by saving it as grid_base.py or download grid_base.py file and executing:

python grid_base.py

Use w, a, s, d to move the tiles. Press SPACE to exit.

🔧 Want to Contribute?
The Oyna project is a fun starting point! You can improve or expand it by:

Adding undo functionality.
Implementing scoring.
Building a GUI version (Tkinter, Pygame, etc.).
Creating an AI to play it.
Supporting custom board sizes or patterns.

Feel free to fork it and submit a pull request. Let’s make it awesome together! 🚀

How to Build a Graphical Minesweeper Game in the Python Terminal.

Kamyarmg — Mon, 31 Mar 2025 21:15:58 +0000

This guide explains how to build the Minesweeper game in the Python terminal. We’ll break down the code step by step—from importing modules and defining helper functions to creating the main classes and implementing the game loop. Finally, you’ll learn how to run the game in your terminal.

This program is built for the Python terminal environment using only Python’s standard libraries. It does not depend on any external libraries and is compatible with Python 3.10 and above.

For the complete code, please visit the “oyna” project and then go to the “Minesweeper” section to view the code. Feel free to contribute to its improvement and development.

1. Importing Modules and Helper Function

The code begins by importing required modules and defining a helper function to capture a single character from user input. This function works across different operating systems.

import itertools
import random
import typing
from enum import Enum

def getch() -> str:
    """Gets a single character"""
    try:
        import msvcrt
        return str(msvcrt.getch().decode("utf-8"))  # type: ignore
    except ImportError:
        import sys
        import termios
        import tty

        fd = sys.stdin.fileno()
        oldsettings = termios.tcgetattr(fd)
        try:
            tty.setraw(fd)
            ch = sys.stdin.read(1)
        finally:
            termios.tcsetattr(fd, termios.TCSADRAIN, oldsettings)
        return ch

Imports:

itertools and random for processing iterators and generating random values.
typing to support type hints.
Enum from the enum module is used to define various states and actions.

getch Function:
Captures a single character without waiting for the Enter key.
Uses msvcrt on Windows and termios/tty on Unix-like systems.

2. Defining States and Actions

Two enums are defined to manage cell states and user actions.

class State(Enum):
    BLOCK = "🟪"
    BOMB = "💣"
    DEAD = "💥"
    EIGHT = " 8"
    FIVE = " 5"
    FLAG = "❓"
    FOUR = " 4"
    NINE = " 9"
    ONE = " 1"
    PLAYER = "🟦"
    SEVEN = " 7"
    SIX = " 6"
    THREE = " 3"
    TWO = " 2"
    WALL = "🔹"
    WIN = "🏆"
    ZERO = "  "

    @classmethod
    def create_from_number(cls, number: int) -> "State":
        return {
            0: cls.ZERO,
            1: cls.ONE,
            2: cls.TWO,
            3: cls.THREE,
            4: cls.FOUR,
            5: cls.FIVE,
            6: cls.SIX,
            7: cls.SEVEN,
            8: cls.EIGHT,
            9: cls.NINE,
        }[number]

class Action(Enum):
    CLICK = "click"
    MOVE_DOWN = "down"
    MOVE_LEFT = "left"
    MOVE_RIGHT = "right"
    MOVE_UP = "up"
    SET_FLAG = "flag"

State Enum:
Contains various visual states for cells, including hidden blocks, bombs, numbers (from ZERO to NINE), flags, walls, and end-game states (WIN and DEAD).

The create_from_number class method maps a numeric value to its corresponding state.

Action Enum:
Lists possible actions such as clicking a cell, moving the player in four directions, and setting a flag.

3. The Cell Class

Each cell on the Minesweeper board is represented by the Cell class. This class holds cell-specific properties and methods to handle actions like clicking and flagging.

class Cell:
    def __init__(self, state: State = State.BLOCK) -> None:
        self.player_is_here = False  # Indicates if the player is on this cell.
        self.seen = False            # Whether the cell has been revealed.
        self.state = state           # The display state of the cell.
        self.value = 0               # Holds the bomb count (or -1 for a bomb).
        self.down: "Cell"
        self.up: "Cell"
        self.right: "Cell"
        self.left: "Cell"

    def __str__(self) -> str:
        # If the player is here, show the PLAYER icon; otherwise, show the current state.
        return State.PLAYER.value if self.player_is_here else self.state.value

    def set_neighbors(
        self, left: "Cell", right: "Cell", up: "Cell", down: "Cell"
    ) -> None:
        self.down = down
        self.up = up
        self.right = right
        self.left = left

    def set_state(self, action: Action) -> "Cell":
        match action:
            case Action.SET_FLAG:
                self._set_flag()
                return self
            case Action.CLICK:
                self._click()
                return self
            case _:
                return self._move_tile(action)

    def _move_tile(self, action: Action) -> "Cell":
        side_: "Cell" = getattr(self, action.value)
        if side_.state == State.WALL:
            return self
        else:
            self.player_is_here = False
            side_.player_is_here = True
            return side_

    def _click(self) -> None:
        # Process a click only if the cell hasn't been seen and is not a wall.
        if self._is_unseen_and_not_wall():
            # If the cell is not a bomb, update its state based on the value.
            self.state = (
                State.create_from_number(self.value) if self.value > -1 else State.BOMB
            )
            self.seen = True
            # If the cell is empty (no bombs around), automatically reveal adjacent cells.
            if self._is_empty():
                self._continue(Action.MOVE_DOWN)
                self._continue(Action.MOVE_LEFT)
                self._continue(Action.MOVE_RIGHT)
                self._continue(Action.MOVE_UP)

    def _is_unseen_and_not_wall(self) -> bool:
        return not self.seen and self.state != State.WALL

    def _is_empty(self) -> bool:
        return self.value == 0

    def _set_flag(self) -> None:
        # Toggle flag if the cell has not been revealed.
        if not self.seen:
            self.state = State.BLOCK if self.state == State.FLAG else State.FLAG

    def _continue(self, side: Action) -> None:
        side_: typing.Union["Cell", None] = getattr(self, side.value)
        if side_ is not None:
            side_.set_state(Action.CLICK)

Attributes:

player_is_here tracks the player’s current position.
seen indicates whether the cell has been clicked and revealed.
state holds the visual representation (like a hidden block, number, flag, or bomb).
value stores the underlying number (bomb count) or -1 if the cell contains a bomb.
Neighbor pointers (up, down, left, right) are set later.

Methods:

__str__: Displays the appropriate icon depending on whether the player is on the cell.
set_neighbors: Sets the cell’s adjacent neighbors.
set_state: Dispatches actions (click, flag, or move) based on the user input.
_click: Reveals the cell; if it is empty, recursively reveals neighboring cells.
_set_flag: Toggles a flag on the cell.
_continue: Automatically continues revealing adjacent cells if the current cell is empty.

4. The Board Class

The Board class manages the game grid, sets up walls, places bombs, and assigns neighboring cells.

class Board:
    def __init__(self, size: int) -> None:
        self.start_player_position = size // 2
        self.size = size
        self.cells = self._cells()
        self.set_initial()
        self.player = self.cells[self.start_player_position][self.start_player_position]

    def _cells(self) -> list[list[Cell]]:
        return [[Cell() for _ in range(self.main_size)] for _ in range(self.main_size)]

    @property
    def main_size(self) -> int:
        # The main board size includes a border (walls) around the game area.
        return self.size + 2

    def set_initial(self) -> None:
        self.set_horizontal_walls()
        self.set_vertical_walls()
        self.set_cells_neighboring()
        self.set_player()
        self.set_bombs()

    def set_horizontal_walls(self) -> None:
        for j in range(self.main_size):
            self.cells[0][j].state = State.WALL
            self.cells[self.main_size - 1][j].state = State.WALL

    def set_vertical_walls(self) -> None:
        for i in range(self.main_size):
            self.cells[i][0].state = State.WALL
            self.cells[i][self.main_size - 1].state = State.WALL

    def set_cells_neighboring(self) -> None:
        for i in range(1, self.main_size - 1):
            for j in range(1, self.main_size - 1):
                self.cells[i][j].set_neighbors(
                    self.cells[i][j - 1],
                    self.cells[i][j + 1],
                    self.cells[i - 1][j],
                    self.cells[i + 1][j],
                )

    def set_player(self) -> None:
        self.cells[self.start_player_position][self.start_player_position].player_is_here = True

    def set_bombs(self) -> None:
        # Place a certain number of bombs randomly on the board.
        for _ in range(self.size + 2):
            cell = self.cells[random.randint(2, self.size - 1)][random.randint(2, self.size - 1)]
            if cell.value != -1:
                cell.value = -1
                # Update neighboring cells by increasing their bomb count.
                self.increase_value(cell.down)
                self.increase_value(cell.down.left)
                self.increase_value(cell.down.right)
                self.increase_value(cell.up)
                self.increase_value(cell.up.left)
                self.increase_value(cell.up.right)
                self.increase_value(cell.left)
                self.increase_value(cell.right)

    @staticmethod
    def increase_value(cell: Cell) -> None:
        # Increment the cell's value if it is not a bomb.
        cell.value += 1 if cell.value != -1 else 0

    def action(self, ch: str) -> None:
        # Map key inputs to actions on the current player cell.
        match ch:
            case "w":
                self.player = self.player.set_state(Action.MOVE_UP)
            case "a":
                self.player = self.player.set_state(Action.MOVE_LEFT)
            case "s":
                self.player = self.player.set_state(Action.MOVE_DOWN)
            case "d":
                self.player = self.player.set_state(Action.MOVE_RIGHT)
            case "e":
                self.player = self.player.set_state(Action.CLICK)
            case "q":
                self.player = self.player.set_state(Action.SET_FLAG)
            case " ":
                self.player.state = State.BOMB
            case _:
                pass

    def __str__(self) -> str:
        return "\n".join(["".join([str(cell) for cell in rows]) for rows in self.cells])

    def player_win(self) -> bool:
        # Determine if the player has won by checking if every non-bomb, non-wall cell has been revealed.
        for cell in itertools.chain(*self.cells):
            if cell.value >= 0 and cell.state != State.WALL and not cell.seen:
                return False
        return True

Grid Initialization:
The board is created with an extra border to act as walls.

Walls:
set_horizontal_walls and set_vertical_walls add walls around the game area.

Neighboring Cells:
set_cells_neighboring connects each cell to its adjacent neighbors.

Bomb Placement:
set_bombs randomly places bombs and updates the numbers of adjacent cells.

User Input:
The action method maps key presses (such as “w”, “a”, “s”, “d” for movement and “e” for clicking) to corresponding actions.

Win Condition:
The player_win method checks if all non-bomb cells have been revealed.

5. The Game Class and Game Loop

The Game class encapsulates the main game loop, managing the display and processing user input until the game ends.

class Game:
    def __init__(self) -> None:
        self.board = Board(15)

    def run(self) -> None:
        self._bold_font()
        while self.allow_continue():
            self._print_board()
            self.board.action(getch())
        self.print_result()

    @staticmethod
    def _bold_font() -> None:
        print("\033[1;10m")

    @staticmethod
    def clear_screen() -> None:
        print("\033[H\033[J", end="")

    def _print_board(self) -> None:
        self.clear_screen()
        print(self.board)

    def allow_continue(self) -> bool:
        # Continue the game if the player hasn't hit a bomb and hasn't yet won.
        return self.board.player.state != State.BOMB and not self.board.player_win()

    def print_result(self) -> None:
        # Once the game is over, update bomb cells to reflect win or loss.
        for cell in filter(lambda c: c.value < 0, itertools.chain(*self.board.cells)):
            cell.state = State.WIN if self.board.player_win() else State.DEAD
            cell.player_is_here = False
        self._print_board()

def run() -> None:
    Game().run()

if __name__ == "__main__":
    run()

Game Initialization:
A Game object is created with a board of size 15.

Game Loop:
The loop continues while the player hasn't triggered a bomb or met the win condition. Each iteration clears the screen, prints the board, and processes a key input.

Display Settings:
The _bold_font method sets a bold font for improved visual appeal.

Result Handling:
After the game ends, print_result updates bomb cells to indicate whether the player won (WIN state) or lost (DEAD state) and then prints the final board.

6. How to Run the Game

To run this Minesweeper game in your Python terminal:

Prerequisites:
Python 3.10 or above. No external libraries are needed as the game uses only standard Python libraries.

Download the Code:
Save the entire code in a file (for example, minesweeper_game.py) or download the grid_base.py file.

Run the Game:
Open your terminal and navigate to the directory containing the file. Execute the command:

python3 minesweeper_game.py

7. How to Play

Once the game starts, the Minesweeper board will be displayed in your terminal. Use the following controls:

Movement:

w: Move Up
a: Move Left
s: Move Down
d: Move Right
e: Click (reveal a cell)
q: Set/Toggle Flag (to mark a suspected bomb)
Space: Exit the game

Objective:
Reveal all cells that do not contain bombs. If you reveal a bomb, the game is over. When all safe cells are revealed, you win!

8. Conclusion

This comprehensive guide provided a step-by-step explanation of the Minesweeper game code in the Python terminal. We covered:

How to handle user input with a cross-platform getch function.
The use of Enum classes to manage cell states and actions.
Detailed explanations of the Cell and Board classes, including neighbor assignment, bomb placement, and win condition checking.
The game loop and how the Game class manages the overall flow.
Instructions on running the game and the controls for playing.

Enjoy the game!