Benefits of Using cgltf for Model Loading in the Equilibrium Engine

Using cgltf for model loading in the Equilibrium Engine provides a minimal, zero-copy glTF 2.0 parser that integrates directly with the ECS and rendering pipeline while maintaining cross-platform compatibility and deterministic error handling.

The Equilibrium Engine leverages cgltf, a lightweight single-header library, to handle 3D asset imports. This choice aligns with the engine's design philosophy of keeping dependencies minimal while supporting modern rendering workflows. Using cgltf for model loading eliminates external runtime dependencies and provides fast, standards-compliant glTF parsing that works seamlessly across the engine's SDL and bgFX foundation.

Minimal Dependency Footprint

cgltf is entirely header-only, which means the Equilibrium Engine avoids pulling in heavy external libraries or dealing with complex linking configurations. The repository contains only a thin wrapper in equilibrium/utils/cgltf_utils.c and equilibrium/utils/cgltf_utils.h, with the core library living in 3rdparty/cgltf/cgltf.h.

This architecture keeps the build tree small and eliminates version-conflict issues common with larger SDKs. Because cgltf has zero external runtime dependencies, the engine remains portable and easy to compile on new targets without resolving complex dependency chains.

Fast, Zero-Copy Parsing

One of the primary advantages of using cgltf for model loading is its zero-copy architecture. The parser works directly on binary GLB and JSON glTF buffers without allocating temporary copies, significantly reducing memory churn and improving load times.

In equilibrium/utils/cgltf_utils.c, the engine calls cgltf_load_buffers to map vertex data into memory, then uses cgltf_accessor_read_* functions to read indices and vertex attributes in place. This approach avoids unnecessary memcpy operations, allowing the engine to stream large scenes efficiently while keeping memory usage predictable.

Full glTF 2.0 Feature Support

cgltf implements the complete glTF 2.0 specification, enabling the Equilibrium Engine to handle modern PBR pipelines without custom extensions. The loader supports meshes, materials, textures, skinning, animations, and extensions including KHR_materials_pbrSpecularGlossiness.

The material loading logic in cgltf_utils.c demonstrates this coverage by reading pbr_metallic_roughness, base_color_texture, and other PBR parameters directly from the cgltf_material struct. This native support means artists can export assets from Blender or other DCC tools and load them immediately without intermediate conversion steps.

Cross-Platform Consistency

Written in pure C, cgltf compiles identically on Windows, macOS, Linux, and embedded targets. This aligns perfectly with the Equilibrium Engine's cross-platform SDL and bgFX foundation.

The same loader code used in launcher/sandbox/bootstrap_system.c runs unchanged across all supported platforms, ensuring that asset loading behavior remains consistent regardless of the operating system. This platform agnosticism is critical for maintaining deterministic behavior in both the editor and runtime environments.

Deterministic Error Handling

cgltf returns explicit cgltf_result codes for every operation, making failure paths straightforward to debug and integrate with the engine's logging system. In equilibrium/utils/cgltf_utils.c, the wrapper checks for cgltf_result_success before proceeding with mesh processing, allowing the engine to fail gracefully when encountering malformed files.

This explicit error model contrasts with exception-based approaches, providing predictable control flow that matches the engine's C-based architecture and enabling precise error messages for asset pipeline debugging.

Low Build Overhead

Because cgltf is a single header, adding or removing the loader does not inflate compile times. The 3rdparty/cgltf directory contains only cgltf.h and a small mikktspace.c helper for tangent generation, keeping the dependency footprint minimal.

Projects that use different asset pipelines can optionally compile out cgltf support without breaking the build system, providing flexibility for specialized deployment targets that might use procedural generation instead of file-based assets.

Easy Integration with ECS and Rendering

The loader works natively with the engine's flecs ECS and bgFX resource wrappers. Functions like group_load, material_load, and process_node in cgltf_utils.c convert cgltf data structures directly into engine-native world_t, Group, and Material structures.

This tight integration eliminates the need for intermediate representation layers, reducing complexity and potential data translation bugs. The loader can iterate over the node hierarchy and immediately populate entity components, as shown in the implementation pattern used by the sandbox launcher.

Implementation Example

Below is a representative pattern from equilibrium/utils/cgltf_utils.c showing how the engine loads glTF assets using cgltf. This implementation handles both .gltf JSON and .glb binary formats while validating data before processing.

bool cgltf_model_load(const char *file, world_t *world) {
    // Parse the glTF file (JSON or binary GLB)
    cgltf_options options = {0};
    cgltf_data *data = NULL;
    if (cgltf_parse_file(&options, file, &data) != cgltf_result_success) return false;

    // Load binary buffers (textures, vertex data)
    if (cgltf_load_buffers(&options, data, file) != cgltf_result_success) {
        cgltf_free(data);
        return false;
    }

    // Validate the glTF hierarchy
    if (cgltf_validate(data) != cgltf_result_success) {
        cgltf_free(data);
        return false;
    }

    // Iterate over scenes → nodes → meshes → primitives
    for (size_t i = 0; i < data->nodes_count; ++i) {
        cgltf_node *node = &data->nodes[i];
        if (node->mesh) process_node(node, world, data);
    }

    cgltf_free(data);
    return true;
}

Key aspects of this implementation include:

• cgltf_parse_file and cgltf_load_buffers handle both file variants automatically
• cgltf_validate rejects malformed assets early in the loading process
• The loop traverses the node graph, delegating to process_node for mesh primitive conversion and material setup

Key Files in the Repository

Understanding the file layout helps when modifying or debugging the loading pipeline:

• equilibrium/utils/cgltf_utils.c – Core loader that parses glTF, extracts meshes and materials, and creates engine resources.
• equilibrium/utils/cgltf_utils.h – Public header exposing cgltf_model_load and helper types.
• 3rdparty/cgltf/cgltf.h – Header-only cgltf library defining glTF data structures and the parsing API.
• launcher/sandbox/bootstrap_system.c – Example usage demonstrating how the sandbox launcher initializes the loading system.
• 3rdparty/cgltf/mikktspace.c – Tangent space generation helper used by the mesh processing pipeline.

Summary

• cgltf provides a single-header, zero-dependency solution for glTF 2.0 loading that keeps the Equilibrium Engine's build system lightweight.
• The parser's zero-copy architecture (cgltf_load_buffers, cgltf_accessor_read_*) minimizes memory overhead and accelerates asset streaming.
• Full specification support for meshes, materials, animations, and PBR extensions enables direct use of modern DCC tool exports.
• Explicit cgltf_result error codes integrate cleanly with the engine's logging for deterministic failure handling.
• Native compatibility with flecs ECS and bgFX rendering allows direct conversion from cgltf structures to engine components in equilibrium/utils/cgltf_utils.c.

Frequently Asked Questions

What makes cgltf different from other glTF loaders?

cgltf is a single-header C library with zero external dependencies, designed specifically for minimal footprint and maximum portability. Unlike larger SDKs that require complex build system integration or runtime libraries, cgltf parses glTF 2.0 files in-place without allocating temporary copies, making it ideal for game engines and real-time applications where binary size and load latency matter.

How does the Equilibrium Engine handle glTF validation?

The engine calls cgltf_validate after parsing and buffer loading in equilibrium/utils/cgltf_utils.c. This function checks the glTF hierarchy for specification compliance before the engine processes nodes, meshes, or materials. If validation fails, the loader returns early and frees allocated memory, preventing malformed assets from reaching the rendering pipeline.

Can cgltf handle both .gltf and .glb file formats?

Yes. The Equilibrium Engine uses cgltf_parse_file and cgltf_load_buffers from 3rdparty/cgltf/cgltf.h to handle both JSON-based .gltf files and binary .glb containers transparently. The same code path processes either format, automatically detecting the file type and mapping buffers accordingly.

Where does tangent generation occur in the loading pipeline?

The engine includes 3rdparty/cgltf/mikktspace.c as a companion to cgltf for generating MikkTSpace tangents. This helper integrates with the mesh processing logic in equilibrium/utils/cgltf_utils.c to compute tangent spaces when the source glTF file does not provide them, ensuring consistent normal mapping across all imported assets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}