Импорт 3D: форматы и загрузка glTF

Выберите формат под задачу

Для передачи готовой модели в Reckfell используйте glTF 2.0. Формат переносит геометрию, иерархию и поддерживаемые PBR-параметры. Он не переносит произвольный граф материала, настройки рендера и всю логику исходного 3D-пакета.

GLB не обязан быть меньше glTF. Его главное удобство — упаковка зависимостей, если выбран соответствующий режим экспорта.

Импорт в редактор и загрузка во время игры

Обычная модель проекта: скопируйте комплект в каталог проекта, например Assets/Props/. Редактор выполняет импорт с настройками ресурса и использует обработанный результат. Его кэш не является исходной моделью: храните исходные файлы и метаданные импорта, а не только содержимое .reckfell/.

Внешняя модель во время игры: используйте GltfDocument. Он разбирает glTF и создаёт иерархию Entity. Этот путь не повторяет все настройки импортёра редактора, не строит коллизии из любого меша, не создаёт игровой скрипт или готовый файл .rprefab.

.rscene — уровень, .rprefab — переиспользуемая иерархия. Переименование model.glb в model.rprefab не конвертирует содержимое. Подробнее: Entity, уровни и префабы.

Полный загрузчик на C#

Нужен C#-проект Reckfell 1.0.0. Сохраните код в ImportModel.cs, прикрепите к Entity3D и задайте ModelPath. Для воспроизводимого исходного ассета можно взять папку Assets из готового интерьера: путь по умолчанию уже соответствует его PawnShop.gltf. Собирать или устанавливать Blender для этого glTF не требуется.

using Reckfell;

public partial class ImportModel : Entity3D
{
    [Export(PropertyHint.File, "*.gltf,*.glb")]
    public string ModelPath { get; set; } = "asset://Assets/PawnShop.gltf";

    public static Error ReadModel(string path, out Entity? model)
    {
        model = null;
        string extension = path.GetExtension().ToLowerInvariant();
        if (extension != "gltf" && extension != "glb")
            return Error.Unavailable;
        if (!FileAccess.FileExists(path))
            return Error.FileNotFound;

        using var document = new GltfDocument();
        using var state = new GltfState();
        Error error = document.AppendFromFile(path, state);
        if (error != Error.Ok)
            return error;

        model = document.GenerateScene(state);
        return model == null ? Error.Failed : Error.Ok;
    }

    public override void _Ready()
    {
        Error error = ReadModel(ModelPath, out Entity? model);
        if (error != Error.Ok || model == null)
        {
            ReckfellApi.PrintErr($"Model load failed: {ModelPath}; {error}");
            return;
        }
        AddChild(model);
        ReckfellApi.Print($"Model loaded: {ModelPath}");
    }
}

После запуска появляется дочерняя иерархия и сообщение Model loaded с путём. Существующая активная Camera3D и освещение определяют, что видно в кадре: этот компонент только загружает модель. Камера из файла модели также может изменить активный ракурс — проверьте импортируемый состав.

ReadModel возвращает ошибку и null при отсутствии файла или неподдерживаемом расширении. При успехе вызывающий код владеет созданной иерархией: добавьте её в дерево или освободите через Free(). Освобождение временных GltfDocument и GltfState после GenerateScene не удаляет созданную модель.

Для экспортированной игры отдельно обеспечьте доступность исходных glTF, .bin и изображений: готовый импортированный ресурс и исходный файл для GltfDocument — разные зависимости. Этот пример не проверяет сборку экспортируемого приложения.

Если нужен прямой импорт .blend

В настройках редактора путь к исполняемому Blender задаёт filesystem/import/blender/blender_path. Импортёр проверяет версию Blender: в исходниках задан минимум 3.0. Наличие этого условия не доказывает совместимость каждого выпуска и каждого файла.

Параметр проекта filesystem/import/blender/enabled управляет этим импортом. На Android и в веб-редакторе он по умолчанию отключён: там нельзя рассчитывать на запуск внешнего Blender. В команде путь через .blend требует доступного Blender на каждой машине, которая выполняет импорт; готовый glTF не требует Blender у получателя.

Найдите причину сбоя

Загрузчик, GLTF/GLB, общие меши, координаты, PBR-привязки и режимы прозрачности проверены в установленном движке. FBX, OBJ, DAE, автоматический .blend-импорт и интерфейс редактора здесь сверены по исходникам, но не прошли отдельную сквозную проверку.