init

MAP-FORMAT.md

@@ -0,0 +1,126 @@
+# Формат карт для Paper Racing A*
+
+## Обзор
+
+Программа поддерживает загрузку карт из JSON-файлов. Это позволяет создавать собственные треки любой сложности.
+
+## Использование
+
+### Запуск со встроенной картой
+```bash
+dotnet run --project racing-astar.csproj
+```
+
+### Запуск с картой из файла
+```bash
+dotnet run --project racing-astar.csproj maps/your-map.json
+```
+
+или через скомпилированный бинарник:
+```bash
+./bin/Debug/net8.0/racing-astar maps/your-map.json
+```
+
+## Формат 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`
+
+```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. **Тестирование**: Используйте встроенные примеры для понимания того, какие карты решаются быстро:
+   ```bash
+   dotnet run --project racing-astar.csproj maps/open-field.json
+   ```
+
+## Ограничения
+
+- **Максимум итераций**: По умолчанию алгоритм ограничен 5,000,000 итераций
+- **Память**: Сложные карты с большим количеством чекпоинтов требуют значительной памяти
+- **Время**: Карты с более чем 10 чекпоинтами могут требовать длительного времени решения
+
+## Технические детали
+
+### Алгоритм A*
+Программа использует алгоритм A* с эвристикой на основе:
+- Евклидова расстояния до чекпоинтов
+- Текущей скорости движения
+- Упрощенной модели физики ускорения
+
+### Ключ состояния
+Каждое уникальное состояние определяется комбинацией:
+- Позиция (X, Y)
+- Скорость (VX, VY)
+- Набор посещенных чекпоинтов
+
+Это позволяет алгоритму эффективно отслеживать уже исследованные состояния и избегать повторной обработки.
+