
## The Journey Starts

Welcome to the start of your journey. You will learn a basic workflow for hosting a website built using the features of Babylon.js. This document is designed for absolutely EVERYONE to give an overview experience to set you on your way to building greater and better with Babylon.js. Whether you're an expert web developer diving into 3D, an amazing artist wanting to create 3D experiences on the web, a student/tinkerer curious about programming, or an absolute beginner, this is your very first step to learning Babylon. We strongly encourage everyone new to Babylon to go through this doc before going any futher through the docs.

This doc will take you on a VERY brief journey of creating and hosting your very first Babylon.js Web Experience. You'll learn about the Babylon.js playground, scratch the surface of learning the core engine, and save your work as a ready-to-host .html file. 

### The Babylon.js Playground

The single most important tool available to you as you learn and develop with Babylon, is the Babylon.js Playground.

![playground](/img/home/playground.jpg)

The playground is your toybox, your tinker environment, your laboratory. This simple website allows you to write Babylon code on the left, and see instant updates on the right. It's really that simple. 

The playground is CRITICAL to your learning journey for two reasons:
- 1) An amazing cycle of code --> see updates instantly. Learn by doing!
- 2) It's saveable & shareable!

Why is saveable & shareable important for learning? Through your Babylon journey, you will undoubtedly come across something that you could use some help figuring out. It is important that you have a safe and welcoming space to ask for help! This is why the core dev team staffs the [Babylon.js Forum](https://forum.babylonjs.com/) every weekday, so we can be there alongside you to help you learn.

And when it comes time to help you learn or solve a problem, we need to SEE and UNDERSTAND the context behind the problem. Sharing your saved playgrounds is the PERFECT solution and is mandatory on the forum. When you're stuck, save your playground, head to the forum, reach out for help, and share the playground. We think you'll be pleasantly surprised at how quickly you'll get help by following this process. 

So now that you know the playground is the single most important tool to start learning, let's open it up in a new tab. 

[Babylon.js Playground](https://playground.babylonjs.com/)

### Your First Creation

Welcome to the Playground! Using the playground is as simple as modifying/creating code in the code editor on the left, and seeing updates in the live Babylon scene on the right! You'll also see a default Babylon scene that we've set up for you. Take a quick look at the comments in green font in the code editor. These comments should give you a basic idea of what's happening with each line of code that's written. Pretty simple right? 

There's no better way to start learning than by doing, so let's make our first scene update!

On lines 20-24 you see the following lines of code:

```
// Our built-in 'sphere' shape.
var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, segments: 32}, scene);

// Move the sphere upward 1/2 its height
sphere.position.y = 1;
```

Go ahead and highlight those lines of code and hit DELETE! You've just made your first change! Feel good? But wait, nothing happened in the scene? That's because we have to re-run the scene with our changes. You can do that by either pressing ALT+ENTER on your keyboard or pressing the 'run' button in the UI.

![run](/img/home/run.jpg)

BOOM! The sphere is gone!

<Playground id="#2KRNG9" title="Playground 1" description="Goodbye Sphere!"/>

Quick side note - Throughout this document we'll add links to playgrounds showing you exactly what changes were just made. You can reference these playgrounds with your own progress if you ever get stuck. The little arrow symbol will open these playgrounds in a new tab.

Let's make another change!

Find the line of code that creates the ground plane and add these new lines underneath it:

```
let groundMaterial = new BABYLON.StandardMaterial("Ground Material", scene);
ground.material = groundMaterial;
ground.material.diffuseColor = BABYLON.Color3.Red();
```

Run the scene again (ALT+ENTER, or run button)

<Playground id="#2KRNG9#1" title="Playground 2" description="The ground is red!"/>

Congratulations! You just created a new material, assigned that new material to the ground plane, and assigned it's diffuse channel to be the color red! Pretty cool huh?! Don't worry if some of that is still a bit confusing, the takeaway here is that you're making code changes on the left and seeing updates on the right.

Ok time for another change.

Find this line:
```
ground.material.diffuseColor = BABYLON.Color3.Red();
```

Replace it with these two lines and run the scene again:
```
let groundTexture = new BABYLON.Texture(Assets.textures.checkerboard_basecolor_png.rootUrl, scene);
ground.material.diffuseTexture = groundTexture;
```

<Playground id="#2KRNG9#2" title="Playground 3" description="The ground is checkered!"/>

Pretty cool! You've now created your first Babylon.js texture and assigned it to the texture property of your ground material! 

Ok it's time for another addition to the scene. After all of your ground-related code, give yourself a little space by hitting enter and on a new line press CTRL+SPACE. This will spawn a list of playground templates. These templates are handy pieces of code that you will likely reuse over and over again through your Babylon learning journey. Go ahead and select the template that says "Import a Mesh w/Callback".

![templates](/img/home/playgroundTemplates.jpg)

You should see the following lines of code pop right into the playground:

```
BABYLON.SceneLoader.ImportMesh("meshName", "url to the mesh parent directory", "Mesh filename.fileextension", scene, function(newMeshes){

});
```

let's do a few more things:

- 1) Delete the word 'meshName' but leave the quotes "". 
- 2) Replace "url to the mesh parent directory" (including quotes) with this:
```
Assets.meshes.Yeti.rootUrl
```
- 3) Replace the "Mesh filename.fileextension" (including quotes) with this:
```
Assets.meshes.Yeti.filename
```
- 4) After the BABYLON.SceneLoader.ImportMesh line, but before the "});" add the following line:

```
newMeshes[0].scaling = new BABYLON.Vector3(0.1, 0.1, 0.1);
```
- 5) Run the scene

<Playground id="#2KRNG9#3" title="Playground 4" description="Yeti on the dance floor!"/>

Whoa! Cool! You just added an animated .gltf object into the scene! And you also scaled it down to fit on the groundplane! Well done! 

Let's change one final thing. We want our scene to be interactive, after all isn't that what why you're here - to create interactive web experiences?

Delete lines 5-9.

Press CTRL+SPACE to bring up the playground templates and create an Arc Rotate Camera.

Run the scene and click+drag or touch+drag on the Babylon scene.

<Playground id="#2KRNG9#4" title="Playground 5" description="Move that camera!"/>

WooHoo! You've added interaction to the scene! Great job! Go ahead and save your playground by pressing CTRL+S or hitting the save button.

![save](/img/home/save.jpg)

### The .html File

At this point, let's say we're happy with our creation, and we want to put the Babylon scene (without the code editor and UI) out into the world for everyone to play with.

Getting your Babylon scene ready to host is as simple as pressing a button. Either press SHIFT+CTRL+S or press the Download button to download an .html file of your Babylon scene to your system.

![download](/img/home/download.jpg)

That's it! You've got everything you need for the world to see your first Babylon experience! Now all we need to do is host it somewhere for the world to see it!

### Hosting Your Babylon Project

Ok time to host this experience. If you're not familiar with web hosting, it basically means putting your web experience in a place where the whole world can access/see it. The world of hosting web pages is HUGE and what follows is just ONE example of how to do it. It is by no means the only way to host a page. 

For this first step into Babylon we're going to use something github pages, because it's easy and free.

Let's start by heading over to [GitHub](https://github.com/).

You'll need to log in (or sign up if you're new to github...it's free).

Next, we'll create a new repository. 

![newRepo](/img/home/newRepo.jpg)

Give your new repo a cool name and make sure to check the "Add a README file."

![newRepoDetails](/img/home/newRepoDetails.jpg)

Congratulations! You've just set up a new GitHub repository! Yay!

Now let's add the downloaded Babylon Playground files to this repository.

Click on "Add file" and then "Upload files"

![uploadFiles](/img/home/uploadFiles.jpg)

Locate the file that you downloaded from the Babylon.js playground and drag it onto this page. Then press the "Commit changes" button.

![uploadCommit](/img/home/uploadCommit.jpg)

One last step and then your Babylon Experience will be hosted with a live url for anyone to see.

Hit the "Settings" button on the main repo page.

![settings](/img/home/settings.jpg)

Navigate to the "Pages" menu item, set the "Branch" to "main", and hit the save button.

![pages](/img/home/pages.jpg)

After your settings are saved you'll see the url to your new live website! You can share that url with anyone that you'd like!

![url](/img/home/url.jpg)

Congratulations! You just built and hosted your very first Babylon.js web experience! 

### Documentation Overview

Before you take off and explore Babylon further, we humbly ask that you read one additional article. Babylon.js is a rich and powerful engine and we've worked hard to provide a LOT of documentation to help you learn it. The last part of the first step of your Babylon journey is to get an overview of how the Documenation is organized.

[Learning the Babylon.js Documentation](/overview/learningTheDocs)



## How It's Organized

Having [started your journey](/overview/journey) and having an [overview](/overview/overview) of Babylon.js, the documentation is designed to take you step by step further on the journey of mastering all that this platform has to offer. The information is organized into an overview and 6 main sections, which contain chapters, together with a detailed API section, and search facilities.

1. [Workflow](/workflow) - There are a variety of ways to deal with the workflow when developing a Babylon.js project. This section will help you to understand the possibilities and provides you with some templates and support for doing so.
2. [Features](/features) - Babylon.js has a wide range of features. This section takes you through these features and helps you to , code and build with them.
3. [Tools And Resources](/toolsAndResources) - Babylon.js has many incredible tools to make the development process simple and enjoyable. It also has several libraries of content available for you to use completely for free. This section will help you understand and leverage both.
4. [Guided Learning](/guidedLearning) - Sometimes it's best to learn while doing. This section helps you do just that. These step by step articles and tutorials will help you learn from some of the communities best and brightest teachers.
5. [Playground](/about-playground) - A detailed look at the central Babylon.js resource, how to use it and the many facilities it has to offer, including the ability to search all the playgrounds.
6. [Contribute](/contibute) - For those of you who want to expand the boundaries of Babylon.js this section describes what is needed and how to contribute to both the code base of Babylon.js and its documentation.

*. [API](/typedoc) - For the most seasoned Babylon.js developers, those who want to understand every single possible super power available, the API meticulously documents every corner of this fantastic platform.

### Workflow
The chapters in this section are:

1. [Starter HTML Template](/workflow/get-started) - A basic HTML template encompassing Babylon.js necessary scene and engine code and a description of it. How to obtain the scene code from a playground.
2. [Templates](/workflow/templates) - Simple and more complex templates for your projects.
3. [Framework Packages](/workflow/packages) - A description of the CND, NPM and ES6 packages for Babylon.js, their history and help in choosing which to use.
4. [Exporters](/workflow/Exporters) - A range of 3D graphic software that can export files in a form that Babylon.js can import together with hints and tips on getting the best from the export.
5. [Support](/workflow/wfDeeper) - A range of support including for local and other servers, Visual Studio Code and WebGU.
6. [External Libraries](/workflow/Babylon.js+ExternalLibraries) - Descriptions of how to use some third party libraries with Babylon.js

### Features
1. [Starter Scene Code](/features/get_started) - How to construct a scene in Babylon.js. Examples are provided using the playground. 
1. [Introduction](/start) - This section is designed to take you on a step by step journey of scratching the surface of Babylon.js and everything it has to offer.
2. [Diving Deeper](/divingDeeper) - Organized by feature, this section will help you take the next step, expand on your knowledge of the platform, and give you a solid understanding of the depth of possibilties in the engine.

## How To Use The Documentation

Babylon.js is a rich API designed to make it as easy as possible to leverage the power of the GPU for your web experience. You can leverage this powerful API by writing Babylon.js scene code in either javascript or typescript. For the purposes of consistency and maximizing accessibility of the documentation, all example code found in these pages will be provided in javascript.

The documentation page layout has several features that you'll want to know about in order to get the most out of your learning journey.

To start, the left most panel is the navigation pane. This pane is how you navigate to where you'd like to go.

![Navigation Pane](/img/home/home1.jpg)

Next is the content pane. It's in the middle, and you guessed it, it contains the main content and information.

![Content Pane](/img/home/home2.jpg)

Some pages have a lot of information that's organized into sub sections. The table of contents pane makes it easy to navigate lengthier pages.

![Table of Contents](/img/home/home4.jpg)

The panel on the right is the examples pane. It provides quick access to every playground (live examples) on the current page.

![Examples Pane](/img/home/home3.jpg)

Lastly, if you select any one of the examples in the examples pane, it will load that example inside of the playground pane at the top of the page content.

![Examples Pane](/img/home/home5.jpg)


## A Note on Versioning

The Babylon.js Documentation is written with the latest major version of Babylon.js in mind. [The API docs](https://doc.babylonjs.com/typedoc) are generated against the latest nightly build.

If you want to install Babylon.js locally using the latest version, please pick the latest release [from the npm page](https://www.npmjs.com/package/@babylonjs/core), and then run:

```shellscript
 npm i @babylonjs/core@preview
```

Don't be scared about using the latest version. Babylon's npm releases are considered stable and are fully tested by the team.




## Welcome

Hello and welcome to Babylon.js! We know you're eager to start your learning journey, but before you dive any deeper or go clicking around, we'd humbly ask that you take the time to read through the following two very important documents. Reading these documents and seeing how everything fits together will set you up for success as you begin your Babylon.js learning journey.

- [The Journey Starts](/overview/journey)
- [About The Documentation](/overview/learningTheDocs)


<div style={{width: "100%", textAlign: "left", paddingTop: "1%", fontSize: "2em"}}>Welcome To The Babylon.js Documentation</div>
<div style={{width: "100%", textAlign: "left", paddingTop: "2%", fontSize: "1em"}}><p>Hello and welcome to the Babylon.js Documentation. In these pages you will find everything you could ever want to know about this powerful, beautiful, simple, and completely open-source web rendering engine. Whether you are just starting your Babylon.js journey, or you are a seasoned veteran, it is our sincere hope that the information contained here will help you bring your ideas to life.</p> <p>Although both are parts of a whole, we cater, individually, for those whose first interest is learning the features of Babylon.js to create 3D scenes and for those 3D world builders who want to know the workflow in order to develop simple or complex web apps.</p> <p>Whatever your approach our Playground is at the center of your learning and before you go any further, we strongly encourage EVERYONE <a href = "/overview/journey">to start your Babylon.js journey here</a></p></div>

<div style={{width: "100%"}}>
<div style={{width: "100%", textAlign: "center", paddingTop: "1%", fontSize: "2em"}}>Learn Babylon.js</div>
<div style={{width: "50%", textAlign: "center", fontSize: "1.75em", float: "left", backgroundColor: "#DDDDDD"}}>Features</div><div style={{width: "50%", textAlign: "center", fontSize: "1.75em", float: "left", backgroundColor: "#AAAAAA"}}>Workflow</div>
<div style={{width: "50%", textAlign: "center", fontSize: "1.55em", float: "left", backgroundColor: "#DDDDDD"}}>Scene Creation</div><div style={{width: "50%", textAlign: "center", fontSize: "1.55em", float: "left", backgroundColor: "#AAAAAA"}}>Project Development</div>
<div style={{width: "50%", textAlign: "center", fontSize: "1.4em", float: "left", paddingTop: "1%", backgroundColor: "#DDDDDD"}}><a href = "/features/get_started">Starter Scene Code</a></div>
<div style={{width: "50%", textAlign: "center", fontSize: "1.4em", float: "left", paddingTop: "1%", backgroundColor: "#AAAAAA"}}><a href = "/workflow/get_started">Starter HTML Template</a></div>
<div style={{width: "50%", textAlign: "center", fontSize: "1.25em", float: "left", backgroundColor: "#DDDDDD"}}>Draw simple 3D shapes in the Playground.</div>
<div style={{width: "50%", textAlign: "center", fontSize: "1.25em", float: "left", backgroundColor: "#AAAAAA"}}>Download a 3D webpage from the Playground.</div>
<img src = "/img/home/home_jigsaw_leftA.png" width = "50%" /><img src = "/img/home/home_jigsaw_rightA.png" width = "50%" />
<div  style={{width: "50%", textAlign: "center", fontSize: "1.25em", float: "left", backgroundColor: "#DDDDDD"}}>Advance to realistic 3D settings and environments.</div>
<div  style={{width: "50%", textAlign: "center", fontSize: "1.25em", float: "left", backgroundColor: "#AAAAAA"}}>Advance to 3D apps with IDEs and frameworks.</div>
</div>




Overview

Welcome

In This Category

The Journey Starts

Your first Babylon interactive 3D experience

Learning The Docs

A quick overview of how the Babylon.js documentation is layed out.