GETTING STARTED: HERE’S WHERE THE REAL FUN BEGINS!

We’ll start with a blank canvas and over the next couple of chapters, we’ll gradually add to it until we’ve created a small but powerful three.js app featuring animation, lights, textures, materials and even camera controls!

Once we have finished Chapter 1.1 and Chapter 1.2, you’ll have this glorious purple box rotating on your screen, and by the end of Section 1: Getting Started, you should have a firm grasp of everything you need to know to start creating your own simple three.js apps.

Each chapter in this section will start where we left off in the previous chapter, so you can use this empty template to follow all the way through, or open the link at the start of each chapter and work from there.

Motivation for this Section

This section is a complete mini tutorial series, designed to get you up to speed as quickly as possible while giving you a thorough grounding in the technical language and concepts you’ll need to go deeper.

We’ll briefly introduce lots of new theory over the next couple of chapters, but don’t worry if it’s a lot to take in since we’ll come back to everything in later sections. We’ll introduce concepts with just enough detail to allow you to start thinking about them and using them, without sacrificing any technical accuracy of course. Then, once you have used them for a while and they are not quite so new, you can come back and fill in any missing details.

This is especially important if you’re coming to three.js from a background as a web developer, or even if you’re starting out your entire development career here. Almost no matter what your background is, you’ll be coming across quite a few new concepts as you learn to use three.js. Displaying 3D in the browser ties together a lot of different fields - we’ll need to understand the JavaScript programming language, layout of HTML elements using CSS, and 3D computer graphics concepts.

The latter can get quite maths heavy, and while three.js does an amazing job of hiding the complexity from you unless you need it, at times you will unavoidably come across weird and wonderful things like matrices and quaternions. So, let’s dive straight in and pretty soon those crazy sounding names will be things you use in your code with barely a second glance.

The Structure of a Basic App

Take a look at the directory structure of the Codesandbox example above.

You can ignore package.json for now. It’s used to set up the Codesandbox project environment.

The Codesandbox.io file tree

The HTML

First of all, let’s take a quick look at the HTML. If you are familiar with the setup of a basic HTML page, there should be nothing surprising to you here. If anything is surprising, be sure to check out Ch 0.7 where we cover in detail all of the HTML we’ll be using throughout the book.

<!-- index.html -->



<!DOCTYPE html>
<html>

  <head>

    <title>Discoverthreejs.com Ch 1.1: Your First Scene</title>

    <meta name="viewport" content="width=device-width, initial-scale=1">

    <meta charset="UTF-8" />

    <link rel="icon" href="https://discoverthreejs.com/favicon.ico" type="image/x-icon">

    <link href="styles/main.css" rel="stylesheet" type="text/css">

    <!--

      Include the main three.js script.

      The global variable THREE will be
      available for use in any scripts
      loaded after this one.

    -->

    <script src="js/vendor/three/three.js"></script>

  </head>

  <body>

    <h1 class="title"><a href="https://discoverthreejs.com/">Discoverthreejs.com</a> - Ch 1.1 Your First Scene</h1>

    <div id="scene-container">
      <!-- This div will hold our scene-->
    </div>


    <!--
      Finally, include the script that
      runs your three.js app.
    -->

    <script src="js/app.js"></script>

  </body>

</html>

The CSS

Next up is main.css, which contains our CSS styles.

/* main.css */



body {
  margin: 0px;
  overflow: hidden;
  color: white;
  text-align: center;
}

h1 {
  position: absolute;
  width: 100%;
  z-index: 1;
  font-size: 1.5rem;
}

a {
  color: white;
}
a:hover{
  color: purple;
}

#scene-container {
  position: absolute;
  width: 100%;
  height: 100%;
}

Again, if any of this is unfamiliar to you, refer back to Ch 0.7: HTML and CSS Used in this Book.

The JavaScript

Finally, there’s app.js, which is where all the magic happens. However, if you look inside it now you’ll see that it’s currently empty. In the next chapter, we’ll fix that, and create our very first three.js app!

// app.js



// Nothing to see here... yet!

The THREE Namespace

We’ve included the three.js script in our page:

<script src="js/vendor/three/three.js"></script>

This script sets up a namespace denoted by the word THREE, all capital letters. This means that we can access all the three.js goodies using dot notation:

const mesh = new THREE.Mesh();

const light = new THREE.SpotLight();

…and so on. The disadvantage of this approach is that it includes everything, including lots of things that we won’t ever be using.

To overcome this, in Section Two, we’ll switch to using JavaScript Modules, which will allow us to import just the part of three.js that we need:

import {
  Mesh,
  SpotLight,
} from './js/vendor/three.module.js;

When using this style, we’ll no longer use the THREE namespace:

const mesh = new Mesh();

const light = new SpotLight();

However, for the remainder of this section we’ll continue to use the kitchen sink THREE namespace.