-
-
Notifications
You must be signed in to change notification settings - Fork 35.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update manual (examples -> addons) (#24888)
* Change imports * Fix links * More fixes * Fix merge conflicts * Fix merge conflicts * More fixes * Rename Examples -> Addons in docs also * Update English versions of fundamentals.html and prerequisites.html
- Loading branch information
Showing
80 changed files
with
343 additions
and
318 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -116,13 +116,12 @@ <h1>Fundamentals</h1> | |
|
|
||
| <p>First let's load three.js</p> | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script type="module"> | ||
| import * as THREE from '../../build/three.module.js'; | ||
| import * as THREE from 'three'; | ||
| </script> | ||
| </pre> | ||
| <p>It's important you put <code class="notranslate" translate="no">type="module"</code> in the script tag. This enables | ||
| us to use the <code class="notranslate" translate="no">import</code> keyword to load three.js. There are other ways | ||
| to load three.js but as of r106 using modules is the recommended way. | ||
| Modules have the advantage that they can easily import other modules | ||
| us to use the <code class="notranslate" translate="no">import</code> keyword to load three.js. As of r147, this is the | ||
| only way to load three.js properly. Modules have the advantage that they can easily import other modules | ||
| they need. That saves us from having to manually load extra scripts | ||
| they are dependent on.</p> | ||
| <p>Next we need is a <code class="notranslate" translate="no"><canvas></code> tag so...</p> | ||
|
|
@@ -132,7 +131,7 @@ <h1>Fundamentals</h1> | |
| </pre> | ||
| <p>We will ask three.js to draw into that canvas so we need to look it up.</p> | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script type="module"> | ||
| import * as THREE from '../../build/three.module.js'; | ||
| import * as THREE from 'three'; | ||
|
|
||
| +function main() { | ||
| + const canvas = document.querySelector('#c'); | ||
|
|
@@ -365,69 +364,86 @@ <h1>Fundamentals</h1> | |
| making our code responsive so it is adaptable to multiple situations</a>.</p> | ||
| <div id="es6" class="threejs_bottombar"> | ||
| <h3>es6 modules, three.js, and folder structure</h3> | ||
| <p>As of version r106 the preferred way to use three.js is via <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import">es6 modules</a>.</p> | ||
| <p>As of version r147 the preferred way to use three.js is via <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import">es6 modules</a> and import maps.</p> | ||
| <p> | ||
| es6 modules can be loaded via the <code class="notranslate" translate="no">import</code> keyword in a script | ||
| or inline via a <code class="notranslate" translate="no"><script type="module"></code> tag. Here's an example of | ||
| both | ||
| or inline via a <code class="notranslate" translate="no"><script type="module"></code> tag. Here's an example | ||
| </p> | ||
| <pre class="prettyprint"><script type="module"> | ||
| import * as THREE from '../../build/three.module.js'; | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script type="module"> | ||
| import * as THREE from 'three'; | ||
|
|
||
| ... | ||
|
|
||
| </script> | ||
| </pre> | ||
| <p> | ||
| Paths must be absolute or relative. Relative paths always start with <code class="notranslate" translate="no">./</code> or <code class="notranslate" translate="no">../</code> | ||
| which is different than other tags like <code class="notranslate" translate="no"><img></code> and <code class="notranslate" translate="no"><a></code>. | ||
| Notice <code class="notranslate" translate="no">'three'</code> specifier there. If you leave it as it is, it will likely produce an error. An <i>import map</i> should be used to tell the browser where to find three.js | ||
| </p> | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script type="importmap"> | ||
| { | ||
| "imports": { | ||
| "three": "./path/to/three.module.js" | ||
| } | ||
| } | ||
| </script> | ||
| </pre> | ||
| <p> | ||
| Note that path specifier can start only with <code class="notranslate" translate="no">./</code> or <code class="notranslate" translate="no">../</code>. | ||
| </p> | ||
| <p> | ||
| References to the same script will only be loaded once as long as their absolute paths | ||
| are exactly the same. For three.js this means it's required that you put all the examples | ||
| libraries in the correct folder structure | ||
| Import maps are still unsupported in Firefox and Safari, so it is recommended to use <a href="https://github.com/guybedford/es-module-shims">an import maps polyfill</a> like so | ||
| </p> | ||
| <pre class="dos">someFolder | ||
| | | ||
| ├-build | ||
| | | | ||
| | +-three.module.js | ||
| | | ||
| +-examples | ||
| | | ||
| +-jsm | ||
| | | ||
| +-controls | ||
| | | | ||
| | +-OrbitControls.js | ||
| | +-TrackballControls.js | ||
| | +-... | ||
| | | ||
| +-loaders | ||
| | | | ||
| | +-GLTFLoader.js | ||
| | +-... | ||
| | | ||
| ... | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script async src="https://unpkg.com/[email protected]/dist/es-module-shims.js"></script></pre> | ||
| <p> | ||
| To import addons like <a href="https://github.com/mrdoob/three.js/blob/master/examples/jsm/controls/OrbitControls.js"><code class="notranslate" translate="no">OrbitControls.js</code></a> use the following | ||
| </p> | ||
| <pre class="prettyprint showlinemods notranslate lang-js" translate="no">import {OrbitControls} from 'three/addons/controls/OrbitControls.js'; | ||
| </pre> | ||
| <p> | ||
| The reason this folder structure is required is because the scripts in the | ||
| examples like <a href="https://github.com/mrdoob/three.js/blob/master/examples/jsm/controls/OrbitControls.js"><code class="notranslate" translate="no">OrbitControls.js</code></a> | ||
| have hard coded relative paths like | ||
| Don't forget to add addons to the import map like so | ||
| </p> | ||
| <pre class="prettyprint">import * as THREE from '../../../build/three.module.js'; | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script type="importmap"> | ||
| { | ||
| "imports": { | ||
| "three": "./path/to/three.module.js", | ||
| "three/addons/": "./different/path/to/examples/jsm/" | ||
| } | ||
| } | ||
| </script> | ||
| </pre> | ||
| <p> | ||
| Using the same structure assures then when you import both three and one of the example | ||
| libraries they'll both reference the same <code class="notranslate" translate="no">three.module.js</code> file. | ||
| You can also use a CDN | ||
| </p> | ||
| <pre class="prettyprint">import * as THREE from './someFolder/build/three.module.js'; | ||
| import {OrbitControls} from './someFolder/examples/jsm/controls/OrbitControls.js'; | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script type="importmap"> | ||
| { | ||
| "imports": { | ||
| "three": "https://unpkg.com/[email protected]/build/three.module.js", | ||
| "three/addons/": "https://unpkg.com/[email protected]/examples/jsm/" | ||
| } | ||
| } | ||
| </script> | ||
| </pre> | ||
| <p>This includes when using a CDN. Be sure your path to <code class="notranslate" translate="no">three.module.js</code> ends with | ||
| <code class="notranslate" translate="no">/build/three.modules.js</code>. For example</p> | ||
| <pre class="prettyprint">import * as THREE from 'https://unpkg.com/[email protected]<b>/build/three.module.js</b>'; | ||
| import {OrbitControls} from 'https://unpkg.com/[email protected]/examples/jsm/controls/OrbitControls.js'; | ||
| <p> | ||
| To conclude, the recommended way of using three.js is | ||
| </p> | ||
| <pre class="prettyprint showlinemods notranslate lang-html" translate="no"><script async src="https://unpkg.com/[email protected]/dist/es-module-shims.js"></script> | ||
|
|
||
| <script type="importmap"> | ||
| { | ||
| "imports": { | ||
| "three": "./path/to/three.module.js", | ||
| "three/addons/": "./different/path/to/examples/jsm/" | ||
| } | ||
| } | ||
| </script> | ||
|
|
||
| <script type="module"> | ||
| import * as THREE from 'three'; | ||
| import {OrbitControls} from 'three/addons/controls/OrbitControls.js'; | ||
|
|
||
| ... | ||
|
|
||
| </script> | ||
| </pre> | ||
| </div> | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.