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.
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.
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.
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.html
yourAwesomeProject |- 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.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
with the Game
class with a constructor
and two methods, createScene
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.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 babylon --->
<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:
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();
});