Published on September 1, 2024

Debugging 3D applications can be challenging - issues might be in JavaScript, shaders, or the GPU itself. Here’s your debugging toolkit.

Browser DevTools

Performance Panel

• Profile frame times
• Identify JavaScript bottlenecks
• Watch for garbage collection spikes

Memory Panel

• Track texture memory usage
• Find geometry leaks
• Monitor buffer allocations

Spector.js

Essential for WebGL debugging:

1. Install the browser extension
2. Capture a frame
3. Inspect:
   • Draw calls
   • Shader programs
   • Texture state
   • Buffer contents

Leva / dat.GUI

Runtime parameter tweaking:

import { useControls } from 'leva'

function Light() {
  const { intensity, color } = useControls({
    intensity: { value: 1, min: 0, max: 10 },
    color: '#ffffff'
  })
  
  return <pointLight intensity={intensity} color={color} />
}

Visual Debugging

Wireframe Mode

<meshBasicMaterial wireframe />

Normal Visualization

<meshNormalMaterial />

Bounding Boxes

import { Box3Helper } from 'three'
// Add to scene to visualize bounds

Common Issues

Black Screen

• Check camera position/target
• Verify lights exist
• Check material settings

Performance Issues

• Too many draw calls (use instancing)
• Shader complexity
• Texture resolution too high

Z-Fighting

• Adjust near/far planes
• Add polygon offset
• Slightly separate geometry

Console Helpers

// Log scene hierarchy
console.log(scene.toJSON())

// Check material properties
console.log(mesh.material)

// Verify geometry
console.log(geometry.attributes)

Good debugging skills are essential for 3D development. Build your toolkit and you’ll solve issues faster.