ExbyteLabs/vertical-partition-system-plugin

Files

Bonchellon 04ad6d3f25 Initial commit: Vertical Partition Streaming plugin (UE 5.7)

Bounded vertical route partition / streaming for handcrafted spiral climb maps
(Only Up / Only Climb). Not World Partition, not Level Instances as core arch.

- Z-cell segmentation + optional XY subcells, editor builder + commandlet
- NonDestructive visibility backend + streaming-level backend
- Offline HLOD proxies: MergedMesh / SimplifiedProxy (ProxyLOD)
- Universal Level Instance + Packed Level Actor + HISM support (flatten+merge)
- Vertical-aware runtime streamer (full/preload/HLOD/unload, hysteresis,
  velocity prediction, fall-risk), WP-style debug viz + vp.* console
- Safe-by-default: only static decor streams; sky/lights/gameplay stay persistent

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-30 17:42:41 +03:00

7.1 KiB

Raw Blame History

Vertical Partition — практическая инструкция

Пошаговое «что нажимать». Архитектура и детали — в README.md.

Плагин берёт готовую вертикальную карту (Only Up / Only Climb), режет её на Z-ячейки, печёт офлайн HLOD-прокси и в рантайме грузит ближние ячейки целиком, дальние показывает как прокси, совсем дальние выгружает.

0. Один раз: включить плагин

Плагин EnabledByDefault — подхватывается сам. Если нет: Edit → Plugins → Vertical Partition → Enabled, перезапустить редактор. После C++-правок нужна полная пересборка (новые модули в редактор «на лету» не подгружаются).

1. Поставить том вокруг трассы

В уровне: Place Actors → ищи Vertical Partition Volume → перетащи на сцену.
Масштабируй Box так, чтобы он охватил всю играбельную спираль (низ → верх). Бокс рисуется голубым; коллизии у него нет.

2. Настроить (в деталях тома, секция `Vertical Partition → Settings`)

Минимум, что нужно тронуть:

Cell Height — высота одной ячейки (см). Ориентир: 1–2 «этажа» трассы. Например 5000.
Full/HLOD/Unload ranges (категория Streaming) — сколько ячеек вокруг игрока держать:
- Full Load Cells Below/Above — целиком (обычно 1/1).
- HLOD Load Cells Below/Above — прокси (например 4/5).
- Unload Cells Below/Above — дальше выгрузка.
Остальное можно оставить по умолчанию.

Важно про LI: если трасса собрана из Level Instance — они должны быть ЗАГРУЖЕНЫ в редакторе (не свёрнуты) перед сборкой. Незагруженный LI пропустится с варнингом «load it and rebuild».

3. Анализ (без записи)

Кнопка 1 - Analyze → Analyze Current Level. Смотри лог (Output Log, фильтр LogVerticalPartition): сколько акторов внутри тома, сколько ячеек, сколько ушло в persistent, варнинги. Ничего не меняется на диске.

4. Сборка

Кнопка 2 - Build → Build Vertical Partition. Что произойдёт:

бэкап карты в Saved/VerticalPartition/Backups/;
генерится дескриптор /Game/VPGenerated/<Карта>/VPD_<Карта>;
пекутся HLOD-прокси в …/Proxies/;
в уровень добавляется актор-менеджер (Vertical Partition Manager);
том получает ссылку на дескриптор.

5. Проверить HLOD во вьюпорте (без запуска игры)

3 - Validate → Preview Chunks — цветные боксы ячеек:
- 🟢 зелёный = у ячейки есть HLOD-прокси;
- 🟠 оранжевый = стримится, но прокси нет (просто прячется вдали);
- ⚪ серый = пусто / persistent.
3 - Validate → Spawn HLOD Preview — спавнит сами прокси-меши поверх оригинала. Спрячь реальный декор (или посмотри издалека), чтобы оценить силуэт.
3 - Validate → Clear Preview — убрать боксы и превью-акторы.

6. Запустить и проверить стриминг

Play. Включи отладку в консоли (~):

vp.Debug 1
vp.DebugDraw 1      ; цветные боксы ячеек в 3D
vp.DebugOverlay 1   ; статистика на экране

Цвета: 🟢 Full · 🔵 HLOD · 🟡 грузится · 🔴 ошибка · ⚪ выгружено · 🟣 forced. Полезные команды: vp.DumpCells, vp.TeleportToCell 12, vp.ForceCellHLOD 8, vp.SetFullRange 2 2, vp.ProfileStreaming.

Что стримится, а что НЕТ (запомни)

Стримится (прячется/заменяется прокси) только чистый статик-декор. Никогда не трогаются (всегда persistent, всегда видны):

свет, Ultra Dynamic Sky, Sky Atmosphere, SkyLight, туман, post-process;
аудио, частицы/Niagara, reflection capture, декали;
физика, реплицируемые, Movable-акторы;
свет/геймплей внутри Level Instance.

→ Поэтому небо и рабочие акторы не пропадают. Управляется флагом Settings → bStreamOnlyStaticDecor (вкл по умолчанию — не выключай без причины).

Если что-то «пропало» / нужно откатить

NonDestructive-режим ничего не удаляет с диска — прячет только в игре (PIE).

Полный сброс: удали актор Vertical Partition Manager из уровня + папку /Game/VPGenerated/, затем Build заново. Или кнопка 5 - Maintenance → Clear Generated Data.
Восстановить карту из бэкапа: 4 - Commit → Restore From Backup.

Частые проблемы

Симптом	Причина / решение
Небо погасло / акторы исчезли в Play	Старый дескриптор до фикса. Build заново (теперь свет/небо/LI остаются persistent).
Level Instance не попал в чанки	LI был свёрнут. Загрузи его в редакторе → `Build`.
Ячейки все оранжевые (нет HLOD)	В ячейке нет статик-геометрии, либо `bGenerateHLODProxies` выключен.
`SimplifiedProxy` ничего не печёт	Нужен включённый ProxyLODPlugin. Без него авто-откат на `MergedMesh` (это ок).
Прокси смещён	Не должно — пекутся с пивотом в (0,0,0). Если видишь смещение — пересобери HLOD.
Хочу перепечь только прокси	`2 - Build → Rebuild HLOD`.

Офлайн-сборка (CI / без открытия редактора)

UnrealEditor-Cmd.exe IHY.uproject -run=VerticalPartition -Map=/Game/Maps/MyClimbMap

Отчёт пишется в Saved/VerticalPartition/<Карта>_Report.txt.

7.1 KiB Raw Blame History Unescape Escape