🎲 Caribbean Dominoes CLI

A beautiful, interactive CLI application to play Caribbean dominoes and learn how to get better so you can beat your friends IRL!

✨ Features

• 🎨 Beautiful Interface: Rich, colorful terminal output with panels, tables, and emojis
• ⌨️ Arrow Key Navigation: Navigate menus using ↑↓ arrow keys or Vim-style j/k keys
• 🤖 Smart CPU Opponents: Play against intelligent CPU players
• 👥 Team-Based Gameplay: 2v2 teams (You + Ally vs 2 Opponents)
• 📊 Real-Time Scoring: Track scores and progress throughout the game
• 🎯 Multiple Game Modes: Standard and quick play modes
• 📖 Built-in Rules: Access game rules and help anytime

🚀 Setup

1. Clone the repository:

git clone <repository-url>
cd domino-game-cli

2. Install dependencies:

uv sync

That’s it! Use uv run python main.py to start playing (see Usage below).

🎮 Usage

Start a Game

# Play with default settings (first to 200 points)
uv run python main.py play

# Quick mode (first to 100 points)
uv run python main.py play --quick

# Custom target score
uv run python main.py play --target 150

View Commands

# Show all available commands
uv run python main.py --help

# View game rules
uv run python main.py rules

# About the game
uv run python main.py about

🎯 Game Controls

• ↑/↓ or j/k: Navigate menu options
• Enter: Select/Confirm choice
• Vim-style navigation: Supports j (down) and k (up) for Vim users

📖 Game Rules

Setup

• 4 players in 2 teams (You + Ally vs 2 Opponents)
• Each player gets 7 dominoes from a double-six set
• First round starts with the [6|6] domino

Gameplay

• Players take turns counter-clockwise
• Match your domino to either end of the line
• If you can’t play, you must pass
• Round ends when someone plays all dominoes or all players pass

Scoring

• Winner scores the sum of all remaining dominoes in other players’ hands
• If game is blocked, player with lowest hand value wins
• First team to reach target score (default: 200) wins!

🛠️ Technology Stack

• Python 3.9+: Core language
• Typer: CLI framework with rich help formatting
• Rich: Beautiful terminal output with colors and formatting

📁 Project Structure

domino-game-cli/
├── domino_game/              # Main package
│   ├── models/               # Domain models (Domino, Board, Player)
│   ├── game/                 # Game engine & logic (AI, scoring, deck)
│   ├── ui/                   # User interface components
│   │   └── renderer/         # Full-screen rendering
│   └── cli.py               # CLI commands
├── tests/                    # Organized test suite
│   ├── test_models/
│   ├── test_game/
│   └── test_ui/
├── main.py                   # Entry point
└── pyproject.toml           # Project configuration

🧪 Testing

Install dev dependencies first:

uv sync --extra dev

Run all tests with pytest:

uv run pytest                    # Run all tests
uv run pytest -v                 # Verbose output
uv run pytest -m "not slow"      # Skip slow tests

Run specific tests:

# Test specific directory
uv run pytest tests/test_game/

# Test specific file
uv run pytest tests/test_models/test_domino.py

# Test specific function
uv run pytest tests/test_game/test_ai.py::test_simple_strategy

Run with coverage:

uv run pytest --cov=domino_game --cov-report=term-missing

Continuous Integration runs automatically on:

• Pull requests to main
• Pushes to main branch

The CI tests the package on Python 3.9, 3.10, 3.11, and 3.12.

📝 Commands Reference

Command	Options	Description
play	--target/-t, --quick/-q	Start a new game
rules	-	Display game rules
about	-	About the application

🎨 Screenshots

The game features:

• Colorful domino representations with unique colors for each number
• Beautiful panels and borders for game states
• Real-time score tracking in tables
• Visual feedback for moves and game events
• Clean, organized layout for easy gameplay

🤝 Contributing

Contributions are welcome! Feel free to submit issues and enhancement requests.

📜 License

See LICENSE file for details.

---

Version 2.0 - Enhanced Edition 🚀