Performance Debugging

Learn to identify and resolve performance issues in Three.js applications.

Performance Debugging Demointermediate

Loading example...

This scene intentionally includes performance issues. Use 3Lens to identify bottlenecks, analyze draw calls, and optimize the scene.

Features Demonstrated

• Frame Stats: Real-time FPS, frame time, and memory monitoring
• Draw Call Analysis: Track render calls and triangle count
• GPU Timing: Measure GPU render time (where supported)
• Performance Rules: Automatic warnings for budget violations
• Timeline Recording: Record and analyze frame sequences

Key Metrics to Monitor

Metric	Target	Warning
FPS	60	< 45
Frame Time	< 16.67ms	> 22ms
Draw Calls	< 100	> 200
Triangles	< 100K	> 500K
Textures	< 50	> 100

Using Performance Rules

import { createProbe } from '@3lens/core';

const probe = createProbe({
  performance: {
    targetFPS: 60,
    warningThreshold: 45,
    criticalThreshold: 30
  },
  rules: [
    {
      name: 'max-draw-calls',
      check: (stats) => stats.drawCalls < 200,
      message: 'Draw calls exceed budget (200)'
    },
    {
      name: 'max-triangles',
      check: (stats) => stats.triangles < 500000,
      message: 'Triangle count exceeds budget (500K)'
    }
  ]
});

probe.on('ruleViolation', (violation) => {
  console.warn(`Performance rule violated: ${violation.rule.name}`);
});

Common Performance Issues

1. Too Many Draw Calls - Use instancing or merge geometries
2. Large Textures - Compress and resize textures appropriately
3. Complex Shaders - Simplify shader logic, use LOD
4. Unoptimized Geometry - Use LOD, simplify distant objects
5. Memory Leaks - Properly dispose of resources

Related Examples

• Memory Leak Detection - Track down resource leaks
• Large Scene Optimization - Scaling techniques
• Shader Debugging - Inspect GLSL/WGSL