🏎️ AI Racing Simulator (Unity ML-Agents)

3D-симулятор автогонок, в котором автомобили управляются нейросетевыми агентами, обученными с помощью методов обучения с подкреплением (Reinforcement Learning). Игрок может соревноваться с ИИ на различных трассах, а также самостоятельно настраивать и запускать процесс обучения новых агентов прямо из игры.

✨ Ключевые особенности

• Нейросетевые противники (ML-Agents): Боты используют алгоритм SAC (Soft Actor-Critic) и непрерывное пространство действий (Continuous Actions) для плавного управления газом, тормозом и рулём.
• Продвинутая физика: Реалистичное поведение автомобилей, дрифт и подвеска на базе Prometeo Car Controller.
• Модульные трассы: Трассы построены с использованием Unity Splines, что позволяет легко менять геометрию, при этом ИИ автоматически адаптируется к новому маршруту.
• Современный UI (UI Toolkit): Адаптивное главное меню, настройки графики/звука, меню паузы и экраны результатов гонки.
• Встроенный конфигуратор обучения: Возможность настраивать гиперпараметры нейросети (Batch Size, Learning Rate, Time Horizon и др.) прямо в UI игры. Игра сама генерирует файл car.yaml для ML-Agents.
• Динамическая музыка: Бесшовное переключение фоновой музыки между меню и гонкой с помощью паттерна Singleton (DontDestroyOnLoad).

🏗️ Архитектура и технологии

• Движок: Unity 6 (6000.3.6f1)
• Машинное обучение: Unity ML-Agents (Release 20+)
• Интерфейс: Unity UI Toolkit (UXML / USS)
• Физика авто: Prometeo Car Controller
• Система трасс: Unity Splines

Как работает ИИ (CarAgent.cs)

Агент получает следующие наблюдения (Observations):

1. Текущая скорость (нормализованная).
2. Боковое скольжение и флаг дрифта.
3. Выравнивание относительно вектора трассы.
4. Боковое смещение от центра трассы.
5. Прогресс прохождения трассы (от 0 до 1).
6. 3D Ray Perception Sensor (Лидары для обнаружения стен).

Система наград: Агент получает награду за продвижение вперёд по сплайну. Чем выше скорость, тем больше множитель награды. Штрафы выдаются за столкновение со стенами, езду задним ходом и простой на месте.

🚀 Инструкция по запуску и установке

Требования

• Unity: Версия 6000.3.6f1 (или совместимая).
• Python: Версия 3.9 - 3.10 (необходим только если вы собираетесь обучать ИИ).

Установка проекта

1. Склонируйте репозиторий:

   git clone https://github.com/YOUR_USERNAME/ML-Race.git

2. Откройте проект в Unity Hub.
3. Дождитесь импорта всех ассетов и пакетов (ML-Agents, UI Toolkit, Splines).
4. Откройте сцену Assets/Scenes/MenuScene.unity.
5. Нажмите Play!

🎮 Как играть

Режим Гонки (Race)

1. В главном меню выберите вкладку Гонка.
2. Выберите трассу, количество кругов и количество ИИ-соперников.
3. Нажмите Старт.
4. Управление: W/A/S/D или Стрелки — движение, Space — ручной тормоз, Esc — пауза.
5. Цель: Проехать заданное количество кругов быстрее ботов.

Режим Обучения (Training)

1. В главном меню выберите вкладку Обучение.
2. Настройте гиперпараметры (количество агентов, шагов, Learning Rate и т.д.).
3. Нажмите Начать обучение. Игра сгенерирует файл Assets/StreamingAssets/car.yaml и загрузит тренировочную сцену.
4. Откройте терминал (командную строку) в папке проекта и активируйте ваше Python-окружение с установленным mlagents.
5. Запустите процесс обучения командой:

   mlagents-learn Assets/StreamingAssets/car.yaml --run-id=CarRace_01

6. Нажмите Play в редакторе Unity, чтобы начать симуляцию.
7. После завершения обучения готовая модель (.nnmodel или .onnx) появится в папке results/CarRace_01/. Переместите её в Assets/Resources/Models/car для использования в гонке.

🛠️ Структура проекта

• Assets/Scripts/ — Исходный код (C#).
• Assets/Scenes/ — Игровые сцены (Меню, Гонки, Тренировка).
• Assets/UI/ и Assets/Resources/UI/ — Файлы вёрстки и стилей интерфейса (UXML/USS).
• Assets/Resources/Models/ — Обученные модели нейросетей.
• Assets/StreamingAssets/ — Сгенерированные конфигурации для ML-Agents.

---

Разработано в рамках изучения Reinforcement Learning и Unity ML-Agents.