An open source 3D engine based on webGL and Javascript

Easy to Try and Setup

The quickest way to see how to use the engine is to head to the First Steps. For your own HTML project nothing needs to be installed on your computer and nothing needs to be installed by a client to run your program. See how simple it is with the getting started tutorial below. Check out the Index or the Features Section to see what is available. Build your first scene and develop it by following the Babylon 101 Course Then move on the find out how to do more. An overview of the documentation is at the bottom of the page.

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.

Documentation Overview

Getting Started

First, check to ensure your browser is WebGL compatible by visiting WebGL.org or Can I use ... WebGL. Browsers such as Internet Explorer 11+, Firefox 4+, Google Chrome 9+ and Opera 15+ support WebGL.

The example project below uses the most recent release of BabylonJS via the BabylonJS CDN, so you don't need to download BabylonJS locally in order to use it.

However, you will need to download the BabylonJS TypeScript definition file from https://cdn.babylonjs.com/babylon.d.ts in order to compile your project. Save this babylon.d.ts file into your project folder and create an empty index.html like so:

Now create a project folder containing an empty index.html file like so:

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:

The HTML document begins as follows (If you prefer using npm/webpack see https://doc.babylonjs.com/features/npm_support):

<!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 BabylonJS -->
    <script src="https://preview.babylonjs.com/babylon.js"></script>
    <!-- Link to the last version of BabylonJS loaders to enable loading filetypes such as .gltf -->
    <script src="https://preview.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
    <!-- Link to pep.js to ensure pointer events work consistently in all browsers -->
    <script src="https://code.jquery.com/pep/0.4.1/pep.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.MeshBuilder.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 that references the BabylonJS TypeScript definition file in your project folder, then create a new 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 render loop :

///<reference path="babylon.d.ts" />

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 render loop.
  game.doRender();
});

Next, add the instance variables needed for our game. These will all be private so, following the BabylonJS coding guidelines, they'll each be prefixed with an underscore :

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. It's 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) as HTMLCanvasElement;
    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 :

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

Your Awesome Project directory should now contain:

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

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

tsc game.ts babylon.d.ts

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

yourAwesomeProject
    |- index.html
    |- game.js
    |- game.ts
    |- babylon.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 BabylonJS --->
    <script src="https://cdn.babylonjs.com/babylon.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 6 params: name, segment, diameter, scene, updatable, sideOrientation 
                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;
                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="https://cdn.babylonjs.com/babylon.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:

///<reference path="babylon.d.ts" />

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) as HTMLCanvasElement;
        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 render loop.
    game.doRender();
});