Loading custom 3D models with glTF

Updated: Nov 11, 2024

Overview

Spatial SDK uses glTF (GL Transmission Format) for loading custom 3D models. It is a standard file format for delivering 3D graphics efficiently. A .glb file is the binary version of the .gltf file, which includes textures, geometry, and other assets in a single file, making it convenient for distribution.

Anatomy of a glTF file

In the context of Spatial SDK, you need to know the following:

A glTF file has a scene with a hierarchy of nodes.

Each node can have a transform (translate, rotation, scale) and a mesh.

Each mesh points to some geometry data (vertices and indices) and a material.

Each material specifies some PBR (Physically Based Rendering) properties (roughness/metallicness) and may point to a texture.

Supported formats

The following extensions are supported:

KHR_texture_transform

KHR_texture_basisu

KHR_materials_unlit

Approximate support for KHR_materials_pbrSpecularGlossiness, for displaying some legacy materials.

Sourcing glTF/glb models

Online: There are many options for finding glTFs online. Sketchfab is a popular platform for free and paid high-quality glTF and .glb models. Search for the model you need and download it in .glb format.

Create Your own: If you want to create custom 3D models, software like Blender allows you to design and export your creations in the glTF or .glb format. You can also edit the files you find online and then export them to the .glb for Spatial SDK (even ones in other file formats).

Loading your `.glb`s in Spatial SDK

As described in the 3D Objects page, once you’ve downloaded your asset (say mymodel.glb), copy it to the assets folder of your app (<myapp>/assets/). You can now load it into your app by using the Mesh component:

Entity.create(
    listOf(
        Mesh(
          Uri.parse("mymodel.glb")
        )
    )
)

Tools for working with glTF files

This section contains a list of tools to work with glTF files.

Blender

Blender is a free and open-source 3D creation tool. Although it can be intimidating for beginners, there are lots of high-quality, free learning resources across the Internet.

Importing models

Blender supports importing from many different 3D model types (for example, .obj, .fbx, .dae). You can often import any supported model type and export it to glTF inside Blender.

You can get models and animations from Mixamo, which provides free and realistic character animations. Using models from Mixamo, you can put your character into a walk cycle, or have them do a backflip, without worrying about rigging or hand animating the model yourself. However, Mixamo doesn’t support exporting to glTF. Instead, you can download the animation as an .fbx, import it into Blender, and then export it to glTF.

Exporting as glTF

Blender has a page on its full glTF support. You can export by clicking on File > Export > glTF 2.0 (.glb/.gltf). Exporting as a .glb file is the best option, as it is a bit easier to move between programs.

After you export, try using a glTF standard model viewer to check if you exported the model correctly. It is best to ensure your models look correct in a commonly used viewer.

If your materials do not show up correctly in a standard viewer, make sure you are using the Principled BSDF shader node for them in Blender. Blender uses this shader to know how to export your material properties.

Khronos resources

Khronos, the organization behind the glTF standard, offers several tools and assets for working with glTF files.

Sample models

The community has curated a set of sample glTF/glb files for testing and verifying the correctness of different glTF features. Some of these models are used in our sample apps.

glTF Sample Viewer

Khronos’ glTF Sample Viewer is a reference implementation of a glTF viewer. You can access all the sample models mentioned in the previous section and drag and drop them into any custom models.

VS Code Plugin

CesiumJS has made a useful VS Code plugin for working with glTF files. With this plugin, you can inspect your glTF files with rich code navigation, use a built-in model viewer with multiple reference implementations (CesiumJS, Three.js, and Babylon.js), and debug your models with a hierarchy explorer. The plugin’s information page gives a helpful overview of how to use it.

glTF Transform

glTF Transform is a powerful JS library that processes glTF files. It enables you to read, modify, prune, optimize, and customize your glTF models.

You can use glTF Transform to convert your assets to the correct format for Spatial SDK. In Spatial SDK, you might want to display models without caring about the collision data. You can use a script to strip out all the collision data before giving the files to Spatial SDK:

function customTransform(options) {
  return async document => {
    for (const nodes of document.getRoot().listNodes()) {
      // remove any node marked as a collider or boundary
      // these are not meant to be visible in the actual game
      if (nodes.getExtras().collider == 1 || nodes.getExtras().boundary == 1) {
        nodes.dispose();
        continue;
      }
      // remove any nodes with ".gltf" in the name, used to reference other files
      if (nodes.getName().indexOf('.gltf') != -1) {
        nodes.dispose();
        continue;
      }
    }
  };
}

If you don’t want to run these scripts locally, check out the gltf.report tool below.

gltf.report

gltf.report is a useful online tool for investigating and profiling your models. One of its most valuable features is the integration with glTF transform, which allows you to run your code on your imported model.

Their default glTF transform script can reduce the size of models by pruning the file and resizing textures to a more appropriate size for mobile. This is a good option for reducing the size of your assets in your app.