Creating A Debug UI

Introduction

This course teaches you how to build powerful debug interfaces for your Three.js projects using the lil-gui library.

You will learn

• how to create interactive controls for modifying object properties in real-time, including position, rotation, color, and material settings
• how to streamline your workflow by adding sliders, buttons, color pickers, and dropdown menus to quickly test and fine-tune their 3D scenes during development.
• how to reduce development time by creating useful UI's for testing your application instead of constantly bouncing back and forth between your code editor and the browser

What is a Debug UI?

A debug UI is a graphical control panel that lets you adjust parameters of your Three.js scene in real-time. Instead of repeatedly changing values in code, saving, and reloading to see the effect, a debug UI allows immediate adjustments during runtime.

Common uses include:

• Adjusting object positions, rotations, and scales
• Modifying material properties (color, opacity, wireframe)
• Controlling lighting parameters
• Testing different settings and configurations
• Finding optimal values for visual elements

Implementing with lil-gui

The course uses lil-gui, a popular UI library included with Three.js that creates a simple control panel with various controls. It replaces the older, no-longer-supported dat.GUI library.

Basic Setup

// Import lil-gui
import GUI from 'three/examples/jsm/libs/lil-gui.module.min.js';

// Create a new GUI instance
const gui = new GUI();

// Optional: Configure GUI width
// gui = new GUI({ width: 600 });

Adding Controls

The fundamental pattern for adding controls is:

gui.add(object, 'propertyName', minValue, maxValue, stepValue);

Where:

• object is what you want to modify (like mesh, material, light)
• propertyName is the string name of the property to control
• minValue and maxValue define the slider range (optional)
• stepValue defines increments (optional)

Example for controlling position:

// Add a slider for X position between -5 and 5
gui.add(mesh.position, 'x', -5, 5);

// Add sliders for Y and Z positions
gui.add(mesh.position, 'y', -5, 5);
gui.add(mesh.position, 'z', -5, 5);