3D import: formats and loading glTF

Choose a format for the task

Use glTF 2.0 to transfer a finished model into Reckfell. It carries geometry, hierarchy and supported PBR parameters. It does not carry an arbitrary material graph, renderer settings or all behavior from the source 3D application.

GLB is not necessarily smaller than glTF. Its main convenience is packaging dependencies when the appropriate export mode is selected.

Editor import and runtime loading

Regular project asset: copy the complete set into the project, for example Assets/Props/. The editor imports it using the resource’s import settings and consumes the processed result. Its cache is not the source model: retain the source files and import metadata, not only .reckfell/ contents.

External model during play: use GltfDocument. It parses glTF and creates an Entity hierarchy. This path does not reproduce every editor import setting or automatically derive collisions from arbitrary meshes, create gameplay scripts or a finished .rprefab file.

.rscene is a level; .rprefab is a reusable hierarchy. Renaming model.glb to model.rprefab does not convert its contents. See Entities, levels and prefabs.

Complete C# loader

Use a Reckfell 1.0.0 C# project. Save the code as ImportModel.cs, attach it to an Entity3D and set ModelPath. For a reproducible source asset, copy Assets from the authored interior example: the default path already matches its PawnShop.gltf. Loading this glTF does not require installing or building Blender.

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}");
    }
}

Running adds a child hierarchy and prints Model loaded with the path. The existing active Camera3D and lighting determine what appears in the frame: this component only loads the model. A camera included in the model can also change the active view; inspect the imported contents.

ReadModel returns an error and null for a missing file or unsupported extension. On success, the caller owns the created hierarchy: add it to the tree or release it with Free(). Disposing the temporary GltfDocument and GltfState after GenerateScene does not delete the generated model.

For an exported game, separately ensure the source glTF, .bin and images remain accessible: a processed imported resource and a source file for GltfDocument are different dependencies. This example does not accept an exported application build.

Direct .blend import

The filesystem/import/blender/blender_path editor setting specifies the Blender executable. The importer checks its version: the source requires at least 3.0. That minimum does not establish compatibility with every release and every file.

The filesystem/import/blender/enabled project setting controls this importer. It defaults to disabled on Android and web editors: do not depend on invoking an external Blender there. A team using .blend needs Blender available on each machine performing import; a recipient of a prepared glTF does not need Blender.

Diagnose a failure

The loader, GLTF/GLB, shared meshes, coordinates, PBR bindings and alpha modes are accepted in the installed runtime. FBX, OBJ, DAE, automatic .blend import and editor controls were checked against source here, without separate end-to-end execution.