You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
159 lines
6.3 KiB
159 lines
6.3 KiB
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<base href="../../../" />
|
|
<script src="page.js"></script>
|
|
<link type="text/css" rel="stylesheet" href="page.css" />
|
|
</head>
|
|
<body>
|
|
<h1>[name]</h1>
|
|
|
|
<p>
|
|
You can install three.js with [link:https://www.npmjs.com/ npm] and modern build tools, or get started quickly with just static hosting or a CDN. For most users, installing from npm is the best choice.
|
|
</p>
|
|
|
|
<p>
|
|
Whichever you choose, be consistent and import all files from the same version of the library. Mixing files from different sources may cause duplicate code to be included, or even break the application in unexpected ways.
|
|
</p>
|
|
|
|
<p>
|
|
All methods of installing three.js depend on ES modules (see [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules]), which allow you to include only the parts of the library needed in the final project.
|
|
</p>
|
|
|
|
<h2>Install from npm</h2>
|
|
|
|
<p>
|
|
To install the [link:https://www.npmjs.com/package/three three] npm module, open a terminal window in your project folder and run:
|
|
</p>
|
|
|
|
<code>
|
|
npm install three
|
|
</code>
|
|
|
|
<p>
|
|
The package will be downloaded and installed. Then you're ready to import it in your code:
|
|
</p>
|
|
|
|
<code>
|
|
// Option 1: Import the entire three.js core library.
|
|
import * as THREE from 'three';
|
|
|
|
const scene = new THREE.Scene();
|
|
|
|
|
|
// Option 2: Import just the parts you need.
|
|
import { Scene } from 'three';
|
|
|
|
const scene = new Scene();
|
|
</code>
|
|
|
|
<p>
|
|
When installing from npm, you'll almost always use some sort of [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool] to combine all of the packages your project requires into a single JavaScript file. While any modern JavaScript bundler can be used with three.js, the most popular choice is [link:https://webpack.js.org/ webpack].
|
|
</p>
|
|
|
|
<p>
|
|
Not all features are accessed directly through the <em>three</em> module (also called a "bare import"). Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see <em>Examples</em> below.
|
|
</p>
|
|
|
|
<p>
|
|
Learn more about npm modules from [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm].
|
|
</p>
|
|
|
|
<h2>Install from CDN or static hosting</h2>
|
|
|
|
<p>
|
|
The three.js library can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use <em>type="module"</em> as shown below.
|
|
It is also required to define an import map which resolves the bare module specifier `three`.
|
|
</p>
|
|
|
|
<code>
|
|
<script async src="https://unpkg.com/es-module-shims@1.3.6/dist/es-module-shims.js"></script>
|
|
|
|
<script type="importmap">
|
|
{
|
|
"imports": {
|
|
"three": "https://unpkg.com/three@<version>/build/three.module.js"
|
|
}
|
|
}
|
|
</script>
|
|
|
|
<script type="module">
|
|
|
|
import * as THREE from 'three';
|
|
|
|
const scene = new THREE.Scene();
|
|
|
|
</script>
|
|
</code>
|
|
|
|
<p>
|
|
Since import maps are not yet supported by all browsers, it is necessary to add the polyfill *es-module-shims.js*.
|
|
</p>
|
|
|
|
<h2>Addons</h2>
|
|
|
|
<p>
|
|
The core of three.js is focused on the most important components of a 3D engine. Many other useful components — such as controls, loaders, and post-processing effects — are part of the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] directory. They are referred to as "addons" (previously called "examples"), because while you can use them off the shelf, they're also meant to be remixed and customized. These components are always kept in sync with the core library, whereas similar third-party packages on npm are maintained by different people and may not be up to date.
|
|
</p>
|
|
|
|
<p>
|
|
Addons do not need to be <em>installed</em> separately, but do need to be <em>imported</em> separately. If three.js was installed with npm, you can load the [page:OrbitControls] component with:
|
|
</p>
|
|
|
|
<code>
|
|
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
|
|
|
|
const controls = new OrbitControls( camera, renderer.domElement );
|
|
</code>
|
|
|
|
<p>
|
|
If three.js was installed from a CDN, use the same code, but with `three/addons/` in the import map.
|
|
</p>
|
|
|
|
<code>
|
|
<script async src="https://unpkg.com/es-module-shims@1.3.6/dist/es-module-shims.js"></script>
|
|
|
|
<script type="importmap">
|
|
{
|
|
"imports": {
|
|
"three": "https://unpkg.com/three@<version>/build/three.module.js",
|
|
"three/addons/": "https://unpkg.com/three@<version>/examples/jsm/"
|
|
}
|
|
}
|
|
</script>
|
|
|
|
<script type="module">
|
|
|
|
import * as THREE from 'three';
|
|
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
|
|
|
|
const controls = new OrbitControls( camera, renderer.domElement );
|
|
|
|
</script>
|
|
</code>
|
|
|
|
<p>
|
|
It's important that all files use the same version. Do not import different addons from different versions, or use addons from a different version than the three.js library itself.
|
|
</p>
|
|
|
|
<h2>Compatibility</h2>
|
|
|
|
<h3>CommonJS imports</h3>
|
|
|
|
<p>
|
|
While most modern JavaScript bundlers now support ES modules by default, some older build tools might not. In those cases you can likely configure the bundler to understand ES modules: [link:http://browserify.org/ Browserify] just needs the [link:https://github.com/babel/babelify babelify] plugin, for example.
|
|
</p>
|
|
|
|
<h3>Node.js</h3>
|
|
|
|
<p>
|
|
Because three.js is built for the web, it depends on browser and DOM APIs that don't always exist in Node.js. Some of these issues can be resolved by using shims like [link:https://github.com/stackgl/headless-gl headless-gl], or by replacing components like [page:TextureLoader] with custom alternatives. Other DOM APIs may be deeply intertwined with the code that uses them, and will be harder to work around. We welcome simple and maintainable pull requests to improve Node.js support, but recommend opening an issue to discuss your improvements first.
|
|
</p>
|
|
|
|
<p>
|
|
Make sure to add `{ "type": "module" }` to your `package.json` to enable ES6 modules in your node project.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|
|
|