AGENT SKILL

threejs-errors-rendering

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
最近更新
2026-11-06
Stars
★ 0
Forks
0

01 前言 Front Matter

name
threejs-errors-rendering
license
MIT
metadata
{ "author": "OpenAEC-Foundation", "version": "1.0" }
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.
compatibility
Designed for Claude Code. Requires Three.js r160+.

02 资源文件 4

03 SKILL.md 正文

threejs-errors-rendering

Debugging Workflow Checklist

When a Three.js scene does not render correctly, ALWAYS follow this sequence:

  1. Open the browser console -- check for WebGL errors or Three.js warnings
  2. Verify the renderer has a non-zero size (renderer.getSize(new THREE.Vector2()))
  3. Confirm the canvas is in the DOM and visible (not display: none)
  4. Check that renderer.render(scene, camera) is called (in a loop or at least once)
  5. Verify the camera is looking at the scene (position, target, near/far)
  6. Confirm at least one light exists for lit materials
  7. Check material side, visible, opacity, and transparent properties
  8. Verify object visible, layers, and frustumCulled properties
  9. 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 setSize
document.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 = new THREE.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.

Fix:

scene.add(new THREE.AmbientLight(0xffffff, 0.5));
scene.add(new THREE.DirectionalLight(0xffffff, 1));

Cause E: render() is never called

The animation loop is not started, or renderer.render(scene, camera) is missing.

Fix:

function animate() {
  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 = new THREE.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 = new THREE.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).

Diagnosis: Log object.position, object.scale, object.matrixWorld.


Symptom 3: Wrong Colors

Cause A: Color space mismatch

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 textures

const 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.

Fix:

material.color.set(0xff0000);      // Correct
material.color = new THREE.Color(0xff0000); // Correct
// material.color = 0xff0000;      // WRONG -- silently fails

Symptom 4: Z-Fighting (Flickering Surfaces)

Z-fighting occurs when two surfaces overlap at nearly the same depth, causing the depth buffer to alternate between them.

Fix A: Polygon offset

const material = new THREE.MeshStandardMaterial({
  polygonOffset: true,
  polygonOffsetFactor: -1,
  polygonOffsetUnits: -1
});

Fix B: Logarithmic depth buffer

const renderer = new THREE.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
  • Shadow acne (stripes): Increase light.shadow.bias (e.g., -0.005)
  • Peter panning (shadow detached): light.shadow.bias is too large, reduce it
  • Low-res shadows: Increase light.shadow.mapSize.set(2048, 2048)

Symptom 6: WebGL Context Lost

The browser reclaims the WebGL context under memory pressure or GPU reset.

Recovery pattern

renderer.domElement.addEventListener('webglcontextlost', (event) => {
  event.preventDefault(); // ALWAYS prevent default to allow restoration
  cancelAnimationFrame(animationId);
}, false);

renderer.domElement.addEventListener('webglcontextrestored', () => {
  // Re-initialize materials, textures, render targets
  initScene();
  animate();
}, false);

NEVER ignore context loss -- the canvas goes black permanently. ALWAYS add both event listeners.


Symptom 7: needsUpdate Missing

BufferAttribute

After modifying vertex data, the GPU buffer is stale:

positions.array[0] = newX;
positions.needsUpdate = true; // ALWAYS set after modifying attribute data

Material

After changing structural properties (adding/removing maps, changing defines):

material.map = newTexture;
material.needsUpdate = true; // triggers shader recompilation
// NEVER set needsUpdate = true every frame -- causes constant recompilation

Texture

After modifying texture image data:

texture.image = newImage;
texture.needsUpdate = true; // triggers GPU re-upload

InstancedMesh

After setMatrixAt() or setColorAt():

mesh.instanceMatrix.needsUpdate = true; // ALWAYS after setMatrixAt
mesh.instanceColor.needsUpdate = true;  // ALWAYS after setColorAt

Symptom 8: updateProjectionMatrix Required

ALWAYS call camera.updateProjectionMatrix() after changing:

  • camera.fov
  • camera.aspect
  • camera.near
  • camera.far
  • camera.zoom
  • camera.left/right/top/bottom (OrthographicCamera)
window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix(); // NEVER forget this
  renderer.setSize(window.innerWidth, window.innerHeight);
});

Symptom 9: Transparent Object Rendering Issues

Transparent objects render in the wrong order (back-to-front sorting fails).

Fix A: renderOrder

// Force specific rendering order
backgroundMesh.renderOrder = 0;
transparentMesh.renderOrder = 1;
frontMesh.renderOrder = 2;

Fix B: depthWrite

const material = new THREE.MeshStandardMaterial({
  transparent: true,
  opacity: 0.5,
  depthWrite: false // prevents transparent objects from writing to depth buffer
});

Fix C: alphaTest instead of transparency

For textures with hard alpha edges (foliage, fences):

const material = new THREE.MeshStandardMaterial({
  map: leafTexture,
  alphaTest: 0.5, // discards fragments below threshold
  side: THREE.DoubleSide
  // NEVER set transparent: true for hard-edge alpha -- use alphaTest instead
});

Common Console Warnings

Warning Cause Fix
THREE.WebGLRenderer: Texture is not power of two NPOT texture with repeat wrapping Use power-of-two textures or ClampToEdgeWrapping
THREE.WebGLProgram: shader error GLSL compilation failure Check custom shader code for syntax errors
THREE.PropertyBinding: Can not bind to... Animation targets missing property Ensure skeleton/morph targets match the animation clip
THREE.BufferGeometry: .addAttribute() removed Using deprecated API Use setAttribute() instead
GL_INVALID_OPERATION: Feedback loop Reading from a texture that is also a render target Use separate textures for reading and writing

Reference Links

Official Sources

04 同仓库更多 Skills

mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

frontend-slides

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

design-dna

Extract, define, and apply design DNA across three dimensions: design system (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL, 3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user wants to see the full 3-dimension design structure/schema, (2) a user provides images, screenshots, or URLs of reference designs and wants them analyzed into a structured JSON profile covering all three dimensions, (3) a user has a Design DNA JSON and content and wants a design generated from it, or (4) any combination of these phases. Triggers on "design DNA", "extract design style", "analyze design", "design tokens from reference", "generate design from JSON", "design system from screenshot", "design profile", "style guide JSON", "visual effects analysis", "design with effects", "3d design analysis".

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

wireframe

Generate JSON wireframe with HTML preview

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

social-publishing

Schedule and publish social media posts across 13 platforms (X, LinkedIn, Instagram, Facebook Pages, TikTok, Discord, Telegram, YouTube, Reddit, WordPress, Pinterest) via the SocialClaw API. Use when the user wants to publish, schedule, or manage social media content programmatically. Requires SOCIALCLAW_API_KEY.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

hermes-tweet

Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

refactoring-ui

Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.

★ 0