From 0a4c186a1cbb8f38dc927c2c9c2cae134912a696 Mon Sep 17 00:00:00 2001
From: DuckBug Coder <coder@duckbug.local>
Date: Sun, 14 Dec 2025 08:13:46 +0000
Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?=
 =?UTF-8?q?=D1=8C=20README=20=D1=81=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D0=BD?=
 =?UTF-8?q?=D0=B8=D0=B5=D0=BC=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0?=
 =?UTF-8?q?=20=D0=B8=20=D0=B8=D0=BD=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=86?=
 =?UTF-8?q?=D0=B8=D1=8F=D0=BC=D0=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..46da560
--- /dev/null
+++ b/README.md
@@ -0,0 +1,172 @@
+# Утка - Flappy Bird Clone
+
+Веб-игра в стиле Flappy Bird, разработанная на React и TypeScript. Цель игры - управлять уткой, избегая препятствий и набирая очки.
+
+## Описание
+
+Игра представляет собой классический клон Flappy Bird с улучшенной графикой, звуковыми эффектами и адаптивным дизайном. Игрок управляет уткой, которая должна пролетать между препятствиями, набирая очки за каждое успешно пройденное препятствие.
+
+## Технологии
+
+### Основные технологии:
+- **React 18+** - UI библиотека для создания компонентов
+- **TypeScript 5+** - Типизированный JavaScript для надежности кода
+- **Vite** - Современный сборщик для быстрой разработки
+- **Canvas API** - Рендеринг игровой графики и анимаций
+- **CSS Modules** - Стилизация компонентов
+
+### Инструменты разработки:
+- **ESLint** - Линтинг кода
+- **Prettier** - Форматирование кода
+- **Vitest** - Тестирование кода
+- **React Testing Library** - Тестирование компонентов
+
+## Установка
+
+1. Клонировать репозиторий:
+```bash
+git clone <repository-url>
+cd duck-game
+```
+
+2. Установить зависимости:
+```bash
+npm install
+```
+
+## Запуск
+
+### Режим разработки
+```bash
+npm run dev
+```
+Приложение будет доступно по адресу `http://localhost:5173`
+
+### Production сборка
+```bash
+npm run build
+```
+Собранные файлы будут находиться в директории `dist/`
+
+### Предпросмотр production сборки
+```bash
+npm run preview
+```
+
+## Управление
+
+- **Пробел** или **Стрелка вверх** - прыжок утки
+- **Клик мыши** или **Тап** - прыжок утки
+- **Escape** - пауза (во время игры)
+
+## Игровые механики
+
+- **Гравитация** - утка постоянно падает вниз
+- **Прыжок** - нажатие клавиши/клик поднимает утку вверх
+- **Препятствия** - нужно пролетать между верхней и нижней частями препятствий
+- **Очки** - начисляются за каждое успешно пройденное препятствие
+- **Прогрессивная сложность** - скорость препятствий увеличивается с ростом счета
+- **Лучший результат** - сохраняется в localStorage браузера
+
+## Архитектура проекта
+
+Проект использует компонентную архитектуру React с разделением на:
+
+- **Компоненты** - React компоненты для UI и игрового canvas
+- **Игровая логика** - классы и системы для игровых механик
+- **Контексты** - управление глобальным состоянием игры
+- **Хуки** - переиспользуемая логика (игровой цикл, клавиатура)
+- **Утилиты** - вспомогательные функции и константы
+
+## Структура проекта
+
+```
+src/
+├── components/          # React компоненты
+│   ├── Game/          # Основной игровой компонент
+│   │   ├── GameCanvas.tsx
+│   │   └── GameCanvas.module.css
+│   └── UI/            # UI компоненты (меню, кнопки)
+│       ├── MainMenu.tsx
+│       ├── PauseMenu.tsx
+│       ├── GameOverMenu.tsx
+│       └── PerformanceOverlay.tsx
+├── game/              # Игровая логика
+│   ├── entities/      # Игровые сущности (Утка, Препятствия)
+│   │   ├── Duck.ts
+│   │   └── Obstacle.ts
+│   ├── systems/       # Игровые системы
+│   │   ├── CollisionSystem.ts
+│   │   ├── ObstacleManager.ts
+│   │   ├── ScoreSystem.ts
+│   │   └── ParticleSystem.ts
+│   └── utils/         # Утилиты
+│       ├── constants.ts
+│       ├── SoundManager.ts
+│       ├── PerformanceMonitor.ts
+│       └── BrowserCompatibility.ts
+├── contexts/          # React контексты
+│   └── GameContext.tsx
+├── hooks/             # Кастомные React хуки
+│   ├── useGameLoop.ts
+│   └── useKeyboard.ts
+├── types/             # TypeScript типы
+│   └── game.types.ts
+└── assets/            # Ресурсы (звуки, изображения)
+    └── sounds/
+```
+
+## Тестирование
+
+### Запуск тестов
+```bash
+npm test
+```
+
+### Запуск тестов с UI
+```bash
+npm run test:ui
+```
+
+### Запуск тестов один раз
+```bash
+npm run test:run
+```
+
+Тесты покрывают:
+- Игровые сущности (Duck, Obstacle)
+- Игровые системы (CollisionSystem, ObstacleManager, ScoreSystem)
+- Контекст игры (GameContext)
+
+## Разработка
+
+### Линтинг
+```bash
+npm run lint
+```
+
+### Форматирование кода
+```bash
+npm run format
+```
+
+## Особенности реализации
+
+- **Оптимизация производительности**: отрисовка только видимых объектов, кэширование границ объектов
+- **Адаптивность**: автоматическое масштабирование canvas для разных размеров экрана
+- **Звуковые эффекты**: система управления звуками с возможностью включения/выключения
+- **Система частиц**: визуальные эффекты при столкновениях
+- **Мониторинг производительности**: отображение FPS и использования памяти в режиме разработки
+- **Прогрессивная сложность**: увеличение скорости препятствий с ростом счета
+
+## Браузерная совместимость
+
+Игра протестирована и работает в:
+- Chrome/Edge (последние версии)
+- Firefox (последние версии)
+- Safari (последние версии)
+- Мобильные браузеры (iOS Safari, Android Chrome)
+
+## Лицензия
+
+Проект создан в образовательных целях.