
## Available Packages

We offer the following packages via CDN, NPM and ES6. It is important that you choose only one of these the delivery methods for you project, mixing any two of them will ensure failure.

The packages available are listed below.

The core **babylonjs** which is necessary for all and sufficient for many projects, plus

* babylonjs-materials - _A collection of Babylon-supported **advanced** materials._
* babylonjs-loaders - _All of Babylon's official loaders (OBJ, STL, glTF)._
* babylonjs-post-process - _Babylon's post processes._
* babylonjs-procedural-textures - _Officially supported procedural textures_.
* babylonjs-serializers - _Scene / mesh serializers._
* babylonjs-gui - _Babylon.js GUI._
* babylonjs-inspector - _Babylon.js inspector._
* babylonjs-viewer - _The stand-alone Babylon.js Viewer._

## History of Package Delivery

In the early days the framework was written in JavaScript and the common way of consuming a JavaScript framework was to load it in a script tag in your HTML and populate a global namespace. Hence the use of BABYLON as the namespace as, for example, in

```javascript
var scene = new BABYLON.Scene(engine);
var camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10));
var light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0));
```

The framework was originally available as a single JavaScript package to download from Github and away you went. Whilst this approach has a very clear upside, ease of use, it also has many downsides. As the package grew larger and larger over time the framework became harder to maintain and attempts to provide a way to minimize the package size were only partly successful. To overcome these issues a change to developing in Typescript and the use of NPM was introduced to the framework. As backward compatability is an important principal of Babylon.js the current version Javascript packages are still available from the Babylon.js CDN and can be directly accessed or downloaded for local use.

The use of npm meant that developers could include Babylon.js in their build tool. By version 3 module support was added using CommonJS moving to UMD (Universal Module Definition). The good thing about our UMD package is the support of one of Babylon.js’ cornerstones. Backwards compatibility could be maintained. Namespaces worked, packages could still be included in a script tag. For those who want it projects could be written in Typescript ready to compile to Javascript. Everybody’s happy. Then along comes ES6.

ES6 provides better dependency management, better syntax, better code structure. And with it, one of its wonderful side-effects — take only what you need. No need to consume the entire Babylon.js package if you just want to show a sphere in a skybox. Welcome tree shaking! Writing your project in Typescript is of course supported. However ES6 has a few hurdles that need to be jumped over just to get it to work. You will probably need a bundler. You will probably need a (custom) build process. You will probably need to compile it to ES5 for cross-browser support.

Babylon.js’s codebase has gradually moved from an older namespace-based syntax to a modern import-based syntax. A main issue with that was backwards compatibility. A future-safe architecture is always a hard task and apparently the older versions of Babylon.js were not entirely that. In some cases, we had circular dependencies. In some cases, we had side-effect (code running when the script is loaded), which is discouraged when using (pure) es6 modules.


## Choosing
What should you use?

Well, as always, that depends. UMD is still faster for rapid prototyping. The Babylon.js playground, for example, still uses the UMD packages (and the global BABYLON namespace). On the other hand, if you start a new project and want to bring a bit of structure, better architecture and smaller package size, I always recommend ES6.

UMD “just works”, mainly because it is still using the most basic browser functionalities. It also guaranteed to work on any browser with WebGL support (yes IE11, I am looking at Safari). Don’t want to use npm? You don’t have to.

ES6 does not populate the global namespace, so no more BABYLON.* support. This might cause (your) legacy work to stop working, or might present some compatibility issues with our documentation website, which, for the sake of consistency, mostly use the BABYLON namespace in code examples. So if you want to just copy examples from the doc page without the need to (sometimes) change them, use UMD.

But whatever you do, choose one of them. Most of the time, when we have a forum question about build issues, it is because of mixing the two module flavors.




## Minimal HTML Template

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

```html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
        <title>Babylon Template</title>

        <style>
            html, body {
                overflow: hidden;
                width: 100%;
                height: 100%;
                margin: 0;
                padding: 0;
            }
            #renderCanvas {
                width: 100%;
                height: 100%;
                touch-action: none;
            }
        </style>

        <script src="https://cdn.babylonjs.com/babylon.js"></script>

    </head>

   <body>

	<canvas id="renderCanvas"></canvas>

	<script>
        const canvas = document.getElementById("renderCanvas"); // Get the canvas element
        const engine = new BABYLON.Engine(canvas, true); // Generate the BABYLON 3D engine
        const createScene = function () {
            // Creates a basic Babylon Scene object
            const scene = new BABYLON.Scene(engine);
            // Creates and positions a free camera
            const camera = new BABYLON.FreeCamera("camera1", 
                new BABYLON.Vector3(0, 5, -10), scene);
            // Targets the camera to scene origin
            camera.setTarget(BABYLON.Vector3.Zero());
            // This attaches the camera to the canvas
            camera.attachControl(canvas, true);
            // Creates a light, aiming 0,1,0 - to the sky
            const light = new BABYLON.HemisphericLight("light", 
                new BABYLON.Vector3(0, 1, 0), scene);
            // Dim the light a small amount - 0 to 1
            light.intensity = 0.7;
            // Built-in 'sphere' shape.
            const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", 
                {diameter: 2, segments: 32}, scene);
            // Move the sphere upward 1/2 its height
            sphere.position.y = 1;
            // Built-in 'ground' shape.
            const ground = BABYLON.MeshBuilder.CreateGround("ground", 
                {width: 6, height: 6}, scene);
            return scene;
        };
        const scene = createScene(); //Call the createScene function
        // Register a render loop to repeatedly render the scene
        engine.runRenderLoop(function () {
                scene.render();
        });
        // Watch for browser/canvas resize events
        window.addEventListener("resize", function () {
                engine.resize();
        });
	</script>

   </body>

</html>
```

<a href="https://raw.githubusercontent.com/BabylonJSGuide/Tiled/master/basic1/index.zip" download="index.zip">Download</a> the template file where Babylon.js is in the cloud.   
<br />
<a href="https://raw.githubusercontent.com/BabylonJSGuide/Tiled/master/basic2.zip" download="basic template">Download</a> the template file containing a local version of Babylon.max.js

## Description

**Color Key to Babylon.js Sections**

![Webpage Key](/img/quickstart/htmlkey.png)

**HTML with Babylon.js Sections in Color**

![Basic Webpage](/img/quickstart/htmlbjs.png)

## Playground to Download From
Use the &#x2913; button to download the template from the playground

<Playground id="#WJXQP0" title="Basic Playground" description="CreateScene Playground Template." />  


# Developing With and For Babylon.js

For those of you who want to know more about the organization and structure of Babylon.js, in order to either use it to develop well structured projects of your own or to make contributions to it, you have come to the right place.  Here you will find where you can obtain Babylon.js in full or just the modules you need to import into you JavaScript or Typescript application.

Even the best developers need help from time to time and the Babylon.js forum is there to help. To make the best use of the forum check out the first page of this section.

Contributions can come in many forms. Answering question on the forum is a useful contribution. Others may spot spelling errors in the documentation or perhaps ways to improve it. Potential contributors to Babylon.js can come from many different backgrounds. For some of you version controllers, repositories, package managers and task runners are second nature and all you need to know are the requirements set by the Babylon.js core team for a pull-request to be accepted. For other of us, perhaps just wanting to explore the world of 3D, they can start out as a series of confusing hurdles. So this section will contain details that many of you can ignore as obvious. For others those details may be the difference between making a contribution or not.



Useful templates to aid in development.


## Getting Your Babylon.js Web Project Set Up
This section provides support about the workflow required to create a 3D web app from getting started, by downloading a complete webpage from a simple playground, to building a large application, using an IDE and other developmental frameworks and packages.