# 🏁 Racing Tools - Инструменты для "Гонки на бумаге"

Веб-приложения для создания карт и визуализации решений. Работают без сервера, просто откройте в браузере.

## 📦 Что внутри

Два веб-приложения в одном проекте:

- **🏁 Редактор карт** (`editor.html`) - создание и редактирование игровых карт
- **🎬 Визуализатор решений** (`player.html`) - анимация траекторий движения

## 🚀 Быстрый старт

### Вариант 1: Через скрипты
```bash
# Редактор карт
./open-editor.sh

# Визуализатор решений
./open-player.sh
```

### Вариант 2: Напрямую в браузере
```bash
firefox editor.html  # Редактор карт
firefox player.html  # Визуализатор решений
```

### Вариант 3: Через Python HTTP сервер
```bash
python3 -m http.server 8000
# Откройте http://localhost:8000/editor.html или http://localhost:8000/player.html
```

## 🏁 Редактор карт

### Возможности
- Создание карт размером от 5×5 до 100×100
- Интуитивное рисование мышью (клик или удержание)
- 6 типов ячеек: дорога, камень, снег, лёд, чекпоинт, старт
- Экспорт/импорт в JSON формате
- Изменение размера с сохранением данных

### Типы ячеек

| Код | Тип | Описание | Цвет | Маркер |
|-----|-----|----------|------|--------|
| 0 | Дорога | Обычная дорога | Светло-серый | - |
| 1 | Камень | Препятствие (непроходимо) | Тёмно-серый | - |
| 2 | Снег | Замедление движения | Голубой | - |
| 3 | Лёд | Скользкая поверхность | Светло-голубой | - |
| 4 | Чекпоинт | Контрольная точка | Жёлтый | C |
| 5 | Старт | Точка старта (обязательно!) | Зелёный | S |

### Быстрый старт редактора

1. Откройте `editor.html`
2. Установите размеры (по умолчанию 15×15)
3. Выберите тип ячейки из палитры
4. Рисуйте мышью на карте (обязательно добавьте точку старта - тип 5)
5. Нажмите "Экспорт JSON" - файл скачается автоматически

## 🎬 Визуализатор решений

### Возможности
- Загрузка карты и решения из JSON
- Пошаговая анимация траектории
- Контроль скорости воспроизведения (1x - 10x)
- Ручное управление (шаг вперед/назад)
- Отображение позиции, скорости и ускорения

### Элементы визуализации

- 🔵 **Синяя линия и точки** - пройденная траектория
- 🔴 **Красный круг** - текущая позиция
- ➡️ **Красная стрелка** - вектор скорости (направление и величина)
- **Панель информации** - шаг, позиция (x, y), скорость (vx, vy), ускорение (ax, ay)

### Управление

| Кнопка | Действие |
|--------|----------|
| ▶ Play | Автоматическое воспроизведение |
| ⏸ Pause | Пауза |
| ⏮ Reset | Сброс к началу |
| ⏪ Back | Шаг назад |
| ⏩ Forward | Шаг вперед |
| Слайдер | Скорость 1x - 10x |

### Быстрый старт визуализатора

1. Откройте `player.html`
2. Загрузите карту (📂 Загрузить карту)
3. Загрузите решение (🎬 Загрузить решение)
4. Нажмите ▶ Play и наблюдайте за движением

## 📄 Форматы файлов

### Формат карты (map)

```json
{
  "map": [
    [5, 0, 0, 1, 0],
    [0, 1, 0, 1, 0],
    [0, 0, 2, 2, 4]
  ]
}
```

**Структура:**
- `map` - двумерный массив целых чисел (int[][])
- Первая строка = верхняя строка карты
- Первый элемент в строке = левая ячейка
- Значения: 0-5 (типы ячеек)
- **Обязательно наличие точки старта (5)**

### Формат решения (solution)

```json
{
  "solution": [
    [1, 1],
    [1, 0],
    [0, 1],
    [-1, 0]
  ]
}
```

**Структура:**
- `solution` - массив векторов ускорения `[[ax, ay], ...]`
- `ax`, `ay` - целые числа (обычно от -1 до 1)
- Каждый элемент = одно действие игрока

### Физика движения

На каждом шаге применяется:
```
velocity += acceleration
position += velocity
```

**Пример:**
```
Шаг 0: pos=(0,0), vel=(0,0)
Шаг 1: acc=(1,1) → vel=(1,1) → pos=(1,1)
Шаг 2: acc=(1,0) → vel=(2,1) → pos=(3,2)
Шаг 3: acc=(0,0) → vel=(2,1) → pos=(5,3)
```

## 🔗 Интеграция с C#

### Чтение карты
```csharp
using System.Text.Json;

var json = File.ReadAllText("racing-map-15x15.json");
var mapData = JsonSerializer.Deserialize<MapData>(json);
int[][] map = mapData.map;

public class MapData
{
    public int[][] map { get; set; }
}
```

### Запись решения
```csharp
var solution = new { solution = new int[][] { 
    new[] { 1, 1 }, 
    new[] { 1, 0 }, 
    new[] { 0, 1 } 
}};

var json = JsonSerializer.Serialize(solution, new JsonSerializerOptions 
{ 
    WriteIndented = true 
});

File.WriteAllText("solution.json", json);
```

## 🎯 Структура проекта

```
racing-tools/
├── editor.html              # Страница редактора карт
├── player.html              # Страница визуализатора решений
├── styles.css               # Общие стили для обоих приложений
├── common.js                # Общие функции и константы
├── editor.js                # Логика редактора
├── player.js                # Логика визуализатора
├── open-editor.sh           # Скрипт запуска редактора
├── open-player.sh           # Скрипт запуска визуализатора
├── demo-with-start.json     # Демо-карта 15×15
├── demo-with-start-solution.json  # Демо-решение
└── README.md                # Этот файл
```

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

### Технологии
- **HTML5** - структура страниц
- **CSS3** - современный градиентный дизайн
- **JavaScript (ES6+)** - вся логика на клиенте
- **Canvas API** - отрисовка карт и визуализация

### Особенности
- ✅ Работает без сервера (статические файлы)
- ✅ Валидация данных при импорте
- ✅ Адаптивная сетка интерфейса
- ✅ Общий CSS и JS для уменьшения дублирования
- ✅ Модульная архитектура (common.js для общего кода)
- ✅ Навигация между страницами
- ✅ Визуальная обратная связь (анимации, подсветка)

### Зависимости
- Нет внешних зависимостей
- Чистый Vanilla JavaScript
- Работает в любом современном браузере

## 🧪 Быстрый тест

### Тест редактора
1. Откройте `editor.html`
2. Нарисуйте простую карту с точкой старта
3. Экспортируйте в JSON
4. Импортируйте обратно - данные должны сохраниться

### Тест визуализатора
1. Откройте `player.html`
2. Загрузите `demo-with-start.json`
3. Загрузите `demo-with-start-solution.json`
4. Нажмите ▶ Play и экспериментируйте с кнопками и скоростью

## 📚 Примеры использования

### Создание карты с чекпоинтами
1. Создайте дорогу (тип 0) в виде трассы
2. Добавьте препятствия (тип 1) по краям
3. Разместите чекпоинты (тип 4) вдоль трассы
4. Обозначьте старт (тип 5) в начале
5. Экспортируйте и используйте в решателе

### Визуализация решения A*
1. Запустите C# решатель, получите JSON с решением
2. Откройте визуализатор
3. Загрузите карту и решение
4. Наблюдайте за оптимальным путем

## 🔗 Связанные проекты

- [Основной проект C#](../README.md) - решатель на основе A*
- [Примеры карт](../maps/) - коллекция готовых карт
- [Документация формата](../MAP-FORMAT.md) - подробное описание формата

## 🤝 Советы и трюки

### Редактор
- Используйте Enter в полях размера для быстрого применения
- Удерживайте мышь для быстрого рисования линий
- JSON также выводится в консоль (F12) для быстрого копирования
- При изменении размера существующие данные сохраняются

### Визуализатор
- Используйте пошаговый режим для детального анализа
- Скорость 1x подходит для медленного разбора
- Скорость 10x для быстрого просмотра длинных решений
- Можно загрузить новое решение без перезагрузки карты

## 🐛 Решение проблем

**Карта не загружается?**
- Проверьте формат JSON
- Убедитесь, что все значения от 0 до 5
- Размеры должны быть от 5×5 до 100×100

**Решение не работает?**
- Убедитесь, что на карте есть точка старта (5)
- Проверьте формат: массив массивов [[ax, ay], ...]
- Сначала загрузите карту, потом решение

**Визуализация странная?**
- Возможно, решение выходит за границы карты
- Проверьте корректность векторов ускорений

---

**Версия:** 2.0 (Объединенная)  
**Дата:** 2025  
**Лицензия:** MIT  
**Автор:** Racing Team