Error rabbit hole incited by documentation

Discussion
1

Hi all, just started using three.js yesterday. My main goal was to load up a model I had created in Blender which I eventually succeeded with. Very nice!!

To get there was a bit of a struggle, I want to go over this journey as I feel the documentation could have been better in regards to this particular task.

To begin with, the Getting Started page is confusing to an absolute newbie as it gives you a single three.js file before the actual installation documentation. It took me some time to understand that there was more to the library than just this file. Not to mention that the documentation encourages using files from the same master version. I don’t believe this part is so bad, but I’m just noting my experience with it. It confused me.

So with the master downloaded and the three.js file replaced, my next task was to get the GLTFLoader working. I am using Atom code editor for this, very simple HTML, CSS and JavaScript, so import statements were out of reach, instead the GLTFLoader would be referenced with script tags in HTML.

My problem here was that the Loading a 3D Model documentation shows to import “three/examples/jsm/GLTFLoader.js”, however, using the file led to this type error, “Uncaught TypeError: THREE.GLTFLoader is not a constructor”, which if you google has caused some confusion. I found that using the “three/examples/js/GLTFLoader.js” file instead, fixed this error for me and I could see my model.

It did take me around 3 hours to resolve this, as I am also learning JavaScript at the moment and didn’t understand where to find the console. Due to this, I was troubleshooting camera position and lighting first, this is suggested when you google “three.js GLTFLoader black screen”.

I understand that this post is a bit trivial, and that I may be wrong about several things in here, but I thought it was worth pointing out from a user experience point of view. I will definitely continue to use three.js.

Thanks for reading.

2

Imo three.js is not a very good library to learn Javascript with - it’s 3D, it’s fun, but it quickly gets complex and has its own quirks. Sooner or later you will encounter some tricky parts of JS, like clojures or endless mutability, and you will be stuck on errors for far longer than 3 hours, trying to figure out whether it is an issue of three or your own code. So basic ES/npm/debugging knowledge is kind of prerequisite.

(Since imports are a cause of a lot of issues of new users, judging by the topics around here - it may indeed be a good idea to explain in the docs that /jsm/ files are ES6, and /js/ files can be linked as external <script>. Couldn’t find it there.)

6 Likes
3

I am pretty happy to learn them side by side and step back to just JavaScript practice if it gets too complicated. I have written a few apps in Java/Kotlin as well as some shaders in OpenGL, I know this is quite different to JavaScript, but some of the fundamental concepts can be similar.

It does appear that the external modules will soon be deprecated anyway, so this topic is kind of pointless. I guess the documentation makes sense with this in mind. It also means that I will for sure learn about npm and JavaScript debugging.

1 Like
4

Looks like the Creating a Scene guide is a bit outdated. It should be recommending using three.module.js rather than three.js which I think is being deprecated soon. @eggyolk would you like to open an issue on GitHub about this?

1 Like
5

@looeee I don’t think it would be necessary given that the modules mentioned will be deprecated soon, the problem described probably won’t happen often when that is the case.