295 lines
11 KiB
Markdown
295 lines
11 KiB
Markdown
# 🏁 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
|
||
|