paper-racing-gpi/MAP-FORMAT.md

Формат карт для Paper Racing A*

Обзор

Программа поддерживает загрузку карт из JSON-файлов. Это позволяет создавать собственные треки любой сложности.

Использование

Запуск со встроенной картой

dotnet run --project racing-astar.csproj

Запуск с картой из файла

dotnet run --project racing-astar.csproj maps/your-map.json

или через скомпилированный бинарник:

./bin/Debug/net8.0/racing-astar maps/your-map.json

Формат JSON

Карта представляет собой JSON-файл со следующей структурой:

{
  "map": [
    [0, 0, 0, 0, 0],
    [0, 1, 4, 1, 0],
    [0, 0, 0, 0, 0]
  ]
}

Типы ячеек

Код	Тип	Описание	Поведение
0	Дорога	Обычная проходимая ячейка	Первая найденная становится стартом (если нет типа 5). Ускорение ±2
1	Камень	Препятствие	Можно проезжать, нельзя останавливаться
2	Снег	Скользкая поверхность	Ограниченное маневрирование, ускорение ±1
3	Лед	Очень скользкая поверхность	Инерция, ускорение нельзя менять
4	Чекпоинт	Контрольная точка	Должна быть посещена
5	Старт	Явная стартовая позиция	Приоритет над типом 0, ускорение ±2

Особенности

1. Стартовая позиция:

   • Если на карте есть ячейка типа 5 (Старт), она становится стартовой позицией
   • Если нет типа 5, то автоматически определяется как первая ячейка типа 0 (дорога), найденная при сканировании карты слева направо, сверху вниз

2. Чекпоинты: Все ячейки с типом 4 автоматически становятся чекпоинтами. Нумерация чекпоинтов идет по порядку их обнаружения (слева направо, сверху вниз).

3. Система координат:

   • JSON-карта описывается сверху вниз (первая строка массива = верх карты)
   • Визуализация отображает карту в правильной ориентации (Y растет вверх)

4. Физика движения: Алгоритм учитывает инерцию - машинка не может мгновенно остановиться или изменить направление. Ускорение на каждом шаге ограничено диапазоном [-2, +2] по каждой оси.

Примеры карт

Простая открытая карта (3 чекпоинта)

Файл: maps/open-field.json

{
  "map": [
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 4, 0, 0, 0, 0, 4, 0, 0, 0, 0, 4, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
  ]
}

Сложная карта с препятствиями (59 чекпоинтов)

Файл: maps/racing-map-42x42.json

Карта размером 42x42 с многочисленными препятствиями и 59 чекпоинтами. Требует значительно больше времени для поиска решения.

Советы по созданию карт

1. Начните с малого: Создайте небольшую карту (10x10 - 20x20) для тестирования.

2. Учитывайте инерцию: Оставляйте достаточно пространства для маневрирования. Машинка не может мгновенно остановиться.

3. Не переусердствуйте с чекпоинтами: Сложность растет экспоненциально с количеством чекпоинтов. Начните с 2-5 чекпоинтов.

4. Открытые пространства: Карты с большим количеством открытого пространства решаются быстрее.

5. Тестирование: Используйте встроенные примеры для понимания того, какие карты решаются быстро:

   dotnet run --project racing-astar.csproj maps/open-field.json
   

Ограничения

• Максимум итераций: По умолчанию алгоритм ограничен 5,000,000 итераций
• Память: Сложные карты с большим количеством чекпоинтов требуют значительной памяти
• Время: Карты с более чем 10 чекпоинтами могут требовать длительного времени решения

Технические детали

Алгоритм A*

Программа использует алгоритм A* с эвристикой на основе:

• Евклидова расстояния до чекпоинтов
• Текущей скорости движения
• Упрощенной модели физики ускорения

Ключ состояния

Каждое уникальное состояние определяется комбинацией:

• Позиция (X, Y)
• Скорость (VX, VY)
• Набор посещенных чекпоинтов

Это позволяет алгоритму эффективно отслеживать уже исследованные состояния и избегать повторной обработки.