Integrate DRACOLoader with GLTFLoader in Three.js

This article provides a practical guide on integrating DRACOLoader with GLTFLoader in Three.js to load and render highly compressed 3D assets. By combining these two loaders, you can significantly reduce the file size of your 3D models, leading to faster web page loading times and improved performance. You will learn how to set up the loaders, configure the Draco decoder path, and successfully load compressed .gltf or .glb files into your WebGL scene.

Why Use Draco Compression?

Draco is an open-source library developed by Google for compressing and decompressing 3D geometric meshes and point clouds. When applied to GLTF assets, it dramatically decreases the file size of vertices, normals, and texture coordinates. Because browsers cannot natively parse Draco-compressed data, Three.js requires DRACOLoader to decompress the assets on the client side using WebAssembly (WASM) before rendering them.

Step-by-Step Integration

To load Draco-compressed files, you must instantiate both GLTFLoader and DRACOLoader, link them together, and provide the path to the Draco decoder library.

1. Import the Loaders

First, import the necessary modules from the Three.js library. You will need the standard GLTFLoader alongside DRACOLoader.

import * as THREE from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';

2. Configure the Draco Decoder

DRACOLoader relies on external WebAssembly and JavaScript decoder files to perform the heavy lifting of decompression. You must point the loader to the directory containing these decoder files using the setDecoderPath method.

You can host these files locally by copying them from node_modules/three/examples/jsm/libs/draco/ to your public assets folder, or you can use a public Content Delivery Network (CDN) like gstatic:

// Initialize DRACOLoader
const dracoLoader = new DRACOLoader();

// Set the path to the WebAssembly decoder files
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');

3. Connect DRACOLoader to GLTFLoader

Once the DRACOLoader is configured, instantiate the GLTFLoader and pass the Draco loader instance to it using the setDRACOLoader method.

// Initialize GLTFLoader
const gltfLoader = new GLTFLoader();

// Link the loaders
gltfLoader.setDRACOLoader(dracoLoader);

4. Load Your Compressed Model

With the loaders linked, you can load your compressed .gltf or .glb files using the standard load method. The decompression process will happen automatically in the background.

// Initialize your Three.js scene
const scene = new THREE.Scene();

// Load the model
gltfLoader.load(
  'models/compressed_model.glb',
  (gltf) => {
    // Add the loaded model to the scene
    scene.add(gltf.scene);
    console.log('Model loaded successfully');
    
    // Optional: Release decoder resources from memory once loading is complete
    dracoLoader.dispose();
  },
  (xhr) => {
    // Progress callback
    console.log(`${(xhr.loaded / xhr.total * 100).toFixed(2)}% loaded`);
  },
  (error) => {
    // Error callback
    console.error('An error occurred while loading the model:', error);
  }
);

Best Practices for Performance

While Draco compression reduces network transfer times, the decompression process requires CPU power and memory on the user’s device. To ensure the best user experience: