# Формат карт для 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)
- Набор посещенных чекпоинтов

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