LoParkour/docs/sd.md

# Спецификация формата LoParkour Schematic (.lpschem)

## 1. Общее описание

**LoParkour Schematic** — это легковесный, расширяемый формат на базе JSON, предназначенный для хранения паркур-уровней в Minecraft. Формат оптимизирован для быстрой загрузки, сетевой передачи (для онлайн-редакторов) и поддержки современных визуальных элементов (Block Displays).

### Основные характеристики
- **Расширение:** `.lpschem`
- **Кодировка:** UTF-8
- **Сжатие:** GZIP (стандарт Java `GZIPOutputStream`)
- **Версия формата:** 2.0

---

## 2. Структура файла

### 2.1. Основные секции

```json
{
  "format_version": 2,
  "metadata": { ... },
  "dimensions": { ... },
  "palette": [ ... ],
  "blocks": [ ... ],
  "markers": { ... },
  "visuals": { ... },
  "logic": { ... }
}
```

### 2.2. Пример полного файла

```json
{
  "format_version": 2,
  "metadata": {
    "name": "Neon City Rush",
    "author": "Loki",
    "difficulty": 0.65,
    "tags": ["urban", "hard", "neon"]
  },
  "dimensions": {
    "width": 10,
    "height": 8,
    "length": 10
  },
  "palette": [
    "minecraft:air",
    "minecraft:black_concrete",
    "minecraft:cyan_stained_glass",
    "minecraft:oak_stairs[facing=north,half=bottom]"
  ],
  "blocks": [0, 1, 1, 2, 0, 3],
  "markers": {
    "start": {"x": 1, "y": 1, "z": 1},
    "end": {"x": 9, "y": 7, "z": 9},
    "checkpoints": [{"x": 5, "y": 4, "z": 5}]
  },
  "visuals": {
    "displays": [
      {
        "type": "block",
        "block": "minecraft:gold_block",
        "pos": [5.5, 2.0, 5.5],
        "scale": [0.8, 0.8, 0.8],
        "animation": {"type": "rotate", "axis": "y", "speed": 1.5}
      }
    ],
    "particles": [
      {"type": "end_rod", "pos": [5.0, 3.0, 5.0], "amount": 5, "spread": 0.2}
    ]
  },
  "logic": {
    "ghost_path": [[1,1,1], [2,1,3], [4,2,5]]
  }
}
```

---

## 3. Детальное описание полей

### 3.1. metadata (обязательное)
Метаданные схематики.

| Поле | Тип | Описание |
|------|-----|----------|
| `name` | string | Название уровня |
| `author` | string | Автор |
| `difficulty` | float | Сложность (0.0 - 1.0) |
| `tags` | string[] | Метки для поиска |

### 3.2. dimensions (обязательное)
Размеры уровня.

| Поле | Тип | Описание |
|------|-----|----------|
| `width` | int | Ширина по оси X |
| `height` | int | Высота по оси Y |
| `length` | int | Длина по оси Z |

### 3.3. palette (обязательное)
Уникальный список используемых блоков. Индекс `0` всегда зарезервирован за `minecraft:air`.

### 3.4. blocks (обязательное)
Одномерный массив индексов блоков. Размер: `width × height × length`.

Формула индекса:  
`index = x + (z × width) + (y × width × length)`

### 3.5. markers (обязательное)
Ключевые точки уровня.

| Поле | Тип | Описание |
|------|-----|----------|
| `start` | object | Координаты старта |
| `end` | object | Координаты финиша |
| `checkpoints` | object[] | Массив чекпоинтов |

Каждая точка содержит поля `x`, `y`, `z`.

### 3.6. visuals (опциональное)
Визуальные эффекты.

#### 3.6.1. displays (BlockDisplay)
Сущности для декораций в воздухе.

| Поле | Тип | Описание |
|------|-----|----------|
| `type` | string | Тип дисплея (`block`) |
| `block` | string | Блок для отображения |
| `pos` | float[3] | Позиция (x, y, z) |
| `scale` | float[3] | Масштаб (x, y, z) |
| `animation` | object | Анимация (опционально) |

Анимация:
| Поле | Тип | Описание |
|------|-----|----------|
| `type` | string | Тип (`rotate`) |
| `axis` | string | Ось вращения (`x`, `y`, `z`) |
| `speed` | float | Скорость вращения |

#### 3.6.2. particles (опциональное)
Точки спавна частиц.

| Поле | Тип | Описание |
|------|-----|----------|
| `type` | string | Тип частиц |
| `pos` | float[3] | Позиция |
| `amount` | int | Количество частиц |
| `spread` | float | Рассеивание |

### 3.7. logic (опциональное)
Логические данные уровня.

| Поле | Тип | Описание |
|------|-----|----------|
| `ghost_path` | int[][] | Путь призрака (массив координат) |

---

## 4. Алгоритмы и оптимизация

### 4.1. Palette Encoding
Вместо хранения полных строк `BlockData` для каждого блока используется уникальный список в `palette`. В `blocks` хранятся только числовые индексы.

**Результат:** Сокращение размера файла в 5-10 раз для повторяющихся структур.

### 4.2. 1D Array Flattening
Одномерный массив обеспечивает быстрый доступ к блокам без вложенных объектов.

### 4.3. Sparse Storage
Индекс `0` всегда зарезервирован за `minecraft:air`. При загрузке блоки воздуха можно игнорировать, что ускоряет вставку.

---

## 5. Визуальные эффекты (Killer Features)

### 5.1. Block Displays
- Висят в воздухе (не по сетке блоков)
- Любого размера (scale)
- Плавное вращение/движение без модов

### 5.2. Частицы
Один асинхронный поток для обработки всех эффектов активных уровней.

---

## 6. Онлайн-редактор (Web Concept)

### Технологии
- **Frontend:** Three.js или React-Three-Fiber
- **Asset Loading:** Текстуры блоков из Minecraft Assets
- **Интерфейс:** Рисование блоков, расстановка чекпоинтов, предпросмотр анимаций

---

## 7. Техника безопасности

| Проблема | Решение |
|----------|---------|
| Несовместимость версий | Проверять `format_version`, уведомлять об обновлении |
| Missing Blocks | Заменять на `MAGENTA_GLAZED_TERRACOTTA` |
| Entity Leak | Хранить UUID дисплеев, удалять при выгрузке |
| Lag Spikes | Лимитировать `visuals` (макс. 50 дисплеев на уровень) |

---

## 8. План реализации (Roadmap)

1. [ ] Создать класс `LPSchematic` с поддержкой `GSON`
2. [ ] Написать `PaletteManager` для автоматической сборки уникальных блоков
3. [ ] Реализовать вставку блоков через `EditSession` или Bukkit API
4. [ ] Добавить поддержку `BlockDisplay` через пакеты (1.19.4+)
5. [ ] Написать конвертер из старого `.dat` / Java Serialization формата

---

*Документация подготовлена для проекта LoParkour. 2026 г.*