Examples website

Discussion
1

I have always felt the three examples website has been a bit of a letdown in transferring knowledge and was wondering if it would be worth opening a discussion about ways to improve it. Some suggestions from me…

  1. Put a note as to what version a particular feature was added in. For some of us, it is difficult to just upgrade to the latest version of three all the time, so sometimes I like the look of an example and find it isn’t in my version. Perhaps being able to see and filter by version would help realize what I can and can’t use and also help make the decision whether to upgrade or not.

  2. Have a short description where necessary. For beginners, some of the examples are not clear what’s even occurring or why it is useful. Where possible improve the comments in the code, I have seen various things in the examples where i have no idea why things are done the way they are and it ends up having to ask on the forum

  3. To complement the above link to the relevant page in the docs where possible, at the moment the docs link to the examples.

  4. Have the examples be able to load in code pen or similar. Currently, when you click the code button it opens up a new window and takes you to the source code, which is handy. But it would be really great if we could actually easily play around with the code. E.g. there may be a new feature that I want to test something out in, rather than me having to download everything and set it all up, being able to open up a sandbox(?) version would be great. I believe this may also help with forum support as someone would have a ready-to-go live setup they could clone and share as a basis for their question.

  5. Middle-clicking an example thumbnail opens a new window but it doesn’t have the thumbnail sidebar I believe it should.

  6. Ability to filter/search list

  7. Some examples don’t work in Firefox, show a warning/flag the thumbnail instead of just nothing happening - this is important as some of us can’t use features that aren’t cross-browser supported.

  8. Improve the interface…unfortunately, I cannot suggest exactly what and #6 would help, but just having a long scrollable list is not very user-friendly. Maybe collapsable categories.

Don’t get me wrong its all great stuff and very helpful, i just think, certainly for beginners, its not the easiest to navigate and get stuck in to.

1 Like
2

i 100% agree with all these though it would be a lot of work, and in most cases probably very hard to fix without the original authors help. i think they’re mostly aimed at showing what three can do, but once you want to use one of these features in your own code you easily have to invest a day or more to untangle pages of spaghetti code without documentation. code sanity in these examples in my opinion is not ideal, they kind of obfuscate what they’re about, as in, the thing you’re looking for is covered by 95% boilerplate.

for instance, recently i wanted to use the lightmap bake thing, it took me a full week until i finally had it separated from the demo code. if these examples could be a little bit more principled, re-usable, in folders with multiple files, and with the tiniest bit of documentation that certainly would help a lot!

2 Likes
3

It is obviously a question of the target of the sample page.

I feel that the examples are meant to demonstrate the great possibilities of three.js.

Therefore, they are often complex and thus hardly manageable for the beginner. Even if you’ve been working with three for a while, you’ll need some time to put the core of the thing into a simple example and remove the stuff that wasn’t needed or considered before.

So you would need two categories of examples:

  1. demonstration of the individual functionalities,
  2. complex examples.

But this makes a lot of work and could surely only be considered as a long-term goal.

By the way, the problem is a major reason why I started the Collection of examples from discourse.threejs.org.

Recently, more and more questions and examples are posted with use of more external libraries and especially react.

This does not make it easier for the “normal” three.js user.
(One example: Mapping Text onto faces of Cube - #14 by drcmda … )

There was already a discussion here to mark these questions separately to “questions”.

I decided not to include such examples (as a rule) in my collection.

4

feel that the examples are meant to demonstrate the great possibilities of three.js.

I think the showcases perhaps do a better job of this. To me, especially since the docs point to them, the examples are a way of learning how to do certain things. It’s just they are not necessarily written with a novice in mind.

Recently, more and more questions and examples are posted with use of more external libraries and especially react

Yeah, it’s frustrating at the rate some great additions are being added just in react. There’s no way I could convert existing projects to react, and I have no idea how to change a react component to standard JS. But I guess that’s just the nature of an open-source internet library.

By the way, the problem is a major reason why I started the Collection of examples from discourse.threejs.org.

Good resource!

5

i can also not post them, i don’t mind at all, i do it because i think it can help in either case, vanilla or not. it’s usually a good solution to the problem, or at least they can find what they need in the open source.

but that’s imo outside the scope of this topic. i still do think that the threejs examples could be more principled because why not.

  1. each new example is a folder, not a .html
  2. it contains a readme.md with a description and hints for people that want to use it
  3. the source is logically split into files that can be studied in isolation and even re-used
  4. the source has comments explaining things that would be necessary to understand
  5. there is something like a small contributor guideline, for instance making it a policy to focus on the feature. why do i want to switch through 10 environment maps and whatnot if the feature has nothing to do with environments, but now it’s doubling the code, etc
2 Likes
6

These two I fully agree with. However, this has been suggested and denied previously over on GitHub. The last time I saw it was a few years ago so possibly @mrdoob has changed his mind since then. But if not, asking for these changes to be made on the three.js repo is a non-starter and not worth spending time on.

The only possibility I see is to create a separate repo and host more user-friendly, modern code-style versions of the examples there.

It would be amazing, imagine a set of examples showing vanilla three.js, Typescript, R3F, Svelte and so on side by side, well documented with explanations of the features they are intended to showcase, and immediately editable in Codesandbox. It would be an invaluable learning resource.

However it’s a ton of work, including a lot of ongoing work to keep the examples up to date with three.js changes.

7

this is pretty nice: use-gesture. all examples get linked into an examples repo that is built separately, but they can all be sandboxed individually like so:

`https://codesandbox.io/embed/github/three/tree/main/examples/${name}`

one click and people can see it, but also edit and play with it.

it’s possible because each example has its own folder and a small package.json:

{
  "name": "threejs-example-instances",
  "version": "1.0.0",
  "main": "src/index.jsx",
  "dependencies": {
    "three": "0.146.0"
  },
  "scripts": {
    "start": "parcel start",
    "build": "parcel build"
  },
  "browserslist": [">0.2%", "not dead", "not ie <= 11", "not op_mini all"]  
}

add a readme.md and it would be complete.

did they explain back then why they didn’t want folders and docs?

8

These are some related issues I recall. Im sure there are more

1 Like
9

So I totally agree that clicking the thumbnail to a new tab or window should open with the sidebar.
I get why the examples html files don’t have the sidebar, but instead of targeting the html directly send to the examples page with the location hash… drives me nuts

The list is searchable, it doesn’t have tags or anything but topic/name is there.

I think one thing happening is looking a react-three examples over and over confuses the perception of all the standard boilerplate it takes to get a vanilla scene going.

Then if you compare something advanced that loads a shader or something it could make the total page incredibly long (especially compared to modularized react)

Three doesn’t have to be that way, you could load it in some module or script tag,
but then it makes the example multi-page and non-standard so you’re hunting around for the files like digging through a old repo on github.

Each page has to stand on its own as a single page app, so it kinda has to have all that junk…

As to CodeSandbox, stackbitz, CodePen, etc…
I get the feeling they’ve seen too many platforms come and go, or stagnate so then they’d have a bunch of dead buttons…

I do believe though that CSB has a URL schema, some others do too, so it wouldn’t have to be sandboxes the library maintains, just formatted links to the examples…

From what I can tell, most examples are often the working example for a new feature or concept, and the best way to explain and get it merged…

It’s not totally a educational piece but a showcase/working example…

They could enforce better inline docs, but a lot of devs suck at that, so might abandon the PR altogether…

Once it’s up no one really wants to do the grunt work of commenting/explaining…

Maybe that would be something for a beginner issue or “first PR” project type of thing?

10

I too have noticed the shortcomings of the examples many years ago.

The problem is that the examples serve as a show-off of three.js capabilities rather than a means to educate the developers about a specific feature, which should be the first priority.
The educating feature X is usually burried in a complex code under Y, Z, and W features, all perplexed to show-off a cool visual.

So in my view, each example should be the minimum possible code required to demonstrate a specific feature and only that, alone. That way it would not need to be deciphered from the rest code and features in order to extract the desired knowledge and learn.

That aside with the other suggestions above would make the examples of coolness educating examples of learning fast three.js and thus making the overall three.js package more attracting, efficient and user-friendly.

2 Likes
11

yes, that’s how it works. it’s what i linked above. it can be completely outside of their service. these dev environments have learned to just read package.json, which tells them the title, author and the dependencies that are necessary. a click and users are running it, but they can change code, fork or download and have everything setup for local use.

while this would be wonderful, the biggest issue i’ve faced is similar to what @dllb just said, the thing you want to study is burried away.

12

I personally think some tags would be a good start and easy to implement. How are we supposed to know where things are in the first place? E.g. I know there’s an example with the new blurred background, but if I search blur nothing comes up.