Настройки 3D-импорта: масштаб и композиция

Root Scale, применение масштаба, загрузка PackedEntity и разделение модели и игрового префаба.

Разделите исходную модель и игровой объект

Исходный glTF описывает переносимые данные модели. Настройки импорта определяют, как редактор преобразует их. Ваш уровень .rscene или префаб .rprefab добавляет игровую композицию: скрипты, дополнительные Entity и нужные экземпляру параметры.

Не редактируйте сгенерированный .rbin в .reckfell/imported/ как собственный префаб. При повторном импорте он создаётся заново. Если нужно изменить форму, UV или исходную расстановку — исправьте модель в 3D-пакете; если нужна игровая логика — разместите модель внутри собственного префаба.

Настройте масштаб один раз

Выберите 3D-файл в Content Browser, измените параметры Import и примените Reimport. Точные имена параметров ниже помогают найти их и проверить сохранённый .import.

Параметр	Что меняет
nodes/root_name	имя корня импортированной иерархии
nodes/root_type	тип корня; для размещения в 3D используйте подходящий тип Entity3D
nodes/root_script	скрипт, назначаемый корню при импорте; это отдельное решение от игрового префаба-обёртки
nodes/root_scale	общий коэффициент масштаба модели
nodes/apply_root_scale	применить коэффициент к данным и размещению потомков либо оставить его на корне

Для контрольной модели размером 1 × 1 и второго экземпляра в (2, 3, 0) получены такие результаты:

Root Scale	Apply Root Scale	Масштаб корня	Размер меша	Положение второго экземпляра в мире
1	включён	(1, 1, 1)	1 × 1	(2, 3, 0)
2	выключен	(2, 2, 2)	1 × 1	(4, 6, 0)
2	включён	(1, 1, 1)	2 × 2	(4, 6, 0)

Последние два варианта дают одинаковый общий размер, но хранят разные локальные данные. Учитывайте это при измерении меша, добавлении дочерних объектов и настройке физики. Не компенсируйте один коэффициент другим в каждом экземпляре уровня.

Загрузите уже импортированную модель

После импорта model.glb положите ImportedProp.cs в C#-проект Reckfell 1.0.0 и прикрепите к Entity3D. Модель должна находиться по ModelPath; значение по умолчанию — asset://Models/model.glb.

C#
using Reckfell;

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

    public override void _Ready()
    {
        var packed = ResourceLoader.Load<PackedEntity>(ModelPath);
        if (packed == null)
        {
            ReckfellApi.PrintErr($"Imported model is unavailable: {ModelPath}");
            return;
        }
        AddChild(packed.Instantiate());
    }
}

При запуске появится дочерняя иерархия из обработанного PackedEntity. Компонент проверен после реального импорта редактором. Он не запускает Blender и не разбирает исходный glTF напрямую: ResourceLoader разрешает путь через метаданные импорта. Для появления картинки нужны активная камера, подходящий ракурс и освещение.

Тот же принцип композиции можно оформить в игровом префабе: корень вашего объекта, дочерняя импортированная модель и игровой скрипт. Модель не должна заменять корень персонажа только потому, что у неё уже есть собственный корень.

Меняйте обработку мешей под задачу

Параметр	Назначение	Чего он не делает
meshes/ensure_tangents	подготовка касательных, нужных для normal mapping	не исправляет неверную UV-развёртку или карту нормалей
meshes/generate_lods	генерация более простых уровней геометрии	не подтверждает приемлемую форму каждого LOD
meshes/create_shadow_meshes	дополнительный вариант меша для проходов теней	не включает свет и не запекает освещение
meshes/light_baking	подготовка режима участия меша в GI и, при нужном режиме, lightmap UV	не выполняет само запекание света
animation/import	включение импорта анимаций	не подтверждает правильную позу, ретаргетинг и все клипы

Для конкретного меша доступны дополнительные настройки: расширенный импорт. Генерацию LOD, lightmap UV и анимацию проверяйте отдельно на своей модели; текущая проверка этого руководства подтверждает масштаб, иерархию и загрузку, а не качество этих генераторов.

Если повторный импорт меняет результат

Изменился размер: сравните Root Scale и Apply Root Scale в .import, затем локальный масштаб игрового экземпляра.
Изменилось имя пути до дочерней Entity: проверьте Root Name и имена в исходной модели, прежде чем исправлять игровой код.
Пропали ваши правки: убедитесь, что они сделаны в собственном префабе или внешнем материале, а не только в кэше импорта.
Не загружается PackedEntity: завершите импорт, проверьте сообщения редактора и тип ресурса. OBJ as Mesh даёт меш, а не тот же тип, что импортированная 3D-иерархия.