
## Pre-Requisites

- Installation of Node.js, NPM, Git, Typescript, Gulp and have a Github Account;
- A fork and clone of Babylon.js;
- Reading the [contribution guidelines](https://github.com/BabylonJS/Babylon.js/blob/master/contributing.md);
- An IDE such as VSCode;
- An ability to code in Typescript. Babylon.js is written in Typescript then compiled and distributed in JavaScript.

At the time of writing the version of Gulp needed was 4.0.0. The current [What's New](/whats-new) should indicate if there have been any changes of version. You can also look in the Babylon.js repository for `package.json` in `Tools/Publisher` which will give the version number for Gulp and Typescript.


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 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 {
    const 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 {
    const 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) {
    const 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) {
const textSize = this._context.measureText(text);
x = (size.width - textSize.width) / 2;
    }
    if (y === null || y === undefined) {
const 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 {
const 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 {
    const 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);

    const targetPosition = this.target.getAbsolutePosition();
    this.position = targetPosition.add(this._cartesianCoordinates);
    this.setTarget(targetPosition);
}
```

```javascript
private _drawRoundedRect(context: CanvasRenderingContext2D, offset: number = 0): void {
    const x = this._currentMeasure.left + offset;
    const y = this._currentMeasure.top + offset;
    const width = this._currentMeasure.width - offset * 2;
    const height = this._currentMeasure.height - offset * 2;

    const 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();
}
```



This tutorial will guide you through the process of creating a material for the [materials library](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/materials)

## 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
const 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.


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/packages/dev/proceduralTextures)

## 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 constructor 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
const 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
```



## Introduction

NOTE: This page requires revision. If you have any questions, please ask in the [forum](https://forum.babylonjs.com/).

Validation tests are visual tests that check that the rendering of a selection of playgrounds / demos are not broken by some of your changes.

You should normally simply run them as part of the standard build, or manually by browsing [http://localhost:1338/tests/validation](http://localhost:1338/tests/validation).

Should you need more in-depth knowledge of the process, this page is for you! Note however that we won't cover everything related to the visual tests but only the most relevant points.

## Validation test lists

A validation test list is a list of visual tests that should be run to guarantee some level of conformance from the code of the repo.

### List format

A validation test list is described in a JSON formatted file, each test being an entry of the **tests** array:

```json
{
  "root": "https://cdn.babylonjs.com",
  "tests": [
    {
      "title": "Procedural texture with NME",
      "playgroundId": "#8S19ZC#3",
      "renderCount": 2,
      "referenceImage": "procedural_nme.png",
      "threshold": 25,
      "errorRatio": 2.5,
      "excludeFromAutomaticTesting": true,
      "excludedEngines": ["webgpu"]
    }
    // ...
  ]
}
```

_Note_: the **root** url is the base url used to retrieve the code for the tests that have a non empty **scriptToRun** or **sceneFolder** entry, but we won't go into more details, we are only interested in tests based on a playground.

A test is simply a playground that is run by the validation engine. The outcome of the test is the comparison between the generated image and a reference image: if it differs too much, the test is flagged as "failed".

The list of the properties you can use to define a test are:

| Name                        | Mandatory | Default value if omitted | Description                                                                                                                                                                                                                  |
| --------------------------- | :-------: | :----------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title                       |     x     |                          | the title of the test, will be displayed in the browser before the test                                                                                                                                                      |
| <nobr>playgroundId</nobr>   |     x     |                          | the playground id. You can omit the leading #, it will be automatically added if missing                                                                                                                                     |
| renderCount                 |           |            1             | the number of frames to render before applying the test                                                                                                                                                                      |
| referenceImage              |           |       "title".png        | the reference image to test the rendering with. Note that the default value is "title.png", **title** being the value of the title property!                                                                                 |
| threshold                   |           |            25            | the threshold value to check each pixel with. If the (absolute) difference between any of the r/g/b component of the rendered image and the reference image is >= threshold then the number of failing pixels is incremented |
| errorRatio                  |           |           2.5            | acceptable percentage of errors. If `num_failed_pixels * 100 / (width * height) > errorRatio`, the test is flagged as "failed"                                                                                               |
| excludeFromAutomaticTesting |           |          false           | If `true`, this test won't be run on the build server. Some tests must be excluded that way because they fail on the software emulator used by the build server                                                              |
| excludedEngines             |           |            []            | list of engines that must not run this test. Use `"webgl1"` for **WebGL 1**, `"webgl2"` for **WebGL 2** and `"webgpu"` for **WebGPU**                                                                                        |

### Creating new lists

The default list of visual tests is configured in the file **tests/validation/config.json** in the repo. This is the list that is used when using the default url [http://localhost:1338/tests/validation](http://localhost:1338/tests/validation).

However, other lists can be created: you simply need to create .json file(s) in the **tests/validation/** directory. For eg **tests/validation/webgpu.json**, which is a list used during the webgpu implementation.

The reference pictures used by the validation tests of the list must be located in a directory named after the list itself. So, if you have created a list `mylist.json`, you should create a directory `mylist/` under `tests/validation/ReferenceImages/` and put the reference pictures there.

## Running tests

The url to use to start the tests from a validation list is [http://localhost:1338/tests/validation](http://localhost:1338/tests/validation): it will run the tests from the default list (`config.json`).

The full format for this url is:

http://localhost:1338/tests/validation/?list=**LIST**&engine=**ENGINE**&test=**TITLE**&fromtest=**TITLE**&useReverseDepthBuffer=**[0|1]**&useNonCompatibilityMode=**[0|1]**&checkresourcecreation=**[0|1]**

- **LIST**: name of the list, without the `.json` part. If not provided, the default value is `config`
- **ENGINE**: name of the engine to run the list with. If not provided, the default value is `webgl2`. The allowed values are: `webgl1`, `webgl2` and `webgpu`
- test=**TITLE**: if provided, run only the test named **TITLE**
- fromtest=**TITLE**: if provided, run the test named **TITLE** and all the tests that follow it in the .json file
- useReverseDepthBuffer=**[0|1]**: if provided and set to `1`, all the tests will be run with `engine.useReverseDepthBuffer = true`
- useNonCompatibilityMode=**[0|1]**: if provided and set to `1`, all the tests will be run with `engine.compatibilityMode = false` (no effect in WebGL)
- checkresourcecreation=**[0|1]**: see explanations below

Note that the old syntax **http://localhost:1338/tests/validation/?TITLE** still works if you want to run a single test named **TITLE** from the default `config.json` list.

When running a list of tests, you will see a **Show only failed test** button in the upper right corner of the browser page: use this button to only show tests that failed. Note however that it hides the succeeded tests at the time you hit the button. If new tests succeed, you will see them. Click the button at the end of the run if you want an up to date list (or reclick it several times during the run).

## Check Resource Creation - WebGPU only

When adding `checkresourcecreation=1` to the test url, three specific checks are performed for each validation test (WebGPU only):

1. that the `engine.countersLastFrame.numEnableEffects` counter value is 0 for the last frame displayed
1. that the number of bind groups created during the last frame is 0 (`BABYLON.WebGPUCacheBindGroups.NumBindGroupsCreatedLastFrame`)
1. that there's no bundle created during the last frame (when in **non compatibility mode**) - `engine.countersLastFrame.numBundleCreationNonCompatMode` counter value is 0

When at least one of these checks is false an error is logged in the browser console.

Regarding _1/_ it's a bug to call `engine.enableEffect` with an `Effect` instead of a `DrawWrapper` in WebGPU so you should fix the problem if a test fails because of that.

Regarding _2/_ and _3/_, those are not errors per see, but when a rendering has been stabilized (there's no creation of new objects, effects, etc. each frame) you should not experience creation of new bind groups (they should be retrieved from the cache) and when in **non compatibility mode** (`engine.compatibilityMode = false`) no bundles should be created but reused instead. However, it's still possible to have _2/_ or _3/_ greater than zero for some validation tests. In that case, you should check if it's expected given the code of the PG or if it could be a problem on `Babylon.js` implementation side.

In order to reach a _stabilized state_ for a PG, the `renderCount` value is set to 50 for all PGs before running them (and the check is performed for the very last frame displayed). That means that the picture comparison would fail for a number of tests, so this comparison is disabled when in `checkresourcecreation=1` mode: if a validation test fails (you get a red cross icon for it instead of a green tick) it means at least one of the 3 checks described above failed (look at the console log for details).

As `engine.countersLastFrame.numBundleCreationNonCompatMode` has meaning on the **non compatibility mode** only, you will always want to also add `useNonCompatibilityMode=1` in the url when setting `checkresourcecreation=1` to check the creation of bundles.



## Introduction

Babylon.js is maintained on Github, a web-based hosting service for version control using Git. Familiarity with using Github is necessary for you to contribute.

## Pre-Requisites

- Installation of Node.js, NPM, Git, Typescript, Gulp and have a Github Account;
- A fork and clone of Babylon.js;
- Reading the [contribution guidelines](https://github.com/BabylonJS/Babylon.js/blob/master/contributing.md);
- An IDE such as VSCode;
- An ability to code in Typescript. Babylon.js is written in Typescript then compiled and distributed in JavaScript.

At the time of writing the version of Gulp needed was 4.0.0. The current [What's New](//doc.babylonjs.com/whats-new) should indicate if there have been any changes of version. You can also look in the Babylon.js repository for `package.json` in `Tools/Publisher` which will give the version number for Gulp and Typescript.


## Contributions

You can contribute to either the Babylon.js engine directly or the documentation for it. The documentation is split into two parts, the 'tutorial' section and the API. The documentation for the API is written from comments within the code for Babylon.js so that details of how to contribute to the API fall under this section.

Contributing to Babylon.js

Introduction

Pre-Requisites

Coming next

Pre-Requisites to Contribute to Babylon.js

Pre-requisites for contributing to Babylon.js.

Start Contributing to Babylon.js

Learn how to start contributing to Babylon.js.

Validation tests

Learn about the visual validation tests and how to run/setup them

Contribute To The API

Learn how to contribute to the Babylon.js API.

Approved Naming Conventions

Learn about standard approved naming conventions in Babylon.js.

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.