looeee / discoverthreejs-site

Repo for the book Discover three.js!

Welcome to Discover three.js!

Languages: English (this file), 中文.

This is the public repo for the book Discover three.js.

Pull requests are welcome, especially for:

• Keeping the book up to date with new three.js releases.
• Errata in the text or code examples.
• Any other bugs, browser or CSS issues.

Search through the markdown folder for "TODO" if you're looking for inspiration ^_^

For larger contributions, please get in touch before making changes - you can open a discussion or issue on this repo.

Developer Guide

Here is the process for building and viewing the book.

Prerequisites: Node.js, Hugo

1. Clone or download the repo
2. Download the Hugo extended binary for your system here and place it in the project root. Tested with Hugo V0.92.0 (*)
3. Run npm install
4. Run npm start
5. Go to http://localhost:1313/ to view the site. You may need to make sure this port is open in your firewall.

* On linux systems you may need to set the ./hugo file as executable using chmod +x ./hugo.

Technical Details

The book is built with Hugo, and this repo follows a fairly typical folder structure for a Hugo project, although the content/ folder has been renamed to markdown/. If you want to make changes, refer to the Hugo docs.

Important folders

• markdown - all the words in the book are contained here.
• assets/src - JS source code.
• assets/scss - SCSS styles for the book are here.
• static - all static files such as figures, fonts, models, textures, images, and favicons are here.
• static/examples - the code for the IDE examples are here. Each example is a World - for examples: static/examples/worlds/first-steps/first-scene contains the example for the chapter First Scene. See static/examples/README.md for more details.
• /public - files generated by Hugo with the command npm run production will go here. By default, in development Hugo renders files into memory, however, it can be useful to generate the files if you need to examine them.

Notes

• Hugo Pipes are used to build SCSS and JS assets. This means the Hugo extended version must be used.
• Running npm start will take several seconds to bundle all the files so please be patient. However, once the server is running, updates should take just a few milliseconds.

LICENSE

Code License

All code in this repo (including code sample in the text and any source code in the /assets folder) is covered by the MIT license. You are free to use it however you like, including in commercial applications. This does not cover any included third party libraries which have their own license.

Text License

Text from the book may not be reproduced without permission outside of this repo and the website discoverthreejs.com. You are free to fork the repo to make changes to the text but you are not allowed to host the text on another site (such as your own blog or tutorial site).

discoverthreejs-site's Issues

VectorKeyframeTrack references ".material.opacity" instead of ".position"

In the following code in the animation section of the book: Link to code block description

The following code is provided:

These three keyframes will make an object start at the center of the scene, move right, up, and forwards over three seconds, then reverse direction and move back to the center. Next, we’ll create a vector track with these keyframes.

import { VectorKeyframeTrack } from 'three';

const times = [0, 3, 6];
const values = [0, 0, 0, 2, 2, 2, 0, 0, 0 ];

const positionKF = new VectorKeyframeTrack('.material.opacity', times, values);

Since this is a Vector track, the key track property should be .position, not .material.opacity

Welcome to the Discover Three.js Discussion Forum

Discussed in #8

^{Originally posted by looeee April 23, 2021}

👋 Welcome!

All readers of Discover three.js are welcome here!
This is a place for you to:

• Ask questions you’re wondering about.
• Share ideas.
• Engage with other community members.
• Welcome others and be open-minded. Remember that this is a community we
  build together 💪.

To get started, comment below with an introduction of yourself.

[ENHANCEMENT] All three.js examples displayed in iframes should be hosted locally

Currently, many of the official three.js examples are included as iframes throughout the book. These slow down the page load and upstream changes on the three.js repo may unexpectedly break something (if an example gets deleted from the three.js repo, for example).

{{< iframe src="https://threejs.org/examples/webgl_materials_envmaps.html" height="500" title="Image Based Lighting (IBL) in action" caption="Image Based Lighting (IBL): the scene background is reflected on the sphere" >}}

It would be better to extract the code from these and include them in this repo.

[BUG, ERROR] Add "precision: 'lowp/mediump/highp'" to renderer

There is a memory allocation error that prevents materials / shaders being drawn on Apple devices and firefox browsers. Gets fixed when adding

precision: 'lowp'

or

precision: 'mediump'

or

precision: 'highp'

to the renderer definition.

[BUG, ERROR] SphereBufferGeometry preview appears to be broken

Describe the bug
On https://discoverthreejs.com/book/first-steps/organizing-with-group/, The first preview box just appears as a gray box with no sphere preview.

To Reproduce

1. Go to https://discoverthreejs.com/book/first-steps/organizing-with-group/#introducing-spherebuffergeometry
2. Look at the gray box and witness the error

Expected behavior (optional)
A SphereBufferGeometry preview.

Screenshots

Desktop (please complete the following information):

• OS: Windows 10 Version 2009 (Build 19042.1052)
• Browser: Brave (chromium based)
• Version 1.26.67 Chromium: 91.0.4472.114 (Official Build) (64-bit)

Edit:
Upon progressing through the book, I found this to be broken too.

In Chapter "Physically Based Rendering and Lighting" the example from threejs is not found and returns 404 page.

Hello!

The first iframe on the page Physically Based Rendering and Lighting returns "404 not found error".

Describe the bug
See the red square on the screenshots:

To Reproduce

1. Go to the page the page Physically Based Rendering and Lighting and see the error.

Tested on desktop, mobile.

Suggestions
As the example was removed from three.js site, I suggest to delete the following lines from the book's markdown:

Thanks! If it's ok, I can open PR to fix the issue.

Tiny error - Chessboard image

Thank you for such an awesome resource to learn three.js!

There is a tiny error in the chessboard image -- https://discoverthreejs.com/images/first-steps/chessboard.svg -- on this page (https://discoverthreejs.com/book/first-steps/transformations/): the white queen and king must be switched :)

Driving example for Three.js

Hello People,
I made an example of driving an helicopter.
Simple, but good for beginners to control movements with Three.js
I would like your opinion and possible publishing of this work.
Respectfully,
José Roberto Lazzareschi
[email protected]
example: jrlazz.eu5.org/anim/heli.php

content cant render

Physically Based Rendering and Lighting

BoxGeometry instead of BoxBufferGeometry

Hello! I am following and trying to reproduce the code in https://discoverthreejs.com/book/first-steps/first-scene/

And I was getting this error:

Uncaught SyntaxError: The requested module './vendor/three/build/three.module.js' does not provide an export named 'BoxBufferGeometry' (at main.js:3:3)

After some research I realized instead of BoxBufferGeometry it needs to be BoxGeometry.

So maybe you want to fix it in the book.

Can re-initialize git ?

git file size too big because of history include hugo.exe 😂

[ENHANCEMENT]Do we have a chinese version translation of this book?

Do we have a chinese version translation of this book?
https://discoverthreejs.com/book/

[ENHANCEMENT] French translation

I suggest that the site has a French translation. I could take care of it

The book uses column-major order for matrices, while three.js docs use row-order

Describe the bug
When i was reading about transformation matrices topic in this book, i found that the description of formula of X-Rotation has a little difference with the makeRotationX method of Matrix4 class in official docs. I didn't know which one was correct. So, i report a issue here now.

Screenshots
Transformation Matrices

makeRotationX method of Matrix4 class

BUG Broken "How to Run Things Locally" link.

Describe the bug
As of this commit, on this page, there is a link How to Run Things Locally which points to a page which no longer exists on the threejs.org site.

To Reproduce
Steps to reproduce the behavior:

1. From a browser, navigate to https://discoverthreejs.com/book/introduction/about-the-book/
2. Search for the text "How to Run Things Locally"
3. The text is a hyperlink to https://threejs.org/docs/#manual/introduction/How-to-run-things-locally
4. Attempt to navigate to that URI.
5. Observe that the page is empty:

Expected behavior
Navigating to the link should result in seeing a page describing how to set up to run a threejs example on your local computer.

[ENHANCEMENT, IDE] Infinite loop protection in the IDE

Currently, the IDE doesn't protect against infinite loops.
It would be great to add this functionality.

There are two steps required here:

1. Research and identify possible solutions (e.g. what do codesandbox, glitch, codepen etc. use?).
2. Add it to the IDE.

[BUG, ERROR] iFrames don't load on Firefox

Describe the bug
I have to use Chrome to see the external content loaded in an iFrame throughout the book.

To Reproduce
Steps to reproduce the behavior:

1. Go to any page with an iFrame. Example: https://discoverthreejs.com/book/first-steps/textures-intro/
2. Observe the demo for the head by Lee Perry-Smith doesn't load in Firefox but does in Chrome.

Desktop (please complete the following information):

• OS: Fedora Linux
• Browser Firefox
• Version 103.0.2 (64-bit)

BUG

Describe the bug
As of 7bbaf74, downloading the code example using the NPM import style from this page produces a file containing cdn.skypack.dev URLs for some imports rather than using npm-aware imports.

To Reproduce
Steps to reproduce the behavior:

1. From a browser, navigate to https://discoverthreejs.com/book/introduction/about-the-book/
2. Make sure the Import Style by the live code editor on the right side of the page is set to NPM (default)
3. Toggle the slider to the ON position
4. Observe the cool sparkleHorse being rendered.
5. Observe that the sparkleHorse.js file's first line is import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'; as expected.
6. Download the code using the Download as Zip icon.
7. Unzip the downloaded .zip file
8. Find the sparkleHorse.js file and observe that its first line is import { GLTFLoader } from 'https://cdn.skypack.dev/[email protected]/examples/jsm/loaders/GLTFLoader.js'; contrary to expectations

Expected behavior
If the NPM Import Style is selected, expect the downloaded .zip file to exactly match the code displayed in the live code editor.

Desktop (please complete the following information):

• OS: Linux (OpenSUSE 15.4)
• Browser: Chrome/Chromium
• Version: 118.0.5993.88 (Official Build) (64-bit)

[BUG] Noindex error

https://discoverthreejs.com/book/ is marked noindex by mistake. It should be index, follow.

Putting this here to track - I will fix it myself. Lewy

Imports broken since three.js update

Hi Lewy!

First of all, congrats to your great book, I love it. Especially the modular approach. Unfortunately, since the most recent three.js updates, your cdn imports don't work anymore. First of all, the version you've linked to cannot be found anymore. After changing that to the newest version (0.137.5 as of time writing), the next error shows up:
index.html:1 Uncaught TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".
I assume that this is due to the newly introduced import mapping, which isn't represented in your source codes yet. Adding this snippet:

	<!-- Import maps polyfill -->
	<!-- Remove this when import maps will be widely supported -->
	<script async src="https://unpkg.com/[email protected]/dist/es-module-shims.js"></script>

	<script type="importmap">
		{
			"imports": {
								"three": "./vendor/three/build/three.module.js"
	               }
		}
	</script>

to the index.html file solved this issue, but now the next error states that there is an
Uncaught SyntaxError: The requested module '/-/[email protected]/dist=es2019,mode=raw/examples/jsm/controls/OrbitControls.js' does not provide an export named 'default'

Please be so kind and update your ressources, which I use as a starting point for all of my three.js projects now.

Best regards,
Daniel

[ENHANCEMENT] Add a search function to the book

The book needs a search function!
This should be added to the left many via a search box near the "Table of Contents" heading.
Search results can either go alongside, replace, or be added into the table of contents.

Lunr.js is probably the easiest to set up.

Some good info to get started here: https://gohugo.io/tools/search/

[ENHANCEMENT] Improve Accessibility of Icon Controls

All icon controls in the IDE and top navbar need to have accessible labels added.
This can be done be adding a new CSS class - something like .visually-hidden - and then adding a <span class="visually-hidden">Control Info</span> to each control.

[ENHANCEMENT] Use skypack.dev instead of unkpg.com

Load modules from skypack.dev instead of unpkg.com
As per the three.js migration guide, this will have to be done before updating to three.js >=r128.

https://www.skypack.dev/view/three

There are two places that need to be updated:
[] Anywhere in the text that unpkg.com is mentioned
[] Inside the IDE

In both cases, a simple search and replace should be enough, however, the IDE downloads will need to be tested after making the change.

[TYPO/BUG] Backslash added before * of namespace imports

Description
A backslash (\) is added in front of the * sign for namespace imports, like so:

import \* as THREE from 'three'

This seems to happen systematically, i.e. the backslash is not in the .md files but is added from somewhere else.

Examples

• https://discoverthreejs.com/book/introduction/get-threejs/#import-the-entire-threejs-core
• https://discoverthreejs.com/book/appendix/javascript-modules/#using-namespaces-with-named-imports

[ENHANCEMENT] Add a print style sheet

The print style sheet should hide the IDE and enforce the light theme to save pinter ink, then ensure that the layout looks ok in print preview.

This should be a relatively small amount of work.

BUG https://cdn.skypack.dev/[email protected] not found

Please report bugs, rendering errors, CSS problems, cross-browser issues and so on here.
If you have found a mistake in the text, you can also report it here, although there's no need to report OS/browser details in that case.

Describe the bug
When performing "Download as Zip" from IDE, zipped site contains references to https://cdn.skynet.dev/[email protected] which does not exist. As of this date, references to https://cdn.skynet.dev/three produce 0.148.0 as the only option:

/*
 * Skypack CDN - [email protected]
 *
 * Learn more:
 *   📙 Package Documentation: https://www.skypack.dev/view/three
 *   📘 Skypack Documentation: https://www.skypack.dev/docs
 *
 * Pinned URL: (Optimized for Production)
 *   ▶️ Normal: https://cdn.skypack.dev/pin/[email protected]/mode=imports/optimized/three.js
 *   ⏩ Minified: https://cdn.skypack.dev/pin/[email protected]/mode=imports,min/optimized/three.js
 *
 */

// Browser-Optimized Imports (Don't directly import the URLs below in your application!)
export * from '/-/[email protected]/dist=es2019,mode=imports/optimized/three.js';
export {default} from '/-/[email protected]/dist=es2019,mode=imports/optimized/three.js';

To Reproduce
Steps to reproduce the behavior:

1. From a browser, navigate to https://discoverthreejs.com/book/first-steps/first-scene/
2. Click on the "Show IDE" icon in the far upper-left corner of the browser client area to make sure the IDE is visible:
   
3. From the IDE, click the "Download as Zip" icon:
   
4. When the download completes, you should have a file like the following in your Downloads/ directory:
   
5. Unzip the file and locate src/main.js. Observe that it contains an import statement as follows.

import {
  BoxBufferGeometry,
  Color,
  Mesh,
  MeshBasicMaterial,
  PerspectiveCamera,
  Scene,
  WebGLRenderer,
} from 'https://cdn.skypack.dev/[email protected]';

6. Observe that the import refers to three version 0.136.2.
7. From a browser, attempt to navigate to 'https://cdn.skypack.dev/[email protected]'
8. Observe this message in your browser: Package "three" exists, but could not match version "0.136.2".

Expected behavior (optional)
Attempting to navigate to 'https://cdn.skypack.dev/[email protected]' should result in something like this in your browser:

Desktop (please complete the following information):

• OS: Ubuntu Linux 22.04.1 LTS
• Browser: Chrome
• Version: 109.0.5414.74 (Official Build) (64-bit)

Additional context
Add any other context about the problem here.

[BUG, ERROR] Mirror example in Camera Controls is not found

Describe the bug
The first example in the Camera Controls section displays a 404: File not found error.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://discoverthreejs.com/book/first-steps/camera-controls/
2. Scroll down to the first example on the page immediately following the text

These add all kinds of functionality, such as mirrored surfaces:

3. See 404: File not found error.

Expected behavior
The example should not render a 404 not found warning but an actual example.

Screenshots
n/a

Desktop:

• OS: Fedora Linux
• Browser: chrome
• Version: 104.0.5112.79

Additional context
It looks like the example was removed. The old url pointed towards https://threejs.org/examples/webgl_mirror_nodes.html. Perhaps it should be pointing towards https://threejs.org/examples/webgl_mirror.html instead. Unless this isn't the intended example.

[ENHANCEMENT] three.js/examples/js has been removed

I was reading section 0.4 so I happend to checked the github repo of three.js as the book says.

And I found that three.js/examples/js was removed(mrdoob/three.js#25043).

Thus I suppose now the paragraph following(in section 0.4) would not be necessary?

Legacy plugins in the examples/js folder. These are the same set of plugins you’ll find in the examples/jsm, however, they will work with outdated browsers. Just like the legacy versions of the core, the legacy plugins will be removed soon and we’ll ignore them in this book.

Make updating the three.js version easier

The IDE needs to load three.js files at run time, however, it doesn't have access to node_modules.

Currently, I'm solving this by manually copying node_modules/three into static/examples/vendor/three.
It would be great if there was some way to do this automatically.

BoxBufferGeometry replacement for BoxGeometry

Apparently the BoxBufferGeometry, which is the first example in the book on creating geometry (https://discoverthreejs.com/book/first-steps/first-scene/#the-geometry), has been replaced by just BoxGeometry in newer versions of Threejs (https://discourse.threejs.org/t/three-geometry-will-be-removed-from-core-with-r125/22401).

Shouldn't this section of the book be updated?

[BUG, HELP WANTED]

Hugo can be installed in various ways on a number of platforms - in particular, Windows, Mac, and Linux, - and either by downloading the binary to a local folder or using a package manager such as choco or snap to install it globally, creating cross-platform NPM scripts that run Hugo is tricky.

Currently, I've added a note to the repo saying that it might be required to adjust the start and production scripts in package.json replacing .\\hugo:

• .\\hugo: current approach, works for local install on Windows
• ./hugo: required for local install in Mac or Linux
• hugo: for global install on any platform

An obvious solution is to require a global install but this makes installing Hugo trickier for people who are not familiar with package managers or editing $PATH so I would prefer to avoid this.

adding a file tree structure to chapters of the book[ENHANCEMENT]

Hey community, I was reading the documentation and thought won't it be pretty easy ,if one(maybe me) put file tree structure in the initial documentation "The Structure of a three.js App"?
something like this:
--src
|-index.html
|-src
|-main.js
|-stylles
|-main.css
Just a suggestion, I may not be right or misinterpreted the goal of the tutorials.

.physicallyCorrectLights has been removed

Three.webGLRenderer: the property .physicallyCorrectLights has been removed. Set renderer .useLegacyLights instead is displayed in the console when I use it.

The solution:

renderer.useLegacyLights = false;

[BUG, ERROR]Get error when do npm start.

When I follow the Developer Guide to run this repo locally, I am getting below error:

PS D:\kevinzhang\study\3D\discoverthreejs-site> npm start

> [email protected] start D:\kevinzhang\study\3D\discoverthreejs-site
> npm run copy-three && cross-env NODE_ENV=dev npm run run-hugo


> [email protected] copy-three D:\kevinzhang\study\3D\discoverthreejs-site
> node scripts/copy-three.cjs

Copying three.js V0.136.0 to examples folder...

> [email protected] run-hugo D:\kevinzhang\study\3D\discoverthreejs-site
> node scripts/run-hugo.cjs

Start building sites … 
hugo v0.92.0-B3549403+extended windows/amd64 BuildDate=2022-01-12T08:23:18Z VendorInfo=gohugoio
INFO 2022/08/12 15:54:44 syncing static files to D:\kevinzhang\study\3D\discoverthreejs-site\
INFO 2022/08/12 15:54:47 postcss: Browserslist: caniuse-lite is outdated. Please run:
  npx browserslist@latest --update-db
  Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
INFO 2022/08/12 15:54:47 postcss: Browserslist: caniuse-lite is outdated. Please run:
  npx browserslist@latest --update-db
  Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
INFO 2022/08/12 15:54:48 postcss: Browserslist: caniuse-lite is outdated. Please run:
  npx browserslist@latest --update-db
  Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/appendix title: 附录
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/appendix/html-and-css-reference title: HTML, CSS
ERROR 2022/08/12 15:54:49 Page not found. URL: book/appendix/dom-api-reference/#your-browser-s-developer-console title: 
浏览器开发者控制台
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/appendix/javascript-reference title: JavaScript
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/appendix/javascript-modules title: 模块
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/appendix/asynchronous-javascript title: 异步编码模式
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/first-steps/_index.md title: 主章节
ERROR 2022/08/12 15:54:49 Page not found. URL: book/appendix title: 附录
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/first-steps/transformations title: 1.5：变换和坐标系
ERROR 2022/08/12 15:54:49 Page not found. URL: /book/first-steps/load-models title: 1.13：加载 glTF 格式的 3D 模型
......

What happened, any help?

Error in the margins of the website footer

Hi guys!
Hope you are ding well.
I wanted to let you know that you have an amazing website and I am really inspired by the way it is designed.
I just noticed a slight error in the footer of your website.

You have given a a margin on the right side of the footer but not on the left side. I have attached an image below.
Please do have a look.

[QUESTION] Better alternatives for implementing the Cube tick method

I've been following along the book just fine writing the code in TypeScript instead of JavaScript, and have a question regarding The cube.tick Method section of the material.

The material mentions:

However, we shouldn’t get into the habit of doing this carelessly since in certain situations it can cause performance issues. We’ll only allow ourselves to do this here as the alternatives are more complex.

I'm curious what the alternatives would be because I have to add // @ts-ignore to the line before the cube.tick function. I'd love to be pointed in the direction of better ways to implement this functionality to deepen my learning and apply it in a more TypeScript safe way.