Development Scripts¶

This document describes the development scripts and CLI commands available for Ajitroids.

Running the Game¶

Basic Execution¶

# Run with Python
python main.py

# Run with uv (if installed)
uv run main.py

# Run as module
python -m ajitroids

Command-Line Options¶

# Show help
python main.py --help

# Enable debug mode
python main.py --debug

# Start in fullscreen
python main.py --fullscreen

# Set custom resolution
python main.py --resolution 1920x1080

# Disable sound
python main.py --no-sound

# Show version
python main.py --version

Testing Commands¶

Running Tests¶

# Run all tests
pytest

# Run with coverage
pytest --cov=modul

# Run specific test file
pytest tests/test_player_respawn.py

# Run specific test
pytest tests/test_player_respawn.py::test_player_respawn

# Run with verbose output
pytest -v

# Stop on first failure
pytest -x

# Show local variables on failure
pytest -l

# Run in parallel (requires pytest-xdist)
pytest -n auto

Test Options¶

# Generate HTML coverage report
pytest --cov=modul --cov-report=html

# Show missing lines
pytest --cov=modul --cov-report=term-missing

# Run only failed tests from last run
pytest --lf

# Run failed tests first
pytest --ff

Code Quality¶

Formatting¶

# Format all Python files
black modul/ tests/ main.py

# Check formatting without changes
black --check modul/ tests/ main.py

# Format specific file
black modul/player.py

# Show diff without applying
black --diff modul/player.py

Linting¶

# Lint all files
flake8 modul/ tests/ main.py

# Lint specific directory
flake8 modul/

# Show statistics
flake8 --statistics modul/

# Generate HTML report
flake8 --format=html --htmldir=flake-report modul/

Type Checking¶

# Install mypy
pip install mypy

# Run type checking
mypy modul/

# Strict mode
mypy --strict modul/

# Generate report
mypy --html-report mypy-report modul/

Documentation¶

Building Documentation¶

# Install dependencies
pip install -r requirements-docs.txt

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

# Build with strict mode (fail on warnings)
mkdocs build --strict

# Deploy to GitHub Pages (manual)
mkdocs gh-deploy

Documentation Options¶

# Serve on different port
mkdocs serve --dev-addr localhost:8001

# Serve with live reload
mkdocs serve --livereload

# Clean build directory
mkdocs build --clean

# Verbose build output
mkdocs build --verbose

Building and Packaging¶

Building Package¶

# Install build tools
pip install build

# Build distribution
python -m build

# Build only wheel
python -m build --wheel

# Build only source distribution
python -m build --sdist

Installing Locally¶

# Install in development mode
pip install -e .

# Install with dev dependencies
pip install -e ".[dev]"

# Install from local build
pip install dist/ajitroids-*.whl

UML Diagram Generation¶

Prerequisites¶

# Install dependencies
pip install pylint graphviz

# On Ubuntu/Debian
sudo apt-get install graphviz

# On macOS
brew install graphviz

Generate Diagrams¶

Create the diagram generation script:

scripts/generate-diagrams.sh:

#!/usr/bin/env bash
set -e

echo "Generating UML diagrams..."

# Create output directory
mkdir -p docs/reference/diagrams

# Generate class diagrams
pyreverse -o png -p Ajitroids modul/

# Move to docs
mv classes_Ajitroids.png docs/reference/diagrams/classes.png
mv packages_Ajitroids.png docs/reference/diagrams/packages.png

echo "Diagrams generated in docs/reference/diagrams/"

Make executable:

chmod +x scripts/generate-diagrams.sh

Run:

./scripts/generate-diagrams.sh

Git Workflow Scripts¶

Clean Repository¶

# Remove Python cache
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

# Remove build artifacts
rm -rf build/ dist/ *.egg-info/

# Remove test artifacts
rm -rf .pytest_cache/ htmlcov/ .coverage

# Remove documentation build
rm -rf site/

Check Repository Status¶

# Show status
git status

# Show diff
git --no-pager diff

# Show staged changes
git --no-pager diff --staged

# Show log
git log --oneline -10

Utility Scripts¶

Reset Settings¶

scripts/reset-settings.sh:

#!/usr/bin/env bash

echo "Resetting Ajitroids settings..."
rm -rf ~/.ajitroids/
echo "Settings reset. They will be recreated on next run."

Backup Save Data¶

scripts/backup-saves.sh:

#!/usr/bin/env bash

BACKUP_DIR="backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

cp -r ~/.ajitroids/* "$BACKUP_DIR/"
echo "Saved data backed up to $BACKUP_DIR"

The repository includes a small development helper that renders all menu classes found in modul.menu to PNG files. This is useful for visually verifying UI changes without running the full game.

Script location: .development/generate_menu_screenshots.py

Run it with:

python .development/generate_menu_screenshots.py

Screenshots are written to the repository .logs/ directory as .logs/<MenuClassName>.png. The .logs/ directory is ignored by Git.

Run Full CI Checks¶

scripts/ci-check.sh:

#!/usr/bin/env bash
set -e

echo "Running CI checks..."

echo "1. Formatting check..."
black --check modul/ tests/ main.py

echo "2. Linting..."
flake8 modul/ tests/ main.py

echo "3. Running tests..."
pytest --cov=modul

echo "4. Building package..."
python -m build

echo "All checks passed!"

Development Shortcuts¶

Create Virtual Environment¶

# Create venv
python -m venv venv

# Activate
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt
pip install -e ".[dev]"

Quick Test¶

# Run game quickly
python main.py --no-sound --resolution 800x600

Profile Performance¶

# Install profiler
pip install py-spy

# Profile the game
py-spy record -o profile.svg -- python main.py

# View profile
open profile.svg

Environment Setup¶

Development Environment¶

# Install all dependencies
pip install -r requirements.txt
pip install -r requirements-docs.txt
pip install -e ".[dev]"

# Verify installation
python -c "import pygame; print(pygame.version.ver)"
pytest --version
black --version

Pre-commit Hooks¶

Set up pre-commit hooks to check code before committing:

.git/hooks/pre-commit:

#!/bin/bash

echo "Running pre-commit checks..."

# Format check
black --check modul/ tests/ main.py || {
    echo "Code formatting failed. Run: black modul/ tests/ main.py"
    exit 1
}

# Lint check
flake8 modul/ tests/ main.py || {
    echo "Linting failed."
    exit 1
}

# Run tests
pytest || {
    echo "Tests failed."
    exit 1
}

echo "Pre-commit checks passed!"