threejs-debug-profiler

Blank canvas debugging starts by reproducing the issue locally, then checking console errors, canvas CSS and drawing-buffer sizes, WebGL context creation, camera aspect and near/far planes, lights, and material visibility. The scene-debugging checklist orders these checks so the root cause is found before editing code.

Profile by recording baseline FPS, frame time, renderer.info render calls, triangles, geometries, and textures in a production build. Then classify the bottleneck as CPU, GPU draw, GPU fragment, or memory, and apply one optimization at a time such as InstancedMesh, shared materials, frustum culling, or DPR caps, re-measuring after each change.

Mobile input failures usually come from missing touch-action CSS, pointer listeners attached to the wrong element, page scroll stealing gestures, or missing viewport meta tags. The mobile input checklist covers pointer capture, safe-area insets, high-DPR scaling, and verification with mobile emulation.

Measure FPS and frame time after warmup, plus renderer.info fields: render.calls, triangles, points, lines, memory.geometries, and memory.textures. Also track render targets, post-processing passes, texture dimensions, bundle size, and JS heap to classify CPU, GPU, memory, or network bottlenecks.

Avoid removing visual detail before checking DPR caps, post-processing cost, shadow settings, instancing, and culling, since these often resolve frame-rate issues without degrading visuals. Optimizing development-server performance instead of a production preview build is also a common mistake.