Key takeaways
- Always serve Three.js HTML and .glb files over a local or remote HTTP server; opening file:// URLs directly triggers browser CORS and fetch failures.
- Use Three.js GLTFLoader with self-contained .glb assets, then verify Y-up orientation, metre dimensions, and base alignment at y = 0 before debugging shaders.
- Visual meshes have zero built-in physics: pair rendered transforms with explicit collision boxes, compound doorway bounds, or sampled terrain heightfields.
- Prevent WebGL memory leaks on scene switches by traversing removed objects to dispose BufferGeometry, Material, Texture, and decoded ImageBitmap instances.
1. Start with a runnable local scene pack
Download one free CC0 case zip from SceneCrate, extract it, and run a local static HTTP server in its directory instead of double-clicking index.html from disk. Browser security rules block ES module imports and binary fetch() calls over file:// URLs.
Each pack is a self-contained Three.js browser example (including models/standard.glb, models/lightweight.glb, scene.json, and report.json) rather than a Unity prefab or Godot project. Start with Shipping Crate (12 triangles, 1 box collider) to verify your loader pipeline before moving to Cedarwatch Cabin or Highland Trail.
2. Load a self-contained GLB with GLTFLoader
Inside a project that already initializes a WebGLRenderer, Scene, PerspectiveCamera, and lights, import GLTFLoader from Three.js addons to load your binary GLB asynchronously. Host the .glb inside your own static assets folder and verify HTTP 200 and Content-Type before troubleshooting Three.js materials.
import { Box3, Vector3 } from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
const loader = new GLTFLoader();
try {
const gltf = await loader.loadAsync('/assets/crate.glb');
const bounds = new Box3().setFromObject(gltf.scene);
const size = bounds.getSize(new Vector3());
console.log('Metre size:', size.toArray(), 'Base Y:', bounds.min.y);
scene.add(gltf.scene);
} catch (error) {
console.error('Model could not be loaded', error);
}- Verify HTTP status 200 and binary response length in the browser Network tab first.
- Measure Box3 size and min.y in metres so props sit on y = 0 rather than floating or clipping.
- Provide hemisphere or environment lighting so metallic-roughness PBR materials do not render black.
3. Connect player movement and collision explicitly
Adding gltf.scene to Three.js only draws triangles; a player controller will walk straight through walls unless collision data is attached. SceneCrate prop packs supply conservative axis-aligned box bounds, building packs supply arrays of local wall and furniture boxes (17 on Cedarwatch Cabin, 28 on Mossgate Passage), and terrain packs supply a 49 × 49 heightfield grid.
Apply identical translation, rotation, and scale to both the rendered mesh and its collision representation. When swapping an asset, always load its matching collision JSON; reusing a single prop bounding box on a cabin seals its 1.64 m front doorway.
4. Dispose geometries, textures, and stale async loads
Calling scene.remove(object) detaches a node from the scene graph, but WebGL vertex buffers, materials, and GPU textures stay allocated until you explicitly call geometry.dispose(), material.dispose(), and texture.dispose(). If textures use ImageBitmap sources, call close() when no other material shares them.
Track an abort controller or monotonic request counter whenever players switch levels or toggle between Standard and Lightweight tiers rapidly, ensuring a slow earlier loadAsync() resolution never overwrites the active scene or leaks unmounted GPU buffers.
Frequently asked questions
Why does GLTFLoader fail with a CORS or network error when opening HTML from disk?
Modern browsers block JavaScript module scripts and fetch() requests over the file:// protocol. Serve your project folder over localhost using Vite, python3 -m http.server, or npx serve.
Why does my PBR GLB model look completely black in Three.js?
glTF 2.0 PBR materials use MeshStandardMaterial or MeshPhysicalMaterial. Without ambient/hemisphere light, directional lights, or a scene.environment map, metallic surfaces have nothing to reflect and render black.
Does scene.remove(gltf.scene) free GPU memory in Three.js?
No. You must traverse the removed hierarchy and call dispose() on every unshared BufferGeometry, Material, and Texture (including base color, normal, roughness/metallic, and occlusion maps).
How does glTF handle coordinate axes compared to Blender?
glTF 2.0 defines right-handed coordinates in metres with +Y up and +Z forward. Blender uses Z up internally, so exporting with Blender’s standard glTF +Y Up option converts axes to match Three.js.