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. Основные секции

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

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

{
  "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 г.