Tutorial 110: Loading glTF 2.0 Models at Runtime

CNA Tutorials  ·  3D Content

CNA can load glTF 2.0 models at runtime, with no conversion step. Support is compiled into every build: there is no CMake option to switch on, and the loader — a vendored copy of cgltf — is always present. This is a departure from XNA, where every asset had to pass through the offline content pipeline first.

Loading a model

Put house.glb in your content root and load it like any other asset. Note the extension is omitted, exactly as in XNA:

// Content/models/house.glb on disk. Load<T> returns the Model by value;
// a failed load throws ContentLoadException, so there is no null to check.
Model house = getContentProperty().Load<Model>("models/house");

// Draw it with the standard XNA Model API
house.Draw(world, view, projection);

Both container forms work: JSON .gltf with external buffers, and binary .glb. External .bin buffers, base64-embedded buffers and images, and PNG/JPEG textures embedded in a buffer view are all handled. Only glTF version 2.0 is accepted — anything else is rejected outright rather than half-loaded.

How ContentManager finds the file

Load<Model>("models/house") tries candidates in a fixed order, and stops at the first hit:

The first row is the one that surprises people. If you are porting an XNA title and its old .xnb models are still in the content tree, dropping a .glb beside them changes nothing — the .xnb keeps winning. Delete it, or load under a different asset name. The same rule now applies to a stale .cnb built by cna-content from an older copy of the model: rebuild it or delete it, or the loose .glb beside it is never read.

Runtime shape and the remaining scale limit

The direct path keeps skinned and unskinned groups together. Model::getSkinsEXTProperty() maps every independent skin to its exact mesh set and palette; the first skin also remains in Model::Tag for compatibility. The scale boundary matters when a file was not authored in glTF's metre units.

• Several independent objects or skins — all arrive in one runtime Model; use SkinsEXT instead of assuming Tag describes every skin.
• A file authored in centimetres — at scale 1.0 the model arrives a hundred times too large.

Use the offline converter when you need a scale multiplier or separately packaged assets per mesh group:

# cna_tool_gltf_to_cnj <input.gltf|.glb> <outDir> <baseName> [unitScale]
cna_tool_gltf_to_cnj assets/city.glb Content/models city 0.01

The tool is built unconditionally with the project, so it is already in your build tree. See Tutorial 111 for the full workflow and what the sidecar files contain. Two build-time alternatives also exist in this snapshot: cna_tool_gltf_to_cnb --unit-scale <f> writes a compiled .cnb with a scale applied, and cna-content build compiles a glTF to .cnb (or .xnb) with no unit-scale option. See Content Pipeline and Tutorial 145.

What is supported

Three boundaries worth knowing

Rigid animation is retained only when Model::Tag is available for it. An unskinned model exposes scene-node clips as ModelAnimationsEXT, and ApplyClipToBonesEXT() poses the corresponding ModelBone hierarchy. In a file that mixes skins with additional rigid tracks, Tag is already occupied by the compatibility SkinningData pointer; those extra rigid tracks are dropped with a named import diagnostic rather than silently.

Two authored UV sets are the representable maximum. Each PBR map selects independently between the first two distinct sampled TEXCOORD sets and keeps its own KHR_texture_transform. A map asking for a third distinct set falls back to packed channel 0 and is named in the import report. See Tutorial 114.

extensionsRequired is enforced. CNA uses one source-owned extension registry for validation and diagnostics. A required extension it does not claim is refused by name; an unknown optional extensionsUsed entry becomes a warning. Some known extensions are deliberately approximated or only partly implemented, and their exact loss is recorded.

Where to go next

• Tutorial 111: The CNJ format and the gltf_to_cnj tool
• Tutorial 112: Skeletal animation from glTF
• Tutorial 145: Build content with cna-content — compile a glTF to .cnb ahead of time
• Tutorial 114: PBR materials
• Model Loading reference