3D import settings: scale and composition — documentation

Root Scale, baking scale, loading PackedEntity and separating a model from its gameplay prefab.

Separate the source model from the gameplay object

A source glTF describes transferable model data. Import settings determine how the editor processes it. Your .rscene level or .rprefab prefab adds gameplay composition: scripts, additional Entities and instance-specific settings.

Do not treat the generated .rbin in .reckfell/imported/ as your own prefab. Reimport recreates it. Change geometry, UVs or authored placement in the source 3D application; place the model inside your own prefab when adding gameplay behavior.

Configure scale once

Select the 3D file in the Content Browser, change Import parameters and apply Reimport. The exact keys below help locate settings and inspect the saved .import file.

Parameter	Changes
nodes/root_name	imported hierarchy root name
nodes/root_type	root type; use an appropriate Entity3D type for 3D placement
nodes/root_script	script assigned to the root on import; a separate choice from a gameplay wrapper prefab
nodes/root_scale	overall model scale factor
nodes/apply_root_scale	apply the factor to descendant data/placement, or leave it on the root

A control model measuring 1 × 1, with a second instance at (2, 3, 0), produced these results:

Root Scale	Apply Root Scale	Root scale	Mesh size	Second instance world position
1	enabled	(1, 1, 1)	1 × 1	(2, 3, 0)
2	disabled	(2, 2, 2)	1 × 1	(4, 6, 0)
2	enabled	(1, 1, 1)	2 × 2	(4, 6, 0)

The last two cases have the same overall size but store different local data. Account for this when measuring meshes, adding children and configuring physics. Do not compensate one scale factor with another on every level instance.

Load the processed model

After importing model.glb, save ImportedProp.cs in a Reckfell 1.0.0 C# project and attach it to an Entity3D. The model must exist at ModelPath, which defaults to 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());
    }
}

Running adds a child hierarchy from the processed PackedEntity. The component was executed after actual editor import. It neither invokes Blender nor parses source glTF directly: ResourceLoader resolves the path through import metadata. An active camera, suitable framing and lighting are required to display the model.

The same composition can be authored as a gameplay prefab: your object root, a child imported model and a gameplay script. A model should not replace a character’s gameplay root merely because it already has its own hierarchy root.

Choose mesh processing for the task

Parameter	Purpose	Does not
meshes/ensure_tangents	prepare tangents required by normal mapping	repair incorrect UVs or a normal map
meshes/generate_lods	generate simpler geometry levels	establish acceptable shape for each LOD
meshes/create_shadow_meshes	create an additional mesh variant for shadow passes	enable lights or bake lighting
meshes/light_baking	prepare the mesh’s GI participation mode and, where selected, lightmap UVs	perform the actual light bake
animation/import	enable animation import	establish correct rest pose, retargeting or every clip

A particular mesh can have further options: Advanced import. Validate LOD generation, lightmap UVs and animation separately on your model; this guide’s acceptance covers scale, hierarchy and loading, rather than generator quality.

When reimport changes the result

Size changed: compare Root Scale and Apply Root Scale in .import, then the gameplay instance’s local scale.
Path to a child Entity changed: inspect Root Name and source model names before changing gameplay code.
Edits disappeared: confirm they live in your own prefab or external material, rather than only the import cache.
PackedEntity does not load: finish import and inspect editor messages and resource type. OBJ as Mesh produces a mesh, rather than the same type as an imported 3D hierarchy.