[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7EHXWR2ST6EXV5XCPEFK5YN":3,"skill-same:01M7EHXWR2ST6EXV5XCPEFK5YN":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":13,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":33,"install":34,"resources":47},"01M7EHXWR2ST6EXV5XCPEFK5YN","threejs-errors-rendering",null,"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.","mhyahya854\u002FAI-Second-Brain_Universal-Rules","mhyahya854","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F194078115?v=4","01M7EGSP2M9T858SDHJMXQ257Y","01M7EGSP3N6HN6879SVDPMD4DZ",0,"MIT","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002FImpertio-Studio\u002FThree.js-Claude-Skill-Package\u002Fthreejs-errors-rendering\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: threejs-errors-rendering\ndescription: >\n  Use when a Three.js scene renders incorrectly: black screen, invisible\n  objects, wrong colors, z-fighting, or broken shadows. Prevents the\n  common mistake of wrong color space, missing material.side, or\n  forgetting updateProjectionMatrix. Covers all common rendering errors\n  with diagnosis steps and fix patterns.\n  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.\nlicense: MIT\ncompatibility: \"Designed for Claude Code. Requires Three.js r160+.\"\nmetadata:\n  author: OpenAEC-Foundation\n  version: \"1.0\"\n---\n\n# threejs-errors-rendering\n\n## Debugging Workflow Checklist\n\nWhen a Three.js scene does not render correctly, ALWAYS follow this sequence:\n\n1. Open the browser console -- check for WebGL errors or Three.js warnings\n2. Verify the renderer has a non-zero size (`renderer.getSize(new THREE.Vector2())`)\n3. Confirm the canvas is in the DOM and visible (not `display: none`)\n4. Check that `renderer.render(scene, camera)` is called (in a loop or at least once)\n5. Verify the camera is looking at the scene (position, target, near\u002Ffar)\n6. Confirm at least one light exists for lit materials\n7. Check material `side`, `visible`, `opacity`, and `transparent` properties\n8. Verify object `visible`, `layers`, and `frustumCulled` properties\n9. Inspect color space settings on renderer and textures\n\n---\n\n## Symptom 1: Black Screen (Nothing Visible)\n\n### Cause A: Renderer has zero size\n\nThe 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.\n\n**Fix:**\n```javascript\n\u002F\u002F ALWAYS ensure the container is in the DOM and has dimensions before setSize\ndocument.body.appendChild(renderer.domElement);\nrenderer.setSize(window.innerWidth, window.innerHeight);\nrenderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));\n```\n\n### Cause B: Camera is inside the object or facing away\n\nThe 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.\n\n**Fix:**\n```javascript\ncamera.position.set(0, 2, 5); \u002F\u002F ALWAYS move camera away from origin\ncamera.lookAt(0, 0, 0);\n```\n\n### Cause C: Near\u002Ffar clipping planes exclude the object\n\nObjects closer than `near` or farther than `far` are clipped. Default PerspectiveCamera near is `0.1`, far is `2000`.\n\n**Fix:**\n```javascript\nconst camera = new THREE.PerspectiveCamera(75, aspect, 0.1, 1000);\n\u002F\u002F NEVER set near to 0 -- causes z-fighting and depth buffer issues\n\u002F\u002F ALWAYS keep far\u002Fnear ratio below 100000 for stable depth precision\n```\n\n### Cause D: No light in the scene\n\n`MeshStandardMaterial`, `MeshPhongMaterial`, and `MeshLambertMaterial` require lights. Without light, they render black. `MeshBasicMaterial` does NOT require lights.\n\n**Fix:**\n```javascript\nscene.add(new THREE.AmbientLight(0xffffff, 0.5));\nscene.add(new THREE.DirectionalLight(0xffffff, 1));\n```\n\n### Cause E: render() is never called\n\nThe animation loop is not started, or `renderer.render(scene, camera)` is missing.\n\n**Fix:**\n```javascript\nfunction animate() {\n  requestAnimationFrame(animate);\n  renderer.render(scene, camera);\n}\nanimate(); \u002F\u002F ALWAYS call the function to start the loop\n```\n\n### Cause F: Scene or camera is wrong reference\n\nPassing an empty scene or an uninitialized camera to `render()`.\n\n**Diagnosis:** Log `scene.children.length` and `camera.type` before the render call.\n\n---\n\n## Symptom 2: Invisible Objects\n\n### Cause A: Wrong material side\n\nBack faces are culled by default (`FrontSide`). If the camera sees the back of a plane or thin geometry, it is invisible.\n\n**Fix:**\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  side: THREE.DoubleSide \u002F\u002F ALWAYS use for planes, leaves, thin objects\n});\n```\n\n### Cause B: opacity without transparent\n\nSetting `opacity: 0.5` without `transparent: true` has NO effect.\n\n**Fix:**\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  opacity: 0.5,\n  transparent: true \u002F\u002F ALWAYS pair with opacity \u003C 1\n});\n```\n\n### Cause C: Object on a different layer\n\nThe 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.\n\n**Fix:**\n```javascript\nobject.layers.set(1);\ncamera.layers.enable(1); \u002F\u002F camera must see layer 1\n```\n\n### Cause D: visible is false (inherited)\n\n`visible = false` on a parent makes ALL descendants invisible. Check the full parent chain.\n\n**Diagnosis:**\n```javascript\nlet node = object;\nwhile (node) {\n  if (!node.visible) console.log('Hidden ancestor:', node.name || node.type);\n  node = node.parent;\n}\n```\n\n### Cause E: frustumCulled incorrectly\n\nIf the bounding sphere is wrong (e.g., after manual vertex changes without `computeBoundingSphere()`), the object may be culled even when visible.\n\n**Fix:**\n```javascript\ngeometry.computeBoundingSphere(); \u002F\u002F ALWAYS call after modifying positions\n\u002F\u002F Or disable frustum culling for objects that must always render:\nmesh.frustumCulled = false;\n```\n\n### Cause F: Object at wrong position or scale 0\n\nObject is at a position far from the camera, or `scale.set(0, 0, 0)`.\n\n**Diagnosis:** Log `object.position`, `object.scale`, `object.matrixWorld`.\n\n---\n\n## Symptom 3: Wrong Colors\n\n### Cause A: Color space mismatch\n\nThis is the MOST COMMON color error in Three.js r160+.\n\n**Rules:**\n- Color\u002Fdiffuse\u002Femissive textures: ALWAYS set `texture.colorSpace = THREE.SRGBColorSpace`\n- Data textures (normal, roughness, metalness, AO, displacement): ALWAYS leave as `THREE.LinearSRGBColorSpace`\n- Renderer output: `renderer.outputColorSpace = THREE.SRGBColorSpace` (default in r160+)\n\n**Symptoms of wrong color space:**\n- Washed-out colors: data texture incorrectly set to `SRGBColorSpace` (double gamma)\n- Over-saturated colors: color texture left in `LinearSRGBColorSpace` (no gamma applied)\n\n**Fix:**\n```javascript\nconst texture = await loader.loadAsync('diffuse.png');\ntexture.colorSpace = THREE.SRGBColorSpace; \u002F\u002F for color textures\n\nconst normalMap = await loader.loadAsync('normal.png');\n\u002F\u002F NEVER set SRGBColorSpace on normal maps -- corrupts surface data\n```\n\n### Cause B: Tone mapping not configured\n\nWithout tone mapping, HDR values are clamped, producing flat or incorrect colors.\n\n**Fix:**\n```javascript\nrenderer.toneMapping = THREE.ACESFilmicToneMapping; \u002F\u002F or AgXToneMapping\nrenderer.toneMappingExposure = 1.0;\n```\n\n### Cause C: Material color set after construction ignored\n\n`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.\n\n**Fix:**\n```javascript\nmaterial.color.set(0xff0000);      \u002F\u002F Correct\nmaterial.color = new THREE.Color(0xff0000); \u002F\u002F Correct\n\u002F\u002F material.color = 0xff0000;      \u002F\u002F WRONG -- silently fails\n```\n\n---\n\n## Symptom 4: Z-Fighting (Flickering Surfaces)\n\nZ-fighting occurs when two surfaces overlap at nearly the same depth, causing the depth buffer to alternate between them.\n\n### Fix A: Polygon offset\n\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  polygonOffset: true,\n  polygonOffsetFactor: -1,\n  polygonOffsetUnits: -1\n});\n```\n\n### Fix B: Logarithmic depth buffer\n\n```javascript\nconst renderer = new THREE.WebGLRenderer({ logarithmicDepthBuffer: true });\n\u002F\u002F Trades performance for better depth precision across large near\u002Ffar ranges\n\u002F\u002F NEVER use with EffectComposer post-processing -- causes artifacts\n```\n\n### Fix C: Position offset\n\nMove one surface slightly:\n```javascript\ndecalMesh.position.z += 0.01; \u002F\u002F small offset to prevent overlap\n```\n\n### Fix D: Reduce near\u002Ffar ratio\n\n```javascript\n\u002F\u002F ALWAYS keep the near plane as large as possible\ncamera.near = 1;    \u002F\u002F not 0.001\ncamera.far = 1000;  \u002F\u002F not 1000000\ncamera.updateProjectionMatrix();\n```\n\n---\n\n## Symptom 5: Shadow Artifacts\n\nFor complete shadow configuration, see the `threejs-impl-shadows` skill. Common quick fixes:\n\n- **No shadows at all:** `renderer.shadowMap.enabled = true`, `light.castShadow = true`, `mesh.castShadow = true`, `ground.receiveShadow = true`\n- **Shadow acne (stripes):** Increase `light.shadow.bias` (e.g., `-0.005`)\n- **Peter panning (shadow detached):** `light.shadow.bias` is too large, reduce it\n- **Low-res shadows:** Increase `light.shadow.mapSize.set(2048, 2048)`\n\n---\n\n## Symptom 6: WebGL Context Lost\n\nThe browser reclaims the WebGL context under memory pressure or GPU reset.\n\n### Recovery pattern\n\n```javascript\nrenderer.domElement.addEventListener('webglcontextlost', (event) => {\n  event.preventDefault(); \u002F\u002F ALWAYS prevent default to allow restoration\n  cancelAnimationFrame(animationId);\n}, false);\n\nrenderer.domElement.addEventListener('webglcontextrestored', () => {\n  \u002F\u002F Re-initialize materials, textures, render targets\n  initScene();\n  animate();\n}, false);\n```\n\n**NEVER** ignore context loss -- the canvas goes black permanently. ALWAYS add both event listeners.\n\n---\n\n## Symptom 7: needsUpdate Missing\n\n### BufferAttribute\n\nAfter modifying vertex data, the GPU buffer is stale:\n```javascript\npositions.array[0] = newX;\npositions.needsUpdate = true; \u002F\u002F ALWAYS set after modifying attribute data\n```\n\n### Material\n\nAfter changing structural properties (adding\u002Fremoving maps, changing `defines`):\n```javascript\nmaterial.map = newTexture;\nmaterial.needsUpdate = true; \u002F\u002F triggers shader recompilation\n\u002F\u002F NEVER set needsUpdate = true every frame -- causes constant recompilation\n```\n\n### Texture\n\nAfter modifying texture image data:\n```javascript\ntexture.image = newImage;\ntexture.needsUpdate = true; \u002F\u002F triggers GPU re-upload\n```\n\n### InstancedMesh\n\nAfter `setMatrixAt()` or `setColorAt()`:\n```javascript\nmesh.instanceMatrix.needsUpdate = true; \u002F\u002F ALWAYS after setMatrixAt\nmesh.instanceColor.needsUpdate = true;  \u002F\u002F ALWAYS after setColorAt\n```\n\n---\n\n## Symptom 8: updateProjectionMatrix Required\n\nALWAYS call `camera.updateProjectionMatrix()` after changing:\n\n- `camera.fov`\n- `camera.aspect`\n- `camera.near`\n- `camera.far`\n- `camera.zoom`\n- `camera.left\u002Fright\u002Ftop\u002Fbottom` (OrthographicCamera)\n\n```javascript\nwindow.addEventListener('resize', () => {\n  camera.aspect = window.innerWidth \u002F window.innerHeight;\n  camera.updateProjectionMatrix(); \u002F\u002F NEVER forget this\n  renderer.setSize(window.innerWidth, window.innerHeight);\n});\n```\n\n---\n\n## Symptom 9: Transparent Object Rendering Issues\n\nTransparent objects render in the wrong order (back-to-front sorting fails).\n\n### Fix A: renderOrder\n\n```javascript\n\u002F\u002F Force specific rendering order\nbackgroundMesh.renderOrder = 0;\ntransparentMesh.renderOrder = 1;\nfrontMesh.renderOrder = 2;\n```\n\n### Fix B: depthWrite\n\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  transparent: true,\n  opacity: 0.5,\n  depthWrite: false \u002F\u002F prevents transparent objects from writing to depth buffer\n});\n```\n\n### Fix C: alphaTest instead of transparency\n\nFor textures with hard alpha edges (foliage, fences):\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  map: leafTexture,\n  alphaTest: 0.5, \u002F\u002F discards fragments below threshold\n  side: THREE.DoubleSide\n  \u002F\u002F NEVER set transparent: true for hard-edge alpha -- use alphaTest instead\n});\n```\n\n---\n\n## Common Console Warnings\n\n| Warning | Cause | Fix |\n|---------|-------|-----|\n| `THREE.WebGLRenderer: Texture is not power of two` | NPOT texture with repeat wrapping | Use power-of-two textures or `ClampToEdgeWrapping` |\n| `THREE.WebGLProgram: shader error` | GLSL compilation failure | Check custom shader code for syntax errors |\n| `THREE.PropertyBinding: Can not bind to...` | Animation targets missing property | Ensure skeleton\u002Fmorph targets match the animation clip |\n| `THREE.BufferGeometry: .addAttribute() removed` | Using deprecated API | Use `setAttribute()` instead |\n| `GL_INVALID_OPERATION: Feedback loop` | Reading from a texture that is also a render target | Use separate textures for reading and writing |\n\n---\n\n## Reference Links\n\n- [references\u002Fmethods.md](references\u002Fmethods.md) -- Fix-related API signatures\n- [references\u002Fexamples.md](references\u002Fexamples.md) -- Complete fix patterns\n- [references\u002Fanti-patterns.md](references\u002Fanti-patterns.md) -- What NOT to do\n\n### Official Sources\n\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Frenderers\u002FWebGLRenderer\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fcameras\u002FPerspectiveCamera\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fmaterials\u002FMaterial\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fcore\u002FObject3D\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fcore\u002FBufferAttribute\n","# threejs-errors-rendering\n\n## Debugging Workflow Checklist\n\nWhen a Three.js scene does not render correctly, ALWAYS follow this sequence:\n\n1. Open the browser console -- check for WebGL errors or Three.js warnings\n2. Verify the renderer has a non-zero size (`renderer.getSize(new THREE.Vector2())`)\n3. Confirm the canvas is in the DOM and visible (not `display: none`)\n4. Check that `renderer.render(scene, camera)` is called (in a loop or at least once)\n5. Verify the camera is looking at the scene (position, target, near\u002Ffar)\n6. Confirm at least one light exists for lit materials\n7. Check material `side`, `visible`, `opacity`, and `transparent` properties\n8. Verify object `visible`, `layers`, and `frustumCulled` properties\n9. Inspect color space settings on renderer and textures\n\n---\n\n## Symptom 1: Black Screen (Nothing Visible)\n\n### Cause A: Renderer has zero size\n\nThe 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.\n\n**Fix:**\n```javascript\n\u002F\u002F ALWAYS ensure the container is in the DOM and has dimensions before setSize\ndocument.body.appendChild(renderer.domElement);\nrenderer.setSize(window.innerWidth, window.innerHeight);\nrenderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));\n```\n\n### Cause B: Camera is inside the object or facing away\n\nThe 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.\n\n**Fix:**\n```javascript\ncamera.position.set(0, 2, 5); \u002F\u002F ALWAYS move camera away from origin\ncamera.lookAt(0, 0, 0);\n```\n\n### Cause C: Near\u002Ffar clipping planes exclude the object\n\nObjects closer than `near` or farther than `far` are clipped. Default PerspectiveCamera near is `0.1`, far is `2000`.\n\n**Fix:**\n```javascript\nconst camera = new THREE.PerspectiveCamera(75, aspect, 0.1, 1000);\n\u002F\u002F NEVER set near to 0 -- causes z-fighting and depth buffer issues\n\u002F\u002F ALWAYS keep far\u002Fnear ratio below 100000 for stable depth precision\n```\n\n### Cause D: No light in the scene\n\n`MeshStandardMaterial`, `MeshPhongMaterial`, and `MeshLambertMaterial` require lights. Without light, they render black. `MeshBasicMaterial` does NOT require lights.\n\n**Fix:**\n```javascript\nscene.add(new THREE.AmbientLight(0xffffff, 0.5));\nscene.add(new THREE.DirectionalLight(0xffffff, 1));\n```\n\n### Cause E: render() is never called\n\nThe animation loop is not started, or `renderer.render(scene, camera)` is missing.\n\n**Fix:**\n```javascript\nfunction animate() {\n  requestAnimationFrame(animate);\n  renderer.render(scene, camera);\n}\nanimate(); \u002F\u002F ALWAYS call the function to start the loop\n```\n\n### Cause F: Scene or camera is wrong reference\n\nPassing an empty scene or an uninitialized camera to `render()`.\n\n**Diagnosis:** Log `scene.children.length` and `camera.type` before the render call.\n\n---\n\n## Symptom 2: Invisible Objects\n\n### Cause A: Wrong material side\n\nBack faces are culled by default (`FrontSide`). If the camera sees the back of a plane or thin geometry, it is invisible.\n\n**Fix:**\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  side: THREE.DoubleSide \u002F\u002F ALWAYS use for planes, leaves, thin objects\n});\n```\n\n### Cause B: opacity without transparent\n\nSetting `opacity: 0.5` without `transparent: true` has NO effect.\n\n**Fix:**\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  opacity: 0.5,\n  transparent: true \u002F\u002F ALWAYS pair with opacity \u003C 1\n});\n```\n\n### Cause C: Object on a different layer\n\nThe 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.\n\n**Fix:**\n```javascript\nobject.layers.set(1);\ncamera.layers.enable(1); \u002F\u002F camera must see layer 1\n```\n\n### Cause D: visible is false (inherited)\n\n`visible = false` on a parent makes ALL descendants invisible. Check the full parent chain.\n\n**Diagnosis:**\n```javascript\nlet node = object;\nwhile (node) {\n  if (!node.visible) console.log('Hidden ancestor:', node.name || node.type);\n  node = node.parent;\n}\n```\n\n### Cause E: frustumCulled incorrectly\n\nIf the bounding sphere is wrong (e.g., after manual vertex changes without `computeBoundingSphere()`), the object may be culled even when visible.\n\n**Fix:**\n```javascript\ngeometry.computeBoundingSphere(); \u002F\u002F ALWAYS call after modifying positions\n\u002F\u002F Or disable frustum culling for objects that must always render:\nmesh.frustumCulled = false;\n```\n\n### Cause F: Object at wrong position or scale 0\n\nObject is at a position far from the camera, or `scale.set(0, 0, 0)`.\n\n**Diagnosis:** Log `object.position`, `object.scale`, `object.matrixWorld`.\n\n---\n\n## Symptom 3: Wrong Colors\n\n### Cause A: Color space mismatch\n\nThis is the MOST COMMON color error in Three.js r160+.\n\n**Rules:**\n- Color\u002Fdiffuse\u002Femissive textures: ALWAYS set `texture.colorSpace = THREE.SRGBColorSpace`\n- Data textures (normal, roughness, metalness, AO, displacement): ALWAYS leave as `THREE.LinearSRGBColorSpace`\n- Renderer output: `renderer.outputColorSpace = THREE.SRGBColorSpace` (default in r160+)\n\n**Symptoms of wrong color space:**\n- Washed-out colors: data texture incorrectly set to `SRGBColorSpace` (double gamma)\n- Over-saturated colors: color texture left in `LinearSRGBColorSpace` (no gamma applied)\n\n**Fix:**\n```javascript\nconst texture = await loader.loadAsync('diffuse.png');\ntexture.colorSpace = THREE.SRGBColorSpace; \u002F\u002F for color textures\n\nconst normalMap = await loader.loadAsync('normal.png');\n\u002F\u002F NEVER set SRGBColorSpace on normal maps -- corrupts surface data\n```\n\n### Cause B: Tone mapping not configured\n\nWithout tone mapping, HDR values are clamped, producing flat or incorrect colors.\n\n**Fix:**\n```javascript\nrenderer.toneMapping = THREE.ACESFilmicToneMapping; \u002F\u002F or AgXToneMapping\nrenderer.toneMappingExposure = 1.0;\n```\n\n### Cause C: Material color set after construction ignored\n\n`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.\n\n**Fix:**\n```javascript\nmaterial.color.set(0xff0000);      \u002F\u002F Correct\nmaterial.color = new THREE.Color(0xff0000); \u002F\u002F Correct\n\u002F\u002F material.color = 0xff0000;      \u002F\u002F WRONG -- silently fails\n```\n\n---\n\n## Symptom 4: Z-Fighting (Flickering Surfaces)\n\nZ-fighting occurs when two surfaces overlap at nearly the same depth, causing the depth buffer to alternate between them.\n\n### Fix A: Polygon offset\n\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  polygonOffset: true,\n  polygonOffsetFactor: -1,\n  polygonOffsetUnits: -1\n});\n```\n\n### Fix B: Logarithmic depth buffer\n\n```javascript\nconst renderer = new THREE.WebGLRenderer({ logarithmicDepthBuffer: true });\n\u002F\u002F Trades performance for better depth precision across large near\u002Ffar ranges\n\u002F\u002F NEVER use with EffectComposer post-processing -- causes artifacts\n```\n\n### Fix C: Position offset\n\nMove one surface slightly:\n```javascript\ndecalMesh.position.z += 0.01; \u002F\u002F small offset to prevent overlap\n```\n\n### Fix D: Reduce near\u002Ffar ratio\n\n```javascript\n\u002F\u002F ALWAYS keep the near plane as large as possible\ncamera.near = 1;    \u002F\u002F not 0.001\ncamera.far = 1000;  \u002F\u002F not 1000000\ncamera.updateProjectionMatrix();\n```\n\n---\n\n## Symptom 5: Shadow Artifacts\n\nFor complete shadow configuration, see the `threejs-impl-shadows` skill. Common quick fixes:\n\n- **No shadows at all:** `renderer.shadowMap.enabled = true`, `light.castShadow = true`, `mesh.castShadow = true`, `ground.receiveShadow = true`\n- **Shadow acne (stripes):** Increase `light.shadow.bias` (e.g., `-0.005`)\n- **Peter panning (shadow detached):** `light.shadow.bias` is too large, reduce it\n- **Low-res shadows:** Increase `light.shadow.mapSize.set(2048, 2048)`\n\n---\n\n## Symptom 6: WebGL Context Lost\n\nThe browser reclaims the WebGL context under memory pressure or GPU reset.\n\n### Recovery pattern\n\n```javascript\nrenderer.domElement.addEventListener('webglcontextlost', (event) => {\n  event.preventDefault(); \u002F\u002F ALWAYS prevent default to allow restoration\n  cancelAnimationFrame(animationId);\n}, false);\n\nrenderer.domElement.addEventListener('webglcontextrestored', () => {\n  \u002F\u002F Re-initialize materials, textures, render targets\n  initScene();\n  animate();\n}, false);\n```\n\n**NEVER** ignore context loss -- the canvas goes black permanently. ALWAYS add both event listeners.\n\n---\n\n## Symptom 7: needsUpdate Missing\n\n### BufferAttribute\n\nAfter modifying vertex data, the GPU buffer is stale:\n```javascript\npositions.array[0] = newX;\npositions.needsUpdate = true; \u002F\u002F ALWAYS set after modifying attribute data\n```\n\n### Material\n\nAfter changing structural properties (adding\u002Fremoving maps, changing `defines`):\n```javascript\nmaterial.map = newTexture;\nmaterial.needsUpdate = true; \u002F\u002F triggers shader recompilation\n\u002F\u002F NEVER set needsUpdate = true every frame -- causes constant recompilation\n```\n\n### Texture\n\nAfter modifying texture image data:\n```javascript\ntexture.image = newImage;\ntexture.needsUpdate = true; \u002F\u002F triggers GPU re-upload\n```\n\n### InstancedMesh\n\nAfter `setMatrixAt()` or `setColorAt()`:\n```javascript\nmesh.instanceMatrix.needsUpdate = true; \u002F\u002F ALWAYS after setMatrixAt\nmesh.instanceColor.needsUpdate = true;  \u002F\u002F ALWAYS after setColorAt\n```\n\n---\n\n## Symptom 8: updateProjectionMatrix Required\n\nALWAYS call `camera.updateProjectionMatrix()` after changing:\n\n- `camera.fov`\n- `camera.aspect`\n- `camera.near`\n- `camera.far`\n- `camera.zoom`\n- `camera.left\u002Fright\u002Ftop\u002Fbottom` (OrthographicCamera)\n\n```javascript\nwindow.addEventListener('resize', () => {\n  camera.aspect = window.innerWidth \u002F window.innerHeight;\n  camera.updateProjectionMatrix(); \u002F\u002F NEVER forget this\n  renderer.setSize(window.innerWidth, window.innerHeight);\n});\n```\n\n---\n\n## Symptom 9: Transparent Object Rendering Issues\n\nTransparent objects render in the wrong order (back-to-front sorting fails).\n\n### Fix A: renderOrder\n\n```javascript\n\u002F\u002F Force specific rendering order\nbackgroundMesh.renderOrder = 0;\ntransparentMesh.renderOrder = 1;\nfrontMesh.renderOrder = 2;\n```\n\n### Fix B: depthWrite\n\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  transparent: true,\n  opacity: 0.5,\n  depthWrite: false \u002F\u002F prevents transparent objects from writing to depth buffer\n});\n```\n\n### Fix C: alphaTest instead of transparency\n\nFor textures with hard alpha edges (foliage, fences):\n```javascript\nconst material = new THREE.MeshStandardMaterial({\n  map: leafTexture,\n  alphaTest: 0.5, \u002F\u002F discards fragments below threshold\n  side: THREE.DoubleSide\n  \u002F\u002F NEVER set transparent: true for hard-edge alpha -- use alphaTest instead\n});\n```\n\n---\n\n## Common Console Warnings\n\n| Warning | Cause | Fix |\n|---------|-------|-----|\n| `THREE.WebGLRenderer: Texture is not power of two` | NPOT texture with repeat wrapping | Use power-of-two textures or `ClampToEdgeWrapping` |\n| `THREE.WebGLProgram: shader error` | GLSL compilation failure | Check custom shader code for syntax errors |\n| `THREE.PropertyBinding: Can not bind to...` | Animation targets missing property | Ensure skeleton\u002Fmorph targets match the animation clip |\n| `THREE.BufferGeometry: .addAttribute() removed` | Using deprecated API | Use `setAttribute()` instead |\n| `GL_INVALID_OPERATION: Feedback loop` | Reading from a texture that is also a render target | Use separate textures for reading and writing |\n\n---\n\n## Reference Links\n\n- [references\u002Fmethods.md](references\u002Fmethods.md) -- Fix-related API signatures\n- [references\u002Fexamples.md](references\u002Fexamples.md) -- Complete fix patterns\n- [references\u002Fanti-patterns.md](references\u002Fanti-patterns.md) -- What NOT to do\n\n### Official Sources\n\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Frenderers\u002FWebGLRenderer\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fcameras\u002FPerspectiveCamera\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fmaterials\u002FMaterial\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fcore\u002FObject3D\n- https:\u002F\u002Fthreejs.org\u002Fdocs\u002F#api\u002Fen\u002Fcore\u002FBufferAttribute\n",{"name":5,"license":14,"metadata":23,"description":26,"compatibility":27},{"author":24,"version":25},"OpenAEC-Foundation","1.0","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.\n","Designed for Claude Code. Requires Three.js r160+.","main","4c174e06a831864e98c30f630a7aa6c04738b094","skills\u002F_intake\u002Fgithub\u002FImpertio-Studio\u002FThree.js-Claude-Skill-Package\u002Fthreejs-errors-rendering","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules","https:\u002F\u002Fgithub.com\u002Fmhyahya854","2026-11-06 02:03:37",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add mhyahya854\u002FAI-Second-Brain_Universal-Rules --skill threejs-errors-rendering",{"tool":40,"command":41},"bunx","bunx skills add mhyahya854\u002FAI-Second-Brain_Universal-Rules --skill threejs-errors-rendering",{"tool":43,"command":44},"pnpm","pnpm dlx skills add mhyahya854\u002FAI-Second-Brain_Universal-Rules --skill threejs-errors-rendering","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002FImpertio-Studio\u002FThree.js-Claude-Skill-Package\u002Fthreejs-errors-rendering\u002FSKILL.md",true,[48,53,59,63],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":13,"sourceHtmlUrl":52},".gitkeep","OTHER","其他","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002FImpertio-Studio\u002FThree.js-Claude-Skill-Package\u002Fthreejs-errors-rendering\u002F.gitkeep",{"path":54,"resourceType":55,"resourceTypeDesc":56,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Fanti-patterns.md","REFERENCE","参考文档",7587,"https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002FImpertio-Studio\u002FThree.js-Claude-Skill-Package\u002Fthreejs-errors-rendering\u002Freferences\u002Fanti-patterns.md",{"path":60,"resourceType":55,"resourceTypeDesc":56,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Fexamples.md",7642,"https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002FImpertio-Studio\u002FThree.js-Claude-Skill-Package\u002Fthreejs-errors-rendering\u002Freferences\u002Fexamples.md",{"path":64,"resourceType":55,"resourceTypeDesc":56,"sizeBytes":65,"sourceHtmlUrl":66},"references\u002Fmethods.md",4932,"https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002FImpertio-Studio\u002FThree.js-Claude-Skill-Package\u002Fthreejs-errors-rendering\u002Freferences\u002Fmethods.md",[68,76,84,92,99,106],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":72,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":18},"01M7EX4T721AAH60R0239P8WBZ","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\u002FPPTX to web, or create slides for a talk\u002Fpitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fzarazhangrui\u002Ffrontend-slides\u002Ffrontend-slides\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fzarazhangrui\u002Ffrontend-slides\u002Ffrontend-slides\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":80,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":18},"01M7EX495RSHTTCEJVX7C83FA3","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\u002Fschema, (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\".","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fzanwei\u002Fdesign-dna\u002Fdesign-dna\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fzanwei\u002Fdesign-dna\u002Fdesign-dna\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":88,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":18},"01M7EX45RF2XZKRC3KDJDTT1PH","wireframe","Generate JSON wireframe with HTML preview","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fyhassy\u002Fwireframe-skill\u002Fwireframe-skill\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fyhassy\u002Fwireframe-skill\u002Fwireframe-skill\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":18},"01M7EWZEM3MHD48AYSYFR2C9JP","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.","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fwshobson\u002Fagents\u002Fsocial-publishing\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":18},"01M7EWKDEK9840C728VXT78EQ9","hermes-tweet","Install and operate Hermes Tweet, a Hermes Agent plugin for X\u002FTwitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X\u002FTwitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X\u002FTwitter context. Requires XQUIK_API_KEY for read and action tools.","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fwshobson\u002Fagents\u002Fhermes-tweet\u002FSKILL.md",[],[],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":18},"01M7EWASXP3NZWW95CJPT2CRWN","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\u002Funprofessional), \"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.","https:\u002F\u002Fgithub.com\u002Fmhyahya854\u002FAI-Second-Brain_Universal-Rules\u002Fblob\u002Fmain\u002Fskills\u002F_intake\u002Fgithub\u002Fwondelai\u002Fskills\u002Frefactoring-ui\u002FSKILL.md",[],[]]