game-collection 1.2.0
🎮 Коллекция классических аркадных игр: Snake, Tetris, Arkanoid и Pac-Man на Python с Pygame
Requires Python: >=3.10
Keywords: games, arcade, pygame, snake, tetris, arkanoid, pacman, python, игры, аркада, змейка, тетрис, арканоид, пакман

# 🎮 Game Collection

<div align="center">

![Python](https://img.shields.io/badge/Python-3.10+-blue?style=for-the-badge&logo=python&logoColor=white)
![Pygame](https://img.shields.io/badge/Pygame-2.5+-green?style=for-the-badge&logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)
![Tests](https://img.shields.io/badge/Tests-85%20passed-brightgreen?style=for-the-badge)

**Коллекция классических аркадных игр на Python с Pygame**

[🎯 Играть](#-установка) • [📖 Документация](#-документация) • [🐛 Баги](https://github.com/hleserg/game/issues) • [💡 Предложения](https://github.com/hleserg/game/issues)

</div>

## ✨ Особенности

| 🐍 **Snake** | 🧩 **Tetris** | 🎯 **Arkanoid** | 👻 **Pac-Man** |
|:---:|:---:|:---:|:---:|
| Классическая змейка с растущей механикой | Блочная головоломка с очисткой линий | Breakout-стиль с физикой мяча | Навигация по лабиринту с точками и призраками |
| Бомбы и золотые яблоки | Поворот фигур и комбо | Разрушение блоков | Избегание призраков |
| Анимации взрывов | Система очков | Ракеты и спецэффекты | Режимы призраков |

## 🚀 Установка

### 📦 Из исходного кода

```bash
# Клонируйте репозиторий
git clone https://github.com/hleserg/game.git
cd game

# Установите в режиме разработки
pip install -e .

# Или с зависимостями для разработки
pip install -e ".[dev]"
```

### 🎯 Из PyPI

```bash
# Стандартная установка
pip install game-collection

# Если проблемы с правами на Windows:
pip install game-collection --no-deps --user
```

### 🪟 Windows

Если возникают проблемы с правами доступа pygame на Windows:

```bash
# Автоматический установщик
install_game.bat

# Или ручная установка
pip install game-collection --no-deps --user
```

## 🎮 Использование

### 💻 Командная строка

После установки запустите коллекцию игр:

```bash
# Через точку входа (если PATH настроен)
game-collection

# Через Python модуль (всегда работает)
python -m game

# Через локальный файл (для разработки)
python src/game/main.py
```

### 🔧 Устранение неполадок

Если команда `game-collection` не найдена:

1. **Windows**: Запустите `setup_path.bat` от имени администратора
2. **Альтернатива**: Всегда используйте `python -m game`
3. **Подробности**: См. [Руководство по установке Windows](WINDOWS_INSTALLATION_GUIDE.md)

### 🛠️ Разработка

```bash
# Запуск игры
python -m game

# Запуск тестов
python -m pytest tests/

# Тесты с покрытием
python -m pytest tests/ --cov=src/game

# Проверка качества кода
python -m ruff check src/
python -m mypy src/

# Сборка исполняемого файла
python build_exe.py

# Установка pre-commit хуков
pre-commit install

# Запуск pre-commit на всех файлах
pre-commit run --all-files
```

### 🐛 Отладочные функции

Игра включает отладочный оверлей, который можно переключать во время игры:

- **F1**: Переключить отладочный оверлей вкл/выкл
- **F2**: Сбросить историю FPS
- **F3**: Переключить полноэкранный режим

Отладочный оверлей показывает:
- FPS в реальном времени и историю FPS
- Текущую игру и состояние
- Позицию мыши
- Нажатые клавиши
- Статистику производительности

## 🎮 Управление

| Клавиша | Действие |
|:---:|:---|
| **Стрелки** | Движение во всех играх |
| **Пробел** | Пауза/Запуск |
| **ESC** | Выход/Назад |
| **F1** | Отладочный оверлей |
| **F2** | Сброс истории FPS |
| **F3** | Полноэкранный режим |

## ⚙️ Конфигурация

Игра использует систему конфигурации, которая сохраняет настройки в соответствующих директориях:

- **Windows**: `%LOCALAPPDATA%/hleserg/GameCollection/`
- **macOS**: `~/Library/Application Support/GameCollection/`
- **Linux**: `~/.local/share/GameCollection/`

### 📁 Файлы конфигурации

- `config.json`: Настройки игр, управление, аудио и уровни сложности
- `scores.json`: Рекорды для всех игр

### 🔧 Опции конфигурации

Конфигурация включает:

- **Дисплей**: Разрешение, полноэкранный режим, FPS
- **Управление**: Привязки клавиш для каждой игры
- **Настройки игр**: Скорость, размер сетки, жизни и т.д.
- **Аудио**: Уровни громкости и включение/выключение
- **Сложность**: Легкий, Обычный, Сложный пресеты

## 🏗️ Разработка

### 📁 Структура проекта

```
src/
├── game/
│   ├── __init__.py
│   ├── __main__.py          # Точка входа
│   ├── main.py              # Основной игровой цикл
│   ├── config.py            # Управление конфигурацией
│   ├── config.json          # Конфигурация по умолчанию
│   ├── games/               # Реализации игр
│   │   ├── base.py          # Базовый класс игры
│   │   ├── logic.py         # Чистые функции игровой логики
│   │   ├── snake.py         # Игра Змейка
│   │   ├── tetris.py        # Игра Тетрис
│   │   ├── arkanoid.py      # Игра Арканоид
│   │   └── pacman.py        # Игра Pac-Man
│   └── ui/                  # Пользовательский интерфейс
│       ├── menu.py          # Главное меню
│       └── scores.py        # Управление рекордами
tests/                       # Модульные тесты
docs/                        # Документация
```

### 🧪 Тестирование

Проект включает комплексные модульные тесты для всей игровой логики:

```bash
# Запуск всех тестов
python -m pytest tests/

# Запуск конкретного файла тестов
python -m pytest tests/test_tetris_logic.py

# Запуск с покрытием
python -m pytest tests/ --cov=src/game/games --cov-report=html
```

### 🔍 Качество кода

Проект использует современные инструменты Python:

- **Ruff**: Быстрый линтинг и форматирование
- **MyPy**: Статическая проверка типов
- **Pytest**: Фреймворк тестирования
- **Appdirs**: Платформо-специфичные директории данных

### 📦 Сборка исполняемых файлов

```bash
# Сборка с PyInstaller
python build_exe.py

# Или вручную
pyinstaller --onefile --windowed --name GameCollection src/game/__main__.py
```

## 📋 Требования

- Python 3.10+
- Pygame 2.5.0+
- Appdirs 1.4.4+ (для управления директориями данных)

### 🛠️ Требования для разработки

- Ruff 0.1.0+ (линтинг и форматирование)
- MyPy 1.8.0+ (проверка типов)
- Pytest 7.4.0+ (тестирование)
- PyInstaller 5.13.0+ (сборка исполняемых файлов)

## 🤝 Вклад в проект

1. Форкните репозиторий
2. Создайте ветку для функции
3. Внесите изменения
4. Запустите проверки качества: `python -m ruff check src/ && python -m mypy src/`
5. Отправьте pull request

## 📄 Лицензия

MIT License - см. файл [LICENSE](LICENSE) для подробностей.

## 📝 Журнал изменений

См. [CHANGELOG.md](CHANGELOG.md) для подробного списка изменений.

---

<div align="center">

**Сделано с ❤️ на Python и Pygame**

⭐ Поставьте звезду, если проект вам понравился!

</div>