An open source 3D engine based on webGL and Javascript

Easy To Try and Easy to Setup

For a quickest way to get started read First Steps For your own project nothing needs to be installed on your computer and nothing needs to be installed by a client to run your program. To see just how simple have a look at the Getting Started tutorial just below! For a broad overview check out the Overviews Section and for more details read Babylon 101

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, check if your browser is WebGL compatible (e.g. Internet Explorer 11+/Firefox 4+/Google Chrome 9+/ Opera 15+...). The example project below uses BabylonJS stored on the web. To download this and other versions, including previews of the one currently under development vist BabylonJS CDN. Then you can develop locally.
Now create a project folder with an index.html file, like this:

yourAwesomeProject
    |- index.htmlyourAwesomeProject
    |- index.html
    |- 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="https://cdn.babylonjs.com/babylon.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>

Now some javascript code to run our project. To begin with, insert at the end of your <body>:

<script>
    window.addEventListener('DOMContentLoaded', function() {
        // All the following code is entered 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.

This project implements the very basics of every BabylonJS program, a scene and two 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);

Now our scene, which needs a camera and a light as well as the shapes. To generate the scene you use a createScene() function.

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('camera', 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; 
    var sphere = BABYLON.MeshBuilder.CreateSphere('sphere', {segments:16, diameter:2}, scene);

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

    // create a built-in "ground" shape; 
    var ground = BABYLON.Mesh.CreateGround('ground1', {height:6, width:6, subdivisions: 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 canvas/window resize event handler, like this:

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

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

class Game {
  constructor(canvasElement : string) {
  }

  createScene() : void {
  }

  doRender() : void {
  }
}

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

  // Create the scene
  game.createScene();

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

Next 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('sphere',
                            {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('ground',
                            {width: 6, height: 6, subdivisions: 2}, this._scene);
}

Now implement doRender, which also takes no parameters and returns nothing. This routine starts the rendering loop and adds the resize Event Listener :

doRender() : 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.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.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);
  }

  doRender() : 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.doRender();
});