Atlaslog / Field Notes / three.js rendering
Field note · three.js rendering
Model loads completely black with no visible material
Quick answer
GLTFLoader reports success and the progress bar reaches 100%, but the model is a black silhouette that does not change when rotated. MeshStandardMaterial needs light, and the scene either has no light sources or only a dim ambient.
Symptom
- The silhouette is visible, proving the geometry is in the scene, but every face is pure black.
- Rotating the model does not change brightness at all.
- No WebGLRenderer errors appear and the materials are MeshStandardMaterial.
Checklist
- Swap the material for MeshBasicMaterial: if it becomes visible, lighting is the cause.
- Count the lights with scene.children.filter(o => o.isLight).length.
- Check that renderer.outputColorSpace is THREE.SRGBColorSpace.
- Check whether material.color was overwritten with 0x000000.
- Check whether part of the meshes use KHR_materials_unlit.
Fix
Add a HemisphereLight with 0xffffff, 0x444444 and intensity 1.5 plus a DirectionalLight at intensity 2.0 positioned at 50, 80, 30, and set outputColorSpace to SRGBColorSpace with ACESFilmicToneMapping. Mark colour maps only with map.colorSpace = SRGBColorSpace.
Code
gltf.scene.traverse(function (o) {
if (o.isMesh) {
console.log(o.name, o.material.type, o.material.color.getHexString());
}
});var renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;
var scene = new THREE.Scene();
scene.background = new THREE.Color(0x1b1f24);
var hemi = new THREE.HemisphereLight(0xffffff, 0x444444, 1.5);
scene.add(hemi);
var dir = new THREE.DirectionalLight(0xffffff, 2.0);
dir.position.set(50, 80, 30);
scene.add(dir);
var loader = new THREE.GLTFLoader();
loader.load('/models/pump.glb', function (gltf) {
scene.add(gltf.scene);
renderer.render(scene, camera);
});
Watch out
- Setting map.colorSpace to SRGBColorSpace on normal or roughness maps, which must stay linear.
- Raising light intensity to 10 to counter the darkness instead of adding a directional light, which flattens all shading.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Model loads completely black with no visible material. https://www.jingweizhi.com/en/cookbook/three-model-all-black.html (accessed 2026-11-03).