Use when a Three.js scene renders incorrectly: black screen, invisible objects, wrong colors, z-fighting, or broken shadows. Prevents the common mistake of wrong color space, missing material.side, or forgetting updateProjectionMatrix. Covers all common rendering errors with diagnosis steps and fix patterns. Keywords: black screen, invisible, wrong color, z-fighting, shadow artifact, rendering error, debug, nothing visible, dark, broken, nothing shows, model not appearing, screen is blank.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
threejs-errors-rendering
description
Use when a Three.js scene renders incorrectly: black screen, invisible objects, wrong colors, z-fighting, or broken shadows. Prevents the common mistake of wrong color space, missing material.side, or forgetting updateProjectionMatrix. Covers all common rendering errors with diagnosis steps and fix patterns. Keywords: black screen, invisible, wrong color, z-fighting, shadow artifact, rendering error, debug, nothing visible, dark, broken, nothing shows, model not appearing, screen is blank.
license
MIT
compatibility
Designed for Claude Code. Requires Three.js r160+.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
threejs-errors-rendering
Debugging Workflow Checklist
When a Three.js scene does not render correctly, ALWAYS follow this sequence:
Open the browser console -- check for WebGL errors or Three.js warnings
Verify the renderer has a non-zero size (renderer.getSize(new THREE.Vector2()))
Confirm the canvas is in the DOM and visible (not display: none)
Check that renderer.render(scene, camera) is called (in a loop or at least once)
Verify the camera is looking at the scene (position, target, near/far)
Confirm at least one light exists for lit materials
Check material side, visible, opacity, and transparent properties
Verify object visible, layers, and frustumCulled properties
Inspect color space settings on renderer and textures
Symptom 1: Black Screen (Nothing Visible)
Cause A: Renderer has zero size
The canvas has 0x0 dimensions. This happens when setSize() is called before the container is in the DOM or when the container has no CSS dimensions.
Fix:
// ALWAYS ensure the container is in the DOM and has dimensions before setSizedocument.body.appendChild(renderer.domElement);
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
Cause B: Camera is inside the object or facing away
The camera is at (0, 0, 0) and the object is also at (0, 0, 0), so the camera is inside the mesh. Or the camera is pointing in the wrong direction.
Fix:
camera.position.set(0, 2, 5); // ALWAYS move camera away from origin
camera.lookAt(0, 0, 0);
Cause C: Near/far clipping planes exclude the object
Objects closer than near or farther than far are clipped. Default PerspectiveCamera near is 0.1, far is 2000.
Fix:
const camera = newTHREE.PerspectiveCamera(75, aspect, 0.1, 1000);
// NEVER set near to 0 -- causes z-fighting and depth buffer issues// ALWAYS keep far/near ratio below 100000 for stable depth precision
Cause D: No light in the scene
MeshStandardMaterial, MeshPhongMaterial, and MeshLambertMaterial require lights. Without light, they render black. MeshBasicMaterial does NOT require lights.
The animation loop is not started, or renderer.render(scene, camera) is missing.
Fix:
functionanimate() {
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
animate(); // ALWAYS call the function to start the loop
Cause F: Scene or camera is wrong reference
Passing an empty scene or an uninitialized camera to render().
Diagnosis: Log scene.children.length and camera.type before the render call.
Symptom 2: Invisible Objects
Cause A: Wrong material side
Back faces are culled by default (FrontSide). If the camera sees the back of a plane or thin geometry, it is invisible.
Fix:
const material = newTHREE.MeshStandardMaterial({
side: THREE.DoubleSide// ALWAYS use for planes, leaves, thin objects
});
Cause B: opacity without transparent
Setting opacity: 0.5 without transparent: true has NO effect.
Fix:
const material = newTHREE.MeshStandardMaterial({
opacity: 0.5,
transparent: true// ALWAYS pair with opacity < 1
});
Cause C: Object on a different layer
The camera and the object MUST share at least one layer. By default both are on layer 0. If the object is moved to another layer, the camera must enable that layer too.
Fix:
object.layers.set(1);
camera.layers.enable(1); // camera must see layer 1
Cause D: visible is false (inherited)
visible = false on a parent makes ALL descendants invisible. Check the full parent chain.
Diagnosis:
let node = object;
while (node) {
if (!node.visible) console.log('Hidden ancestor:', node.name || node.type);
node = node.parent;
}
Cause E: frustumCulled incorrectly
If the bounding sphere is wrong (e.g., after manual vertex changes without computeBoundingSphere()), the object may be culled even when visible.
Fix:
geometry.computeBoundingSphere(); // ALWAYS call after modifying positions// Or disable frustum culling for objects that must always render:
mesh.frustumCulled = false;
Cause F: Object at wrong position or scale 0
Object is at a position far from the camera, or scale.set(0, 0, 0).
This is the MOST COMMON color error in Three.js r160+.
Rules:
Color/diffuse/emissive textures: ALWAYS set texture.colorSpace = THREE.SRGBColorSpace
Data textures (normal, roughness, metalness, AO, displacement): ALWAYS leave as THREE.LinearSRGBColorSpace
Renderer output: renderer.outputColorSpace = THREE.SRGBColorSpace (default in r160+)
Symptoms of wrong color space:
Washed-out colors: data texture incorrectly set to SRGBColorSpace (double gamma)
Over-saturated colors: color texture left in LinearSRGBColorSpace (no gamma applied)
Fix:
const texture = await loader.loadAsync('diffuse.png');
texture.colorSpace = THREE.SRGBColorSpace; // for color texturesconst normalMap = await loader.loadAsync('normal.png');
// NEVER set SRGBColorSpace on normal maps -- corrupts surface data
Cause B: Tone mapping not configured
Without tone mapping, HDR values are clamped, producing flat or incorrect colors.
Fix:
renderer.toneMapping = THREE.ACESFilmicToneMapping; // or AgXToneMapping
renderer.toneMappingExposure = 1.0;
Cause C: Material color set after construction ignored
material.color.set() works, but material.color = new THREE.Color() after construction also works. The common mistake is setting color as a hex number directly: material.color = 0xff0000 does NOT work.
const renderer = newTHREE.WebGLRenderer({ logarithmicDepthBuffer: true });
// Trades performance for better depth precision across large near/far ranges// NEVER use with EffectComposer post-processing -- causes artifacts
Fix C: Position offset
Move one surface slightly:
decalMesh.position.z += 0.01; // small offset to prevent overlap
Fix D: Reduce near/far ratio
// ALWAYS keep the near plane as large as possible
camera.near = 1; // not 0.001
camera.far = 1000; // not 1000000
camera.updateProjectionMatrix();
Symptom 5: Shadow Artifacts
For complete shadow configuration, see the threejs-impl-shadows skill. Common quick fixes:
No shadows at all:renderer.shadowMap.enabled = true, light.castShadow = true, mesh.castShadow = true, ground.receiveShadow = true
