Babylon.js: README Instructions Not Functional

[gpresland]

Bugs

• Expected result:

Following the README should add access to various materials as explained at:
https://doc.babylonjs.com/extensions/grid#using-the-grid-material
and demoed at:
https://www.babylonjs-playground.com/#1UFGZH#12

• Current result:

Following the README does not work. BABYLON gives property errors. e.g.

Property 'GridMaterial' does not exist on type 'typeof import("babylonjs")'.ts(2339)

from

const groundMaterial = new BABYLON.GridMaterial("groundMaterial", this._scene);

This is occurring on a simple barebones app created with npx create-react-app my-app --typescript.

package.json

  "dependencies": {
    "@types/jest": "24.0.18",
    "@types/node": "12.7.4",
    "@types/react": "16.9.2",
    "@types/react-dom": "16.9.0",
    "babylonjs": "^4.0.3",
    "babylonjs-loaders": "^4.0.3",
    "babylonjs-materials": "^4.0.3",
    "react": "^16.9.0",
    "react-dom": "^16.9.0",
    "react-scripts": "3.1.1",
    "typescript": "3.6.2"
  },

tsconfig.json

{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react"
  },
  "include": [
    "src"
  ],
  "types": [
    "babylonjs",
    "babylonjs-materials",
  ]
}

Canvas.tsx contains the following at the top.
```tsx
import * as BABYLON from "babylonjs";
import "babylonjs-materials";
...

[deltakosh]

Hello please use forum for questions as stated in the issue template

[gpresland]

For anyone else who comes across this problem, the official documentation is incorrect and does not work. The solution is to do:

import * as BABYLON from "babylonjs";
import * as MATERIALS from "babylonjs-materials";

and use MATERIALS when you want access to the Babylon materials.

That said, there are various other bugs I've run in to where the current documentation and examples do not reflect the actual source code, resulting in TypeScript error where you cannot compile. My solution unfortunately has to be to stick with Three.js until these issues in Babylon and/or its documentation get resolved.

[deltakosh]

Well you really don't want to go to our forum :D
pinging @sebavan

Furthermore I don't see where you found that error in the doc. The doc you mentioned has nothing to do with importing modules. Did you read the ES6 documentation? https://doc.babylonjs.com/features/es6_support

You may have specifics that we don't know about as the vast majority of the people discussing on the forum has no issues with the doc.

Anyway, have fun. 3js is an excellent framework

[jaqmol]

Well you really don't want to go to our forum :D
pinging @sebavan

Furthermore I don't see where you found that error in the doc. The doc you mentioned has nothing to do with importing modules. Did you read the ES6 documentation? https://doc.babylonjs.com/features/es6_support

I just had the same problem. Typescript project won't compile. BabylonJS-Git-Repo won't import. Nothing mentioned about how to properly import extensions in the BabylonJS documentation. I wasted 2 hours trying to adjust my project and TS build system without success, until I stumbled over this post here mentioning "babylonjs-materials". If you have a place in your documentation or forum where this issue is discussed, why didn't you post a link here?

[deltakosh]

Maybe we could improve the es6 page? https://doc.babylonjs.com/features/es6_support

Would you suggest some edits?

[jaqmol]

Unfortunately I couldn't figure this out by myself. Claiming everyone else could find the ES6-page doesn't help much.

• Looking at https://doc.babylonjs.com/extensions/ I can't find a link to the ES6 page.
• This page doesn't help as well: https://doc.babylonjs.com/extensions/grid

So the questions from my side is: Which path actually leads to https://doc.babylonjs.com/features/es6_support? And is this path discoverable for people who have TypeScript-compiler-errors?

[deltakosh]

This is an excellent question. Honestly we need to work on it but also it is complicated as some stuff work for some people and not for others.

Adding @PirateJC as he is working on the doc reorg ;)

[sebavan]

@jaqmol could you share the code you tried and first doc page you looked at ?

I will add the relevant info to those docs.

Basically it should just work by default by importing from the materials-library from ts:

In ES5:

import { GridMaterial } from 'babylonjs-materials';

In ES6:

import { GridMaterial } from '@babylonjs/materials/grid/gridMaterial';

[jaqmol]

The documentation I found was not mentioning the "@babylon/..." packages at all for TypeScript. So I got stuck with "babylonjs" packages, which don't work with the materials. The documentation was so unclear, that I tried to link my project (via package.json) to a local copy of the whole BabylonJS project (from Githhub); which didn't work because the build-system is set up completely different. But none of that actually matters, I got it running in a minute or two after I got pointed to the ES6 page. I believe the issue here is discoverability of information.

The whole time I was never even getting the idea to look into the features section of the documentation for information about TypeScript project setup. It didn't occur to me. I would understand features in the field of graphics to be part of the features category of a framework like BabylonJS. I would not get the idea that TypeScript-support via the indirection of ES6 (which makes it even harder to discover) would be found under features. I was actually searching for a category that covers project setup or build systems (webpack, parcel, etc.) and couldn't find anything (build-systems are a big part of the JS ecosystem and a crucial part of every project setup nowadays). I guess at least mentioning more of that specifically in it's own category would help the documentation a lot. Maybe giving the ES6-page it's own category and adding the term "TypeScript" to the title already solves the problem. Plus linking to it from almost every page of the extensions category.

[jaqmol]

Concerning your own forum: Needing to sign up for one more thing on the internet, next to the other 10000 things gets tiring. I'm very happy you're not ignoring the issues here on Github. in general I find Babylon an excellent framework! Keep it up.

[deltakosh]

@jaqmol: Ok to do a pR to update the page?