Three.js is an open-source JavaScript library/API used to create and display animated 3D computer graphics on a web browser, compatible with the HTML5 canvas element, WebGL, and SVG. In this How to Learn article, we'll explore the capabilities of this engine and share resources and suggestions to help you start developing games with it right away.
Why Use Three.js?
Since Three.js was first released by Ricardo Cabello to GitHub in 2010, the code base has been continuously maintained and enhanced by a growing and supportive community. The set of built-in features is extensive, and includes:
- renderers (Canvas, WebGL, and SVG)
- scenes (can be changed at runtime, imported, and exported)
- cameras (perspective and orthographic)
- lights (point, spot, directional, and ambient; objects can cast/receive shadows)
- textures and materials (Lambert, Phong, etc., including support for bump maps and specular maps)
- geometries (including lines, planes, cubes, spheres, polyhedra, cylinders, particle systems, and 3D text)
- utilities to export Three.js-compatible JSON files from 3D modeling software (such as Blender, 3ds Max, or Maya) and import files (such as Wavefront (.obj) or Collada (.dae)) directly into a scene
- shaders (providing complete access to OpenGL Shading Language for more direct control of the graphics pipeline)
- a library of post-processing shaders (including bloom, blur, edge detection, Fresnel, sepia, and vignette)
- a library of stereoscopic effects (Anaglyph, Parallax/Cross-eyed, and Oculus Rift)
Over 100 examples illustrating these features (and more) are included in the main repository, and many other sites provide collections of examples with source code available. Plus, since the library is written in Javascript, it is easy to get up and running, as well as to deploy your work.
Notable Games and Visualizations
HexGL
A futuristic racing game created by Thibaut Despoulain:
Trigger Rally
An automobile racing game created by Jasmine Kent:
Related development articles can be found at Jasmine's Gamasutra blog.
ChuClone
A 2.5D platformer rendered in 3D, with a built-in live level editor, created by Mario Gonzalez:
Marble Table
A marble/soccer game created by Jerome Etienne:
Astray
A maze game created by Rye Terrell:
CubeSlam
A 3D ping-pong game that incorporates video chat within the game, created by Google:
More information can be found at the game's Chrome Experiments page and this behind-the-scenes article.
Find Your Way to OZ
An interactive journey created by Walt Disney and UNIT9
More information is available at the game's Chrome Experiments page.
Getting Started
Since Three.js is a Javascript library, setting up your development environment is particularly easy: the only requirements are a text editor and a web browser. That being said, text editors with features such as syntax highlighting/folding, bracket matching, a document map, and so on - such as Notepad++ or Sublime Text - will provide a better coding experience.
As for web browsers, both Google Chrome and Mozilla Firefox have excellent WebGL support. Google Chrome has a particularly helpful set of built-in developer tools that can greatly simplify the workflow process, such as a console that can be used for debugging and inspecting Javascript values and objects, and Workspace settings that allow you to edit and save source files from within the browser. More details can be found at the Chrome DevTools site.
Tip: It is also possible to write code using Three.js entirely online, using services such as jsFiddle, as demonstrated by this example. However, this option is typically only used for sharing examples or demonstrations with small amounts of code.
To set up Three.js, first go to the GitHub repo. There will be a button that says "Download ZIP" that will allow you to download all the code in the repository as a ZIP file. (There are other alternatives, such as cloning or forking the repository using Git, which are unnecessary for the average user - these options are primarily useful only if you plan to contribute to the source code or online documentation.)
Once you have downloaded and unzipped the file into a directory of your choosing, one more important step remains before you can view most of the examples on your own computer. Many Three.js projects involve loading content from external files (such as images), but, for security reasons, web browsers restrict this behavior by default. The two options for solving this problem are to either change the security settings on your web browser, or to run files from a local server.
The former option is the most straightforward (for example, changing the settings for Google Chrome in Windows can be accomplished by creating a shortcut for Chrome and editing the path to include the flag --allow-file-access-from-files). Instructions for both options can be found in the official wiki, in the page titled How to run things locally.
JavaScript
Three.js is written in Javascript, so it's recommended that you have a working knowledge of this language. There is a myriad of resources freely available across the internet for this; two particularly outstanding interactive resources are:
- Codecademy, which contains a large number of interactive lessons with responsive and intelligent feedback, as well a user-friendly glossary
- Eloquent Javascript, a free digital textbook written by Marijn Haverbeke, which includes an interactive coding environment that runs all included examples and allows the reader to edit and experiment with the example code
Three.js
To learn how to set up a basic scene in Three.js (including a discussion about scenes, cameras, renderers, meshes, and the animation loop, visit: the official manual. Another great introduction to creating a basic scene is the article Getting Started with Three.js by Paul Lewis
A more thorough introductory survey of the capabilities of Three.js is the excellent presentation by James Williams (a video and slideshow) at Introduction to WebGL and Three.js.
Next Steps
The Three.js documentation, available at http://threejs.org/docs/, is a work in progress but a good first place to get an idea for many of the available functions.
A more comprehensive way to learn about the inner workings of the library is to browse the the source code of the official collection of examples at http://threejs.org/examples/, which are often titled by the aspect of the library they most prominently feature. Another resource, consisting of simplified and thoroughly commented examples written for beginners, is the collection at http://stemkoski.github.io/Three.js/. Also, many Three.js projects are announced on Twitter with the #ThreeJS hashtag or on the Three.js subreddit.
Two particularly impressive and inspirational collections of advanced Three.js projects are:
- AlteredQualia, created by Branislav Ulicny (@alteredq, one of the major contributors to the Three.js library)
- JavaScript + WebGL, created by Klas Kroon (aka OutsideOfSociety, @oosmoxiecode)
Some websites and blogs that discuss development and frequently feature Three.js projects include:
- Learning WebGL, originally created by Giles Thomas; the current editor-in-chief is Tony Parisi
- Learning Three.js, written by Jerome Etienne
- japh(r)'s Three.js posts, written by Chris Strom
To learn more about the foundations of 3D computer graphics, check out Interactive 3D Graphics, a free online course taught by Eric Haines that features video lectures and interactive programming exercises using Three.js.
If you need to incorporate functionality beyond that provided by Three.js, it is easy (and common practice) to incorporate additional Javascript libraries, such as:
- Tween.js: a library for automatically interpolating values, useful for smooth animations
- Physi.js: a physics engine designed for use with Three.js
- dat.GUI: a lightweight graphical user interface for changing variables
- Gamepad.js: a library that simplifies processing input from gamepads and joysticks
If you want to create advanced graphical effects beyond those that are included with Three.js, you will need to learn to write shaders, which are functions that run directly on the GPU. Two excellent introductions to shaders, written specifically for users of Three.js, are:
- Intro to Pixel Shaders in Three.js, written by Felix Turner
- An Introduction to Shaders, written by Paul Lewis
Finally, if you are interested in deploying your project for Android or iOS, Ludei's CocoonJS is a platform that does exactly that. The process is well-documented and relatively easy, as most of the work is automated by the CocoonJS Cloud Compilation System.
Where to Go for Help
If you have a question that you can't figure out by looking at the examples or resources above, the place to go for help is Stack Overflow, the premier question and answer site for professional and enthusiast programmers. First, search to see if your question was already asked; if not, register for an account and ask it there!
Conclusion
With these resources at your disposal, it is time to start creating! Three.js has an active and vibrant community, so you should always feel free to ask questions, join in the discussions, and showcase your work. The best of luck to you in your endeavors!
