pmndrs
Examples are too convoluted
Is your feature request related to a problem?
I'm quite excited about using this library, but I find the demo examples quite convoluted. Basically there are two issues:
-
Demos try to demonstrate more than 1 concept which makes it hard to read the thing you are looking for. For example the Blooming demo has antialiasing, two separate bloom effects which I then need to untangle. Half the file is about setting up the GUI and the environment. The constructor alone takes up 1 screen. Why is it necessary to rotate the objects. Its quite unnecessary and it complicates the example.
-
Demo's depend on other files through inheritance. I find myself busy for quite some time figuring out where composers are defined, what the 'assets' property is etc. For example why is the render function not included in this file. Also, why are the imports relative to the src directory, that's not how I will use it right?
Describe the solution you'd like
Make simple, short, standalone demos (HTML files!) that can be run by itself. Maybe you can take inspiration from the THREE.js examples? I quite like those. Sometimes a bit too extended as well but never really a problem.
Hey, thanks for the feedback!
The main purpose of the demos is to showcase the effects and to verify that they work, but I get what you mean and I agree that it would be nice if the demos were a bit easier to read.
The current setup is easy to maintain because it follows the DRY principle and produces a single optimized code bundle. However, it's a good idea to explore a different approach with standalone demos.
For example the Blooming demo has antialiasing, two separate bloom effects which I then need to untangle.
SMAA has been the default anitaliasing solution for a while now and it requires some setup code, but the demos are likely going to switch to MSAA in the future which will remove SMAA from most demos. I don't think keeping both bloom effect versions in the same demo is necessarily a bad thing. The setup code for both effects is pretty short after all.
Half the file is about setting up the GUI and the environment.
It's unfortunate that the GUI setup takes up so much space, but even with standalone demos this wouldn't really change.
The constructor alone takes up 1 screen.
That's mostly due to the doc comments. The other reason is vertical indentation which I find just as important as horizontal indentation. The good news is that the comments will be reduced or removed when the demos are converted to TypeScript.
Why is it necessary to rotate the objects.
I think it's a good way to showcase how bloom interacts with non-blooming objects and to see how antialiasing handles diagonal lines.
I find myself busy for quite some time figuring out where composers are defined, what the 'assets' property is etc.
The intention was to reduce boilerplate code as much as possible to be able to focus on the meat of the matter, namely asset loading, the scene/pass setup and the GUI controls.
For example why is the render function not included in this file.
The current approach allows it to be defined in one place. With standalone demos, every demo needs its own render method.
Also, why are the imports relative to the src directory, that's not how I will use it right?
The three.js examples also import the library from a relative path because that's where the latest library code is located. This is especially important during development where importing the NPM package makes no sense.
Make simple, short, standalone demos (HTML files!) that can be run by itself.
Including raw JS code in HTML files is not a practice I'd want to promote. I think it's important to keep the code separate from the HTML file to be able to do tree-shaking, transpilation and minification. The demos will be converted to TypeScript soon, so they will need to be processed by a bundler and the current setup makes this easy, especially because it only has to create a single bundle. Changing the approach to standalone demos will require changes in the build setup to create separate bundles for the individual demos.
Thanks for your feedback! I think your first sentence says it all; if the goal is to showcase and verify that it works then how it works now is fine.
However that would not be my choice. Im using tens if not hundreds of libraries and digging through their documentation and source code files takes up a lot of my time. So I will definitely favour the ones that are easier for me to wrap my head around. Obviously DRY and separating JS and HTML are good principles in normal production environments. Because the goal there is to provide stable, fast, small etc code. The goal of the demo files IMHO should be to teach people. Therefore I think those principles should be less important than readability in this case.
These are just my 2 its, so feel free to do with it what you want :) In this case I had to choose to go for 'native' three functionality. I spent several hours on this library and I just felt it would be easier to go with the native solution. I hope I get the chance to revisit this library in the future.