
# Journey Beyond the Docs

Sometimes all a person needs is to know the syntax for a particular component, a no-nonsense explanation of a specific topic. Other times, more context is needed to understand a concept. After all, an isolated code snippet does not an application make (unless it's running in the [Playground](https://playground.babylonjs.com) of course). For those who want or need more context, [there's a book for that](https://packt.link/Josh)!

_Going the Distance with Babylon.js_ is a book that bridges the gap between the practical, focused information in the BJS documentation and real-world application development incorporating those concepts.

By the way, it's possible that you or your employer already have access to the title for free as part of a subscription service.

![book](/img/how_to/book/book.webp)

## Officially Endorsed by the Babylon.js Team

With a foreword by David Catuhe (not to mention cover art!) and extensive consultation with the Babylon.js team on both the book's technical content and the overall content structure, _Going the Distance_ doesn't just regurgitate material available in the reference docs.

The book teaches you how to build [_Space-Truckers: The Video Game_](https://space-truckers.com) from start to finish. In the process, you'll learn about contributing to Open-Source projects, 3D graphics concepts, simple game AI, and more! Early in the book, a lot of attention is paid to helping readers become familiar with Babylon.js and specific coding approaches.

As readers progress, though, the pace quickens and the amount of detail shifts from explaining sections of code to explaining larger components and concepts. At every step of the way, however, there are numerous Playground snippets, links to external resources, and specific pointers to GitHub source code branches, ensuring that there's always a contextual, working sample of code for comparison.

## Creativity Unbound

Release any preconceptions you might be carrying about yourself, like "I'm not good at math, so I can't possibly understand 3D programming!" or "I don't know anything about graphics, this is impossible for me to learn!" None of that thinking will have any traction after you read this book, because you'll know first-hand how easy it can be to make what was previously a dream into reality.

The ecosystem of tools that Babylon.js provides removes much of the underlying mathematical complexity, allowing you to focus where it matters - on the content. Over the course of _Going the Distance_'s fourteen chapters, you'll be exposed to, and learn how to take advantage of, the rich tooling, diverse resources, and well-documented features that are part of Babylon.js.

Don't worry about getting overwhelmed, though! Each chapter focuses on a group of related features and functionality that are used to construct the next part of _Space-Truckers: The Video Game_. As you progress through the book, you'll also be building up the application from first principles until you have a full application that can be published to an app store.

What are you waiting for? [GO GET YOUR COPY!!!](https://www.amazon.com/Going-Distance-Babylon-js-maintainable-browser-based/dp/1801076588/ref=sr_1_1?keywords=going+the+distance+with+babylon+js&qid=1664490295&sprefix=going+the+dist%2Caps%2C141&sr=8-1)



## How To Create A Game

## Introduction

Hello everyone, this is capucat. I'm an intern on the team! My project for this summer was to develop a game using Babylon.js (4.1) and share my learnings through this tutorial.

The game I created is Hanabi, or Summer's Festival. It's a short 3D platformer based on summer festivals and paper lantern lighting. The story is about this cat whose family works on crafting all the lanterns and fireworks for the village. Every year there's a special summer festival where they have a firework show to start it off. The goal is to navigate through the village, lighting all of the lanterns before delivering the fireworks to the mountaintop shrine. You have only 1 hour (4 minutes in real time) and 1 sparkler (20-second lifetime).

![illustration](/img/how_to/create-a-game/startscreen.webp)

I was a complete beginner when it came to working with Babylon.js, so this was a great learning experience. I'm really excited to be sharing this process with everyone because the community makes a lot of amazing things. I hope this series inspires people to use Babylon.js for their own game development, or simply to explore what you can do with Babylon.js!

![gameplay](/img/how_to/create-a-game/gameplay.webp)

## Summary
Starting with setting up a project locally, this series walks you through how I went about creating this game and links all relevant files. This series isn't meant to be a guide to a perfect game, but rather a reflection of a learning process. Game development is meant to be an iterative process, so this series isn't a step-by-step guide to how I developed the game; however, I've done my best to break it down into sections that explain concepts and the overall methods that I found worked best.

It's important to note that this game only scratches the surface of what Babylon.js has to offer, so feel free to modify and experiment with different features!



## Dev Stories

Welcome to the Dev Stories! These are project-focused narrative retellings of how 
Babylon.js Team and Community members created various experiences. These stories
are specifically intended to "pave the golden path," quickly taking readers
through techniques and best practices that they can then reuse in their own
projects. In short, these stories are intended to serve as examples for readers
with a task in mind. We can't tell you _the_ way to do it, but if you want to 
know how _we'd_ do it, then you've come to the right place.



# Intro

The following steps will guide you through baking lightmaps for your test level with Blender.
Lightmaps can help you make unique levels by tweaking lighting and making it look good independently of the hardware.
This tutorial was made for Blender because it's easily available, but most steps can be adapted to Maya or 3DSMax.

## Modeling
Model the room using cubes.
Remove the roof.
![Modeling](/img/how_to/lightmaps/lm1-0.webp)
Model stairs in less than 40 seconds: https://www.youtube.com/watch?v=J4T256mVkS0

## Material and textures
Create 2 materials: 1 for walls and 1 for the ground.
![Material and textures](/img/how_to/lightmaps/lm2-0.webp)
Select the faces in edit mode, then click the Apply button.
![Material and textures](/img/how_to/lightmaps/lm2-1.webp)

## Lighting
Add sun light.
![Lighting](/img/how_to/lightmaps/lm3-0.webp)
Add an area light that covers the whole scene.
![Lighting](/img/how_to/lightmaps/lm3-1.webp)

## UV set
Select all faces in edit mode. Apply a box UV projection.
![UV set](/img/how_to/lightmaps/lm4-0.webp)
Go to UV edit mode. Scale the UVs up until the pixel density is good.
![UV set](/img/how_to/lightmaps/lm4-1.webp)

## 2nd UV set
Add a new UV set and set it as active.
![2nd UV set](/img/how_to/lightmaps/lm5-0.webp)
Select all faces and Lightmap Pack menu option.
![2nd UV set](/img/how_to/lightmaps/lm5-1.webp)

## Preparing shading
Add 2 UV maps: the first for the default UV set and the second for the lightmap set.
![Preparing shading](/img/how_to/lightmaps/lm6-0.webp)
![Preparing shading](/img/how_to/lightmaps/lm6-1.webp)
Create a new lightmap image with an appropriate size.
![Preparing shading](/img/how_to/lightmaps/lm6-2.webp)

## Baking
With Cycles renderer: Diffuse lighting without color.
![Baking](/img/how_to/lightmaps/lm7-0.webp)
Do not forget to save the baked image as a lightmap.

## Test Playground
Export the scene as a glb and upload it so it's available online.
Make a new Playground and copy-paste the code.
Apply the lightmap to every mesh.
![Result](/img/how_to/lightmaps/lmResult.webp)

<Playground id="#SSD1Q5#1" title="Scene with lightmap" description="Scene with lightmap"/>


## Networking

In this section, you can learn how to create networked Babylon.js experiences such as multiplayer games or remote multi-user interactions.



![Vite + Babylon.js Combo Logo](/img/how_to/using-vite/01.webp)

## What is Vite and why do you need it?

[Vite](https://vitejs.dev/) is a modern development environment that bundles and optimizes your code, launches local test servers instantly, automates more project configurations out of the box, and includes other quality-of-life improvements. In other words, it's an all-in-one tool that lets you develop Babylon.js projects locally on your computer with ease. It's intended to replace Webpack, which has a similar goal but requires more work and maintenance (especially with its config files).

Whether you're ready to graduate from playing with example projects in the [Playground](https://playground.babylonjs.com/), or if you're already a seasoned developer looking to upgrade your software stack, this guide can benefit any of your future Babylon.js projects!

## Leaving the Playground with VSCode & npm

***You can skip to Step 3 if you already have a code editor and npm installed.*** Otherwise, it's time to finally leave the Playground and learn how to create Babylon.js projects that you can publish and share anywhere. This is usually done with a code editor, a program that helps you write and manage your projects.

**(1)** Install a code editor. This tutorial uses [Visual Studio Code](https://code.visualstudio.com/) *(or [VSCodium](https://vscodium.com/))* but you can still follow along if you want to use a different one.

![VSC](/img/how_to/using-vite/02.webp)

Your code editor may look something like this when opened.

**(2)** Close your code editor and install Node.js with [one of these installers](https://nodejs.dev/en/download/) (or via your package manager if you use Linux.) Installing this gives us access to [npm](https://www.npmjs.com/), a library of Node.js packages to help you build web-based apps and keep them up-to-date. This is how we're going to install Babylon.js and Vite.

![npm test](/img/how_to/using-vite/03.webp)

You'll know if you did it right by opening Command Prompt on Windows (or Terminal on macOS/Linux) and writing `npm -v`. If the output is a version number, you're good to go.

## Setting up Vite & Babylon.js

Once you have your code editor and Node.js installed, we can begin setting up your development folder.

**(3)** Create a folder on your computer wherever you want to store your Babylon.js projects, and open it in your code editor using the menu `File` > `Open Folder`. If prompted, click on "Yes, I trust the authors." You should now have a sidebar on your left like this:

![npm test](/img/how_to/using-vite/04.webp)

**(4)** Toggle the terminal using the menu `View` > `Terminal` and enter the following commands one after the other:

- `npm i vite` *(`i` is short for `install`)*
- `npm i -D @babylonjs/core`  *(`-D` is short for `--save-dev`)*
- `npm i -D @babylonjs/inspector`

This installs Vite and some Babylon.js features in your created folder (in a subdirectory called `node_modules`).

**(5)** Now enter the command `npm init vite`. Enter the name of your Babylon.js project, such as `testProj` or whatever name you want. You can also set a package name, but the default one works fine. Choose "Vanilla" from the list that pops up, and then choose "TypeScript." (This setup also works with JavaScript, but with slightly different steps not documented here.)

![folder structure with vanilla Vite](/img/how_to/using-vite/05.webp)

Look at that! We have a new folder containing a Vite template project. You can rename the folder if you want.

## Configuring a test project

Now let's turn our vanilla Vite folder into an example Babylon.js project that you can use as a foundation for your future Vite & Babylon.js projects.

**(6)** Right-click your new folder in the left-hand side and choose `Open in Integrated Terminal`. A second tab in your terminal will open, which is pointing to your newly-generated project folder.

![new tab](/img/how_to/using-vite/06.webp)

*Note to advanced users: The reason why we didn't just `cd` into the new folder is because it's convenient to have both the root and project folders open as separate tabs in our Terminal. Doing this lets us maintain our packages in the root folder separately from the project subfolder. We can install our necessary packages once in the root folder and reference them freely in the code inside our project subfolders. NPM is smart enough to detect any packages installed in parent folders - you don't have to install them directly inside your project root directories. This is a good habit to get into instead of maintaining multiple copies of Vite and Babylon.js in every single project folder, which wastes storage space. Feel free to deviate from this structure if you'd like, though.*

**(7)** Now enter the following commands in the terminal:

- `npm i`
- `npm run dev`

The first command installs the Vite packages that still need to be in your project root folder, and the second tells Vite to run a server that tests your current code.

**(8)** Your terminal should now say that Vite is currently running. Ctrl+click on the localhost: URL to view your test server inside your browser.

![Vite success](/img/how_to/using-vite/07.webp)

If you see this screen, good job! The foundation of our Vite project is set up. Now let's make it run Babylon.js.

**(9)** Go back to your Terminal and press Ctrl+C to stop the server. (Don't forget that keyboard shortcut.) 

Now use the left-hand sidebar (and some right-clicking) to do the following:

- Delete everything inside the `public` and `src` folders
- Create a new file inside `src` called `app.ts`
- Double-click on `index.html` and `tsconfig.json`

![file tabs](/img/how_to/using-vite/08.webp)

You should now have all three of these files open.

**(10)** Copy the contents of the three code blocks below and paste them into their respective files. Save each file (Ctrl+S) after you do this.

![Picture of a file](/img/how_to/using-vite/09.webp)

This code for **app.ts** is a test scene of a sphere from [another Babylon.js tutorial](https://doc.babylonjs.com/guidedLearning/createAGame/gettingSetUp). Notice how the `import` statements at the top allow the rest of the code to function: 

```typescript
import "@babylonjs/core/Debug/debugLayer";
import "@babylonjs/inspector";
import { Engine, Scene, ArcRotateCamera, Vector3, HemisphericLight, Mesh, MeshBuilder } from "@babylonjs/core";

class App {
    constructor() {
        // create the canvas html element and attach it to the webpage
        var canvas = document.createElement("canvas");
        canvas.style.width = "100%";
        canvas.style.height = "100%";
        canvas.id = "gameCanvas";
        document.body.appendChild(canvas);

        // initialize babylon scene and engine
        var engine = new Engine(canvas, true);
        var scene = new Scene(engine);

        var camera: ArcRotateCamera = new ArcRotateCamera("Camera", Math.PI / 2, Math.PI / 2, 2, Vector3.Zero(), scene);
        camera.attachControl(canvas, true);
        var light1: HemisphericLight = new HemisphericLight("light1", new Vector3(1, 1, 0), scene);
        var sphere: Mesh = MeshBuilder.CreateSphere("sphere", { diameter: 1 }, scene);

        // hide/show the Inspector
        window.addEventListener("keydown", (ev) => {
            // Shift+Ctrl+Alt+I
            if (ev.shiftKey && ev.ctrlKey && ev.altKey && ev.keyCode === 73) {
                if (scene.debugLayer.isVisible()) {
                    scene.debugLayer.hide();
                } else {
                    scene.debugLayer.show();
                }
            }
        });

        // run the main render loop
        engine.runRenderLoop(() => {
            scene.render();
        });
    }
}
new App();
```

This code for **index.html** contains the title that will appear in the browser title bar, as well as a `<script>` tag to tell Vite which file has the main code to start our project, which is `app.ts` in our case:

```html
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>Title of Your Project</title>
    </head>
    <body>
       <script type="module" src="./src/app.ts"></script>
    </body>
</html>
```

This code for **tsconfig.json** is a slimmed-down combination of the default Vite file and the one from that other Babylon.js tutorial mentioned earlier. Each line roughly explains what each setting does. (Note that JSON files normally don't allow you to insert comments like this example here, but tsconfig.json in particular does.) You can read the [TypeScript docs](https://www.typescriptlang.org/tsconfig) if you want to learn more:

```json
{
  "compilerOptions": {
    "target": "es6", // choose our ECMA/JavaScript version (all modern browsers support ES6 so it's your best bet)
    "lib": [ // choose our default ECMA/libraries to import
      "dom", // mandatory for all browser-based apps
      "es6" // mandatory for targeting ES6
    ],
    "useDefineForClassFields": true, // enable latest ECMA runtime behavior with older ECMA/JavaScript versions (delete this line if target: "ESNext" or "ES2022"+)
    "module": "ESNext", // use the latest ECMA/JavaScript syntax for our import statements and such
    "moduleResolution": "node", // ensures we are using CommonJS for our npm packages
    "noResolve": false, // disable TypeScript from automatically detecting/adding files based on import statements and etc (it's less helpful than you think)
    "isolatedModules": true, // allows our code to be processed by other transpilers, such as preventing non-module TS files (you could delete this since we're only using base TypeScript)
    "removeComments": true, // remove comments from our outputted code to save on space (look into terser if you want to protect the outputted JS even more)
    "esModuleInterop": true, // treats non-ES6 modules separately from ES6 modules (helpful if module: "ESNext")
    "noImplicitAny": false, // usually prevents code from using "any" type fallbacks to prevent untraceable JS errors, but we'll need this disabled for our example code
    "noUnusedLocals": false, // usually raises an error for any unused local variables, but we'll need this disabled for our example code
    "noUnusedParameters": true, // raises an error for unused parameters
    "noImplicitReturns": true, // raises an error for functions that return nothing
    "skipLibCheck": true // skip type-checking of .d.ts files (it speeds up transpiling)
  },
  "include": ["src"] // specify location(s) of .ts files
}
```

**(11)** Run `npm run dev` in your terminal and Ctrl+click the localhost: link again.

![Babylon & Vite ready](/img/how_to/using-vite/10.webp)

🎉 YOU DID IT!! You just successfully created a local development environment for Babylon.js using Vite!

## Maintenance and updates

**HOWEVER,** before you continue your Babylon.js journey with your shiny new setup, here's some basic upkeep you'll have to keep in mind:

- You should occasionally run `npm up` *(short for `update`)* in the first terminal tab, which is the one for the main folder above your projects. This keeps Vite and Babylon.js updated.
- If you need to uninstall a package from Step 4 or otherwise, run `npm un <packageNameHere>` *(short for `uninstall`)* in that same main folder or terminal tab.
- Static assets such as images or 3D models should go in the `public` folder. These can then be referenced as if they're in the root folder `"./likethis.png"`.
- If you ever get stuck, reach out to [the Babylon forums](https://forum.babylonjs.com/) for help.

And that's it - you can go code now!

## Building and sharing online

...But let's say you finished making a project and you want to share it with the rest of the world. It's time to take advantage of Vite's bundling abilities and export your code into lightweight JS for the web!

Here's how:

- Make sure all your non-code assets (images, 3D models, etc.) are in the `public` folder to ensure that they end up in the final bundle.
- If it's not already open as a tab, right-click on your project's folder (not the main one) and choose `Open in Integrated Terminal`. Or just click on your second Terminal tab if you still have it.
- Run this command: `npm run build`
- Your exported code bundle is now in a folder called `dist`. Check if it works by running: `npm run preview`
- **IMPORTANT:** Once you verify this test works, open `dist/index.html` and look for any file paths that point to root with `/`. Add a period in front of all of those root paths (meaning `/assets` would become `./assets`) and save the file. For a more permanent solution, you can modify the package.json file in your project directory. Change the line: "build": "tsc && vite build" to: "build": "tsc && vite build --base=./". This will ensure that the base path is correctly set during the build process, eliminating the need to manually edit file paths in dist/index.html after each build.

![Final dist folder](/img/how_to/using-vite/11.webp)

NOW you can upload the contents of your `dist` folder to a host like GitHub Pages or Vercel to share it with the world! It'll run way faster than a project from the Playground since the code bundle only includes the parts of Babylon.js that you need, instead of the entire engine.

*Note to advanced users: if you really want to push the limits of Vite and its bundling capabilities, you can look into using Dynamic `import` Statements. This feature allows you to put import statements inside functions instead of at the top of your code, which helps reduce the overall size of your exported bundle via code-splitting. I haven't tried this feature myself, but [this overview video](https://www.youtube.com/watch?v=kwUfeWe7DCw) from Beyond Fireship is a great place to start exploring this workflow if you're interested.*

*Note to existing Vite users: you might've noticed that I instructed users to put all static assets in the `public` folder, instead of using URL-holding variables that come from having every asset as an `import` statement, as specified in [the Vite documentation](https://vitejs.dev/guide/assets.html#importing-asset-as-url). This is because we don't really have to do this when Babylon.js projects contain heavy assets like 3D models by default. The obscured filenames that result from using the Vite docs' method don't really prevent the end user from ripping assets from Babylon.js projects either. If you still want to use this "Importing Assets as URLs" workflow anyway, do note that you'll have to create a `.d.ts` file in your `src` folder and figure out [this code snippet](https://stackoverflow.com/questions/51100401/typescript-image-import#answer-51163365) to get it to work with TypeScript. As you can probably tell, I also haven't tested this method.*

## Credits

This tutorial was originally a [forum post](https://forum.babylonjs.com/t/how-to-vite-with-babylon-js-game-tutorial-series/33845) I wrote to replace Webpack in capucat's [Create A Game Tutorial Series](https://doc.babylonjs.com/guidedLearning/createAGame), but I was told to turn it into an article for the docs, so here we are. Thank you PirateJC for requesting this write-up! I think it turned out great.

***Written by [wavetro](https://wavetro.net/)***

*Last updated: 2022-SEP-22*



Do you learn best by watching someone else teach you or guide you? This is the place for you. In this section of the docs, you'll find a host of different video tutorials and guides that teach you everything from how to load a mesh, to how to create advanced shaders. We sincerely hope these videos are helpful. Is there a video that isn't here that you'd like to see? Hop on over to our forum to suggest new ones! [Babylon.js Forum](https://forum.babylonjs.com/)


The workshop contains a selection of experiments and partially finished projects. These bring together several aspects of Babylon.js in one place, along with a description of their design and construction. Some could be developed into full applications, but really they are just workshop ideas that expand on the examples in the documentation.


A selection of tutorials on games and applications that describe how they are achieved.


## Major Changes

When a simple page edit is not enough—for example, when you want to add new pages or run the documentation locally on your computer before pushing online to be sure nothing is broken—there are a number of steps to complete.

Requirements:

- [GitHub](https://github.com) account
- [git](https://www.git-scm.com/downloads)
- [GitHub Desktop](https://desktop.github.com/) (optional, but makes local git repositories easier to use)
- [node.js](https://nodejs.org/en/), we support node 16 and up.
- An IDE such as VSCode

You will need to know how to fork the [Documentation](https://github.com/BabylonJS/Documentation) repository and clone it onto your local system.

### Running and editing the doc locally

Using a CLI in your local Documentation folder, run:

`npm install`

This will install the dependencies needed for the project. You can now run:

`npm run dev`

This will launch the dev server on http://localhost:3000

Open the project using your favorite code editor. This can also be done from GitHub Desktop:

![visual studio](/img/contribute/documentation/further-visual-studio.webp)

(_you may have_ Open in Atom _rather than_ Open in Visual Studio _, that's not a big deal_)

You can finally start to update the markdown files!

![visual studio](/img/contribute/documentation/further-editing.webp)

### Adding new images

If you need to create new illustrations, you should add them to the GitHub repo in a specific folder: [`Documentation/public/img/`](https://github.com/BabylonJS/Documentation/tree/master/public/img).

So on your local fork, go to this `img` folder. You can see there are already a lot of folders, so try to use existing folders to put your new images if possible.

Let's say you just created a new page, linked at `https://doc.babylonjs.com/features/divingDeeper/my_very_great_page`.

Here, you can create a `my_very_great_page` folder inside `/img/features/divingDeeper/` and put `my-wonderful-image.jpg` into it.

Then, on your markdown page, use this link pattern:

```markdown
![quick description (for accessibility)](/img/features/divingDeeper/my_very_great_page/my-wonderful-image.jpg)
```

Of course, try to keep the image size as small as you can (while keeping a good visual quality). Our build system will do its best to optimize the image nonetheless.

### Adding new pages

#### Page structure

Now that everything is working well, you may want to add new content. To do so, please open `/configuration/structure.json`.

This file is a catalog where you can reference new files added to the repo.

The file is a tree of documents, starting from the root page and going to the different sections. Each page can, but does not have to, have its own children.

For example, let's say we want to add this page. We know that our new page will be in the _Diving Deeper/Audio_ section:

```javascript
{
    "friendlyName": "Home Page",
    "content": "landing_pages/home",
    "children": {
    /* [...] */
    "divingDeeper": {
            "friendlyName": "Diving Deeper",
            "children": {
              /* [...] */
              "audio": {
                    "friendlyName": "Audio",
                    "children": {
                        "playingSoundsMusic": { "friendlyName": "Playing Sounds and Music", "children": {}, "content": "How_To/audio/Playing_sounds_and_music" },
                        // This is the place you will add your document
                    },
                    "content": "landing_pages/features/divingDeeperAudioLandingPage"
                },
            }
    }
    /* [...] */
}
```

Just add the necessary information about your new page:

```javascript
/* [...] */
"documentKeyAndUrl": {
  "friendlyName": "A friendly title to your document",
  "children": {/* if any, children will contain the rest of the documents */},
  "content": "the markdown file that correlates to this document."
},
/* [...] */
```

Notice the object's key. This will be your new page filename (without the `.md` extension):
![new content](/img/contribute/documentation/further-new-content.webp)

#### Page metadata

Each page can, but does not have to, have a metadata section that provides further information for the page. This is important if you want the page to be visible in search results.
The metadata section is YAML added to the top of the page:

```yaml
---
title: Page title, if you want to override the title from the structure file
image: A link to an image that will be used as this page's image
description: A short description for this page
keywords: comma-separated keywords for this page.
further-reading: A list of links to add at the end of this page. Can be internal or external links
video-overview: A youtube video id to show at the beginning of this page
video-content: a list of videos (youtube or files) to show at the end of the page.
---
```

For example, this is a part of the metadata in the node_material page:

```yaml
---
title: Node Material
image: /img/pageImages/nodeMaterial.webp
description: The Node Material is a simple, highly customizable material that you can build yourself piece by piece. Combined with the powerful node-based editor, you can easily create stunning custom GPU shaders and FX for your Babylon.js scenes.
keywords: shaders, glsl, node editor, graphics, GPU program, material, NME, Node Material, Node Material Editor
further-reading:
  - title: Dedicated NME Forum Examples
    url: https://forum.babylonjs.com/t/node-materials-examples/6048
  - title: 3 Tips For Getting Started Building Procedural Node Material Shaders
    url: https://babylonjs.medium.com/procedural-node-material-shaders-3-tips-for-getting-started-4089c1832dfc
  - title: Mesh shattering with baked physics
    url: https://babylonjs.medium.com/mesh-shattering-with-baked-physics-5b3f8f381743
  - title: Fighting Self-Doubt, with Water
video-content:
  - title: Node-Based Procedural Textures
    url: https://youtu.be/qqMuuSM7GvI
  - title: Creating Procedural Node Materials Through Code
    url: https://youtu.be/GrmVObi6caQ
  - title: Node Material Post Processes
    url: https://youtu.be/QTuL5raapQQ
  - title: Node Material Editor Particles!!!!
    url: https://youtu.be/fZvZMXDoVp4
  - title: Interactive Hex Tile Series
    url: https://www.youtube.com/playlist?list=PLsaE__vWcRamMC5oJwhrSj3x3jT9TWOPB
  - title: Unraveling Advanced Anisotropic Reflections
---
```

Everything in the metadata is optional and serves a different purpose. However, it is always better to add as much information as possible. This will help people find and use the page, and that is the goal here.
The image provided will be used when sharing this link on sites supporting open graph, such as Facebook, Medium, Twitter, and so on. The default image is the Babylon.js logo.

#### Internal links

To link to an internal document, use its path from the root without adding the domain. For example:

```markdown
[Post Processes](/features/featuresDeepDive/postProcesses/usePostProcesses)
```

### Adding examples

It is always great to provide examples on your documentation page. By using the correct Markdown, you can add playgrounds and NME, and they will be added automatically to the page's side menu.
To add a playground, add the following code:

```html
<Playground id="playgroundId" title="Playground title" description="A short description" image="Optional image url" />
```

The playground ID is the 6-character id, and the version number if needed. For example: `#Y642I8#2`.
The same applies to NME examples:

```html
<nme id="nmeId" title="NME title" description="A short description" />
```

This can be either inline or on a new line and will automatically add the external and example link.
An image will be generated for each playground without an image, so don't worry about screen-capturing your playground. Please commit those images along with your document!

### Adding media (videos and images)

To add a YouTube link, use the YouTube markdown tag:

```html
<Youtube id="qqMuuSM7GvI" />
```

To add an image, you can use the markdown annotation:

```markdown
![Particle choice](/img/how_to/Materials/particleMenu.webp)
```

but you can also use the more advanced `<img/>` tag, which gives you more control over formatting, size, and so on. As always, everything is optional, but very nice to have:

```html
<img src="internal link to image" title="Image title" alt="Similar to title" width="300" height="200" caption="Copyright (or any other) caption that will appear under the image" />
```

### Sending pull request

A Pull Request (PR) must be made to integrate your modifications into the documentation.
You will first pull your local modifications into your online fork, then ask to merge your fork into the main repo.
In GitHub Desktop, you will see all of your modifications. Sometimes a file named `babylon.d.ts` will automatically be modified, but it is okay to include it in the PR.
Add an explicit summary into the required field, and click to _Commit to master_:
![pushing](/img/contribute/documentation/further-pushing.webp)
Then, click the _Push origin_ button:
![push](/img/contribute/documentation/further-push.webp)
Then go to your online GitHub repo. You can use GitHub Desktop for that:
![github](/img/contribute/documentation/further-github.webp)
At this point, your fork is updated online with your latest modifications.
Click the _New pull request_ button:
![github pull](/img/contribute/documentation/further-github-pull.webp)
If there are no conflicts, you will be able to follow the same steps as we saw above in the [easy way](/contribute/contributeToDocs/easydoc) section.
Congratulations again, you're now a documentation master!

## Good Practices

### General

- if you're not familiar with Markdown, you can read this short [GitHub guide](https://guides.github.com/features/mastering-markdown/)
- even if you're seeing just a tiny typo, feel free to do a pull request dedicated to it
- do one commit per task; a pull request can include multiple commits if needed
  - example: if you have two pages to modify, once the first page is edited, do a commit
- tables can be a great help for readability
- avoid the use of first person
- pay attention to spelling, grammar, and punctuation
- when you're not sure about a point, ask for proofreading

### Images

- use and store images from the documentation FTP as much as possible; read [Adding new images](/contribute/contributeToDocs/addToDocs#adding-new-images)
- be careful about image size (tip: Photoshop has a "Save for the web" export)

### Code

- when showing a block of JavaScript or TypeScript, include the language name after the opening code block backticks to ensure syntax highlighting:
  ![markdown code](/img/contribute/documentation/markdown-code.webp)
- JavaScript and TypeScript fences that use the `BABYLON` namespace are automatically displayed with **ES6**, **ES6 pure** (when supported), and **UMD** tabs. Keep only the UMD form in the Markdown so the variants cannot drift apart.
- Pure imports do not register engine extensions, loaders, serializers, or prototype augmentations automatically. Examples can assume application-level setup, but pages that teach setup should show the relevant explicit registration.
- Add `no-code-variants` after the fence language only when the snippet uses a community extension, removed API, or illustrative placeholder that has no ES module equivalent:

  ````markdown
  ```javascript no-code-variants
  const terrain = new BABYLON.DynamicTerrain(...);
  ```
  ````
- when quoting a property in a sentence, you can use single _\`_ char (<kbd>Alt</kbd> + numpad <kbd>96</kbd>)
  - example: You can set the `roughness` of a PBR material to 1.

### Links

For links to other parts of the Babylon.js documentation and API, use relative links.
For example, use `[Load Files with Assets Manager](/contribute/contributeToDocs)` rather than `[Load Files with Assets Manager](https://doc.babylonjs.com/contribute/contributeToDocs)`

## Further Reading

Any articles, URLs, documents, and links that you'd like the reader to have as a reference on the page should go into the "further reading" metadata section at the top of the page. See [Page Metadata](#page-metadata) for more detail.


Guided Learning

Coming next

Dev Stories

Dev Stories are project-focused narratives showing how Babylon.js experiences were made.

Journey Beyond The Docs

Dive into the Babylon.js Book "Going this Distance with Babylon.js"

Introduction To Creating Games

Dive into some deeper game creation methods and techniques.

Using Vite with Babylon.js

Graduate from the Playground and easily export projects into lightweight, web-optimized code.

Level prototyping using baked lightmaps

Bake lightmaps and use them for a level test playground

Networking

Learn how you can make a networked experience with Babylon.js.

Videos

Early videos from the start of Babylon.js

Workshops

A selection of experiments and partially finished projects

Offsite Tutorials

List of helpful offsite tutorials about Babylon.js.