mnemo_cards/games/apps/bus_word_game/README.md

🚌 Bus Word Game

📖 Описание проекта

Bus Word Game - это веб-игра на Flutter с использованием движка Flame, где игрок управляет автобусом Volkswagen T1, который должен ловить предметы, соответствующие слову, отображающемуся на экране. Игрок должен перепрыгивать через ловушки и избегать неподходящих предметов.

🏗️ Архитектура проекта

🎮 Основные компоненты

BusWordGame (lib/game/bus_word_game.dart)

• Главный игровой класс, наследующий от FlameGame
• Управляет игровым циклом и всеми компонентами
• Обрабатывает пользовательский ввод (клики, клавиатура)
• Управляет генерацией препятствий, платформ и сменой слов
• Включает систему паузы и окончания игры

GameState (lib/game/game_state.dart)

• Центральное хранилище состояния игры
• Управляет счетом, уровнем, текущим словом
• Содержит логику генерации слов и препятствий
• Отслеживает состояние паузы и окончания игры

🎨 Игровые компоненты

BusComponent (lib/game/components/bus_component.dart)

• Приоритет: 1000 (поверх всех игровых объектов)
• Управляет автобусом с физикой (гравитация, прыжки)
• Анимации: растяжение вверх при прыжке, сжатие вниз при приземлении
• Состояния: на земле, на платформе, в воздухе
• Коллизии: с платформами и землей
• Отладка: визуальные индикаторы состояния

PlatformComponent (lib/game/components/platform_component.dart)

• Приоритет: 100 (средний уровень)
• Платформы из тайлов (left.png, middle.png, right.png)
• Размеры: 3-5 тайлов в ширину (192-320px)
• Высота: 15-25px
• Движение: прокрутка влево с разной скоростью
• Коллизии: определение нахождения автобуса

TileGroundComponent (lib/game/components/tile_ground_component.dart)

• Приоритет: -1000 (фон)
• Многослойная земля из тайлов
• Прокрутка: непрерывная анимация движения
• Слои: небо (градиент), земля (тайлы), дорога (линии)
• Методы: getGroundY(), getRoadY()

BackgroundWordComponent (lib/game/components/background_word_component.dart)

• Приоритет: -500 (между фоном и игровыми объектами)
• Большое целевое слово на фоне неба
• Размер: 120px шрифт для слова, 24px для подписи
• Цвет: очень прозрачный белый с тенями
• Позиция: по центру экрана
• Обновление: синхронизировано с UI при смене слова

PlatformComponent (lib/game/components/platform_component.dart)

• Приоритет: 100 (средний уровень)
• Платформы из тайлов (left.png, middle.png, right.png)
• Размеры: 3-5 тайлов в ширину (192-320px)
• Высота: 15-25px
• Движение: прокрутка влево с разной скоростью
• Коллизии: определение нахождения автобуса

UIComponent (lib/game/components/ui_component.dart)

• Приоритет: 2000 (поверх игровых объектов)
• Отображает текущее слово и счет
• Элементы: "ЛОВИ:", слово, "ОЧКИ:", счет
• Позиционирование: верхняя часть экрана
• Обновление: динамическое изменение текста

DebugComponent (lib/game/components/debug_component.dart)

• Приоритет: 3000 (самый высокий)
• Отладочная информация в реальном времени
• Данные: состояние игры, позиции, FPS, количество объектов
• Обновление: каждые 0.5 секунды
• Визуал: полупрозрачный фон с контуром

🛠️ Технический стек

Основные технологии

• Flutter: 3.x - фреймворк для веб-приложений
• Flame: 1.16.0 - игровой движок для Flutter
• Dart: язык программирования

Дополнительные пакеты

• audioplayers: 5.2.1 - воспроизведение звуков
• shared_preferences: 2.2.2 - сохранение настроек

Архитектурные паттерны

• Component-based Architecture: все игровые объекты - компоненты
• State Management: централизованное управление состоянием
• Event-driven: обработка событий пользователя
• Timer-based: генерация объектов по времени

🎯 Игровая механика

Управление

• Клик/Пробел: прыжок автобуса
• ESC: пауза/возобновление игры

Физика автобуса

• Гравитация: 700 пикселей/сек²
• Скорость прыжка: -600 пикселей/сек
• Состояния: на земле, на платформе, в воздухе
• Коллизии: AABB (Axis-Aligned Bounding Box)

Анимации автобуса

• Растяжение при прыжке: до 1.3x по высоте, 0.15 сек
• Сжатие при приземлении: до 0.8x по высоте, 0.15 сек
• Кривые анимации: быстрое начало, медленное завершение

Платформы

• Генерация: каждые 2 секунды
• Высота: 180-400px от земли
• Стратегии: низкие, средние, высокие, случайные
• Тайлы: 3-5 тайлов в ширину

Система очков

• Правильный предмет: +10 очков
• Неправильный предмет: -5 очков
• Ловушка: игра окончена

🎨 Визуальные элементы

Приоритеты отрисовки (Z-Index)

-1000: Земля/фон (TileGroundComponent)
-500:  Фоновое слово (BackgroundWordComponent)
100:   Платформы (PlatformComponent)
1000:  Автобус (BusComponent)
2000:  UI (UIComponent)
3000:  Отладка (DebugComponent)

Цветовая схема

• Небо: градиент голубых оттенков
• Земля: коричневые тайлы
• Дорога: серый с белыми линиями
• Платформы: тайлы с коричневыми оттенками
• UI: зеленые и синие акценты

Тайлы

• Земля: assets/images/tiles/full/top_middle.png
• Платформы: assets/images/tiles/floating_platform/left.png, middle.png, right.png

🐛 Система отладки

Логирование

• dart:developer: подробные логи всех компонентов
• Категории: загрузка, физика, коллизии, анимации
• Визуальные индикаторы: цветные кружки состояния автобуса

Отладочная информация

• Состояние игры и автобуса
• Позиции и скорости объектов
• Количество препятствий и платформ
• FPS и производительность

🚀 Запуск проекта

Предварительные требования

• Flutter SDK 3.x
• Dart SDK
• Веб-браузер

Установка зависимостей

cd apps/bus_word_game
flutter pub get

Запуск в режиме разработки

flutter run -d web-server --web-port 8080

Сборка для продакшена

flutter build web

📁 Структура файлов

apps/bus_word_game/
├── lib/
│   ├── main.dart                 # Точка входа приложения
│   ├── screens/
│   │   ├── menu_screen.dart      # Главное меню
│   │   └── game_screen.dart      # Игровой экран
│   ├── game/
│   │   ├── bus_word_game.dart    # Главный игровой класс
│   │   ├── game_state.dart       # Состояние игры
│   │   └── components/
│   │       ├── bus_component.dart        # Автобус
│   │       ├── platform_component.dart   # Платформы
│   │       ├── tile_ground_component.dart # Земля
│   │       ├── background_word_component.dart # Фоновое слово
│   │       ├── ui_component.dart         # Пользовательский интерфейс
│   │       ├── debug_component.dart      # Отладка
│   │       └── obstacle_component.dart   # Препятствия
│   └── assets/
│       ├── images/
│       │   ├── bus.png                   # Спрайт автобуса
│       │   └── tiles/
│       │       ├── full/                 # Тайлы земли
│       │       └── floating_platform/    # Тайлы платформ
│       ├── audio/                        # Звуковые эффекты
│       └── data/                         # Данные игры
├── pubspec.yaml                  # Зависимости и ресурсы
└── README.md                     # Документация

🔧 Конфигурация

Параметры игры (bus_word_game.dart)

static const double gameSpeed = 200.0;
static const double obstacleSpawnInterval = 2.0;
static const double wordChangeInterval = 10.0;
static const double platformSpawnInterval = 2.0;

Физика автобуса (bus_component.dart)

double gravity = 700.0;
double velocityY = -600.0; // Скорость прыжка
double animationDuration = 0.15; // Длительность анимации

🎮 Геймплей

Цель игры

Ловить предметы, соответствующие отображаемому слову, избегая ловушек и неподходящих предметов.

Управление

• Прыжок: клик мышью или пробел
• Пауза: клавиша ESC
• Платформы: прыгайте на них для достижения высоты

Механики

• Физика: реалистичная гравитация и движение
• Анимации: визуальная обратная связь
• Коллизии: точное определение столкновений
• Прогрессия: увеличение сложности со временем

🔮 Планы развития

Краткосрочные цели

• Добавление звуковых эффектов
• Система сохранения рекордов
• Настройки игры
• Мобильная версия

Среднесрочные цели

• Новые типы препятствий
• Система бонусов
• Множественные уровни
• Мультиплеер

Долгосрочные цели

• 3D графика
• ИИ противников
• Социальные функции
• Монетизация

👨‍💻 Руководство разработчика

Добавление нового компонента

1. Создайте класс, наследующий от PositionComponent
2. Реализуйте методы onLoad(), update(), render()
3. Установите правильный priority
4. Добавьте в BusWordGame.onLoad()

Отладка

• Используйте developer.log() для логирования
• Включите DebugComponent для визуальной отладки
• Проверяйте консоль браузера (F12)

Производительность

• Оптимизируйте количество объектов на экране
• Используйте пулы объектов для часто создаваемых элементов
• Мониторьте FPS через отладочную информацию

📝 Лицензия

Проект разработан для образовательных целей. Используйте код свободно для изучения и создания собственных игр.

🤝 Вклад в проект

Приветствуются предложения по улучшению игры! Создавайте issues и pull requests для:

• Исправления багов
• Добавления новых функций
• Улучшения производительности
• Обновления документации

---

Автор: AI Assistant
Версия: 2.0
Дата обновления: 2024