Babylon.js Ease of Use

Just found really great and extremely funny SCIENTIFIC document about Babylon.js ease of use - http://www.diva-portal.org/smash/get/diva2:1523176/FULLTEXT01.pdf

For the ease of use part, observation sessions were made with nine developers who were tasked with getting a basic 3D model up and running locally with each framework with the official documentation as a starting point, one hour limit respectively.

Here is just one experience “from the other side”.

Participant I
Hardware + OS: macbook pro, ubuntu
Languages + techniques: c++,c#,html,js, have used 3d before. not used webpack/node in a while so didn’t remember how it works and how I remembered how it works was wrong and made me confused.

Babylon.js

Runs ‘npm install --save babylonjs’
“Well now it went wrong.”
Deletes everything and creates a test folder and then runs ‘npm init’ first and then ‘npm install’.
Reads about imports via link 2 then reads under ‘getting started’ via link 1.
“So we can test an example then to see if things work.”
Copies some code from getting started.
"It’s been a long time since I’ve done this but we’ll see if we get things to work”
Googles ‘npm run package.json’
Ends up on michael-kuehnel.de guide about npm, follows it a bit.
“Aha maybe it is not an imported script, but why doesn’t it want to, now I lost the second link.”
Pastes import * as BABYLON at the top of a .js file.
Gets syntax error, cannot import module.
“Ouch ouch ouch.”
Tries require instead of import.
Reloads, gets ‘engine is not defined’.
“I suppose I have to go back and check out how the heck this works.”
Googles ‘npm tutorial’.
Reads over at nodesource.com.
Double-checks that guide with own installation.
Goes to sitepoint.com/npmguide.
Googles ‘npm tutorial run script’
Back to the michael-kuehnel.de guide.
Runs ‘npm --help’ and reads a bit about it.
“Yes it was an error message.” Refers to it being connected to babylon.js not npm.
Reads more in the Babylon.js docs.
Copies selective import {engine} etc scene from babylonjs.
Tries to use import instead of require.
Reads throughout the npm support page.
“Need to do all these things as well.”
Runs ‘npm install --savedev typescript webpack tsloader webpack-cli’.
Creates a webpack.config.js and pastes the sample code there.
Also adds an tsconfig.json.
“Should I really need to include…?”
Creates HTML file index.html and pastes code from npm support page Babylon.js docs.
“This seems to be for ts, that’s not what I’m doing here.”
Finds guided learning getting set up in the documentation, scrolls through it and reads.
Opens getting started again, link 1.
Big sigh.
Clicks on the ‘first scene and model’ and getting started playground, it comes up a cube.
Scrolls more in ‘first scene and model’ section.
Googles ‘babylon nodejs’, clicks on a local webserver guide, goes back to babylon.js.
Peruses documentation, homepage, diving deeper, api, babylon native. Clicks on learn and then documentation, getting
started.
“I have already looked at this.”
"Well, they could have been a little clearer but they seem to have their own thing that they test all their examples in.“ Refers to
the playground.
Deletes everything in the test folder.
Creates an index.html.
Now follows guided learning create a game tutorial.
run sudo apt-install node-typescript.
“Do you need all that?”
Runs everything anyway.
Runs ‘npm run build’ but gets error that it does not resolve some dependencies with webpack, cli and more.
Checks through its terminal history.
Creates a public folder and moves index.html to it.
Clean webpack plugin seems to have problems.
Runs ‘npm run start’ and gets ‘webpack-dev-server not found’.
“Here we see that it is installed.”
Installs it again anyway.
Does not seem to work.
Runs the installations of typescript and ts-loader etc.
Gets several deprecation warnings that fsevents will break and chokidar will break on nodev14.
The computer crashes and the participant drops out of zoom-call, back again two minutes later.
Googles ‘set up babylon.js’
Comes to the a page on tree shaking on Babylon.js docs.
Tries ‘npm run build’.
Reads more on the tree shaking page.
Goes to stack overflow.
Runs ‘npm run start’, does not work.
Deletes entire node_modules.
Copies webpack-dev-server again from the guide to start a game within Babylon.js docs.
Runs ‘npm run build’.
Runs ‘npm run start’.
Gets error ‘cannot find node_module webpack-cli’
Installs it.
Runs ‘npm run build’.
Opens index.html in the browser, sees a sphere.
“But if I do as they write there I don’t get it to work. Only like this.”


Do you recognize yourself in this example? As for myself - yes, I do.
I also have to admit that while reading this I’ve laughed to tears :slight_smile:

From my point of view the “Getting Started” part of the docs should give more clear and structured information about the possible first steps which are not so evident for users as one may think.

5 Likes

Dear lord. This was/IS me, over the last 72 hrs, with far less experience :joy: Certainly makes me feel better. I hope it gets easier… any day now, I’m waiting for it to all just click! :smiley:

I do think some parts of Babylon’s Documentation could be made easier to consume and stitch together though. The Playground is helpful but it makes it challenging to understand use-case without literally tinkering until something clicks. For a newcomer it consumes a lot of time “play-testing” or deciphering someone else’s PG, which is good for some things and frustrating for others.

Personally, most of the time I want to quickly know how a piece of the jigsaw connects with the next, and ideally rely on PG as a last resort. I think Blender and it’s Python integration is good example, where things feel a bit more intuitive to understand, search a solution or click together with a bit of python…

2 Likes

As the main author of the “Getting Started” section I wrote it from the point of view of the things I would have wanted to know when I first started to learn Babylon.js back in 2015 and there was a decision to write it in book style that you read from start through rather than a dip in style. As such it concentrates on the basic methods and facilities of Babylon.js. Obviously the backgrounds and needs of people coming to Babylon.js vary widely and will have different expectations of what “Getting Started” should be
about.

Currently this need seems to be about something more than the basic use of the template from
Getting Started - Chapter 1 - Setup Your First Web App | Babylon.js Documentation though I am not yet clear what this need is.

Like others I am just a member of the community and not part of the main team. The content of the docs are the work of the community.

We all want the docs to help whatever approach people want to take as far as it is possible. If a new section or pages are needed for people just beginning with Babylon.js then please help by either laying out a summary of page titles and content or even better submit a PR of the section or pages. Perhaps a template section is needed.

Those of you who have struggled in getting started and have overcome are probably the best people to do this.

2 Likes

@JohnK Your book style is brilliant. I just put some documented evidences about how it is difficult for users to enter Babylon world (only 63 % of the participants managed to implement a most basic 3D model and setup in Babylon.js in one hour).

From my point of view “The Getting Started” section should undertake a massive remake.

All that new users actually need are just pointers/links which directly give them what they need. They don’t want “to move through Getting Started”, they want to get clear instructions how to start.

At the moment these instructions are either unclear or just hidden in other sections. This section - NPM Support | Babylon.js Documentation - is even more confusing for newcomers (if they managed to find it). We can see this confusion in everyday forum questions (just one example - [Solved] Getting Set Up not running) and it takes a lot of time from all community members - to answer to the same questions again and again.

One particular perspective that the 3rd paradigm could give us is on the reluctance to extensively read the manual before knowing if something works. This is how people do, so how can they be supported in their learning process? No matter the scores and task times, many of the observed developers now do not have a pleasant attitude towards Babylon.js and Three.js. They did not have a joyful and smooth initial experience with either framework.

1 Like

I would still qualify your quote with

All that some new users actually need is…

It does depend on the expectations of the new user. For those who want to start by quickly learning the basic methods and features of Babylon.js I would argue that the Getting Started section serves them well and that is does is borne out by the decrease in questions about these basics. Now I would agree that from some of the current questions in the forum some users want clear instructions on how to quickly set up a working local Babylon.js system and this could range from a basic HTML template using JavaScript to a full blown complete working environment using NPM and Typescript.

For me the quickest set up is in the link I provided above which requires three clicks on the menu Getting Started->Firsts->First App on the Web. However for people who expect this page (or one like it) to be up and center from entering the docs I can see that they may then be lost.

As usual for most open source projects contributors generally want to improve the project itself rather than get involved with the docs.

Given that the docs are open source and some people are having difficulty with unclear and hidden sections about getting setup and want clear instructions on how to start I would ask those community members willing to do so to detail how this should be organised, what it should contain and maybe write the content and submit a PR.

I’m at the rookie end of both spectrums in dev and in Babylon, but one thing @labris touched on in the initial user-experience I think is momentum. Having recently learned Solidity purely from Youtube tutorials and the online Docs, it was super simple to follow Getting Started as well as Topic-specific videos that drilled down from the very basics of environment setup, step by step.

This is probably harder in Babylon where they may be many different kinds of setups, but if there’s one solid recipe to get started, from setting up VSCODE, through to the rest of it, I think that would really help. Maybe Youtube is particularly useful for this, and I’ve been following the official Babylon tutorials, though for a newcomer, I don’t know what env setup they have, and have even less understanding of why the same code on my machine, does not work per the tutorial/or as it does in Playground sometimes. That is unless I untangle a large number of forums/articles to orientate myself on what exactly is the problem, before then facing the challenge of rewriting the code.

I’m sure an experienced dev can make their way through it, but it has been really challenging so far. The help on this forum has been a huge respite, though it’s not an efficient way to seek answers/and orientate oneself.

Not sure of what the solutions are, but this just my feedback having dived in. I want to love this thing, but building momentum with it/the docs/tutorials in various Language (TS? JS?) or Modes (Playground/ Vscode) makes for very choppy ride — at least for a noob like me.

2 Likes

Would you be kind enough to explain with one specific example of what you were trying to achieve, what led you to being tangled, what the tangle was and which forum posts and articles helped you to become untagled?

This would help in looking at what is needed in the docs to help others in the future.

TLDR;
I only use Javascript, for my personal use all the bother of Typescript telling me my types don’t match and compiling and building is too much. My use of VSCode for Babylon.js is very straight forward but very naive ( and perhaps too naive for many users and the docs).

  1. Create folder for BabylonJS projects
  2. Create a project folder within BabylonJS for new project
  3. Copy HTML template from view-source:Babylon Template
  4. Create new HTML file in VSCode and paste copied template into project folder.
  5. Try out code in playground.
  6. Copy and paste the CreateScene function into my file to replace existing one
  7. Run Locally

You can miss out the playground step but I find it easier to edit in the playground until my code works then transfer to VSCode.

Without running a server on your local machine you will need to link to a Cors compliant site for your images, e.g. Imgur

You can build on this by, for example, using github within VSCode to keep versions of your project. You can then store images and models on your github repository and link to them using the raw.githubusercontent method.

If I want local versions of babylon.js or babylon.gui.js I just visit the relevant sites https://raw.githubusercontent.com/BabylonJS/Babylon.js/master/dist/babylon.js, https://raw.githubusercontent.com/BabylonJS/Babylon.js/master/dist/gui/babylon.gui.min.js select all and copy and then paste into my folder and create links to these rather than CDN.

This point is often missing since it seems that a lot of people just don’t know how to view source :frowning:
Would be much easier for them to have a big DOWNLOAD button with this code in zip.

1 Like

Something that might be considered.

What do @RaananW and @PirateJC think

People also do not know that they can download a playground into a zip file that gives a working local version

1 Like

Totally. We need to consider the fact that not all users know what npm or github for that matter. Downloading a working source code might be a good starting point. We will need to document that very well, also saying that this is the most basic way of using babylon, and that there are a lot of other and maybe better ways to consume the framework. @PirateJC , what do you think?

2 Likes

It doesn’t work atm but I hope it will be fixed soon - Fix PG download (#11826) · BabylonJS/Babylon.js@256b51e · GitHub

I believe you should take into account all users, and create a single git repo for starters, that is both average Joe and developer friendly:

  1. Average Joe - give him ready made zip download link on github page
  2. Developer - give him a working step by step instructions on how to install and start the app on all OS system (example)

Using Create React App is the simplest approach that lets users open index.html locally in their computer and it still works. Plus it’s a good starting point for devs to play with babylon locally.

1 Like

Downloadable start files of various descriptions is a good starting point although the issue of setup docs that started the topic remains.

Community help much appreciated.

1 Like

Use github starting templates as self documenting docs, led by example - you no longer have one setup doc, your main setup doc becomes a summary of different setup docs for different users.

All big software releases have this - different flavours for different users.

Links to a couple of examples please

Here it is

The same participant probably shouldn’t implement both three.js and babylon.js, since some experiences with the first one could be applied to the second. Not fair if all participants implementing three.js first. :smile:

2 Likes

Well, for the statistically significant ensemble there should be 9000 participants instead of just 9…
Anyway, all observations (especially unsuccessful ones) are really valuable input how “a user” feels. And, actually, they are confused.



Challenges present opportunity, this is like the early days of Bitcoin, I missed that boat by not being a programmer back then. I was sitting there and knew the wave was passing by me :). ten years forward, I’m here, ready to catch this 3D wave!

3 Likes

@labris : That table you posted made me smile

“Years of coding experience” - not alot. HTML and a javascript library from the internet for creating websites for artists to display their work, or festivals to display images of coming attractions.I had also created some VRML worlds with VRMLPad/Blender for the Cortona server. Created models for Second Life using a Blender add on. All self taught.

“Age” - er, um, old!

“Familiarity with Javascript” - hardly!

That was 8 years ago. I tried both babylon.js and three.js. With a basic template from the community forum, @Deltakosh’s blender exporter (before @JCPalmer arrived), I dropped three.js. Took me about a month to make that decision. Never looked back.

However, as I view the current forum, it seems to be more and more about coding and less about creating .babylon content. I look at some posts and have very little idea about what the conversation is all about.

Must say though that I do read and enjoy most of your posts and responses. They seem to get right down to the nitty-gritty of the questions asked.

Stay Safe All, gryff :slight_smile:

3 Likes