
# 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 by - it's possible that you or your employer's subscription service has to the title for free as part of your subscription.

![book](/img/how_to/book/book.png)

## Officially Endorsed by the Babylon.js Team

With a forward by David Catuhe (not to mention cover art!) and extensive consultation with the Babylon.js team on both the book's technical content as well as 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, there is a lot of attention paid to helping familiarize readers with Bablyon.js and specific coding approaches.

As readers progress though, the pace quickens and the amount of detail changes 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 remove much of the underlying maths messiness, allowing you to put 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 best take advantage of the rich tooling, diverse resources, and incredibly well-documented that are parts 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 starting from first principles and ending with 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 the summer festivals and papern lantern lighting. The story is about this cat whose family works on crafting all 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 top mountain shrine. You have only 1 hour (4 minutes real-time) and 1 sparkler (20 second lifetime).

![illustration](/img/how_to/create-a-game/startscreen.png)

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 that this series inspires people to start using Babylon.js for their own game development or just start exploring the things you can do with Babylon.js!

![gameplay](/img/how_to/create-a-game/gameplay.gif)

## Summary
Starting with setting up a project locally, this series will walk you through how I went about creating this game, linking 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 of how I developed the game; however, I've done my best to break it down into sections that explain concepts and the overall methods of what 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 on 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 has been made for Blender as 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.jpg)
Model stairs in less than 40seconds: https://www.youtube.com/watch?v=J4T256mVkS0

## Material and textures
Create 2 materials: 1 for walls, 1 for ground.
![Material and textures](/img/how_to/lightmaps/lm2-0.jpg)
Select faces in edit mode, click apply button.
![Material and textures](/img/how_to/lightmaps/lm2-1.jpg)

## Lighting
Add sun light.
![Lighting](/img/how_to/lightmaps/lm3-0.jpg)
Add Area light that covers all scene.
![Lighting](/img/how_to/lightmaps/lm3-1.jpg)

## UV set
Select all faces in edit mode. Apply box UV projection.
![UV set](/img/how_to/lightmaps/lm4-0.jpg)
Go to UV edit mode. Scale UV up until pixel density is good.
![UV set](/img/how_to/lightmaps/lm4-1.jpg)

## 2nd UV set
Add new UV set and set it as active.
![2nd UV set](/img/how_to/lightmaps/lm5-0.jpg)
Select all faces and Lightmap Pack menu option.
![2nd UV set](/img/how_to/lightmaps/lm5-1.jpg)

## Preparing shading
Add 2 UV maps: First for Default UV set. Second for lightmap set.
![Preparing shading](/img/how_to/lightmaps/lm6-0.jpg)
![Preparing shading](/img/how_to/lightmaps/lm6-1.jpg)
Create new Lightmap image with appropriate size.
![Preparing shading](/img/how_to/lightmaps/lm6-2.jpg)

## Baking
With Cycles renderer: Diffuse lighting without color.
![Baking](/img/how_to/lightmaps/lm7-0.jpg)
Do not forget to save baked image Bake as lightmap.

## Test Playground
Export scene as glb and upload it so it's available online.
Make new playgound and copy paste code.
Apply lightmap to every meshes.
![Result](/img/how_to/lightmaps/lmResult.jpg)

<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.png)

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

[Vite](https://vitejs.dev/) is a modern development environment that bundles & optimizes your code, launches local test servers instantly, automates more project configurations out-of-the-box, and contains other quality-of-life improvements. In other words, it's an all-in-one tool that lets you develop Babylon.js projects on your computer locally and with ease. It's intended to replace Webpack, which has a similar goal as Vite 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 will be using [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.png)

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.png)

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.png)

**(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 of 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.png)

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.png)

*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 directly install them inside your project root directories. This is a good habit to get into instead of maintaining multiple copies of Vite and Babylon.js installed in every single project folder, resulting in wasted 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 updates the Vite packages in your project root folder that still need to be directly in there, and the second one 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.png)

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.png)

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.png)

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 between 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.png)

🎉 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.png)

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 holds a selection of experiments and partially finished projects. They put together several aspects of Babylon.js in one place with a description of their design and construction. Some could be developed into full applications but really they are just workshop ideas which 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 you want to add new pages or to run the documentation locally on your computer before pushing online, just to be sure nothing is broken then 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.
- IDE such as VSCode

You will need 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 at the location of 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 be done also from Github Desktop:

![visual studio](/img/contribute/documentation/further-visual-studio.png)

(_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.png)

### Adding new images

In case you have to create new illustrations, you need to send them on the Github repo into 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 says you just create a new page, linked on `https://doc.babylonjs.com/features/divingDeeper/my_very_great_page`.

Here, you can create a `my_very_great_page` folder into the `/img/features/divingDeeper/` one, 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 not must) 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 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 markdown extension .md):
![new content](/img/contribute/documentation/further-new-content.png)

#### Page metadata

Each page can (but not must) have a metadata section, that provides further information for this page. This is important if you want the page to be visible when being searched.
The metadata section is a 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.jpg
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 has a different value. However, it is always better to add as much information as possible. This will help people find and use the page. And this 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 in 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 in 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.png)
```

but you can also use the more advanced `<img/>` tag, that has 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) has to be made to integrate your modifications into the documentation.
You will first pull your local modifications into your online fork, then ask for merging 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 there's no problem to PR with it.
Add an explicit summary into the required field, and click to _Commit to master_:
![pushing](/img/contribute/documentation/further-pushing.png)
Then, click the _Push origin_ button:
![push](/img/contribute/documentation/further-push.png)
And go to your online Github repo. You can use Github Desktop for that:
![github](/img/contribute/documentation/further-github.png)
For now, your fork is updated online, having your last modifications.
Click the _New pull request_ button:
![github pull](/img/contribute/documentation/further-github-pull.png)
If no conflicts, you will be able to follow the same steps as we seen above in the [easy way](/contribute/contributeToDocs/easydoc) section.
Congratulation 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 tasks, a pull request can take into account 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 proof-reading

### 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 code block starting ticks to ensure syntax highlighting:
  ![markdown code](/img/contribute/documentation/markdown-code.png)
- 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.
