Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 39 ยท Getting Started

Helpers and Debugging Tools

Debug Three.js scenes with built-in helpers, lil-gui sliders and a stats panel, and learn the usual reasons for a blank screen or a black object.

Three.js scenes fail silently in a very specific way: you see a black or empty canvas and no error. Fixing that is a skill, and the library gives you good tools: visual helpers that draw invisible things such as axes, bounding boxes and lights; a GUI library for tweaking values live; a performance panel; and the console. This lesson covers them and ends with a checklist for the most common mistakes.

Helpers that draw invisible things

Helpers are ordinary objects you add to the scene. They exist to make hidden data visible during development, and you remove them for production.

Helper Shows
AxesHelper(size) The x (red), y (green), z (blue) axes of the origin or of an object you add it to
GridHelper(size, divisions) A floor grid
BoxHelper(object, color) The bounding box of an object, updated with update()
Box3Helper(box3) A Box3 you computed yourself
ArrowHelper(dir, origin, length, color) A direction arrow, good for normals and velocities
PolarGridHelper A circular grid
CameraHelper(camera) The frustum of a camera
DirectionalLightHelper, PointLightHelper, SpotLightHelper, HemisphereLightHelper Position and direction of lights
SkeletonHelper(object) The bones of a skinned model
VertexNormalsHelper (add-on) The normal at every vertex

A trick worth remembering: adding an AxesHelper as a child of a mesh shows that mesh's own local axes, which makes rotations easy to understand.

lil-gui for live tweaking

lil-gui is the library that Three.js examples use. It builds a panel of sliders, color pickers and checkboxes bound to the properties of any object. It ships in the add-ons folder.

JavaScript
import GUI from "three/addons/libs/lil-gui.module.min.js";

const gui = new GUI();
gui.add(mesh.position, "x", -3, 3, 0.01);
gui.add(mesh.rotation, "y", 0, Math.PI * 2);
gui.addColor(params, "color").onChange((c) => material.color.set(c));
gui.add(material, "wireframe");

Because it edits properties directly, you need no extra code. When you find good values, copy them into your source.

Stats and the renderer's own numbers

Stats from the add-ons draws a small frames-per-second panel. renderer.info is even more informative: it counts draw calls, triangles, geometries and textures currently in memory. Those numbers are what you look at when a scene is slow.

Helpers, GUI and renderer.info

Drag the sliders and watch the yellow bounding box follow. BoxHelper is not automatic: you call bounds.update() after the object changes. Also notice the draw call count: every mesh and every helper costs at least one.

Reading the console

Three.js logs useful warnings. A few you will meet:

  • THREE.WebGLRenderer: Context Lost. The GPU reset the context, often from too many or too large resources.
  • THREE.WebGLProgram: Shader Error followed by a numbered listing: a mistake in custom shader code.
  • Failed to load resource or a 404 on a texture: the path is wrong, and the material renders black or white.
  • THREE.Object3D.add: object not an instance of THREE.Object3D: you tried to add something that is not an object, such as a geometry.
  • Messages about renderer.outputEncoding or other missing properties mean you copied an old tutorial written for an earlier version of the API.

Why is my screen blank? A checklist

  1. Camera inside the object or looking away. Move the camera back (camera.position.z = 5) and call camera.lookAt(0, 0, 0).
  2. Forgot scene.add(mesh). Creating a mesh does not place it in the world.
  3. No render call. Either you forgot renderer.render(scene, camera) or your loop never started.
  4. Object outside the frustum. The camera only sees between near and far. Very large scenes need a larger far.
  5. Lit material without lights. MeshStandardMaterial and similar are black in a scene with no lights. Add a light, or use MeshBasicMaterial to confirm the object exists.
  6. Canvas has no size. If you use your own canvas in a flex layout it may be 0 pixels high.
  7. Scale zero or huge. Units that are too small (a 0.001 sized model) or huge need a camera adjustment.
  8. Faces culled. By default only the front side of a triangle is drawn. A plane seen from behind vanishes unless you set side: THREE.DoubleSide.

When nothing shows, replace the material with new THREE.MeshBasicMaterial({ color: "red" }) and move the camera back. If the red shape appears, the problem is lighting or the material. If not, it is the camera, scene or renderer.

Debugging: why is it black?

The left sphere uses a physically based material that needs light, so it renders almost black. The right sphere uses MeshBasicMaterial, which ignores lights and stays flat blue. Chapter 4 explains lights properly.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You add an AxesHelper as a child of a mesh. What does it show?

    Children inherit their parent's transform, so the helper follows the mesh and displays its local orientation.
  2. 2. Which object tells you the number of draw calls and triangles per frame?

    renderer.info.render has calls and triangles; renderer.info.memory counts geometries and textures.
  3. 3. A MeshStandardMaterial sphere renders almost black in your scene. What is the most likely cause?

    Physically based materials need light. Add a light or an environment map.
  4. 4. Why does a plane disappear when viewed from behind?

    Only the front side of each triangle is rendered unless you ask for the back or both sides.

Summary

  • Helpers draw hidden data (axes, boxes, lights, frustums); remember to update() those that do not follow automatically.
  • lil-gui binds sliders to object properties so you can tune values live.
  • renderer.info reports draw calls, triangles and memory; use it before optimizing.
  • A blank canvas is usually the camera, a missing scene.add, a missing light or culled faces.
  • Swapping in a red MeshBasicMaterial is the fastest way to split problems into "geometry or camera" versus "lighting".

Next: The Scene Graph and Object3D