Compressed Meshes
The geometry in a GLB file is often most of its size. Compressing it can make the file several times smaller, so it downloads faster, at the cost of decoding it when it loads.
The engine loads GLB and glTF files compressed with either of the two common glTF compression schemes:
| Scheme | glTF extensions | Decoder |
|---|---|---|
| Draco | KHR_draco_mesh_compression | Draco WebAssembly module, run in web workers |
| meshopt | EXT_meshopt_compression, KHR_meshopt_compression | meshoptimizer decoder module |
Neither decoder is part of the engine. You serve the decoder files with your application and tell the engine where they are, as described below. A compressed file loaded without its decoder fails to load.
Choosing a Scheme
Both schemes shrink geometry a lot, but they work differently:
- Draco compresses mesh primitives: vertex positions, normals, texture coordinates and other attributes, and indices. It usually produces the smallest files for static geometry, but decoding is comparatively slow, so the engine decodes it in web workers. Draco does not compress animations or morph targets.
- meshopt compresses the glTF buffer views themselves, so it applies to all binary data in the file: vertex attributes, indices, animation keyframes and morph targets. Files are usually a little larger than Draco's, but decoding is much faster. Compressed meshopt data also compresses further with the gzip or Brotli compression that web servers apply.
Prefer meshopt for animated or skinned models and when load time on slower devices matters, and Draco when the smallest download of static geometry matters most.
Textures are not affected by either scheme. To compress them as well, use Basis textures.
Draco
Creating Draco Files
- gltf-pipeline:
gltf-pipeline -i model.glb -o model-draco.glb -d - glTF-Transform:
gltf-transform draco model.glb model-draco.glb - Blender's glTF exporter, with the Compression option enabled.
- The Editor can compress models with Draco when it imports them. See Mesh Compression in the import settings.
Loading Draco Files
The Draco decoder is a WebAssembly module with a JavaScript glue script. Take the files from a Draco release, or copy the set in the engine's examples, and configure the engine with their URLs before loading any Draco compressed model:
import { WasmModule } from 'playcanvas';
WasmModule.setConfig('DracoDecoderModule', {
glueUrl: 'lib/draco/draco.wasm.js',
wasmUrl: 'lib/draco/draco.wasm.wasm',
fallbackUrl: 'lib/draco/draco.js'
});
// optionally wait for the decoder to load before loading models
await new Promise((resolve) => {
WasmModule.getInstance('DracoDecoderModule', resolve);
});
Alternatively, configure the decoder directly with dracoInitialize, which also sets the number of workers decoding in parallel:
import { dracoInitialize } from 'playcanvas';
dracoInitialize({
jsUrl: 'lib/draco/draco.wasm.js',
wasmUrl: 'lib/draco/draco.wasm.wasm',
numWorkers: 2,
lazyInit: true // start the workers when the first Draco mesh loads
});
Without either, the engine looks for draco.wasm.js and draco.wasm.wasm next to the page.
In the Editor, add the decoder to the project with the Draco Library button in the Rendering settings, and the engine is configured for you.
For a working project, see the Loading Draco Compressed GLBs tutorial.
Meshopt
Meshopt support requires Engine 2.24 or later.
Creating Meshopt Files
- gltfpack:
gltfpack -i model.glb -o model-meshopt.glb -cc. The-coption compresses, and-cccompresses further. gltfpack also quantizes vertex data withKHR_mesh_quantization, which the engine supports. - glTF-Transform:
gltf-transform meshopt model.glb model-meshopt.glb
Loading Meshopt Files
The decoder is meshopt_decoder.mjs from the meshoptimizer JavaScript package. Initialize it with meshoptInitialize before loading any meshopt compressed model. Either pass the URL of the decoder module, which the engine imports the first time a meshopt compressed file loads:
import { meshoptInitialize } from 'playcanvas';
meshoptInitialize({ url: 'lib/meshopt/meshopt_decoder.mjs' });
Or, when you bundle your application, import the decoder from the meshoptimizer npm package and pass it in:
import { MeshoptDecoder } from 'meshoptimizer';
import { meshoptInitialize } from 'playcanvas';
meshoptInitialize({ decoder: MeshoptDecoder });
A relative url resolves against the page, like any other URL in your document. Files using KHR_meshopt_compression need the decoder from meshoptimizer 1.0 or later.
By default the decoder runs on the main thread, which is fast enough for most models. To decode large files without blocking the main thread, set numWorkers to decode on web workers instead:
meshoptInitialize({ url: 'lib/meshopt/meshopt_decoder.mjs', numWorkers: 2 });
Once the decoder is initialized, meshopt compressed models load like any other, as container assets:
import { Asset } from 'playcanvas';
const asset = new Asset('model', 'container', { url: 'models/model-meshopt.glb' });
asset.ready(() => {
const entity = asset.resource.instantiateRenderEntity();
app.root.addChild(entity);
});
app.assets.add(asset);
app.assets.load(asset);
If no decoder was initialized, loading fails with an error saying the buffer view is meshopt compressed and naming meshoptInitialize. The exception is a file that also contains uncompressed fallback data, such as one written by gltfpack with -cf: without a decoder, the engine loads the fallback data instead, and with one, it skips downloading the fallback.