Getting Started: Here's Where the Real Fun Begins! 1

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

The purpose of this section is 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. 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

index.html

<!DOCTYPE html>
<html>

  <head>

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

    <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
    <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="https://threejs.org/build/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="container">
      <!-- This div will hold our scene-->
    </div>

    <footer>

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

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

    </footer>

  </body>
</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.

In the <head> section we’ve added a <title> (which is what shows up in your address bar at the top of the screen), some basic <meta> tags, a link to the main.css style sheet, and finally a link the the main three.js script, which we are loading directly from the threejs.org website for simplicity.

The only unusual thing here is the viewport meta tag:



<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">

By adding this, we have disabled user scaling, which is standard practice for a full-screen three.js app.

Next, in the <body> section, we’ve added a <h1> title telling us about the page, and a <div> called container. We’ll draw our three.js scene inside this container. Finally, also inside the <body>, we’ve added a <footer>, and inside this footer, we’ve added our app.js script.

Adding app.js to the footer like this ensure that it will not run until the rest of the page has been read. If we put app.js directly after the three.js script and then tried to use our <div class="container">, we might find that the browser had not read that far into the page yet, in which case it would give an error.

The other file is main.css, which contains some basic CSS styling to set up the layout of our page.

The CSS

main.css

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

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

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

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

main.css contains our CSS styles. We won’t say much about this, as it’s very basic for now - just enough to make sure that the container takes up the full window, and the title is drawn on top of the container, and any scrollbars are hidden.

The JavaScript

app.js

// Nothing to see here... yet!

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