
If you want to contribute to babylon.js (What an _excellent_ idea!), you should attempt to align your code with the following naming conventions:

- Private variables are named starting with \_ : `_myVariable`
- Camel casing is used for non static properties/functions/variables: `var myUberUsefulVariable`
- Pascal casing must be used for "static" functions: `BABYLON.Vector3.Project`
- Braces ({}) must be used for every block, even when there is only one line:

```
if (condition) {
    this.doSomething();
}
```

- Braces start on the same line and end on the next one
- Each new file must contain only one class

You have to use **TypeScript** to submit a pull request.

Please, do not forget to update the [documentation](https://github.com/BabylonJS/Documentation).



## Need for Contribution

Many people have asked for the API documentation to be improved. This is a major task with lots of files needing comments added. Comments are very useful for future development and maintenance of the code but now they are even more useful since in the correct format they are can be read by “TYPEDOC” and produce the API documentation for the classes, properties and methods used by Babylon.js. The core team has worked to make this happen as you can see by the new API documentation. Volunteers are needed to add comments so even if you only have time to do a couple of files then please do volunteer.

## How to Contribute

You need to add appropriate comments according to the formats given below. Check the comments for errors and submit a PR when everything is validated.

1. Fork and clone [Babylon.js](https://github.com/BabylonJS/Babylon.js) from github;
2. In the folder **Tools/Gulp** install npm with `npm install` and then gulp with `npm install -g gulp@4.0.0`;
3. Edit files from within the **src** folder by adding comments;
4. Execute `gulp typedoc-check` to validate the comments;
5. Do NOT COMMIT any changes to the file **babylon.d.ts**. Use `discard` to remove changes;
6. When validated submit a PR.

Whilst the above steps will validate the comments it will not allow you to see the results. Since you do not want to affect anything within your local clone of Babylon.js you will need to create a new folder **outside** the Babylon.js folder. You can then follow these steps to produce viewable results of your comments.

After editing and validating files within the **src** folder and before the PR:

7. In the new folder install typedoc using `$ npm install typedoc`;
8. Copy the **src** folder into the new folder;
9. Copy the **tsconfig.json** file from the **src** folder into the new folder;
10. Create a folder called documents in the new folder;
11. In the new folder use `$ typedoc --out documents src` to create the documents from the src
12. In the **documents** folder find and open index.html to check results. Note that these will not appear exactly the same as the Babylon.js API documentation web pages but close enough to check.

## Format of Comments

Below are descriptions of the format of comment for the various code entities with examples.

Comments go immediately in front of the entity and have the form of plain comments

```
/**
* comment
* more comments
*/
```

or comments plus key @words

| @word    | followed by                                                   |
| -------- | ------------------------------------------------------------- |
| @param   | parameter name then parameter description                     |
| @returns | description of what a function returns                        |
| @see     | URL when it is useful to link to another site or page add one |
| @ignore  | reason why it is ignored                                      |

## Enum

**Defines a set of named constants**

Plain comments to describe the purpose of the ENUM and the constants it defines

```javascript
/**
* Defines the list of states available for a task inside an AssetsManager
*/
export enum AssetTaskState {
    /**
     * Initialization
     */
    INIT,
    /**
     * Running
     */
    RUNNING,
    /**
     * Done
     */
    DONE,
    /**
     * Error
     */
    ERROR
}
```

```javascript
/**
* Specifies the level of max blur that should be applied when using the depth of field effect
*/
export enum DepthOfFieldEffectBlurLevel {
    /**
     * Subtle blur
     */
    Low,
    /**
     * Medium blur
     */
    Medium,
    /**
     * Large blur
     */
    High
};
```

## Class

**Template containing the constructor along with the public, private and protected properties and methods defining an object**

A defines comment to describe the purpose of the CLASS

```javascript
/**
 * Defines a HemisphericLight object that simulates the ambient environment light
 * so the passed direction is the light reflection direction, not the incoming direction
 */
export class HemisphericLight extends Light {
  //All the parts defining the class in here
}
```

```javascript
/**
 * Define an abstract asset task used with a {BABYLON.AssetsManager} class to load assets into a scene
 */
 export abstract class AbstractAssetTask {
     //All the parts defining the class in here
}
```

## Constructor

**This creates an instance of the class**

# No Parameters

A creates comment to describe the CONSTRUCTOR

```javascript
export class MapperManager {
  //class properties

  /**
   * Creates a new MapperManager object to manage the different implemented mappers
   */
  constructor() {
    this._mappers = {
      html: new HTMLMapper(),
      json: new JSONMapper(),
      dom: new DOMMapper()
    };
  }
}
```

## With Parameters

A creates comment to describe the CONSTRUCTOR and use @param for each parameter. The first item after @param must be the parameter name then a further comment. In addition should any members of the constructor be declared as public the comment should be repeated before the member in the parameters list.

### No Public Parameters

Create and @param comments for constructor.

```javascript
/**
 * Create a new Model loader
 * @param _viewer the viewer using this model loader
 */
constructor(private _viewer: AbstractViewer) {
    this._loaders = [];
    this._loadId = 0;
}
```

```javascript
/**
 * Creates a Solid Particle object
 * Don't create particles manually, use instead the Solid Particle System internal tools like _addParticle()
 * @param particleIndex is the particle index in the Solid Particle System pool. It's also the particle identifier
 * @param positionIndex is the starting index of the particle vertices in the SPS "positions" array
 * @param indiceIndex is the starting index of the particle indices in the SPS "indices" array
 * @param model is a reference to the model shape on what the particle is designed.
 * @param shapeId is the model shape identifier in the SPS
 * @param idxInShape is the index of the particle in the current model (ex: the 10th box of addShape(box, 30))
 * @param modelBoundingInfo is the reference to the model BoundingInfo used for intersection computations
 */
constructor(particleIndex: number, positionIndex: number, indiceIndex: number, model: Nullable<ModelShape>, shapeId: number, idxInShape: number, sps: SolidParticleSystem, modelBoundingInfo: Nullable<BoundingInfo> = null) {
    this.idx = particleIndex;
    this._pos = positionIndex;
    this._ind = indiceIndex;
    this._model = <ModelShape>model;
    this.shapeId = shapeId;
    this.idxInShape = idxInShape;
    this._sps = sps;
    if (modelBoundingInfo) {
        this._modelBoundingInfo = modelBoundingInfo;
        this._boundingInfo = new BoundingInfo(modelBoundingInfo.minimum, modelBoundingInfo.maximum);
    }
}
```

### With Public Parameters

Create and @param comments for constructor and copied comments before any public parameter in list

```javascript
/**
 * Creates a new Action
 * @param triggerOptions the trigger, with or without parameters, for the action
 * @param condition an optional determinant of action
 */
constructor(

    /**
     * The trigger, with or without parameters, for the action
     */
    public triggerOptions: any,

    condition?: Condition) {

    if (triggerOptions.parameter) {
                this.trigger = triggerOptions.trigger;
                this._triggerParameter = triggerOptions.parameter;
            } else {
                this.trigger = triggerOptions;
            }

            this._nextActiveAction = this;
            this._condition = condition;
}
```

```javascript
/**
 * Creates a new instance ConeParticleEmitter
 * @param radius the radius of the emission cone (1 by default)
 * @param angles the cone base angle (PI by default)
 * @param directionRandomizer defines how much to randomize the particle direction [0-1]
 */
constructor(
    radius = 1,
    /**
     * The cone base angle (PI by default)
     */
    public angle = Math.PI,

    /**
     * Defines how much to randomize the particle direction [0-1]
     */
    public directionRandomizer = 0) {

    this.radius = radius;
}
```

## Property of Class, Constructor, Function

### Public with public variable

Plain comments to describe the PROPERTY

```javascript
/**
 * The groundColor is the light in the opposite direction to the one specified during creation
 * You can think of the diffuse and specular light as coming from the centre of the object in the given direction and the groundColor light in the opposite direction
 */
public groundColor = new Color3(0.0, 0.0, 0.0);

/**
 * The light reflection direction, not the incoming direction
 */
public direction: Vector3

```

### Public with private variable

There are occasions when a variable should be public for the use of the code but private from a user. Such variables start with an underscore. Plain comments are useful for development but the variable should be ignored when building the API documentation. Hence the use of @ignore

```javascript
/**
 * Internal only - manager for action
 * @ignore
 */
public _actionManager: ActionManager;
```

### Private or Protected

These will be ignored automatically when building the API documentation and comments are optional.

```javascript
private _worldMatrix: Matrix;

protected _background: string;
```

## Method of Class, Constructor or Function

### Public with public name

### No Parameters

#### No Return Value

Plain comments to describe the FUNCTION

```javascript
/**
 * Clears the texture
 */
public clear(): void {
    var size = this.getSize();
    this._context.fillRect(0, 0, size.width, size.height);
}
```

```javascript
/**
 * Skips to next active action
 */
public skipToNextActiveAction(): void {
    if (this._nextActiveAction._child) {

if (!this._nextActiveAction._child._actionManager) {
    this._nextActiveAction._child._actionManager = this._actionManager;
}

this._nextActiveAction = this._nextActiveAction._child;
    } else {
this._nextActiveAction = this;
    }
}
```

```javascript
/**
 * Observable called when all tasks are processed
 */
public onTaskSuccessObservable = new Observable<AbstractAssetTask>();
```

#### With Return Value

Comments to describe the FUNCTION and use @returns

```javascript
/**
 * Gets the context of the canvas used by the texture
 * @returns the canvas context of the dynamic texture
 */
public getContext(): CanvasRenderingContext2D {
    return this._context;
}
```

```javascript
 /**
 * Serializes the current light into a Serialization object
 * @returns the serialized object
 */
public serialize(): any {
    var serializationObject = SerializationHelper.Serialize(this);

    // Internal working here

    return serializationObject;
}
```

```javascript
/**
 * @returns the current error object (if task is in error)
 */
public get errorObject(): { message?: string; exception?: any; } {
    return this._errorObject;
}
```

### With Parameters

#### No Return Value

Comments to describe the FUNCTION and use @param for each parameter. The first item after @param must be the parameter name then a further comment

```javascript
/**
 * Execute the current task
 * @param scene defines the scene where you want your assets to be loaded
 * @param onSuccess is a callback called when the task is successfully executed
 * @param onError is a callback called if an error occurs
 */
public run(scene: Scene, onSuccess: () => void, onError: (message?: string, exception?: any) => void) {
    this._taskState = AssetTaskState.RUNNING;
    this.runTask(scene, () => {
this.onDoneCallback(onSuccess, onError);
    }, (msg, exception) => {
this.onErrorCallback(onError, msg, exception);
    });
}
```

```javascript
/**
 * Draws text onto the texture
 * @param text defines the text to be drawn
 * @param x defines the placement of the text from the left
 * @param y defines the placement of the text from the top when invertY is true and from the bottom when false
 * @param font defines the font to be used with font-style, font-size, font-name
 * @param color defines the color used for the text
 * @param clearColor defines the color for the canvas, use null to not overwrite canvas
 * @param invertY defines the direction for the Y axis (default is true - y increases downwards)
 * @param update defines whether texture is immediately update (default is true)
 */
public drawText(text: string, x: number, y: number, font: string, color: string, clearColor: string, invertY?: boolean, update = true) {
    var size = this.getSize();
    if (clearColor) {
this._context.fillStyle = clearColor;
this._context.fillRect(0, 0, size.width, size.height);
    }

    this._context.font = font;
    if (x === null || x === undefined) {
var textSize = this._context.measureText(text);
x = (size.width - textSize.width) / 2;
    }
    if (y === null || y === undefined) {
var fontSize = parseInt((font.replace(/\D/g, '')));;
y = (size.height / 2) + (fontSize / 3.65);
    }

    this._context.fillStyle = color;
    this._context.fillText(text, x, y);

    if (update) {
this.update(invertY);
    }
}

```

#### With Return Value

Comments to describe the FUNCTION and use @param for each parameter and @returns to describe what the function returns. The first item after @param must be the parameter name then a further comment.

```javascript
/**
 * Add a TextFileAssetTask to the list of active tasks
 * @param taskName defines the name of the new task
 * @param url defines the url of the file to load
 * @returns a new TextFileAssetTask object
 */
public addTextFileTask(taskName: string, url: string): TextFileAssetTask {
var task = new TextFileAssetTask(taskName, url);
    this._tasks.push(task);

    return task;
}
```

```javascript
 /**
 * Sets the passed Effect object with the HemisphericLight normalized direction and color and the passed name (string).
 * @param effect The effect to update
 * @param lightIndex The index of the light in the effect to update
 * @returns The hemispheric light
 */
public transferToEffect(effect: Effect, lightIndex: string): HemisphericLight {
    var normalizeDirection = Vector3.Normalize(this.direction);
    this._uniformBuffer.updateFloat4("vLightData",
normalizeDirection.x,
normalizeDirection.y,
normalizeDirection.z,
0.0,
lightIndex);
    this._uniformBuffer.updateColor3("vLightGround", this.groundColor.scale(this.intensity), lightIndex);
    return this;
}
```

## Public with private name

There are occasions when a function should be public for the use of the code but private from a user. Such names start with an underscore. Plain comments are useful for development but the variable should be ignored when building the API documentation. Hence the use of @ignore

```javascript
/**
 * @ignore internal use only
 */
public _getWorldMatrix(): Matrix {
    if (!this._worldMatrix) {
this._worldMatrix = Matrix.Identity();
    }
    return this._worldMatrix;
}
```

```javascript
/**
 * @ignore internal use only
 */
public _onPointerEnter(target: Control): boolean {
    if (!super._onPointerEnter(target)) {
return false;
    }

    if (this.pointerEnterAnimation) {
this.pointerEnterAnimation();
    }

    return true;
}
```

## Private or Protected

These will be ignored automatically when building the API documentation and comments are optional.

```javascript
protected _buildUniformLayout(): void {
    this._uniformBuffer.addUniform("vLightData", 4);
    this._uniformBuffer.addUniform("vLightDiffuse", 4);
    this._uniformBuffer.addUniform("vLightSpecular", 3);
    this._uniformBuffer.addUniform("vLightGround", 3);
    this._uniformBuffer.addUniform("shadowsInfo", 3);
    this._uniformBuffer.addUniform("depthValues", 2);
    this._uniformBuffer.create();
}
```

```javascript
private follow(): void {
    if (!this.target) {
        return;
    }
    this._cartesianCoordinates.x = this.radius * Math.cos(this.alpha) * Math.cos(this.beta);
    this._cartesianCoordinates.y = this.radius * Math.sin(this.beta);
    this._cartesianCoordinates.z = this.radius * Math.sin(this.alpha) * Math.cos(this.beta);

    var targetPosition = this.target.getAbsolutePosition();
    this.position = targetPosition.add(this._cartesianCoordinates);
    this.setTarget(targetPosition);
}
```

```javascript
private _drawRoundedRect(context: CanvasRenderingContext2D, offset: number = 0): void {
    var x = this._currentMeasure.left + offset;
    var y = this._currentMeasure.top + offset;
    var width = this._currentMeasure.width - offset * 2;
    var height = this._currentMeasure.height - offset * 2;

    var radius = Math.min(height / 2 - 2, Math.min(width / 2 - 2, this._cornerRadius));

    context.beginPath();
    context.moveTo(x + radius, y);
    context.lineTo(x + width - radius, y);
    context.quadraticCurveTo(x + width, y, x + width, y + radius);
    context.lineTo(x + width, y + height - radius);
    context.quadraticCurveTo(x + width, y + height, x + width - radius, y + height);
    context.lineTo(x + radius, y + height);
    context.quadraticCurveTo(x, y + height, x, y + height - radius);
    context.lineTo(x, y + radius);
    context.quadraticCurveTo(x, y, x + radius, y);
    context.closePath();
}
```


Since the engine is constantly evolving, you may notice some gaps in the documentation. You're going to know how to fix that!

## The easy way

Requirements: you just need a [Github](https://github.com) account.

To update an existing page, just head to https://github.com/BabylonJS/Documentation/tree/master/content

This folder is the root of all static content used by the site itself.

Then pick a page you want to update and select the edit button:

![quick edit](/img/contribute/documentation/easy-edit.png)

You can now [use markdown](https://guides.github.com/features/mastering-markdown/) to edit the documentation page.

Once done, try to quickly explain what your modification is for, and click on the _Propose file change_ button:

![propose file change](/img/contribute/documentation/easy-submit.png)

For now, your modification isn't yet in the main files. You have to ask to BabylonJS core team to validate and merge your work.

Press _Create pull request_ button:

![sending pull](/img/contribute/documentation/easy-pull.png)

If needed, modify your comment, and press again _Create pull request_ button:

![commenting pull](/img/contribute/documentation/easy-pull2.png)

Congratulations, your modifications are now waiting to be validated and merged into the official documentation!

![pull now waiting](/img/contribute/documentation/easy-pull-waiting.png)

Do not hesitate to read the [Good Practice](/divingDeeper/developWithBjs/contributeToDocs#good-practices) section.

## Deeper Changes

Sometimes, quick edits like above are not sufficient. Indeed, you might want to run the documentation locally on your computer before pushing online, just to be sure nothing is broken.

Requirements:

-   a [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 12 and up.
-   [yarn](https://yarnpkg.com/getting-started/install)

### Forking

Start by going to the main BabylonJS [Documentation](https://github.com/BabylonJS/Documentation) repository and clicking on the _Fork_ button:

![fork](/img/contribute/documentation/further-fork-creation.png)

This will make a copy of the repository, but on your account.

Click on _Clone or download_ button, and _Open in Desktop_:

![open locally](/img/contribute/documentation/further-open-desktop.png)

Github Desktop will be opened and ask you where you want to save your fork.

When the files are downloaded, open a command in this repo. It can be done quickly using Github Desktop menu:

![powershell](/img/contribute/documentation/further-powershell.png)

(_you may have_ Open in Command _rather than_ Open in PowerShell _, that's not a big deal_)

You need 'yarn' installed. For further information about yarn you can go to the [yarn installation guide](https://yarnpkg.com/getting-started/install).

After installing yarn type `yarn install`, press enter and wait the operation to be done.

This fork operation has to be done only once. You're now able to run locally the documentation by following the next section.

### Running and editing the doc locally

Run:

`yarn 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 starting 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/divingDeeper/my_very_great_page`.

Here, you can create a `my_very_great_page` folder into the `/img/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/divingDeeper/my_very_great_page/my-wonderful-image.jpg)
```

Of course, try to keep image size as low 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/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 logo.

#### Internal links

To link to an internal document, use its path from root without adding the domain. For example:

```markdown
[Post Processes](/divingDeeper/postProcesses/usePostProcesses)
```

### Adding examples

It is always great to provide examples in your documentation page. You can add playgrounds and NME, and they will be added automatically to the page's side menu, if you use the right markdown.

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-chars id and the version number, if needed. For example: `#Y642I8#2`.

Same thing does 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 on _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 on _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](/divingDeeper/developWithBjs/contributeToDocs#the-easy-way) 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](/divingDeeper/developWithBjs/contributeToDocs#adding-new-images)
-   be careful about image size (tip: Photoshop has a "Save for the web" export)

### Code

-   when showing a JavaScript block of code, inform Markdown that it's JavaScript to ensure syntax highlighting:

![markdown code](/img/contribute/documentation/markdown-code.png)

-   when quoting a property in a sentence, you can use single _\`_ char (Alt + numpad 96)
    -   example: You can set the `roughness` of a PBR material to 1.

### Links

-   use relative links
    -   example: `[Load Files with Assets Manager](/divingDeeper/developWithBjs/contributeToDocs)` instead of `[Load Files with Assets Manager](/divingDeeper/developWithBjs/contributeToDocs)`

## Further Reading

Any articles, urls, docs, links that you'd like the reader to have as reference for a doc page, should go into the further reading section of the metadata at the top of each page.



# Make the Best use of The Forum

The [Babylon.js forum](https://forum.babylonjs.com) is a fantastic place to get help or help others.
This short page is intended to help you get the best answer as quickly as possible.

## What to do if you have a question for the forum

The best way to get an answer quickly is to follow this 3 easy steps:
- Search about your issue on the [documentation](). Maybe the problem you have is just a matter of understanding how the API works?
- Search about your issue on the [forum](https://forum.babylonjs.com). Maybe someone else already had the same problem?
- Provide a reproduction of your issue within the [playground](https://playground.babylonjs.com). Questions with a playground are likely to get a answer within the next two hours. It is really hard for the community to help without a repro because of the inner rich nature of JavaScript, WebGL and Babylon.js. Consider this step **mandatory**.


**Babylon.js** comes with different versions that you can find in the /dist folder of the [repository](https://github.com/BabylonJS/Babylon.js/tree/master/dist):

## CDN

Babylon.js files can be found on our CDN:

* https://cdn.babylonjs.com/babylon.js
* https://cdn.babylonjs.com/babylon.max.js


## Unminified version: *babylon.max.js*

This version is aimed to be used for debugging purpose only. It is not minified so you can easy use it to debug. 
Please do not use it in production environment as the file size is really important (more than 3.0 MB).

## Minified version: *babylon.js*

This is the complete version of babylon.js. File size is less than 250KB when gizipped. This version is aimed for production.



This tutorial will guide you through the process of creating a material for the [materials library](https://github.com/BabylonJS/Babylon.js/tree/master/materialsLibrary)

## Setting up environment

First of all, you need to create a folder for your shader in the /materialsLibrary/src folder. Let's call it diffuseEmissive.
Then you need to create your files:

- babylon.diffuseEmissiveMaterial.ts (just copy/paste from babylon.simpleMaterial.ts)
- diffuseEmissive.vertex.fx (just copy/paste from simple.vertex.fx)
- diffuseEmissive.fragment.fx (just copy/paste from simple.fragment.fx)

Then update the config.json file in the tools/gulp and add an entry in the "materialsLibrary/libraries" section of the file:

```javascript
  "libraries": [
    ...
      {
        "output": "babylon.triPlanarMaterial.min.js",
        "entry": "./legacy/legacy-triPlanar.ts",
        "preventLoadLibrary": true
      }
      ...
  ]
```

To build all materials and generate the _dist_ folder, just run from the tools/gulp folder:

```bash
gulp materialsLibrary
```

## Update the shaders

Because we used the simple material as source, we already have everything required for a complete babylon.js material.
The simple material already supports diffuse texture.

To add support for an emissive texture, let's add this code to the header of diffuseEmissive.vertex.fx file:

```
#ifdef EMISSIVE
varying vec2 vEmissiveUV;
uniform mat4 emissiveMatrix;
uniform vec2 vEmissiveInfos;
#endif
```

Then add this code in the main function:

```
#ifdef EMISSIVE
	if (vEmissiveInfos.x == 0.)
	{
		vEmissiveUV = vec2(emissiveMatrix * vec4(uv, 1.0, 0.0));
	}
	else
	{
		vEmissiveUV = vec2(emissiveMatrix * vec4(uv2, 1.0, 0.0));
	}
#endif
```

This code will generate the correct UV to read from emissive texture. Please note that we use #ifdef to take profit of the babylon.js smart shaders.

Then you have to update the fragment shader. First add this code to the header:

```
#ifdef EMISSIVE
varying vec2 vEmissiveUV;
uniform sampler2D emissiveSampler;
uniform vec2 vEmissiveInfos;
#endif
```

Then add this code at the end of the main function (just before the last line (gl_FragColor = ...):

```
#ifdef EMISSIVE
	color.rgb += texture2D(emissiveSampler, vEmissiveUV) * vEmissiveInfos.y;
#endif
```

## Update the material

First of all, rename all occurences of _SimpleMaterialDefines_ to _DiffuseEmissiveMaterialDefines_ and _SimpleMaterial_ to _DiffuseEmissiveMaterial_.

Then add this property to _SimpleMaterialDefines_ class:

```javascript
public EMISSIVE = false;
```

Add this property to the _DiffuseEmissiveMaterial_ class:

```javascript
public emissiveTexture: BaseTexture;
```

Then go to _isReady_ function and add this code in the `if (scene.textureEnabled)` block:

```javascript
if (this.emissiveTexture && StandardMaterial.EmissiveTextureEnabled) {
  if (!this.emissiveTexture.isReady()) {
    return false;
  } else {
    needUVs = true;
    this._defines.EMISSIVE = true;
  }
}
```

The next function to update is _bind_. Add this code after the `//Textures` comment:

```javascript
if (this.emissiveTexture && StandardMaterial.EmissiveTextureEnabled) {
  this._effect.setTexture("emissiveSampler", this.emissiveTexture);

  this._effect.setFloat2(
    "vEmissiveInfos",
    this.emissiveTexture.coordinatesIndex,
    this.emissiveTexture.level
  );
  this._effect.setMatrix(
    "emissiveMatrix",
    this.emissiveTexture.getTextureMatrix()
  );
}
```

You may also need to add this code to the _clone_ function:

```javascript
if (this.emissiveTexture && this.emissiveTexture.clone) {
  newMaterial.emissiveTexture = this.emissiveTexture.clone();
}
```

For completeness, you will also have to complete the _serialize_ and _Parse_ functions (This is only required if you want to save/load your material to a .babylon file).
Please note that _serialize_ function needs to output the complete material name to the serializationObject like here:

```javascript
serializationObject.customType = "BABYLON.SimplelMaterial";
```

And you're done for the material! Now it is time to test it.

## Update the test page

To test your material, open the /materialsLibrary/index.html page. References are added automatically.

Then add the material at line 120:

```javascript
var diffuseEmissive = new BABYLON.DiffuseEmissiveMaterial(
  "diffuseEmissive",
  scene
);
diffuseEmissive.diffuseTexture = new BABYLON.Texture(
  "textures/amiga.jpg",
  scene
);
diffuseEmissive.diffuseTexture.uScale = 5;
diffuseEmissive.diffuseTexture.vScale = 5;

diffuseEmissive.emissiveTexture = new BABYLON.Texture(
  "textures/amiga.jpg",
  scene
);
diffuseEmissive.emissiveTexture.uScale = 10;
diffuseEmissive.emissiveTexture.vScale = 10;
```

Finally update the UI control:

```javascript
gui
  .add(options, "material", ["standard", "simple", "diffuseEmissive"])
  .onFinishChange(function() {
    switch (options.material) {
      case "diffuseEmissive":
        currentMaterial = diffuseEmissive;
        break;
      case "simple":
        currentMaterial = simple;
        break;
      default:
        currentMaterial = std;
        break;
    }

    currentMesh.material = currentMaterial;
  });
```

## Launch the test server

To Launch the server, you can start from the tools/gulp folder:

```bash
gulp webserver
```

## Using the material with Babylon.js file loader

Babylon.js file format supports the use of custom material. You must provide a `serialize()` and a `Parse()` functions alongside with a `getClassName()` function.
To let the loader knows about your material, you will also need to add the following line to the code using your material:

```javascript
Tools.RegisteredExternalClasses["MyMaterial"] = MyMaterial;
```

This code will add your class to the list of supported external classes so that the loader will be able to instantiate it when loading a .babylon file with a reference to your material.


## Introduction

The NPM package manager is one of the best way to define and organize your project's dependencies. Parallel to traditional javascript development (including a script in a 'script' HTML Tag), using npm packages allows you to use tools like Webpack or Browserify to pack your project and (continuously) deliver it.

We now officially support our npm packages and will continue updating the npm's repository with new versions as they being developed. The first supported version is 3.1.0-alpha3.4

All examples in this tutorial will use commonjs / es6 imports. However, since we are using [UMD](https://github.com/umdjs/umd), the same files being used in our npm packages can also be used with AMD-imports and can also be simply included in an HTML script tag.

## Available packages

We offer babaylon.js' core and its modules as npm packages. The following are available:

* [babylonjs](https://www.npmjs.com/package/babylonjs) - Babylon's core.
* [babylonjs-materials](https://www.npmjs.com/package/babylonjs-materials) - a collection of Babylon-supported advanced materials.
* [babylonjs-loaders](https://www.npmjs.com/package/babylonjs-loaders) -  All of Babylon's official loaders (OBJ, STL, glTF)
* [babylonjs-post-process](https://www.npmjs.com/package/babylonjs-post-process) - Babylon's post processes.
* [babylonjs-procedural-textures](https://www.npmjs.com/package/babylonjs-procedural-textures) - Officially supported procedural textures
* [babylonjs-serializers](https://www.npmjs.com/package/babylonjs-serializers) - Scene / mesh serializers.
* [babylonjs-gui](https://www.npmjs.com/package/babylonjs-gui) - BabylonJS GUI module.
* [babylonjs-viewer](https://www.npmjs.com/package/babylonjs-viewer) - The stand-alone BabylonJS Viewer.

## Basic usage

Babylon's core and modules take care of setting the dependencies between themselves, so the developer simply needs to import or require them to get everything working.

### Installing Babylon.js

To install the latest babylon version use:

```bash
npm install --save babylonjs
```

This will install babylonjs' javascript files and will also include a TypeScript declaration file.

To include Babylon in a javascript or typescript file, use:

```javascript
import * as BABYLON from 'babylonjs';
```

You can also load specific classes if you need them:

```javascript
import { Engine, Scene } from 'babylonjs';
```

**NOTE:** if you can't make this import method to work, go to the section on typescript and webpack below.

### Installing other Babylon modules

After including babylonjs you can add Babylon's extra modules using npm as follows:

```bash
npm install --save babylonjs-materials [other packages]
```

Same as the babylonjs, this will install (default-minified and non-minified) javascript files and a declaration file.

To import the dependencies, you will need to import them like for the babylon module:

```javascript
import * as Materials from 'babylonjs-materials';
```

And use it like below:

```javascript
let skyMaterial = new Materials.SkyMaterial(.....)
```

### using require()

If you prefer not to use es6-import syntax, you can use require in order to import babylon into your project:

```javascript
let BABYLON = require('babylonjs');
let GUI = require('babylonjs-gui');
let materials = require('babylonjs-materials');
```

## TypeScript support

Being written in TypeScript, Babylon.js will always support TypeScript developers. We provide a declaration file in each package, that either extends the BABYLON namespace or declares a new namespace that can be used during development.

If not detected by your IDE (mostly in case you are not relying on import/export), the most important thing to get full TypeScript support in your project is to add the imported packages as types of compilerOptions in [tsconfig.json](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) as follows:

```javascript
{
    "compilerOptions": {
        .....,
        "types": [
            "babylonjs",
            "babylonjs-gui",
            "babylonjs-materials"
        ],
        ...
    },
    ...
}

```

This will load BABYLON's namespace and will allow autocomplete (and of course type safety) correctly.

**NOTE:** to generate a default `tsconfig.json` file that contains useful information about the different settings, run the following in your terminal:
```
tsc --init
```

### Example using webpack

A very simple webpack configuration to compile a babylon.js TypeScript project can look like this:

```javascript
module.exports = {
    entry: {
        app: './mygame.ts'
    },
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: '[name].js'
    },
    resolve: {
        extensions: ['.ts', '.tsx', '.js']
    },
    devtool: 'source-map',
    plugins: [

    ],
    module: {
        rules: [{
            test: /\.tsx?$/,
            loader: 'ts-loader',
            exclude: /node_modules/
        }]
    }
}
```

Simply create a file `webpack.config.js` at the root of your project and copy-paste the above template in it.
The file `mygame.ts` should the entry point of the project.

**NOTE:** Make sure you've installed the following packages:
```
npm install --save-dev webpack
npm install --save-dev webpack-cli
npm install --save-dev typescript
npm install --save-dev ts-loader
```


## ES6
If you wish to benefit from tree shaking and other nitty gritties, you can now rely on our Babylon.js ES6 packages:

* [@babylonjs/core](https://www.npmjs.com/package/@babylonjs/core) - Babylon's core.
* [@babylonjs/materials](https://www.npmjs.com/package/@babylonjs/materials) - a collection of Babylon-supported advanced materials.
* [@babylonjs/loaders](https://www.npmjs.com/package/@babylonjs/loaders) -  All of Babylon's official loaders (OBJ, STL, glTF)
* [@babylonjs/post-processes](https://www.npmjs.com/package/@babylonjs/post-processes) - Babylon's post processes.
* [@babylonjs/procedural-textures](https://www.npmjs.com/package/@babylonjs/procedural-textures) - Officially supported procedural textures
* [@babylonjs/serializers](https://www.npmjs.com/package/@babylonjs/serializers) - Scene / mesh serializers.
* [@babylonjs/gui](https://www.npmjs.com/package/@babylonjs/gui) - BabylonJS GUI module.
* [@babylonjs/inspector](https://www.npmjs.com/package/@babylonjs/inspector) - The BabylonJS Inspector for es 6.

Please note that you can not mix ES6 and our legacy packages.

```javascript
import { Engine } from '@babylonjs/core/Engines/engine'

const canvas = document.getElementById("canvas");

const engine = new Engine(canvas, true);

// code continues....
```

For more information, you can have a look at [the ES6 documentation](/divingDeeper/developWithBjs/treeShaking);

## External libraries

### Pre 3.2.0-beta.1

Cannon and Oimo (both physics engines) are being delivered as dependencies when installing babylonjs using npm. There is no need to install them on your own.

### Current version

Cannon and Oimo are both optional dependencies. If you want to use any of them, please install them yourself.

### using the optional dependencies with AMD

If you wish to use oimo for example, install Oimo using npm:

```shell
npm install oimo
```

This will allow our UMD definition to find oimo in node_modules and use it. If you use AMD you will need to first declare oimo as a module (as oimo uses anonymous AMD definition):

```javascript
define('oimo', ['path/to/oimo'], function(OIMO) {
    return OIMO;
})
```

Now Babylon will automatically find oimo and will inject it.

### Using Webpack

To use either oimo or cannon, install them using npm. Our UMD definition will find them and inject them automatically.

If you use commonjs and webpack and don't install cannon or oimo, you might see a warning saying that those dependencies could not be found. To fix that, use webpack's `externals` feature.

In `webpack.config.js` add:

```javascript
    ...,
    externals: {
        oimo: 'OIMO', //or true
        cannon: 'CANNON' //or true
    },
    ...
```

This will define both of those dependencies as external dependencies and will not load them anymore.

You can see an example of that in the Viewer directory of our main repository.

## Questions and Troubleshooting

### error TS2307: Cannot find module 'babylonjs' (or other modules)

* Make sure you have a version higher than 3.1.0-alpha3.4
* Make sure you added 'babylonjs' to "types" in tsconfig.json

### Even though I use only a few classes from the BABYLON namespace, the entire Babylon module is included

Due to the way BabylonJS is built, Tree-Shaking is currently not quite possible. Babylon's internal objects have deep connections with one another (for performance reasons). That means, that your built JS file will be at least Babylon.js' minified size.

You can still use custom builds to build you own minimal version: //doc.babylonjs.com/how_to/how_to_start#custom-builds

### Naming is different than what the documentation states

Our documentation always refers to the BABYLON namespace. We therefore always use this namespace when talking about objects/classes, and also use this namespace when talking about the GUI.

When using es-6 imports or require, you are the one responsible to setting the namespace in accordance to your needs. Pay attention when changing it and when copying code from the Playground.

## Example of a webpack project using Babylon modules

Let's see an example of how to setup a Babylon project written in Typescript and bundled using Webpack.

I will be using webpack 4, but the same setup will work with the previous version of webpack.

### Setting up the project

We will be using npm to install dependencies. We first run `npm init` to generate package.json . You can generate package.json in any other way you wish.

After package,json was generated, we will install the needed dev dependencies:

```bash
npm install --save-dev typescript webpack ts-loader webpack-cli
```

Now we will need to configure webpack to know what to actually do. This is a simple example of the webpack configuration file, `webpack.config.js`:

```javascript
const path = require("path");

module.exports = {
    entry: './index.ts',
    output: {
        filename: 'index.js',
        path: path.resolve(__dirname, 'dist')
    },
    resolve: {
        extensions: [".ts"]
    },
    module: {
        rules: [
            { test: /\.tsx?$/, loader: "ts-loader" }
        ]
    },
    mode: "development"
};
```

We will also add `tsconfig.json`:

```javascript
{
    "compilerOptions": {
        "target": "es5",
        "module": "commonjs",
        "noResolve": false,
        "noImplicitAny": false,
        "removeComments": true,
        "preserveConstEnums": true,
        "sourceMap": true,
        "experimentalDecorators": true,
        "isolatedModules": false,
        "lib": [
            "dom",
            "es2015.promise",
            "es5"
        ],
        "declaration": true,
        "outDir": "./"
    },
    "files": [
        "./index.ts"
    ]
}
```

We will also add an html file with a canvas (index.html):

```html
<!DOCTYPE html>
<html>

    <head>
        <style>
            html,
            body {
                overflow: hidden;
                width: 100%;
                height: 100%;
                margin: 0;
                padding: 0;
                text-align: center;
            }

            #renderCanvas {
                width: 100%;
                height: 100%;
                touch-action: none;
            }
        </style>
    </head>

    <body>
        <canvas id="renderCanvas"></canvas>
        <script src="dist/index.js"></script>
    </body>

</html>
```

After adding a new file called `index.ts` we are ready to start developing.

### Adding babylon support

We will start a simple project with Babylon core module, the loaders, and the GUI.

First - let's install babylon's dependencies:

```bash
npm install --save babylonjs babylonjs-loaders babylonjs-gui
```

This will install the latest stable version of Babylon. To install the latest preview version, use the preview stream:

```bash
npm install --save babylonjs@preview babylonjs-loaders@preview babylonjs-gui@preview
```

### Writing some code

Our index.ts will show a sphere for now. I will be using a code very similar to the playground, but you can structure your code as you wish:

```javascript
var canvas: any = document.getElementById("renderCanvas");
var engine: Engine = new Engine(canvas, true);

function createScene(): Scene {
    var scene: 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);

    return scene;
}

var scene: Scene = createScene();

engine.runRenderLoop(() => {
    scene.render();
});
```

You will notice that the BABYLON namespace is gone. and that you see a lot of errors, if actually using this file. This is because we haven't yet imported the needed dependencies from babylonjs.

We will use es6 imports for that. To add the dependencies, we have two options. Defining the BABYLON namespace:

```javascript
import * as BABYLON from 'babylonjs';
```

This will actually bring back the BABYLON namespace. My preferred option is only loading the dependencies you need:

```javascript
import { Engine, Scene, ArcRotateCamera, HemisphericLight, Vector3, MeshBuilder, Mesh } from "babylonjs";
```

Adding this line to the beginning of the file will load all needed dependencies to your project and will eliminate all errors.

### Bundling the project

Compiling index.ts using tsc will work. But it will generate a file that is unusable without babylonjs itself. To get a bundled file we will run webpack. Again, two ways for that:

```bash
./node_modules/.bin/webpack
```

Or creating a build task in package.json:

```javascript
    "scripts": {
        "build": "webpack"
    },
```

And running:

```bash
npm run build
```

We will now have an index.js in the dist folder that we can use in our index.html

You will notice there are a few warnings about dependencies. We will deal with that later.

### Checking your project

The best way for you during development would be the webpack dev server (https://github.com/webpack/webpack-dev-server/), but it is not a part of the scope of this tutorial.

To check the current project, I use the http-server npm module (installed globally). You can use any web server that will serve the root folder of our project.

If you open out index.html, we will see a sphere. Hooray!

### Adding the GUI

For the sake of learning, we will add a new file, `gui.ts`, even thou it can still be done with a single ts file. Our gui.ts file will look like this:

```javascript
import { AbstractMesh } from "babylonjs";
import { AdvancedDynamicTexture, Rectangle, Control, TextBlock } from "babylonjs-gui";

let advancedTexture: AdvancedDynamicTexture;

function init(): void {
    if (!advancedTexture) {
        advancedTexture = AdvancedDynamicTexture.CreateFullscreenUI("ui1");
    }
}

export function addLabelToMesh(mesh: AbstractMesh): void {
    if (!advancedTexture) {
        init();
    }
    let label: Rectangle = new Rectangle("label for " + mesh.name);
    label.background = "black";
    label.height = "30px";
    label.alpha = 0.5;
    label.width = "100px";
    label.cornerRadius = 20;
    label.thickness = 1;
    label.linkOffsetY = 30;
    label.top = "10%";
    label.zIndex = 5;
    label.verticalAlignment = Control.VERTICAL_ALIGNMENT_TOP;
    advancedTexture.addControl(label);

    const text1: TextBlock = new TextBlock();
    text1.text = mesh.name;
    text1.color = "white";
    label.addControl(text1);
}
```

and in our index.js, we will import the function and use it in our createScene function:

```javascript
import { addLabelToMesh } from "./gui";
```

and the createScene function looks like this:

```javascript
function createScene(): Scene {
    var scene: 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);

    addLabelToMesh(sphere);

    return scene;
}
```

If we compile now using webpack, we will have our GUI element in our scene.

### Eliminating the dependencies warnings

Babylon is using oimo, cannon and earcut as external, optional dependencies. If you don't use them, you can define them as externals in webpack configuration, and avoid the warnings:

```javascript
    externals: {
        "oimo": true,
        "cannon": true,
        "earcut": true
    },
```


This tutorial will guide you through the process of creating a procedural texture for the [procedural textures library](https://github.com/BabylonJS/Babylon.js/tree/master/proceduralTexturesLibrary)

## Setting up environment

First of all, you need to create a folder for your shader in the /proceduralTexturesLibrary/src folder. Let's call it **cloudBis**.

Then you need to create your files:

- babylon.**cloudBis**ProceduralTexture.ts (just copy/paste from babylon.woodProceduralTexture.ts )
- **cloudBis**ProceduralTexture.fragment.fx (just copy/paste from woodProceduralTexture.fragment.fx )

To integrate your new procedural texture to the build process, you have to edit the config.json file in the tools/gulp folder and add an entry in the "proceduralTextureLibrary/libraries" section of the file:

```javascript
  "libraries": [
    ...
      {
        "output": "babylon.brickProceduralTexture.min.js",
        "entry": "./legacy/legacy-brick.ts",
        "preventLoadLibrary": true
      }
    ...
  ]
```

To build all the procedural textures and generate the _dist_ folder, just run from the tools/gulp folder:

```bash
gulp proceduralTextureLibrary
```

## Update the shaders

Open the **cloudBisProceduralTexture.fragment.fx** file.
The shader is composed of 3 parts:

- The variables and uniforms definition

```
precision highp float;

varying vec2 vUV;

uniform vec4 skyColor;
uniform vec4 cloudColor;

```

- All the functions you need (here **rand**, **noise** and **fbm**)

```
float rand(vec2 n) {
	return fract(cos(dot(n, vec2(12.9898, 4.1414))) * 43758.5453);
}

float noise(vec2 n) {
	const vec2 d = vec2(0.0, 1.0);
	vec2 b = floor(n), f = smoothstep(vec2(0.0), vec2(1.0), fract(n));
	return mix(mix(rand(b), rand(b + d.yx), f.x), mix(rand(b + d.xy), rand(b + d.yy), f.x), f.y);
}

float fbm(vec2 n) {
	float total = 0.0, amplitude = 1.0;
	for (int i = 0; i < 4; i++) {
		total += noise(n) * amplitude;
		n += n;
		amplitude *= 0.5;
	}
	return total;
}
```

- The **main** function which is the one called to get the pixel color

```c
void main() {
	vec2 p = vUV * 12.0;
	vec4 c = mix(skyColor, cloudColor, fbm(p));
	gl_FragColor = c;
}
```

## Write the procedural texture

The procedural texture is a .ts file. It contains a class which has to inherit from the **ProceduralTexture** class.

To be sure that you have intelliSense and that the compilation phase works well you have to add a reference at the top of your **babylon.cloudBisProceduralTexture.ts** file :

```javascript
/// <reference path="../../../dist/preview release/babylon.d.ts"/>
```

The main part of the magic for a procedural texture is happening in the shader file. The TypeScript file is mainly here to give its caller the ability to set values for uniforms and pass it to the shader itself.
By convention we create a function named **updateShaderUniforms()** which will be called from the construtor and in every setters for each property.

Here is an example for the CloudBisProceduralTexture.

As you can see the **setXXX** function is used to send a specific value to the shader.

The shader is called by its name in the constructor using the **super** function.

```javascript
module BABYLON {
    export class CloudBisProceduralTexture extends ProceduralTexture {
        private _skyColor = new Color4(0.15, 0.68, 1.0, 1.0);
        private _cloudColor = new Color4(1, 1, 1, 1.0);

        constructor(name: string, size: number, scene: Scene, fallbackTexture?: Texture, generateMipMaps?: boolean) {
            super(name, size, "cloudProceduralTexture", scene, fallbackTexture, generateMipMaps);
            this.updateShaderUniforms();
            this.refreshRate = 0;
        }

        public updateShaderUniforms() {
            this.setColor4("skyColor", this._skyColor);
            this.setColor4("cloudColor", this._cloudColor);
        }

        public get skyColor(): Color4 {
            return this._skyColor;
        }

        public set skyColor(value: Color4) {
            this._skyColor = value;
            this.updateShaderUniforms();
        }

        public get cloudColor(): Color4 {
            return this._cloudColor;
        }

        public set cloudColor(value: Color4) {
            this._cloudColor = value;
            this.updateShaderUniforms();
        }
    }
}
```

## Update the test page

To test your material, open the /proceduralTextureLibrary/index.html page. References are added automatically.

Then add the procedural texture line 192:

```javascript
var cloudBis = new BABYLON.CloudBisProceduralTexture("cloudPTBis", 256, scene);
```

Finally update the UI control:

```javascript
gui
  .add(options, "texture", [
    "default",
    "fire",
    "wood",
    "cloud",
    "grass",
    "road",
    "brick",
    "marble",
    "starfield",
    "cloudBis"
  ])
  .onFinishChange(function() {
    resetPTOptions();
    switch (options.texture) {
      case "fire":
        currentTexture = firePT;
        addPToptions(firePT, ["time", "alphaThreshold", "speed"]);
        break;
      case "wood":
        currentTexture = woodPT;
        addPToptions(woodPT, ["ampScale", "woodColor"]);
        break;
      case "cloud":
        currentTexture = cloudPT;
        addPToptions(cloudPT, ["skyColor", "cloudColor"]);
        break;
      case "grass":
        currentTexture = grassPT;
        addPToptions(grassPT, ["groundColor"]);
        break;
      case "road":
        currentTexture = roadPT;
        addPToptions(roadPT, ["roadColor"]);
        break;
      case "brick":
        currentTexture = brickPT;
        addPToptions(brickPT, [
          "numberOfBricksHeight",
          "numberOfBricksWidth",
          "brickColor",
          "jointColor"
        ]);
        break;
      case "marble":
        currentTexture = marblePT;
        addPToptions(marblePT, [
          "numberOfTilesHeight",
          "numberOfTilesWidth",
          "amplitude",
          "jointColor"
        ]);
        break;
      case "starfield":
        currentTexture = starfieldPT;
        addPToptions(starfieldPT, [
          "saturation",
          "distfading",
          "darkmatter",
          "alpha",
          "time",
          "beta",
          "zoom",
          "formuparam",
          "stepsize",
          "tile",
          "brightness"
        ]);
        break;
      case "cloudBis":
        currentTexture = cloudBis;
        break;
      case "none":
      default:
        currentTexture = diffuseTexture;
        break;
    }

    std.diffuseTexture = currentTexture;
    window.enableTexture(options.texture);
  });
```

## (Optional) enable a graphical interface.

If your procedural texture contains properties that allows the dev to customize it, you can enable an interface to change them live in the sample.

To do that, you only have to add a call to the **addPToptions** helper function in your **case**

Your code will look like this :

```javascript
case "cloudBis":
currentTexture = cloudBis;
addPToptions(cloudBis, ['skyColor', 'cloudColor']);
break;
```

The first parameter is the texture object and the second one is an array containing the list of properties you want to make editable in the sample.

## Launch the test server

To Launch the server, you can start from the tools/gulp folder:

```bash
gulp webserver
```



# Using the Playground in Development of BJS

During the early stages of developing code to contribute to Babylon.js it can be useful to try out that code in the Playground. Just ensure that the Playground is in Typescript mode by using the link https://www.babylonjs-playground.com/ts.html# . The `New` button will then give you the starting code. 

## An Example

Babylon.js has code to form a bezier curve found at https://github.com/BabylonJS/Babylon.js/blob/master/src/Maths/math.path.ts , (just search for Curve3 on this page) so it would make sense to put any code to form a bezier surface on the same page.

The first step is to produce code that works. You can of course immediately follow the steps in [how to start contributing](/divingDeeper/developWithBjs/howToStart) and of course before submitting a PR there will have to be working code submitted as described on this page. However you might not yet be confident with the whole approach of forking the code, using git, setting up an IDE and pull requests but are familiar with using Typescript.

So an alternative is to try out the code in the playground. The following playground shows the Typescript code for a bezier surface which is in development with the playground.

<Playground id="H3AF26#1" title="Playground Code Example - Bezier Surface" description="Simple playground example of a Bezier Surface." image="/img/playgroundsAndNMEs/divingDeeperUsingPlaygrounds1.jpg"/>

Though this shows working code it is not completely ready for copying into a local repository of Babylon.js, committing and sending a PR. For a start not all the comments needed are in place. 

Also once placed in the local repository the first line

```javascript
class BezierSurface {
```

would need to be changed to

```javascript
export class BezierSurface {
```


## From Playground to Pull Request

Once you are happy the code works and you have copied it to your local repository then before submitting your PR please make sure you have read the following to ensure a smooth positive result.

[Start Contibuting](how to start contributing)  
[Contributing Read Me](https://github.com/BabylonJS/Babylon.js/blob/master/contributing.md)  
[Code Guidelines](/divingDeeper/developWithBjs/approvedNamingConventions)  
[Comments in the API](/divingDeeper/developWithBjs/contributeToAPI)

On the other hand there is always the possibility that someone in the core team likes your idea and its execution so much they might just copy and add it to Babylon.js directly.


&nbsp;


# Visual Studio Code

VSCode is one of several integrated development environments that can be used in the development of projects using Babylon.js. It has the advantage of Git integration built in and a plugin to display .babylon files.

You can install VSCode from their site: [https://code.visualstudio.com/](https://code.visualstudio.com/)

Once installed, a few plugins will help you having the best experience. You can search for them in the extension tab (Ctrl+Shift+d):

1. Debugger for Chrome as well as the chrome browser.
2. Shader language support for VS Code (syntax highlighting and autocompletion in glsl shader)
3. [This extension](https://marketplace.visualstudio.com/items?itemName=julianchen.babylon-js-viewer) can be used to display the content of a babylon file directly in vscode. It can be useful if you want to quickly check if your artist did a good job with object and their names :)

Finally, I would recommend adding a few shortcuts to your environment. Follow the [guide](https://code.visualstudio.com/docs/customization/keybindings#_customizing-shortcuts):
 1. To configure keyboard shortcuts the way you want, go to the menu under File > Preferences > Keyboard Shortcuts. (Code > Preferences > Keyboard Shortcuts on Mac)
 2. In the left side, add:
 ```
// Place your key bindings in this file to overwrite the defaults
[
{ "key": "ctrl+shift+alt+s",         "command": "workbench.action.files.saveFiles" },
{ "key": "ctrl+shift+alt+k",         "command": "workbench.action.tasks.terminate" },
{ "key": "ctrl+shift+alt+t",         "command": "workbench.action.tasks.test" },
{ "key": "ctrl+shift+alt+l",         "command": "workbench.action.tasks.showLog" },
{ "key": "ctrl+shift+alt+r",         "command": "workbench.action.tasks.runTask" }
]
```

This will make the main commands quicker to access. Do not hesitate to adapt the bindings to your preferences.

![keybindings](/img/how_to/howToStart/keybindings.png)

Also in VSCode there is a ```Debug``` tab on the menu. To use it with Babylon.js you need to install an extension, find out more from  [Debugger for Chrome](https://code.visualstudio.com/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code).

With the test task running from the VSCode debug tab, chose the section you want to debug and launch the debugger.

This will debug all the Typescript and Javascript in chrome and stop on your breakpoints setup in those files in VSCode. This debugs all the code from src, materialsLibrary, procceduralTexturesLibrary, postprocessLibrary...

*Hint*: If another chrome session is already running on remote debug on port 9222 the debugger will fail to attach as the port is already open. You will have to close the other remote debug first.


## Customize Your Build

The Workloads that you might have known are gone in 4.0.0 in favor of [ES6 packages]((/divingDeeper/developWithBjs/npmSupport#es6). You do not need anymore to customize the output of the build as you can rely on [tree shaking](https://webpack.js.org/guides/tree-shaking/) on our npm packages externally.



# Image Filter Control

The Babylon.js Filter Control is a web control built on top of Babylon.js in order to apply filter to pictures in web pages with blazing fast speed.

## Introduction
Filtering images to apply effect might be tedious and slow on the CPU. The best place to do so (for a wide variety of effects) is on the GPU. But setting up an entire WebGL pipeline simply to process images might be tricky even more if you wish to benefit from WebGL 2 to 1 fallback and workaround famous platform issues.

To greatly simplify this task we introduced the `ImageFilter` Control.

![ImageFilter](/img/features/controls/imageFilter.png)

## How to use

### Installation
To begin with the image filter control, you first need to install the controls npm package.

```
npm install @babylonjs/controls
```

To reduce the size of your web page, the controls library is based on the es6 version of `@babylonjs/core` used as a peer dependency. Therefore if you are not relying on it so far in you project, you also need to install core:

```
npm install @babylonjs/core
```

### Instantiation
Once done, you can now import the control in your code:

```
import { ImageFilter } from "@babylonjs/controls/imageFilter";
```

And simply instantiate it in your page:

```
const imageFilter = new ImageFilter(filterCanvas);
```

You simply need to provide a canvas on which we will be able to use a WebGL context. You could as well provide another Babylon.js control in order to share the WebGL context.

Also you, would you need more specific engine configurations, or if you want to use post processes, you should manually use your own engine:

```
const engine = new Engine(filterCanvas);
const imageFilter = new ImageFilter(engine);
```

By default the controls relies on ThinEngine in order to optimize your bundle but it might have some limitations you do not want to have as part of your experiences.

## Using Post Process
In order to apply a custom shader as the image filter, you can use the following code:

```
const blackAndWhitePostProcess = new BlackAndWhitePostProcess("bw", 1, null, undefined, engine);
backAndWhiteFilter.filter(imageToProcess, blackAndWhitePostProcess);
```

Where imageToProcess could be either:
* the url of a picture.
* a video element (the current visible frame of the video will be used)
* another canvas element (the current visible state will be used)

This will apply the post process to the provided input and display it in the canvas.

## Using Custom shader
In order to apply an existing post process as the image filter, you can use the following code:

```
const customEffectWrapper = new EffectWrapper({
    name: "Custom",
    engine: customFilter.engine,
    fragmentShader: `
        // Samplers
        varying vec2 vUV;
        uniform sampler2D textureSampler;
        
        void main(void) 
        {
            gl_FragColor = texture2D(textureSampler, vUV);

            // Swizzle channels
            float r = gl_FragColor.r;
            gl_FragColor.r = gl_FragColor.b;
            gl_FragColor.b = r;
        }
    `,
    samplerNames: ["textureSampler"]
});
customFilter.filter(imageToProcess, customEffectWrapper);
```

Where imageToProcess could be either:
* the url of a picture.
* a video element (the current visible frame of the video will be used)
* another canvas element (the current visible state will be used)

This will apply the custom shader in parameter to the picture. By default, `vUV` is available as a varying defining the full ouptput as texture coordinates. `textureSampler` needs to be present and defines the texture corresponding to the input parameter.

Please note that if you need to add custom unifoms or samplers, they should be defined in the effect wrapper list:

```
const customEffectWrapper = new EffectWrapper({
    name: "Custom",
    engine: customFilter.engine,
    fragmentShader: `
        varying vec2 vUV;
        
        // Default Sampler
        uniform sampler2D textureSampler;

        // Custom uniforms
        uniform sampler2D otherTexture;
        uniform vec3 colorOffset;

        const vec2 scale = vec2(0.25, 1.);

        void main(void) 
        {
            gl_FragColor = texture2D(textureSampler, vUV);

            // Swizzle channels
            float r = gl_FragColor.r;
            gl_FragColor.r = gl_FragColor.b;
            gl_FragColor.b = r;
            gl_FragColor.rgb += clamp(colorOffset, 0., 1.);

            gl_FragColor.rgb *= texture2D(otherTexture, vUV * scale).rgb;
        }
    `,
    // Defines the list of existing samplers (default + customs).
    samplerNames: ["textureSampler", "otherTexture"],
    // Defines the list of existing uniform to be bound.
    uniformNames: ["colorOffset"],
});
```

Then you can simply bind them either in `onApply`:

```
customEffectWrapper.onApplyObservable.add(() => {
    // Sets the custom values.
    customEffectWrapper.effect.setTexture("otherTexture", otherTexture);
    customEffectWrapper.effect.setFloat3("colorOffset", 0.2, 0, 0.2);
})
```

Or during the render loop:

```
// Rely on the underlying engine render loop to update the filter result every frame.
engine.runRenderLoop(() => {
    // Only render if the custom texture is ready (the default one is 
    // checked for you by the render function)
    if (!otherTexture.isReady()) {
        return;
    }

    // Sets the custom values.
    time += engine.getDeltaTime() / 1000;
    customEffectWrapper.effect.setTexture("otherTexture", otherTexture);
    customEffectWrapper.effect.setFloat3("colorOffset", Math.cos(time) * 0.5 + 0.5, 0, Math.sin(time) * 0.5 + 0.5);

    // Render. Please note we are using render instead of filter to improve 
    // performances of real time filter. filter is creating a promise and will therefore
    // generate some lags and garbage.
    customFilter.render(mainTexture, customEffectWrapper);
});
```

Finally, if you are relying on new textures, you need to wait for them to be ready before rendering.

## Process to the canvas
This is by far the simplest, if you have a canvas in your page. You simply need to use the following code to fit the provided element to the canvas size:

```
imageFilter.filter(imageToProcess, filter);
```

On the previous line, imageToResize could be either:
* the url of a picture.
* a video element (the current visible frame of the video will be used)
* another canvas element (the current visible state will be used)

This is the default behavior.

## Process to a Babylon Texture
Instead of filtering directly to a canvas, you could prefer to only create a Babylon.js texture on the GPU. For this, you can use the following function:

```
const texture = imageFilter.getFilteredTexture(imageToResize, { width: 128, height: 100 }, filter);
```

Like before, imageToResize could be either:
* the url of a picture.
* a video element (the current visible frame of the video will be used).
* another canvas element (the current visible state will be used).

You also need to provide the size you want your texture to have on the GPU.

Now you are free to use this texture with any other controls.

## Real Time filtering
Instead of filtering only one time, you might want to create dynamic real time effects. For this, you can simply render the effect during the render loop:

```
// Rely on the underlying engine render loop to update the filter result every frame.
engine.runRenderLoop(() => {
    // Only render if the custom texture is ready (the default one is 
    // checked for you by the render function)
    if (!otherTexture.isReady()) {
        return;
    }

    // Sets the custom values.
    time += engine.getDeltaTime() / 1000;
    customEffectWrapper.effect.setTexture("otherTexture", otherTexture);
    customEffectWrapper.effect.setFloat3("colorOffset", Math.cos(time) * 0.5 + 0.5, 0, Math.sin(time) * 0.5 + 0.5);

    // Render. Please note we are using render instead of filter to improve 
    // performances of real time filter. filter is creating a promise and will therefore
    // generate some lags and garbage.
    customFilter.render(mainTexture, customEffectWrapper);
});
```

This requires to use the render function instead of the filter one to enhance your experience performances.

## Full Code Sample

You can find the integrallity of the code sample above on [Github](https://github.com/BabylonJS/Controls/blob/master/www/imageFilter/index.ts) if you want to see it in action and better see how some of the functionnalities could be used.

## Live Demo

Please, have a look at the [Live Image Filter Demo](https://controls.babylonjs.com/imageFilter) to better appreciate how it works.


Developing With and For Babylon.js

Coming next

Make the Best Use of the Forum

Learn about the best place to get help, the Babylon.js forum.

Framework Versions

Learn about the different versions of Babylon.js.

NPM Support

Learn about Babylon.js's use of the NPM Package Manager.

Babylon.js ES6 support with Tree Shaking

Learn about tree shaking and package management in Babylon.js.

Workloads (legacy)

Learn about the legacy workload system in Babylon.js.

Using Visual Studio Code (VSCode)

Learn how to use the popular oss IDE VSCode for Babylon.js development.

Start Contributing to Babylon.js

Learn how to start contributing to Babylon.js.

Approved Naming Conventions

Learn about standard approved naming conventions in Babylon.js.

Using the Playground for Development in Babylon.js

Learn all about making your development process easier with the super handy playground.

Contribute To The API

Learn how to contribute to the Babylon.js API.

Contribute To The Documentation

Learn how to contribute to the Babylon.js Documentation.

Create a Material For The Material Library

Learn how to add your own material to the Babylon.js material library.

Create a Procedural Texture for the Procedural Textures Library

Learn how to add your own procedural texture to the Babylon.js procedural textures library.