ThreeJS

ThreeJS Hello Cubes JavaScript Tutorial

This article covers how to create a 3D Web app with JavaScript using ThreeJS.

The app will display several 3D rotating cubes on the screen.

Step 1. Define the project

The project will be called threejs-hello and use the following components:

Folders

  • src – a source folder to hold all the files and subfolders
    • the root of the Web app will be src
  • src/css – a stylesheet folder that will be a subfolder of src

Browser files

  • src/index.html – the main browser file to display the scene
  • src/css/app.css – the stylesheet for the Web app

Application files

  • src/app.js – the main JavaScript file of the Web app
  • src/cube.js – a cube factory class that will create new ThreeJS cubes on demand
  • src/cube-scene.js – a cube scene factory class that will return a new ThreeJS scene containing a number of rotating cubes

Step 2. Create a new project folder

Now that you’ve defined the project structure, it’s time to set it up:

  1. Open up a terminal / command window
  2. Create a new folder called threejs-hello
  3. Switch to that folder
  4. Under that folder, create a new subfolder called src
  5. Under the src folder create a new subfolder called css

Step 3. Create the project files

  1. In the src folder create the following empty files: 
    index.html
app.js
cube.js
cube-scene.js
  2. In the src/css folder create the following empty file: 
    app.css

Step 4. Define the index.html file

Paste the following into the src/index.html file:

[gist]https://gist.github.com/mitchallen/1aab522e5cf848114748e7b149c3ad72[/gist]

Code Description

The code above, does the folowing:

  • Sets the title that appears at the top of the browser window
    • You can make this anything you want
  • Includes the css/app.css style sheet that you will define soon
  • Includes the minimized ThreeJS library JavaScript file using a CDN network
    • The /r22/ designation refers to the build version number
  • Includes the src/app.js file that you will define soon
    • It’s important to use the type="module" attribute or the code won’t load properly

Step 5. Fill in the src/css/app.css file

Paste the following into the src/css/app.css file:

[gist]https://gist.github.com/mitchallen/de832a40ec6dac3aee70572a777c4263[/gist]

Code Description

The css code above does the following:

  • Sets all margins on the body to zero
  • Sets the width and height of a canvas element created by the script to 100%

The settings are to allow a 3D scene to fill the entire browser window.

Step 6. Define the cube.js file

Paste the following info the src/cube.js file:

[gist]https://gist.github.com/mitchallen/5bafea98c0a1ba461a8c7ef2f37cb759[/gist]

Code Description

The code above does the following:

  1. Defines and exports a cube factory class (CubeFactory)
  2. Defines a static create method to return new cubes
    • The method takes an optional object (spec) defining override parameters
  3. Setup default values or use arguments
    • If no spec object is passed to the method, default values will be used
    • If the spec object contains existing parameters, the default values will be overwritten for that parameter
    • Values for color, size (width, height, depth) and offset (translate[X,Y,Z]) can all be overridden
  4. Uses ThreeJS to define a 3D cube
    • One way to create a 3D object in ThreeJS is to combine a geometry and a material to define a mesh
  5. Use the name property to specify a type
    • Instead of assigning individual names to each cube, the name property will be used to designate a type (in this case “cube”)
  6. Use ThreeJS methods on the cube to move it to a specific offset from 0, 0, 0
    • The default values are all set to 0.0, so the cube would be drawn in the 3D center of the scene
  7. Returns the new cube

Usage example

In this example, cubes of various colors, sizes and locations would be added to a scene:

[gist]https://gist.github.com/mitchallen/ff1c43260715cb583252e49d7625f332[/gist]

Step 7. Define the cube-scene.js file

Paste the following info the src/cube-scene.js file:

[gist]https://gist.github.com/mitchallen/78209a9092ef08baf56c80ed1add1725[/gist]

Code Description

The code above does the following:

  1. Imports the cube class factory (CubeFactory)
  2. Defines and exporst a scene factory class (CubeSceneFactory)
  3. Defines a static create method to return new scenes filled with 3D cubes
  4. Sets up default values or uses spec arguments
  5. Defines a list of options for cubes to be created
  6. Sets up a ThreeJS renderer to render the scene
  7. Creates a new ThreeJS scene
  8. Creates a ThreeJS camera
  9. Adds several cubes to the scene using the cubeOptions list of parameters
  10. Defines a cube scene with methods to return
  11. Defines a method on the cube scene to handle browser window resizing
  12. Defines a method to be called each time the scene is rendered
    • Traverses the scene looking for all objects with a name of “cube”
    • If a cube object is found it’s x and y rotation parameters are incremented to animate the cube spinning
  13. Returns the new cube scene

Step 8. Define the app.js file

The main app.js file will do the following:

  • Import the CubeSceneFactory class
  • Create a new cube scene (cubeScene) using the factory
  • Define a render function to handle drawing a frame of the scene
  • Add event listener code to handle browser window resizing

Paste the following into the src/app.js file:

[gist]https://gist.github.com/mitchallen/d546bb794c4b0addd6d42e0bb2d78e29[/gist]

Code Description

The code above does the following:

  1. Lists a reminder in the comments for how to include the script in an HTML file
  2. Imports a CubeSceneFactory from ./cube-scene.js which you will define soon
  3. Creates cubeScene from the factory using its create method
    • The clear RGB (color) hex value will be used as the background color
  4. Defines a render function that does the following:
    • calls the ThreeJS requestAnimationFrame function
    • calls a method on the cubeScene called step to rotate each cube a little for every frame
  5. Adds and defines a window listener to handle the browser being resized
    • Calls the cubeScene resize method to draw frames based on the changed browser size
  6. Calls render to initiate drawing the screen

Step 9. Serve the files

To run the app you need to serve up src/index.html using a Web server.

On a Mac you can do that with this command:

cd src
python -m SimpleHTTPServer $PORT || 8000

Then in a browser like Chrome, browse to:

On a Mac you can also open the browser from the command line”

open http://localhost:8000

You can also host demo apps for free by posting them to services like:

If you have an AWS, Azure or Google Cloud account you can also serve the files from buckets as a static Web site.

Troubleshooting

  • This demo works best in the latest version of Chrome or the Oculus Browser
  • If you are getting a blank screen, use the browser JavaScript console to review issues

Conclusion

In this article you learned how to:

  • Create a simple Hello World app using ThreeJS
  • Define a class factory to generate cubes of various colors, sizes and positions
  • Define another class factory to generate a ThreeJS scene filled with cube
  • Use a render loop to animate cubes on the screen
  • Serve the files so the 3D app can be viewed in a browser

References

Read next