Controlling the variables used in the scene

When you're developing and writing JavaScript, you often need to tune some variables for the best visualization. You might need to change the color of a sphere, change the speed of an animation, or experiment with more complex material properties. You can just change the source code, and reload the HTML, but that becomes tedious and time consuming. In this recipe, we'll show you an alternative way to quickly and easily control the variables in your Three.js scene.

Getting ready

For this recipe, we also need an external JavaScript library called dat.gui. You can download the latest version from https://code.google.com/p/dat-gui/, or look into the libs directory of the sources provided with this book. To use this library, you first have to include it in the top of your HTML file:

    <script src="../libs/dat.gui.min.js"></script>

In the source folder of this chapter, there is also a ready-to-use example, which we'll explain in the following sections. When you open the 01.07-control-variables.html file, you'll see the following:

As you can see in the preceding screenshot, a menu is available in the top-right corner that you can use to control the rotation speed and the scaling of the cube.

How to do it...

To use this library for yourself, you only need to do a couple of small things:

1. The first thing you need to do is define a JavaScript object that contains the properties you want to control. In this case, you need to add it to the init function and create a new global JavaScript variable with the name, control:

       ...
       var control;
       function init() {
         ...
   
         control = new function() {
           this.rotationSpeed = 0.005;
           this.scale = 1;
         };
         addControls(control);
   
         // call the render function
         render();
       }

2. The control object in the preceding code contains two properties: rotationSpeed and scale. In the addControls function, we'll create the UI component that is shown in the preceding screenshot:

       function addControls(controlObject) {
         var gui = new dat.GUI();
         gui.add(controlObject, 'rotationSpeed', -0.1, 0.1);
         gui.add(controlObject, 'scale', 0.01, 2);
       }

   In this addControls function, we use the provided argument that contains the rotationSpeed and scale properties in order to create the control GUI. For each variable, we specify four arguments:

   1. Object: The first argument is the JavaScript object that contains the variables. In our case, it's the object passed to the addControls function.
   2. Name: The second argument is the name of the variable we want to add. This should point to one of the variables (or functions) available in the object that is provided in the first argument.
   3. Minimum value: The third argument is the minimum value that should be shown in the GUI.
   4. Maximum value: The last argument specifies the maximum value that should be shown.
3. At this point, we've got a GUI that can be used to control the variables, as you can see in the following screenshot:
   

   The only thing we now need to do is make sure that we update our object in the render loop, which is based on the variables from the GUI. We can do this easily in the render function, which is as follows:

       function render() {
         renderer.render(scene, camera);
         scene.getObjectByName('cube').rotation.x+= control.rotationSpeed;
         scene.getObjectByName('cube').scale.set (control.scale,
           control.scale,
           control.scale);
         requestAnimationFrame(render);
       }

There's more...

In this recipe, we've just used dat.gui to change the numeric values. The dat.gui library also allows you to add controls for other types of values as follows:

• If the variable you add is a Boolean, a checkbox will be shown
• If the variable is a string, you can add an array of valid values
• If the variable is a color, you can use add color to create a color picker
• If the variable is a function, you get a button that fires the selected function

Besides this, you can add different kinds of event listeners to fire custom callbacks when a value managed by dat.gui changes. For more information, see the dat.gui library documentation which you can find at http://workshop.chromeexperiments.com/examples/gui/#1--Basic-Usage.