Поиск типичных неисправностей 3DGS в UE5 по симптомам

Эта страница построена по тому, что вы видите, и для каждого пункта указаны возможные причины, способ проверки и решение.

Как посмотреть журналы и воспользоваться инструментами отладки, см. Журналы и диагностика. Вопросы справочного характера (какие форматы поддерживаются, чем различаются два конвейера) см. в Частых вопросах.

Содержание

Сначала сделайте эти два шага

Большинство проблем находится в пределах этих двух шагов, поэтому при любом симптоме начните с них.

1. Откройте Output Log и посмотрите журнал плагина. Сбои загрузки, ошибки путей и проблемы лицензирования оставляют там понятные сообщения. Как это сделать, см. Просмотр журнала плагина.
2. Убедитесь, что данные загрузились. Выберите Actor и посмотрите, есть ли содержимое в MetaInfo панели Details (Total Splats больше 0). Пусто — значит данные не попали в сцену, сразу переходите к разделу Сбой загрузки данных.

Сбой загрузки данных

Симптом: нажали Load, но ничего не появилось

Проверьте по порядку:

Симптом: в редакторе всё нормально, а после сборки ничего не видно

Проверьте две вещи по порядку.

Первое: не использован ли абсолютный путь. Абсолютные пути действительны только на текущей машине, а на другой такого пути нет. Замените на относительный путь от каталога Content проекта, например Scenes/Tower/meta.lcc2.

Второе: указан ли каталог данных в настройках упаковки. Два параметра служат разным целям, выбирайте по потребности:

Второй нужен, когда данные LCC требуется упаковать в pak; первый — когда данные достаточно распространять вместе с результатом сборки. Оба находятся в ProjectSettings > Packaging.

После настройки соберите проект заново и проверьте, действительно ли данные оказались в результате сборки. Подробную настройку см. в Быстром старте.

Симптом: после сборки проекта на Blueprint плагин не работает

Проекты только на Blueprint (Blueprint-only) поддерживаются лишь в редакторе, упаковка не поддерживается. Для упаковки обязательно нужен проект C++.

Симптом: географические координаты не совпадают, режим GIS не действует

Проверьте следующее:

• Содержат ли данные информацию RTK. Проверьте через GetMetaInfo().IsRTK(); сообщение This lcc does not have RTK information! в журнале означает, что географической информации в данных нет
• При включении из кода вызывайте SetGeoPlacement(true) — этот вызов автоматически перезагружает данные, чтобы настройка вступила в силу. Прямое присваивание bEnableGeoPlace перезагрузку не запускает
• При смещении положения подстройте его через GeoLocationOffset

Порядок настройки совместно с Cesium см. в Интеграции со сторонними и движковыми плагинами.

Симптом: аварийное завершение при перемещении по очень большим данным LCC2

Если используется v1.0.0, это известный дефект той версии (превышение предела GPU Buffer). Обновитесь до v2.x или выше.

Симптом: при загрузке большого PLY возникает ошибка, связанная с массивом

Известный дефект v3.0.0, исправлен в v3.3.0 и выше — обновите версию.

Большие файлы PLY теперь читаются потоково, и ограничения размера файла в 2 ГБ больше нет. Если загрузка по-прежнему не удаётся, чаще всего число splat превышает ёмкость видеопамяти, см. Ограничения загрузки одиночных форматов.

Изображение не отображается или отображается не полностью

Симптом: Actor есть в сцене, но содержимое совсем не видно

Симптом: дальнее содержимое пропадает и появляется только при приближении

Это нормальное поведение LOD и ограничения дистанции, а не неисправность. Чтобы дальний план тоже отображался:

• Увеличьте Max Distance — ценой снижения производительности
• Уменьшите Level Factor, чтобы на той же дистанции использовалась более высокая точность
• Туман помогает скрыть границу дистанции

Симптом: при быстром повороте вида у края экрана появляются дыры

Предзагрузка узлов не успевает за изменением вида. В конвейере LCC можно включить Add Extra Preload Nodes: он добавляет дополнительные предзагружаемые узлы ценой увеличения числа рендерящихся узлов.

Симптом: в SceneCapture или на мини-карте пусто

Сначала включите SceneCaptureComponent Support в настройках проекта. По умолчанию этот пункт выключен и имеет небольшую стоимость по производительности.

Как задать стратегию рендеринга для SceneCapture отдельно из кода, см. SetSceneCaptureRenderMode; обратите внимание, что эта группа интерфейсов действует только в конвейере LCC.

Симптом: 3DGS перекрыт поверхностью воды

Причина — обработка глубины материалом однослойной воды. Включите SingleLayerWater Support, см. Поддержка однослойной воды.

Проблемы качества изображения

Симптом: при движении видны шлейфы и остаточные изображения

Причина — метод сглаживания. TSR и TAA опираются на историю кадров для накопления во времени, поэтому при движении 3DGS легко оставляет предыдущий кадр.

Пробуйте по порядку и найдите баланс между качеством и шлейфами:

None → FXAA → MSAA → TAA → TSR

Если в сцене есть только 3DGS, можно сразу задать None: шлейфов не будет, а стоимость сглаживания уйдёт. Значения по умолчанию для каждого конвейера и место настройки см. в Параметрах производительности.

Симптом: изображение мерцает, края дрожат

Пробуйте по убыванию отдачи:

1. Проверьте метод сглаживания. Это самая частая причина; для конвейера LCC2 рекомендуется TSR, см. Параметры производительности.
2. Конвейер LCC: уменьшите Sort Factor, чтобы сортировка выполнялась чаще. При слишком низкой частоте сортировки порядок полупрозрачных элементов обновляется раз в несколько кадров, что выглядит как лёгкое дрожание изображения.
3. Проверьте Small Splat Threshold: слишком большое значение делает дальний план зернистым.
4. Если мелкие структуры мерцают при приближении и удалении камеры, попробуйте включить Mip Filter: он выполняет низкочастотную фильтрацию с компенсацией непрозрачности и стабильнее на разных масштабах. Для .ply / .spz / .sog этот пункт выключен по умолчанию.

Симптом: в изображении дыры, картинка разреженная

SplatScale выставлен слишком малым. Значение по умолчанию 1.0 является верхним пределом; уменьшение снижает overdraw и повышает частоту кадров, но при уменьшении квадов появляются просветы. Увеличьте значение обратно.

Симптом: цвета серые и плоские

Используйте параметры коррекции цвета, см. Визуальные настройки. Обычно немного повышают Contrast или высветляют тёмные области через Gamma. Интерфейсы кода см. в Color Adjustment.

Симптом: заметны швы в изображении (конвейер LCC)

Файлы LCC версии 5.0 и выше обрабатывают швы автоматически. Для данных более старых версий включите устранение швов вручную; соответствующее свойство — bEnableSeamCutting.

Симптом: в сцене появляется полоса

Проверьте масштаб Actor. Actor семейства LCC (ALCCActor, ALCC2Actor, ASogActor, ASpzActor, APlyActor) поддерживают только равномерное масштабирование.

Не используйте такое неравномерное масштабирование:

• С отрицательными значениями, например (-1, 1, 1)
• С разными значениями по осям, например (2, 1, 3)

Все три оси должны совпадать, например (1, 1, 1) или (2, 2, 2). Неравномерное масштабирование приводит к сбоям рендеринга, которые выглядят как полоса на изображении.

Проблемы освещения

Симптом: после переключения в Lit изображение пересвечено

В цвета снятых данных уже запечено освещение места съёмки, и свет сцены накладывается сверху ещё одним слоем.

• Конвейер LCC2: снизьте исходную яркость через LightingScale, см. Нормали и освещение
• Проверьте, не слишком ли высока интенсивность освещения сцены

Симптом: в режиме Lit нет затенения по форме, изображение плоское

Это ожидаемое поведение. У данных 3DGS нет геометрических нормалей, а режимы Fixed, ViewFacing и Hemispherical строят нормали приближёнными способами, поэтому дают только общее изменение яркости и ни один из них не создаёт затенения, следующего форме. Определения режимов см. в ELCC2NormalGenerationMode.

Настоящее затенение по форме даёт только режим ProxyMesh: для него нужно подготовить и разместить прокси-меш, а также иметь лицензию. См. Прокси-меш и Нормали и освещение.

Три приближённых режима различаются тем, как общая яркость меняется вместе с освещением и видом, а не наличием затенения по форме:

• Fixed: вся область использует одну фиксированную нормаль, при движении камеры полностью стабильна
• ViewFacing: нормали следуют за камерой, поэтому при повороте вида меняется общая яркость
• Hemispherical: нормали отображаются из экранной позиции на фиксированную полусферу, поэтому при вращении направленного света общая яркость меняется плавнее, чем в двух предыдущих режимах

Симптом: режим ProxyMesh задан, но не действует

Подробнее см. Прокси-меш.

Симптом: затенение появляется не в том месте

Прокси-меш слишком сильно расходится с фактической поверхностью 3DGS. Либо улучшите прилегание прокси-меша, либо перейдите на приближённый режим нормалей: затенения по форме он не даёт, но работает стабильнее.

Симптом: тени ProxyMesh есть только вблизи, а вдали исчезают

Тени обрезаются по расстоянию. Это проблема самого движка, а не дефект плагина.

Решение: выберите Actor ProxyMesh и выключите, а затем снова включите Far Shadow (дальние тени) — тени восстановятся полностью. Свойство находится в категории Lighting у StaticMeshComponent.

Симптом: в режиме Lit появляются огромные некорректные тени

Приближённые режимы нормалей при некоторых углах освещения дают сбои. Пробуйте по порядку:

1. Переключите NormalMode и посмотрите, какой режим ведёт себя нормально
2. Измените угол направленного света
3. Перейдите на режим ProxyMesh с хорошо прилегающим прокси-мешем — это решение даёт лучший результат

Симптом: после включения теней изменились цвета

Это ожидаемое поведение. Получая внешнее освещение, 3DGS меняет цвета вслед за источником света, поэтому настройте цвет и интенсивность направленного света.

Симптом: яркость не поддаётся настройке, сцена в целом тёмная

Если в проекте используется плагин композитинга вроде Composure, отключите на Component параметры, связанные с постобработкой, и управляйте экспозицией через Post Process Volume.

Настройки, связанные с экспозицией, см. в Визуальных настройках.

Симптом: эффекты Niagara не видны на 3DGS

Конвейер LCC2 выводит глубину, поэтому перекрытие эффектов определяется правильно и в норме такая проблема не возникает.

Столкнуться с ней можно только в конвейере LCC (данные .lcc), потому что он не выводит глубину и порядок полупрозрачных элементов определяется приоритетом сортировки. Решение — повысить Translucent Sort Priority у Niagara System, чтобы система рендерилась поверх 3DGS.

Симптом: по краям сцены беспорядочное содержимое

Это данные окружения. Измените LoadMode с Both на OnlyMain, чтобы рендерилась только основная часть.

Симптом: переключение режима освещения не даёт результата

В режиме облака точек SetLightMode не действует: присваивание пропускается и в журнал выводится предупреждение. Сначала вернитесь в режим 3DGS.

Симптом: после переключения в режим Lit никакого освещения нет

В конвейере прямого рендеринга (Forward Shading) отсутствует GBuffer, поэтому переосвещение невозможно. Значение Lit у LightMode результата не даёт.

Чтобы режим Lit работал нормально, перейдите на конвейер отложенного рендеринга (Deferred Shading). Снимите флажок в Project Settings > Rendering > Forward Shading. Учтите, что шаблон VR в UE по умолчанию включает Forward Shading, и при использовании этого шаблона его нужно выключить вручную.

Изменение параметров не даёт результата

Симптом: значения в Performance изменены, но ничего не поменялось

Слева от каждого параметра есть флажок, и пока он снят, используется встроенное значение плагина по умолчанию, а введённое вами значение не действует. Это самая частая ловушка.

Встроенные значения по умолчанию для каждого параметра см. в Параметрах производительности.

Симптом: изменение параметров полной загрузки ничего не меняет

Use Full Load и Full Load Splat Number вычисляются при загрузке, поэтому после изменения нужно загрузить данные заново.

Разницу между двумя способами загрузки см. в Рендеринге.

Симптом: изменение свойств объёма обрезки или секущей плоскости во время выполнения не даёт результата

В текущей версии такой проблемы нет: данные обрезки и рассечения читаются каждый кадр, поэтому присваивание bEnabled, Mode или VolumeType вступает в силу на следующем кадре, как и изменение трансформации (положение, поворот, масштаб).

Если результата всё равно нет, проверьте, добавлен ли этот Actor в массив ClippingVolumes / SectionPlanes у Component и не превышена ли квота одновременно действующих элементов (без лицензии 50 каждого типа; лишние в рендеринге не участвуют и вызывают предупреждение).

В старых версиях требовался ручной вызов Refresh(). Этот метод и SetUpdateComponent() теперь объявлены устаревшими и ничего не делают, см. ALCCClippingVolume.

Симптом: сферические гармоники включены, но изображение не изменилось

• Данные могут быть типа Portable, который сферических гармоник не содержит. Проверьте через CanSetShcoef(); определения типов см. в EFileType
• В режиме облака точек SetUseShcoef молча не действует, сначала вернитесь в режим 3DGS
• В LCC2 сферические гармоники можно отключить отдельно через SetUseShcoef

Симптом: объёмов обрезки добавлено много, но действует только часть

В бесплатной редакции действует ограничение 50 объектов каждого типа. В журнале есть явное указание: Unlicensed: enabled clipping volumes limited to 50 .... О лицензировании см. Редакции и лицензирование.

Проблемы производительности

Полный порядок оптимизации при низкой частоте кадров см. в Руководстве по оптимизации производительности; здесь приведены только быстрые проверки.

Симптом: низкая частота кадров

Сначала убедитесь, что узкое место именно в 3DGS. Посмотрите Game / Draw / GPU через stat unit, затем посмотрите собственные затраты LCC через stat XGrids. Если доля затрат LCC невелика, проблема в других частях сцены (освещение, постобработка, логика Blueprint), и настройка параметров LCC улучшения не даст.

Если причина действительно в 3DGS, настраивайте по убыванию отдачи:

1. Увеличьте Level Factor (самая заметная отдача)
2. Уменьшите Max Distance
3. Уменьшите Max Splat Num
4. Повысьте Start Level, чтобы пропустить самый детальный уровень
5. Отключите сферические гармоники
6. При необходимости перейдите в режим облака точек

Симптом: слишком высокий расход видеопамяти

• Увеличьте Level Factor
• Уменьшите Max Splat Num
• В конвейере LCC2 измените LCC2 GPU Memory Budget
• Измените порог освобождения Max GPU Usage Percetage For Free

Правила распределения видеопамяти и механизм автоматического освобождения см. в Рендеринге. Одиночные форматы (.sog / .spz / .ply) загружаются целиком за один проход, поэтому расход видеопамяти постоянен и не зависит от вида, см. Ограничения загрузки одиночных форматов.

Симптом: рывки при загрузке

• Первое включение коллизий даёт единичную стоимость запекания, поэтому включайте их на этапе загрузки, а не во время действий игрока
• Уменьшите Max Load Collision Distance, чтобы загружать только нужный диапазон
• Измените конфигурацию потоков, см. Параметры производительности

Симптом: при взаимном проникновении нескольких 3DGS перекрытие определяется неверно

• Конвейер LCC: включите сортировку прозрачности между несколькими Actor
• Конвейер LCC2: измените порог глубины, чтобы сдвинуть место записи глубины

Коллизии и навигация

Симптом: луч не попадает в 3DGS

Сообщение There is neither collision.bin nor collision.lci in the folder в журнале означает, что в каталоге данных нет файла коллизий.

У LCC1 есть отдельный набор интерфейсов трассировки лучей по положениям точек, но он недостаточно протестирован, поэтому лучше использовать коллизии вместе с трассировкой лучей движка, см. ULCCComponent Raycast.

Симптом: персонаж падает вниз сразу после старта

Коллизии загружаются динамически по блокам, поэтому в самом начале игры данные коллизий могут быть ещё не построены, и персонаж падает, если под ним нет коллизий.

Как это обойти:

• Разместите PlayerStart немного выше уровня земли
• Либо разрешайте персонажу двигаться с задержкой в несколько секунд
• Включайте коллизии на этапе загрузки, а не после того, как игрок начал действовать

Симптом: персонаж проваливается сквозь модель или падает, отойдя на некоторое расстояние

Коллизии подгружаются потоково по расстоянию, поэтому за пределами диапазона загрузки тел коллизий нет. Увеличьте Max Load Collision Distance(m) так, чтобы он покрывал область перемещений персонажа.

При слишком быстром движении персонажа коллизии тоже могут не успевать; это тоже смягчается увеличением дистанции загрузки.

Симптом: NavMesh совсем не строится

Полный порядок действий см. в Поддержке системы навигации.

Аварийные завершения

Симптом: аварийное завершение после ошибки утверждения ArraySliceIndex

Сообщение выглядит так:

Assertion failed: ArraySliceIndex >= 0

Причина в том, что текущая версия не поддерживает формат Adaptive GBuffer у Substrate.

Решение:

1. Откройте ProjectSettings > Rendering и найдите Substrate GBuffer Format (Project).
2. Измените значение на BlendableGBuffer. Это значение по умолчанию для движка.
3. Перезапустите движок.

AdaptiveGBuffer — известный несовместимый формат, BlendableGBuffer работает нормально.

Проблемы лицензирования

Сначала посмотрите Status в панели плагина: зелёная галочка означает, что лицензия в порядке и возможности редакции Pro доступны. Если галочка не зелёная, лицензия не действует — посмотрите журнал, чтобы уточнить причину.

Сообщения о лицензировании в журнале достаточно однозначны, действуйте по подсказке:

Порядок лицензирования см. в Редакциях и лицензировании.

Сборка и упаковка

Симптом: отсутствуют бинарные файлы или не собирается модуль

При появлении любой из ошибок ниже пересоздайте и пересоберите проект по шагам этого раздела:

Missing UnrealGame binary. You may have to build the UE project with your IDE.
Alternatively, build using UnrealBuildTool with the commandline:
UnrealGame <Platform> <Configuration>

*** could not be compiled. Try rebuilding from source manually

Причина в том, что после добавления плагина в проект C++ движок обнаруживает новые модули, но соответствующих результатов сборки нет. Действуйте так:

1. Закройте проект.
2. Найдите файл *.uproject проекта.
3. Щёлкните *.uproject правой кнопкой и выберите в меню Generate Visual Studio project files.
4. Дождитесь завершения повторной генерации проекта VS.
5. Дважды щёлкните *.sln, чтобы открыть Visual Studio.
6. В обозревателе решений щёлкните проект правой кнопкой и выберите Set as Startup Project, чтобы он стал запускаемым проектом.
7. Убедитесь, что конфигурация проекта — Development Editor и Win64.
8. Нажмите Debug > Start Without Debugging, чтобы запустить проект.
9. После успешной сборки проект открывается нормально. Дальше достаточно дважды щёлкнуть *.uproject, и повторять эту процедуру каждый раз не нужно.

Если после этих шагов сборка по-прежнему не удаётся, сначала удалите каталог Intermediate проекта, а затем выполните всё заново начиная с шага 3.

Порядок установки плагина см. в Быстром старте.

Симптом: сбой упаковки

Сначала проверьте три пункта:

• Full Rebuild в ProjectSettings > Packaging должен оставаться выключенным, и не выполняйте Rebuild в VS. Плагин не поддерживает ни то, ни другое, см. Быстрый старт
• Убедитесь, что используется проект C++: проекты на Blueprint упаковать нельзя
• Убедитесь, что версия движка входит в поддерживаемый диапазон (UE 5.4 ~ 5.8)

Конкретные ошибки описаны в двух следующих разделах.

Симптом: при упаковке сообщается об отсутствии предкомпилированного манифеста

Сообщение выглядит так:

Missing precompiled manifest for 'LCC4UnrealRuntime',
'\Shipping\LCC4UnrealRuntime\LCC4UnrealRuntime.precompiled'.
This module was most likely not flagged for being included in a precompiled build
- set 'PrecompileForTargets = PrecompileTargetsType.Any;' in LCC4UnrealRuntime.build.cs
to override. If part of a plugin, also check if its 'Type' is correct.

Почему это происходит: упомянутые в ошибке файлы изначально поставляются вместе с плагином и находятся в его каталоге Intermediate. При выполнении Full Rebuild из ProjectSettings > Packaging или Rebuild в VS движок очищает каталог Intermediate и удаляет эти предкомпилированные результаты.

LCC4Unreal — бинарный плагин без исходного кода, поэтому удалённые результаты пересобрать невозможно и восстановить их можно только из пакета плагина. Поэтому этих двух операций следует избегать.

Как исправить:

1. Убедитесь, что Full Rebuild в ProjectSettings > Packaging выключен, и не выполняйте Rebuild в VS.
2. Скопируйте содержимое каталога плагина lcc4unreal/Intermediate/Build/Win64/UnrealGame в каталог проекта <каталог проекта>/Intermediate/Build/Win64/<имя проекта>.
3. Скопируйте содержимое каталога плагина lcc4unreal/Intermediate/Build/Win64/x64 в каталог проекта <каталог проекта>/Intermediate/Build/Win64/x64.
4. Перезапустите движок и соберите пакет заново.

Примечание: имя целевого каталога на шаге 2 — это имя проекта, а не UnrealGame. Например, если проект называется MyProject, целевой путь — MyProject/Intermediate/Build/Win64/MyProject.

Если ошибка указывает на другие файлы: два каталога выше покрывают типичные случаи. Когда в ошибке упоминаются другие файлы, действуйте так же: найдите файл в каталоге Intermediate плагина по тому же относительному пути и скопируйте его в соответствующее место проекта.

Если каталог Intermediate самого плагина тоже очищен: копировать будет неоткуда — заново скачайте пакет плагина и распакуйте его с перезаписью, это восстановит файлы.

Симптом: сборка не проходит на пользовательском движке

Выпускаемые пакеты плагина подходят только для движка, опубликованного Epic. Кастомные ветки производителей, коммерческие движки на базе UE и движки с самостоятельно изменённым исходным кодом требуют отдельной адаптации, см. Пользовательские версии движка.

Симптом: ошибка при сборке под Android

Текущая версия не поддерживает прямую сборку под платформу Android. Это ограничение совместимости платформы, изменением настроек упаковки его не решить.

Для использования на устройствах VR применяйте схему с запуском на ПК и стримингом, см. Быстрый старт — Quest3.

Проблема не решена

Соберите приведённую ниже информацию и свяжитесь с нами, см. Свяжитесь с нами:

• Версия плагина и версия движка
• Формат данных и примерный объём
• Полный файл журнала того запуска, в котором возникла проблема — не фильтруйте его и не присылайте только строки с ошибкой
• Шаги воспроизведения
• Модель видеокарты и версия драйвера

Расположение файла журнала и другие подробности см. в Журналах и диагностике.