An open source 3D engine based on webGL and Javascript

Easy Setup

Nothing needs to be installed on your computer to develop programs with BabylonJS. Nothing needs to be installed by the client to run your program. You can see this excess of simplicity in our Getting Started tutorial just below! Then find out more and get an overview of possibilities by checking out the documentation map.

WebGL

Web Graphics Library, or WebGL, is a JavaScript API designed to render interactive 3D computer graphics and 2D graphics within any compatible web browser, without the use of any plug-ins.

Javascript

Also know as ECMAScript, JavaScript is a dynamic, prototype-based scripting language, with first-class functions. Widely used on client-side (and sometimes even server-side, like on this website!), Javascript is the language that BabylonJS is based on.

Getting Started

First, download the last version of BabylonJS. Also, check if your browser is WebGL compatible (e.g. Internet Explorer 11+/Firefox 4+/Google Chrome 9+/ Opera 15+...). Then create a project folder in which you'll place the last version of BabylonJS and an index.html file, like this:

yourAwesomeProject
    |- index.html
    |- babylon.jsyourAwesomeProject
    |- index.html
    |- babylon.js
    |- babylon.d.ts

We will only code in the index.html file to keep it as simple and concise as possible. The HTML document begins as follow:

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html" charset="utf-8"/>
    <title>Babylon - Getting Started</title>
    <!-- link to the last version of babylon -->
    <script src="babylon.2.5.js"></script>
</head>
<body>
    <canvas id="renderCanvas"></canvas>
</body>
</html>

As you can see, we inserted in the <body> a <canvas> element. This <canvas> element will be the place where we'll display the result of our 3D rendering. Insert some style in the <head>:

<style>
    html, body {
        overflow: hidden;
        width   : 100%;
        height  : 100%;
        margin  : 0;
        padding : 0;
    }

    #renderCanvas {
        width   : 100%;
        height  : 100%;
        touch-action: none;
    }
</style>

We will now write the necessary javascript code to run our demonstration. To begin with, insert at the end of your <body>:

<script>
    window.addEventListener('DOMContentLoaded', function() {
        // your code here
    });
</script>

As you can see, we wrap the javascript code inside of a DOMContentLoaded event handler, to be sure that the whole DOM is loaded before doing anything else. The code we'll write after this point is to be placed inside of this wrapper.

The code we'll show you implements the very basics of every BabylonJS program, meaning the creation of a scene, and the insertion and display of meshes (here, two basic shapes: a sphere and a ground plane). We'll go through it step by step.

The first step is to get the reference of the canvas element from our HTML document:

var canvas = document.getElementById('renderCanvas');

Then, load the Babylon 3D engine:

var engine = new BABYLON.Engine(canvas, true);

After that, we create our scene. In order to keep your program compatible with the Babylon.js Playground, we recommend that you insert a "createScene" function at this point. Beside generating a Babylon Scene Object, createScene() is where you will add your basic scene requirements: a camera, a light, and two basic meshes (a sphere and a ground plane).

var createScene = function() {
    // create a basic BJS Scene object
    var scene = new BABYLON.Scene(engine);

    // create a FreeCamera, and set its position to (x:0, y:5, z:-10)
    var camera = new BABYLON.FreeCamera('camera1', new BABYLON.Vector3(0, 5,-10), scene);

    // target the camera to scene origin
    camera.setTarget(BABYLON.Vector3.Zero());

    // attach the camera to the canvas
    camera.attachControl(canvas, false);

    // create a basic light, aiming 0,1,0 - meaning, to the sky
    var light = new BABYLON.HemisphericLight('light1', new BABYLON.Vector3(0,1,0), scene);

    // create a built-in "sphere" shape; its constructor takes 4 params: name, subdivisions, radius, scene
    var sphere = BABYLON.Mesh.CreateSphere('sphere1', 16, 2, scene);

    // move the sphere upward 1/2 of its height
    sphere.position.y = 1;

    // create a built-in "ground" shape; its constructor takes 5 params: name, width, height, subdivisions and scene
    var ground = BABYLON.Mesh.CreateGround('ground1', 6, 6, 2, scene);

    // return the created scene
    return scene;
}

Now that our createScene() function is ready, we need to call it:

var scene = createScene();

The next three javascript lines are very important, as they register a render loop to repeatedly render the scene on the canvas:

engine.runRenderLoop(function() {
    scene.render();
});

Lastly, you should implement a little canvas/window resize event handler, like this:

window.addEventListener('resize', function() {
    engine.resize();
});

We will now write the necessary Typescript code to run our demonstration. To begin with, create a new file game.ts with Game class with a constructor and two methods, createScene and animate. And add a Event Listener for DOMContentLoaded which will instantiate the Game, create the scene and start the animation :

class Game {
  constructor(canvasElement : string) {
  }

  createScene() : void {
  }

  animate() : void {
  }
}

window.addEventListener('DOMContentLoaded', () => {
  // Create the game using the 'renderCanvas'
  let game = new Game('renderCanvas');

  // Create the scene
  game.createScene();

  // start animation
  game.animate();
});

Next we'll add the instance variables needed for our game. These will all be private so, following the Babylon js coding guidelines, they'll all begin an underscore :

code.javascript.ts.
    class Game {
        private _canvas: HTMLCanvasElement;
        private _engine: BABYLON.Engine;
        private _scene: BABYLON.Scene;
        private _camera: BABYLON.FreeCamera;
        private _light: BABYLON.Light;

        ...
    }

Now implement the constructor, its passed the name of the canvas element and constructors have no return value. The code uses the canvasElement parameter to create the canvas and then creates the engine :

constructor(canvasElement : string) {
  // Create canvas and engine
  this._canvas = document.getElementById(canvasElement);
  this._engine = new BABYLON.Engine(this._canvas, true);
}

Then implement createScene, which takes no parameters and returns nothing hence its type is void. The code comments detail its actions.

createScene() : void {
   // create a basic BJS Scene object
   this._scene = new BABYLON.Scene(this._engine);

   // create a FreeCamera, and set its position to (x:0, y:5, z:-10)
   this._camera = new BABYLON.FreeCamera('camera1', new BABYLON.Vector3(0, 5,-10), this._scene);

   // target the camera to scene origin
   this._camera.setTarget(BABYLON.Vector3.Zero());

   // attach the camera to the canvas
   this._camera.attachControl(this._canvas, false);

   // create a basic light, aiming 0,1,0 - meaning, to the sky
   this._light = new BABYLON.HemisphericLight('light1', new BABYLON.Vector3(0,1,0), this._scene);

   // create a built-in "sphere" shape; with 16 segments and diameter of 2
   let sphere = BABYLON.MeshBuilder.CreateSphere('sphere1',
                            {segments: 16, diameter: 2}, this._scene);

   // move the sphere upward 1/2 of its height
   sphere.position.y = 1;

   // create a built-in "ground" shape
   let ground = BABYLON.MeshBuilder.CreateGround('ground1',
                            {width: 6, height: 6, subdivisions: 2}, this._scene);
}

Next we'll implement animate, which also takes no parameters and returns nothing. This routine starts the rendering loop and adds the resize Event Listener :

animate() : void {
  // run the render loop
  this._engine.runRenderLoop(() => {
      this._scene.render();
  });

  // the canvas/window resize event handler
  window.addEventListener('resize', () => {
      this._engine.resize();
  });
}

Finally, save the game.ts file and add the reference to game.js, which will be generated from game.ts, to your index.html :

code.html.
    <!DOCTYPE html>
    <html>
    <head>
        <script src="game.js"></script>
    </head>
    </html>

Your Awesome Project directory should now contain:

yourAwesomeProject
    |- index.html
    |- game.ts
    |- babylon.2.3.js
    |- babylon.2.3.d.ts

Now compile game.ts which will output game.js:

tsc game.ts babylon.2.3.d.ts

You should now see game.js in Your Awesome Project directory:

yourAwesomeProject
    |- index.html
    |- game.js
    |- game.ts
    |- babylon.2.3.js
    |- babylon.2.3.d.ts

And that's it! Save your files and open index.html with your favorite web browser. You should see the following:

You can click on the image above to see a live demo on the BabylonJS playground.

If you have any trouble with this demonstration, feel free to copy-paste the following code in your index.html file:

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html" charset="utf-8"/>
    <title>Babylon - Getting Started</title>
    <!--- link to the last version of babylon --->
    <script src="babylon.2.3.debug.js"></script>
    <style>
        html, body {
            overflow: hidden;
            width   : 100%;
            height  : 100%;
            margin  : 0;
            padding : 0;
        }

        #renderCanvas {
            width   : 100%;
            height  : 100%;
            touch-action: none;
        }
    </style>
</head>
<body>
    <canvas id="renderCanvas"></canvas>
    <script>
        window.addEventListener('DOMContentLoaded', function(){
            // get the canvas DOM element
            var canvas = document.getElementById('renderCanvas');

            // load the 3D engine
            var engine = new BABYLON.Engine(canvas, true);

            // createScene function that creates and return the scene
            var createScene = function(){
                // create a basic BJS Scene object
                var scene = new BABYLON.Scene(engine);

                // create a FreeCamera, and set its position to (x:0, y:5, z:-10)
                var camera = new BABYLON.FreeCamera('camera1', new BABYLON.Vector3(0, 5,-10), scene);

                // target the camera to scene origin
                camera.setTarget(BABYLON.Vector3.Zero());

                // attach the camera to the canvas
                camera.attachControl(canvas, false);

                // create a basic light, aiming 0,1,0 - meaning, to the sky
                var light = new BABYLON.HemisphericLight('light1', new BABYLON.Vector3(0,1,0), scene);

                // create a built-in "sphere" shape; its constructor takes 5 params: name, width, depth, subdivisions, scene
                var sphere = BABYLON.Mesh.CreateSphere('sphere1', 16, 2, scene);

                // move the sphere upward 1/2 of its height
                sphere.position.y = 1;

                // create a built-in "ground" shape; its constructor takes the same 5 params as the sphere's one
                var ground = BABYLON.Mesh.CreateGround('ground1', 6, 6, 2, scene);

                // return the created scene
                return scene;
            }

            // call the createScene function
            var scene = createScene();

            // run the render loop
            engine.runRenderLoop(function(){
                scene.render();
            });

            // the canvas/window resize event handler
            window.addEventListener('resize', function(){
                engine.resize();
            });
        });
    </script>
</body>
</html><!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html" charset="utf-8"/>
    <title>Babylon - Getting Started</title>
    <!--- link to the last version of babylon --->
    <script src="babylon.2.3.debug.js"></script>
    <script src="game.js"></script>
    <style>
        html, body {
            overflow: hidden;
            width   : 100%;
            height  : 100%;
            margin  : 0;
            padding : 0;
        }

        #renderCanvas {
            width   : 100%;
            height  : 100%;
            touch-action: none;
        }
    </style>
</head>
<body>
    <canvas id="renderCanvas"></canvas>
</body>
</html>

Then, feel free to copy-paste the following code in your game.ts file:

class Game {
  private _canvas: HTMLCanvasElement;
  private _engine: BABYLON.Engine;
  private _scene: BABYLON.Scene;
  private _camera: BABYLON.FreeCamera;
  private _light: BABYLON.Light;

  constructor(canvasElement : string) {
    // Create canvas and engine
    this._canvas = document.getElementById(canvasElement);
    this._engine = new BABYLON.Engine(this._canvas, true);
  }

  createScene() : void {
      // create a basic BJS Scene object
      this._scene = new BABYLON.Scene(this._engine);

      // create a FreeCamera, and set its position to (x:0, y:5, z:-10)
      this._camera = new BABYLON.FreeCamera('camera1', new BABYLON.Vector3(0, 5,-10), this._scene);

      // target the camera to scene origin
      this._camera.setTarget(BABYLON.Vector3.Zero());

      // attach the camera to the canvas
      this._camera.attachControl(this._canvas, false);

      // create a basic light, aiming 0,1,0 - meaning, to the sky
      this._light = new BABYLON.HemisphericLight('light1', new BABYLON.Vector3(0,1,0), this._scene);

      // create a built-in "sphere" shape; with 16 segments and diameter of 2
      let sphere = BABYLON.MeshBuilder.CreateSphere('sphere1',
                            {segments: 16, diameter: 2}, this._scene);

      // move the sphere upward 1/2 of its height
      sphere.position.y = 1;

      // create a built-in "ground" shape
      let ground = BABYLON.MeshBuilder.CreateGround('ground1',
                            {width: 6, height: 6, subdivisions: 2}, this._scene);
  }

  animate() : void {
    // run the render loop
    this._engine.runRenderLoop(() => {
        this._scene.render();
    });

    // the canvas/window resize event handler
    window.addEventListener('resize', () => {
        this._engine.resize();
    });
  }
}

window.addEventListener('DOMContentLoaded', () => {
  // Create the game using the 'renderCanvas'
  let game = new Game('renderCanvas');

  // Create the scene
  game.createScene();

  // start animation
  game.animate();
});