paper-racing-gpi/racing-tools

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

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

📦 Что внутри

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

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

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

Вариант 1: Через скрипты

# Редактор карт
./open-editor.sh

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

Вариант 2: Напрямую в браузере

firefox editor.html  # Редактор карт
firefox player.html  # Визуализатор решений

Вариант 3: Через Python HTTP сервер

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)

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

Структура:

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

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

{
  "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#

Чтение карты

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; }
}

Запись решения

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# - решатель на основе A*
• Примеры карт - коллекция готовых карт
• Документация формата - подробное описание формата

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

Редактор

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

Визуализатор

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

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

Карта не загружается?

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

Решение не работает?

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

Визуализация странная?

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

---

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