Экспорт 3D в glTF: файлы, материалы и проверка

Что переносит glTF

glTF 2.0 — формат обмена 3D-данными, а не резервная копия проекта. Экспортируйте геометрию и поддерживаемые материалы для обработки в DCC-приложении или передачи в другой инструмент. Для сохранения игровых Entity и ресурсов Reckfell используйте собственные форматы проекта, а для доставки игры — экспорт проекта.

Успешная запись файла не гарантирует одинаковую картинку: целевое приложение может иначе обрабатывать освещение, материалы и расширения glTF. Скрипты, игровые связи, настройки WorldEnvironment, постобработка и симуляция частиц не превращаются в переносимый игровой проект.

Экспорт из редактора

1. Откройте нужный 3D-уровень или префаб. Экспорт обходит его корень и потомков; это не экспорт всех открытых вкладок.
2. Проверьте геометрию, локальные трансформации, материалы и принадлежность объектов сохраняемому дереву. В режиме редактора временные потомки без Owner могут быть исключены.
3. Выберите Scene → Export As… → glTF 2.0 Scene…, задайте выходной файл и проверьте параметры экспорта перед подтверждением.
4. Откройте результат в целевой программе. Сравните масштаб, иерархию, поверхности, текстуры и нужные анимации.

Названия пунктов могут быть локализованы. Настройки видимости и режима корня влияют на состав результата; невидимый объект не следует считать автоматически исключённым. Работа интерфейса здесь сверена с исходниками; дополнительные плагины могут менять настройки экспорта.

Не называйте .gltf с соседними файлами «встроенным» форматом. Для очень крупных данных и нестандартных настроек не предполагайте, что одного .glb всегда достаточно.

Экспорт из C#

Выходная папка должна существовать и быть доступна для записи. Передайте живой корень Entity3D и путь с расширением .glb или .gltf, например user://model.glb. Сохраните класс в ExportModel.cs:

using System;
using Reckfell;

public static class ExportModel
{
    public static Error Write(Entity3D root, string outputPath)
    {
        if (!outputPath.EndsWith(".glb", StringComparison.OrdinalIgnoreCase)
            && !outputPath.EndsWith(".gltf", StringComparison.OrdinalIgnoreCase))
            return Error.InvalidParameter;

        using var document = new GltfDocument();
        using var state = new GltfState();
        Error error = document.AppendFromScene(root, state);
        if (error != Error.Ok)
            return error;
        return document.WriteToFilesystem(state, outputPath);
    }
}

AppendFromScene заполняет GltfState; файл создаёт WriteToFilesystem. Проверяйте результат обоих этапов. Для независимого экспорта пример создаёт новый state при каждом вызове. Исходное дерево не освобождается и остаётся у вызывающего кода.

Результат Error.Ok означает успешное выполнение API, а не проверку всех художественных и игровых требований. Экспорт может создать несколько файлов и не является атомарной заменой папки: при ошибке проверьте частично записанный результат.

Ограничения, которые видны на практике

Проверка результата и ошибки

Для обратной загрузки создайте новый GltfDocument и GltfState, вызовите AppendFromFile(path, state) и после Error.Ok — GenerateScene(state). Полученное дерево ещё не добавлено в EntityTree: используйте его явно и освободите, когда оно не нужно. Такой тест проверяет чтение самим Reckfell; совместимость с другим приложением требует отдельной проверки в нём.

Продолжение: импорт 3D и файлы во время выполнения.