Learning Three.js Part 2 – the Basics

In the last post in this series we looked at what three.js is, and what you need to start developing with it. Now it’s time to make our first three.js scene. A note before we get started, the source code for each part of this series is available on github. Feel free to download it, but the best way to learn is to follow along with the tutorials.

Setting up our basic page

The first thing we need to do is setup a basic HTML page and link to our three.js library. Below is the skeleton HTML page that we will be using:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>Learning Three.js Part 2 - the Basics</title>
	<script src="jquery-3.1.0.min.js"></script>
	<script src="three.min.js"></script>
</head> var scene = new THREE.Scene(); 

	<div id="render"></div> 


Setting up your scene

In three.js, a scene is the container that holds all the other objects we create. Everything we want to be rendered needs to be added to the scene. We create a new scene with the following:

var scene = new THREE.Scene();

That will go inside out jQuery function. Easy enough. Next up we need add a camera to the scene. A camera in three.js works the same as a camera in the real world, it’s the eye from which you’ll be seeing everything in the scene. Besides a camera, we need to add a renderer. The renderer is essentially the DOM element to which we will be rendering out our scene. We can create a camera and renderer like so:

var scene = new THREE.Scene();			
var camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000);
var renderer = new THREE.WebGLRenderer();

renderer.setSize(window.innerWidth, window.innerHeight);
renderer.shadowMapEnabled = true;

camera.position.x = -20;
camera.position.y = 40;
camera.position.z = 20;		

The code above is creating a new camera (a perspective camera. The different cameras are explained later in this series). When creating a new camera we pass 4 parameters to it, namely:

  • FOV – the field of view of the camera. If you’re a gamer you’ll know what that is, if not, read this.
  • Aspect Ratio – the ratio of the width to the height of our screen
  • Near – the near clipping plane of the camera. This is the closest distance to the camera that objects will still be rendered.
  • Far – the far clipping plane of the camera. This is the furthest distance from the camera that objects will still be rendered

Let there be light! (and a cube)

Next up we need to add a light to our scene. Without a light, our scene will be dark. That sounds like a quote from Game of Thrones. There are a number of different lights we can create in three.js, but for now we’re going to use a spotlight. But even with a light our scene won’t look like much because it’s empty. To solve that problem, we’ll add a cube. We do that like so:

var cubeGeometry = new THREE.CubeGeometry(4,4,4);
var cubeMaterial = new THREE.MeshLambertMaterial({color: 0xff0000});
var cube = new THREE.Mesh(cubeGeometry, cubeMaterial);
cube.position.x = 0;
cube.position.y = 10;
cube.position.z = 0;
cube.castShadow = true;
cube.receiveShadow = true;			

var ambientLight = new THREE.AmbientLight(0xffffff, 0.3);
scene.add( ambientLight );

var spotLight = new THREE.SpotLight( 0xffffff );
spotLight.position.set( -16, 20, 8);
spotLight.castShadow = true;
spotLight.shadowMapWidth = 2048;
spotLight.shadowMapHeight = 2048;
scene.add( spotLight );

// add fog
scene.fog = new THREE.FogExp2( 0xffffff, 0.018 );

// look at our cube

// render the scene
renderer.render(scene, camera);

A couple things you’ll notice, firstly that you need to move the renderer.render function to after the light and cube have been added. The scene is not automatically rendered, we need to tell when three.js when to render our scene. You’ll also notice that we need to set which objects in the scene cast and receive shadows. Shadows are very expensive, not in money, in performance.

We then add two lights to our scene. The first light is an ambient light. Think of ambient light as a global light, it lights everything in the scene equally and has no position. We add this to brighten up the entire scene. The second light that we add is a spot light. Like the name suggests, a spot light works the same as a spotlight in real life. Next up we add some exponential fog. The further away an object is from the camera, the more it will be obscured by the fog.

If you’ve done everything right you should see a very red, lit cube, something like:

That doesn’t look like much yet, but it’s a start. In the next part of this series we’ll be making our cube move. Exciting stuff. You can grab the source for what we’ve done so far here